rpdfium 0.4.1

data/lib/rpdfium/table/extractor.rb

@@ -0,0 +1,246 @@
+# frozen_string_literal: true
+
+module Rpdfium
+  module Table
+    # Trova tabelle su una pagina, fedele al `pdfplumber.TableFinder`.
+    #
+    # Pipeline:
+    #   1. raccogli edges candidati per ogni asse, secondo strategia
+    #      (`:lines` / `:lines_strict` / `:text` / `:explicit`)
+    #   2. merge_edges (snap collineari + join contigui)
+    #   3. filter per lunghezza minima
+    #   4. edges_to_intersections con tolerance
+    #   5. intersections_to_cells (smallest cell per ogni punto)
+    #   6. cells_to_tables (grouping per corner condivisi)
+    #
+    # API pubblica:
+    #   ext = Rpdfium::Table::Extractor.new(page, **opts)
+    #   ext.tables           # => [Table, ...]   (oggetti Rpdfium::Table::Table)
+    #   ext.extract          # => [[[String]]]   (Array di tabelle, ogni tabella
+    #                                              è Array di righe, ogni riga
+    #                                              è Array di stringhe)
+    #   ext.find             # alias di .tables (compat back con 0.2.x)
+    #   ext.edges            # edges raffinati
+    #   ext.intersections    # Hash {[x,y] => {v:[],h:[]}}
+    #   ext.cells            # Array<bbox>
+    class Extractor
+      DEFAULTS = {
+        vertical_strategy:   :lines,
+        horizontal_strategy: :lines,
+        explicit_vertical_lines:   [],
+        explicit_horizontal_lines: [],
+
+        # Tolleranze. I `_x_` / `_y_` ereditano dal valore non-suffisso.
+        snap_tolerance:           3.0,
+        snap_x_tolerance:         nil,
+        snap_y_tolerance:         nil,
+        join_tolerance:           3.0,
+        join_x_tolerance:         nil,
+        join_y_tolerance:         nil,
+
+        edge_min_length:           3.0,
+        edge_min_length_prefilter: 1.0,
+
+        min_words_vertical:   Edges::DEFAULT_MIN_WORDS_VERTICAL,
+        min_words_horizontal: Edges::DEFAULT_MIN_WORDS_HORIZONTAL,
+
+        intersection_tolerance:   3.0,
+        intersection_x_tolerance: nil,
+        intersection_y_tolerance: nil,
+
+        # Settings testo (passati a TextExtraction quando si chiama .extract).
+        # I default 3.0 sono quelli di pdfplumber.
+        text_x_tolerance: Util::WordExtractor::DEFAULT_X_TOLERANCE,
+        text_y_tolerance: Util::WordExtractor::DEFAULT_Y_TOLERANCE,
+        text_keep_blank_chars: false,
+
+        # Auto-fallback: se :lines non produce edges, riprova con :text.
+        # Manteniamo il flag (era già in 0.2.x) ma SOLO come fallback,
+        # mai come "fix" su layout patologici — coerente con pdfplumber che
+        # non lo ha (chi usa pdfplumber sa che deve scegliere la strategia).
+        auto_fallback: true
+      }.freeze
+
+      VALID_STRATEGIES = %i[lines lines_strict text explicit].freeze
+
+      attr_reader :page, :settings
+
+      def initialize(page, **opts)
+        @page = page
+        @settings = resolve_settings(DEFAULTS.merge(opts))
+        validate_strategies!
+      end
+
+      # Pipeline completa, costruisce gli edges raffinati.
+      def edges
+        @edges ||= build_edges(@settings[:vertical_strategy],
+                               @settings[:horizontal_strategy]).then do |built|
+          if built.empty? && @settings[:auto_fallback] &&
+             (@settings[:vertical_strategy] != :text ||
+              @settings[:horizontal_strategy] != :text)
+            # Fallback: l'auto-fallback è LASCO, riprova tutto a :text.
+            build_edges(:text, :text)
+          else
+            built
+          end
+        end
+      end
+
+      def intersections
+        @intersections ||= Edges.edges_to_intersections(
+          edges,
+          x_tolerance: @settings[:intersection_x_tolerance],
+          y_tolerance: @settings[:intersection_y_tolerance]
+        )
+      end
+
+      def cells
+        @cells ||= Cells.intersections_to_cells(intersections)
+      end
+
+      def tables
+        @tables ||= Cells.cells_to_tables(cells).map { |group| Table.new(@page, group) }
+      end
+      alias find tables
+
+      # Estrai i dati di tutte le tabelle: Array<Array<Array<String>>>.
+      def extract(**text_opts)
+        merged = {
+          x_tolerance: @settings[:text_x_tolerance],
+          y_tolerance: @settings[:text_y_tolerance],
+          keep_blank_chars: @settings[:text_keep_blank_chars]
+        }.merge(text_opts)
+
+        tables.map { |t| t.extract(**merged) }
+      end
+
+      private
+
+      def resolve_settings(s)
+        # Cascata x/y dai non-suffissi
+        s[:snap_x_tolerance] ||= s[:snap_tolerance]
+        s[:snap_y_tolerance] ||= s[:snap_tolerance]
+        s[:join_x_tolerance] ||= s[:join_tolerance]
+        s[:join_y_tolerance] ||= s[:join_tolerance]
+        s[:intersection_x_tolerance] ||= s[:intersection_tolerance]
+        s[:intersection_y_tolerance] ||= s[:intersection_tolerance]
+        s
+      end
+
+      def validate_strategies!
+        %i[vertical_strategy horizontal_strategy].each do |k|
+          unless VALID_STRATEGIES.include?(@settings[k])
+            raise ArgumentError, "#{k} must be one of #{VALID_STRATEGIES}"
+          end
+          if @settings[k] == :explicit
+            list = @settings[:"explicit_#{k.to_s.split('_').first}_lines"]
+            if list.nil? || list.size < 2
+              raise ArgumentError, "Strategy :explicit on #{k} requires " \
+                                    "at least 2 explicit_*_lines"
+            end
+          end
+        end
+      end
+
+      def build_edges(v_strat, h_strat)
+        words = nil
+        words = page_words if v_strat == :text || h_strat == :text
+
+        v_base = edges_for_strategy(:v, v_strat, words)
+        h_base = edges_for_strategy(:h, h_strat, words)
+
+        v_explicit = explicit_v_edges
+        h_explicit = explicit_h_edges
+
+        all = v_base + v_explicit + h_base + h_explicit
+        merged = Edges.merge_edges(
+          all,
+          snap_x_tolerance: @settings[:snap_x_tolerance],
+          snap_y_tolerance: @settings[:snap_y_tolerance],
+          join_x_tolerance: @settings[:join_x_tolerance],
+          join_y_tolerance: @settings[:join_y_tolerance]
+        )
+        Edges.filter_edges(merged, min_length: @settings[:edge_min_length])
+      end
+
+      def page_words
+        # Genera words usando il nostro WordExtractor (consistente con
+        # quello usato in Table#extract, così i thresholds combaciano).
+        # `lean: true`: vedi commento in Table#extract.
+        chars = @page.chars(lean: true)
+        Util::WordExtractor.new(
+          x_tolerance: @settings[:text_x_tolerance],
+          y_tolerance: @settings[:text_y_tolerance],
+          keep_blank_chars: @settings[:text_keep_blank_chars]
+        ).extract_words(chars)
+      end
+
+      def edges_for_strategy(axis, strat, words)
+        case strat
+        when :lines, :lines_strict
+          axis == :v ? page_vertical_edges(strict: strat == :lines_strict)
+            : page_horizontal_edges(strict: strat == :lines_strict)
+        when :text
+          axis == :v ? Edges.words_to_edges_v(words || [], word_threshold: @settings[:min_words_vertical])
+            : Edges.words_to_edges_h(words || [], word_threshold: @settings[:min_words_horizontal])
+        when :explicit then []
+        end
+      end
+
+      # Converte i `vertical_lines` di Page (formato {x, top, bottom}) al
+      # formato pdfplumber-style atteso dalle Edges.
+      # Nota: in 0.3.0 NON includiamo i lati di rettangoli quando :strict
+      # (ma al momento Page non li espone separatamente, è una semplificazione
+      # che documenteremo).
+      def page_vertical_edges(strict: false) # rubocop:disable Lint/UnusedMethodArgument
+        prefilter = @settings[:edge_min_length_prefilter]
+        @page.vertical_lines.filter_map do |s|
+          length = s[:bottom] - s[:top]
+          next if length < prefilter
+
+          { x0: s[:x], x1: s[:x], top: s[:top], bottom: s[:bottom],
+            orientation: "v" }
+        end
+      end
+
+      def page_horizontal_edges(strict: false) # rubocop:disable Lint/UnusedMethodArgument
+        prefilter = @settings[:edge_min_length_prefilter]
+        @page.horizontal_lines.filter_map do |s|
+          length = s[:x1] - s[:x0]
+          next if length < prefilter
+
+          { x0: s[:x0], x1: s[:x1], top: s[:y], bottom: s[:y],
+            orientation: "h" }
+        end
+      end
+
+      def explicit_v_edges
+        page_h = @page.height
+        @settings[:explicit_vertical_lines].map do |item|
+          x, top, bottom = case item
+                           when Numeric then [item.to_f, 0.0, page_h]
+                           when Hash
+                             [item[:x] || item.fetch("x"),
+                              item[:top]    || item["top"]    || 0.0,
+                              item[:bottom] || item["bottom"] || page_h]
+                           end
+          { x0: x, x1: x, top: top, bottom: bottom, orientation: "v" }
+        end
+      end
+
+      def explicit_h_edges
+        page_w = @page.width
+        @settings[:explicit_horizontal_lines].map do |item|
+          y, x0, x1 = case item
+                      when Numeric then [item.to_f, 0.0, page_w]
+                      when Hash
+                        [item[:y]  || item.fetch("y"),
+                         item[:x0] || item["x0"] || 0.0,
+                         item[:x1] || item["x1"] || page_w]
+                      end
+          { x0: x0, x1: x1, top: y, bottom: y, orientation: "h" }
+        end
+      end
+    end
+  end
+end

