Datagrunt 4.1.0: Tunable Embedded-Image Size Filtering for PDF Extraction

Embedded images in PDFs are noisy. Alongside the figures and logos you actually want, real-world documents are full of 1×1 spacer pixels, hairline rules, and icon slivers that are technically images but carry no content. Since its first PDF release, Datagrunt has filtered these out with a fixed rule: drop any embedded image smaller than 40 px on either side.

That default is right for most documents — but not all. A pipeline extracting scanned signatures, small product thumbnails, or favicon-sized brand marks needs to keep images below 40 px. A pipeline that only cares about full-page figures wants to filter more aggressively. Until now, that threshold was hardcoded and unreachable from the public API.

Datagrunt 4.1.0 makes it a knob.

A single keyword argument

PDFReader and PDFWriter now accept a keyword-only min_image_dimension argument:

from datagrunt import PDFReader

# Keep smaller images — capture logos, signatures, or small icons.
reader = PDFReader("report.pdf", min_image_dimension=15)

# Filter more aggressively — keep only large figures.
reader = PDFReader("report.pdf", min_image_dimension=200)

# Keep every image, including 1x1 px artifacts (disable the filter).
reader = PDFReader("report.pdf", min_image_dimension=0)

The same argument works on PDFWriter, so image extraction to disk honors the same threshold:

from datagrunt import PDFWriter

PDFWriter("report.pdf", min_image_dimension=15).extract_images(output_dir="images")

Consistent, safe, and unchanged by default

• Both engines, every output path. The threshold is honored identically on the default PDFium engine and on PyMuPDF, across to_dicts, to_dataframe, to_arrow_table, and the writer’s JSON / Markdown / image outputs — including parallel (workers > 1) parsing.
• Defaults are unchanged. Omit the argument and you get the long-standing 40 px behavior, byte-for-byte. This is a purely additive, backward-compatible change.
• Fails fast. min_image_dimension must be a non-negative integer; an invalid value raises the moment you construct the reader or writer, not deep inside a parse.

Upgrade today

Datagrunt 4.1.0 is available on PyPI:

uv pip install --upgrade datagrunt