rpdfium 0.4.1

data/lib/rpdfium/util/column_inference.rb

@@ -0,0 +1,139 @@
+# frozen_string_literal: true
+
+module Rpdfium
+  module Util
+    # Inferenza di colonne dati su PDF non-tabellari.
+    #
+    # Identifica gruppi di word che appartengono alla stessa "colonna"
+    # verticale di un layout (es. una colonna di importi in un modulo
+    # prestampato) anche quando non ci sono linee disegnate.
+    #
+    # L'algoritmo opera in tre passaggi:
+    #
+    # 1. **Cluster per coordinata X** — raggruppa le word con la stessa x0
+    #    (left-aligned) o x1 (right-aligned, tipico dei numeri) entro la
+    #    tolleranza configurabile.
+    #
+    # 2. **Spezza per gap verticali** — se due word consecutive in un
+    #    gruppo hanno un gap verticale "anomalo" (> 3× la mediana, o
+    #    > 40pt), le separa in colonne distinte. Risolve casi tipo "codice
+    #    fiscale in alto + tabella sotto" che condividono la stessa X.
+    #
+    # 3. **Filtra per densità** — una colonna "vera" ha valori regolarmente
+    #    equispaziati (coefficiente di variazione dei gap < soglia). Esclude
+    #    falsi positivi come valori isolati che si trovano per caso allineati.
+    #
+    # @example
+    #   inference = Rpdfium::Util::ColumnInference.new(
+    #     x_tolerance: 3.0,
+    #     min_size: 3,
+    #     cv_threshold: 0.15
+    #   )
+    #   columns = inference.infer(words)
+    #   # => [
+    #   #   [word1, word2, ..., word12],   # 12 importi nella colonna 1
+    #   #   [word1, word2, ..., word12]    # 12 codici nella colonna 2
+    #   # ]
+    class ColumnInference
+      DEFAULT_X_TOLERANCE = 3.0
+      DEFAULT_MIN_SIZE = 3
+      DEFAULT_CV_THRESHOLD = 0.15
+      DEFAULT_GAP_MULTIPLIER = 3.0
+      DEFAULT_GAP_ABSOLUTE = 40.0
+
+      def initialize(x_tolerance: DEFAULT_X_TOLERANCE,
+                     min_size: DEFAULT_MIN_SIZE,
+                     cv_threshold: DEFAULT_CV_THRESHOLD,
+                     gap_multiplier: DEFAULT_GAP_MULTIPLIER,
+                     gap_absolute: DEFAULT_GAP_ABSOLUTE)
+        @x_tolerance = x_tolerance
+        @min_size = min_size
+        @cv_threshold = cv_threshold
+        @gap_multiplier = gap_multiplier
+        @gap_absolute = gap_absolute
+      end
+
+      # Inferisce le colonne dai word forniti. Usa sia x0 (left-align) che
+      # x1 (right-align) come criteri di allineamento, ritorna l'unione
+      # delle colonne identificate.
+      #
+      # @param words [Array<Hash>] word con :x0, :x1, :top
+      # @return [Array<Array<Hash>>] array di colonne, ognuna è un array
+      #   di word ordinati per :top crescente
+      def infer(words)
+        return [] if words.empty?
+
+        by_x0 = cluster_by(words, :x0)
+        by_x1 = cluster_by(words, :x1)
+
+        # Unione: una word può apparire in più colonne. È compito del
+        # chiamante decidere come gestire (es. preferire la prima
+        # colonna, o quella più grande). Qui ritorniamo tutte.
+        (by_x0 + by_x1)
+      end
+
+      # Cluster di word per una specifica coordinata.
+      # @param coord [Symbol] :x0 o :x1
+      def cluster_by(words, coord)
+        sorted = words.sort_by { |v| v[coord] }
+        x_groups = []
+        current = []
+        sorted.each do |v|
+          if current.empty? || (v[coord] - current.last[coord]).abs <= @x_tolerance
+            current << v
+          else
+            x_groups << current
+            current = [v]
+          end
+        end
+        x_groups << current
+
+        columns = []
+        x_groups.each do |group|
+          sorted_y = group.sort_by { |v| v[:top] }
+          gaps = sorted_y.each_cons(2).map { |a, b| b[:top] - a[:top] }
+
+          if gaps.empty?
+            columns << sorted_y if dense_enough?(sorted_y)
+            next
+          end
+
+          median_gap = gaps.sort[gaps.size / 2]
+          threshold = [median_gap * @gap_multiplier, @gap_absolute].max
+
+          sub = [sorted_y.first]
+          sorted_y.each_cons(2) do |a, b|
+            gap = b[:top] - a[:top]
+            if gap > threshold
+              columns << sub if dense_enough?(sub)
+              sub = [b]
+            else
+              sub << b
+            end
+          end
+          columns << sub if dense_enough?(sub)
+        end
+        columns
+      end
+
+      # Una colonna è "abbastanza densa" se ha almeno min_size valori e
+      # il coefficiente di variazione (std_dev/mean) dei gap verticali è
+      # sotto la soglia. CV bassa = spacing regolare = colonna ripetitiva
+      # vera (vs. valori sparsi accidentalmente allineati).
+      def dense_enough?(col_values)
+        return false if col_values.size < @min_size
+
+        sorted_y = col_values.sort_by { |v| v[:top] }
+        gaps = sorted_y.each_cons(2).map { |a, b| b[:top] - a[:top] }
+        return true if gaps.size < 2
+
+        mean = gaps.sum / gaps.size.to_f
+        variance = gaps.map { |g| (g - mean)**2 }.sum / gaps.size
+        std_dev = Math.sqrt(variance)
+        cv = mean.zero? ? Float::INFINITY : std_dev / mean
+
+        cv < @cv_threshold
+      end
+    end
+  end
+end

