tabula-rb 1.0.0

data/lib/tabula/core/ruling.rb

@@ -0,0 +1,303 @@
+# frozen_string_literal: true
+
+module Tabula
+  # Represents a ruling line (horizontal or vertical line segment) in a PDF.
+  # Used for detecting table cell boundaries in lattice-mode extraction.
+  class Ruling
+    # Tolerance for considering lines as horizontal/vertical
+    ORIENTATION_TOLERANCE = 1.0
+
+    # Tolerance for near-intersection detection
+    INTERSECTION_TOLERANCE = 1.0
+
+    attr_accessor :x1, :y1, :x2, :y2
+
+    def initialize(x1, y1, x2, y2)
+      @x1 = x1.to_f
+      @y1 = y1.to_f
+      @x2 = x2.to_f
+      @y2 = y2.to_f
+      normalize!
+    end
+
+    # Create from two points
+    def self.from_points(p1, p2)
+      new(p1.x, p1.y, p2.x, p2.y)
+    end
+
+    # Create from top, left, width, height (like Rectangle)
+    def self.from_bounds(top, left, width, height)
+      new(left, top, left + width, top + height)
+    end
+
+    # Normalize almost-horizontal and almost-vertical lines
+    def normalize!
+      if horizontal?
+        avg_y = (y1 + y2) / 2.0
+        @y1 = avg_y
+        @y2 = avg_y
+        # Ensure x1 < x2
+        @x1, @x2 = @x2, @x1 if x1 > x2
+      elsif vertical?
+        avg_x = (x1 + x2) / 2.0
+        @x1 = avg_x
+        @x2 = avg_x
+        # Ensure y1 < y2
+        @y1, @y2 = @y2, @y1 if y1 > y2
+      end
+      self
+    end
+
+    def horizontal?
+      (y2 - y1).abs <= ORIENTATION_TOLERANCE
+    end
+
+    def vertical?
+      (x2 - x1).abs <= ORIENTATION_TOLERANCE
+    end
+
+    def oblique?
+      !horizontal? && !vertical?
+    end
+
+    # Position perpendicular to the line (y for horizontal, x for vertical)
+    def position
+      horizontal? ? y1 : x1
+    end
+
+    def position=(value)
+      if horizontal?
+        @y1 = value
+        @y2 = value
+      else
+        @x1 = value
+        @x2 = value
+      end
+    end
+
+    # Start point along the line direction
+    def start
+      horizontal? ? x1 : y1
+    end
+
+    # End point along the line direction
+    def end
+      horizontal? ? x2 : y2
+    end
+
+    def length
+      Math.sqrt(((x2 - x1)**2) + ((y2 - y1)**2))
+    end
+
+    def top
+      [y1, y2].min
+    end
+
+    def bottom
+      [y1, y2].max
+    end
+
+    def left
+      [x1, x2].min
+    end
+
+    def right
+      [x1, x2].max
+    end
+
+    def width
+      right - left
+    end
+
+    def height
+      bottom - top
+    end
+
+    # Get bounding rectangle
+    def bounds
+      Rectangle.new(top, left, width, height)
+    end
+
+    # Get start and end points as Point objects
+    def p1
+      Point.new(x1, y1)
+    end
+
+    def p2
+      Point.new(x2, y2)
+    end
+
+    # Calculate angle in degrees (0 = horizontal, 90 = vertical)
+    def angle
+      Math.atan2(y2 - y1, x2 - x1) * 180.0 / Math::PI
+    end
+
+    # Find intersection point with another ruling (only for orthogonal lines)
+    def intersection_point(other)
+      return nil if horizontal? == other.horizontal?
+      return nil if oblique? || other.oblique?
+
+      if horizontal?
+        Point.new(other.x1, y1)
+      else
+        Point.new(x1, other.y1)
+      end
+    end
+
+    # Check if this ruling intersects another (with tolerance)
+    def intersects?(other, tolerance = INTERSECTION_TOLERANCE)
+      point = intersection_point(other)
+      return false unless point
+
+      # Check if intersection point lies within both line segments
+      if horizontal?
+        x_in_self = point.x.between?(left - tolerance, right + tolerance)
+        y_in_other = point.y.between?(other.top - tolerance, other.bottom + tolerance)
+        x_in_self && y_in_other
+      else
+        y_in_self = point.y.between?(top - tolerance, bottom + tolerance)
+        x_in_other = point.x.between?(other.left - tolerance, other.right + tolerance)
+        y_in_self && x_in_other
+      end
+    end
+
+    # Check if lines nearly intersect (for cell detection)
+    def nearly_intersects?(other, tolerance = INTERSECTION_TOLERANCE)
+      intersects?(other, tolerance)
+    end
+
+    # Expand the ruling by extending its endpoints
+    def expand(amount)
+      if horizontal?
+        Ruling.new(x1 - amount, y1, x2 + amount, y2)
+      elsif vertical?
+        Ruling.new(x1, y1 - amount, x2, y2 + amount)
+      else
+        # For oblique lines, expand in both directions
+        dx = (x2 - x1) / length * amount
+        dy = (y2 - y1) / length * amount
+        Ruling.new(x1 - dx, y1 - dy, x2 + dx, y2 + dy)
+      end
+    end
+
+    # Clip ruling to a rectangular area
+    def clip_to(rect)
+      CohenSutherlandClipping.clip(self, rect)
+    end
+
+    # Check if this ruling overlaps with another (for collapsing)
+    def colinear_with?(other, tolerance = 1.0)
+      return false unless horizontal? == other.horizontal?
+
+      if horizontal?
+        (y1 - other.y1).abs < tolerance
+      else
+        (x1 - other.x1).abs < tolerance
+      end
+    end
+
+    def ==(other)
+      return false unless other.is_a?(Ruling)
+
+      x1 == other.x1 && y1 == other.y1 && x2 == other.x2 && y2 == other.y2
+    end
+    alias eql? ==
+
+    def hash
+      [x1, y1, x2, y2].hash
+    end
+
+    def dup
+      Ruling.new(x1, y1, x2, y2)
+    end
+
+    def to_s
+      orientation = if horizontal?
+                      'H'
+                    else
+                      (vertical? ? 'V' : 'O')
+                    end
+      "Ruling[#{orientation}](#{x1}, #{y1}) -> (#{x2}, #{y2})"
+    end
+
+    def inspect
+      to_s
+    end
+
+    class << self
+      # Find all intersection points between horizontal and vertical rulings
+      # Uses sweep line algorithm for O(n log n) performance
+      def find_intersections(horizontal_rulings, vertical_rulings)
+        intersections = {}
+
+        horizontal_rulings.each do |h|
+          vertical_rulings.each do |v|
+            next unless h.intersects?(v)
+
+            point = h.intersection_point(v)
+            next unless point
+
+            # Round to avoid floating point issues
+            key = [point.x.round(2), point.y.round(2)]
+            intersections[key] ||= point
+          end
+        end
+
+        intersections.values
+      end
+
+      # Collapse colinear rulings that are close together
+      def collapse_oriented_rulings(rulings, tolerance = 1.0)
+        return [] if rulings.empty?
+
+        # Separate horizontal and vertical
+        horizontal = rulings.select(&:horizontal?).sort_by(&:y1)
+        vertical = rulings.select(&:vertical?).sort_by(&:x1)
+
+        collapsed = []
+        collapsed.concat(collapse_group(horizontal, tolerance))
+        collapsed.concat(collapse_group(vertical, tolerance))
+        collapsed
+      end
+
+      # Crop rulings to a rectangular area
+      def crop_to_area(rulings, rect)
+        rulings.filter_map { |r| r.clip_to(rect) }
+      end
+
+      private
+
+      def collapse_group(rulings, tolerance)
+        return [] if rulings.empty?
+
+        groups = []
+        current_group = [rulings.first]
+
+        rulings[1..].each do |ruling|
+          if current_group.last.colinear_with?(ruling, tolerance)
+            current_group << ruling
+          else
+            groups << current_group
+            current_group = [ruling]
+          end
+        end
+        groups << current_group
+
+        # Merge each group into a single ruling
+        groups.map do |group|
+          if group.first.horizontal?
+            y = group.map(&:y1).sum / group.size
+            min_x = group.map(&:left).min
+            max_x = group.map(&:right).max
+            Ruling.new(min_x, y, max_x, y)
+          else
+            x = group.map(&:x1).sum / group.size
+            min_y = group.map(&:top).min
+            max_y = group.map(&:bottom).max
+            Ruling.new(x, min_y, x, max_y)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/tabula/core/spatial_index.rb

