elkrb 1.0.0 → 2.0.0

data/lib/elkrb/layout/port_constraint_processor.rb

@@ -17,53 +17,124 @@ module Elkrb
       def apply_port_constraints(graph)
         return unless graph.children
 
-        graph.children.each do |node|
-          process_node_ports(node)
-        end
+        placed_port_order.clear
+        process_port_level(graph.children, graph.edges, graph)
       end
 
       private
 
+      def process_port_level(nodes, edges, owner)
+        inferred_sides = inferred_port_sides(edges, owner)
+        nodes.each do |node|
+          process_node_ports(node, inferred_sides)
+          process_port_level(node.children, node.edges, node) if node.children
+        end
+      end
+
       # Process ports for a single node
       #
       # @param node [Elkrb::Graph::Node] The node to process
-      def process_node_ports(node)
+      def process_node_ports(node, inferred_sides = {})
         return unless node.ports && !node.ports.empty?
-        return unless node.width && node.height && node.width.positive? && node.height.positive?
+        # Skip zero and non-finite dimensions: a zero axis has nothing to
+        # distribute along, and `[0, NaN].min` raises. Negative is fine.
+        return unless [node.width, node.height].all? { |dim| dim&.finite? && !dim.zero? }
 
-        # Detect sides if not specified
-        detect_port_sides(node)
+        detect_port_sides(node, inferred_sides)
+        constraint = @resolver.get("elk.portConstraints", node)
+        return if constraint == "FIXED_POS"
 
-        # Group ports by side
         ports_by_side = group_ports_by_side(node.ports)
 
-        # Apply ordering within each side
         ports_by_side.each do |side, ports|
-          order_ports_on_side(node, side, ports)
+          order_ports_on_side(
+            node, side, ports, fixed: fixed_order?(constraint)
+          )
         end
 
+        placed_port_order[node] = ports_by_side
+
         # Position ports on node boundaries
         position_ports_on_boundaries(node, ports_by_side)
       end
 
+      # Place a node's ports again after its size changed. A node that
+      # #process_node_ports already ordered keeps that order: indices cannot
+      # be sorted a second time (an explicit and an assigned one collide)
+      # and positions cannot be read back (they tie when the size is
+      # subnormal). A node it skipped gets the one full pass instead.
+      #
+      # @param node [Elkrb::Graph::Node] The node whose ports to place again
+      def replace_node_ports(node)
+        ports_by_side = placed_port_order[node]
+        return process_node_ports(node) unless ports_by_side
+        return unless [node.width, node.height].all? { |dim| dim&.finite? && !dim.zero? }
+
+        position_ports_on_boundaries(node, ports_by_side)
+      end
+
+      # Each node's ports per side, in the order #process_node_ports gave
+      # them. Keyed by identity: equal nodes would share one entry by value.
+      #
+      # @return [Hash{Elkrb::Graph::Node => Hash}]
+      def placed_port_order
+        @placed_port_order ||= {}.compare_by_identity
+      end
+
       # Detect port sides for ports with UNDEFINED side
       #
       # @param node [Elkrb::Graph::Node] The node containing the ports
-      def detect_port_sides(node)
+      def detect_port_sides(node, inferred_sides = {})
         node.ports.each do |port|
-          if port.side == Graph::Port::UNDEFINED
-            detected_side = port.detect_side(node.width, node.height)
-            port.side = detected_side
-          end
+          configured = @resolver.get("elk.port.side", port, default: nil) ||
+            port.side
+          side = configured&.upcase
+          side = port.detect_side(node.width, node.height) if
+            side.nil? || side == Graph::Port::UNDEFINED
+          side = inferred_sides.fetch(port.id, side) if
+            side == Graph::Port::UNDEFINED
+          validate_port_side!(port, side)
+          port.side = side unless side == Graph::Port::UNDEFINED && port.side.nil?
         end
       end
 
