Source code

Download source archive ↓

src/pypdf/_text_extraction/_text_extractor.py

1# Copyright (c) 2006, Mathieu Fenniak
2# Copyright (c) 2007, Ashish Kulkarni <kulkarni.ashish@gmail.com>
3#
4# All rights reserved.
5#
6# Redistribution and use in source and binary forms, with or without
7# modification, are permitted provided that the following conditions are
8# met:
9#
10# * Redistributions of source code must retain the above copyright notice,
11# this list of conditions and the following disclaimer.
12# * Redistributions in binary form must reproduce the above copyright notice,
13# this list of conditions and the following disclaimer in the documentation
14# and/or other materials provided with the distribution.
15# * The name of the author may not be used to endorse or promote products
16# derived from this software without specific prior written permission.
17#
18# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
19# AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
20# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
21# ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
22# LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
23# CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
24# SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
25# INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
26# CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
27# ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
28# POSSIBILITY OF SUCH DAMAGE.
29
30from collections.abc import Callable
31from typing import Any
32
33from .._codecs import encoding_dict_from_named_encoding
34from ..generic import DictionaryObject, TextStringObject
35from ..generic._font import Font, FontDescriptor
36from . import OrientationNotFoundError, crlf_space_check, get_display_str, get_text_operands, mult
37
38
39def _get_number_operand(operands: list[Any], index: int, default: float) -> float:
40    """Return the operand at index as a float, or default if it is missing or not a number."""
41    if index < len(operands) and isinstance(operands[index], (int, float)):
42        return float(operands[index])
43    return default
44
45
46class TextExtraction:
47    """
48    A class to handle PDF text extraction operations.
49
50    This class encapsulates all the state and operations needed for extracting
51    text from PDF content streams, replacing the nested functions and nonlocal
52    variables in the original implementation.
53    """
54
55    def __init__(self) -> None:
56        # Text extraction state variables
57        self.cm_matrix: list[float] = [1.0, 0.0, 0.0, 1.0, 0.0, 0.0]
58        self.tm_matrix: list[float] = [1.0, 0.0, 0.0, 1.0, 0.0, 0.0]
59        self.cm_stack: list[
60            tuple[
61                list[float],
62                DictionaryObject | None,
63                Font,
64                float,
65                float,
66                float,
67                float,
68                float,
69            ]
70        ] = []
71
72        # Store the last modified matrices; can be an intermediate position
73        self.cm_prev: list[float] = [1.0, 0.0, 0.0, 1.0, 0.0, 0.0]
74        self.tm_prev: list[float] = [1.0, 0.0, 0.0, 1.0, 0.0, 0.0]
75
76        # Store the position at the beginning of building the text
77        self.memo_cm: list[float] = [1.0, 0.0, 0.0, 1.0, 0.0, 0.0]
78        self.memo_tm: list[float] = [1.0, 0.0, 0.0, 1.0, 0.0, 0.0]
79
80        self.char_scale = 1.0
81        self.space_scale = 1.0
82        self.char_spacing = 0.0
83        self._space_width: float = 500.0  # will be set correctly at first Tf
84        # Right after a Tf, a word gap is a gap in either the previous or the new font.
85        self._previous_font_space: float | None = None
86        self._actual_str_size: dict[str, float] = {
87            "str_widths": 0.0,
88            "str_height": 0.0,
89        }  # will be set to string length calculation result
90        self.TL = 0.0
91        self.font_size = 12.0  # init just in case of
92        # (axis index, min, max) of baselines kept on the current extracted line.
93        self._line_span: tuple[int, float, float] | None = None
94
95        # Text extraction variables
96        self.text: str = ""
97        self.output: str = ""
98        self.rtl_dir: bool = False  # right-to-left
99        self.font_resource: DictionaryObject | None = None
100        self.font = Font(
101            name = "NotInitialized",
102            sub_type="Unknown",
103            encoding=encoding_dict_from_named_encoding("cp1252"),  # WinAnsiEncoding
104            font_descriptor=FontDescriptor(),
105            )
106        self.orientations: tuple[int, ...] = (0, 90, 180, 270)
107        self.visitor_text: Callable[[Any, Any, Any, Any, Any], None] | None = None
108        self.font_resources: dict[str, DictionaryObject] = {}
109        self.fonts: dict[str, Font] = {}
110
111        self.operation_handlers = {
112            b"BT": self._handle_bt,
113            b"ET": self._handle_et,
114            b"q": self._handle_save_graphics_state,
115            b"Q": self._handle_restore_graphics_state,
116            b"cm": self._handle_cm,
117            b"Tz": self._handle_tz,
118            b"Tc": self._handle_tc,
119            b"Tw": self._handle_tw,
120            b"TL": self._handle_tl,
121            b"Tf": self._handle_tf,
122            b"Td": self._handle_td,
123            b"Tm": self._handle_tm,
124            b"T*": self._handle_t_star,
125            b"Tj": self._handle_tj_operation,
126        }
127
128    def initialize_extraction(
129        self,
130        orientations: tuple[int, ...] = (0, 90, 180, 270),
131        visitor_text: Callable[[Any, Any, Any, Any, Any], None] | None = None,
132        font_resources: dict[str, DictionaryObject] | None = None,
133        fonts: dict[str, Font] | None = None
134    ) -> None:
135        """Initialize the extractor with extraction parameters."""
136        self.orientations = orientations
137        self.visitor_text = visitor_text
138        self.font_resources = font_resources or {}
139        self.fonts = fonts or {}
140
141        # Reset state
142        self.text = ""
143        self.output = ""
144        self.rtl_dir = False
145        self._line_span = None
146
147    def compute_str_widths(self, str_widths: float) -> float:
148        return str_widths / 1000
149
150    def process_operation(self, operator: bytes, operands: list[Any]) -> None:
151        if operator in self.operation_handlers:
152            handler = self.operation_handlers[operator]
153            str_widths = handler(operands)
154
155            # Post-process operations that affect text positioning
156            if operator in {b"Td", b"Tm", b"T*", b"Tj"}:
157                self._post_process_text_operation(str_widths or 0.0)
158
159    def process_tj_offset(self, offset: float, space_width: float) -> None:
160        """Add a space for a word gap in a TJ array and count the offset in the text width."""
161        # The offset moved the pen, so it counts towards the width and the added space does not.
162        str_widths = self._actual_str_size["str_widths"] - offset * self.font_size
163        # A Tf just before this TJ has already moved the text to the output.
164        previous = self.text or self.output
165        # A positive offset moves the next glyph back (kerning), so only a negative one can be a gap.
166        if -offset >= space_width and previous and previous[-1] not in " \n":
167            self.process_operation(b"Tj", [" "])
168        self._actual_str_size["str_widths"] = str_widths
169
170    def _post_process_text_operation(self, str_widths: float) -> None:
171        """Handle common post-processing for text positioning operations."""
172        text_was_empty = self.text == ""
173        space_width = self.font_size * self._space_width
174        if self._previous_font_space is not None:
175            space_width = min(space_width, self._previous_font_space)
176        try:
177            self.text, self.output, self.cm_prev, self.tm_prev, self._line_span = crlf_space_check(
178                self.text,
179                (self.cm_prev, self.tm_prev),
180                (self.cm_matrix, self.tm_matrix),
181                (self.memo_cm, self.memo_tm),
182                self.font_resource,
183                self.orientations,
184                self.output,
185                self.font_size,
186                self.visitor_text,
187                str_widths,
188                self.compute_str_widths(space_width),
189                self._actual_str_size["str_height"],
190                self._line_span,
191            )
192            if text_was_empty or self.text == "":
193                self.memo_cm = self.cm_matrix.copy()
194                self.memo_tm = self.tm_matrix.copy()
195        except OrientationNotFoundError:
196            pass
197
198    def _handle_tj(
199        self,
200        text: str,
201        operands: list[str | TextStringObject],
202        cm_matrix: list[float],
203        tm_matrix: list[float],
204        font_resource: DictionaryObject | None,
205        font: Font,
206        orientations: tuple[int, ...],
207        font_size: float,
208        rtl_dir: bool,
209        visitor_text: Callable[[Any, Any, Any, Any, Any], None] | None,
210        actual_str_size: dict[str, float],
211    ) -> tuple[str, bool, dict[str, float]]:
212        text_operands, is_str_operands, font_widths = get_text_operands(
213            operands, cm_matrix, tm_matrix, font, orientations
214        )
215        if is_str_operands:
216            text += text_operands
217        else:
218            text, rtl_dir, completed = get_display_str(
219                text,
220                cm_matrix,
221                tm_matrix,  # text matrix
222                font_resource,
223                font,
224                text_operands,
225                font_size,
226                rtl_dir,
227                visitor_text,
228            )
229            self.output += completed
230        # Tc is in text space units and applies to every glyph.
231        actual_str_size["str_widths"] += font_widths * font_size + 1000 * self.char_spacing * len(text_operands)
232        actual_str_size["str_height"] = font_size
233        return text, rtl_dir, actual_str_size
234
235    def _flush_text(self) -> None:
236        """Flush accumulated text to output and call visitor if present."""
237        self.output += self.text
238        if self.visitor_text is not None:
239            self.visitor_text(self.text, self.memo_cm, self.memo_tm, self.font_resource, self.font_size)
240        self.text = ""
241        self.memo_cm = self.cm_matrix.copy()
242        self.memo_tm = self.tm_matrix.copy()
243
244    # Operation handlers
245
246    def _handle_bt(self, operands: list[Any]) -> None:
247        """Handle BT (Begin Text) operation - Table 5.4 page 405."""
248        self.tm_matrix = [1.0, 0.0, 0.0, 1.0, 0.0, 0.0]
249        self._flush_text()
250
251    def _handle_et(self, operands: list[Any]) -> None:
252        """Handle ET (End Text) operation - Table 5.4 page 405."""
253        self._flush_text()
254
255    def _handle_save_graphics_state(self, operands: list[Any]) -> None:
256        """Handle q (Save graphics state) operation - Table 4.7 page 219."""
257        self.cm_stack.append(
258            (
259                self.cm_matrix,
260                self.font_resource,
261                self.font,
262                self.font_size,
263                self.char_scale,
264                self.space_scale,
265                self.char_spacing,
266                self.TL,
267            )
268        )
269
270    def _handle_restore_graphics_state(self, operands: list[Any]) -> None:
271        """Handle Q (Restore graphics state) operation - Table 4.7 page 219."""
272        try:
273            (
274                self.cm_matrix,
275                self.font_resource,
276                self.font,
277                self.font_size,
278                self.char_scale,
279                self.space_scale,
280                self.char_spacing,
281                self.TL,
282            ) = self.cm_stack.pop()
283        except MemoryError:  # pragma: no cover  # TODO: BLE001
284            raise
285        except Exception:
286            self.cm_matrix = [1.0, 0.0, 0.0, 1.0, 0.0, 0.0]
287
288    def _handle_cm(self, operands: list[Any]) -> None:
289        """Handle cm (Modify current matrix) operation - Table 4.7 page 219."""
290        self.output += self.text
291        if self.visitor_text is not None:
292            self.visitor_text(self.text, self.memo_cm, self.memo_tm, self.font_resource, self.font_size)
293        self.text = ""
294        try:
295            self.cm_matrix = mult([float(operand) for operand in operands[:6]], self.cm_matrix)
296        except MemoryError:  # pragma: no cover  # TODO: BLE001
297            raise
298        except Exception:
299            self.cm_matrix = [1.0, 0.0, 0.0, 1.0, 0.0, 0.0]
300        self.memo_cm = self.cm_matrix.copy()
301        self.memo_tm = self.tm_matrix.copy()
302
303    def _handle_tz(self, operands: list[Any]) -> None:
304        """Handle Tz (Set horizontal text scaling) operation - Table 5.2 page 398."""
305        self.char_scale = _get_number_operand(operands, 0, 100.0) / 100
306
307    def _handle_tc(self, operands: list[Any]) -> None:
308        """Handle Tc (Set character spacing) operation - Table 5.2 page 398."""
309        self.char_spacing = _get_number_operand(operands, 0, 0.0)
310
311    def _handle_tw(self, operands: list[Any]) -> None:
312        """Handle Tw (Set word spacing) operation - Table 5.2 page 398."""
313        self.space_scale = 1.0 + _get_number_operand(operands, 0, 0.0)
314
315    def _handle_tl(self, operands: list[Any]) -> None:
316        """Handle TL (Set Text Leading) operation - Table 5.2 page 398."""
317        # The leading is measured in unscaled text space units (PDF 32000-1, 9.3.5)
318        # and T* applies the text matrix to it, so it must not be scaled here.
319        self.TL = _get_number_operand(operands, 0, 0.0)
320
321    def _handle_tf(self, operands: list[Any]) -> None:
322        """Handle Tf (Set font size) operation - Table 5.2 page 398."""
323        if self.text != "":
324            self._previous_font_space = self.font_size * self._space_width
325            self.output += self.text  # .translate(cmap)
326            if self.visitor_text is not None:
327                self.visitor_text(self.text, self.memo_cm, self.memo_tm, self.font_resource, self.font_size)
328        self.text = ""
329        self.memo_cm = self.cm_matrix.copy()
330        self.memo_tm = self.tm_matrix.copy()
331        try:
332            self.font_resource = self.font_resources[operands[0]]
333            self.font = self.fonts[operands[0]]
334        except (KeyError, IndexError):  # font not found / operand missing
335            self.font_resource = None
336            font_descriptor = FontDescriptor()
337            self.font = Font(
338                "Unknown",
339                space_width=250,
340                encoding=dict.fromkeys(range(256), "�"),
341                font_descriptor=font_descriptor,
342                character_map={},
343            )
344
345        self._space_width = self.font.space_width / 2  # Actually the width of _half_ a space...
346        try:
347            self.font_size = float(operands[1])
348        except MemoryError:  # pragma: no cover  # TODO: BLE001
349            raise
350        except Exception:
351            pass  # keep previous size
352
353    def _handle_td(self, operands: list[Any]) -> float:
354        """Handle Td (Move text position) operation - Table 5.5 page 406."""
355        # A special case is a translating only tm:
356        # tm = [1, 0, 0, 1, e, f]
357        # i.e. tm[4] += tx, tm[5] += ty.
358        tx = _get_number_operand(operands, 0, 0.0)
359        ty = _get_number_operand(operands, 1, 0.0)
360        self.tm_matrix[4] += tx * self.tm_matrix[0] + ty * self.tm_matrix[2]
361        self.tm_matrix[5] += tx * self.tm_matrix[1] + ty * self.tm_matrix[3]
362        str_widths = self.compute_str_widths(self._actual_str_size["str_widths"])
363        self._actual_str_size["str_widths"] = 0.0
364        return str_widths
365
366    def _handle_tm(self, operands: list[Any]) -> float:
367        """Handle Tm (Set text matrix) operation - Table 5.5 page 406."""
368        try:
369            tm_matrix = [float(operand) for operand in operands[:6]]
370        except (TypeError, ValueError):
371            tm_matrix = []
372        # Fall back to the identity matrix when Tm carries the wrong number of
373        # operands, mirroring _handle_cm, so the text matrix stays a six-element
374        # list and later positioning operators do not read past its end.
375        self.tm_matrix = tm_matrix if len(tm_matrix) == 6 else [1.0, 0.0, 0.0, 1.0, 0.0, 0.0]
376        str_widths = self.compute_str_widths(self._actual_str_size["str_widths"])
377        self._actual_str_size["str_widths"] = 0.0
378        return str_widths
379
380    def _handle_t_star(self, operands: list[Any]) -> float:
381        """Handle T* (Move to next line) operation - Table 5.5 page 406."""
382        self.tm_matrix[4] -= self.TL * self.tm_matrix[2]
383        self.tm_matrix[5] -= self.TL * self.tm_matrix[3]
384        str_widths = self.compute_str_widths(self._actual_str_size["str_widths"])
385        self._actual_str_size["str_widths"] = 0.0
386        return str_widths
387
388    def _handle_tj_operation(self, operands: list[Any]) -> float:
389        """Handle Tj (Show text) operation - Table 5.5 page 406."""
390        if not operands or not isinstance(operands[0], (str, bytes)):
391            return 0.0
392        self._previous_font_space = None
393        self.text, self.rtl_dir, self._actual_str_size = self._handle_tj(
394            self.text,
395            operands,
396            self.cm_matrix,
397            self.tm_matrix,
398            self.font_resource,
399            self.font,
400            self.orientations,
401            self.font_size,
402            self.rtl_dir,
403            self.visitor_text,
404            self._actual_str_size,
405        )
406        return 0.0  # str_widths will be handled in post-processing