data/lib/rpdfium/util/label_matcher.rb

@@ -0,0 +1,214 @@
+# frozen_string_literal: true
+
+module Rpdfium
+  module Util
+    # Associa label semantiche a valori inseriti su PDF di moduli compilati
+    # (F24, comunicazioni IVA, modelli 770) dove template e dati coesistono
+    # come testo grafico in font diversi.
+    #
+    # Strategia base:
+    #
+    # 1. **Cluster** le parole del template in "label coerenti": word
+    #    geometricamente vicine formano un'unica label.
+    #
+    # 2. **Per ogni valore** cerca:
+    #    - `:col` — label SOPRA in stessa colonna
+    #    - `:row` — label A SINISTRA in stessa riga
+    #
+    # 3. (Opzionale) **Riassegnazione per colonne**: usa `ColumnInference`
+    #    per identificare colonne ripetitive (es. ST2..ST13 del 770 Quadro
+    #    ST) e propaga l'header canonico a tutti i valori della colonna,
+    #    superando il limite `col_max_dy`.
+    #
+    # @example uso base
+    #   matcher = Rpdfium::Util::LabelMatcher.new
+    #   matcher.match(value_words, anchor_words)
+    #
+    # @example con tabelle ripetitive (header in cima alla colonna)
+    #   matcher = Rpdfium::Util::LabelMatcher.new(
+    #     column_inference: Rpdfium::Util::ColumnInference.new
+    #   )
+    #   matcher.match(value_words, anchor_words)
+    class LabelMatcher
+      DEFAULT_COL_MAX_DY = 80.0
+      DEFAULT_ROW_MAX_DX = 200.0
+      DEFAULT_COL_X_TOLERANCE = 10.0
+      DEFAULT_ROW_Y_TOLERANCE = 2.0
+      DEFAULT_CLUSTER_SAME_ROW_DY = 4.0
+      DEFAULT_CLUSTER_SAME_ROW_DX = 12.0
+      DEFAULT_CLUSTER_ADJ_ROW_DY = 4.0
+      DEFAULT_IGNORE_LABEL_PATTERN = /\A\d{1,3}\z|\A[IVX]{1,5}\z/.freeze
+      WIDE_VALUE_THRESHOLD = 60.0
+
+      def initialize(col_max_dy: DEFAULT_COL_MAX_DY,
+                     row_max_dx: DEFAULT_ROW_MAX_DX,
+                     col_x_tolerance: DEFAULT_COL_X_TOLERANCE,
+                     row_y_tolerance: DEFAULT_ROW_Y_TOLERANCE,
+                     cluster_same_row_dy: DEFAULT_CLUSTER_SAME_ROW_DY,
+                     cluster_same_row_dx: DEFAULT_CLUSTER_SAME_ROW_DX,
+                     cluster_adj_row_dy: DEFAULT_CLUSTER_ADJ_ROW_DY,
+                     ignore_label_pattern: DEFAULT_IGNORE_LABEL_PATTERN,
+                     column_inference: nil)
+        @col_max_dy = col_max_dy
+        @row_max_dx = row_max_dx
+        @col_x_tolerance = col_x_tolerance
+        @row_y_tolerance = row_y_tolerance
+        @cluster_same_row_dy = cluster_same_row_dy
+        @cluster_same_row_dx = cluster_same_row_dx
+        @cluster_adj_row_dy = cluster_adj_row_dy
+        @ignore_label_pattern = ignore_label_pattern
+        @column_inference = column_inference
+      end
+
+      # Calcola le associazioni label → valore.
+      #
+      # @param values [Array<Hash>] word del layer "dati"
+      # @param anchors [Array<Hash>] word del layer "template"
+      # @return [Array<Hash>] uno per valore: { value:, labels: { col:, row: }, geometry: }
+      def match(values, anchors)
+        labels = cluster_anchors(anchors)
+
+        prelim = values.map do |v|
+          col = find_col_label(v, labels)
+          row = find_row_label(v, labels)
+          { value: v, col: col, row: row }
+        end
+
+        # Riassegnazione opzionale per colonne ripetitive
+        prelim = reassign_by_columns(prelim, labels, values) if @column_inference
+
+        prelim.map do |entry|
+          v = entry[:value]
+          {
+            value: v[:text],
+            labels: {
+              col: entry[:col]&.dig(:text),
+              row: entry[:row]&.dig(:text)
+            },
+            geometry: {
+              x0: v[:x0], x1: v[:x1], top: v[:top], bottom: v[:bottom]
+            }
+          }
+        end
+      end
+
+      # Ricostruisce le label dal cluster delle word del template.
+      # Esposto pubblicamente per ispezione/debug.
+      def cluster_anchors(anchor_words)
+        remaining = anchor_words.dup
+        groups = []
+        until remaining.empty?
+          seed = remaining.shift
+          group = [seed]
+          grew = true
+          while grew
+            grew = false
+            remaining.dup.each do |w|
+              close = group.any? do |g|
+                dx_horiz = [w[:x0] - g[:x1], g[:x0] - w[:x1]].max
+                same_row = (w[:top] - g[:top]).abs < @cluster_same_row_dy &&
+                           dx_horiz < @cluster_same_row_dx
+                dy_above = (g[:top] - w[:bottom]).abs
+                dy_below = (w[:top] - g[:bottom]).abs
+                vertical_adjacent = [dy_above, dy_below].min < @cluster_adj_row_dy
+                x_overlap = !(w[:x1] < g[:x0] - 3 || w[:x0] > g[:x1] + 3)
+                adj_row = vertical_adjacent && x_overlap
+                same_row || adj_row
+              end
+              if close
+                group << w
+                remaining.delete(w)
+                grew = true
+              end
+            end
+          end
+          groups << group
+        end
+        labels = groups.map { |g| group_to_label(g) }
+        if @ignore_label_pattern
+          labels = labels.reject { |l| l[:text].match?(@ignore_label_pattern) }
+        end
+        labels
+      end
+
+      private
+
+      def group_to_label(group)
+        sorted = group.sort_by { |w| [w[:top].round(0), w[:x0]] }
+        {
+          text: sorted.map { |w| w[:text] }.join(" "),
+          x0: group.map { |w| w[:x0] }.min,
+          x1: group.map { |w| w[:x1] }.max,
+          top: group.map { |w| w[:top] }.min,
+          bottom: group.map { |w| w[:bottom] }.max
+        }
+      end
+
+      def find_col_label(value, labels)
+        # Per word "wide" (più larghe della maggior parte delle label,
+        # tipicamente perché frutto di merge di una stringa che attraversa
+        # più colonne template) usa il left edge: la label corretta è
+        # quella sotto cui INIZIA il valore.
+        value_width = value[:x1] - value[:x0]
+        anchor_point =
+          if value_width > WIDE_VALUE_THRESHOLD
+            value[:x0] + 5.0
+          else
+            (value[:x0] + value[:x1]) / 2.0
+          end
+
+        labels.select do |l|
+          l[:x0] - @col_x_tolerance <= anchor_point &&
+            l[:x1] + @col_x_tolerance >= anchor_point &&
+            l[:bottom] < value[:top] &&
+            (value[:top] - l[:bottom]) <= @col_max_dy
+        end.min_by { |l| value[:top] - l[:bottom] }
+      end
+
+      def find_row_label(value, labels)
+        vy = (value[:top] + value[:bottom]) / 2.0
+        labels.select do |l|
+          l[:top] <= vy &&
+            l[:bottom] >= vy - @row_y_tolerance &&
+            l[:x1] < value[:x0] &&
+            (value[:x0] - l[:x1]) <= @row_max_dx
+        end.max_by { |l| l[:x1] }
+      end
+
+      # Identifica colonne dati e propaga l'header canonico stampato in
+      # cima alla colonna a TUTTI i valori della colonna.
+      # Usa @column_inference fornito al constructor.
+      def reassign_by_columns(prelim, labels, values)
+        columns = @column_inference.infer(values)
+        return prelim if columns.empty?
+
+        # Ordina colonne più grandi prima (più evidenza statistica)
+        sorted_columns = columns.sort_by { |c| -c.size }
+
+        column_headers = {}
+        sorted_columns.each do |col_values|
+          col_top = col_values.map { |v| v[:top] }.min
+          anchor_x = col_values.map { |v| (v[:x0] + v[:x1]) / 2.0 }.sum / col_values.size
+
+          header = labels.select do |l|
+            l[:x0] - @col_x_tolerance <= anchor_x &&
+              l[:x1] + @col_x_tolerance >= anchor_x &&
+              l[:bottom] <= col_top + 1
+          end.min_by { |l| col_top - l[:bottom] }
+
+          next unless header
+
+          col_values.each do |v|
+            column_headers[v.object_id] ||= header
+          end
+        end
+
+        prelim.map do |entry|
+          v = entry[:value]
+          new_col = column_headers[v.object_id]
+          new_col ? entry.merge(col: new_col) : entry
+        end
+      end
+    end
+  end
+end

