rpdfium 0.4.1

data/lib/rpdfium/structure/tree.rb

@@ -0,0 +1,202 @@
+# frozen_string_literal: true
+
+module Rpdfium
+  module Structure
+    # StructTree di una pagina PDF tagged.
+    #
+    # Per PDF tagged (PDF/UA, esport accessibility-friendly da
+    # Word/LibreOffice/InDesign), espone la struttura logica del documento:
+    # Document → P, H1, Table, TR, TH, TD, Figure, ecc.
+    #
+    # Per PDF NON tagged, `Page#struct_tree` ritorna nil. Per PDF "tagged
+    # ma vuoti" (es. CR Banca d'Italia, StructTreeRoot presente ma con
+    # element placeholder senza type/MCID), `Tree#empty?` ritorna true.
+    #
+    # Lifecycle: il Tree mantiene un handle PDFium che è "owning" — chiamare
+    # `FPDF_StructTree_Close` lo dealloca. PDFium dealloca automaticamente
+    # lo struct tree alla chiusura del documento, quindi in pratica:
+    #
+    #   - se non chiudi mai il tree esplicitamente, PDFium lo libera con
+    #     `FPDF_CloseDocument` (zero perdita persistente, ma il tree resta
+    #     in memoria fino alla chiusura del doc — può essere ~MB)
+    #   - per controllo deterministico (rilascia subito), usa il blocco:
+    #
+    #       page.struct_tree do |tree|
+    #         tree.walk { |el| ... }
+    #       end
+    #     all'uscita dal blocco il tree viene chiuso, anche su eccezione.
+    #
+    # Per scelta progettuale NON usiamo `ObjectSpace.define_finalizer`: se
+    # il GC chiamasse `FPDF_StructTree_Close` dopo che il documento è già
+    # stato chiuso, si avrebbe un use-after-free → segfault. La chiusura
+    # via Document è sempre sicura; la chiusura via Tree.close (esplicita
+    # o tramite blocco) richiede che il documento sia ancora vivo.
+    class Tree
+      attr_reader :handle, :page
+
+      # Ritorna nil se la pagina non è tagged. Altrimenti un Tree.
+      def self.for_page(page)
+        h = Raw.FPDF_StructTree_GetForPage(page.handle)
+        return nil if h.null?
+
+        new(page, h)
+      end
+
+      def initialize(page, handle)
+        @page = page
+        @handle = handle
+        @closed = false
+        @mcid_text_cache = nil
+
+        # NOTA: niente finalizer. FPDF_StructTree_Close è "owning": chiama
+        # ~CPDF_StructTree() che libera l'oggetto. Se il documento PDF
+        # viene chiuso prima del tree, il finalizer GC chiamerebbe Close
+        # su memoria già liberata → segfault. Lifetime sicuro:
+        #   - close esplicito via `tree.close` o via blocco
+        #     `page.struct_tree { |tree| ... }`
+        #   - se nessuno chiude esplicitamente, PDFium libera il tree
+        #     insieme al documento al `FPDF_CloseDocument` (no leak
+        #     persistent, solo riserva memoria fino a chiusura doc)
+      end
+
+      def closed?
+        @closed
+      end
+
+      # Chiusura esplicita (idempotente). Dopo close, non chiamare metodi
+      # su questo Tree né sugli Element che ha generato.
+      def close
+        return if @closed
+
+        Raw.FPDF_StructTree_Close(@handle)
+        @closed = true
+        @mcid_text_cache = nil
+      end
+
+      # Numero di element root (figli diretti del StructTreeRoot per
+      # questa pagina). Tipicamente 1 (`<Document>`), ma può essere
+      # arbitrariamente alto su PDF strani (es. cu.pdf: 717 placeholder).
+      def root_count
+        n = Raw.FPDF_StructTree_CountChildren(@handle)
+        [n, 0].max
+      end
+
+      # Element root (figli diretti del StructTreeRoot). Tipicamente 1
+      # (`<Document>`).
+      def roots
+        (0...root_count).filter_map do |i|
+          h = Raw.FPDF_StructTree_GetChildAtIndex(@handle, i)
+          h.null? ? nil : Element.new(self, h)
+        end
+      end
+
+      # True se il tree è strutturalmente vuoto (nessun element con type
+      # leggibile dai root). Caso comune per PDF "fintamente tagged" come
+      # CR Banca d'Italia: il StructTreeRoot esiste ma gli element sono
+      # placeholder vuoti.
+      def empty?
+        return true if root_count.zero?
+
+        roots.none? { |r| r.type || r.children.any? }
+      end
+
+      # Walk depth-first di TUTTI gli element del tree. Equivalente a
+      # `roots.flat_map(&:walk)`. Senza block ritorna Enumerator.
+      def walk(&block)
+        return enum_for(:walk) unless block
+
+        roots.each { |r| r.walk(&block) }
+      end
+
+      # Trova tutti gli element del tipo specificato (es. "Table", "P",
+      # "Figure"). Confronto case-sensitive (i tipi PDF sono "Table",
+      # "P", "H1", ecc.).
+      def find_all(type:)
+        walk.select { |el| el.type == type }
+      end
+
+      # Restituisce tutti gli element di tipo "Table". Conveniente per
+      # estrazione tabelle semantica.
+      def tables
+        find_all(type: "Table")
+      end
+
+      # Page objects raggruppati per Marked Content ID, per consentire a
+      # Element#text di risolvere il testo dei suoi MCID. La mappa è
+      # costruita una sola volta per Tree e cached.
+      #
+      # Pubblico ma destinato a uso interno; non parte dell'API stabile.
+      def mcid_text_map
+        @mcid_text_cache ||= build_mcid_text_map
+      end
+
+      def to_s
+        "#<Rpdfium::Structure::Tree roots=#{root_count}#{empty? ? ' empty' : ''}>"
+      end
+      alias inspect to_s
+
+      private
+
+      # Itera tutti i page objects (incl. Form XObject) e raggruppa il loro
+      # testo per MCID. Il pattern probe-then-fetch su FPDFTextObj_GetText
+      # è già rodato (vedi Page#read_text_obj_text_fast).
+      def build_mcid_text_map
+        map = Hash.new { |h, k| h[k] = +"" }
+        tp = @page.text_page
+        page_handle = @page.handle
+        buf = FFI::MemoryPointer.new(:uint8, 1024)
+
+        walk_objects = lambda do |handle, is_form|
+          n = is_form ? Raw.FPDFFormObj_CountObjects(handle) : Raw.FPDFPage_CountObjects(handle)
+          n.times do |i|
+            obj = is_form ? Raw.FPDFFormObj_GetObject(handle, i) : Raw.FPDFPage_GetObject(handle, i)
+            next if obj.null?
+
+            obj_type = Raw.FPDFPageObj_GetType(obj)
+            if obj_type == Raw::PAGEOBJ_TEXT
+              mcid = Raw.FPDFPageObj_GetMarkedContentID(obj)
+              if mcid >= 0
+                text = read_text_obj_text(obj, tp, buf)
+                map[mcid] << text if text
+              end
+            elsif obj_type == Raw::PAGEOBJ_FORM
+              walk_objects.call(obj, true)
+            end
+          end
+        end
+
+        walk_objects.call(page_handle, false)
+        map
+      end
+
+      def read_text_obj_text(obj, tp, buf)
+        # Probe con buffer 1024 byte (sufficiente per il 99% dei marked
+        # content runs, che tipicamente sono parole singole o frasi brevi).
+        needed = Raw.FPDFTextObj_GetText(obj, tp.handle, buf, 1024)
+        return nil if needed < 2
+
+        if needed > 1024
+          big = FFI::MemoryPointer.new(:uint8, needed)
+          needed = Raw.FPDFTextObj_GetText(obj, tp.handle, big, needed)
+          return nil if needed < 2
+
+          payload = needed - 2
+          return nil if payload <= 0
+
+          return big.read_bytes(payload)
+                    .force_encoding("UTF-16LE")
+                    .encode("UTF-8", invalid: :replace, undef: :replace)
+                    .delete("\u0000")
+        end
+
+        payload = needed - 2
+        return nil if payload <= 0
+
+        buf.read_bytes(payload)
+           .force_encoding("UTF-16LE")
+           .encode("UTF-8", invalid: :replace, undef: :replace)
+           .delete("\u0000")
+      end
+    end
+  end
+end

