elkrb 1.0.0 → 2.0.0

data/lib/elkrb/layout/algorithms/layered/orthogonal_router.rb

@@ -0,0 +1,253 @@
+# frozen_string_literal: true
+
+require_relative "port_order"
+require_relative "port_spread"
+require_relative "orthogonal/gap_solver"
+require_relative "orthogonal/junction_points"
+
+module Elkrb
+  module Layout
+    module Algorithms
+      module Layered
+        # Orthogonal routes for the edges between adjacent layers. Each gap
+        # between two layers holds the perpendicular runs of its edges, one
+        # per routing slot; an edge leaves the side of its node that faces
+        # the next layer, runs to its slot, along it, and on to its target.
+        #
+        # All geometry is read through callables, so the same router sizes
+        # the gaps before nodes have a layer position and routes after.
+        #
+        # Not ported: the segment splitting described on
+        # Orthogonal::GapSolver.
+        class OrthogonalRouter
+          # Cross-axis geometry, each a callable.
+          #
+          # `start` is where an item starts, `extent` its cross size and
+          # `port` the cross size of a port.
+          Measure = Struct.new(:start, :extent, :port, keyword_init: true)
+
+          # An edge's route: its points, source first, and the junction
+          # points where it meets other edges of its hyperedge segment.
+          Route = Struct.new(:points, :junctions)
+          # Bend points and junction points per edge, per gap.
+          class Book
+            attr_reader :bends, :junctions
+
+            def initialize
+              @bends = {}.compare_by_identity
+              @junctions = {}.compare_by_identity
+            end
+
+            def record(edge, gap, bends, junctions)
+              (@bends[edge] ||= {})[gap] = bends
+              (@junctions[edge] ||= {})[gap] = junctions
+            end
+          end
+          private_constant :Book
+
+          # Distance between neighbouring routing slots.
+          EDGE_SPACING = 10.0
+          # Distance between a layer and its first routing slot.
+          EDGE_NODE_SPACING = 10.0
+          TOLERANCE = Orthogonal::HyperEdgeSegment::TOLERANCE
+          # Node side that faces the next layer, and the side that faces the
+          # previous one, per direction.
+          FACING_SIDES = {
+            "RIGHT" => %w[EAST WEST], "LEFT" => %w[WEST EAST],
+            "DOWN" => %w[SOUTH NORTH], "UP" => %w[NORTH SOUTH]
+          }.freeze
+
+          # @param layers [Array<Array>] nodes and DummySlots per layer
+          # @param port_order [PortOrder]
+          # @param index [NodeIndex] resolves edge endpoints to nodes
+          # @param direction [String] RIGHT, LEFT, DOWN or UP
+          # @param measure [Measure] cross-axis geometry
+          def initialize(layers, port_order, index, direction:, measure:)
+            @layers = layers
+            @port_order = port_order
+            @index = index
+            @facing = FACING_SIDES.fetch(direction)
+            @vertical = %w[DOWN UP].include?(direction)
+            @sign = %w[LEFT UP].include?(direction) ? -1 : 1
+            @measure = measure
+            @items = layers.flatten.to_h { |item| [item.id, item] }
+            @offsets = spread_offsets
+          end
+
+          # Number of routing slots in each gap between two layers.
+          def slot_counts
+            gaps.map { |segments| Orthogonal::GapSolver.slot_count(segments) }
+          end
+
+          # @param along_range [#call] [low, high] of an item on the layer
+          #   axis, in final coordinates
+          # @return [Hash{Edge=>Route}] the route of each edge that crosses
+          #   a layer gap, source first; an edge whose declared port is not
+          #   on the side facing its neighbour layer is left out
+          def routes(along_range)
+            @along_range = along_range
+            book = gap_book
+            grouped_segments.select { |_edge, links| facing?(links) }
+              .to_h { |edge, links| [edge, route(edge, links, book)] }
+          end
+
+          private
+
+          def spread_offsets
+            sizes = @items.transform_values do |item|
+              @measure.extent.call(item)
+            end
+            PortSpread.offsets(@layers, @port_order, sizes, @measure.port)
+          end
+
+          def gaps
+            @layers.each_cons(2).map do |layer, _next_layer|
+              ports = layer.flat_map do |item|
+                @port_order.visual(item.id, :east)
+              end
+              Orthogonal::GapSolver.new(EDGE_SPACING)
+                .solve(ports, method(:cross_of))
+            end
+          end
+
+          def cross_of(port)
+            item = @items.fetch(port.item_id)
+            offset = item.respond_to?(:dummy?) ? 0.0 : @offsets.fetch(port)
+            @measure.start.call(item) + offset
+          end
+
+          # Bend points and junction points per edge, per gap: lists of
+          # [along, cross].
+          def gap_book
+            book = Book.new
+            pairs = @layers.each_cons(2).zip(gaps)
+            pairs.each_with_index do |(pair, segments), gap|
+              start = layer_high(pair.first) + EDGE_NODE_SPACING
+              joints = Orthogonal::JunctionPoints.new
+              segments.each { |s| place(s, [start, gap], book, joints) }
+            end
+            book
+          end
+
+          def place(segment, (start, gap), book, joints)
+            return if segment.straight?
+
+            along = start + (segment.slot * EDGE_SPACING)
+            source_links(segment).each do |link|
+              points = bend_points(link, along) or next
+              book.record(link.edge, gap, points, joints.among(segment, points))
+            end
+          end
+
+          def source_links(segment)
+            segment.ports.select { |port| port.side == :east }
+              .flat_map(&:segments)
+          end
+
+          def bend_points(link, along)
+            from = cross_of(link.from_port)
+            to = cross_of(link.to_port)
+            return if (from - to).abs <= TOLERANCE
+
+            [[along, from], [along, to]]
+          end
+
+          def grouped_segments
+            groups = {}.compare_by_identity
+            @port_order.segments.each do |link|
+              (groups[link.edge] ||= []) << link
+            end
+            groups.transform_values do |links|
+              links.sort_by { |link| layer_index(link.from_port.item_id) }
+            end
+          end
+
+          def facing?(links)
+            links.all? do |link|
+              port_faces?(link.from_port, @facing.first) &&
+                port_faces?(link.to_port, @facing.last)
+            end
+          end
+
+          def port_faces?(port, side)
+            port.declared.nil? || port.declared.side == side
+          end
+
+          def layer_index(item_id)
+            @layer_index ||= index_layers
+            @layer_index.fetch(item_id)
+          end
+
+          def index_layers
+            map = {}
+            @layers.each_with_index do |layer, i|
+              layer.each { |item| map[item.id] = i }
+            end
+            map
+          end
+
+          def route(edge, links, book)
+            first = links.first.from_port
+            inner = gap_points(edge, links, book.bends)
+            points = [anchor(first, :high), *inner,
+                      anchor(links.last.to_port, :low)]
+            joined = gap_points(edge, links, book.junctions)
+            forward = forward?(edge, first)
+            Route.new(oriented(points, forward), oriented(joined, forward))
+          end
+
+          def oriented(points, forward)
+            real = points.map { |along, cross| real_point(along, cross) }
+            forward ? real : real.reverse
+          end
+
+          def gap_points(edge, links, per_gap)
+            links.flat_map do |link|
+              per_gap.dig(edge, layer_index(link.from_port.item_id)) || []
+            end
+          end
+
+          def forward?(edge, first_port)
+            @index.node(edge.sources.first)&.id == first_port.item_id
+          end
+
+          # The point where an edge meets a port: on the item's border, or
+          # beyond it for a declared port.
+          def anchor(port, side)
+            item = @items.fetch(port.item_id)
+            low, high = abstract_range(item)
+            reach = port.declared ? declared_extent(port.declared) : 0.0
+            along = side == :high ? high + reach : low - reach
+            [along, cross_of(port)]
+          end
+
+          def declared_extent(declared)
+            (declared.public_send(@vertical ? :height : :width) || 0).to_f
+          end
+
+          def abstract_range(item)
+            low, high = @along_range.call(item)
+            @sign.positive? ? [low, high] : [-high, -low]
+          end
+
+          # The far edge of a layer, port overhang included.
+          def layer_high(layer)
+            return 0.0 if layer.empty?
+
+            layer.map do |item|
+              declared = @port_order.visual(item.id, :east)
+                .filter_map(&:declared)
+              reach = declared.map { |d| declared_extent(d) }.max || 0.0
+              abstract_range(item).last + reach
+            end.max
+          end
+
+          def real_point(along, cross)
+            real = @sign * along
+            @vertical ? [cross, real] : [real, cross]
+          end
+        end
+      end
+    end
+  end
+end

