docs/ src/ tests/: Page.insert_htmlbox(): also down-scale to fit long words.

We do additional scaling to fit long words that would extend beyond the
horizontal bounds of the rect.

Fixes #4613.

Author: julian-smith-artifex-com

docs/page.rst

@@ -847,14 +847,17 @@ In a nutshell, this is what you can do with PyMuPDF:
 
       :returns: A tuple of floats `(spare_height, scale)`.
 
-         - `spare_height`: -1 if content did not fit, else >= 0. It is the height of the unused (still available) rectangle stripe. Positive only if scale = 1 (no down-scaling happened).
-         - `scale`: down-scaling factor, 0 < scale <= 1.
+          - spare_height: The height of the remaining space in `rect` below the
+            text, or -1 if we failed to fit.
+          - scale: The scaling required; `0 < scale <= 1`.  Will be less than
+            `scale_low` if we failed to fit.
 
-         Please refer to examples in this section of the recipes: :ref:`RecipesText_I_c`.
+      Please refer to examples in this section of the recipes: :ref:`RecipesText_I_c`.
 
       |history_begin|
 
-      * New in v1.23.8; rebased-only.
+      * In v.1.26.5: do additional scaling to fit long words.
+      * New in v1.23.8: rebased-only.
       * New in v1.23.9: `opacity` parameter.
 
       |history_end|

src/__init__.py

@@ -12266,7 +12266,8 @@ def insert_htmlbox(
         oc=0,
         opacity=1,
         overlay=True,
-    ) -> float:
+        _scale_word_width=True,
+    ) -> tuple:
         """Insert text with optional HTML tags and stylings into a rectangle.
 
         Args:
@@ -12282,14 +12283,16 @@ def insert_htmlbox(
             oc: (int) the xref of an OCG / OCMD (Optional Content).
             opacity: (float) set opacity of inserted content.
             overlay: (bool) put text on top of page content.
+            _scale_word_width: internal, for testing only.
         Returns:
             A tuple of floats (spare_height, scale).
-            spare_height: -1 if content did not fit, else >= 0. It is the height of the
-                   unused (still available) rectangle stripe. Positive only if
-                   scale_min = 1 (no down scaling).
-            scale: downscaling factor, 0 < scale <= 1. Set to 0 if spare_height = -1 (no fit).
+            spare_height:
+                The height of the remaining space in <rect> below the
+                text, or -1 if we failed to fit.
+            scale:
+                The scaling required; `0 < scale <= 1`.
+                Will be less than `scale_low` if we failed to fit.
         """
-
         # normalize rotation angle
         if not rotate % 90 == 0:
             raise ValueError("bad rotation angle")
