fix(cli): avoid generating images for non-image exports (#3127)

* fix(cli): avoid generating images for non-image exports

Signed-off-by: Hassan Raza <raihassanraza10@gmail.com>

* test(cli): cover output image export policy

Signed-off-by: Hassan Raza <raihassanraza10@gmail.com>

* fix(cli): use denylist for image export gating

Signed-off-by: Hassan Raza <raihassanraza10@gmail.com>

* fix(cli): clarify image export mode help text

Signed-off-by: Hassan Raza <raihassanraza10@gmail.com>

---------

Signed-off-by: Hassan Raza <raihassanraza10@gmail.com>

Author: M-Hassan-Raza

docling/cli/main.py

@@ -370,6 +370,25 @@ def _split_list(raw: str | None) -> list[str] | None:
     return re.split(r"[;,]", raw)
 
 
+_OUTPUT_FORMATS_NOT_SUPPORTING_IMAGE_EMBEDDING = frozenset(
+    {
+        OutputFormat.TEXT,
+        OutputFormat.DOCTAGS,
+        OutputFormat.VTT,
+    }
+)
+
+
+def _should_generate_export_images(
+    image_export_mode: ImageRefMode,
+    to_formats: list[OutputFormat],
+) -> bool:
+    return image_export_mode != ImageRefMode.PLACEHOLDER and any(
+        to_format not in _OUTPUT_FORMATS_NOT_SUPPORTING_IMAGE_EMBEDDING
+        for to_format in to_formats
+    )
+
+
 @app.command(no_args_is_help=True)
 def convert(  # noqa: C901
     input_sources: Annotated[
@@ -404,7 +423,7 @@ def convert(  # noqa: C901
         ImageRefMode,
         typer.Option(
             ...,
-            help="Image export mode for the document (only in case of JSON, Markdown or HTML). With `placeholder`, only the position of the image is marked in the output. In `embedded` mode, the image is embedded as base64 encoded string. In `referenced` mode, the image is exported in PNG format and referenced from the main exported document.",
+            help="Image export mode for image-capable document outputs (JSON, YAML, HTML, HTML split-page, and Markdown). Text, DocTags, and WebVTT outputs do not export images. With `placeholder`, only the position of the image is marked in the output. In `embedded` mode, the image is embedded as base64 encoded string. In `referenced` mode, the image is exported in PNG format and referenced from the main exported document.",
         ),
     ] = ImageRefMode.EMBEDDED,
     pipeline: Annotated[
@@ -750,7 +769,10 @@ def convert(  # noqa: C901
                 )
                 pipeline_options.table_structure_options.mode = table_mode
 
-            if image_export_mode != ImageRefMode.PLACEHOLDER:
+            if _should_generate_export_images(
+                image_export_mode,
+                to_formats,
+            ):
                 pipeline_options.generate_page_images = True
                 pipeline_options.generate_picture_images = (
                     True  # FIXME: to be deprecated in version 3

tests/test_cli.py

@@ -1,8 +1,11 @@
 from pathlib import Path
 
+import pytest
+from docling_core.types.doc import ImageRefMode
 from typer.testing import CliRunner
 
-from docling.cli.main import app
+from docling.cli.main import _should_generate_export_images, app
+from docling.datamodel.base_models import OutputFormat
 
 runner = CliRunner()
 
@@ -27,6 +30,35 @@ def test_cli_convert(tmp_path):
     assert converted.exists()
 
 
+@pytest.mark.parametrize(
+    ("image_export_mode", "to_formats", "expected"),
+    [
+        (ImageRefMode.PLACEHOLDER, [OutputFormat.JSON], False),
+        (ImageRefMode.EMBEDDED, [OutputFormat.TEXT, OutputFormat.DOCTAGS], False),
+        (ImageRefMode.EMBEDDED, [OutputFormat.MARKDOWN], True),
+        (
+            ImageRefMode.EMBEDDED,
+            [OutputFormat.TEXT, OutputFormat.MARKDOWN],
+            True,
+        ),
+    ],
+)
+def test_should_generate_export_images(image_export_mode, to_formats, expected):
+    assert _should_generate_export_images(image_export_mode, to_formats) is expected
+
+
+def test_image_export_policy_covers_all_output_formats():
+    non_image_export_formats = {
+        OutputFormat.TEXT,
+        OutputFormat.DOCTAGS,
+        OutputFormat.VTT,
+    }
+    image_export_formats = set(OutputFormat) - non_image_export_formats
+
+    assert image_export_formats.isdisjoint(non_image_export_formats)
+    assert image_export_formats | non_image_export_formats == set(OutputFormat)
+
+
 def test_cli_audio_auto_detection(tmp_path):
     """Test that CLI automatically detects audio files and sets ASR pipeline."""
     from docling.datamodel.base_models import FormatToExtensions, InputFormat