data/lib/rpdfium/table/cells.rb

@@ -0,0 +1,137 @@
+# frozen_string_literal: true
+
+module Rpdfium
+  module Table
+    # Costruisce celle da intersezioni e tabelle da celle.
+    # Algoritmi 1:1 con pdfplumber.intersections_to_cells e
+    # pdfplumber.cells_to_tables.
+    module Cells
+      module_function
+
+      # Ricerca della "smallest cell" per ogni intersezione: dato un punto
+      # `pt = (x, y)`, cerca il rettangolo minimo i cui 4 corner sono
+      # intersezioni e i cui 4 lati hanno edge che le connettono.
+      #
+      # Il vincolo "edge connect" è cruciale: due intersezioni con stessa
+      # x non bastano — devono CONDIVIDERE almeno un edge verticale (cioè
+      # appartenere a uno stesso segmento continuo). Idem orizzontale.
+      # Questo evita falsi positivi tipo "due colonne lontane allineate
+      # accidentalmente".
+      #
+      # `intersections` è il Hash prodotto da Edges.edges_to_intersections,
+      # con chiavi `[x, y]` e valori `{ v: [edges...], h: [edges...] }`.
+      def intersections_to_cells(intersections)
+        return [] if intersections.empty?
+
+        # Indici di adiacenza: per ogni edge (oggetto Hash, identità di
+        # ruby), quali intersection points contiene? Pdfplumber lo fa
+        # confrontando bbox degli edge — noi abbiamo accesso diretto agli
+        # oggetti edge dentro `intersections[pt]`, basta usare l'identity.
+        # Per "stesso edge" usiamo `equal?` (identità d'oggetto).
+        edge_ids = intersections.transform_values do |val|
+          { v: val[:v].map(&:object_id).to_set,
+            h: val[:h].map(&:object_id).to_set }
+        end
+
+        edge_connects = lambda do |p1, p2|
+          if p1[0] == p2[0]
+            return !(edge_ids[p1][:v] & edge_ids[p2][:v]).empty?
+          end
+          if p1[1] == p2[1]
+            return !(edge_ids[p1][:h] & edge_ids[p2][:h]).empty?
+          end
+          false
+        end
+
+        points = intersections.keys.sort
+        npoints = points.size
+
+        # Indici spaziali: precomputa punti per colonna (stessa x) e per riga
+        # (stessa y), già ordinati perché `points` è sorted.
+        # Permette lookup O(log n) via bsearch invece di O(n) via select.
+        by_x = Hash.new { |h, k| h[k] = [] }
+        by_y = Hash.new { |h, k| h[k] = [] }
+        points.each { |p| by_x[p[0]] << p; by_y[p[1]] << p }
+
+        cells = []
+        points.each_with_index do |pt, i|
+          next if i == npoints - 1
+
+          # Punti direttamente sotto `pt` (stessa x, y maggiore)
+          col = by_x[pt[0]]
+          below_start = col.bsearch_index { |q| q[1] > pt[1] } || col.size
+          below = col[below_start..]
+
+          # Punti direttamente a destra di `pt` (stessa y, x maggiore)
+          row_pts = by_y[pt[1]]
+          right_start = row_pts.bsearch_index { |q| q[0] > pt[0] } || row_pts.size
+          right = row_pts[right_start..]
+
+          # Cerca il PRIMO (== più piccolo per via dell'ordinamento) bottom-right
+          # i cui 4 corner sono presenti e gli edge connettono.
+          found = nil
+          below.each do |b|
+            next unless edge_connects.call(pt, b)
+
+            right.each do |r|
+              next unless edge_connects.call(pt, r)
+
+              br = [r[0], b[1]]
+              next unless intersections.key?(br)
+              next unless edge_connects.call(br, r)
+              next unless edge_connects.call(br, b)
+
+              found = [pt[0], pt[1], br[0], br[1]]
+              break
+            end
+            break if found
+          end
+          cells << found if found
+        end
+        cells
+      end
+
+      # Raggruppa celle in tabelle in base ai corner condivisi.
+      #
+      # Algoritmo: Union-Find (disjoint set) sui corner — O(n α(n)) invece
+      # del greedy fixed-point O(n²) di pdfplumber. Il risultato è identico:
+      # due celle finiscono nello stesso gruppo se condividono almeno un corner.
+      #
+      # Filtro finale: scarta tabelle con UNA SOLA cella (rumore).
+      def cells_to_tables(cells)
+        return [] if cells.empty?
+
+        n = cells.size
+        parent = Array.new(n) { |i| i }
+
+        find = lambda do |i|
+          i = parent[i] = parent[parent[i]] while parent[i] != i
+          i
+        end
+        union = ->(a, b) { parent[find.call(a)] = find.call(b) }
+
+        # Per ogni corner, raccoglie gli indici delle celle che lo condividono
+        # e le unisce nel medesimo componente.
+        corner_to_cells = Hash.new { |h, k| h[k] = [] }
+        cells.each_with_index do |cell, idx|
+          x0, top, x1, bottom = cell
+          [[x0, top], [x0, bottom], [x1, top], [x1, bottom]].each do |corner|
+            corner_to_cells[corner] << idx
+          end
+        end
+        corner_to_cells.each_value do |idxs|
+          idxs.each_cons(2) { |a, b| union.call(a, b) }
+        end
+
+        # Raggruppa per root del Union-Find
+        groups = Hash.new { |h, k| h[k] = [] }
+        cells.each_with_index { |cell, i| groups[find.call(i)] << cell }
+
+        # Sort top-to-bottom, left-to-right; filtra single-cell.
+        groups.values
+              .sort_by { |t| t.map { |c| [c[1], c[0]] }.min }
+              .reject  { |t| t.size <= 1 }
+      end
+    end
+  end
+end