data/lib/rpdfium/table/table.rb

@@ -0,0 +1,184 @@
+# frozen_string_literal: true
+
+module Rpdfium
+  module Table
+    # Rappresenta una tabella trovata su una pagina. Espone celle, righe,
+    # colonne, bbox, e il metodo `extract` che ritorna i dati testuali.
+    #
+    # Ogni cella è una bbox `[x0, top, x1, bottom]` (top-down).
+    # Una "row" è il gruppo di celle che condividono la stessa `top`.
+    # Una "column" è il gruppo che condivide la stessa `x0`.
+    class Table
+      attr_reader :page, :cells
+
+      def initialize(page, cells)
+        @page = page
+        @cells = cells
+      end
+
+      def bbox
+        @cells.each_with_object(
+          [Float::INFINITY, Float::INFINITY, -Float::INFINITY, -Float::INFINITY]
+        ) do |c, acc|
+          acc[0] = c[0] if c[0] < acc[0]
+          acc[1] = c[1] if c[1] < acc[1]
+          acc[2] = c[2] if c[2] > acc[2]
+          acc[3] = c[3] if c[3] > acc[3]
+        end
+      end
+
+      # Restituisce le righe come Array<Array<bbox|nil>>. Le celle "mancanti"
+      # in una riga (es. perché la tabella ha una topologia irregolare) sono
+      # rappresentate come nil — coerente con pdfplumber.
+      def rows
+        rows_or_columns(:row)
+      end
+
+      def columns
+        rows_or_columns(:col)
+      end
+
+      # Estrai dati: Array<Array<String>>. Per ogni riga, per ogni cella,
+      # filtra i char della pagina il cui MIDPOINT è nella bbox della cella,
+      # poi ricostruisce il testo via Util::TextExtraction (che a sua volta
+      # passa da WordExtractor).
+      #
+      # Questo è il path di pdfplumber.Table.extract — per ogni riga prima
+      # filtra i char della riga (ottimizzazione: quasi tutti i char delle
+      # altre righe vengono scartati subito), poi per ogni cella filtra
+      # ancora dentro la sub-bbox.
+      #
+      # Ottimizzazione rispetto al path naïve: i char vengono ordinati per
+      # midpoint verticale una sola volta; per ogni riga si usa bsearch per
+      # trovare in O(log n) i char candidati invece di scansionare tutto
+      # l'array O(n) per ogni riga.
+      #
+      # NOTA su strategia :text: `words_to_edges_h` emette per design DUE
+      # edges per riga (top e bottom della bbox del cluster). Significa che
+      # una tabella detectata da text-strategy avrà righe "vere" intervallate
+      # da righe "vuote" tra il bottom-edge della riga N e il top-edge della
+      # riga N+1. Questo è identico al comportamento di pdfplumber. Il
+      # caller può filtrare via `result.reject { |row| row.all?(&:empty?) }`
+      # se vuole eliminarle.
+      # `cell_padding`: estende il bbox di ogni cella verso sinistra e verso
+      # l'alto di N punti. Default 0 (= comportamento pdfplumber identico).
+      # Utile per PDF dove i char sporgono leggermente dal bordo della cella
+      # (es. la "I" maiuscola della cella "Intermediario" in CR Banca d'Italia
+      # ha x0=24.0 ma il bordo della cella è a x=25.6 — viene scartata dal
+      # filtro midpoint, output "ntermediario:"). Con `cell_padding: 2.0` la
+      # cella diventa [23.6, ..., 100, ...] e la "I" viene catturata.
+      #
+      # Padding solo sui bordi "interno-sinistro" e "interno-alto" per
+      # evitare di duplicare char condivisi tra celle adiacenti (un char tra
+      # cella A e cella B finirebbe in entrambe se entrambe paddassero su
+      # tutti i lati).
+      def extract(x_tolerance: Util::WordExtractor::DEFAULT_X_TOLERANCE,
+                  y_tolerance: Util::WordExtractor::DEFAULT_Y_TOLERANCE,
+                  keep_blank_chars: false,
+                  cell_padding: 0.0)
+        # `lean: true`: salta 5 chiamate FFI per char (font name, weight,
+        # angle, hyphen flag, unicode error) che non servono al pipeline
+        # di estrazione tabelle. Su tabelle con migliaia di char riduce
+        # il tempo di compute_chars del ~30%.
+        chars = @page.chars(lean: true)
+
+        # Ordina per midpoint verticale una volta sola; costruisce un array
+        # parallelo di vmid per bsearch. Costo: O(n log n) una tantum.
+        sorted_chars = chars.sort_by { |c| (c[:top] + c[:bottom]) / 2.0 }
+        vmids = sorted_chars.map { |c| (c[:top] + c[:bottom]) / 2.0 }
+
+        # Istanzia WordExtractor UNA volta sola e riusalo per tutte le celle
+        # (può esserci una tabella con decine di celle, evitiamo allocazioni).
+        word_extractor = Util::WordExtractor.new(
+          x_tolerance: x_tolerance,
+          y_tolerance: y_tolerance,
+          keep_blank_chars: keep_blank_chars
+        )
+
+        all_rows = rows
+        all_rows.map do |row|
+          row_bbox = row_bounding_box(row)
+          lo = vmids.bsearch_index { |v| v >= row_bbox[1] - cell_padding } || sorted_chars.size
+          hi = vmids.bsearch_index { |v| v >= row_bbox[3] } || sorted_chars.size
+          row_chars = sorted_chars[lo...hi]
+
+          row.map do |cell|
+            next nil if cell.nil?
+
+            padded = cell_padding.zero? ? cell : pad_cell_bbox(cell, cell_padding)
+            cell_chars = row_chars.select { |c| char_in_bbox?(c, padded) }
+            if cell_chars.empty?
+              ""
+            else
+              extract_text_with(cell_chars, word_extractor, y_tolerance)
+            end
+          end
+        end
+      end
+
+      private
+
+      # Versione "inlined" di Util::TextExtraction.extract_text che riusa
+      # un WordExtractor preesistente invece di crearlo ogni volta.
+      def extract_text_with(chars, word_extractor, y_tolerance)
+        words = word_extractor.extract_words(chars)
+        return "" if words.empty?
+
+        line_clusters = Util::Cluster.cluster_objects(words, :top, tolerance: y_tolerance)
+        line_clusters.map do |line_words|
+          line_words.sort_by { |w| w[:x0] }.map { |w| w[:text] }.join(" ")
+        end.join("\n")
+      end
+
+      def pad_cell_bbox(bbox, padding)
+        x0, top, x1, bottom = bbox
+        # Estendi solo i bordi "interno-sinistro" e "interno-alto" per evitare
+        # di catturare char della cella adiacente destra/sotto.
+        [x0 - padding, top - padding, x1, bottom]
+      end
+
+      # Test "char midpoint dentro bbox" — esattamente come pdfplumber.
+      # Il midpoint del char (non gli estremi della bbox) è il criterio:
+      # un char a cavallo del bordo viene assegnato alla cella in cui ha
+      # più "peso visivo".
+      def char_in_bbox?(char, bbox)
+        x0, top, x1, bottom = bbox
+        h_mid = (char[:x0] + char[:x1]) / 2.0
+        v_mid = (char[:top] + char[:bottom]) / 2.0
+        h_mid >= x0 && h_mid < x1 && v_mid >= top && v_mid < bottom
+      end
+
+      def row_bounding_box(row)
+        row.compact.each_with_object(
+          [Float::INFINITY, Float::INFINITY, -Float::INFINITY, -Float::INFINITY]
+        ) do |c, acc|
+          acc[0] = c[0] if c[0] < acc[0]
+          acc[1] = c[1] if c[1] < acc[1]
+          acc[2] = c[2] if c[2] > acc[2]
+          acc[3] = c[3] if c[3] > acc[3]
+        end
+      end
+
+      # Ricostruisce righe o colonne. axis 0 = x (per row clustering antiaxis=top),
+      # axis 1 = top (per column clustering antiaxis=x0). Usa il key invariante
+      # come "anchor" e il key variabile come ordering interno.
+      def rows_or_columns(kind)
+        # Per row: sortBy = top, antiaxis = x0
+        # Per col: sortBy = x0, antiaxis = top
+        sort_idx, group_idx = kind == :row ? [1, 0] : [0, 1]
+
+        # Tutti gli x0 (per row) o top (per col) distinti, sortati
+        all_keys = @cells.map { |c| c[group_idx] }.uniq.sort
+
+        # Group by sort_idx
+        sorted_cells = @cells.sort_by { |c| [c[sort_idx], c[group_idx]] }
+        grouped = sorted_cells.chunk_while { |a, b| a[sort_idx] == b[sort_idx] }.to_a
+
+        grouped.map do |group_cells|
+          by_anchor = group_cells.to_h { |c| [c[group_idx], c] }
+          all_keys.map { |k| by_anchor[k] }
+        end
+      end
+    end
+  end
+end

