Class: Rpdfium::Page

Inherits:
Object
  • Object
show all
Defined in:
lib/rpdfium/page.rb

Overview

Page wrapper. Lazy-loads the TextPage. All returned coordinates are in the page’s “top-down” space: (0,0) is at the top left, x grows toward the right, y toward the bottom. PDFium uses “bottom-up” — the conversion happens here once and for all.

Constant Summary collapse

BOX_FUNCTIONS = 
{
  media: :FPDFPage_GetMediaBox,
  crop: :FPDFPage_GetCropBox,
  bleed: :FPDFPage_GetBleedBox,
  trim: :FPDFPage_GetTrimBox,
  art: :FPDFPage_GetArtBox
}.freeze
NUMERIC_PUNCT =

True if the pair (prev_char, curr_char) is a “numeric” context: digit-punctuation, punctuation-digit, or digit-digit. In these cases a modest gap is probably kerning internal to the number, not a word boundary. A higher threshold avoids splitting numbers like “2.895,26” into “2 . 895 , 26”.

%w[. , ].freeze
TEXT_OBJ_INITIAL_BUF_BYTES =

Initial buffer size for FPDFTextObj_GetText: 256 bytes = 128 UTF-16 chars. Empirically sufficient for ~99% of real text objects (single words or short phrases). When a text obj is larger, we fall back to the correct probe-then-fetch.

256

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(document, index) ⇒ Page

Returns a new instance of Page.

Raises:



11
12
13
14
15
16
17
18
19
20
21
22
23
24
 
# File 'lib/rpdfium/page.rb', line 11

def initialize(document, index)
  @document = document
  @index    = index
  handle    = Raw.FPDF_LoadPage(document.handle, index)
  raise PageError, "Could not load page #{index}" if handle.null?

  @text_page = nil
  # State shared with the finalizer: idempotent on close, survives GC
  # without making a double FPDF_ClosePage call. Holding a reference to
  # @document guarantees that the Document is not collected before the
  # Page (FPDF_ClosePage requires the Document still alive).
  @state = { handle: handle, closed: false }
  ObjectSpace.define_finalizer(self, self.class.finalizer(@state))
end

Instance Attribute Details

#document ⇒ Object (readonly)

Returns the value of attribute document.



9
10
11
 
# File 'lib/rpdfium/page.rb', line 9

def document
  @document
end

#index ⇒ Object (readonly)

Returns the value of attribute index.



9
10
11
 
# File 'lib/rpdfium/page.rb', line 9

def index
  @index
end

Class Method Details

.finalizer(state) ⇒ Object 



26
27
28
29
30
31
32
33
34
 
# File 'lib/rpdfium/page.rb', line 26

def self.finalizer(state)
  proc do
    next if state[:closed]
    next if state[:handle].null?

    Raw.FPDF_ClosePage(state[:handle])
    state[:closed] = true
  end
end

Instance Method Details

#annotations ⇒ Object

Annotations =====


1235
1236
1237
1238
 
# File 'lib/rpdfium/page.rb', line 1235

def annotations
  n = Raw.FPDFPage_GetAnnotCount(@state[:handle])
  Array.new(n) { |i| Annotation.new(self, i) }
end

#apply_page_rotation_to_char(rotation, raw_w, raw_h, x0, x1, y_top, y_bot, origin_x, origin_y) ⇒ Object

Applies the page rotation to a char’s coordinates.

Input: raw PDFium coords (bottom-up, pre-rotation) of a bbox ‘[x0, x1, y_top, y_bot]` (with y_top > y_bot because bottom-up) and of an origin point.

Output: top-down coords in the post-rotation page system, in the standard rpdfium convention: ‘[x0, x1, top, bottom]` with `top < bottom`. Consistent with pdfplumber.

PDFium convention: GetRotation = N means the displayed page is rotated by N*90° clockwise relative to the raw content stream system. PDFium returns the coords in the raw system; we apply the rotation to align with the rendering.

Case 0°: identity + bottom-up→top-down. Case 90° CW: a bbox wide in x becomes tall in y. The raw x_min (left)

coincides with the top of the post-rotation system.

Case 180°: flips both axes. Case 270° CW: a bbox wide in x becomes tall in y, but flipped vertically.



517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
 
# File 'lib/rpdfium/page.rb', line 517

def apply_page_rotation_to_char(rotation, raw_w, raw_h,
                                 x0, x1, y_top, y_bot,
                                 origin_x, origin_y)
  case rotation
  when 0, nil
    # No rotation. Standard bottom-up → top-down.
    # page_h_post == raw_h.
    [x0, x1, raw_h - y_top, raw_h - y_bot,
     origin_x, raw_h - origin_y]

  when 90
    # 90° CW. Post-rotation dimensions: w=raw_h, h=raw_w.
    # Transform: x_post = y_raw, y_post = raw_w - x_raw (bottom-up).
    # In top-down: top = x_min_raw, bottom = x_max_raw.
    new_x0 = y_bot   # small y_raw → small x_post
    new_x1 = y_top   # large y_raw → large x_post
    new_top    = x0  # small x_raw → small top (high)
    new_bottom = x1  # large x_raw → large bottom (low)
    new_ox = origin_y
    new_oy = origin_x       # top-down origin_y = x_raw
    [new_x0, new_x1, new_top, new_bottom, new_ox, new_oy]

  when 180
    # 180°. Post-rotation dimensions: unchanged (raw_w × raw_h).
    # Transform: x_post = raw_w - x_raw, y_post = raw_h - y_raw.
    # In top-down: top = y_bot_raw, bottom = y_top_raw.
    new_x0 = raw_w - x1
    new_x1 = raw_w - x0
    new_top    = y_bot   # raw bottom → td top (high)
    new_bottom = y_top   # raw top → td bottom (low)
    new_ox = raw_w - origin_x
    # Origin in top-down post-180°: the y axis is already flipped by
    # the rotation, so origin_y carries over unchanged.
    new_oy = origin_y
    [new_x0, new_x1, new_top, new_bottom, new_ox, new_oy]

  when 270
    # 270° CW (= 90° CCW). Post-rotation dimensions: w=raw_h, h=raw_w.
    # Transform: x_post = raw_h - y_raw, y_post = x_raw (bottom-up).
    # In top-down: top = raw_w - x_max_raw, bottom = raw_w - x_min_raw.
    new_x0 = raw_h - y_top  # large y → small x_post
    new_x1 = raw_h - y_bot
    new_top    = raw_w - x1
    new_bottom = raw_w - x0
    new_ox = raw_h - origin_y
    new_oy = raw_w - origin_x
    [new_x0, new_x1, new_top, new_bottom, new_ox, new_oy]

  else
    # Non-standard rotation (not a multiple of 90°): fall back to
    # the pre-rotation behavior. This should never happen for
    # well-formed PDFs.
    [x0, x1, raw_h - y_top, raw_h - y_bot,
     origin_x, raw_h - origin_y]
  end