data/lib/rpdfium/table/debugger.rb

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+
+module Rpdfium
+  module Table
+    # Genera una visualizzazione di debug: la pagina renderizzata in PNG con
+    # sovrapposti gli edges rilevati e i bbox delle celle. Equivalente di
+    # pdfplumber.Page.to_image().debug_tablefinder().
+    #
+    # Implementato puro Ruby: rasterizza la pagina via render(), poi disegna
+    # sopra il bitmap manipolando i bytes RGBA, infine salva in PNG.
+    module Debugger
+      module_function
+
+      RED   = [255, 0, 0, 200].freeze
+      GREEN = [0, 200, 0, 200].freeze
+      BLUE  = [80, 80, 255, 120].freeze
+
+      def visualize(page, output_path, scale: 2.0, **table_opts)
+        extractor = Extractor.new(page, **table_opts)
+        edges = extractor.edges
+        intersections = extractor.intersections
+        tables = extractor.tables
+
+        w, h, bytes, _stride = page.render(scale: scale, output: :rgba)
+        canvas = Canvas.new(w, h, bytes)
+
+        # Disegna edges. Nuovo formato: ogni edge ha orientation + x0/x1/top/bottom.
+        # Un edge orizzontale ha top == bottom; un verticale ha x0 == x1.
+        edges.each do |e|
+          canvas.line((e[:x0] * scale).to_i, (e[:top]    * scale).to_i,
+                       (e[:x1] * scale).to_i, (e[:bottom] * scale).to_i, RED)
+        end
+
+        # Disegna intersezioni (cerchi 4px). Sono Hash con chiave [x, y].
+        intersections.each_key do |(x, y)|
+          canvas.dot((x * scale).to_i, (y * scale).to_i, GREEN, 4)
+        end
+
+        # Riempie tabelle con blu trasparente. Table#bbox è tuple [x0, top, x1, bottom].
+        tables.each do |t|
+          x0, top, x1, bottom = t.bbox
+          canvas.rect_fill((x0 * scale).to_i, (top    * scale).to_i,
+                            (x1 * scale).to_i, (bottom * scale).to_i, BLUE)
+        end
+
+        Rpdfium::IO::PNG.write(output_path, w, h, canvas.bytes, stride: w * 4)
+        output_path
+      end
+    end
+
+    # Mini canvas RGBA per disegnare sopra il rendering. Niente di sofisticato:
+    # linee Bresenham, dots, rect fill con alpha blending semplice.
+    class Canvas
+      attr_reader :bytes, :width, :height
+
+      def initialize(width, height, rgba_bytes)
+        @width  = width
+        @height = height
+        # Lavoriamo su una stringa mutabile (binstring)
+        @bytes = rgba_bytes.dup.force_encoding(Encoding::ASCII_8BIT)
+      end
+
+      def set_pixel(x, y, color)
+        return if x < 0 || x >= @width || y < 0 || y >= @height
+
+        idx = (y * @width + x) * 4
+        r, g, b, a = color
+        if a >= 255
+          @bytes.setbyte(idx, r)
+          @bytes.setbyte(idx + 1, g)
+          @bytes.setbyte(idx + 2, b)
+          @bytes.setbyte(idx + 3, 255)
+        else
+          # Alpha blending semplice (over operator)
+          src_a = a / 255.0
+          inv = 1 - src_a
+          @bytes.setbyte(idx,     (r * src_a + @bytes.getbyte(idx)     * inv).to_i)
+          @bytes.setbyte(idx + 1, (g * src_a + @bytes.getbyte(idx + 1) * inv).to_i)
+          @bytes.setbyte(idx + 2, (b * src_a + @bytes.getbyte(idx + 2) * inv).to_i)
+        end
+      end
+
+      # Bresenham
+      def line(x0, y0, x1, y1, color)
+        dx = (x1 - x0).abs
+        dy = -(y1 - y0).abs
+        sx = x0 < x1 ? 1 : -1
+        sy = y0 < y1 ? 1 : -1
+        err = dx + dy
+        x = x0; y = y0
+        loop do
+          set_pixel(x, y, color)
+          break if x == x1 && y == y1
+
+          e2 = 2 * err
+          if e2 >= dy
+            err += dy; x += sx
+          end
+          if e2 <= dx
+            err += dx; y += sy
+          end
+        end
+      end
+
+      def dot(cx, cy, color, radius)
+        (-radius..radius).each do |dy|
+          (-radius..radius).each do |dx|
+            set_pixel(cx + dx, cy + dy, color) if dx * dx + dy * dy <= radius * radius
+          end
+        end
+      end
+
+      def rect_fill(x0, y0, x1, y1, color)
+        (y0..y1).each do |y|
+          (x0..x1).each do |x|
+            set_pixel(x, y, color)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/rpdfium/table/edges.rb

