elkrb 1.0.2 → 2.0.0

data/lib/elkrb/layout/node_index.rb

@@ -0,0 +1,149 @@
+# frozen_string_literal: true
+
+require_relative "../errors"
+require_relative "../geometry/point"
+
+module Elkrb
+  module Layout
+    # Resolves node and port ids to their owning node, for ONE hierarchy
+    # level. Node ids and port ids share one namespace at a level; the
+    # same id may legitimately repeat at a different level (build a
+    # fresh index per level, never reused across `layout_flat` calls).
+    #
+    # `.build` is the entry point; construct every index through it.
+    class NodeIndex
+      # The edges of this level, in graph-then-children order.
+      attr_reader :edges
+
+      def self.build(graph)
+        new(graph)
+      end
+
+      # Indexes every hierarchy level while retaining each level's namespace.
+      # The offset is the sum of ancestor node coordinates; a node's own x/y
+      # remain local and are not included in its entry.
+      def self.build_deep(graph)
+        entries = {}
+        build_deep_level(graph, Geometry::Point.new, entries)
+        entries
+      end
+
+      def self.build_deep_level(graph, offset, entries)
+        index = build(graph)
+        children = graph.children || []
+        children.each { |node| record_deep_entries(entries, index, node, offset) }
+        build_deep_children(children, offset, entries)
+      end
+      private_class_method :build_deep_level
+
+      def self.build_deep_children(children, offset, entries)
+        children.select(&:hierarchical?).each do |node|
+          build_deep_level(node, descendant_offset(offset, node), entries)
+        end
+      end
+      private_class_method :build_deep_children
+
+      def self.descendant_offset(offset, node)
+        Geometry::Point.new(
+          x: offset.x + (node.x || 0.0),
+          y: offset.y + (node.y || 0.0),
+        )
+      end
+      private_class_method :descendant_offset
+
+      def self.record_deep_entries(entries, index, node, offset)
+        [node.id, *node.ports.to_a.map(&:id)].each do |id|
+          (entries[id] ||= []) << [index.node(id), offset]
+        end
+      end
+      private_class_method :record_deep_entries
+
+      def node(id)
+        @nodes_by_id[id]
+      end
+
+      def endpoint_nodes(ids)
+        (ids || []).filter_map { |id| node(id) }
+      end
+
+      # Endpoints resolved for TOPOLOGY: a nested endpoint projects onto its
+      # top-level ancestor instead of vanishing. Use this wherever an edge
+      # contributes to layering or cycle detection; use #endpoint_nodes when
+      # you want the literal nodes of this level and nothing else.
+      def endpoint_owners(ids)
+        (ids || []).filter_map { |id| owner(id) }.uniq
+      end
+
+      # The node AT THIS LEVEL that owns `id`: the node itself, the node
+      # whose port it is, or the top-level ancestor of a nested descendant.
+      #
+      # This level always wins, so a nested id can never shadow one here --
+      # that shadowing is what #node exists to keep out. But a graph-owned
+      # cross-hierarchy edge (`c1 -> p2`, with c1 nested under p1) is
+      # supported, and dropping its nested endpoint takes the edge out of
+      # the topology entirely. Projecting c1 onto p1 keeps it.
+      #
+      # Use this for graph-owned edges only. Child-owned nested edges stay
+      # excluded by #edges_on, which is a separate concern.
+      def owner(id)
+        node(id) || @owners_by_descendant_id[id]
+      end
+
+      # The edges `child` declares that belong to THIS level. A
+      # hierarchical child's `edges` address its own namespace --
+      # `HierarchicalProcessor#create_child_graph` hands them to the
+      # child's level, which is where their ids resolve. Ids are unique
+      # only within a level, so reading them here aliases a nested
+      # endpoint onto an unrelated node or port of this level.
+      def edges_on(child)
+        return [] if child.hierarchical?
+
+        child.edges || []
+      end
+
+      private
+
+      def initialize(graph)
+        @nodes_by_id = {}
+        children = graph.children || []
+        children.each { |child| index_node(child) }
+        @edges = ((graph.edges || []) +
+          children.flat_map { |child| edges_on(child) }).freeze
+        @owners_by_descendant_id = {}
+        children.each { |child| index_descendants(child, child) }
+      end
+
+      # Maps every id below a top-level child back to that child. Only ids
+      # this level does not already own are recorded, so #owner can never
+      # let a descendant displace a node or port of this level.
+      def index_descendants(node, owner)
+        (node.children || []).each do |descendant|
+          claim_descendant(descendant.id, owner)
+          descendant.ports&.each { |port| claim_descendant(port.id, owner) }
+          index_descendants(descendant, owner)
+        end
+      end
+
+      def claim_descendant(id, owner)
+        return if id.nil? || @nodes_by_id.key?(id) || @owners_by_descendant_id.key?(id)
+
+        @owners_by_descendant_id[id] = owner
+      end
+
+      def index_node(node)
+        add(node.id, node, "node")
+        node.ports&.each { |port| add(port.id, node, "port") }
+      end
+
+      def add(id, node, kind)
+        raise Elkrb::ValidationError, "#{kind} without id" if id.nil?
+
+        if @nodes_by_id.key?(id)
+          raise Elkrb::ValidationError, "duplicate id: #{id}"
+        end
+
+        @nodes_by_id[id] = node
+      end
+    end
+  end
+end

