elkrb 1.0.0 → 2.0.0

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

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+module Elkrb
+  module Layout
+    module Spore
+      # Rectangle arithmetic shared by the SPOrE overlap removal phases.
+      # Rectangles are anything answering x, y, width and height.
+      module Geometry
+        FUZZINESS = 0.0001
+        DISTANCE_EPSILON = 0.00001
+
+        # Two rectangles seen along one axis.
+        Axis = Struct.new(:low_a, :size_a, :low_b, :size_b) do
+          # Signed gap between the nearer sides; negative when they overlap.
+          def separation
+            [low_a - (low_b + size_b), low_b - (low_a + size_a)].max
+          end
+
+          # Distance from the far side of one to the near side of the other,
+          # the smaller of the two ways round.
+          def span_gap
+            [(low_a - (low_b + size_b)).abs, (low_a + size_a - low_b).abs].min
+          end
+
+          def center_distance
+            ((low_a + (size_a / 2.0)) - (low_b + (size_b / 2.0))).abs
+          end
+
+          def within_reach?
+            center_distance <= (size_a / 2.0) + (size_b / 2.0)
+          end
+
+          def coincident?
+            center_distance.zero?
+          end
+
+          def ratio
+            span_gap / center_distance
+          end
+
+          def depth
+            [low_a + size_a, low_b + size_b].min - [low_a, low_b].max
+          end
+        end
+
+        module_function
+
+        def distance(from_x, from_y, to_x, to_y)
+          dx = from_x - to_x
+          dy = from_y - to_y
+          Math.sqrt((dx * dx) + (dy * dy))
+        end
+
+        # Guava's DoubleMath.fuzzyCompare: 0 when within +tolerance+.
+        def fuzzy_compare(left, right, tolerance)
+          return 0 if fuzzy_equal?(left, right, tolerance)
+          return left <=> right unless left.nan? || right.nan?
+
+          left.nan? ? 1 : -1
+        end
+
+        def fuzzy_equal?(left, right, tolerance)
+          left == right || (left - right).abs <= tolerance ||
+            (left.nan? && right.nan?)
+        end
+
+        def axes(first, second)
+          [Axis.new(first.x, first.width, second.x, second.width),
+           Axis.new(first.y, first.height, second.y, second.height)]
+        end
+
+        # The factor by which the line between the two centres must be
+        # stretched for the rectangles to just touch (1.0 when they already
+        # do not overlap). The centres must differ.
+        def overlap(first, second)
+          both = axes(first, second)
+          return 1.0 unless both.all?(&:within_reach?)
+
+          apart = both.reject(&:coincident?)
+          return 0.0 if apart.empty?
+
+          apart.map(&:ratio).min + 1
+        end
+
+        # Whether the rectangles share more than rounding noise in both axes.
+        def intersect?(first, second)
+          axes(first, second).all? { |axis| axis.depth > FUZZINESS }
+        end
+
+        # Distance between the closest sides (touching sides: 0), or the
+        # negated corner distance when the rectangles overlap.
+        def shortest_distance(first, second)
+          horizontal, vertical = axes(first, second).map(&:separation)
+          h_clear = fuzzy_compare(horizontal, 0.0, DISTANCE_EPSILON)
+          v_clear = fuzzy_compare(vertical, 0.0, DISTANCE_EPSILON)
+          return [vertical, horizontal].max if (h_clear >= 0) ^ (v_clear >= 0)
+
+          corner = Math.sqrt((vertical * vertical) + (horizontal * horizontal))
+          h_clear.positive? ? corner : -corner
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+module Elkrb
+  module Layout
+    module Spore
+      # Top-to-bottom scanline that reports the pairs of bodies whose
+      # rectangles overlap. Mirrors the Java sweep, including its early stop:
+      # once a newly inserted body has met an overlapping neighbour, the scan
+      # of the left-sorted active set ends at the next non-overlapping one.
+      class OverlapSweep
+        # @return [Array<Array(Body, Body)>] each pair once, in sweep order
+        def self.pairs(bodies)
+          new.pairs(bodies)
+        end
+
+        def pairs(bodies)
+          @active = []
+          @pairs = []
+          events(bodies).each do |body, low|
+            low ? insert(body) : remove(body)
+          end
+          @pairs
+        end
+
+        private
+
+        # Each body twice (top border, bottom border), by row.
+        def events(bodies)
+          stamps = bodies.flat_map { |body| [[body, true], [body, false]] }
+          stamps.each_with_index.sort do |(first, i), (second, j)|
+            compare(first, second).nonzero? || (i <=> j)
+          end.map(&:first)
+        end
+
+        # At equal rows the bottom borders come first.
+        def compare(first, second)
+          by_row = row(first) <=> row(second)
+          return by_row unless by_row.zero?
+
+          (first.last ? 1 : 0) <=> (second.last ? 1 : 0)
+        end
+
+        def row(stamp)
+          body, low = stamp
+          low ? body.y : body.y + body.height
+        end
+
+        def remove(body)
+          @active.delete_if { |other| other.equal?(body) }
+        end
+
+        def insert(body)
+          at = @active.bsearch_index do |other|
+            (sort_key(other) <=> sort_key(body)) >= 0
+          end
+          @active.insert(at || @active.size, body)
+          collect_pairs(body)
+        end
+
+        # The active set is not guaranteed to hold the overlaps contiguously
+        # (a wide body can hide behind a narrow one); the scan stops at the
+        # first gap after a hit, as Java's does.
+        def collect_pairs(body)
+          met = false
+          @active.each do |other|
+            if overlapping?(body, other)
+              @pairs << [body, other]
+              met = true
+            elsif met
+              break
+            end
+          end
+        end
+
+        def sort_key(body)
+          [body.x, body.origin_x, body.origin_y]
+        end
+
+        def overlapping?(first, second)
+          return false if first.equal?(second)
+
+          Geometry.fuzzy_compare(first.x, second.x + second.width,
+                                 Geometry::FUZZINESS).negative? &&
+            Geometry.fuzzy_compare(second.x, first.x + first.width,
+                                   Geometry::FUZZINESS).negative?
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+require_relative "body"
+require_relative "geometry"
+
+module Elkrb
+  module Layout
+    module Spore
+      # Reading nodes into bodies and writing them back, shared by the two
+      # SPOrE algorithms. The including algorithm supplies +rng+ and +option+.
+      module Placement
+        # ELK's own defaults for the SPOrE algorithms; the shared registry
+        # values are for the other algorithms.
+        DEFAULT_SPACING = 8.0
+        DEFAULT_PADDING = {
+          left: 8.0, top: 8.0, right: 8.0, bottom: 8.0
+        }.freeze
+
+        private
+
+        def padding
+          option("elk.padding", default: DEFAULT_PADDING).to_h
+        end
+
+        def build_bodies(nodes, spacing)
+          seen = {}
+          nodes.map do |node|
+            body = Body.new(node, spacing)
+            body.nudge(rng) while seen.key?(body.origin)
+            seen[body.origin] = true
+            body
+          end
+        end
+
+        # The body whose centre is nearest the middle of the graph; the first
+        # of equally near ones.
+        def most_central(bodies, graph)
+          cx, cy = middle(graph)
+          bodies.each_with_index.min_by do |body, i|
+            [Geometry.distance(body.origin_x, body.origin_y, cx, cy), i]
+          end.first
+        end
+
+        def middle(graph)
+          [graph.x.to_f + (graph.width.to_f / 2.0),
+           graph.y.to_f + (graph.height.to_f / 2.0)]
+        end
+
+        def place(body)
+          node = body.source
+          node.x = body.center_x - (node.width.to_f / 2.0)
+          node.y = body.center_y - (node.height.to_f / 2.0)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,119 @@
+# frozen_string_literal: true
+
+module Elkrb
+  module Layout
+    module Spore
+      # Distance between two line segments measured along a direction, by
+      # tracing rays from each segment's end points onto the other. Points
+      # and vectors are [x, y] pairs of floats.
+      module Rays
+        # How close two points must be to count as the same end point.
+        END_POINT_TOLERANCE = 0.05
+
+        module_function
+
+        # @return [Float] the distance from segment b to segment a along
+        #   +direction+, or from a to b along its opposite, whichever is
+        #   smaller; Infinity when neither reaches
+        def distance(a_from, a_to, b_from, b_to, direction)
+          [trace(a_from, a_to, b_from, b_to, direction),
+           trace(b_from, b_to, a_from, a_to, negate(direction))].min
+        end
+
+        def trace(a_from, a_to, b_from, b_to, direction)
+          a_span = minus(a_to, a_from)
+          grazing = grazing_ray?([a_from, a_to], [b_from, b_to], direction)
+          hits = [b_from, b_to].map do |origin|
+            [origin, crossing(a_from, a_span, origin, direction)]
+          end
+          shortest(a_from, a_to, hits, grazing)
+        end
+
+        # One ray lands exactly on an end point of a while the shifted
+        # segment crosses a elsewhere, so the other ray's miss is not a miss.
+        def grazing_ray?(segment_a, segment_b, direction)
+          a_from, a_to = segment_a
+          b_from, b_to = segment_b
+          shifted = crossing(a_from, minus(a_to, a_from),
+                             plus(b_from, direction), minus(b_to, b_from))
+          !shifted.nil? && !near?(shifted, a_from) && !near?(shifted, a_to)
+        end
+
+        # The first ray that lands on an end point of a is dropped, but lets
+        # the second one through.
+        def shortest(a_from, a_to, hits, grazing)
+          forgiven = grazing
+          hits.filter_map do |origin, point|
+            next unless point
+
+            if near?(point, a_from) != near?(point, a_to) && !forgiven
+              forgiven = true
+              next
+            end
+            length(minus(point, origin))
+          end.min || Float::INFINITY
+        end
+
+        # Where the segments p + t*r and q + u*s meet (0 <= t, u <= 1), the
+        # point of the collinear overlap nearest the middle of the second
+        # when they overlap along a line, or nil.
+        def crossing(p_from, r_span, q_from, s_span)
+          offset = minus(q_from, p_from)
+          return transversal(p_from, r_span, offset, s_span) unless
+            cross(r_span, s_span).zero?
+
+          return unless cross(offset, r_span).zero?
+
+          collinear(p_from, r_span, q_from, s_span)
+        end
+
+        def transversal(p_from, r_span, offset, s_span)
+          r_cross_s = cross(r_span, s_span)
+          t = cross(offset, s_span) / r_cross_s
+          u = cross(offset, r_span) / r_cross_s
+          plus(p_from, scale(r_span, t)) if t.between?(0, 1) && u.between?(0, 1)
+        end
+
+        def collinear(p_from, r_span, q_from, s_span)
+          middle = plus(q_from, scale(s_span, 0.5))
+          near_start = length(minus(p_from, middle))
+          p_to = plus(p_from, r_span)
+          near_end = length(minus(p_to, middle))
+          reach = length(s_span) * 0.5
+          return p_from if near_start < near_end && near_start <= reach
+
+          p_to if near_end <= reach
+        end
+
+        def near?(first, second)
+          (first[0] - second[0]).abs <= END_POINT_TOLERANCE &&
+            (first[1] - second[1]).abs <= END_POINT_TOLERANCE
+        end
+
+        def minus(first, second)
+          [first[0] - second[0], first[1] - second[1]]
+        end
+
+        def plus(first, second)
+          [first[0] + second[0], first[1] + second[1]]
+        end
+
+        def scale(vector, factor)
+          [vector[0] * factor, vector[1] * factor]
+        end
+
+        def negate(vector)
+          [-vector[0], -vector[1]]
+        end
+
+        def cross(first, second)
+          (first[0] * second[1]) - (first[1] * second[0])
+        end
+
+        def length(vector)
+          Math.sqrt((vector[0] * vector[0]) + (vector[1] * vector[1]))
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module Elkrb
+  module Layout
+    module Spore
+      # Minimum spanning tree grown outward from a root by repeatedly adding
+      # the cheapest edge that joins a tree body to a body not yet in it.
+      # Edges of equal cost are taken in the order given.
+      module SpanningTree
+        # A body and the bodies reached through it.
+        Branch = Struct.new(:body, :children)
+
+        module_function
+
+        # @param edges [Array<Array(Body, Body)>]
+        # @param root [Body]
+        # @yieldparam first [Body]
+        # @yieldparam second [Body]
+        # @yieldreturn [Float] the edge's cost
+        # @return [Branch]
+        def build(edges, root, &)
+          pending = by_cost(edges, &)
+          tree = Branch.new(root, [])
+          branches = {}.compare_by_identity
+          branches[root] = tree
+          while (index = cheapest_crossing(pending, branches))
+            attach(branches, *pending.delete_at(index))
+          end
+          tree
+        end
+
+        def by_cost(edges, &)
+          edges.each_with_index
+            .sort_by { |(first, second), i| [yield(first, second), i] }
+            .map(&:first)
+        end
+
+        def cheapest_crossing(pending, branches)
+          pending.index do |first, second|
+            branches.key?(first) != branches.key?(second)
+          end
+        end
+
+        def attach(branches, first, second)
+          from, added = branches.key?(first) ? [first, second] : [second, first]
+          branch = Branch.new(added, [])
+          branches[from].children << branch
+          branches[added] = branch
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,159 @@
+# frozen_string_literal: true
+
+module Elkrb
+  module Layout
+    module Spore
+      # Delaunay triangulation by incremental Bowyer-Watson insertion into a
+      # super-triangle. Points are [x, y] pairs and must be distinct.
+      module Triangulation
+        WIGGLE_ROOM = 50.0
+
+        # The extent of a point set.
+        Bounds = Struct.new(:min_x, :max_x, :min_y, :max_y) do
+          def width
+            max_x - min_x
+          end
+
+          def half_height
+            (max_y - min_y) / 2
+          end
+
+          def frame_top
+            [min_x - WIGGLE_ROOM, min_y - width - WIGGLE_ROOM]
+          end
+
+          def frame_bottom
+            [min_x - WIGGLE_ROOM, max_y + width + WIGGLE_ROOM]
+          end
+
+          def frame_tip
+            [max_x + half_height + WIGGLE_ROOM, min_y + half_height]
+          end
+        end
+
+        # Vector arithmetic on [x, y] pairs.
+        module Pair
+          module_function
+
+          def delta(from, to)
+            [to[0] - from[0], to[1] - from[1]]
+          end
+
+          def sum(first, second)
+            [first[0] + second[0], first[1] + second[1]]
+          end
+
+          def dot(first, second)
+            (first[0] * second[0]) + (first[1] * second[1])
+          end
+
+          def cross(first, second)
+            (first[0] * second[1]) - (first[1] * second[0])
+          end
+
+          def distance(from, to)
+            Math.sqrt(dot(delta(from, to), delta(from, to)))
+          end
+        end
+
+        # A triangle with its circumcentre cached.
+        Triangle = Struct.new(:a, :b, :c) do
+          def vertices
+            [a, b, c]
+          end
+
+          def edges
+            [[a, b], [b, c], [c, a]]
+          end
+
+          def contains_edge?(edge)
+            edges.any? { |own| Triangulation.same_edge?(own, edge) }
+          end
+
+          def circumcenter
+            @circumcenter ||= compute_circumcenter
+          end
+
+          def in_circumcircle?(point)
+            Geometry.fuzzy_compare(Pair.distance(circumcenter, point),
+                                   Pair.distance(circumcenter, a),
+                                   Geometry::FUZZINESS).negative?
+          end
+
+          private
+
+          def compute_circumcenter
+            ab = Pair.delta(a, b)
+            ac = Pair.delta(a, c)
+            e, f, g = circumcenter_terms(ab, ac)
+            [term(1, ac, e, ab, f) / g, term(0, ab, f, ac, e) / g]
+          end
+
+          def circumcenter_terms(ab_vec, ac_vec)
+            [Pair.dot(ab_vec, Pair.sum(a, b)),
+             Pair.dot(ac_vec, Pair.sum(a, c)),
+             2 * Pair.cross(ab_vec, Pair.delta(b, c))]
+          end
+
+          def term(index, first, first_scale, second, second_scale)
+            (first[index] * first_scale) - (second[index] * second_scale)
+          end
+        end
+
+        module_function
+
+        def same_edge?(first, second)
+          first == second || first == second.reverse
+        end
+
+        # @param points [Array<Array(Float, Float)>]
+        # @return [Array<Array(Array, Array)>] each edge once
+        def triangulate(points)
+          return [] if points.empty?
+
+          frame = enclosing_triangle(points)
+          triangles = points.reduce([frame]) do |current, point|
+            insert(current, point)
+          end
+          inner_edges(triangles, frame).uniq(&:sort)
+        end
+
+        def inner_edges(triangles, frame)
+          triangles.flat_map(&:edges).reject do |edge|
+            edge.any? { |vertex| frame.vertices.include?(vertex) }
+          end
+        end
+
+        # Large enough that no point sits near its border, which would give
+        # circumcircles too big for a double to compare.
+        def enclosing_triangle(points)
+          bounds = Bounds.new(*points.map(&:first).minmax,
+                              *points.map(&:last).minmax)
+          Triangle.new(bounds.frame_top, bounds.frame_bottom,
+                       bounds.frame_tip)
+        end
+
+        def insert(triangles, point)
+          invalid, valid = triangles.partition do |triangle|
+            triangle.in_circumcircle?(point)
+          end
+          boundary(invalid).each do |from, to|
+            valid << Triangle.new(point, from, to)
+          end
+          valid
+        end
+
+        # Edges of the invalid triangles that no other invalid triangle has.
+        def boundary(invalid)
+          invalid.flat_map do |triangle|
+            triangle.edges.select do |edge|
+              invalid.none? do |other|
+                !other.equal?(triangle) && other.contains_edge?(edge)
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/elkrb/layout_flags.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module Elkrb
+  # @api private
+  #
+  # The one table that turns CLI flags into layout options. A flag the user
+  # typed becomes a canonical option on the ROOT graph, where it outranks
+  # whatever the file says for itself. A flag the user did not type is never
+  # written, so the file's own options (including its elk.algorithm pin)
+  # stay in charge.
+  module LayoutFlags
+    OPTION_IDS = {
+      algorithm: "elk.algorithm",
+      spacing: "elk.spacing.nodeNode",
+      layer_spacing: "elk.layered.spacing.nodeNodeBetweenLayers",
+      direction: "elk.direction",
+      edge_routing: "elk.edgeRouting",
+    }.freeze
+    private_constant :OPTION_IDS
+
+    PADDING_FLAGS = %i[padding_top padding_bottom padding_left padding_right]
+      .freeze
+    private_constant :PADDING_FLAGS
+
+    # ELK parses a padding string with missing sides as 0, so the sides the
+    # user did not give are written out as the registry default.
+    DEFAULT_PADDING = 12
+    private_constant :DEFAULT_PADDING
+
+    class << self
+      # @param graph [Elkrb::Graph::Graph, Hash] a Graph, or the Hash an
+      #   ELKT parse returns
+      # @param options [Hash] Thor options, Symbol keys; only the flags
+      #   present are applied
+      # @return [Elkrb::Graph::Graph] the graph, with the flags written onto
+      #   its layoutOptions
+      def apply(graph, options)
+        graph = Graph::Graph.from_hash(graph) if graph.is_a?(::Hash)
+        graph.layout_options = {} if graph.layout_options.nil?
+
+        flag_options(options).each do |id, value|
+          graph.layout_options[id] = value
+        end
+        graph
+      end
+
+      private
+
+      def flag_options(options)
+        given = OPTION_IDS.filter_map do |flag, id|
+          [id, options[flag]] unless options[flag].nil?
+        end.to_h
+
+        padding = padding_string(options)
+        given["elk.padding"] = padding if padding
+        given
+      end
+
+      def padding_string(options)
+        return nil if PADDING_FLAGS.all? { |flag| options[flag].nil? }
+
+        side = ->(flag) { options[flag] || DEFAULT_PADDING }
+        "[top=#{side.call(:padding_top)},left=#{side.call(:padding_left)}," \
+          "bottom=#{side.call(:padding_bottom)}," \
+          "right=#{side.call(:padding_right)}]"
+      end
+    end
+  end
+end