data/lib/rpdfium/util/cluster.rb

@@ -0,0 +1,143 @@
+# frozen_string_literal: true
+
+module Rpdfium
+  module Util
+    # Primitive di clustering 1D usate da tutto il pipeline tabellare.
+    # Mappa diretta su `pdfplumber.utils.clustering` (cluster_list,
+    # cluster_objects, make_cluster_dict).
+    #
+    # PROPRIETÀ CHIAVE: questi cluster sono "1D agglomerative single-linkage":
+    # due valori finiscono nello stesso cluster se sono entro `tolerance` da
+    # un valore qualsiasi del cluster. NON solo dal centro/media. Ne consegue
+    # che catene di valori ravvicinati possono estendere il cluster ben oltre
+    # `tolerance` (questo è esattamente il comportamento di pdfplumber, e su
+    # cui si appoggiano le sue euristiche edge/intersection).
+    module Cluster
+      module_function
+
+      # Raggruppa valori scalari in cluster. I valori dentro lo stesso cluster
+      # sono entro `tolerance` da almeno un altro valore del cluster.
+      #
+      # Esempio:
+      #   cluster_list([1.0, 1.5, 2.0, 5.0], tolerance: 1.0)
+      #   #=> [[1.0, 1.5, 2.0], [5.0]]
+      #
+      # NOTA: Catene "stepping stone": [1, 2, 3, 4] con tol=1 fanno UN cluster
+      # solo, anche se 1 e 4 distano 3. Questo è il comportamento di
+      # pdfplumber, è documentato nei suoi issue come potenzialmente
+      # sorprendente ma intenzionale. Lo manteniamo identico.
+      def cluster_list(values, tolerance: 0)
+        return [] if values.empty?
+
+        sorted = values.sort
+        clusters = [[sorted.first]]
+        sorted[1..].each do |v|
+          if (v - clusters.last.last).abs <= tolerance
+            clusters.last << v
+          else
+            clusters << [v]
+          end
+        end
+        clusters
+      end
+
+      # Raggruppa oggetti (Hash) in cluster basandosi su una funzione di
+      # estrazione `key_fn` (oppure simbolo Hash key) e tolleranza.
+      #
+      # Esempio:
+      #   cluster_objects(words, ->(w) { w[:top] }, tolerance: 1)
+      #   cluster_objects(words, :top, tolerance: 1)   # syntactic sugar
+      def cluster_objects(objects, key_fn, tolerance: 0, presorted: false)
+        return [] if objects.empty?
+
+        # Fast path per il caso Symbol più comune (:top, :x0, :bottom):
+        # accesso diretto Hash[symbol] è ~2× più veloce della lambda call.
+        if key_fn.is_a?(Symbol)
+          # Se il chiamante garantisce che l'input è già sortato per key_fn
+          # (es. perché viene da un sort lessicografico [key_fn, ...]) si
+          # può saltare il sort interno. Risparmio significativo quando
+          # cluster_objects è chiamato in loop su molte righe piccole.
+          sorted = presorted ? objects : objects.sort_by { |o| o[key_fn] }
+          first = sorted.first
+          last_key = first[key_fn]
+          clusters = [[first]]
+          tol = tolerance.to_f
+          i = 1
+          n = sorted.size
+          while i < n
+            obj = sorted[i]
+            curr_key = obj[key_fn]
+            if (curr_key - last_key).abs <= tol
+              clusters.last << obj
+            else
+              clusters << [obj]
+            end
+            last_key = curr_key
+            i += 1
+          end
+          return clusters
+        end
+
+        # Path generico con accessor callable
+        accessor = key_fn
+        sorted = presorted ? objects : objects.sort_by { |o| accessor.call(o) }
+        last_key = accessor.call(sorted.first)
+        clusters = [[sorted.first]]
+
+        sorted[1..].each do |obj|
+          curr_key = accessor.call(obj)
+          if (curr_key - last_key).abs <= tolerance
+            clusters.last << obj
+          else
+            clusters << [obj]
+          end
+          last_key = curr_key
+        end
+        clusters
+      end
+
+      # bbox = [x0, top, x1, bottom] (top-down). Ritorna la bbox che racchiude
+      # tutti gli oggetti passati. Usa min/max di x0/top/x1/bottom.
+      def objects_to_bbox(objects)
+        objects.each_with_object(
+          [Float::INFINITY, Float::INFINITY, -Float::INFINITY, -Float::INFINITY]
+        ) do |o, acc|
+          acc[0] = o[:x0]     if o[:x0]     < acc[0]
+          acc[1] = o[:top]    if o[:top]    < acc[1]
+          acc[2] = o[:x1]     if o[:x1]     > acc[2]
+          acc[3] = o[:bottom] if o[:bottom] > acc[3]
+        end
+      end
+
+      # Variante che ritorna un Hash invece di tuple — comoda nel contesto
+      # edge dove ci serve mescolare bbox+orientation.
+      def objects_to_rect(objects)
+        x0, top, x1, bottom = objects_to_bbox(objects)
+        { x0: x0, top: top, x1: x1, bottom: bottom,
+          width: x1 - x0, height: bottom - top }
+      end
+
+      # bbox sovrapposti. None overlap => nil. Match pdfplumber's
+      # get_bbox_overlap: ritorna la bbox di intersezione, oppure nil.
+      def bbox_overlap(a, b)
+        ax0, atop, ax1, abot = a
+        bx0, btop, bx1, bbot = b
+        x0 = [ax0, bx0].max
+        x1 = [ax1, bx1].min
+        return nil if x0 >= x1
+
+        top = [atop, btop].max
+        bot = [abot, bbot].min
+        return nil if top >= bot
+
+        [x0, top, x1, bot]
+      end
+
+      # True se due bbox si sovrappongono (anche solo a un punto è no, deve
+      # esserci area positiva).
+      def bbox_overlaps?(a, b)
+        !bbox_overlap(a, b).nil?
+      end
+    end
+  end
+end