+      def inferred_port_sides(edges, owner)
+        outgoing_side, incoming_side = endpoint_sides(owner)
+        (edges || []).each_with_object({}) do |edge, sides|
+          next if edge.sources == edge.targets
+
+          (edge.sources || []).each { |id| sides[id] ||= outgoing_side }
+          (edge.targets || []).each { |id| sides[id] ||= incoming_side }
+        end
+      end
+
+      def endpoint_sides(owner)
+        case @resolver.get("elk.direction", owner)
+        when "LEFT" then [Graph::Port::WEST, Graph::Port::EAST]
+        when "DOWN" then [Graph::Port::SOUTH, Graph::Port::NORTH]
+        when "UP" then [Graph::Port::NORTH, Graph::Port::SOUTH]
+        else [Graph::Port::EAST, Graph::Port::WEST]
+        end
+      end
+
+      def validate_port_side!(port, side)
+        return if port.valid_side?(side)
+
+        raise ArgumentError,
+              "Invalid port side: #{side}. Must be one of " \
+              "#{Graph::Port::SIDES.join(', ')}"
+      end
+
       # Group ports by their side
       #
       # @param ports [Array<Elkrb::Graph::Port>] The ports to group
       # @return [Hash<String, Array<Elkrb::Graph::Port>>] Ports grouped by side
       def group_ports_by_side(ports)
-        ports.group_by(&:side)
+        ports.group_by { |port| port.side || Graph::Port::UNDEFINED }
+      end
+
+      def fixed_order?(constraint)
+        %w[FIXED_SIDE FIXED_ORDER].include?(constraint)
       end
 
       # Order ports on a specific side
@@ -75,11 +146,14 @@ module Elkrb
       # @param node [Elkrb::Graph::Node] The node containing the ports
       # @param side [String] The side to order ports on
       # @param ports [Array<Elkrb::Graph::Port>] The ports on this side
-      def order_ports_on_side(_node, side, ports)
+      def order_ports_on_side(_node, side, ports, fixed: false)
+        return order_fixed_ports(ports) if fixed
+
         # Sort by index if specified, otherwise by position
         ports.sort_by! do |port|
-          if port.index >= 0
-            port.index
+          index = port.index || -1
+          if index >= 0
+            index
           elsif [Graph::Port::NORTH, Graph::Port::SOUTH].include?(side)
             # Horizontal sides: sort by x position
             port.x || 0
@@ -91,49 +165,53 @@ module Elkrb
 
         # Assign sequential indices to ports without explicit index
         ports.each_with_index do |port, idx|
-          port.index = idx if port.index.negative?
+          port.index = idx if (port.index || -1).negative?
         end
       end
 
+      def order_fixed_ports(ports)
+        ordered = ports.each_with_index.sort_by do |(port, position)|
+          resolved_port_index(port) || position
+        end
+        ports.replace(ordered.map(&:first))
+        ports.each_with_index do |port, position|
+          port.index = resolved_port_index(port) || position
+        end
+      end
+
+      def resolved_port_index(port)
+        @resolver.get("elk.port.index", port, default: nil) || port.index
+      end
+
       # Position ports on node boundaries
       #
       # @param node [Elkrb::Graph::Node] The node containing the ports
       # @param ports_by_side [Hash<String, Array<Elkrb::Graph::Port>>] Ports grouped by side
       def position_ports_on_boundaries(node, ports_by_side)
+        # The real top/bottom and left/right local offsets -- for a negative
+        # height/width, local 0 is the real BOTTOM/RIGHT edge, so NORTH and
+        # SOUTH (and WEST/EAST) must pick whichever of 0/height (0/width) is
+        # actually the min/max, not always 0 for the "near" side.
+        top, bottom, left, right = [0, node.height].minmax + [0, node.width].minmax
+
         # NORTH: top edge, distributed horizontally
         if ports_by_side[Graph::Port::NORTH]
-          distribute_ports_horizontally(
-            node,
-            ports_by_side[Graph::Port::NORTH],
-            0,
-          )
+          distribute_ports_horizontally(node, ports_by_side[Graph::Port::NORTH], top)
         end
 
         # SOUTH: bottom edge, distributed horizontally
         if ports_by_side[Graph::Port::SOUTH]
-          distribute_ports_horizontally(
-            node,
-            ports_by_side[Graph::Port::SOUTH],
-            node.height,
-          )
+          distribute_ports_horizontally(node, ports_by_side[Graph::Port::SOUTH], bottom)
         end
 
         # WEST: left edge, distributed vertically
         if ports_by_side[Graph::Port::WEST]
-          distribute_ports_vertically(
-            node,
-            ports_by_side[Graph::Port::WEST],
-            0,
-          )
+          distribute_ports_vertically(node, ports_by_side[Graph::Port::WEST], left)
         end
 
         # EAST: right edge, distributed vertically
         if ports_by_side[Graph::Port::EAST]
