41class Document(pp.PdfDocument):
 42    """
 43    This class is a convenience wrapper with caching around the high-level APIs
 44    of pypdfium.
 45    """
 46
 47    def __init__(self, path: Path, autoclose: bool = False):
 48        """
 49        :param path: Path to the PDF to open.
 50        """
 51        path = Path(path)
 52        self.name: str = path.stem
 53        """Stem of the document file name"""
 54        super().__init__(path, autoclose=autoclose)
 55        self._path = path
 56        self._bbox_cache = defaultdict(dict)
 57        _LOGGER.debug(f"Loading: {path}")
 58
 59    @cached_property
 60    def metadata(self) -> dict[str, str]:
 61        """The PDF metadata dictionary."""
 62        return self.get_metadata_dict()
 63
 64    @property
 65    def destinations(self) -> Iterator[tuple[int, str]]:
 66        """Yields (page 0-index, named destination) of the whole document."""
 67        for ii in range(pp.raw.FPDF_CountNamedDests(self)):
 68            length = pp.raw.FPDF_GetNamedDest(self, ii, 0, 0)
 69            clength = ctypes.c_long(length)
 70            cbuffer = ctypes.create_string_buffer(length * 2)
 71            dest = pp.raw.FPDF_GetNamedDest(self, ii, cbuffer, clength)
 72            name = cbuffer.raw[: clength.value * 2].decode("utf-16-le").rstrip("\x00")
 73            page = pp.raw.FPDFDest_GetDestPageIndex(self, dest)
 74            yield (page, name)
 75
 76    @cached_property
 77    def toc(self) -> list[pp.PdfOutlineItem]:
 78        """
 79        The table of content as a sorted list of outline items ensuring item has
 80        a page index by reusing the last one.
 81        """
 82        tocs = set()
 83        # Sometimes the TOC contains duplicates so we must use a set
 84        last_page_index = 0
 85        for toc in self.get_toc():
 86            outline = _OutlineItem(
 87                toc.level,
 88                toc.title,
 89                toc.is_closed,
 90                toc.n_kids,
 91                toc.page_index or last_page_index,
 92                toc.view_mode,
 93                toc.view_pos,
 94            )
 95            last_page_index = toc.page_index or last_page_index
 96            tocs.add(outline)
 97        return list(sorted(list(tocs), key=lambda o: (o.page_index, o.level, o.title)))
 98
 99    @cached_property