data/lib/elkrb/options/decimal.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module Elkrb
+  module Options
+    # Reads the numbers inside an option value. String#to_f answers 0.0 for
+    # "abc" and for "0x10", which would lay a graph out with zero spacing and
+    # no sign anything was wrong, so a string must be plain decimal notation.
+    # Float() is not the guard: it also takes "0x10".
+    module Decimal
+      PATTERN = /\A[+-]?(?:\d+\.?\d*|\.\d+)(?:[eE][+-]?\d+)?\z/
+      # Ruby 3.3's Float() rejects "5." and "1.e3"; 3.4 accepts them.
+      TRAILING_DOT = /\.(?=\D|\z)/
+      private_constant :PATTERN, :TRAILING_DOT
+
+      # @param text [String]
+      # @return [Float, nil] nil unless text is plain decimal in a readable
+      #   encoding
+      def self.parse(text)
+        return unless text.encoding.ascii_compatible? && text.valid_encoding?
+
+        stripped = text.strip
+        Float(stripped.sub(TRAILING_DOT, ".0")) if PATTERN.match?(stripped)
+      end
+
+      # @param value [String, Numeric, nil] a number or its text; nil is 0.0
+      # @return [Float]
+      # @raise [ArgumentError] when a String is not plain decimal, or the
+      #   value is neither a number nor a String (false, true, an Array)
+      def self.to_f(value)
+        return value.to_f if value.nil? || value.is_a?(Numeric)
+
+        (value.is_a?(String) && parse(value)) ||
+          raise(ArgumentError, "Invalid number: #{value.inspect}")
+      end
+
+      # The first non-nil of hash[key as Symbol], hash[key as String], so an
+      # explicit false reaches to_f and is rejected instead of reading as
+      # absent the way `||` would.
+      #
+      # @param hash [Hash]
+      # @param key [Symbol]
+      # @param default [Object] returned when both spellings are nil
+      def self.component(hash, key, default)
+        value = hash[key]
+        value = hash[key.to_s] if value.nil?
+        value.nil? ? default : value
+      end
+    end
+  end
+end