From bd4a74de0e5b7ff8117371b4d064e718d3a471bc Mon Sep 17 00:00:00 2001
From: "James R. Barlow" <james@purplerock.ca>
Date: Wed, 18 Feb 2026 18:00:34 -0800
Subject: [PATCH] Restore image rendering for hocrtransform

Fixes [Question] How to reproduce hocr renderer image overlay ?
Fixes #1634
---
 src/ocrmypdf/fpdf_renderer/renderer.py | 14 ++++++++++++++
 src/ocrmypdf/hocrtransform/__main__.py | 12 ++++--------
 2 files changed, 18 insertions(+), 8 deletions(-)

diff --git a/src/ocrmypdf/fpdf_renderer/renderer.py b/src/ocrmypdf/fpdf_renderer/renderer.py
index a8b8a9a9..dca1dae6 100644
--- a/src/ocrmypdf/fpdf_renderer/renderer.py
+++ b/src/ocrmypdf/fpdf_renderer/renderer.py
@@ -128,6 +128,7 @@ class Fpdf2PdfRenderer:
         dpi: float,
         multi_font_manager: MultiFontManager,
         invisible_text: bool = True,
+        image: Path | None = None,
         debug_render_options: DebugRenderOptions | None = None,
     ):
         """Initialize renderer.
@@ -137,6 +138,8 @@ class Fpdf2PdfRenderer:
             dpi: Source image DPI
             multi_font_manager: MultiFontManager instance
             invisible_text: If True, render text as invisible (text mode 3)
+            image: Optional path to image to overlay on top of the text layer,
+                creating a sandwich PDF (text underneath, image on top)
             debug_render_options: Options for debug visualization
 
         Raises:
@@ -151,6 +154,7 @@ class Fpdf2PdfRenderer:
         self.dpi = dpi
         self.multi_font_manager = multi_font_manager
         self.invisible_text = invisible_text
+        self.image = image
         self.debug_options = debug_render_options or DebugRenderOptions()
 
         # Setup coordinate transform
@@ -226,6 +230,16 @@ class Fpdf2PdfRenderer:
             for line in self.page.lines:
                 self._render_line(pdf, line)
 
+        # Place image on top of text layer (sandwich mode)
+        if self.image is not None:
+            pdf.image(
+                str(self.image),
+                x=0,
+                y=0,
+                w=self.coord_transform.page_width_pt,
+                h=self.coord_transform.page_height_pt,
+            )
+
     def _register_font(self, pdf: FPDF, font_manager: FontManager) -> str:
         """Register font with fpdf2 if not already registered.
 
diff --git a/src/ocrmypdf/hocrtransform/__main__.py b/src/ocrmypdf/hocrtransform/__main__.py
index e75b3f70..0a112ee5 100644
--- a/src/ocrmypdf/hocrtransform/__main__.py
+++ b/src/ocrmypdf/hocrtransform/__main__.py
@@ -32,7 +32,7 @@ if __name__ == "__main__":
         '-i',
         '--image',
         default=None,
-        help='Path to the image to be placed above the text (not yet supported)',
+        help='Path to the image to overlay on top of the text layer',
     )
     parser.add_argument('hocrfile', help='Path to the hocr file to be parsed')
     parser.add_argument('outputfile', help='Path to the PDF file to be generated')
@@ -59,17 +59,13 @@ if __name__ == "__main__":
     multi_font_manager = MultiFontManager(font_dir)
 
     # Render to PDF using fpdf2
+    image_path = Path(args.image) if args.image else None
     renderer = Fpdf2PdfRenderer(
         page=ocr_page,
         dpi=dpi,
         multi_font_manager=multi_font_manager,
-        invisible_text=False,
+        invisible_text=bool(args.image),
+        image=image_path,
         debug_render_options=debug_options,
     )
     renderer.render(Path(args.outputfile))
-
-    if args.image:
-        print(
-            f"Warning: Image overlay (--image {args.image}) is not yet supported "
-            "with the fpdf2 renderer."
-        )