upload v1.18.9

Author: JorjMcKie

docs/changes.rst

@@ -11,6 +11,7 @@ Changes in Version 1.18.9
 * **Changed** :meth:`Document.subset_fonts`: Text is **not rewritten** any more and should therefore **retain all its origial properties** -- like being hidden or being controlled by Optional Content mechanisms.
 * **Changed** :ref:`TextWriter` output to also accept text in right to left mode (Arabian, Hebrew): :meth:`TextWriter.fill_textbox`, :meth:`TextWriter.append`. These methods now accept a new boolean parameter `right_to_left`, which is *False* by default. Implements `#897 <https://github.com/pymupdf/PyMuPDF/issues/897>`_.
 * **Changed** :meth:`TextWriter.fill_textbox` to return all lines of text, that did not fit in the given rectangle. Also changed the default of the ``warn`` parameter to no longer print a warning message in overflow situations.
+* **Added** a utility function :meth:`recover_quad`, which computes the quadrilateral of a span. This function can be used when quadrilaterals for text extracted with the "dict" or "rawdict" options of :meth:`Page.get_text`.
 
 Changes in Version 1.18.8
 -------------------------

docs/faq.rst

@@ -818,30 +818,11 @@ How to Mark Non-horizontal Text
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 The previous section already shows an example for marking non-horizontal text detected by text **searching**.
 
-But text **extraction** with the "dict" option of :meth:`Page.get_text` may also return text with a non-zero angle to the x-axis. This is reflected by the value of the ``"dir"`` key of the line dictionary: it is the tuple ``(cosine, sine)`` of that angle.
+But text **extraction** with the "dict" / "rawdict" options of :meth:`Page.get_text` may also return text with a non-zero angle to the x-axis. This is reflected by the value of the ``"dir"`` key of the line dictionary: it is the tuple ``(cosine, sine)`` of that angle. If this value **does not equal** ``(1, 0)``, then the extracted text / characters are rotated by some angle != 0.
 
-Currently, all bboxes returned by the method's are rectangles only -- no quads. So we can mark the span text (correctly) only, if the **angle is 0, 90, 180 or 270 degrees.**
-
-In this case we can convert the span bbox into the right quad by choosing the right sequence of its corners::
-
-    r = fitz.Rect(span["bbox"])
-
-    if line["dir"] == (1, 0):  # rotation 0
-        q = fitz.Quad(r)
-
-    elif line["dir"] == (0, -1):  # rotation 90
-        q = fitz.Quad(r.bl, r.tl, r.br, r.tr)
-
-    elif line["dir"] == (-1, 0):  # rotation 180
-        q = fitz.Quad(r.br, r.bl, r.tr, r.tl)
-
-    elif line["dir"] == (0, 1):  # rotation 270
-        q = fitz.Quad(r.tr, r.br, r.tl, r.bl)
-
-    else:
-        q = fitz.Quad(r)
-        print("warning: unsupported text flow")
+All bboxes returned by the method are rectangles only -- no quads. In order to mark the span text correctly (or fitting a quad around it), its quadrilateral must be recovered from the data in the line and the span. Do this with the following utility function::
 
+    q = fitz.recover_quad(line["dir"], span)
     annot = page.addHighlightAnnot(q)
 
 

docs/functions.rst

@@ -48,6 +48,7 @@ Yet others are handy, general-purpose utilities.
 :meth:`PaperRect`                    return rectangle for a known paper format
 :meth:`sRGB_to_pdf`                  return PDF RGB color tuple from a sRGB integer
 :meth:`sRGB_to_rgb`                  return (R, G, B) color tuple from a sRGB integer
+:meth:`recover_quad`                 return the quad for a text span ("dict" / "rawdict")
 :meth:`glyph_name_to_unicode`        return unicode from a glyph name
 :meth:`unicode_to_glyph_name`        return glyph name from a unicode
 :meth:`make_table`                   split rectangle in sub-rectangles
@@ -160,12 +161,25 @@ Yet others are handy, general-purpose utilities.
 
       *New in v1.17.4*
 
-      Convenience function returning a color (red, green, blue) for a given *sRGB* color integer .
+      Convenience function returning a color (red, green, blue) for a given *sRGB* color integer.
 
       :arg int srgb: an integer of format RRGGBB, where each color component is an integer in range(255).
 
       :returns: a tuple (red, green, blue) with integer items in intervall *0 <= item <= 255* representing the same color.
 
+-----
+
+   .. method:: recover_quad(line_dir, span)
+
+      *New in v1.18.9*
+
+      Convenience function returning the quadrilateral envelopping the text of a text span, as returned by :meth:`Page.get_text` using the "dict" or "rawdict" options.
+
+      :arg tuple line_dict: the value ``line["dir"]`` of the span's line.
+      :arg dict span: the span sub-dictionary.
+
+      :returns: the quadrilateral of the span's text.
+
 -----
 
    .. method:: make_table(rect, cols=1, rows=1)

docs/page.rst

@@ -303,9 +303,9 @@ In a nutshell, this is what you can do with PyMuPDF:
            >>> page.addHighlightAnnot(quads)
 
       .. note::