-          distribute_ports_vertically(
-            node,
-            ports_by_side[Graph::Port::EAST],
-            node.width,
-          )
+          distribute_ports_vertically(node, ports_by_side[Graph::Port::EAST], right)
         end
       end
 
@@ -144,10 +222,15 @@ module Elkrb
       # @param y_pos [Float] The y position of the edge
       def distribute_ports_horizontally(node, ports, y_pos)
         count = ports.length
-        spacing = node.width / (count + 1).to_f
+        # Walk from the real left edge rightwards, so the ascending order
+        # #order_ports_on_side just sorted into is the order they land in --
+        # starting at local 0 reverses it when node.width is negative.
+        width = node.width
+        left = [0, width].min
+        spacing = (width.abs / (count + 1).to_f)
 
         ports.each_with_index do |port, idx|
-          port.x = spacing * (idx + 1)
+          port.x = left + (spacing * (idx + 1)) - ((port.width || 0.0) / 2.0)
           port.y = y_pos
           port.offset = port.x
         end
@@ -160,11 +243,15 @@ module Elkrb
       # @param x_pos [Float] The x position of the edge
       def distribute_ports_vertically(node, ports, x_pos)
         count = ports.length
-        spacing = node.height / (count + 1).to_f
+        # Same reason as #distribute_ports_horizontally: start at the real
+        # top edge so a negative node.height does not reverse the order.
+        height = node.height
+        top = [0, height].min
+        spacing = (height.abs / (count + 1).to_f)
 
         ports.each_with_index do |port, idx|
           port.x = x_pos
-          port.y = spacing * (idx + 1)
+          port.y = top + (spacing * (idx + 1)) - ((port.height || 0.0) / 2.0)
           port.offset = port.y
         end
       end

data/lib/elkrb/layout/spore/body.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module Elkrb
+  module Layout
+    module Spore
+      # A node as SPOrE sees it: the node's box grown by the node spacing
+      # (the rectangle), its moving centre, and the centre it had when the
+      # current pass started (the key that edges and tree vertices use).
+      class Body
+        attr_reader :source, :x, :y, :width, :height, :center_x, :center_y,
+                    :origin_x, :origin_y
+
+        def initialize(source, spacing)
+          @source = source
+          @width = source.width.to_f + spacing
+          @height = source.height.to_f + spacing
+          reposition(middle(source.x, source.width),
+                     middle(source.y, source.height))
+        end
+
+        def origin
+          [origin_x, origin_y]
+        end
+
+        def translate(shift_x, shift_y)
+          @center_x += shift_x
+          @center_y += shift_y
+          @x += shift_x
+          @y += shift_y
+        end
+
+        def center_at(new_x, new_y)
+          translate(new_x - center_x, new_y - center_y)
+        end
+
+        # Starts the next pass from where the last one left the node.
+        def rebase
+          @origin_x = x + (width / 2.0)
+          @origin_y = y + (height / 2.0)
+        end
+
+        # Moves the node a hair off its spot, so that two nodes that started
+        # on the same point get distinct centres and every tree edge has a
+        # direction to stretch along.
+        def nudge(rng)
+          reposition(center_x + ((rng.rand - 0.5) * 0.001),
+                     center_y + ((rng.rand - 0.5) * 0.001))
+        end
+
+        private
+
+        def middle(low, size)
+          low.to_f + (size.to_f / 2.0)
+        end
+
+        def reposition(new_x, new_y)
+          @center_x = @origin_x = new_x
+          @center_y = @origin_y = new_y
+          @x = new_x - (width / 2.0)
+          @y = new_y - (height / 2.0)
+        end
+      end
+    end
+  end
+end

data/lib/elkrb/layout/spore/depth_first_compaction.rb