data/lib/elkrb/layout/polyomino/component_compactor.rb

@@ -0,0 +1,138 @@
+# frozen_string_literal: true
+
+require_relative "footprint"
+require_relative "packer"
+require_relative "../../geometry/rectangle"
+require_relative "../../geometry/dimension"
+
+module Elkrb
+  module Layout
+    module Polyomino
+      # Packs disconnected components the way ELK's DisCoPolyominoCompactor
+      # does: each component becomes a low-resolution polyomino, the
+      # polyominoes are packed, and each component gets the offset that moves
+      # it to its polyomino's place.
+      #
+      # A component is an Array of shapes, a shape an Array of [x, y] corners.
+      class ComponentCompactor
+        # ELK's bound on the cell count per component that the cell size
+        # is solved for.
+        UPPER_BOUND = 100.0
+        private_constant :UPPER_BOUND
+
+        # @param components [Array<Array<Array<Array<Float>>>>]
+        # @param aspect_ratio [Float] target width/height, above zero
+        # @param fill [Boolean]
+        def initialize(components, aspect_ratio:, fill: true)
+          @components = components
+          @aspect_ratio = aspect_ratio
+          @fill = fill
+        end
+
+        # @return [Array<Array(Float, Float)>] the [dx, dy] to add to each
+        #   component's coordinates, in the order the components were given
+        def offsets
+          return [] if @components.empty?
+
+          @boxes = @components.map { |shapes| bounding_box(shapes) }
+          @cell = cell_size
+          placed, origin = pack_pieces
+          placed.sort_by(&:payload).map { |piece| offset_of(piece, origin) }
+        end
+
+        private
+
+        def bounding_box(shapes)
+          xs, ys = shapes.flatten(1).transpose
+          Geometry::Rectangle.new(xs.min, ys.min,
+                                  xs.max - xs.min, ys.max - ys.min)
+        end
+
+        # The packed pieces and the [col, row] of the packing's top-left.
+        def pack_pieces
+          pieces = @components.each_index.map { |index| build_piece(index) }
+          placed, grid = Packer.pack(pieces, aspect_ratio: @aspect_ratio,
+                                             fill: @fill)
+          [placed, (grid.filled_bounds || [0, 0]).first(2)]
+        end
+
+        def offset_of(piece, origin)
+          box = @boxes[piece.payload]
+          [horizontal_offset(piece, box, origin[0]),
+           vertical_offset(piece, box, origin[1])]
+        end
+
+        def horizontal_offset(piece, box, origin_col)
+          axis_offset(piece.col - origin_col, piece.width, @cell.width,
+                      box.x, box.width)
+        end
+
+        def vertical_offset(piece, box, origin_row)
+          axis_offset(piece.row - origin_row, piece.height, @cell.height,
+                      box.y, box.height)
+        end
+
+        # Cells from the packing's edge to the piece, plus half the space the
+        # piece has over the component, less where the component starts.
+        def axis_offset(cells_from_edge, piece_cells, cell, start, size)
+          (cells_from_edge * cell) + margin(size, piece_cells, cell) - start
+        end
+
+        # The polyomino is at least as large as the component; half the
+        # difference is the space either side of it.
+        def margin(size, cells, cell)
+          ((cells * cell) - size) / 2.0
+        end
+
+        # The cell size at which packing every component with at most
+        # UPPER_BOUND cells of slack stays tight (ELK's computeCellSize),
+        # stretched by the aspect ratio.
+        def cell_size
+          base = solve_cell_size
+          if @aspect_ratio > 1.0
+            Geometry::Dimension.new(base * @aspect_ratio, base)
+          else
+            Geometry::Dimension.new(base, base / @aspect_ratio)
+          end
+        end
+
+        def solve_cell_size
+          size = cell_formula(@boxes.sum { |box| box.width + box.height },
+                              @boxes.sum { |box| box.width * box.height },
+                              UPPER_BOUND * @boxes.size)
+          size.positive? ? size : 1.0
+        end
+
+        def cell_formula(sum, product, cells)
+          root = Math.sqrt((4.0 * cells * product) - (4.0 * product) +
+                           (sum * sum))
+          (root + sum) / (2.0 * (cells - 1.0))
+        end
+
+        def build_piece(index)
+          box = @boxes[index]
+          piece = Piece.new((box.width / @cell.width).ceil,
+                            (box.height / @cell.height).ceil, index)
+          block_touched_cells(piece, first_footprint(box, piece),
+                              @components[index])
+          piece
+        end
+
+        def first_footprint(box, piece)
+          Footprint.new(
+            box.x - margin(box.width, piece.width, @cell.width),
+            box.y - margin(box.height, piece.height, @cell.height),
+            @cell.width, @cell.height
+          )
+        end
+
+        def block_touched_cells(piece, first, shapes)
+          piece.positions.each do |col, row|
+            cell = first.step(col, row)
+            piece.block(col, row) if shapes.any? { |s| cell.touched_by?(s) }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/elkrb/layout/polyomino/footprint.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+module Elkrb
+  module Layout
+    module Polyomino
+      # One raster cell, as a rectangle in the plane of the shapes it is
+      # tested against. A shape is an Array of [x, y] corners.
+      #
+      # ELK rasterises a shape to the cells whose border it crosses, or that
+      # contain it whole; a cell lying wholly inside a shape is not touched
+      # by it. Profile Fill closes that gap.
+      class Footprint
+        EPSILON = 0.00001
+        private_constant :EPSILON
+
+        def initialize(left, top, width, height)
+          @left = left
+          @top = top
+          @width = width
+          @height = height
+        end
+
+        # The footprint +cols+ cells right and +rows+ cells down.
+        def step(cols, rows)
+          self.class.new(@left + (cols * @width), @top + (rows * @height),
+                         @width, @height)
+        end
+
+        # ELK's DCElement#intersects: a border of the cell crosses the shape,
+        # or the shape lies strictly inside the cell. Touching does not count.
+        def touched_by?(shape)
+          return false if shape.size < 2
+
+          crosses_border?(shape) || shape.all? { |point| inside?(point) }
+        end
+
+        private
+
+        def crosses_border?(shape)
+          shape.zip(shape.rotate).any? do |first, second|
+            !(inside?(first) && inside?(second)) &&
+              sides.any? { |side| crossing?(side, [first, second]) }
+          end
+        end
+
+        def inside?(point)
+          strictly_between?(point[0], @left, @left + @width) &&
+            strictly_between?(point[1], @top, @top + @height)
+        end
+
+        def strictly_between?(value, low, high)
+          low < value && value < high
+        end
+
+        def sides
+          right = @left + @width
+          bottom = @top + @height
+          corners = [[@left, @top], [right, @top],
+                     [right, bottom], [@left, bottom]]
+          corners.zip(corners.rotate)
+        end
+
+        # ELK's ElkMath.intersects(l11, l12, l21, l22): the segments cross
+        # at a point interior to both, within EPSILON.
+        def crossing?(first, second)
+          direction = vector(first)
+          other = vector(second)
+          det = cross_product(other, direction)
+          return false if det.abs <= EPSILON
+
+          delta = difference(first[0], second[0])
+          [cross_product(delta, direction), cross_product(delta, other)]
+            .all? { |numerator| interior?(numerator / det) }
+        end
+
+        def interior?(fraction)
+          fraction > EPSILON && fraction < 1 - EPSILON
+        end
+
+        def vector(segment)
+          difference(segment[1], segment[0])
+        end
+
+        def difference(first, second)
+          [first[0] - second[0], first[1] - second[1]]
+        end
+
+        def cross_product(first, second)
+          (first[0] * second[1]) - (first[1] * second[0])
+        end
+      end
+    end
+  end
+end