-        Obviously, text marker annotations need to know what is the top and the bottom, the left and the right side of the tetragon to be marked. If the arguments are quads, this information is given by the sequence of the quad points. In contrast, a rectangle delivers much less information -- this is illustrated by the fact, that 4! = 24 different quads can be constructed with the four corners of each reactangle.
+        Obviously, text marker annotations need to know what is the top, the bottom, the left, and the right side of the tetragon to be marked. If the arguments are quads, this information is given by the sequence of the quad points. In contrast, a rectangle delivers much less information -- this is illustrated by the fact, that 4! = 24 different quads can be constructed with the four corners of each reactangle.
 
-        Therefore, we **strongly recommend** to use the ``quads`` option for text searches, to ensure correct text markers. For more details on text marking see section "How to Mark Non-horizontal Text" of :ref:`FAQ`.
+        Therefore, we **strongly recommend** to use the ``quads`` option for text searches, to ensure correct text markers. A similar consideration applies to **marking text spans** extracted with the "dict" / "rawdict" options of :meth:`Page.get_text`. For more details on text marking see section "How to Mark Non-horizontal Text" of :ref:`FAQ`.
 
       :arg rect_like,quad_like,list,tuple quads: *(Changed in v1.14.20)* the location(s) -- rectangle(s) or quad(s) -- to be marked. A list or tuple must consist of :data:`rect_like` or :data:`quad_like` items (or even a mixture of either). Every item must be finite, convex and not empty (as applicable). *(Changed in v1.16.14)* **Set this parameter to** *None* if you want to use the following arguments.
       :arg point_like start: *(New in v1.16.14)* start text marking at this point. Defaults to the top-left point of *clip*.

docs/version.rst

@@ -1,6 +1,6 @@
 Covered Version
 --------------------
 
-This documentation covers PyMuPDF v1.18.9 features as of **2021-02-25 12:22:20**.
+This documentation covers PyMuPDF v1.18.9 features as of **2021-02-26 13:46:32**.
 
 .. note:: The major and minor versions of **PyMuPDF** and **MuPDF** will always be the same. Only the third qualifier (patch level) may deviate from that of MuPDF.

fitz/helper-python.i

@@ -1359,6 +1359,54 @@ def make_table(rect: rect_like =(0, 0, 1, 1), cols: int =1, rows: int =1) -> lis
     return rects
 
 
+def recover_quad(line_dir, span):
+    """Recover the quadrilateral of a text span.
+
+    Args:
+        line_dir: the value 'line["dir"]' of the span's line, which is
+                  a tuple (cos, sin) of the text angle with the x-axis.
+        span: the span dictionary
+    Returns:
+        The quadrilateral envelopping the span's text.
+    """
+    if type(line_dir) is not tuple or len(line_dir) != 2:
+        raise ValueError("bad line dir argument")
+    if type(span) is not dict:
+        raise ValueError("bad span argument")
+    cos, sin = line_dir
+    bbox = Rect(span["bbox"])
+
+    if TOOLS.set_small_glyph_heights():  # ==> just fontsize
+        d = 1
+    else:
+        d = span["ascender"] - span["descender"]
+
+    height = d * span["size"]
+    hs = height * sin
+    hc = height * cos
+    if hc >= 0 and hs <= 0:  # Quadrant 1
+        ul = bbox.bl - (0, hc)
+        ur = bbox.tr + (hs, 0)
+        ll = bbox.bl - (hs, 0)
+        lr = bbox.tr + (0, hc)
+    elif hc <= 0 and hs <= 0:  # Quadrant 2
+        ul = bbox.br + (hs, 0)
+        ur = bbox.tl - (0, hc)
+        ll = bbox.br + (0, hc)
+        lr = bbox.tl - (hs, 0)
+    elif hc <= 0 and hs >= 0:  # Quadrant 3
+        ul = bbox.tr - (0, hc)
+        ur = bbox.bl + (hs, 0)
+        ll = bbox.tr - (hs, 0)
+        lr = bbox.bl + (0, hc)
+    else:  # Quadrant 4
+        ul = bbox.tl + (hs, 0)
+        ur = bbox.br - (0, hc)
+        ll = bbox.tl + (0, hc)
+        lr = bbox.br - (hs, 0)
+    return Quad(ul, ur, ll, lr)
+
+
 def repair_mono_font(page: "Page", font: "Font") -> None:
     """Repair character spacing for mono fonts.
 

fitz/utils.py

@@ -1087,6 +1087,7 @@ def setToC(
     old_xrefs = doc._delToC()  # del old outlines, get their xref numbers
 
     # prepare table of xrefs for new bookmarks
+    old_xrefs = []
     xref = [0] + old_xrefs
     xref[0] = doc._getOLRootNumber()  # entry zero is outline root xref number
     if toclen > len(old_xrefs):  # too few old xrefs?

fitz/version.i

@@ -1,6 +1,6 @@
 %pythoncode %{
 VersionFitz = "1.18.0"
 VersionBind = "1.18.9"
-VersionDate = "2021-02-25 12:22:20"
-version = (VersionBind, VersionFitz, "20210225122220")
+VersionDate = "2021-02-26 13:46:32"
+version = (VersionBind, VersionFitz, "20210226134632")
 %}