@@ -0,0 +1,120 @@
+# frozen_string_literal: true
+
+module Tabula
+  # Spatial index for efficient rectangle queries.
+  # Uses a simple grid-based approach for O(1) average lookup.
+  class SpatialIndex
+    attr_reader :rectangles
+
+    # @param cell_size [Float] size of grid cells (default 50)
+    def initialize(cell_size: 50.0)
+      @cell_size = cell_size
+      @grid = Hash.new { |h, k| h[k] = [] }
+      @rectangles = []
+    end
+
+    # Add a rectangle to the index
+    # @param rectangle [Rectangle] rectangle to add
+    def add(rectangle)
+      @rectangles << rectangle
+      cells_for(rectangle).each do |cell|
+        @grid[cell] << rectangle
+      end
+      self
+    end
+
+    # Add multiple rectangles
+    # @param rectangles [Array<Rectangle>] rectangles to add
+    def add_all(rectangles)
+      rectangles.each { |r| add(r) }
+      self
+    end
+
+    # Find all rectangles that intersect with the query rectangle
+    # @param query [Rectangle] query rectangle
+    # @return [Array<Rectangle>] intersecting rectangles
+    def intersects(query)
+      candidates = candidate_set(query)
+      candidates.select { |r| r.intersects?(query) }
+    end
+
+    # Find all rectangles that are fully contained within the query rectangle
+    # @param query [Rectangle] query rectangle
+    # @return [Array<Rectangle>] contained rectangles
+    def contains(query)
+      candidates = candidate_set(query)
+      candidates.select { |r| query.contains?(r) }
+    end
+
+    # Find all rectangles that contain the query point
+    # @param point [Point] query point
+    # @return [Array<Rectangle>] rectangles containing the point
+    def at_point(point)
+      cell = cell_for_point(point)
+      @grid[cell].select { |r| r.contains_point?(point) }
+    end
+
+    # Find rectangles within a given distance of the query rectangle
+    # @param query [Rectangle] query rectangle
+    # @param distance [Float] maximum distance
+    # @return [Array<Rectangle>] nearby rectangles
+    def nearby(query, distance)
+      expanded = Rectangle.from_bounds(
+        query.top - distance,
+        query.left - distance,
+        query.bottom + distance,
+        query.right + distance
+      )
+      intersects(expanded)
+    end
+
+    # Compute bounding box of all indexed rectangles
+    # @return [Rectangle, nil] bounding box or nil if empty
+    def bounds
+      Rectangle.bounding_box_of(@rectangles)
+    end
+
+    # Number of indexed rectangles
+    def size
+      @rectangles.size
+    end
+
+    def empty?
+      @rectangles.empty?
+    end
+
+    # Clear all indexed rectangles
+    def clear
+      @grid.clear
+      @rectangles.clear
+      self
+    end
+
+    private
+
+    def cell_for_point(point)
+      col = (point.x / @cell_size).floor
+      row = (point.y / @cell_size).floor
+      [col, row]
+    end
+
+    def cells_for(rectangle)
+      min_col = (rectangle.left / @cell_size).floor
+      max_col = (rectangle.right / @cell_size).floor
+      min_row = (rectangle.top / @cell_size).floor
+      max_row = (rectangle.bottom / @cell_size).floor
+
+      cells = []
+      (min_col..max_col).each do |col|
+        (min_row..max_row).each do |row|
+          cells << [col, row]
+        end
+      end
+      cells
+    end
+
+    def candidate_set(query)
+      cells_for(query).flat_map { |cell| @grid[cell] }.uniq
+    end
+  end
+end