data/lib/elkrb/layout/polyomino/grid.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+module Elkrb
+  module Layout
+    module Polyomino
+      # A rectangular grid of blocked and empty cells, addressed either from
+      # the top-left corner or from the cell at (center_col, center_row).
+      #
+      # Port of the two-valued core of ELK's PlanarGrid. Out-of-range reads
+      # raise IndexError; Ruby arrays would otherwise wrap negative indexes
+      # around to the far edge.
+      class Grid
+        attr_reader :width, :height, :center_col, :center_row
+
+        def initialize(width, height)
+          @width = width
+          @height = height
+          @center_col = (width - 1) >> 1
+          @center_row = (height - 1) >> 1
+          @cells = Array.new(height) { Array.new(width, false) }
+        end
+
+        def blocked?(col, row)
+          check_bounds(col, row)
+          @cells[row][col]
+        end
+
+        def block(col, row)
+          check_bounds(col, row)
+          @cells[row][col] = true
+        end
+
+        def in_bounds?(col, row)
+          col.between?(0, width - 1) && row.between?(0, height - 1)
+        end
+
+        # Each blocked cell as (col, row), top row first.
+        def each_blocked
+          return enum_for(:each_blocked) unless block_given?
+
+          @cells.each_with_index do |line, row|
+            line.each_with_index { |cell, col| yield col, row if cell }
+          end
+        end
+
+        # Every (col, row) of the grid.
+        def positions
+          (0...width).to_a.product((0...height).to_a)
+        end
+
+        # The cells as rows of booleans, and as columns of booleans.
+        def rows
+          @cells.map(&:dup)
+        end
+
+        def columns
+          Array.new(width) { |col| @cells.map { |line| line[col] } }
+        end
+
+        # The [left, top] of +other+ on this grid when its center cell sits
+        # at (+shift_col+, +shift_row+) from this grid's center cell.
+        def origin_for(other, shift_col, shift_row)
+          [shift_col - other.center_col + center_col,
+           shift_row - other.center_row + center_row]
+        end
+
+        # True when placing +other+ at that shift would put a blocked cell of
+        # +other+ on a blocked cell of this grid or outside it.
+        def intersects?(other, shift_col, shift_row)
+          left, top = origin_for(other, shift_col, shift_row)
+          other.each_blocked.any? do |col, row|
+            taken?(left + col, top + row)
+          end
+        end
+
+        # Blocks the cells +other+ blocks when placed at that shift.
+        def add_blocked_cells_from(other, shift_col, shift_row)
+          left, top = origin_for(other, shift_col, shift_row)
+          other.each_blocked { |col, row| block(left + col, top + row) }
+        end
+
+        # The bounding box of the blocked cells as [min_col, min_row, width,
+        # height], or nil when nothing is blocked.
+        def filled_bounds
+          cols, rows = each_blocked.to_a.transpose
+          return nil unless cols
+
+          [cols.min, rows.min,
+           cols.max - cols.min + 1, rows.max - rows.min + 1]
+        end
+
+        private
+
+        def taken?(col, row)
+          !in_bounds?(col, row) || @cells[row][col]
+        end
+
+        def check_bounds(col, row)
+          return if in_bounds?(col, row)
+
+          raise IndexError, "(#{col}, #{row}) is outside #{width}x#{height}"
+        end
+      end
+    end
+  end
+end