end

#artbox ⇒ Object 



94
 
# File 'lib/rpdfium/page.rb', line 94

def artbox;   box_to_topdown(box(:art));   end

#best_reference_width(a, b) ⇒ Object

Returns the “reference” width for computing the gap/width ratio. Prefers the advance (more stable than the bbox for chars with post-applied kerning). If either char lacks an advance, falls back to the max of the bbox widths.



277
278
279
280
281
282
283
284
 
# File 'lib/rpdfium/page.rb', line 277

def best_reference_width(a, b)
  a_adv = a[:advance]
  b_adv = b[:advance]

  return [a_adv, b_adv].max if a_adv && b_adv

  [(a[:x1] - a[:x0]), (b[:x1] - b[:x0])].max
end

#bleedbox ⇒ Object 



92
 
# File 'lib/rpdfium/page.rb', line 92

def bleedbox; box_to_topdown(box(:bleed)); end

#box(kind = :crop) ⇒ Object 



62
63
64
65
66
67
68
69
70
71
72
 
# File 'lib/rpdfium/page.rb', line 62

def box(kind = :crop)
  fn = BOX_FUNCTIONS[kind] or raise ArgumentError, "Unknown box: #{kind}"
  l = FFI::MemoryPointer.new(:float)
  b = FFI::MemoryPointer.new(:float)
  r = FFI::MemoryPointer.new(:float)
  t = FFI::MemoryPointer.new(:float)
  return nil if Raw.send(fn, @state[:handle], l, b, r, t) == 0

  { left: l.read_float, bottom: b.read_float,
    right: r.read_float, top: t.read_float }
end

#build_synthetic_space(prev, c) ⇒ Object 



286
287
288
289
290
291
292
293
294
295
296
297
 
# File 'lib/rpdfium/page.rb', line 286

def build_synthetic_space(prev, c)
  {
    char: ' ', codepoint: 32,
    x0: prev[:x1], x1: c[:x0],
    top: prev[:top], bottom: prev[:bottom],
    origin_x: prev[:x1], origin_y: prev[:origin_y],
    angle: 0.0, fontsize: prev[:fontsize], font: prev[:font],
    weight: prev[:weight], render_mode: nil,
    generated: true, hyphen: false, unicode_error: false,
    advance: nil, text_obj_id: nil, text_obj_ends_with_space: nil
  }
end

#chars(loose: true, inject_spaces: true, lean: false, geometry: false) ⇒ Object

Returns every char with rich metadata:

:char     string (1 codepoint)
:x0,:x1   horizontal bbox
:top,:bottom  vertical bbox (top-down: top < bottom)
:origin_x, :origin_y  glyph insertion point (top-down)
:angle    glyph rotation angle (radians)
:fontsize size in points
:font     font name (if available)
:weight   weight (e.g. 400=regular, 700=bold)
:render_mode  rendering mode (fill/stroke/invisible). Read via
              the text object that contains the char (PDFium no
              longer exposes a char-level API after chromium/6611).
              nil on old PDFium builds that do not support the
              char→object lookup.
:generated  true if inserted by PDFium (e.g. synthetic spaces)
:hyphen   true if a hyphenation hyphen
:unicode_error  true if PDFium could not map it