data/lib/rpdfium/util/text_extraction.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module Rpdfium
+  module Util
+    # Estrazione testo "lineare" da una collezione di char, layout=False.
+    # Equivalente di pdfplumber.utils.text.chars_to_textmap nella variante
+    # senza preservazione del layout grafico.
+    #
+    # Algoritmo:
+    #   1. Estrai words con WordExtractor (gli stessi tolerance).
+    #   2. Cluster di words per `top` con y_tolerance → righe logiche.
+    #   3. Per ogni riga, ordina per x0 e joina con singolo spazio.
+    #   4. Joina le righe con "\n".
+    #
+    # NOTA su una sottigliezza: pdfplumber permette di usare x_tolerance
+    # diverso da y_tolerance sia per word-extraction che per line-clustering.
+    # Replichiamo questa flessibilità.
+    module TextExtraction
+      module_function
+
+      DEFAULT_X_TOLERANCE = WordExtractor::DEFAULT_X_TOLERANCE
+      DEFAULT_Y_TOLERANCE = WordExtractor::DEFAULT_Y_TOLERANCE
+
+      def extract_text(chars,
+                       x_tolerance: DEFAULT_X_TOLERANCE,
+                       y_tolerance: DEFAULT_Y_TOLERANCE,
+                       keep_blank_chars: false)
+        return "" if chars.empty?
+
+        words = WordExtractor.new(
+          x_tolerance: x_tolerance,
+          y_tolerance: y_tolerance,
+          keep_blank_chars: keep_blank_chars
+        ).extract_words(chars)
+        return "" if words.empty?
+
+        # Cluster delle WORDS per top: righe di output finali.
+        # Usa y_tolerance "di linea" — pdfplumber qui usa la stessa y_tolerance
+        # passata, ed è coerente con come si comporta extract_text.
+        line_clusters = Cluster.cluster_objects(words, :top, tolerance: y_tolerance)
+
+        # Per ogni riga di output joina con spazio singolo.
+        line_clusters.map do |line_words|
+          line_words.sort_by { |w| w[:x0] }.map { |w| w[:text] }.join(" ")
+        end.join("\n")
+      end
+    end
+  end
+end