@@ -0,0 +1,127 @@
+# frozen_string_literal: true
+
+require_relative "gap"
+require_relative "geometry"
+
+module Elkrb
+  module Layout
+    module Spore
+      # Compacts a spanning tree depth first: once a node's subtrees are
+      # compacted, each is slid as one piece toward the node until it would
+      # touch something, so the gaps between tree neighbours close.
+      class DepthFirstCompaction
+        # :free slides along the line between the two centres; the others
+        # slide along one axis only. :orthogonal picks the axis the centres
+        # are further apart on.
+        MODES = %i[free orthogonal horizontal vertical].freeze
+
+        # @param tree [SpanningTree::Branch] the tree, rooted at the branch
+        #   that stays put
+        # @param mode [Symbol] one of MODES
+        def self.compact(tree, mode: :free)
+          new(tree, mode).compact
+        end
+
+        def initialize(tree, mode)
+          @root = tree
+          @mode = mode
+        end
+
+        def compact
+          compact_branch(@root)
+        end
+
+        private
+
+        def compact_branch(branch)
+          branch.children.each { |child| compact_branch(child) }
+          close_gaps(branch)
+        end
+
+        def close_gaps(branch)
+          branch.children.each { |child| close_gap(branch.body, child) }
+        end
+
+        def close_gap(parent, child)
+          slide = slide_toward(parent, child.body)
+          limit = limit_by_others(@root, child, slide, length(slide))
+          translate(child, scale_to(slide, limit))
+        end
+
+        # The way and the distance the child would slide to meet its parent.
+        def slide_toward(parent, child)
+          slide = [parent.center_x - child.center_x,
+                   parent.center_y - child.center_y]
+          return scale_to(slide, Gap.underlap(parent, child)) if @mode == :free
+
+          slide_along(along_x?(slide) ? 0 : 1, parent, child, slide)
+        end
+
+        def along_x?(slide)
+          case @mode
+          when :horizontal then true
+          when :vertical then false
+          else slide[0].abs >= slide[1].abs
+          end
+        end
+
+        # Slides along axis +index+ (0 = x, 1 = y) only; the child stops at
+        # the parent's side when they share a stretch of the other axis.
+        def slide_along(index, parent, child, slide)
+          line = [0.0, 0.0].tap { |vector| vector[index] = slide[index] }
+          along, across = Geometry.axes(parent, child).rotate(index)
+          return line unless shares_stretch?(across)
+
+          scale_to(line, along.separation)
+        end
+
+        def shares_stretch?(axis)
+          axis.low_b + axis.size_b > axis.low_a &&
+            axis.low_b < axis.low_a + axis.size_a
+        end
+
+        # The shortest of +limit+ and the distance from every body outside
+        # the child's own subtree to the bodies below the child.
+        def limit_by_others(branch, child, slide, limit)
+          limit = [limit, limit_by_below(branch.body, child, slide, limit)].min
+          branch.children.each do |sub|
+            next if sub.equal?(child)
+
+            limit = [limit, limit_by_others(sub, child, slide, limit)].min
+          end
+          limit
+        end
+
+        # Looks at the bodies below +branch+, not at +branch+ itself.
+        def limit_by_below(other, branch, slide, limit)
+          branch.children.each do |sub|
+            if Gap.touch?(other, sub.body)
+              return 0 if Gap.pressed?(other, sub.body, slide)
+            else
+              limit = [limit, Gap.distance(other, sub.body, slide)].min
+            end
+            limit = [limit, limit_by_below(other, sub, slide, limit)].min
+          end
+          limit
+        end
+
+        def translate(branch, shift)
+          branch.body.translate(*shift)
+          branch.children.each { |sub| translate(sub, shift) }
+        end
+
+        def length(vector)
+          Math.sqrt((vector[0] * vector[0]) + (vector[1] * vector[1]))
+        end
+
+        # Same direction, new length (a zero vector stays zero).
+        def scale_to(vector, new_length)
+          size = length(vector)
+          return vector unless size.positive?
+
+          [vector[0] / size * new_length, vector[1] / size * new_length]
+        end
+      end
+    end
+  end
+end

