# Chandra load_file Function: Supported File Formats and Processing Logic

> Explore Chandra's load_file function. Discover supported formats like PDF and Pillow-readable images, and understand how it converts them to RGB Pillow Image objects.

- Repository: [Datalab/chandra](https://github.com/datalab-to/chandra)
- Tags: api-reference
- Published: 2026-03-27

---

**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`](https://github.com/datalab-to/chandra/blob/main/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`](https://github.com/datalab-to/chandra/blob/main/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`](https://github.com/datalab-to/chandra/blob/main/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`](https://github.com/datalab-to/chandra/blob/main/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:

```python
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`](https://github.com/datalab-to/chandra/blob/main/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`](https://github.com/datalab-to/chandra/blob/main/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`](https://github.com/datalab-to/chandra/blob/main/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`](https://github.com/datalab-to/chandra/blob/main/chandra/input.py) converts this notation to zero-based page indices, and only those specific pages are rendered and returned in the resulting list.