data/lib/elkrb/layout/polyomino/packer.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+require_relative "piece"
+
+module Elkrb
+  module Layout
+    module Polyomino
+      # Packs pieces onto one grid, largest first, each at the first free
+      # position of a line-by-line walk out from the grid's center.
+      #
+      # Port of ELK's PolyominoCompactor with the defaults DisCo runs with:
+      # QUADRANTS_LINE_BY_LINE traversal, BY_SIZE_AND_SHAPE ordering, and
+      # Profile Fill. Pieces have no extensions, so ELK's extension-based
+      # orderings and quadrant restrictions are all no-ops and are not ported.
+      module Packer
+        module_function
+
+        # Places every piece and returns the pieces in packing order. Each
+        # piece's col and row become its top-left cell on the returned grid.
+        #
+        # @param pieces [Array<Piece>]
+        # @param aspect_ratio [Float] target width/height of the packing
+        # @param fill [Boolean] apply Profile Fill before packing
+        # @return [Array(Array<Piece>, Grid)] pieces in packing order, grid
+        def pack(pieces, aspect_ratio:, fill: true)
+          pieces.each(&:fill_enclosed_cells) if fill
+          grid = Grid.new(*grid_size(pieces, aspect_ratio))
+          ordered = packing_order(pieces)
+          ordered.each { |piece| place(grid, piece) }
+          [ordered, grid]
+        end
+
+        # Largest first; equal pieces keep the order they were given in.
+        def packing_order(pieces)
+          pieces.each_with_index
+            .sort_by { |piece, index| [-shape_cost(piece), index] }
+            .map(&:first)
+        end
+
+        def grid_size(pieces, aspect_ratio)
+          width = doubled_extent(pieces, :width)
+          height = doubled_extent(pieces, :height)
+          return [(width * aspect_ratio).ceil, height] if aspect_ratio > 1.0
+
+          [width, (height / aspect_ratio).ceil]
+        end
+
+        def doubled_extent(pieces, side)
+          first = pieces.first&.public_send(side) || 0
+          2 * (pieces.sum(&side) + first)
+        end
+
+        # Squared short side plus long side: ELK's
+        # MinPerimeterComparatorWithShape.
+        def shape_cost(piece)
+          short, long = [piece.width, piece.height].minmax
+          (short * short) + long
+        end
+
+        def place(grid, piece)
+          shift = free_shift(grid, piece)
+          grid.add_blocked_cells_from(piece, *shift)
+          piece.col, piece.row = grid.origin_for(piece, *shift)
+        end
+
+        def free_shift(grid, piece)
+          limit = [grid.width, grid.height].max
+          shift = [0, 0]
+          while grid.intersects?(piece, *shift)
+            shift = next_shift(*shift)
+            next if shift.all? { |step| step.abs <= limit }
+
+            raise Elkrb::Error, "polyomino packing found no free position"
+          end
+          shift
+        end
+
+        # ELK's SuccessorLineByLine: the walk 0,0 -> 1,0 -> ... along each
+        # row of an expanding square, rows top to bottom.
+        def next_shift(col, row)
+          return corner_shift(col, row) if col >= 0 && col.abs == row.abs
+          return [col + 1, row] unless col.abs > row.abs
+
+          [-col, col.negative? ? row : row + 1]
+        end
+
+        def corner_shift(col, row)
+          return [-col - 1, -col - 1] if col == row
+
+          [-col, row + 1]
+        end
+      end
+    end
+  end
+end