‘loose: true` (DEFAULT) uses FPDFText_GetLooseCharBox: all chars on the same logical line share the same vertical bbox (top/bottom), proportional to the font size rather than to the individual glyph. This is exactly the behavior of pdfminer.six/pdfplumber, and the only one that lets the midpoint test in Table#extract also capture punctuation chars (`.`, `,`) along with the numbers aligned to the baseline. With `loose: false` you get the “tight” bbox of the single glyph, useful for fine layout measurements but wrong for the table cell filter. `geometry: true` is a stronger form of `lean` reserved for the table/word pipeline: on top of `lean` it ALSO skips the per-char origin (FPDFText_GetCharOrigin) and the text-object lookup (FPDFText_GetTextObject + GetFont/GetFontSize/GetTextRenderMode/ GetText), and emits a 6-key hash (char, x0, x1, top, bottom, generated) instead of the full one. Those are exactly the fields the WordExtractor / Table pipeline reads; cutting the rest removes ~3 FFI roundtrips per char and a large amount of hash allocation, which on a page with thousands of chars is the dominant cost of extract_tables. Unlike `lean` (which keeps the full hash shape, just with nil/false metadata), `geometry` changes the hash shape, so it is NOT a drop-in for general char consumers — only for the geometry-only pipeline.



171
172
173
174
175
176
177
178
179
180
181
182
183
 
# File 'lib/rpdfium/page.rb', line 171

def chars(loose: true, inject_spaces: true, lean: false, geometry: false)
  # Cache: chars() is called once by Table#extract and then again by
  # WordExtractor (going through Extractor#page_words if
  # vertical/horizontal_strategy is :text). Each call costs O(n) FFI
  # roundtrips per char — expensive on pages with thousands of chars.
  cache_key = [loose, inject_spaces, lean, geometry]
  @chars_cache ||= {}
  return @chars_cache[cache_key] if @chars_cache.key?(cache_key)

  raw = geometry ? compute_geometry_chars(loose: loose) : compute_chars(loose: loose, lean: lean)
  result = inject_spaces ? rebuild_word_separators(raw) : raw
  @chars_cache[cache_key] = result
end

#chars_where(font: nil, height: nil, weight: nil, bbox: nil, where: nil, **char_opts) ⇒ Object

Generic char filter. Returns the chars that match ALL the specified predicates (intersection, not union).

Supported arguments:

font:   exact String, Array<String>, or Regexp
height: Float (single value), Range, Array<Float>
weight: Integer or Range
bbox:   [left, top, right, bottom] in the page's top-down coords
where:  block that receives the char hash, must return truthy

All parameters are optional; the ones passed are combined with AND.

Typically combined with WordExtractor to extract “clean” text:

data_chars = page.chars_where(font: /Courier/i)
words = Rpdfium::Util::WordExtractor.new.extract_words(data_chars)

or used as a building block for custom pipelines.



762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
 
# File 'lib/rpdfium/page.rb', line 762

def chars_where(font: nil, height: nil, weight: nil, bbox: nil, where: nil, **char_opts)
  cs = chars(**char_opts)

  cs.select do |c|
    next false if font && !font_matches?(c[:font], font)
    next false if height && !range_matches?((c[:bottom] - c[:top]), height)
    next false if weight && !range_matches?(c[:weight], weight)
    if bbox
      left, top, right, bottom = bbox
      hm = (c[:x0] + c[:x1]) / 2.0
      vm = (c[:top] + c[:bottom]) / 2.0
      next false unless hm >= left && hm < right && vm >= top && vm < bottom
    end
    next false if where && !where.call(c)
    true
  end
end

#close ⇒ Object 



1344
1345
1346
1347
1348
1349
1350
1351
1352
 
# File 'lib/rpdfium/page.rb', line 1344

def close
  return if @state[:closed]

  @text_page&.close
  Raw.FPDF_ClosePage(@state[:handle]) unless @state[:handle].null?
  @state[:handle] = FFI::Pointer::NULL
  @state[:closed] = true
  ObjectSpace.undefine_finalizer(self)
end

#compute_chars(loose:, lean: false) ⇒ Object 



300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
 
# File 'lib/rpdfium/page.rb', line 300

def compute_chars(loose:, lean: false)
  tp = text_page
  n = tp.char_count
  return [] if n.zero?

  # Page geometry after applying the PDF rotation.
  page_rotation = rotation
  raw_w, raw_h = rotated_dimensions(page_rotation)

  result = Array.new(n)

  # FFI buffers reused across all loop iterations.
  # MemoryPointer.new is non-trivial (~µs each); allocating O(n) of them
  # per char is the main cost of compute_chars after the FFI calls.
  l = FFI::MemoryPointer.new(:double)
  r = FFI::MemoryPointer.new(:double)
  b = FFI::MemoryPointer.new(:double)
  t = FFI::MemoryPointer.new(:double)
  ox = FFI::MemoryPointer.new(:double)
  oy = FFI::MemoryPointer.new(:double)
  rect = Raw::FS_RECTF.new
  font_buf = FFI::MemoryPointer.new(:uchar, 256) unless lean
  flags_buf = FFI::MemoryPointer.new(:int) unless lean
  fs_buf = FFI::MemoryPointer.new(:float)
  gw_buf = FFI::MemoryPointer.new(:float)
  matrix = Raw::FS_MATRIX.new
  text_obj_text_buf = FFI::MemoryPointer.new(:uint8, TEXT_OBJ_INITIAL_BUF_BYTES)

  text_obj_cache = {}
  tp_handle = tp.handle

  n.times do |i|
    x0, x1, y_top, y_bot = read_char_bbox(tp, i, loose, l, r, b, t, rect)
    Raw.FPDFText_GetCharOrigin(tp_handle, i, ox, oy)
    origin_x_raw = ox.read_double
    origin_y_raw = oy.read_double

    # Font name: skipped in lean mode (1 FFI call saved per char).
    font_name = nil
    unless lean
      n_bytes = Raw.FPDFText_GetFontInfo(tp_handle, i, font_buf, 256, flags_buf)
      font_name = font_buf.read_bytes(n_bytes - 1).force_encoding(Encoding::UTF_8.to_s) if n_bytes > 1
    end

    cp = Raw.FPDFText_GetUnicode(tp_handle, i)

    text_obj = begin
      Raw.FPDFText_GetTextObject(tp_handle, i)
    rescue Rpdfium::LoadError
      nil
    end

    rm, font_handle, font_size_for_obj, ends_with_space =
      fetch_text_obj_info(text_obj, tp, text_obj_cache,
                          fs_buf: fs_buf, text_buf: text_obj_text_buf)

    # Advance: 2 FFI calls per char (GetGlyphWidth + GetMatrix). In lean
    # mode we skip it — best_reference_width falls back to bbox-width
    # which works just as well for the word-boundary discriminant.
    advance = if lean
                nil
              else
                compute_glyph_advance_fast(font_handle, cp, font_size_for_obj,
                                            tp_handle, i, gw_buf, matrix)
              end

    td_x0, td_x1, td_top, td_bottom, td_ox, td_oy =
      apply_page_rotation_to_char(page_rotation, raw_w, raw_h,
                                   x0, x1, y_top, y_bot,
                                   origin_x_raw, origin_y_raw)

    # In lean mode we skip 5 FFI calls per char:
    # GetCharAngle, GetFontWeight, IsHyphen, HasUnicodeMapError,
    # (and the GetFontSize fallback if font_size_for_obj is nil).
    # On pages with thousands of chars the saving is significant
    # (tens of ms). The metadata come out nil/false, which is the
    # neutral value for the internal text/tables/words pipeline.
    result[i] =
      if lean
        {
          char: safe_codepoint(cp),
          codepoint: cp,
          x0: td_x0,
          x1: td_x1,
          top: td_top,
          bottom: td_bottom,
          origin_x: td_ox,
          origin_y: td_oy,
          angle: nil,
          fontsize: font_size_for_obj,
          font: nil,
          weight: nil,
          render_mode: rm,
          generated: Raw.FPDFText_IsGenerated(tp_handle, i) == 1,
          hyphen: false,
          unicode_error: false,
          advance: advance,
          text_obj_id: text_obj && !text_obj.null? ? text_obj.address : nil,
          text_obj_ends_with_space: ends_with_space
        }
      else
        {
          char: safe_codepoint(cp),
          codepoint: cp,
          x0: td_x0,
          x1: td_x1,
          top: td_top,
          bottom: td_bottom,
          origin_x: td_ox,
          origin_y: td_oy,
          angle: Raw.FPDFText_GetCharAngle(tp_handle, i),
          fontsize: font_size_for_obj || Raw.FPDFText_GetFontSize(tp_handle, i),
          font: font_name,
          weight: Raw.FPDFText_GetFontWeight(tp_handle, i),
          render_mode: rm,
          generated: Raw.FPDFText_IsGenerated(tp_handle, i) == 1,
          hyphen: Raw.FPDFText_IsHyphen(tp_handle, i) == 1,
          unicode_error: Raw.FPDFText_HasUnicodeMapError(tp_handle, i) == 1,
          advance: advance,
          text_obj_id: text_obj && !text_obj.null? ? text_obj.address : nil,
          text_obj_ends_with_space: ends_with_space
        }
      end
  end
  result
end

#compute_geometry_chars(loose:) ⇒ Object

Minimal char extraction for the table/word pipeline. See ‘chars` `geometry:` for the rationale. Compared to compute_chars(lean: true) this skips, per char: FPDFText_GetCharOrigin (origin is never read by the pipeline) and the per-char angle/font/weight/render-mode reads, the page rotation is applied inline (no origin, no intermediate 6-tuple allocation), and the result hash carries only the fields the WordExtractor / Table / rebuild_word_separators path reads.