data/lib/rpdfium/util/word_extractor.rb

@@ -0,0 +1,151 @@
+# frozen_string_literal: true
+
+module Rpdfium
+  module Util
+    # Estrae "words" da una lista di char, fedelmente a pdfplumber.WordExtractor.
+    #
+    # Algoritmo:
+    #   1. Ordina i char per (top, x0): righe top-to-bottom, char left-to-right
+    #      dentro ogni riga.
+    #   2. Cluster per top con `y_tolerance` → "righe logiche" di char.
+    #   3. Dentro ogni riga, cluster per gap orizzontale: due char sono nella
+    #      stessa word se `next.x0 - prev.x1 <= x_tolerance`. Anche un char
+    #      whitespace separa la word (a meno che `keep_blank_chars`).
+    #   4. Per ogni cluster di char emette una word: text concatenato, bbox.
+    #
+    # Differenze da pdfplumber (semplificazioni accettabili per il nostro uso):
+    #   - Non gestiamo `line_dir`/`char_dir` rotated (testo ruotato non
+    #     orizzontale ltr): non rilevante per i casi d'uso correnti.
+    #   - Non gestiamo `use_text_flow` (ordering basato sul content stream):
+    #     i nostri char arrivano già da PDFium nell'ordine geometrico via
+    #     `chars` (top, x0).
+    #   - Non gestiamo `expand_ligatures`: PDFium di solito espande i
+    #     codepoint correttamente già a livello char.
+    #
+    # Queste differenze sono documentate; se mai necessarie si aggiungono
+    # come feature toggles senza cambiare il path di default.
+    class WordExtractor
+      DEFAULT_X_TOLERANCE = 3.0
+      DEFAULT_Y_TOLERANCE = 3.0
+
+      attr_reader :x_tolerance, :y_tolerance, :keep_blank_chars
+
+      def initialize(x_tolerance: DEFAULT_X_TOLERANCE,
+                     y_tolerance: DEFAULT_Y_TOLERANCE,
+                     keep_blank_chars: false,
+                     extra_attrs: nil)
+        @x_tolerance = x_tolerance.to_f
+        @y_tolerance = y_tolerance.to_f
+        @keep_blank_chars = keep_blank_chars
+        @extra_attrs = extra_attrs || []
+      end
+
+      # Restituisce un Array di Hash: { text:, x0:, x1:, top:, bottom:, chars: }.
+      # Se `extra_attrs` è non vuoto, ogni word splitta anche al cambio di
+      # questi attributi (es. fontname/size diversi → word diverse).
+      def extract_words(chars)
+        return [] if chars.empty?
+
+        # Fast path: 1 solo char → 1 word triviale (se non whitespace).
+        if chars.size == 1
+          c = chars.first
+          return [] if blank?(c) && !@keep_blank_chars
+
+          return [build_word([c])]
+        end
+
+        # 1. Ordina per (top, x0). Top-down, left-to-right.
+        sorted = chars.sort_by { |c| [c[:top], c[:x0]] }
+
+        # 2. Cluster in righe per `top`.
+        # `presorted: true`: sorted è già ordinato per [top, x0], quindi
+        # implicitamente anche per top — cluster_objects salta il proprio
+        # sort interno.
+        rows = Cluster.cluster_objects(sorted, :top,
+                                        tolerance: @y_tolerance,
+                                        presorted: true)
+
+        words = []
+        rows.each do |row|
+          # Re-sort per x0 dentro ogni riga clusterizzata.
+          #
+          # NOTA: in linea di principio l'input `sorted` è già ordinato per
+          # [top, x0], quindi i cluster di top dovrebbero essere già in
+          # ordine x0. MA il sort globale `[top, x0]` rispetta strettamente
+          # l'ordine per top — se due char della stessa riga visiva hanno
+          # top diversi entro tolerance (es. la "i" minuscola spesso ha
+          # top più alto di 0.008pt rispetto alle altre lettere a causa di
+          # come PDFium calcola la bbox), il sort globale li interfoglia.
+          # Il cluster_objects per :top non riordina internamente i char,
+          # quindi un char con top leggermente minore finisce DAVANTI a
+          # tutte le altre lettere della parola.
+          #
+          # Esempio reale: "Categoria" dove "i" ha top=414.9789 e le altre
+          # 414.9869 → output `iCategora` invece di `Categoria`.
+          # Il fix è semplicemente ri-sortare per x0 dentro la riga.
+          row_sorted = row.sort_by { |c| c[:x0] }
+
+          word_chars = []
+          row_sorted.each do |c|
+            if char_begins_new_word?(word_chars.last, c)
+              words << build_word(word_chars) unless word_chars.empty?
+              word_chars = []
+            end
+            # Whitespace: per default lo usiamo come separatore (lo scartiamo).
+            # Con keep_blank_chars=true lo includiamo nella word corrente.
+            if blank?(c) && !@keep_blank_chars
+              words << build_word(word_chars) unless word_chars.empty?
+              word_chars = []
+            else
+              word_chars << c
+            end
+          end
+          words << build_word(word_chars) unless word_chars.empty?
+        end
+
+        words
+      end
+
+      private
+
+      def char_begins_new_word?(prev, curr)
+        return false if prev.nil?
+
+        # Gap orizzontale (PDF font hinting può dare overlap leggero, max 0)
+        gap = curr[:x0] - prev[:x1]
+        return true if gap > @x_tolerance
+
+        # Cambio di riga (può succedere se y_tolerance è grande ma due
+        # char sono comunque su righe diverse)
+        return true if (curr[:top] - prev[:top]).abs > @y_tolerance
+
+        # Cambio di un extra_attr richiesto
+        @extra_attrs.any? { |attr| prev[attr] != curr[attr] }
+      end
+
+      def blank?(c)
+        c[:char].nil? || c[:char].match?(/\A\s\z/) || c[:generated]
+      end
+
+      def build_word(chars)
+        text   = +""
+        x0     =  Float::INFINITY
+        x1     = -Float::INFINITY
+        top    =  Float::INFINITY
+        bottom = -Float::INFINITY
+
+        chars.each do |c|
+          text   << c[:char]
+          x0     = c[:x0]     if c[:x0]     < x0
+          x1     = c[:x1]     if c[:x1]     > x1
+          top    = c[:top]    if c[:top]    < top
+          bottom = c[:bottom] if c[:bottom] > bottom
+        end
+
+        word = { text: text, x0: x0, x1: x1, top: top, bottom: bottom, chars: chars }
+        @extra_attrs.each { |a| word[a] = chars.first[a] }
+        word
+      end
+    end
+  end
+end