data/lib/elkrb/layout/polyomino/piece.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+require_relative "grid"
+
+module Elkrb
+  module Layout
+    module Polyomino
+      # A grid plus the position the packer gave it, in cells of the packing
+      # grid. +payload+ is whatever the caller wants back (a component).
+      class Piece < Grid
+        attr_accessor :col, :row
+        attr_reader :payload
+
+        def initialize(width, height, payload = nil)
+          super(width, height)
+          @payload = payload
+          @col = 0
+          @row = 0
+        end
+
+        # Blocks every empty cell that has a blocked cell somewhere to its
+        # north, south, east and west, so a small piece cannot be packed into
+        # the hole of a large one. Profile Fill of Freivalds et al. (2002).
+        def fill_enclosed_cells
+          enclosed_cells.each { |col, row| block(col, row) }
+        end
+
+        private
+
+        def enclosed_cells
+          north, south = extents(columns)
+          east, west = extents(rows)
+          positions.select do |col, row|
+            between?(col, east[row], west[row]) &&
+              between?(row, north[col], south[col])
+          end
+        end
+
+        # Per line, the index of its first and of its last blocked cell; an
+        # empty line gets the values that no cell can lie between.
+        def extents(lines)
+          [lines.map { |line| line.index(true) || line.size },
+           lines.map { |line| line.rindex(true) || -1 }]
+        end
+
+        def between?(value, low, high)
+          low < value && value < high
+        end
+      end
+    end
+  end
+end