52def annotate_debug_info(page: Page, new_doc: pp.PdfDocument = None, index: int = 0) -> pp.PdfDocument:
 53    """
 54    Copies each page into a new or existing PDF document and overlays the internal information on top of the content.
 55    - Renders the bounding boxes in RED and origins in BLACK of all characters.
 56    - Renders the bounding boxes of web links in BLUE GREEN.
 57    - Renders the bounding boxes of object links in YELLOW GREEN.
 58    - Renders all graphics paths in BLUE.
 59    - Renders the bounding boxes of computed graphics clusters in CYAN.
 60
 61    :param page: The page to be annotated.
 62    :param new_doc: The PDF document to copy the page to. If not provided, a new document is created.
 63    :param index: The index of the page in the new document.
 64    :return: The new document with the annotated page added.
 65    """
 66    _, height = page.width, page.height
 67
 68    if new_doc is None:
 69        new_doc = pp.raw.FPDF_CreateNewDocument()
 70    # copy page over to new doc
 71    assert pp.raw.FPDF_ImportPages(new_doc, page.pdf, str(page.number).encode("ascii"), index)
 72    new_page = pp.raw.FPDF_LoadPage(new_doc, index)
 73    rotation = page.rotation
 74
 75    for path in page.paths:
 76        p0 = path.points[0]
 77        if rotation:
 78            obj = pp.raw.FPDFPageObj_CreateNewPath(height - p0.y, p0.x)
 79        else:
 80            obj = pp.raw.FPDFPageObj_CreateNewPath(p0.x, p0.y)
 81        assert pp.raw.FPDFPageObj_SetStrokeColor(obj, 0, 0, 0xFF, 0xC0)
 82        assert pp.raw.FPDFPageObj_SetStrokeWidth(obj, 0.25)
 83        assert pp.raw.FPDFPageObj_SetLineJoin(obj, pp.raw.FPDF_LINEJOIN_ROUND)
 84        assert pp.raw.FPDFPageObj_SetLineCap(obj, pp.raw.FPDF_LINECAP_ROUND)
 85        assert pp.raw.FPDFPath_SetDrawMode(obj, 0, True)
 86        for point in path.points[1:]:
 87            if point.type == path.Type.MOVE:
 88                if rotation:
 89                    assert pp.raw.FPDFPath_MoveTo(obj, height - point.y, point.x)
 90                else:
 91                    assert pp.raw.FPDFPath_MoveTo(obj, point.x, point.y)
 92            else:
 93                if rotation:
 94                    assert pp.raw.FPDFPath_LineTo(obj, height - point.y, point.x)
 95                else:
 96                    assert pp.raw.FPDFPath_LineTo(obj, point.x, point.y)
 97        pp.raw.FPDFPage_InsertObject(new_page, obj)
 98
 99    for bbox, _ in page.graphic_clusters():
