Chandra load_file Function: Supported File Formats and Processing Logic

Chandra's load_file function supports PDF documents and any raster image format readable by Pillow, converting both into standardized lists of RGB Pillow Image objects.

The load_file function serves as the central document ingestion entry point in the datalab-to/chandra repository. Located in chandra/input.py, this utility standardizes how Chandra processes external files, ensuring that both multi-page PDFs and single images emerge as uniform lists of Pillow Image objects ready for downstream inference.

Supported File Formats for load_file

According to the implementation in chandra/input.py (lines 66-76), the load_file function explicitly handles two primary categories of files through distinct processing branches determined by filetype.guess(filepath).

PDF Documents

When filetype.guess returns an extension of "pdf", the function routes the file to the PDF processing pipeline. This format receives specialized handling to extract individual pages as separate images, with support for selective page ranges via configuration options.

Raster Image Files (PNG, JPEG, BMP, GIF, WebP, etc.)

If filetype.guess returns None or any extension other than "pdf", the code defaults to the image processing branch. This branch accepts any format supported by Pillow, including PNG, JPEG, BMP, GIF, and WebP files, treating all non-PDF inputs as generic images.

How load_file Processes Each Format

The internal logic delegates to specialized loaders based on the detected file type, with each path producing a standardized output format suitable for Chandra's inference pipeline.

PDF Rendering Pipeline

For PDF documents, load_file calls load_pdf_images (lines 27-50), which utilizes pypdfium2 to open the document. The pipeline optionally flattens annotations, renders each page at an appropriate DPI determined by settings in chandra/settings.py, and converts the renderings into Pillow Image objects. The function returns a list of Image objects, one per PDF page, preserving the document's page order.

Image Loading and Resizing Logic

For raster images, the function invokes load_image (lines 16-24), which opens the file using Image.open(filepath).convert("RGB"). If the image dimensions fall below the MIN_IMAGE_DIM threshold defined in chandra/settings.py (lines 1-30), the image is automatically up-scaled to meet the minimum size requirement. This ensures consistent input quality for downstream processing. The result is a single-element list containing the processed RGB Image.

Configuration Options and Page Ranges

The load_file function accepts a config dictionary that supports format-specific options. For PDF files, you can pass a "page_range" string (e.g., "1-3,5") to limit processing to specific pages. The helper function parse_range_str (lines 53-63) converts this notation into zero-based page indices, allowing efficient partial document ingestion without rendering unnecessary pages.

Practical Code Examples

Here are concrete examples demonstrating how to load different file types using Chandra's ingestion API:

from chandra.input import load_file

# Load specific pages from a PDF (returns list of page images)

pdf_images = load_file("report.pdf", {"page_range": "1-3"})
print(f"Loaded {len(pdf_images)} pages from PDF")

# Load a single raster image (PNG, JPEG, etc.)

img_list = load_file("photo.png", {})
print(f"Loaded {len(img_list)} image with dimensions {img_list[0].size}")

Summary

• Chandra's load_file function in chandra/input.py serves as the unified entry point for document ingestion, supporting both PDFs and raster images.
• PDF processing utilizes pypdfium2 to render pages at configurable DPI settings defined in chandra/settings.py, returning a list of Pillow Image objects.
• Image processing leverages Pillow to open any supported raster format, automatically up-scaling images smaller than the MIN_IMAGE_DIM threshold.
• Page range selection allows selective PDF loading via the config dictionary's "page_range" parameter, parsed by parse_range_str to zero-based indices.

Frequently Asked Questions

What file formats does Chandra's load_file function support?

The function supports PDF documents and any raster image format that Pillow can decode, including PNG, JPEG, BMP, GIF, and WebP. Detection relies on filetype.guess(filepath) to distinguish PDFs from other formats, with all non-PDF files falling back to the image processing branch.

How does Chandra handle PDF files differently from images?

PDFs are processed by load_pdf_images which uses pypdfium2 to render each page as a separate image at an appropriate DPI, while raster images are handled by load_image which simply opens them with Pillow and converts to RGB. PDFs return multiple images (one per page), whereas images return a single-element list containing one Image object.

What happens if an image is too small when loading into Chandra?

If an image's dimensions are smaller than the MIN_IMAGE_DIM value defined in chandra/settings.py, the load_image function automatically up-scales the image to meet that minimum threshold. This ensures consistent resolution for downstream processing pipelines.

Can I load specific pages from a PDF instead of the entire document?

Yes. Pass a config dictionary with a "page_range" key (e.g., {"page_range": "1-3,5"}) to load_file. The parse_range_str helper in chandra/input.py converts this notation to zero-based page indices, and only those specific pages are rendered and returned in the resulting list.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}