‘text_obj_ends_with_space` is intentionally KEPT: rebuild_word_separators uses it as the content-stream “token end” signal that distinguishes a word boundary from internal numeric kerning (e.g. “2.895,26”). Dropping it would change word splitting on PDFs that rely on that signal, so the GetTextObject lookup stays (its info tuple is cached per text object).



440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
 
# File 'lib/rpdfium/page.rb', line 440

def compute_geometry_chars(loose:)
  tp = text_page
  n = tp.char_count
  return [] if n.zero?

  page_rotation = rotation
  raw_w, raw_h = rotated_dimensions(page_rotation)

  result = Array.new(n)

  # FFI buffers reused across all iterations (see compute_chars).
  l = FFI::MemoryPointer.new(:double)
  r = FFI::MemoryPointer.new(:double)
  b = FFI::MemoryPointer.new(:double)
  t = FFI::MemoryPointer.new(:double)
  rect = Raw::FS_RECTF.new
  fs_buf = FFI::MemoryPointer.new(:float)
  text_obj_text_buf = FFI::MemoryPointer.new(:uint8, TEXT_OBJ_INITIAL_BUF_BYTES)
  text_obj_cache = {}
  tp_handle = tp.handle

  n.times do |i|
    x0, x1, y_top, y_bot = read_char_bbox(tp, i, loose, l, r, b, t, rect)

    text_obj = begin
      Raw.FPDFText_GetTextObject(tp_handle, i)
    rescue Rpdfium::LoadError
      nil
    end
    _, _, _, ends_with_space =
      fetch_text_obj_info(text_obj, tp, text_obj_cache,
                          fs_buf: fs_buf, text_buf: text_obj_text_buf)

    # Inline page-rotation → top-down coords (mirror of
    # apply_page_rotation_to_char, dropping the origin outputs).
    td_x0, td_x1, td_top, td_bottom =
      case page_rotation
      when 90 then [y_bot, y_top, x0, x1]
      when 180 then [raw_w - x1, raw_w - x0, y_bot, y_top]
      when 270 then [raw_h - y_top, raw_h - y_bot, raw_w - x1, raw_w - x0]
      else # 0, nil, or non-multiple-of-90 fallback
        [x0, x1, raw_h - y_top, raw_h - y_bot]
      end

    result[i] = {
      char: safe_codepoint(Raw.FPDFText_GetUnicode(tp_handle, i)),
      x0: td_x0,
      x1: td_x1,
      top: td_top,
      bottom: td_bottom,
      generated: Raw.FPDFText_IsGenerated(tp_handle, i) == 1,
      text_obj_ends_with_space: ends_with_space
    }
  end
  result
end

#compute_glyph_advance_fast(font, codepoint, font_size, tp_handle, char_index, gw_buf, matrix) ⇒ Object

Computes the glyph advance in page coordinates for a specific char. Formula: glyph_width(font, codepoint, font_size) × |CTM.a|. Reuses the caller-provided gw_buf and matrix instead of allocating per char. Returns nil if the advance is not computable (font unavailable, or PDFium build without FPDFFont_GetGlyphWidth).



645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
 
# File 'lib/rpdfium/page.rb', line 645

def compute_glyph_advance_fast(font, codepoint, font_size, tp_handle,
                                char_index, gw_buf, matrix)
  return nil if font.nil? || font_size.nil?

  ok = begin
    Raw.FPDFFont_GetGlyphWidth(font, codepoint, font_size, gw_buf)
  rescue Rpdfium::LoadError
    return nil
  end
  return nil if ok == 0

  glyph_w_font_units = gw_buf.read_float

  # CTM scale: reuse the matrix in-place.
  scale = if Raw.FPDFText_GetMatrix(tp_handle, char_index, matrix) == 1
            matrix[:a].abs
          else
            1.0
          end
  glyph_w_font_units * scale
end

#cropbox ⇒ Object

PDF spec 14.11.2: if CropBox is absent, the default is MediaBox. The cropbox is the “visible” area of the page; for PDFs from business software it often coincides with the MediaBox. pdfplumber performs the fallback automatically.



88
89
90
 
# File 'lib/rpdfium/page.rb', line 88

def cropbox
  box_to_topdown(box(:crop)) || mediabox
end

#fetch_text_obj_info(text_obj, tp, cache, fs_buf:, text_buf:) ⇒ Object

Cache lookup for a text object. Returns a tuple:

[render_mode, font_handle, font_size, ends_with_space]

‘ends_with_space` indicates whether the text of the entire text object ends with a space (a “token end” signal declared by the PDF). It is a property of the object, not of the single char, so it can be computed once and cached together with the other fields — this avoids one FPDFTextObj_GetText call for every char that shares the obj.



582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
 
# File 'lib/rpdfium/page.rb', line 582

def fetch_text_obj_info(text_obj, tp, cache, fs_buf:, text_buf:)
  return [nil, nil, nil, nil] if text_obj.nil? || text_obj.null?

  addr = text_obj.address
  return cache[addr] if cache.key?(addr)

  rm = Raw.FPDFTextObj_GetTextRenderMode(text_obj)
  font = Raw.FPDFTextObj_GetFont(text_obj)
  font_handle = font.null? ? nil : font

  font_size = if Raw.FPDFTextObj_GetFontSize(text_obj, fs_buf) == 1
                fs_buf.read_float
              end

  obj_text = read_text_obj_text_fast(text_obj, tp, text_buf)
  ends_with_space = obj_text&.end_with?(' ')

  tuple = [rm, font_handle, font_size, ends_with_space]
  cache[addr] = tuple
  tuple
end

#font_inventory(height_tolerance: 0.5) ⇒ Object

Distribution of chars by (font, visual height, weight).

Returns an Array of Hash sorted by descending count:

[{ font:, height:, weight:, count:, sample: }, ...]

‘height` is the visual height of the char in points (bottom - top), more reliable than `fontsize`, which PDFium normalizes to 1.0 when the real size is in the CTM matrix (a common case on forms generated with scaling).

‘sample` is the first 40 chars of that group, in document order, for inspection.

Heights are bucketed within ‘height_tolerance` (single-linkage, per font+weight) rather than rounded to a fixed precision. A round glyph whose loose box overshoots the cap line by a fraction of a point (“O”, “S”, “C”…) would otherwise land in a spurious one-glyph group (e.g. “O” at h=6.6 split off from the rest of the line at h=6.5, producing garbled samples like “CDICE FISCALE” with every “O” missing). Clustering keeps each logical size in a single group.

Use it to choose the ‘chars_where` filter: typically the font with the most chars is the template, and the minority fonts (a single size, often monospace) are the data.



720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
 
# File 'lib/rpdfium/page.rb', line 720

