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