data/lib/elkrb/layout/algorithms/layered/port_order.rb

@@ -0,0 +1,188 @@
+# frozen_string_literal: true
+
+module Elkrb
+  module Layout
+    module Algorithms
+      module Layered
+        # The port slots every layer item exposes toward its neighbouring
+        # layers, and the order they sit in.
+        #
+        # An edge crossing one layer gap is a Segment from an EAST slot of the
+        # item in the earlier layer to a WEST slot of the item in the later
+        # one. A slot is an explicit port, or the one slot a port-less
+        # endpoint gets per edge.
+        #
+        # A list is kept in the order ELK keeps it: EAST lists run top to
+        # bottom, WEST lists bottom to top. #visual always answers top to
+        # bottom. Sorting a WEST list ascending therefore places the lowest
+        # value at the bottom; the sweep in CrossingMinimizer depends on
+        # that.
+        class PortOrder
+          # One slot on the EAST or WEST side of a layer item.
+          class Port
+            attr_reader :item_id, :side, :declared, :sequence, :segments
+
+            def initialize(item_id:, side:, declared:, sequence:)
+              @item_id = item_id
+              @side = side
+              @declared = declared
+              @sequence = sequence
+              @segments = []
+            end
+
+            def others
+              segments.map { |segment| segment.other_port(self) }
+            end
+          end
+
+          # One edge crossing one layer gap, `from_port` in the earlier layer.
+          Segment = Struct.new(:edge, :from_port, :to_port) do
+            def other_port(port)
+              port.equal?(from_port) ? to_port : from_port
+            end
+          end
+
+          SIDES = %i[east west].freeze
+
+          attr_reader :segments
+
+          # @param layers [Array<Array>] nodes and DummySlots per layer
+          # @param index [NodeIndex, nil] resolves edge endpoints to nodes
+          def initialize(layers, index)
+            @layer_of = layer_map(layers)
+            @slots = dummy_slots_by_edge(layers)
+            @ports = {}
+            @segments = []
+            @index = index
+            (index ? index.edges : []).each_with_index do |edge, order|
+              add_edge(edge, order)
+            end
+            @lists = build_lists
+          end
+
+          # Ports of one side, top to bottom.
+          def visual(item_id, side)
+            list = list(item_id, side)
+            side == :west ? list.reverse : list
+          end
+
+          # Reorders a list ascending by the block's value. The sort is
+          # stable, so equal values keep their order.
+          def sort!(item_id, side)
+            list = list(item_id, side)
+            @lists[[item_id, side]] =
+              list.each_with_index.sort_by do |port, position|
+                [yield(port), position]
+              end.map(&:first)
+          end
+
+          # The port lists as they are now, for #restore.
+          def snapshot
+            @lists.transform_values(&:dup)
+          end
+
+          def restore(snapshot)
+            @lists = snapshot.transform_values(&:dup)
+          end
+
+          private
+
+          def list(item_id, side)
+            @lists.fetch([item_id, side], [])
+          end
+
+          def layer_map(layers)
+            layers.each_with_index.with_object({}) do |(layer, number), map|
+              layer.each { |item| map[item.id] = number }
+            end
+          end
+
+          def dummy_slots_by_edge(layers)
+            slots = {}.compare_by_identity
+            layers.flatten.select { |item| item.respond_to?(:layer_index) }
+              .sort_by(&:layer_index).each do |slot|
+                (slots[slot.edge] ||= []) << slot
+              end
+            slots
+          end
+
+          def add_edge(edge, order)
+            source = owner(edge.sources)
+            target = owner(edge.targets)
+            return unless placed?(source) && placed?(target)
+
+            add_chain(edge, order, *earlier_first(edge, source, target))
+          end
+
+          # The two nodes, earlier layer first, with the endpoint ids the
+          # edge names on each.
+          def earlier_first(edge, source, target)
+            named = [edge.sources.first, edge.targets.first]
+            if @layer_of[source.id] < @layer_of[target.id]
+              [[source, target], named]
+            else
+              [[target, source], named.reverse]
+            end
+          end
+
+          def placed?(node)
+            node && @layer_of.key?(node.id)
+          end
+
+          # `named` holds the endpoint ids the edge gives on the earlier and
+          # the later layer.
+          def add_chain(edge, order, ends, named)
+            chain = [ends.first, *Array(@slots[edge]), ends.last]
+            chain.each_cons(2).with_index do |pair, position|
+              next unless adjacent?(*pair)
+
+              add_segment(edge, order, pair,
+                          [position.zero? && named.first,
+                           position == chain.length - 2 && named.last])
+            end
+          end
+
+          def adjacent?(from, to)
+            @layer_of[to.id] - @layer_of[from.id] == 1
+          end
+
+          def add_segment(edge, order, items, endpoints)
+            segment = Segment.new(
+              edge,
+              port(items.first, :east, order, endpoints.first),
+              port(items.last, :west, order, endpoints.last),
+            )
+            segment.from_port.segments << segment
+            segment.to_port.segments << segment
+            @segments << segment
+          end
+
+          def port(item, side, order, endpoint)
+            declared = declared_port(item, endpoint)
+            key = declared ? declared.id : [:edge, order]
+            @ports[[item.id, side, key]] ||= Port.new(
+              item_id: item.id, side: side, declared: declared,
+              sequence: declared ? [0, item.ports.index(declared)] : [1, order]
+            )
+          end
+
+          def declared_port(item, endpoint)
+            return unless endpoint && item.respond_to?(:ports)
+
+            item.ports&.find { |candidate| candidate.id == endpoint }
+          end
+
+          def owner(endpoints)
+            id = (endpoints || []).first
+            @index.owner(id) if id
+          end
+
+          def build_lists
+            @ports.values.group_by { |port| [port.item_id, port.side] }
+              .transform_values { |ports| ports.sort_by(&:sequence) }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/elkrb/layout/algorithms/layered/port_spread.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Elkrb
+  module Layout
+    module Algorithms
+      module Layered
+        # Where the ports of one side sit along an item's cross axis: spread
+        # evenly, as ELK spaces free ports.
+        module PortSpread
+          # Cross offset of each port's centre from the start of its item.
+          #
+          # @param layers [Array<Array>] items per layer
+          # @param port_order [PortOrder]
+          # @param sizes [Hash{String=>Numeric}] cross size per item id
+          # @param port_size_of [#call] cross size of a port
+          # @return [Hash] offset per port, keyed by identity
+          def self.offsets(layers, port_order, sizes, port_size_of)
+            offsets = {}.compare_by_identity
+            layers.flatten.product(PortOrder::SIDES) do |item, side|
+              ports = port_order.visual(item.id, side)
+              spread(ports, sizes.fetch(item.id), port_size_of)
+                .each { |port, mid| offsets[port] = mid }
+            end
+            offsets
+          end
+
+          def self.spread(ports, extent, port_size_of)
+            widths = ports.map { |port| port_size_of.call(port) }
+            ports.zip(centres(widths, extent))
+          end
+
+          def self.centres(widths, extent)
+            gap = (extent - widths.sum) / (widths.length + 1)
+            widths.each_with_index.map do |width, i|
+              widths.first(i).sum + (gap * (i + 1)) + (width / 2.0)
+            end
+          end
+        end
+      end
+    end
+  end
+end