def font_inventory(height_tolerance: 0.5)
  real = chars.reject { |c| c[:generated] }
  # Tag with document position so the cluster (which gets reordered by
  # height) can be put back in reading order for the sample.
  indexed = real.each_with_index.to_a

  by_font_weight = indexed.group_by { |(c, _i)| [c[:font], c[:weight]] }

  by_font_weight.flat_map do |(font, weight), pairs|
    height_of = ->(p) { p[0][:bottom] - p[0][:top] }
    Util::Cluster.cluster_objects(pairs, height_of, tolerance: height_tolerance).map do |cluster|
      mean_h = cluster.sum { |p| height_of.call(p) } / cluster.size.to_f
      ordered = cluster.sort_by { |(_c, i)| i }
      {
        font: font,
        height: mean_h.round(1),
        weight: weight,
        count: cluster.size,
        sample: ordered.first(40).map { |(c, _i)| c[:char] }.join
      }
    end
  end.sort_by { |g| -g[:count] }
end

#form_fields ⇒ Object

Form widgets only



1246
1247
1248
1249
1250
1251
 
# File 'lib/rpdfium/page.rb', line 1246

def form_fields
  return [] unless @document.has_forms?

  annotations.select { |a| a.subtype == :widget }
             .map    { |a| Form::Field.new(@document.form_env, a) }
end

#handle ⇒ Object 



36
37
38
 
# File 'lib/rpdfium/page.rb', line 36

def handle
  @state[:handle]
end

#has_transparency? ⇒ Boolean

Returns:

  • (Boolean) 


50
51
52
 
# File 'lib/rpdfium/page.rb', line 50

def has_transparency?
  Raw.FPDFPage_HasTransparency(@state[:handle]) == 1
end

#height ⇒ Object 



43
 
# File 'lib/rpdfium/page.rb', line 43

def height;   Raw.FPDF_GetPageHeightF(@state[:handle]); end

#horizontal_lines(tolerance: 0.5) ⇒ Object

Horizontal lines: dy ~ 0 within tolerance



1105
1106
1107
1108
1109
1110
1111
 
# File 'lib/rpdfium/page.rb', line 1105

def horizontal_lines(tolerance: 0.5)
  line_segments.select { |s| (s[:y0] - s[:y1]).abs <= tolerance }
               .map { |s| { y: (s[:y0] + s[:y1]) / 2.0,
                            x0: [s[:x0], s[:x1]].min,
                            x1: [s[:x0], s[:x1]].max,
                            stroke_width: s[:stroke_width] } }
end

#images ⇒ Object 



1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
 
# File 'lib/rpdfium/page.rb', line 1220

def images
  n = Raw.FPDFPage_CountObjects(@state[:handle])
  out = []
  n.times do |i|
    obj = Raw.FPDFPage_GetObject(@state[:handle], i)
    next if obj.null?
    next unless Raw.FPDFPageObj_GetType(obj) == Raw::PAGEOBJ_IMAGE

    out << Image::Embedded.new(self, obj)
  end
  out
end

#label_value_pairs(data_font:, template_font: nil, data_filter: nil, matcher: nil, x_tolerance: 3.0, y_tolerance: 3.0, **char_opts) ⇒ Array<Hash>

Associates the template’s semantic labels with the values entered on the page. For filled forms (F24, Comunicazione IVA, 770, etc.) where the template and the data are both static text but in different fonts.

Associates the template’s semantic labels with the values entered on the page. A primitive for structured extraction from filled forms where template and data coexist as graphical text in different fonts.

**For advanced cases** (repetitive tables, merging of multi-cell words, structured output) compose with ‘Util::WordMerger`, `Util::ColumnInference`, and configure the `Util::LabelMatcher` appropriately — see the examples in the docs.

Parameters:

  • data_font (String, Regexp, Array) —

    font of the entered “data” layer. Typically Courier (F24, 770) or Helvetica (Comunicazione IVA). See ‘Page#font_inventory` to identify it.

  • data_font (String, Regexp, Array) —

    font of the “data” layer.

  • template_font (String, Regexp, Array, nil) (defaults to: nil) —

    font of the “template” layer. If nil, uses all chars that are NOT in ‘data_font`.

  • data_filter (Proc, nil) (defaults to: nil) —

    optional filter on the value text.

  • matcher (LabelMatcher, nil) (defaults to: nil) —

    preconfigured instance. If nil, creates one with the defaults.

  • x_tolerance, —

    y_tolerance [Float] tolerances for WordExtractor.

  • char_opts (Hash) —

    kwargs passed to ‘#chars` (e.g. `inject_spaces: false` for box-based forms).

Returns:

  • (Array<Hash>) —

    one per value: { value:, labels: { col:, row: }, geometry: … }



849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
 
# File 'lib/rpdfium/page.rb', line 849

def label_value_pairs(data_font:, template_font: nil,
                      data_filter: nil, matcher: nil,
                      x_tolerance: 3.0, y_tolerance: 3.0,
                      **char_opts)
  data_chars = chars_where(font: data_font, **char_opts)
  anchor_chars =
    if template_font
      chars_where(font: template_font, **char_opts)
    else
      chars(**char_opts).reject { |c| c[:generated] }.reject do |c|
        send(:font_matches?, c[:font], data_font)
      end
    end

  we = Util::WordExtractor.new(x_tolerance: x_tolerance, y_tolerance: y_tolerance)
  data_words = we.extract_words(data_chars)
  data_words = data_words.select { |w| data_filter.call(w[:text]) } if data_filter
  anchor_words = we.extract_words(anchor_chars)

  m = matcher || Util::LabelMatcher.new
  m.match(data_words, anchor_words)
end

#line_segments(include_curves: false, include_dashed: false) ⇒ Object

Extracts all the line segments (LINETO) of the path objects. Returns Array<Hash>:

:x0,:y0,:x1,:y1  endpoints (top-down)
:stroke_width    stroke width
:horizontal/:vertical  derived for convenience