100        _rect(new_page, rotation, bbox, width=2, stroke=0x00FFFF)
101
102    for link in page.objlinks:
103        _rect(new_page, rotation, link.bbox, width=0.75, stroke=0x9ACD32)
104
105    for link in page.weblinks:
106        for bbox in link.bboxes:
107            _rect(new_page, rotation, bbox, width=0.75, stroke=0x00FF00)
108
109    for char in page.chars:
110        color = 0x0000FF
111        if char.bbox.width:
112            _rect(new_page, rotation, char.bbox, width=0.5, stroke=0xFF0000)
113            _vline(
114                new_page,
115                rotation,
116                char.bbox.midpoint.x,
117                char.bbox.midpoint.y - 1,
118                char.bbox.midpoint.y + 1,
119                width=0.25,
120                stroke=0xFF0000,
121            )
122            _hline(
123                new_page,
124                rotation,
125                char.bbox.midpoint.y,
126                char.bbox.midpoint.x - 1,
127                char.bbox.midpoint.x + 1,
128                width=0.25,
129                stroke=0xFF0000,
130            )
131            color = 0x000000
132        _vline(new_page, rotation, char.origin.x, char.origin.y - 1, char.origin.y + 1, width=0.25, stroke=color)
133        _hline(new_page, rotation, char.origin.y, char.origin.x - 1, char.origin.x + 1, width=0.25, stroke=color)
134
135    assert pp.raw.FPDFPage_GenerateContent(new_page)
136    pp.raw.FPDF_ClosePage(new_page)
137    return new_doc

 34class Document(pp.PdfDocument):
 35    """
 36    The PDF document is the root of the entire data structure and provides
 37    access to PDF metadata, the table of contents, as well as individual
 38    pages.
 39
 40    You should extend from this class for a specific vendor to provide the
 41    correct page class from `page()` function.
 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            clength = ctypes.c_long()
 69            pp.raw.FPDF_GetNamedDest(self, ii, None, clength)
 70            cbuffer = ctypes.create_string_buffer(clength.value)
 71            dest = pp.raw.FPDF_GetNamedDest(self, ii, cbuffer, clength)
 72            name = cbuffer.raw[: clength.value].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[_OutlineItem]:
 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            dest = toc.get_dest()
 87            last_page_index = (dest and dest.get_index()) or last_page_index
 88            tocs.add(_OutlineItem(toc.level, toc.get_title(), last_page_index))
 89        return list(sorted(list(tocs), key=lambda o: (o.page_index, o.level, o.title)))
 90
 91    @cached_property
 92    def identifier_permanent(self) -> str:
 93        """The permanent file identifier."""
 94        return self.get_identifier(pp.raw.FILEIDTYPE_PERMANENT)
 95
 96    @cached_property
 97    def identifier_changing(self) -> str:
 98        """The changing file identifier."""
 99        return self.get_identifier(pp.raw.FILEIDTYPE_CHANGING)
100
101    @cached_property
102    def page_count(self) -> int:
103        """The number of pages in the document."""
104        return pp.raw.FPDF_GetPageCount(self)
105
106    @cache
107    def page(self, index: int) -> Page:
108        """
109        :param index: 0-indexed page number.
110        :return: the page object for the index.
111        """
112        assert index < self.page_count
113        return Page(self, index)
114
115    def pages(self, numbers: Iterable[int] = None) -> Iterator[Page]:
116        """
117        :param numbers: an iterable range of page numbers (0-indexed!).
118                        If `None`, then the whole page range is used.
119        :return: yields each page in the range.
120        """
121        if numbers is None:
122            numbers = range(self.page_count)
123        for ii in numbers:
124            if 0 <= ii < self.page_count:
125                yield self.page(ii)
126
127    def __repr__(self) -> str:
128        return f"Doc({self.name})"

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

 14class Character:
 15    """
 16    Each character on the PDF page is represented by a character object,
 17    describing exactly where and how to render the associated glyph.
 18
 19    While there are font flags, PDF files typically use entirely different fonts
 20    to render normal, bold, and italic characters.
 21
 22    The character's loose bounding box may not always be available, since it
 23    must be explicitly provided by the font. The tight bounding box is only
 24    available as long as the glyph is renderable, so a space character may have
 25    a loose, but not a tight bounding box, or none at all.
 26    """
 27
 28    class RenderMode(Enum):
 29        """Tells the PDF viewer how to render this character glyph."""
 30
 31        UNKNOWN = -1
 32        FILL = 0
 33        STROKE = 1
 34        FILL_STROKE = 2
 35        INVISIBLE = 3
 36        FILL_CLIP = 4
 37        STROKE_CLIP = 5
 38        FILL_STROKE_CLIP = 6
 39        CLIP = 7
 40
 41    def __init__(self, page: "modm_data.pdf.page.Page", index: int):  # noqa: F821
 42        """
 43        :param page: The page containing the character.
 44        :param index: The index of the character.
 45        """
 46        self._page = page
 47        self._text = page._text
 48        self._index = index
 49        self._font = None
 50        self._rotation = int(math.degrees(pp.raw.FPDFText_GetCharAngle(self._text, self._index)))
 51
 52        self.unicode: int = pp.raw.FPDFText_GetUnicode(self._text, self._index)
 53        """The unicode value of the character."""
 54        self.objlink: "modm_data.pdf.link.ObjLink" = None  # noqa: F821
 55        """The object link of this character or `None`"""
 56        self.weblink: "modm_data.pdf.link.WebLink" = None  # noqa: F821
 57        """The web link of this character or `None`"""
 58
 59        bbox = Rectangle(*self._loose_charbox())
 60        if self._page.rotation:
 61            bbox = Rectangle(bbox.p0.y, self._page.height - bbox.p1.x, bbox.p1.y, self._page.height - bbox.p0.x)
 62        self._bbox = bbox
 63
 64    def _loose_charbox(self) -> tuple[float, float, float, float]:
 65        # Newer pdfium computes the loose box from the real font ascent and
 66        # descent, which makes it ~10% taller than the font size. All layout
 67        # heuristics in pdf2html are tuned to the previous definition, where
 68        # the box is exactly one font size tall and one advance width wide, and
 69        # collapses for rotated characters (see `Page._fix_bboxes()`).
 70        # The single precision rounding is part of that definition, since line
 71        # heights are compared for equality when merging lines.
 72        left, bottom, right, top = self._text.get_charbox(self._index, loose=True)
 73        obj = pp.raw.FPDFText_GetTextObject(self._text, self._index)
 74        size = pp.raw.FPDFText_GetFontSize(self._text, self._index)
 75        if not obj or not size:
 76            return left, bottom, right, top
 77        font = pp.raw.FPDFTextObj_GetFont(obj)
 78        ascent, descent, width = ctypes.c_float(), ctypes.c_float(), ctypes.c_float()
 79        pp.raw.FPDFFont_GetAscent(font, 1000, ascent)
 80        pp.raw.FPDFFont_GetDescent(font, 1000, descent)
 81        if ascent.value == descent.value:
 82            return left, bottom, right, top
 83
 84        def _f32(value: float) -> float:
 85            return ctypes.c_float(value).value
 86
 87        matrix = pp.raw.FS_MATRIX()
 88        x, y = ctypes.c_double(), ctypes.c_double()
 89        assert pp.raw.FPDFText_GetMatrix(self._text, self._index, matrix)
 90        assert pp.raw.FPDFText_GetCharOrigin(self._text, self._index, x, y)
 91        scale = _f32(_f32(matrix.a * size) / (ascent.value - descent.value))
 92        bottom = _f32(y.value + _f32(descent.value * scale))
 93        top = _f32(y.value + _f32(ascent.value * scale))
 94        if pp.raw.FPDFText_IsGenerated(self._text, self._index):
 95            return x.value, bottom, x.value, top
 96        # The width lookup fails for characters without a reverse unicode
 97        # mapping, in which case the new left and right bounds are close enough.
 98        if pp.raw.FPDFFont_GetGlyphWidth(font, self.unicode, size, width) and width.value:
 99            left, right = x.value, _f32(x.value + _f32(matrix.a * width.value))
100        return left, bottom, right, top
101
102    def generated_space(self) -> "Character":
103        """
104        :return: A zero-sized space character located at the origin of this
105                 character, like the ones pdfium generates for visual gaps.
106        """
107        space = copy.copy(self)
108        space.__dict__ = {k: v for k, v in self.__dict__.items() if k.startswith("_") or k.endswith("link")}
109        space.unicode = 0x20
110        space._bbox = space.tbbox = Rectangle(self.origin.x, self.origin.y, self.origin.x, self.origin.y)
111        space.origin = self.origin
112        return space
113
114    def _font_flags(self) -> tuple[str, int]:
115        if self._font is None:
116            font = ctypes.create_string_buffer(255)
117            flags = ctypes.c_int()
118            pp.raw.FPDFText_GetFontInfo(self._text, self._index, font, 255, flags)
119            self._font = (font.value.decode("utf-8"), flags.value)
120        return self._font
121
122    @property
123    def char(self) -> str:
124        """The printable string of the unicode value."""
125        char = chr(self.unicode)
126        return char if char.isprintable() else ""
127
128    @cached_property
129    def origin(self) -> Point:
130        """The origin of the character."""
131        x, y = ctypes.c_double(), ctypes.c_double()
132        assert pp.raw.FPDFText_GetCharOrigin(self._text, self._index, x, y)
133        if self._page.rotation:
134            return Point(y.value, self._page.height - x.value)
135        return Point(x.value, y.value)
136
137    @cached_property
138    def width(self) -> float:
139        """The width of the character's bounding box."""
140        if self.rotation:
141            return self.bbox.height
142        return self.bbox.width
143
144    @cached_property
145    def height(self) -> float:
146        """The height of the character's bounding box."""
147        if self.rotation:
148            return self.bbox.width
149        return self.bbox.height
150
151    @cached_property
152    def tbbox(self) -> Rectangle:
153        """The tight bounding box of the character."""
154        tbbox = Rectangle(*self._text.get_charbox(self._index))
155        if self._page.rotation:
156            tbbox = Rectangle(tbbox.p0.y, self._page.height - tbbox.p1.x, tbbox.p1.y, self._page.height - tbbox.p0.x)
157        return tbbox
158
159    @property
160    def bbox(self) -> Rectangle:
161        """
162        The loose bounding box of the character.
163        .. note::
164            If the loose bounding box is not available, the tight bounding box
165            is used instead.
166        """
167        if not self._bbox.width or not self._bbox.height:
168            return self.tbbox
169        return self._bbox
170
171    @cached_property
172    def twidth(self) -> float:
173        """The width of the character's tight bounding box."""
174        return self.tbbox.width
175
176    @cached_property
177    def theight(self) -> float:
178        """The height of the character's tight bounding box."""
179        return self.tbbox.height
180
181    @cached_property
182    def render_mode(self) -> RenderMode:
183        """The render mode of the character."""
184        return Character.RenderMode(
185            pp.raw.FPDFTextObj_GetTextRenderMode(pp.raw.FPDFText_GetTextObject(self._text, self._index))
186        )
187
188    @cached_property
189    def rotation(self) -> int:
190        """The rotation of the character in degrees modulo 360."""
191        # Special case for vertical text in rotated pages
192        if self._page.rotation == 90 and self._rotation == 0 and self.unicode not in {0x20, 0xA, 0xD}:
193            return 90
194        if self._page.rotation and self._rotation:
195            return (self._page.rotation + self._rotation) % 360
196        return self._rotation
197
198    @cached_property
199    def size(self) -> float:
200        """The font size of the character."""
201        return pp.raw.FPDFText_GetFontSize(self._text, self._index)
202
203    @cached_property
204    def weight(self) -> int:
205        """The font weight of the character."""
206        return pp.raw.FPDFText_GetFontWeight(self._text, self._index)
207
208    @cached_property
209    def fill(self) -> int:
210        """The fill color of the character."""
211        r, g, b, a = ctypes.c_uint(), ctypes.c_uint(), ctypes.c_uint(), ctypes.c_uint()
212        pp.raw.FPDFText_GetFillColor(self._text, self._index, r, g, b, a)
213        return r.value << 24 | g.value << 16 | b.value << 8 | a.value
214
215    @cached_property
216    def stroke(self) -> int:
217        """The stroke color of the character."""
218        r, g, b, a = ctypes.c_uint(), ctypes.c_uint(), ctypes.c_uint(), ctypes.c_uint()
219        pp.raw.FPDFText_GetStrokeColor(self._text, self._index, r, g, b, a)
220        return r.value << 24 | g.value << 16 | b.value << 8 | a.value
221
222    @cached_property
223    def font(self) -> str:
224        """The font name of the character."""
225        return self._font_flags()[0]
226
227    @cached_property
228    def flags(self) -> int:
229        """The font flags of the character."""
230        return self._font_flags()[1]
231
232    def descr(self) -> str:
233        """Human-readable description of the character for debugging."""
234        char = chr(self.unicode)
235        if not char.isprintable():
236            char = hex(self.unicode)
237        return (
238            f"Chr({char}, {self.size}, {self.weight}, {self.rotation}, "
239            f"{self.render_mode}, {self.font}, {hex(self.flags)}, "
240            f"{self.fill}, {self.stroke}, {repr(self.bbox)})"
241        )
242
243    def __str__(self) -> str:
244        return self.char
245
246    def __repr__(self) -> str:
247        char = chr(self.unicode)
248        escape = {0xA: "\\n", 0xD: "\\r", 0x9: "\\t", 0x20: "␣"}
249        char = escape.get(self.unicode, char if char.isprintable() else hex(self.unicode))
250        return char