100    def identifier_permanent(self) -> str:
101        """The permanent file identifier."""
102        return self.get_identifier(pp.raw.FILEIDTYPE_PERMANENT)
103
104    @cached_property
105    def identifier_changing(self) -> str:
106        """The changing file identifier."""
107        return self.get_identifier(pp.raw.FILEIDTYPE_CHANGING)
108
109    @cached_property
110    def page_count(self) -> int:
111        """The number of pages in the document."""
112        return pp.raw.FPDF_GetPageCount(self)
113
114    @cache
115    def page(self, index: int) -> Page:
116        """
117        :param index: 0-indexed page number.
118        :return: the page object for the index.
119        """
120        assert index < self.page_count
121        return Page(self, index)
122
123    def pages(self, numbers: Iterable[int] = None) -> Iterator[Page]:
124        """
125        :param numbers: an iterable range of page numbers (0-indexed!).
126                        If `None`, then the whole page range is used.
127        :return: yields each page in the range.
128        """
129        if numbers is None:
130            numbers = range(self.page_count)
131        for ii in numbers:
132            if 0 <= ii < self.page_count:
133                yield self.page(ii)
134
135    def __repr__(self) -> str:
136        return f"Doc({self.name})"

 30class Page(pp.PdfPage):
 31    """
 32    This class provides low-level access to graphics and characters of the page.
 33    It also fixes missing bounding boxes for rotates characters on page load,
 34    as well as allow searching for characters in an area instead of just text.
 35    """
 36
 37    def __init__(self, document: "modm_data.pdf.Document", index: int):  # noqa: F821
 38        """
 39        :param document: a PDF document.
 40        :param index: 0-index page number.
 41        """
 42        self.index = index
 43        """0-index page number."""
 44        self.number = index + 1
 45        """1-index page number."""
 46
 47        super().__init__(pp.raw.FPDF_LoadPage(document, index), document, document.formenv)
 48        self._links = None
 49        self._weblinks = None
 50        self._linked = False
 51
 52        _LOGGER.debug(f"Loading: {index}")
 53
 54        self._text = self.get_textpage()
 55        self._linkpage = pp.raw.FPDFLink_LoadWebLinks(self._text)
 56        self._structtree = pp.raw.FPDF_StructTree_GetForPage(self)
 57        # close them in reverse order
 58        weakref.finalize(self, pp.raw.FPDF_StructTree_Close, self._structtree)
 59        weakref.finalize(self, pp.raw.FPDFLink_CloseWebLinks, self._linkpage)
 60
 61        self._fix_bboxes()
 62
 63    @cached_property
 64    def label(self) -> str:
 65        """The page label."""
 66        return self.pdf.get_page_label(self.index)
 67
 68    @cached_property
 69    def width(self) -> float:
 70        """The page width."""
 71        return self.get_width()
 72
 73    @cached_property
 74    def height(self) -> float:
 75        """The page height."""
 76        return self.get_height()
 77
 78    @cached_property
 79    def rotation(self) -> int:
 80        """The page rotation in degrees."""
 81        return self.get_rotation()
 82
 83    @cached_property
 84    def bbox(self) -> Rectangle:
 85        """The page bounding box."""
 86        return Rectangle(*self.get_bbox())
 87
 88    @cached_property
 89    def char_count(self) -> int:
 90        """The total count of characters."""
 91        return self._text.count_chars()
 92
 93    @cache
 94    def char(self, index: int) -> Character:
 95        """:return: The character at the 0-index."""
 96        return Character(self, index)
 97
 98    @property
 99    def chars(self) -> Iterator[Character]:
100        """Yields all characters."""
101        for ii in range(self.char_count):
102            yield self.char(ii)
103
104    @cached_property
105    def objlinks(self) -> list[ObjLink]:
106        """All object links."""
107        links = []
108        pos = ctypes.c_int(0)
109        link = pp.raw.FPDF_LINK()
110        while pp.raw.FPDFLink_Enumerate(self, pos, link):
111            links.append(ObjLink(self, link))
112        return links
113
114    @cached_property
115    def weblinks(self) -> list[WebLink]:
116        """All web links."""
117        links = []
118        for ii in range(pp.raw.FPDFLink_CountWebLinks(self._linkpage)):
119            links.append(WebLink(self, ii))
120        return links
121
122    def chars_in_area(self, area: Rectangle) -> list[Character]:
123        """
124        :param area: area to search for character in.
125        :return: All characters found in the area.
126        """
127        found = []
128        # We perform binary searches of the lower and upper y-positions first
129        # lines are ordered by y-position
130        ypositions = list(self._charlines.keys())
131        y_bottom = bisect_left(ypositions, area.bottom)
132        y_top = bisect_right(ypositions, area.top, lo=y_bottom)
133
134        # Then for every line we do another binary search for left and right
135        for ypos in ypositions[y_bottom:y_top]:
136            chars = self._charlines[ypos]
137            x_left = bisect_left(chars, area.left, key=lambda c: c.bbox.midpoint.x)
138            x_right = bisect_right(chars, area.right, lo=x_left, key=lambda c: c.bbox.midpoint.x)
139            # Finally we add all these characters
140            found.extend(chars[x_left:x_right])
141        return found
142
143    def text_in_area(self, area: Rectangle) -> str:
144        """
145        :param area: area to search for text in.
146        :return: Only the text found in the area.
147        """
148        return self._text.get_text_bounded(area.left, area.bottom, area.right, area.top)
149
150    @property
151    def structures(self) -> Iterator[Structure]:
152        """The PDF/UA tags."""
153        count = pp.raw.FPDF_StructTree_CountChildren(self._structtree)
154        for ii in range(count):
155            child = pp.raw.FPDF_StructTree_GetChildAtIndex(self._structtree, ii)
156            yield Structure(self, child)
157
158    def find(self, string: str, case_sensitive: bool = True) -> Iterator[Character]:
159        """
160        Searches for a match string as whole, consecutive words and yields the
161        characters.
162
163        :param string: The search string.
164        :param case_sensitive: Ignore case if false.
165        :return: yields the characters found.
166        """
167        searcher = self._text.search(string, match_case=case_sensitive, match_whole_word=True, consecutive=True)
168        while idx := searcher.get_next():
169            chars = [self.char(ii) for ii in range(idx[0], idx[0] + idx[1])]
170            yield chars
171
172    @cached_property
173    def paths(self) -> list[Path]:
174        """All paths."""
175        return [Path(o) for o in self.get_objects([pp.raw.FPDF_PAGEOBJ_PATH])]
176
177    @cached_property
178    def images(self) -> list[Image]:
179        """All images."""
180        return [Image(o) for o in self.get_objects([pp.raw.FPDF_PAGEOBJ_IMAGE])]
181
182    def graphic_clusters(
183        self, predicate: Callable[[Path | Image], bool] = None, absolute_tolerance: float = None
184    ) -> list[tuple[Rectangle, list[Path]]]:
185        if absolute_tolerance is None:
186            absolute_tolerance = min(self.width, self.height) * 0.01
187
188        # First collect all vertical regions
189        filtered_paths = []
190        for path in self.paths:
191            if predicate is None or predicate(path):
192                filtered_paths.append(path)
193        for image in self.images:
194            if predicate is None or predicate(image):
195                filtered_paths.append(image)
196
197        regions = []
198        for path in sorted(filtered_paths, key=lambda path: path.bbox.y):
199            for reg in regions:
200                if reg.overlaps(path.bbox.bottom, path.bbox.top, absolute_tolerance):
201                    # They overlap, so merge them
202                    reg.v0 = min(reg.v0, path.bbox.bottom)
203                    reg.v1 = max(reg.v1, path.bbox.top)
204                    reg.objs.append(path)
205                    break
206            else:
207                regions.append(Region(path.bbox.bottom, path.bbox.top, path))
208
209        # Now collect horizontal region inside each vertical region
210        for yreg in regions:
211            for path in sorted(filtered_paths, key=lambda path: path.bbox.x):
212                # check if horizontal line is contained in vregion
213                if yreg.contains(path.bbox.y, absolute_tolerance):
214                    for xreg in yreg.subregions:
215                        if xreg.overlaps(path.bbox.left, path.bbox.right, absolute_tolerance):
216                            # They overlap so merge them
217                            xreg.v0 = min(xreg.v0, path.bbox.left)
218                            xreg.v1 = max(xreg.v1, path.bbox.right)
219                            xreg.objs.append(path)
220                            break
221                    else:
222                        yreg.subregions.append(Region(path.bbox.left, path.bbox.right, path))
223
224        clusters = []
225        for yreg in regions:
226            for xreg in yreg.subregions:
227                if len(yreg.subregions) > 1:
228                    # Strip down the height again for subregions
229                    y0, y1 = 1e9, 0
230                    for path in xreg.objs:
231                        y0 = min(y0, path.bbox.bottom)
232                        y1 = max(y1, path.bbox.top)
233                else:
234                    y0, y1 = yreg.v0, yreg.v1
235                bbox = Rectangle(xreg.v0, y0, xreg.v1, y1)
236                clusters.append((bbox, xreg.objs))
237
238        return sorted(clusters, key=lambda c: (-c[0].y, c[0].x))
239
240    def _link_characters(self):
241        if self._linked:
242            return
243        # The in-document links only gives us rectangles and we must find the
244        # linked chars ourselves
245        for link in self.objlinks:
246            for char in self.chars_in_area(link.bbox):
247                char.objlink = link
248        # The weblinks give you an explicit char range, very convenient
249        for link in self.weblinks:
250            for ii in range(*link.range):
251                self.char(ii).weblink = link
252        self._linked = True
253
254    @cached_property
255    def _charlines(self):
256        charlines = defaultdict(list)
257        for char in self.chars:
258            charlines[round(char.bbox.midpoint.y, 1)].append(char)
259
260        orderedchars = OrderedDict.fromkeys(sorted(charlines))
261        for ypos, chars in charlines.items():
262            orderedchars[ypos] = sorted(chars, key=lambda c: c.bbox.midpoint.x)
263
264        return orderedchars
265
266    def _fix_bboxes(self):
267        def _key(char):
268            height = round(char.tbbox.height, 1)
269            width = round(char.tbbox.width, 1)
270            return f"{char.font} {char.unicode} {height} {width}"
271
272        fix_chars = []
273        for char in self.chars:
274            if not char._bbox.width or not char._bbox.height:
275                if char._rotation:
276                    fix_chars.append(char)
277                elif char.unicode not in {0xA, 0xD}:
278                    fix_chars.append(char)
279            elif char.unicode not in {0xA, 0xD} and not char._rotation and _key(char) not in self.pdf._bbox_cache:
280                bbox = char._bbox.translated(-char.origin).rotated(self.rotation + char._rotation)
281                self.pdf._bbox_cache[_key(char)] = (char, bbox)
282                # print("->", _key(char), char.descr(), char.height, char.rotation, char._rotation, self.rotation)
283        for char in fix_chars:
284            bbox = self.pdf._bbox_cache.get(_key(char))
285            if bbox is not None:
286                # print("<-", char.descr(), char._rotation, char.rotation, char.height)
287                _, bbox = bbox
288                bbox = bbox.rotated(-self.rotation - char._rotation).translated(char.origin)
289                char._bbox = bbox
290            elif char.unicode not in {0x20, 0xA, 0xD}:
291                _LOGGER.debug(f"Unable to fix bbox for {char.descr()}!")

 28class Character:
 29    """
 30    This class contains all information about a single character in the PDF
 31    page.
 32    """
 33
 34    class RenderMode(Enum):
 35        """Tells the PDF viewer how to render this character glyph."""
 36
 37        UNKNOWN = -1
 38        FILL = 0
 39        STROKE = 1
 40        FILL_STROKE = 2
 41        INVISIBLE = 3
 42        FILL_CLIP = 4
 43        STROKE_CLIP = 5
 44        FILL_STROKE_CLIP = 6
 45        CLIP = 7
 46
 47    def __init__(self, page: "modm_data.pdf.page.Page", index: int):  # noqa: F821
 48        """
 49        :param page: The page containing the character.
 50        :param index: The index of the character.
 51        """
 52        self._page = page
 53        self._text = page._text
 54        self._index = index
 55        self._font = None
 56        self._rotation = int(math.degrees(pp.raw.FPDFText_GetCharAngle(self._text, self._index)))
 57
 58        self.unicode: int = pp.raw.FPDFText_GetUnicode(self._text, self._index)
 59        """The unicode value of the character."""
 60        self.objlink: "modm_data.pdf.link.ObjLink" = None  # noqa: F821
 61        """The object link of this character or `None`"""
 62        self.weblink: "modm_data.pdf.link.WebLink" = None  # noqa: F821
 63        """The web link of this character or `None`"""
 64
 65        bbox = Rectangle(*self._text.get_charbox(self._index, loose=True))
 66        if self._page.rotation:
 67            bbox = Rectangle(bbox.p0.y, self._page.height - bbox.p1.x, bbox.p1.y, self._page.height - bbox.p0.x)
 68        self._bbox = bbox
 69
 70    def _font_flags(self) -> tuple[str, int]:
 71        if self._font is None:
 72            font = ctypes.create_string_buffer(255)
 73            flags = ctypes.c_int()
 74            pp.raw.FPDFText_GetFontInfo(self._text, self._index, font, 255, flags)
 75            self._font = (font.value.decode("utf-8"), flags.value)
 76        return self._font
 77
 78    @property
 79    def char(self) -> str:
 80        """The printable string of the unicode value."""
 81        char = chr(self.unicode)
 82        return char if char.isprintable() else ""
 83
 84    @cached_property
 85    def origin(self) -> Point:
 86        """The origin of the character."""
 87        x, y = ctypes.c_double(), ctypes.c_double()
 88        assert pp.raw.FPDFText_GetCharOrigin(self._text, self._index, x, y)
 89        if self._page.rotation:
 90            return Point(y.value, self._page.height - x.value)
 91        return Point(x.value, y.value)
 92
 93    @cached_property
 94    def width(self) -> float:
 95        """The width of the character's bounding box."""
 96        if self.rotation:
 97            return self.bbox.height
 98        return self.bbox.width
 99