For tables, mainly the “pure” horizontal and vertical segments are of interest. Beziers and oblique segments are ignored by default (pass ‘include_curves: true` to get them as the bbox of their points).

Descends recursively into Form XObjects applying their transformation matrix. Many PDFs (TeamSystem, Zucchetti, Excel templates) encapsulate the entire page in a Form XObject — without the descent, we would see zero lines here even though the page is visually full of borders/separators. Behavior aligned with pdfminer.six (and therefore pdfplumber). ‘include_curves` true: includes Beziers as segments (with the :curve flag). `include_dashed` true: includes dashed lines (with the :dashed flag).

Default: false. Dashed lines are often non-visual "guides" in print
templates and confuse table cell detection. Those who want them
explicitly (e.g. full drawing extraction) pass true.



929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
 
# File 'lib/rpdfium/page.rb', line 929

def line_segments(include_curves: false, include_dashed: false)
  # Cache by parameters: line_segments is typically called twice per
  # page (by horizontal_lines AND by vertical_lines), and iterates all
  # the path objects of the page via FFI — expensive on PDFs with rich
  # graphics (e.g. CR Banca d'Italia: ~500-1000 path objs per page).
  cache_key = [include_curves, include_dashed]
  @line_segments_cache ||= {}
  return @line_segments_cache[cache_key] if @line_segments_cache.key?(cache_key)

  out = []
  page_rotation = rotation
  raw_w, raw_h = rotated_dimensions(page_rotation)
  ctx = { rotation: page_rotation, raw_w: raw_w, raw_h: raw_h }
  collect_line_segments(@state[:handle], identity_matrix, ctx,
                         include_curves, out, page_object: false)
  result = include_dashed ? out : out.reject { |s| s[:dashed] }
  @line_segments_cache[cache_key] = result
end

#lines(x_tolerance: 3.0, y_tolerance: 3.0, separator: ' ', font: nil, height: nil, weight: nil, bbox: nil, where: nil, **char_opts) ⇒ Object

Groups the filtered chars into logical rows and returns an Array of strings (one per row, top-to-bottom, chars within the row left-to-right). Convenient when the PDF is a filled form and you want only the entered values as clean rows.

F24 example:

page.lines(font: /Courier/i)
# => ["Soggetto:  Azienda  S.R.L.  ( 01234567890 )",
#     "0  1  2  3  4  5  6  7  8  9  0",
#     "Azienda  S.R.L.",
#     "1001  11  2021  499,81  0,00",
#     "1712  12  2021  32,46  0,00",
#     "1701  11  2021  0,00  295,89",
#     "532,27  295,89  236,38",
#     ...]

The filter parameters are the same as ‘chars_where`. The `x_tolerance` and `y_tolerance` parameters control the WordExtractor.

The inter-word separator is two spaces (for readability on forms with spaced fields); change it with ‘separator:`.



802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
 
# File 'lib/rpdfium/page.rb', line 802

def lines(x_tolerance: 3.0, y_tolerance: 3.0, separator: '  ',
          font: nil, height: nil, weight: nil, bbox: nil, where: nil,
          **char_opts)
  cs = chars_where(font: font, height: height, weight: weight,
                   bbox: bbox, where: where, **char_opts)
  return [] if cs.empty?

  we = Util::WordExtractor.new(x_tolerance: x_tolerance,
                               y_tolerance: y_tolerance)
  words = we.extract_words(cs)
  return [] if words.empty?

  # Cluster by top (with tolerance), then sort by x0 within the row
  rows = Util::Cluster.cluster_objects(words, :top, tolerance: y_tolerance)
  rows.map do |row_words|
    row_words.sort_by { |w| w[:x0] }.map { |w| w[:text] }.join(separator)
  end
end

#link_at(x, y) ⇒ Object

Hit-test: returns the link annotation that contains the point (x, y) in the page’s top-down coordinates. Returns an Annotation instance or nil.

More efficient than iterating ‘links` when starting from a coordinate (e.g. mapping a click on the rendering → the link URL). pdfplumber has no direct equivalent.



1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
 
# File 'lib/rpdfium/page.rb', line 1202

def link_at(x, y)
  # PDFium uses bottom-up coords; convert
  pdf_y = height - y
  link_handle = Raw.FPDFLink_GetLinkAtPoint(@state[:handle],
                                             x.to_f, pdf_y.to_f)
  return nil if link_handle.null?

  annot_handle = Raw.FPDFLink_GetAnnot(@state[:handle], link_handle)
  return nil if annot_handle.null?

  # Annotation requires an index in the page; we do not have it directly
  # here. We iterate the page's annotations and find the one with the
  # closest rect. For most PDFs this is O(small).
  annotations.find { |a| a.subtype == :link && annotation_contains?(a, x, y) }
end

#links ⇒ Object

Link annotations only (clickable, external or internal)



1241
1242
1243
 
# File 'lib/rpdfium/page.rb', line 1241

def links
  annotations.select { |a| a.subtype == :link }
end

#marked_content_inventory ⇒ Object

Iterates all the marks (BMC/BDC operators) with their names and parameters. Returns Array<Hash> with { obj_handle, mark_name, params }. For tagged PDFs, the common mark_names are: “P” (paragraph), “Span”, “Artifact”, “Figure”, “TR” (table row), “TD” (table cell).



1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
 
# File 'lib/rpdfium/page.rb', line 1175

def marked_content_inventory
  out = []
  walk_page_objects do |obj, _ctm|
    mark_count = safely_count_marks(obj)
    mark_count.times do |mi|
      mark = Raw.FPDFPageObj_GetMark(obj, mi)
      next if mark.null?

      out << {
        obj: obj,
        mark_name: read_mark_name(mark),
        params: read_mark_params(mark)
      }
    end
  end
  out
end

#marked_content_regions ⇒ Object

Iterates all the marked content of the page (BDC/BMC operators of the PDF content stream) grouping the page objects by their mcid (Marked Content ID). Useful for “tagged” PDFs (PDF/UA, exports from Word/InDesign): an mcid ≥ 0 identifies a semantic unit (paragraph, span, figure), and all the objects with the same mcid belong to the same structure tag.

Returns a Hash { mcid (Integer) => Array<page_object_handle> }. mcid -1 (the page objects without marked content) is OMITTED.

On non-tagged PDFs (e.g. most PDFs from Italian business software) the Hash is empty. On tagged PDFs it is the source of truth for semantically grouping chars/words — more reliable than any geometric heuristic.



1162
1163
1164
1165
1166
1167
1168
1169
 
# File 'lib/rpdfium/page.rb', line 1162

def marked_content_regions
  out = Hash.new { |h, k| h[k] = [] }
  walk_page_objects do |obj, _ctm|
    mcid = read_marked_content_id(obj)
    out[mcid] << obj if mcid >= 0
  end
  out
end

#mediabox ⇒ Object

pdfplumber-compatible accessors. Return the box as the tuple

x0, top, x1, bottom

in top-down coordinates (the same system

used by chars, edges, table cells). Return nil if the box is not defined in the PDF (e.g. ArtBox or BleedBox are often absent).

Usage example:

crop = page.cropbox        # → [0.0, 0.0, 595.28, 841.88] or nil
crop != [0, 0, page.width, page.height]  # PDF has an explicit crop



82
 
# File 'lib/rpdfium/page.rb', line 82

def mediabox; box_to_topdown(box(:media)); end

#numeric_context?(prev_char, curr_char) ⇒ Boolean

Returns:

  • (Boolean) 


265
266
267
268
269
270
271
 
# File 'lib/rpdfium/page.rb', line 265

def numeric_context?(prev_char, curr_char)
  return false if prev_char.nil? || curr_char.nil?

  prev_num = prev_char.match?(/\d/) || NUMERIC_PUNCT.include?(prev_char)
  curr_num = curr_char.match?(/\d/) || NUMERIC_PUNCT.include?(curr_char)
  prev_num && curr_num
end

#read_text_obj_text_fast(text_obj, tp, buf) ⇒ Object

Reads the text of a PDF text object, reusing the caller-provided buffer instead of allocating one per call.

C signature: ‘unsigned long FPDFTextObj_GetText(FPDF_PAGEOBJECT, FPDF_TEXTPAGE, FPDF_WCHAR* buffer, unsigned long length)` — length in BYTES, the return is the total number of bytes needed (including the null terminator), even if the buffer is too small.

For 99% of text objs the initial 256-byte buffer is enough; in the rare case PDFium requires more space, a larger buffer is allocated on demand (rare path, OK to allocate).



615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
 
# File 'lib/rpdfium/page.rb', line 615

def read_text_obj_text_fast(text_obj, tp, buf)
  return nil if text_obj.nil? || text_obj.null?

  needed = Raw.FPDFTextObj_GetText(text_obj, tp.handle, buf,
                                    TEXT_OBJ_INITIAL_BUF_BYTES)
  return nil if needed < 2

  if needed > TEXT_OBJ_INITIAL_BUF_BYTES
    # Rare path: text obj with > 128 chars. Allocate a dedicated buffer.
    big_buf = FFI::MemoryPointer.new(:uint8, needed)
    needed = Raw.FPDFTextObj_GetText(text_obj, tp.handle, big_buf, needed)
    return nil if needed < 2

    payload_bytes = needed - 2
    return nil if payload_bytes <= 0

    return decode_utf16le(big_buf.read_bytes(payload_bytes))
  end

  payload_bytes = needed - 2
  return nil if payload_bytes <= 0

  decode_utf16le(buf.read_bytes(payload_bytes))
end

#rebuild_word_separators(chars) ⇒ Object

Rebuilds the spaces that separate words based on the GEOMETRY of the “real” chars, completely discarding PDFium’s synthetic spaces (which are unreliable: PDFium emits them aggressively even between digits of numbers like “2.895,26”).

Algorithm:

1. Filter out all :generated chars (typically synthetic spaces
   with a degenerate bbox).
2. Cluster the remaining chars by row (top tolerance 1pt).
3. Within each row, sort by x0 and for each consecutive pair
   compute gap = next.x0 - prev.x1 and char_w = (prev.w + next.w) / 2.
   If gap > 0.275 × char_w → insert a new synthetic space
   (bbox normalized to the top/bottom of the chars).

Threshold 0.275: tuned empirically on a real TeamSystem PDF. Measured distribution: intra-word gap max ratio 0.24, inter-word gap min ratio 0.31. Classification 100% correct on the training dataset (1400 intra + 663 inter cases). pdfminer.six uses 0.1 internally (‘word_margin`) but with additional info from the font advance, not available from PDFium.



205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
 
# File 'lib/rpdfium/page.rb', line 205

def rebuild_word_separators(chars)
  reals = chars.reject { |c| c[:generated] }
  return chars if reals.empty?

  # Cluster by row, preserving the top ordering
  sorted_top = reals.sort_by { |c| c[:top] }
  rows = []
  sorted_top.each do |c|
    if rows.last && (c[:top] - rows.last.last[:top]).abs <= 1.0
      rows.last << c
    else
      rows << [c]
    end
  end

  result = []
  rows.each do |row|
    row_sorted = row.sort_by { |c| c[:x0] }
    prev = nil
    row_sorted.each do |c|
      if prev
        gap = c[:x0] - prev[:x1]

        # Signal from the PDF content stream: prev.text_obj_ends_with_space.
        # If prev does NOT end a token (false), the gap is internal
        # kerning → never insert a space.
        #
        # If prev ends a token (true), it may be:
        #   - a real word end (relatively large geometric gap)
        #   - a syntactic token end (e.g. between digits and punctuation
        #     of a number "2", "."), with a small gap.
        #
        # We discriminate with the geometric threshold combined with the
        # typographic "context": if the pair (prev_char, curr_char) looks
        # like a numeric context (digits + punctuation), we use a higher
        # threshold; otherwise the normal threshold.
        obj_signal_present = prev.key?(:text_obj_ends_with_space)
        obj_says_continues = obj_signal_present && !prev[:text_obj_ends_with_space]

        unless obj_says_continues
          ref_w = best_reference_width(prev, c)
          threshold_ratio = numeric_context?(prev[:char], c[:char]) ? 0.7 : 0.3
          threshold = ref_w > 0 ? ref_w * threshold_ratio : 0.5
          result << build_synthetic_space(prev, c) if gap > threshold
        end
      end
      result << c
      prev = c
    end
  end
  result
end

#render(scale: 2.0, rotate: 0, output: :rgba, include_annotations: false, include_forms: false, background: 0xFFFFFFFF) ⇒ Object

Render to a bitmap. ‘output` can be :rgba (default), :bgra, :gray. Returns [w, h, bytes] where bytes is a binary string. If include_forms is true and the document has forms, it overlays the widgets.

Raises:



1293
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
1304
1305
1306
1307
1308
1309
1310
1311
1312
1313
1314
1315
1316
1317
1318
1319
1320
1321
1322
1323
 
# File 'lib/rpdfium/page.rb', line 1293

def render(scale: 2.0, rotate: 0, output: :rgba,
           include_annotations: false, include_forms: false,
           background: 0xFFFFFFFF)
  w = (width  * scale).round
  h = (height * scale).round
  flags = 0
  flags |= Raw::FPDF_ANNOT if include_annotations
  flags |= Raw::FPDF_REVERSE_BYTE_ORDER if output == :rgba
  format = output == :gray ? Raw::FPDFBitmap_Gray : Raw::FPDFBitmap_BGRA

  bitmap = Raw.FPDFBitmap_CreateEx(w, h, format, FFI::Pointer::NULL, 0)
  raise Error, 'Bitmap allocation failed' if bitmap.null?

  begin
    Raw.FPDFBitmap_FillRect(bitmap, 0, 0, w, h, background)
    Raw.FPDF_RenderPageBitmap(bitmap, @state[:handle], 0, 0, w, h,
                              rotation_index(rotate), flags)
    if include_forms && @document.form_env
      Raw.FPDF_FFLDraw(@document.form_env.handle, bitmap, @state[:handle],
                       0, 0, w, h, rotation_index(rotate), flags)
    end
    stride = Raw.FPDFBitmap_GetStride(bitmap)
    buf    = Raw.FPDFBitmap_GetBuffer(bitmap)
    # The stride may exceed w*bpp due to alignment padding.
    # In BGRA it is almost always w*4, but we respect it for safety.
    bytes  = buf.read_bytes(stride * h)
    [w, h, bytes, stride]
  ensure
    Raw.FPDFBitmap_Destroy(bitmap)
  end
end

#render_to_png(path, **opts) ⇒ Object

Direct rendering to a PNG file. Uses Rpdfium::IO::PNG (pure Ruby, zero deps).



1326
1327
1328
1329
1330
 
# File 'lib/rpdfium/page.rb', line 1326

def render_to_png(path, **opts)
  w, h, bytes, stride = render(output: :rgba, **opts)
  Rpdfium::IO::PNG.write(path, w, h, bytes, stride: stride)
  path
end

#rotation ⇒ Object

Rotation in degrees: 0/90/180/270



46
47
48
 
# File 'lib/rpdfium/page.rb', line 46

def rotation
  [0, 90, 180, 270][Raw.FPDFPage_GetRotation(@state[:handle])] || 0
end

#search(query, **opts) ⇒ Object

Search =====


1334
1335
1336
 
# File 'lib/rpdfium/page.rb', line 1334

def search(query, **opts)
  Search.new(self, query, **opts)
end

#struct_tree ⇒ Object

Struct tree of the page (PDF/UA / Tagged PDF). Returns nil if the page is not tagged. For PDFs from Word/LibreOffice/InDesign exports with accessibility tags enabled, it exposes the logical structure (Document → P, H1, Table, TR, TH, TD, Figure, etc.).

Usage modes:

# Automatic lifecycle (RAII via finalizer):
tree = page.struct_tree
tree&.walk { |el| puts el.type }

# Deterministic lifecycle (close at end of block):
page.struct_tree do |tree|
  tree.tables.each { |t| ... }
end

On non-tagged PDFs it returns nil. On “tagged but empty” PDFs (e.g. CR Banca d’Italia, StructTreeRoot present but with placeholder elements), it returns a Tree with ‘Tree#empty? == true`.



1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
 
# File 'lib/rpdfium/page.rb', line 1274

def struct_tree
  tree = Structure::Tree.for_page(self)
  if block_given?
    begin
      yield tree
    ensure
      tree&.close
    end
  else
    tree
  end
end

#text ⇒ Object

Text (“simple” version) =====


98
99
100
101
102
103
104
105
106
 
# File 'lib/rpdfium/page.rb', line 98

def text
  tp = text_page
  n = tp.char_count
  return '' if n.zero?

  buf = FFI::MemoryPointer.new(:ushort, n + 1)
  Raw.FPDFText_GetText(tp.handle, 0, n, buf)
  decode_utf16le(buf.read_bytes((n + 1) * 2), replace: true)
end

#text_in_bbox(left:, top:, right:, bottom:) ⇒ Object

Extracts the text inside an arbitrary bbox (top-down coords). Useful for “read the header of this cell”.



110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
 
# File 'lib/rpdfium/page.rb', line 110

def text_in_bbox(left:, top:, right:, bottom:)
  tp = text_page
  h = height
  # Convert to bottom-up for PDFium
  pdf_top    = h - top
  pdf_bottom = h - bottom
  # PDFium wants: left, top, right, bottom where top > bottom (PDF coords)
  # Probe size:
  n = Raw.FPDFText_GetBoundedText(
    tp.handle, left, pdf_top, right, pdf_bottom, FFI::Pointer::NULL, 0
  )
  return '' if n <= 0

  buf = FFI::MemoryPointer.new(:ushort, n)
  Raw.FPDFText_GetBoundedText(
    tp.handle, left, pdf_top, right, pdf_bottom, buf, n
  )
  decode_utf16le(buf.read_bytes(n * 2), replace: true)
end

#text_page ⇒ Object

Internals =====


1340
1341
1342
 
# File 'lib/rpdfium/page.rb', line 1340

def text_page
  @text_page ||= TextPage.new(self)
end

#trimbox ⇒ Object 



93
 
# File 'lib/rpdfium/page.rb', line 93

def trimbox;  box_to_topdown(box(:trim));  end

#vector_rects ⇒ Object

Compat with the first version: bbox of the path objects (useful for rectangles drawn as thin borders).



1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
 
# File 'lib/rpdfium/page.rb', line 1124

def vector_rects
  n = Raw.FPDFPage_CountObjects(@state[:handle])
  h = height
  out = []

  l = FFI::MemoryPointer.new(:float)
  r = FFI::MemoryPointer.new(:float)
  b = FFI::MemoryPointer.new(:float)
  t = FFI::MemoryPointer.new(:float)

  n.times do |i|
    obj = Raw.FPDFPage_GetObject(@state[:handle], i)
    next if obj.null?
    next unless Raw.FPDFPageObj_GetType(obj) == Raw::PAGEOBJ_PATH
    next unless Raw.FPDFPageObj_GetBounds(obj, l, r, b, t) == 1

    out << { x0: l.read_float, x1: r.read_float,
             top: h - t.read_float, bottom: h - b.read_float }
  end
  out
end

#vertical_lines(tolerance: 0.5) ⇒ Object

Vertical lines: dx ~ 0 within tolerance



1114
1115
1116
1117
1118
1119
1120
 
# File 'lib/rpdfium/page.rb', line 1114

def vertical_lines(tolerance: 0.5)
  line_segments.select { |s| (s[:x0] - s[:x1]).abs <= tolerance }
               .map { |s| { x: (s[:x0] + s[:x1]) / 2.0,
                            top: [s[:y0], s[:y1]].min,
                            bottom: [s[:y0], s[:y1]].max,
                            stroke_width: s[:stroke_width] } }
end

#width ⇒ Object

Geometry =====


42
 
# File 'lib/rpdfium/page.rb', line 42

def width;    Raw.FPDF_GetPageWidthF(@state[:handle]); end

#words(x_tolerance: 3.0, y_tolerance: 3.0, **char_opts) ⇒ Object 



875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
 
# File 'lib/rpdfium/page.rb', line 875

def words(x_tolerance: 3.0, y_tolerance: 3.0, **char_opts)
  cs = chars(**char_opts)
  return [] if cs.empty?

  # Group into rows by y
  rows = group_consecutive(cs.sort_by { |c| [c[:top], c[:x0]] }) do |a, b|
    (a[:top] - b[:top]).abs <= y_tolerance
  end

  rows.flat_map do |row|
    sorted = row.sort_by { |c| c[:x0] }
    # Split on gap > x_tolerance or explicit space
    word_groups = []
    buf = []
    sorted.each do |c|
      gap = buf.empty? ? 0.0 : (c[:x0] - buf.last[:x1])
      space = c[:char].match?(/\s/) || c[:generated]
      if buf.empty?
        buf << c unless space
      elsif space || gap > x_tolerance
        word_groups << buf unless buf.empty?
        buf = space ? [] : [c]
      else
        buf << c
      end
    end
    word_groups << buf unless buf.empty?
    word_groups.map { |g| word_from_chars(g) }
  end
end