@@ -0,0 +1,225 @@
+# frozen_string_literal: true
+
+module Rpdfium
+  module Table
+    # Operazioni su edges (segmenti orizzontali/verticali) usate dal
+    # TableFinder. Mappa diretta su `pdfplumber/table.py`.
+    #
+    # Convenzioni interne (allineate a pdfplumber):
+    #   - Ogni edge è un Hash con :orientation ("v" | "h"),
+    #     :x0, :x1, :top, :bottom (in coordinate top-down).
+    #   - Edge orizzontale: top == bottom, x0 < x1.
+    #   - Edge verticale:   x0 == x1, top < bottom.
+    #
+    # Le edges possono provenire da:
+    #   - linee vettoriali del PDF (path segments)
+    #   - rettangoli (decomposti in 4 lati)
+    #   - line "implicite" dedotte dall'allineamento di words (strategia :text)
+    #   - line specificate dall'utente (strategia :explicit)
+    module Edges
+      module_function
+
+      # Snap: cluster di edges quasi-collineari → coordinata media comune.
+      # Per orizzontali snappa la `top` (== `bottom`); per verticali la `x0`.
+      def snap_edges(edges, x_tolerance: 3.0, y_tolerance: 3.0)
+        v_edges, h_edges = edges.partition { |e| e[:orientation] == "v" }
+
+        snapped_v = Util::Cluster.cluster_objects(v_edges, :x0, tolerance: x_tolerance)
+                                 .flat_map { |g| move_to_avg(g, "v") }
+        snapped_h = Util::Cluster.cluster_objects(h_edges, :top, tolerance: y_tolerance)
+                                 .flat_map { |g| move_to_avg(g, "h") }
+        snapped_v + snapped_h
+      end
+
+      def move_to_avg(cluster, orientation)
+        case orientation
+        when "h"
+          mean = cluster.sum { |e| e[:top] } / cluster.size.to_f
+          cluster.map { |e| e.merge(top: mean, bottom: mean) }
+        when "v"
+          mean = cluster.sum { |e| e[:x0] } / cluster.size.to_f
+          cluster.map { |e| e.merge(x0: mean, x1: mean) }
+        end
+      end
+
+      # Join: dato un gruppo di edges sulla stessa retta infinita (stessa top
+      # per orizzontali, stessa x0 per verticali), fonde quelli i cui estremi
+      # sono entro `tolerance`.
+      #
+      # Match esatto del comportamento di pdfplumber.join_edge_group: scorre
+      # sorted per minprop, estende il "current" se overlap/contiguità entro
+      # tolerance, altrimenti apre nuovo current.
+      def join_edge_group(edges, orientation, tolerance: 3.0)
+        return [] if edges.empty?
+
+        min_prop, max_prop =
+          orientation == "h" ? [:x0, :x1] : [:top, :bottom]
+
+        sorted = edges.sort_by { |e| e[min_prop] }
+        joined = [sorted.first.dup]
+        sorted[1..].each do |e|
+          last = joined.last
+          if e[min_prop] <= last[max_prop] + tolerance
+            last[max_prop] = e[max_prop] if e[max_prop] > last[max_prop]
+          else
+            joined << e.dup
+          end
+        end
+        joined
+      end
+
+      # Pipeline completa: snap + join. Fedele a pdfplumber.merge_edges.
+      def merge_edges(edges,
+                      snap_x_tolerance: 3.0, snap_y_tolerance: 3.0,
+                      join_x_tolerance: 3.0, join_y_tolerance: 3.0)
+        if snap_x_tolerance.positive? || snap_y_tolerance.positive?
+          edges = snap_edges(edges,
+                              x_tolerance: snap_x_tolerance,
+                              y_tolerance: snap_y_tolerance)
+        end
+
+        # Raggruppa per (orientation, "valore della retta")
+        # h → top, v → x0
+        groups = edges.group_by do |e|
+          e[:orientation] == "h" ? ["h", e[:top]] : ["v", e[:x0]]
+        end
+        groups.flat_map do |(orient, _key), group|
+          tol = orient == "h" ? join_x_tolerance : join_y_tolerance
+          join_edge_group(group, orient, tolerance: tol)
+        end
+      end
+
+      # Filtra edges troppo corti.
+      def filter_edges(edges, orientation: nil, min_length: 1.0)
+        edges.reject do |e|
+          next true if orientation && e[:orientation] != orientation
+
+          length = if e[:orientation] == "h"
+                     e[:x1] - e[:x0]
+                   else
+                     e[:bottom] - e[:top]
+                   end
+          length < min_length
+        end
+      end
+
+      # ------------------------------------------------------------------
+      # words → edges (strategia :text)
+      # ------------------------------------------------------------------
+
+      DEFAULT_MIN_WORDS_VERTICAL = 3
+      DEFAULT_MIN_WORDS_HORIZONTAL = 1
+
+      # Per ogni cluster di word allineate "in alto" (stessa top, entro tol=1)
+      # con almeno `word_threshold` membri, emette DUE edges orizzontali (top
+      # e bottom della bbox di quel cluster). Avere il bottom oltre al top è
+      # critico: garantisce che l'ultima riga di ogni tabella abbia un edge
+      # orizzontale di chiusura.
+      def words_to_edges_h(words, word_threshold: DEFAULT_MIN_WORDS_HORIZONTAL)
+        by_top = Util::Cluster.cluster_objects(words, :top, tolerance: 1.0)
+        large = by_top.select { |g| g.size >= word_threshold }
+        rects = large.map { |g| Util::Cluster.objects_to_rect(g) }
+        return [] if rects.empty?
+
+        min_x0 = rects.map { |r| r[:x0] }.min
+        max_x1 = rects.map { |r| r[:x1] }.max
+
+        rects.flat_map do |r|
+          [
+            { x0: min_x0, x1: max_x1, top: r[:top],    bottom: r[:top],    orientation: "h" },
+            { x0: min_x0, x1: max_x1, top: r[:bottom], bottom: r[:bottom], orientation: "h" }
+          ]
+        end
+      end
+
+      # Tre cluster di word per x: x0, x1, centerpoint. Cluster con almeno
+      # `word_threshold` membri sono candidati colonna. Le bbox di ciascun
+      # cluster vengono "condensate": se una bbox si sovrappone a un'altra
+      # già selezionata (più popolata), viene scartata.
+      #
+      # Per ogni bbox condensata emetto un edge verticale al suo x0 (left
+      # della colonna). In aggiunta, emetto un edge "right" finale al max
+      # x1 di tutte le bbox: chiude visivamente la tabella sulla destra.
+      def words_to_edges_v(words, word_threshold: DEFAULT_MIN_WORDS_VERTICAL)
+        by_x0 = Util::Cluster.cluster_objects(words, :x0, tolerance: 1.0)
+        by_x1 = Util::Cluster.cluster_objects(words, :x1, tolerance: 1.0)
+        center_fn = ->(w) { (w[:x0] + w[:x1]) / 2.0 }
+        by_center = Util::Cluster.cluster_objects(words, center_fn, tolerance: 1.0)
+
+        clusters = by_x0 + by_x1 + by_center
+        # Più popolati prima
+        sorted = clusters.sort_by { |c| -c.size }
+        large = sorted.select { |c| c.size >= word_threshold }
+        bboxes = large.map { |c| Util::Cluster.objects_to_bbox(c) }
+
+        condensed_bboxes = bboxes.each_with_object([]) do |b, acc|
+          acc << b unless acc.any? { |c| Util::Cluster.bbox_overlaps?(b, c) }
+        end
+        return [] if condensed_bboxes.empty?
+
+        # Sort left-to-right per emettere edges in ordine geometrico.
+        condensed_rects = condensed_bboxes.map do |b|
+          { x0: b[0], top: b[1], x1: b[2], bottom: b[3] }
+        end.sort_by { |r| r[:x0] }
+
+        max_x1, min_top, max_bottom = condensed_rects.each_with_object(
+          [-Float::INFINITY, Float::INFINITY, -Float::INFINITY]
+        ) do |r, acc|
+          acc[0] = r[:x1]     if r[:x1]     > acc[0]
+          acc[1] = r[:top]    if r[:top]    < acc[1]
+          acc[2] = r[:bottom] if r[:bottom] > acc[2]
+        end
+
+        # Edge "left" di ogni colonna + un edge finale "right".
+        left_edges = condensed_rects.map do |r|
+          { x0: r[:x0], x1: r[:x0], top: min_top, bottom: max_bottom, orientation: "v" }
+        end
+        right_edge = { x0: max_x1, x1: max_x1, top: min_top, bottom: max_bottom, orientation: "v" }
+        left_edges + [right_edge]
+      end
+
+      # ------------------------------------------------------------------
+      # intersezioni edges
+      # ------------------------------------------------------------------
+
+      # Per ogni coppia (h, v) che si interseca entro tolerance, registra
+      # un'intersezione `(v.x0, h.top)` con i puntatori agli edge sorgenti.
+      # Il valore in `intersections[(x, y)] = { v: [...], h: [...] }` permette
+      # poi al cell-builder di verificare "edge connect".
+      #
+      # Ottimizzazione rispetto al loop naïve O(|v|×|h|): sorted_h è ordinato
+      # per top; per ogni edge verticale si usa bsearch per trovare il primo h
+      # candidato e si esce appena h[:top] supera v[:bottom] + y_tolerance,
+      # riducendo le iterazioni al solo sottoinsieme verticalmente rilevante.
+      def edges_to_intersections(edges, x_tolerance: 1.0, y_tolerance: 1.0)
+        v_edges, h_edges = edges.partition { |e| e[:orientation] == "v" }
+        intersections = {}
+        sorted_v = v_edges.sort_by { |v| [v[:x0], v[:top]] }
+        sorted_h = h_edges.sort_by { |h| [h[:top], h[:x0]] }
+        h_tops = sorted_h.map { |h| h[:top] }
+
+        sorted_v.each do |v|
+          v_top_min = v[:top]    - y_tolerance
+          v_top_max = v[:bottom] + y_tolerance
+
+          # Salta tutti gli h il cui top è ancora sotto la finestra verticale.
+          start_idx = h_tops.bsearch_index { |t| t >= v_top_min } || sorted_h.size
+
+          sorted_h[start_idx..].each do |h|
+            # Gli h rimanenti sono oltre la finestra: esci subito.
+            break if h[:top] > v_top_max
+
+            next unless v[:x0] >= h[:x0] - x_tolerance
+            next unless v[:x0] <= h[:x1] + x_tolerance
+
+            key = [v[:x0], h[:top]]
+            entry = intersections[key] ||= { v: [], h: [] }
+            entry[:v] << v
+            entry[:h] << h
+          end
+        end
+        intersections
+      end
+    end
+  end
+end