data/lib/rpdfium/util/word_merger.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+module Rpdfium
+  module Util
+    # Fonde word adiacenti sulla stessa riga in un'unica word con bbox
+    # aggregata e text concatenato.
+    #
+    # Tre strategie disponibili come metodi separati:
+    #
+    # - `merge_by_proximity` — fonde tutte le word adiacenti che soddisfano
+    #   il criterio di vicinanza. Strategia base.
+    #
+    # - `merge_by_label` — fonde solo word che condividono la stessa "label"
+    #   (chiave esterna calcolata dal chiamante). Utile per preservare la
+    #   semantica quando label diverse cadono sulla stessa riga (es. flag
+    #   in colonne adiacenti).
+    #
+    # - `merge_unlabeled` — fonde solo word "orfane" (label nil) lasciando
+    #   intatte quelle con label. Inverso di merge_by_label.
+    #
+    # Tutte ritornano una nuova lista di word, con quelle fuse rappresentate
+    # come hash `{ text:, x0:, x1:, top:, bottom: }`.
+    #
+    # @example merge per proximity
+    #   merger = Rpdfium::Util::WordMerger.new(x_gap: 20.0, y_tol: 3.0)
+    #   merged = merger.merge_by_proximity(words)
+    #
+    # @example merge per label, con label fornita dal chiamante
+    #   labels_by_word = words.each_with_object({}) { |w, h| h[w] = compute_label(w) }
+    #   merged = merger.merge_by_label(words, labels_by_word)
+    class WordMerger
+      DEFAULT_X_GAP = 20.0
+      DEFAULT_Y_TOL = 3.0
+
+      def initialize(x_gap: DEFAULT_X_GAP, y_tol: DEFAULT_Y_TOL)
+        @x_gap = x_gap
+        @y_tol = y_tol
+      end
+
+      # Fonde tutte le word adiacenti (stessa riga + gap orizzontale ≤ x_gap).
+      def merge_by_proximity(words)
+        merge_groups(words) { |a, b| true }
+      end
+
+      # Fonde solo word con la stessa label.
+      # @param labels_by_word [Hash] mapping word → label (qualunque tipo).
+      #   Word con stessa label vengono fuse, word con label diverse no.
+      def merge_by_label(words, labels_by_word)
+        merge_groups(words) do |a, b|
+          labels_by_word[a] == labels_by_word[b]
+        end
+      end
+
+      # Fonde solo word con label nil (orfane).
+      def merge_unlabeled(words, labels_by_word)
+        merge_groups(words) do |a, b|
+          labels_by_word[a].nil? && labels_by_word[b].nil?
+        end
+      end
+
+      private
+
+      # Algoritmo generico di merging: scorre i word ordinati per (top, x0)
+      # e li raggruppa quando soddisfano sia il criterio geometrico
+      # (stessa riga e gap orizzontale stretto) che il predicato `yield`
+      # fornito dal chiamante.
+      def merge_groups(words)
+        return [] if words.empty?
+
+        sorted = words.sort_by { |w| [w[:top].round(1), w[:x0]] }
+        groups = []
+        current = [sorted.first]
+        sorted.drop(1).each do |w|
+          prev = current.last
+          on_same_row = (w[:top] - prev[:top]).abs <= @y_tol
+          adjacent = w[:x0] - prev[:x1] <= @x_gap && w[:x0] >= prev[:x0]
+          if on_same_row && adjacent && yield(prev, w)
+            current << w
+          else
+            groups << current
+            current = [w]
+          end
+        end
+        groups << current
+
+        groups.map { |g| merge_group(g) }
+      end
+
+      def merge_group(group)
+        return group.first if group.size == 1
+
+        {
+          text: group.map { |w| w[:text] }.join(" "),
+          x0: group.map { |w| w[:x0] }.min,
+          x1: group.map { |w| w[:x1] }.max,
+          top: group.map { |w| w[:top] }.min,
+          bottom: group.map { |w| w[:bottom] }.max
+        }
+      end
+    end
+  end
+end

data/lib/rpdfium/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Rpdfium
+  VERSION = "0.4.1"
+end