What Is the TiledScanDetector Threshold for Aggregate Pixel Detection in pdf‑inspector?

The aggregate‑pixel threshold for pdf‑inspector's TiledScanDetector is 2 000 000 pixels (2 M pixels). When the combined area of all detected image tiles on a PDF page meets or exceeds this value, the detector flags the document as a tiled scan—even if no individual tile surpasses the per‑tile size limit.

The pdf‑inspector repository implements a Rust‑based PDF classification system that distinguishes between text‑based, scanned, tiled‑scan, and mixed PDFs. The tiled‑scan detection heuristic relies on this aggregate area calculation to catch documents where many small tiles collectively represent a scanned page image.

Where the 2 M‑Pixel Threshold Is Defined

The threshold originates from explicit design decisions documented in AGENTS.md【source: AGENTS.md】. The design notes state that tiled‑scan detection "catches scanned PDFs … where … aggregate area does ≥ 2 M pixels".

This value represents a practical compromise: large enough to avoid false positives on documents with decorative header images, yet sensitive enough to flag true tiled scans that split a single page image into hundreds of small tiles.

Implementation in the Source Code

Two files collaborate to enforce this threshold:

• src/detector.rs – Orchestrates the high‑level PDF type classification pipeline. It calls the tiled‑scan heuristic and finalizes the PdfType classification based on detector results.

• src/vision/oar.rs – Contains the low‑level logic that sums tile pixel areas and applies the 2 M‑pixel cutoff. This helper evaluates whether the aggregate image area triggers the tiled‑scan flag.

The detection flow works as follows: the pipeline extracts image tiles from each page, computes their individual dimensions, aggregates the total pixel count, and compares this sum against the 2 000 000‑pixel threshold defined in the design specification.

Practical Usage Example

Below is a complete Rust example demonstrating how to invoke the detector and inspect the aggregate pixel count that drives the tiled‑scan decision:

use pdf_inspector::detector::{detect_pdf_type, PdfType};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Path to the PDF you want to analyse
    let pdf_path = "example.pdf";

    // Run the detector
    let pdf_info = detect_pdf_type(pdf_path)?;

    // Print the classification result
    match pdf_info.pdf_type {
        PdfType::TiledScan => {
            println!("📄 This PDF is identified as a tiled scan (≥ 2 M px).");
        }
        PdfType::TextBased => {
            println!("📄 Text‑based PDF (no large aggregate image area).");
        }
        PdfType::Scanned => {
            println!("📄 Scanned PDF (large single image tiles).");
        }
        PdfType::Mixed => {
            println!("📄 Mixed PDF (both text and scanned content).");
        }
    }

    // If you need the exact pixel count for debugging:
    println!("Total image‑tile pixel area: {}", pdf_info.total_tile_pixels);
    Ok(())
}

The detect_pdf_type function returns a PdfInfo struct containing total_tile_pixels, which exposes the raw aggregate value before threshold comparison. This field enables manual verification of the 2 M‑pixel rule for debugging or logging purposes.

When the Threshold Triggers Classification

Understanding the threshold behavior helps interpret detector output:

• Below 2 M pixels – Document likely classified as TextBased or Mixed, depending on other heuristics.

• At or above 2 M pixels – Document flagged as TiledScan, indicating the page content probably originates from a scanned source that was sliced into multiple tiles during PDF generation.

This aggregate approach complements per‑tile size limits, ensuring detection succeeds even when aggressive tiling splits a scanned page into pieces too small to trigger individual tile thresholds.

Summary

• The TiledScanDetector aggregate‑pixel threshold is 2 000 000 pixels.

• Implemented in src/vision/oar.rs with orchestration from src/detector.rs.

• Documented explicitly in AGENTS.md as a key design decision.

• Accessible at runtime through pdf_info.total_tile_pixels for verification and debugging.

• Triggers PdfType::TiledScan classification when met or exceeded.

Frequently Asked Questions

What happens if a single tile exceeds 2 000 000 pixels?

A single tile exceeding this size would likely trigger the scanned PDF heuristic instead, which applies separate per‑tile thresholds. The tiled‑scan detector specifically addresses cases where no single tile is large enough, but their combined area reaches the aggregate limit.

Can the 2 M‑pixel threshold be configured at runtime?

According to the current implementation in src/vision/oar.rs, the threshold appears as a compile‑time constant derived from the design specification in AGENTS.md. No public API exposes runtime configuration of this value in the provided source analysis.

Why use an aggregate threshold instead of just per‑tile limits?

Per‑tile limits miss tiled scans—documents that split a single scanned page into hundreds of small tiles to optimize rendering or compression. The aggregate threshold catches these cases by measuring total image coverage, regardless of how the scan was partitioned.

How does pdf‑inspector calculate tile pixel area?

The detector examines each image tile's width and height metadata, multiplies these dimensions for individual tile areas, and sums these products across all tiles on the page. This arithmetic feeds directly into the 2 000 000‑pixel comparison in src/vision/oar.rs.

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