Specifying image size during conversion to markdown

[DylanDsouza00]

Question

...I have a PDF file containing numerous images, and I am trying to convert it into a PDF document. I do not want an tag to be generated for every image in the PDF. Is it possible to set restrictions on the image size, including length and width?

Below code is used to convert to a normal markdown file

source = "input/A_"  # Local Path
converter = DocumentConverter()
result = converter.convert(source)

# Create output folder if it doesn't exist
output_folder = "output"
os.makedirs(output_folder, exist_ok=True)

source_filename = os.path.basename(source)
output_filename = os.path.splitext(source_filename)[0] + ".md"  # Change extension to .md
output_path = os.path.join(output_folder, output_filename)

# Write markdown to file
with open(output_path, "w", encoding="utf-8") as file:
    file.write(result.document.export_to_markdown())

print(f"Markdown written to {output_path}")

[dosubot]

Docling lets you filter which images are included in Markdown output by setting the min_picture_page_surface_ratio parameter in PdfPipelineOptions. This value (default 0.05, or 5%) means only images covering more than that fraction of the page area are processed—so increasing it excludes smaller images from the output. There’s no built-in way to filter by explicit pixel width or height, only by area ratio relative to the page size example.

To control whether images are embedded, use the image_mode parameter in export_to_markdown. By default, image_mode="placeholder" inserts comments instead of actual images. To embed images, use image_mode="inline" or "referenced" and set generate_picture_images=True in your pipeline options details.

Example:

from docling.datamodel.pipeline_options import PdfPipelineOptions
from docling.datamodel.format_options import PdfFormatOption, InputFormat
from docling.converter import DocumentConverter

converter = DocumentConverter(
    format_options={
        InputFormat.PDF: PdfFormatOption(
            pipeline_options=PdfPipelineOptions(
                generate_picture_images=True,
                min_picture_page_surface_ratio=0.10  # Only include images >10% of page area
            )
        )
    }
)
result = converter.convert("input/A_")
md = result.document.export_to_markdown(image_mode="placeholder")

If you want to completely remove all image tags or placeholders, you’ll need to post-process the Markdown output (for example, with a regex or script) reference.

Let me know if you want a sample post-processing script!

To reply, just mention @dosu.

---

^{How did I do? Good | Irrelevant | Incorrect | Verbose | Hallucination | Report 🐛 | Other}    

[DylanDsouza00]

source = "input/A_DO"  # Local Path
converter = DocumentConverter(
    format_options={
        InputFormat.PDF: PdfFormatOption(
            pipeline_options=PdfPipelineOptions(
                generate_picture_images=True,
                picture_area_threshold=0.40  # Only include images >40% of page area
            )
        )
    }
)
result = converter.convert(source)

# Create output folder if it doesn't exist
output_folder = "output"
os.makedirs(output_folder, exist_ok=True)

source_filename = os.path.basename(source)
output_filename = os.path.splitext(source_filename)[0] + "v2.md"  # Change extension to .md
output_path = os.path.join(output_folder, output_filename)


# Write markdown to file
with open(output_path, "w", encoding="utf-8") as file:
    file.write(result.document.export_to_markdown())

print(f"Markdown written to {output_path}")

I have been using this script but it still gives an tag to almost every image/icon in the pdf

[dosubot]

The reason you're still seeing tags for almost every image is that picture_area_threshold is not the parameter Docling uses to filter images by size in the PDF-to-Markdown pipeline. The correct parameter is min_picture_page_surface_ratio in PdfPipelineOptions. Setting picture_area_threshold only affects picture description models, not which images are included in the Markdown output.

To filter out small images/icons, use min_picture_page_surface_ratio (e.g., 0.40 for 40% of the page area):

from docling.datamodel.pipeline_options import PdfPipelineOptions
from docling.datamodel.format_options import PdfFormatOption, InputFormat
from docling.converter import DocumentConverter

source = "input/A_DOC128437-EN-O Operator manual Crossorter.pdf"
converter = DocumentConverter(
    format_options={
        InputFormat.PDF: PdfFormatOption(
            pipeline_options=PdfPipelineOptions(
                generate_picture_images=True,
                min_picture_page_surface_ratio=0.40  # Only include images >40% of page area
            )
        )
    }
)
result = converter.convert(source)
# ... (rest of your code unchanged)

Docling only filters by area ratio, not by explicit pixel width/height, so images with large bounding boxes may still appear. If you want to remove all tags or filter them further, you can post-process the Markdown file with a script like this:

import re

with open("output/yourfile.md", "r", encoding="utf-8") as f:
    md = f.read()

# Remove all Markdown image tags: ![alt](url)
md = re.sub(r'!\[.*?\]\(.*?\)', '', md)

with open("output/yourfile_noimg.md", "w", encoding="utf-8") as f:
    f.write(md)

This will strip all image tags from your Markdown output. If you need more granular filtering (e.g., by alt text or URL), you can adjust the regex accordingly.

References:
min_picture_page_surface_ratio is the correct parameter
Filtering is only by area ratio, not pixel size

To reply, just mention @dosu.

---

^{How did I do? Good | Irrelevant | Incorrect | Verbose | Hallucination | Report 🐛 | Other}    

[DylanDsouza00]

source = "input/A_DOC128437-EN-O Operator manual Crossorter.pdf"  # Local Path
converter = DocumentConverter(
    format_options={
        InputFormat.PDF: PdfFormatOption(
            pipeline_options=PdfPipelineOptions(
                generate_picture_images=True,
                min_picture_page_surface_ratio=0.40  # Only include images >30% of page area
            )
        )
    }
)
result = converter.convert(source)

# Create output folder if it doesn't exist
output_folder = "output"
os.makedirs(output_folder, exist_ok=True)

source_filename = os.path.basename(source)
output_filename = os.path.splitext(source_filename)[0] + "v2.md"  # Change extension to .md
output_path = os.path.join(output_folder, output_filename)


# Write markdown to file
with open(output_path, "w", encoding="utf-8") as file:
    file.write(result.document.export_to_markdown())

print(f"Markdown written to {output_path}")

Even this code gives all images/icons as output even though threshold is 40%. Can you verify this?

[dosubot]

I’ve verified that setting min_picture_page_surface_ratio (or picture_area_threshold) in PdfPipelineOptions does not actually filter images by size in the PDF-to-Markdown pipeline. All images detected in the PDF are included in the Markdown output, regardless of these settings. The parameters are either ignored or only affect image description tasks, not which images are included in Markdown export. This behavior is expected given the current codebase, even though documentation and some issues suggest otherwise (source).

If you want to exclude small images/icons, you’ll need to post-process the Markdown output (for example, with a script that removes unwanted image tags). Let me know if you want a sample script for that!

To reply, just mention @dosu.

---

^{How did I do? Good | Irrelevant | Incorrect | Verbose | Hallucination | Report 🐛 | Other}    

[DylanDsouza00]

@dolfim-ibm can you verify the above response,please?

[dolfim-ibm]

I don't think such a parameter min_picture_page_surface_ratio exists at all.

It is correct that we have a parameter to filter which pictures are processed with the OCR step and with the picture description step (if activated).

For customizing the export to markdown, I would suggest looking at a custom serializer. You can provide your own picture_serializer which can apply the logic you suggest above. The example at could be a good starting point: https://docling-project.github.io/docling/examples/serialization/#creating-a-custom-serializer.

If you are willing to give it try, feel free to post your serializer as an example. We always welcome such contributions.