data/lib/tabula/detectors/detection_algorithm.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Tabula
+  module Detectors
+    # Base class for table detection algorithms
+    class DetectionAlgorithm
+      # Detect table areas on a page
+      # @param page [Page] page to detect tables on
+      # @param options [Hash] algorithm-specific options
+      # @return [Array<Rectangle>] detected table areas
+      def self.detect(page, **options)
+        new(**options).detect(page)
+      end
+
+      # @param options [Hash] algorithm options
+      def initialize(**options)
+        @options = options
+      end
+
+      # Detect table areas on a page
+      # @param page [Page] page to detect tables on
+      # @return [Array<Rectangle>]
+      def detect(page)
+        raise NotImplementedError, 'Subclasses must implement #detect'
+      end
+
+      # Get algorithm name
+      # @return [String]
+      def name
+        self.class.name.split('::').last
+      end
+    end
+  end
+end

data/lib/tabula/detectors/nurminen_detection_algorithm.rb

@@ -0,0 +1,211 @@
+# frozen_string_literal: true
+
+module Tabula
+  module Detectors
+    # Nurminen's table detection algorithm.
+    # Based on Anssi Nurminen's master's thesis approach.
+    # Detects tables using text alignment and edge analysis.
+    class Nurminen < DetectionAlgorithm
+      # Text edge types
+      EDGE_LEFT = 0
+      EDGE_MID = 1
+      EDGE_RIGHT = 2
+
+      # Minimum rows for a valid table
+      MIN_ROWS = 2
+
+      # Overlap threshold for duplicate detection
+      OVERLAP_THRESHOLD = 0.9
+
+      # Detect table areas on a page
+      # @param page [Page] page to detect tables on
+      # @return [Array<Rectangle>] detected table areas
+      def detect(page)
+        tables = []
+
+        # First, try ruling-based detection
+        ruling_tables = detect_from_rulings(page)
+        tables.concat(ruling_tables)
+
+        # Then, try text-based detection
+        text_tables = detect_from_text(page)
+
+        # Merge results, removing duplicates
+        text_tables.each do |text_table|
+          tables << text_table unless overlaps_existing?(text_table, tables)
+        end
+
+        tables
+      end
+
+      private
+
+      def detect_from_rulings(page)
+        SpreadsheetDetection.detect(page)
+      end
+
+      def detect_from_text(page)
+        lines = page.text_lines
+        return [] if lines.size < MIN_ROWS
+
+        # Find text edges
+        edges = find_text_edges(lines)
+        return [] if edges.empty?
+
+        # Find relevant edges (most common alignment)
+        relevant = find_relevant_edges(edges)
+        return [] if relevant.empty?
+
+        # Detect tables from edge patterns
+        detect_tables_from_edges(lines, relevant, page)
+      end
+
+      def find_text_edges(lines)
+        edges = { EDGE_LEFT => [], EDGE_MID => [], EDGE_RIGHT => [] }
+
+        lines.each do |line|
+          line.sorted_chunks.each do |chunk|
+            # Left edge
+            edges[EDGE_LEFT] << TextEdge.new(chunk.left, line.top, line.bottom, EDGE_LEFT)
+
+            # Center edge
+            center = chunk.left + (chunk.width / 2.0)
+            edges[EDGE_MID] << TextEdge.new(center, line.top, line.bottom, EDGE_MID)
+
+            # Right edge
+            edges[EDGE_RIGHT] << TextEdge.new(chunk.right, line.top, line.bottom, EDGE_RIGHT)
+          end
+        end
+
+        edges
+      end
+
+      def find_relevant_edges(edges)
+        # Cluster edges by x position
+        all_edges = edges.values.flatten
+        return [] if all_edges.empty?
+
+        clustered = cluster_edges(all_edges)
+        return [] if clustered.empty?
+
+        # Find edges that appear in multiple rows
+        min_occurrences = [2, (all_edges.size * 0.1).ceil].max
+        clustered.select { |_, count| count >= min_occurrences }.keys
+      end
+
+      def cluster_edges(edges, tolerance: 8.0)
+        return {} if edges.empty?
+
+        sorted = edges.sort_by(&:x)
+        clusters = {}
+        current_cluster = [sorted.first]
+
+        sorted[1..].each do |edge|
+          if (edge.x - current_cluster.last.x).abs <= tolerance
+            current_cluster << edge
+          else
+            avg_x = current_cluster.sum(&:x) / current_cluster.size
+            clusters[avg_x] = current_cluster.size
+            current_cluster = [edge]
+          end
+        end
+
+        unless current_cluster.empty?
+          avg_x = current_cluster.sum(&:x) / current_cluster.size
+          clusters[avg_x] = current_cluster.size
+        end
+
+        clusters
+      end
+
+      def detect_tables_from_edges(lines, edge_positions, page)
+        return [] if edge_positions.size < 2
+
+        tables = []
+
+        # Look for consistent patterns across consecutive lines
+        table_start = nil
+        table_lines = []
+
+        lines.each_with_index do |line, idx|
+          line_edges = extract_line_edges(line)
+          aligned = edges_aligned_with_columns?(line_edges, edge_positions)
+
+          if aligned
+            table_start ||= idx
+            table_lines << line
+          elsif table_lines.size >= MIN_ROWS
+            # End of table
+            table = create_table_bounds(table_lines, page)
+            tables << table if table
+            table_start = nil
+            table_lines = []
+          else
+            table_start = nil
+            table_lines = []
+          end
+        end
+
+        # Handle table at end of page
+        if table_lines.size >= MIN_ROWS
+          table = create_table_bounds(table_lines, page)
+          tables << table if table
+        end
+
+        tables
+      end
+
+      def extract_line_edges(line)
+        edges = []
+        line.sorted_chunks.each do |chunk|
+          edges << chunk.left
+          edges << chunk.right
+        end
+        edges
+      end
+
+      def edges_aligned_with_columns?(line_edges, column_positions, tolerance: 10.0)
+        return false if line_edges.empty?
+
+        # Check if at least half of the line edges align with column positions
+        aligned_count = line_edges.count do |edge|
+          column_positions.any? { |col| (edge - col).abs <= tolerance }
+        end
+
+        aligned_count >= (line_edges.size * 0.3)
+      end
+
+      def create_table_bounds(lines, page)
+        return nil if lines.empty?
+
+        bounds = Rectangle.bounding_box_of(lines)
+        return nil unless bounds
+
+        # Expand slightly to include full cell boundaries
+        padding = 2.0
+        Rectangle.from_bounds(
+          [bounds.top - padding, 0].max,
+          [bounds.left - padding, 0].max,
+          [bounds.bottom + padding, page.height].min,
+          [bounds.right + padding, page.width].min
+        )
+      end
+
+      def overlaps_existing?(table, existing_tables)
+        existing_tables.any? { |t| t.overlap_ratio(table) >= OVERLAP_THRESHOLD }
+      end
+
+      # Helper class for text edges
+      class TextEdge
+        attr_reader :x, :top, :bottom, :type
+
+        def initialize(x, top, bottom, type)
+          @x = x
+          @top = top
+          @bottom = bottom
+          @type = type
+        end
+      end
+    end
+  end
+end