100    @cached_property
101    def height(self) -> float:
102        """The height of the character's bounding box."""
103        if self.rotation:
104            return self.bbox.width
105        return self.bbox.height
106
107    @cached_property
108    def tbbox(self) -> Rectangle:
109        """The tight bounding box of the character."""
110        tbbox = Rectangle(*self._text.get_charbox(self._index))
111        if self._page.rotation:
112            tbbox = Rectangle(tbbox.p0.y, self._page.height - tbbox.p1.x, tbbox.p1.y, self._page.height - tbbox.p0.x)
113        return tbbox
114
115    @property
116    def bbox(self) -> Rectangle:
117        """
118        The loose bounding box of the character.
119        .. note::
120            If the loose bounding box is not available, the tight bounding box
121            is used instead.
122        """
123        if not self._bbox.width or not self._bbox.height:
124            return self.tbbox
125        return self._bbox
126
127    @cached_property
128    def twidth(self) -> float:
129        """The width of the character's tight bounding box."""
130        return self.tbbox.width
131
132    @cached_property
133    def theight(self) -> float:
134        """The height of the character's tight bounding box."""
135        return self.tbbox.height
136
137    @cached_property
138    def render_mode(self) -> RenderMode:
139        """The render mode of the character."""
140        return Character.RenderMode(pp.raw.FPDFText_GetTextRenderMode(self._text, self._index))
141
142    @cached_property
143    def rotation(self) -> int:
144        """The rotation of the character in degrees modulo 360."""
145        # Special case for vertical text in rotated pages
146        if self._page.rotation == 90 and self._rotation == 0 and self.unicode not in {0x20, 0xA, 0xD}:
147            return 90
148        if self._page.rotation and self._rotation:
149            return (self._page.rotation + self._rotation) % 360
150        return self._rotation
151
152    @cached_property
153    def size(self) -> float:
154        """The font size of the character."""
155        return pp.raw.FPDFText_GetFontSize(self._text, self._index)
156
157    @cached_property
158    def weight(self) -> int:
159        """The font weight of the character."""
160        return pp.raw.FPDFText_GetFontWeight(self._text, self._index)
161
162    @cached_property
163    def fill(self) -> int:
164        """The fill color of the character."""
165        r, g, b, a = ctypes.c_uint(), ctypes.c_uint(), ctypes.c_uint(), ctypes.c_uint()
166        pp.raw.FPDFText_GetFillColor(self._text, self._index, r, g, b, a)
167        return r.value << 24 | g.value << 16 | b.value << 8 | a.value
168
169    @cached_property
170    def stroke(self) -> int:
171        """The stroke color of the character."""
172        r, g, b, a = ctypes.c_uint(), ctypes.c_uint(), ctypes.c_uint(), ctypes.c_uint()
173        pp.raw.FPDFText_GetStrokeColor(self._text, self._index, r, g, b, a)
174        return r.value << 24 | g.value << 16 | b.value << 8 | a.value
175
176    @cached_property
177    def font(self) -> str:
178        """The font name of the character."""
179        return self._font_flags()[0]
180
181    @cached_property
182    def flags(self) -> int:
183        """The font flags of the character."""
184        return self._font_flags()[1]
185
186    def descr(self) -> str:
187        """Human-readable description of the character for debugging."""
188        char = chr(self.unicode)
189        if not char.isprintable():
190            char = hex(self.unicode)
191        return (
192            f"Chr({char}, {self.size}, {self.weight}, {self.rotation}, "
193            f"{self.render_mode}, {self.font}, {hex(self.flags)}, "
194            f"{self.fill}, {self.stroke}, {repr(self.bbox)})"
195        )
196
197    def __str__(self) -> str:
198        return self.char
199
200    def __repr__(self) -> str:
201        char = chr(self.unicode)
202        escape = {0xA: "\\n", 0xD: "\\r", 0x9: "\\t", 0x20: "␣"}
203        char = escape.get(self.unicode, char if char.isprintable() else hex(self.unicode))
204        return char