@@ -12321,24 +12324,50 @@ def insert_htmlbox(
         else:
             raise ValueError("'text' must be a string or a Story")
         # ----------------------------------------------------------------
-        # Find a scaling factor that lets our story fit in
+        # Find a scaling factor that lets our story fit in. Instead of scaling
+        # the text smaller, we instead look at how much bigger the rect needs
+        # to be to fit the text, then reverse the scaling to get how much we
+        # need to scale down the text.
         # ----------------------------------------------------------------
-        scale_max = None if scale_low == 0 else 1 / scale_low
+        rect_scale_max = None if scale_low == 0 else 1 / scale_low
 
-        fit = story.fit_scale(temp_rect, scale_min=1, scale_max=scale_max)
+        fit = story.fit_scale(temp_rect, scale_min=1, scale_max=rect_scale_max)
+        
         if not fit.big_enough:  # there was no fit
-            return (-1, scale_low)
-
-        filled = fit.filled
-        scale = 1 / fit.parameter  # shrink factor
-
-        spare_height = fit.rect.y1 - filled[3]  # unused room at rectangle bottom
-        # Note: due to MuPDF's logic this may be negative even for successful fits.
-        if scale != 1 or spare_height < 0:  # if scaling occurred, set spare_height to 0
+            scale = 1/fit.parameter
+            return (-1, scale)
+
+        # fit.filled is a tuple; we convert it in place to a Rect for
+        # convenience. (fit.rect is already a Rect.)
+        fit.filled = Rect(fit.filled)
+        assert (fit.rect.x0, fit.rect.y0) == (0, 0)
+        assert (fit.filled.x0, fit.filled.y0) == (0, 0)
+        
+        # Extra scaling for width if any word is wider than the fit rect - in
+        # this case fit.filled.x1 will be greater than fit.rect.x1.
+        scale_for_width = None
+        if _scale_word_width and fit.filled.x1 > fit.rect.x1:
+            scale_for_width = fit.filled.x1 / fit.rect.x1
+            fit.rect.x1 *= scale_for_width
+            fit.rect.y1 *= scale_for_width
+            fit.parameter *= scale_for_width
+
+        scale = 1 / fit.parameter
+        if scale < scale_low:
+            # Extra scaling for width has reduced scale out of range, so return
+            # failure.
+            return (-1, scale)
+        
+        if scale != 1 and scale_for_width is None:
+            # Scaling occurred but with no final width adjustment, so there
+            # will be no spare height.
             spare_height = 0
+        else:
+            # There will usually be spare height.
+            spare_height = max((fit.rect.y1 - fit.filled.y1) * scale, 0)
 
         def rect_function(*args):
-            return fit.rect, fit.rect, Identity
+            return fit.rect, fit.rect, None
 
         # draw story on temp PDF page
         doc = story.write_with_links(rect_function)
@@ -16045,15 +16074,17 @@ class FitResult:
         `big_enough`:
             `True` if the fit succeeded.
         `filled`:
-            From the last call to `Story.place()`.
+            Tuple (x0, y0, x1, y1) from the last call to `Story.place()`. This
+            will be wider than .rect if any single word (which we never split)
+            was too wide for .rect.
         `more`:
             `False` if the fit succeeded.
         `numcalls`:
             Number of calls made to `self.place()`.
         `parameter`:
             The successful parameter value, or the largest failing value.
         `rect`:
-            The rect created from `parameter`.
+            The pumupdf.Rect created from `parameter`.
         '''
         def __init__(self, big_enough=None, filled=None, more=None, numcalls=None, parameter=None, rect=None):
             self.big_enough = big_enough
@@ -16229,7 +16260,7 @@ def fit_scale(self, rect, scale_min=0, scale_max=None, delta=0.001, verbose=Fals
         Finds smallest value `scale` in range `scale_min..scale_max` where
         `scale * rect` is large enough to contain the story `self`.
 
-        Returns a `Story.FitResult` instance.
+        Returns a `Story.FitResult` instance with `.parameter` set to `scale`.
 
         :arg width:
             width of rect.

tests/resources/test_4613.png

@@ -7,6 +7,11 @@
 """
 import pymupdf
 
+import gentle_compare
+
+import os
+import textwrap
+
 # codespell:ignore-begin
 text = """Der Kleine Schwertwal (Pseudorca crassidens), auch bekannt als Unechter oder Schwarzer Schwertwal, ist eine Art der Delfine (Delphinidae) und der einzige rezente Vertreter der Gattung Pseudorca.
 
@@ -286,3 +291,58 @@ def test_4400():
         text = '111111111'
         print(f'Calling writer.fill_textbox().', flush=1)
         writer.fill_textbox(rect=pymupdf.Rect(0, 0, 100, 20), pos=(80, 0), text=text, fontsize=8)
+
+
+def test_4613():
+    print()
+    text = 3 * 'abcdefghijklmnopqrstuvwxyz\nABCDEFGHIJKLMNOPQRSTUVWXYZ\n'
+    story = pymupdf.Story(text)
+    rect = pymupdf.Rect(10, 10, 100, 100)
+    
+    # Test default operation where we get additional scaling down because of
+    # the long words in our text.
+    with pymupdf.open() as doc:
+        page = doc.new_page()
+        spare_height, scale = page.insert_htmlbox(rect, story)
+        print(f'test_4613(): {spare_height=} {scale=}')
+        # Even though we have scaled down, the additional scaling from word width
+        # means there is spare vertical space.
+        assert abs(spare_height - 50.53) < 0.1
+        assert abs(scale - 0.4009) < 0.01
+
+        page.draw_rect(rect, (1, 0, 0))
+        path = os.path.normpath(f'{__file__}/../../tests/test_4613.pdf')
+        doc.save(path)
+
+        path_pixmap = os.path.normpath(f'{__file__}/../../tests/test_4613.png')
+        path_pixmap_expected = os.path.normpath(f'{__file__}/../../tests/resources/test_4613.png')
+        pixmap = page.get_pixmap(dpi=300)
+        pixmap.save(path_pixmap)
+        
+        new_text = page.get_text('text', clip=rect)
+        print(f'test_4613(): new_text:')
+        print(textwrap.indent(new_text, '    '))
+        assert new_text == text
+
+        rms = gentle_compare.pixmaps_rms(pixmap, path_pixmap_expected)
+        assert rms == 0, f'{rms=}'
+    
+    # Check with _scale_word_width=False - ignore too-wide words.
+    with pymupdf.open() as doc:
+        page = doc.new_page()
+        spare_height, scale = page.insert_htmlbox(rect, story, _scale_word_width=False)
+        print(f'test_4613(): _scale_word_width=False: {spare_height=} {scale=}')
+        # With _scale_word_width=False there is no additional scaling down from
+        # word width, so we should have spare_height == 0 and only a small
+        # amount of down-scaling.
+        assert spare_height == 0
+        assert abs(scale - 0.914) < 0.01
+
+    # Check that we get no fit if scale_low is not low enough.
+    with pymupdf.open() as doc:
+        page = doc.new_page()
+        scale_low=0.6
+        spare_height, scale = page.insert_htmlbox(rect, story, scale_low=scale_low)
+        print(f'test_4613(): {scale_low=}: {spare_height=} {scale=}')
+        assert spare_height == -1
+        assert abs(scale - 0.40093) < 0.01