data/lib/elkrb/layout/spore/edge_cost.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+require_relative "gap"
+require_relative "geometry"
+
+module Elkrb
+  module Layout
+    module Spore
+      # The cost of a spanning-tree edge between two bodies, by the names ELK
+      # gives its cost functions. Costs read the bodies' positions from
+      # before the pass moved anything.
+      module EdgeCost
+        NAMES = %w[CENTER_DISTANCE CIRCLE_UNDERLAP RECTANGLE_UNDERLAP
+                   INVERTED_OVERLAP MINIMUM_ROOT_DISTANCE].freeze
+
+        module_function
+
+        # @param name [String] one of NAMES
+        # @param root [Body] the body the tree grows from
+        # @return [Proc] takes two bodies, returns their edge's cost
+        def for(name, root)
+          case name
+          when "CENTER_DISTANCE" then method(:center_distance)
+          when "CIRCLE_UNDERLAP" then method(:circle_underlap)
+          when "RECTANGLE_UNDERLAP" then Gap.method(:underlap)
+          when "INVERTED_OVERLAP" then method(:inverted_overlap)
+          when "MINIMUM_ROOT_DISTANCE" then root_distance(root)
+          else raise ArgumentError, "unknown cost function #{name.inspect}"
+          end
+        end
+
+        def center_distance(first, second)
+          Geometry.distance(first.origin_x, first.origin_y,
+                            second.origin_x, second.origin_y)
+        end
+
+        # The distance between the circles around the two rectangles, each
+        # reaching from its centre to its top left corner.
+        def circle_underlap(first, second)
+          center_distance(first, second) - reach(first) - reach(second)
+        end
+
+        def reach(body)
+          Geometry.distance(body.origin_x, body.origin_y, body.x, body.y)
+        end
+
+        def root_distance(root)
+          lambda do |first, second|
+            [first, second].map do |body|
+              Geometry.distance(body.origin_x, body.origin_y,
+                                root.center_x, root.center_y)
+            end.min
+          end
+        end
+
+        # Negative and growing with the overlap when the rectangles overlap,
+        # so the most overlapped pairs join the tree first.
+        def inverted_overlap(first, second)
+          distance = Geometry.shortest_distance(first, second)
+          return distance if distance >= 0
+
+          between = Geometry.distance(first.center_x, first.center_y,
+                                      second.center_x, second.center_y)
+          -(Geometry.overlap(first, second) - 1) * between
+        end
+      end
+    end
+  end
+end

data/lib/elkrb/layout/spore/gap.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+require_relative "geometry"
+require_relative "rays"
+
+module Elkrb
+  module Layout
+    module Spore
+      # How far apart two bodies' rectangles are, in the three senses the
+      # tree compaction needs.
+      module Gap
+        # Corner pairs that make up a rectangle's four sides, indexing
+        # [top left, bottom left, top right, bottom right].
+        EDGE_CORNERS = [[0, 2], [0, 1], [3, 2], [3, 1]].freeze
+
+        module_function
+
+        # How far the rectangles can be pushed together along the line
+        # between their centres before they touch (0 when their reach
+        # overlaps on both axes).
+        def underlap(first, second)
+          axes = Geometry.axes(first, second)
+          scale = axes.map { |axis| reach_scale(axis) }.min
+          centres = Math.sqrt(axes.sum { |axis| axis.center_distance**2 })
+          (1 - scale) * centres
+        end
+
+        # 1 when the rectangles' reach overlaps on this axis, else the share
+        # of the centre distance left once they touch.
+        def reach_scale(axis)
+          axis.within_reach? ? 1 : 1 - axis.ratio
+        end
+
+        # Whether the rectangles share a point, give or take rounding noise.
+        def touch?(first, second)
+          Geometry.axes(first, second).all? do |axis|
+            Geometry.fuzzy_compare(axis.separation, 0.0,
+                                   Geometry::FUZZINESS) <= 0
+          end
+        end
+
+        # Whether first's side lies exactly on second's, on the side that a
+        # push along +direction+ would drive them into each other.
+        def pressed?(first, second, direction)
+          Geometry.axes(first, second).zip(direction).any? do |axis, push|
+            pressed_on?(axis, push)
+          end
+        end
+
+        def pressed_on?(axis, push)
+          (push.negative? && flush?(axis.low_b, axis.low_a + axis.size_a)) ||
+            (push.positive? && flush?(axis.low_b + axis.size_b, axis.low_a))
+        end
+
+        def flush?(left, right)
+          Geometry.fuzzy_compare(left, right, Geometry::FUZZINESS).zero?
+        end
+
+        # How far +second+ can move along +direction+ before it hits +first+
+        # (Infinity when it never does).
+        def distance(first, second, direction)
+          edges(first).product(edges(second)).map do |one, other|
+            Rays.distance(*one, *other, direction)
+          end.min
+        end
+
+        def edges(body)
+          xs = [body.x, body.x + body.width]
+          ys = [body.y, body.y + body.height]
+          corners = xs.product(ys)
+          EDGE_CORNERS.map { |from, to| [corners[from], corners[to]] }
+        end
+      end
+    end
+  end
+end