etassia 0.1.0

data/lib/etassia/layout/mindmap_cose_geometry.rb

@@ -0,0 +1,190 @@
+# frozen_string_literal: true
+
+module Etassia
+  module Layout
+    # Box geometry of the mindmap force layout: overlap, the border points
+    # where the line between two box centres leaves each box, and how far
+    # two overlapping boxes must move apart.
+    module MindmapCoseGeometry
+      # [slope sign, first side to test] for the first box, keyed by whether
+      # the other box lies to its left and above it. The second box uses
+      # the side two steps round.
+      CARDINAL_LINES = {
+        [true, true] => [1, 4],
+        [true, false] => [-1, 3],
+        [false, true] => [-1, 1],
+        [false, false] => [1, 2],
+      }.freeze
+
+      module_function
+
+      # @return [Array<Float>] [left, top, right, bottom] around +bodies+
+      def bounding_box(bodies)
+        [bodies.map(&:x).min, bodies.map(&:y).min,
+         bodies.map(&:right).max, bodies.map(&:bottom).max]
+      end
+
+      def intersects?(first, second)
+        !(first.right < second.x || first.bottom < second.y ||
+          second.right < first.x || second.bottom < first.y)
+      end
+
+      # @return [Array<Float>, nil] [x1, y1, x2, y2] where the centre line
+      #   leaves +first+ and +second+, or nil when the boxes overlap.
+      def clip_points(first, second)
+        return nil if intersects?(first, second)
+
+        aligned_clip(first, second) || slanted_clip(first, second)
+      end
+
+      def aligned_clip(first, second)
+        if first.center_x == second.center_x
+          vertical_clip(first, second)
+        elsif first.center_y == second.center_y
+          horizontal_clip(first, second)
+        end
+      end
+
+      def vertical_clip(first, second)
+        x1 = first.center_x
+        x2 = second.center_x
+        if first.center_y > second.center_y
+          [x1, first.y, x2, second.bottom]
+        else
+          [x1, first.bottom, x2, second.y]
+        end
+      end
+
+      def horizontal_clip(first, second)
+        y1 = first.center_y
+        y2 = second.center_y
+        if first.center_x > second.center_x
+          [first.x, y1, second.right, y2]
+        else
+          [first.right, y1, second.x, y2]
+        end
+      end
+
+      def slanted_clip(first, second)
+        slope = slope_between(first, second)
+        left_up = [first.center_x > second.center_x,
+                   first.center_y > second.center_y]
+        border_point(first, slope, left_up, second_box: false) +
+          border_point(second, slope, left_up, second_box: true)
+      end
+
+      def slope_between(first, second)
+        rise = second.center_y - first.center_y
+        run = second.center_x - first.center_x
+        rise / run
+      end
+
+      def border_point(box, slope, left_up, second_box:)
+        other_left = second_box ? !left_up[0] : left_up[0]
+        corner = corner_point(box, slope, other_left)
+        return corner if corner
+
+        sign, line = CARDINAL_LINES.fetch(left_up)
+        line = ((line + 1) % 4) + 1 if second_box
+        side_point(box, slope, cardinal(sign * box_slope(box), slope, line))
+      end
+
+      def box_slope(box)
+        box.height / box.width
+      end
+
+      def corner_point(box, slope, other_left)
+        diagonal = box_slope(box)
+        if -diagonal == slope
+          other_left ? [box.x, box.bottom] : [box.right, box.y]
+        elsif diagonal == slope
+          other_left ? [box.x, box.y] : [box.right, box.bottom]
+        end
+      end
+
+      def cardinal(box_slope, slope, line)
+        box_slope > slope ? line : 1 + (line % 4)
+      end
+
+      def side_point(box, slope, direction)
+        case direction
+        when 1 then top_point(box, slope)
+        when 2 then right_point(box, slope)
+        when 3 then bottom_point(box, slope)
+        else left_point(box, slope)
+        end
+      end
+
+      def top_point(box, slope)
+        [box.center_x + (-box.half_height / slope), box.y]
+      end
+
+      def right_point(box, slope)
+        [box.right, box.center_y + (box.half_width * slope)]
+      end
+
+      def bottom_point(box, slope)
+        [box.center_x + (box.half_height / slope), box.bottom]
+      end
+
+      def left_point(box, slope)
+        [box.x, box.center_y + (-box.half_width * slope)]
+      end
+
+      # How far each of two overlapping boxes is pushed along each axis.
+      #
+      # @return [Array<Float>] [x, y] separation for the first box
+      def separation(first, second, buffer)
+        move_x, move_y = overlap_shift(first, second)
+        direction_x = direction(first.center_x, second.center_x)
+        direction_y = direction(first.center_y, second.center_y)
+        [push(direction_x, move_x, buffer), push(direction_y, move_y, buffer)]
+      end
+
+      def push(direction, move, buffer)
+        -1 * direction * ((move / 2) + buffer)
+      end
+
+      # The overlap along the axis it is cheaper to separate on, and the
+      # matching movement along the other axis.
+      def overlap_shift(first, second)
+        overlap_x, overlap_y = overlaps(first, second)
+        slope = centre_slope(first, second)
+        move_x = overlap_y / slope
+        if overlap_x < move_x
+          [overlap_x, slope * overlap_x]
+        else
+          [move_x, overlap_y]
+        end
+      end
+
+      def direction(first_centre, second_centre)
+        first_centre < second_centre ? -1 : 1
+      end
+
+      def centre_slope(first, second)
+        same_row = first.center_y == second.center_y
+        same_column = first.center_x == second.center_x
+        return 1.0 if same_row && same_column
+
+        slope_between(first, second).abs
+      end
+
+      def overlaps(first, second)
+        [axis_overlap(first.x, first.right, second.x, second.right),
+         axis_overlap(first.y, first.bottom, second.y, second.bottom)]
+      end
+
+      def axis_overlap(low_a, high_a, low_b, high_b)
+        overlap = [high_a, high_b].min - [low_a, low_b].max
+        if low_a <= low_b && high_a >= high_b
+          overlap + [low_b - low_a, high_a - high_b].min
+        elsif low_b <= low_a && high_b >= high_a
+          overlap + [low_a - low_b, high_b - high_a].min
+        else
+          overlap
+        end
+      end
+    end
+  end
+end

data/lib/etassia/layout/mindmap_cose_grid.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+require_relative "mindmap_cose_geometry"
+
+module Etassia
+  module Layout
+    # Spatial index that limits which pairs of mindmap boxes repel each
+    # other: only boxes in neighbouring cells within the repulsion range.
+    class MindmapCoseGrid
+      MARGIN = 15.0
+
+      def initialize(bodies, range)
+        @bodies = bodies
+        @range = range
+        @cells = []
+      end
+
+      # Rebuilds the cells from the current box positions.
+      def refresh
+        left, top, right, bottom = bounds
+        @cells = Array.new(((right - left) / @range).ceil) do
+          Array.new(((bottom - top) / @range).ceil) { [] }
+        end
+        @bodies.each { |body| add(body, left, top) }
+      end
+
+      # Recomputes which not yet processed boxes lie within range of +body+.
+      def refresh_surrounding(body, processed)
+        found = {}
+        candidates(body).each do |other|
+          next if processed.key?(other) || found.key?(other)
+
+          found[other] = true if within_range?(body, other)
+        end
+        body.surrounding = found.keys
+      end
+
+      private
+
+      def bounds
+        left, top, right, bottom = MindmapCoseGeometry.bounding_box(@bodies)
+        width = right - left
+        height = bottom - top
+        [left - MARGIN, top - MARGIN, left + width + MARGIN,
+         top + height + MARGIN]
+      end
+
+      def add(body, left, top)
+        first_x, last_x = span(body.x, body.width, left)
+        first_y, last_y = span(body.y, body.height, top)
+        (first_x..last_x).each do |column|
+          (first_y..last_y).each { |row| @cells[column][row] << body }
+        end
+        body.cells = [first_x, last_x, first_y, last_y]
+      end
+
+      # @return [Array<Integer>] first and last cell index along one axis
+      def span(start, size, origin)
+        [((start - origin) / @range).floor,
+         ((size + start - origin) / @range).floor]
+      end
+
+      def candidates(body)
+        first_x, last_x, first_y, last_y = body.cells
+        found = []
+        ((first_x - 1)..(last_x + 1)).each do |column|
+          ((first_y - 1)..(last_y + 1)).each do |row|
+            found.concat(cell_members(column, row, body))
+          end
+        end
+        found
+      end
+
+      def cell_members(column, row, body)
+        return [] unless cell?(column, row)
+
+        @cells[column][row].reject { |other| other.equal?(body) }
+      end
+
+      def cell?(column, row)
+        column >= 0 && row >= 0 && column < @cells.length &&
+          row < @cells.first.length
+      end
+
+      def within_range?(body, other)
+        gap_x = gap(body.center_x, other.center_x, body.width, other.width)
+        gap_y = gap(body.center_y, other.center_y, body.height, other.height)
+        gap_x <= @range && gap_y <= @range
+      end
+
+      def gap(centre, other_centre, size, other_size)
+        (centre - other_centre).abs - ((size / 2) + (other_size / 2))
+      end
+    end
+  end
+end

data/lib/etassia/layout/mindmap_cose_link.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require_relative "mindmap_cose_geometry"
+
+module Etassia
+  module Layout
+    # An edge between two bodies, measured between the box borders.
+    class MindmapCoseLink
+      attr_reader :source, :target, :length_x, :length_y, :length
+
+      def initialize(source, target)
+        @source = source
+        @target = target
+      end
+
+      def other_end(body)
+        body.equal?(source) ? target : source
+      end
+
+      # @return [Float, nil] the new length, or nil when the two boxes
+      #   overlap, which leaves the edge without a spring force.
+      def measure
+        clip = MindmapCoseGeometry.clip_points(target, source)
+        return unless clip
+
+        @length_x = unit_floor(clip[0] - clip[2])
+        @length_y = unit_floor(clip[1] - clip[3])
+        @length = hypotenuse
+      end
+
+      private
+
+      def hypotenuse
+        Math.sqrt((length_x * length_x) + (length_y * length_y))
+      end
+
+      def unit_floor(value)
+        value.abs < 1.0 ? (value <=> 0).to_f : value
+      end
+    end
+  end
+end

data/lib/etassia/layout/mindmap_cose_relaxation.rb

@@ -0,0 +1,166 @@
+# frozen_string_literal: true
+
+require_relative "mindmap_cose_geometry"
+require_relative "mindmap_cose_grid"
+require_relative "../js_math"
+
+module Etassia
+  module Layout
+    # The spring-embedder loop of the mindmap force layout: edges pull their
+    # boxes to an ideal length, nearby boxes push apart, and a cooling
+    # schedule damps every move until the layout settles.
+    class MindmapCoseRelaxation
+      IDEAL_LENGTH = 50.0
+      SPRING_STRENGTH = 0.45
+      REPULSION_STRENGTH = 4500.0
+      MIN_ITERATIONS = 2500
+      CHECK_PERIOD = 100
+      GRID_PERIOD = 10
+      MAX_DISPLACEMENT = 300.0
+      DISPLACEMENT_PER_BODY = 1.5
+      MIN_REPULSION_DISTANCE = IDEAL_LENGTH / 10.0
+      SEPARATION_BUFFER = IDEAL_LENGTH / 2.0
+      REPULSION_RANGE = 2 * IDEAL_LENGTH
+      FINAL_COOLING = CHECK_PERIOD.fdiv(MIN_ITERATIONS)
+      COOLING_CYCLES = MIN_ITERATIONS / CHECK_PERIOD.to_f
+
+      def initialize(bodies, links)
+        @bodies = bodies
+        @links = links
+        @max_iterations = [bodies.length * 5, MIN_ITERATIONS].max
+        @threshold = DISPLACEMENT_PER_BODY * bodies.length
+        @grid = MindmapCoseGrid.new(bodies, REPULSION_RANGE)
+        @cooling = 1.0
+        @iterations = 0
+        @cycle = 0
+        @displacement = 0.0
+        @previous_displacement = 0.0
+      end
+
+      def run
+        loop do
+          @iterations += 1
+          break if @iterations == @max_iterations
+
+          if cooling_check_due?
+            break if converged?
+
+            cool
+          end
+          step
+        end
+      end
+
+      private
+
+      attr_reader :bodies, :links
+
+      def cooling_check_due?
+        (@iterations % CHECK_PERIOD).zero?
+      end
+
+      def step
+        @displacement = 0.0
+        spring_forces
+        repulsion_forces
+        bodies.each do |body|
+          @displacement += body.move(@cooling, MAX_DISPLACEMENT)
+        end
+      end
+
+      def cool
+        @cycle += 1
+        decay = JsMath.pow(@cycle, JsMath.log(100 * (1.0 - FINAL_COOLING)) /
+                               JsMath.log(COOLING_CYCLES)) / 100
+        @cooling = [1.0 - decay, FINAL_COOLING].max
+      end
+
+      def converged?
+        oscillating = oscillating?
+        converged = @displacement < @threshold
+        @previous_displacement = @displacement
+        converged || oscillating
+      end
+
+      def oscillating?
+        return false unless @iterations > @max_iterations / 3.0
+
+        (@displacement - @previous_displacement).abs < 2
+      end
+
+      def spring_forces
+        links.each do |link|
+          length = link.measure
+          next if length.nil? || length.zero?
+
+          pull = SPRING_STRENGTH * (length - IDEAL_LENGTH)
+          apply_spring(link, pull * (link.length_x / length),
+                       pull * (link.length_y / length))
+        end
+      end
+
+      def apply_spring(link, force_x, force_y)
+        link.source.spring_x += force_x
+        link.source.spring_y += force_y
+        link.target.spring_x -= force_x
+        link.target.spring_y -= force_y
+      end
+
+      def repulsion_forces
+        refresh = (@iterations % GRID_PERIOD) == 1
+        @grid.refresh if refresh
+        done = {}
+        bodies.each do |body|
+          @grid.refresh_surrounding(body, done) if refresh
+          body.surrounding.each { |other| repel(body, other) }
+          done[body] = true
+        end
+      end
+
+      def repel(first, second)
+        if MindmapCoseGeometry.intersects?(first, second)
+          push_apart(first, second)
+        else
+          push_away(first, second)
+        end
+      end
+
+      def push_apart(first, second)
+        x, y = MindmapCoseGeometry.separation(first, second, SEPARATION_BUFFER)
+        share = 1.0 / 2
+        apply_repulsion(first, second, share * (2 * x), share * (2 * y))
+      end
+
+      def push_away(first, second)
+        apply_repulsion(first, second, *inverse_square_force(first, second))
+      end
+
+      # @return [Array<Float>] the force on the second box, along x and y
+      def inverse_square_force(first, second)
+        gap_x, gap_y = border_gaps(first, second)
+        squared = (gap_x * gap_x) + (gap_y * gap_y)
+        distance = Math.sqrt(squared)
+        force = REPULSION_STRENGTH / squared
+        [force * gap_x / distance, force * gap_y / distance]
+      end
+
+      def border_gaps(first, second)
+        clip = MindmapCoseGeometry.clip_points(first, second)
+        [minimum_gap(clip[2] - clip[0]), minimum_gap(clip[3] - clip[1])]
+      end
+
+      def apply_repulsion(first, second, force_x, force_y)
+        first.repulsion_x -= force_x
+        first.repulsion_y -= force_y
+        second.repulsion_x += force_x
+        second.repulsion_y += force_y
+      end
+
+      def minimum_gap(gap)
+        return gap unless gap.abs < MIN_REPULSION_DISTANCE
+
+        (gap <=> 0) * MIN_REPULSION_DISTANCE
+      end
+    end
+  end
+end

data/lib/etassia/layout/mindmap_cose_seed.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+require_relative "mindmap_cose_geometry"
+require_relative "../js_math"
+require_relative "mindmap_cose_wedge"
+
+module Etassia
+  module Layout
+    # Initial placement for a tree: the centre of the tree goes in the
+    # middle and every branch gets an angular wedge, one ring per level.
+    class MindmapCoseSeed
+      RING_GAP = 50.0
+      ANGLE_SPAN = 359.0
+
+      def initialize(bodies)
+        @bodies = bodies
+      end
+
+      # Positions every body with the top left of the tree at the origin.
+      #
+      # @return [Array<Float>] width and height of the placed tree
+      def place
+        tree = breadth_first_order
+        centre = tree_centre(tree)
+        @ring = [tree.map(&:diagonal).max, RING_GAP].max
+        branch(centre, nil, MindmapCoseWedge.new(0.0, ANGLE_SPAN), 0.0)
+        move_to_origin
+      end
+
+      private
+
+      attr_reader :bodies
+
+      def breadth_first_order
+        order = [bodies.first]
+        order.each do |body|
+          body.neighbors.each do |other|
+            order << other unless order.include?(other)
+          end
+        end
+        order
+      end
+
+      # cose-base names the centre by peeling leaves layer by layer, but its
+      # loop walks the whole node list instead of the leaves and drops every
+      # other node on each pass. The survivor depends only on that order, so
+      # the degree bookkeeping is left out.
+      def tree_centre(tree)
+        remaining = tree
+        while remaining.length > 2
+          remaining = remaining.select.with_index { |_, index| index.odd? }
+        end
+        remaining.first
+      end
+
+      def move_to_origin
+        left, top, right, bottom = MindmapCoseGeometry.bounding_box(bodies)
+        bodies.each do |body|
+          body.x -= left
+          body.y -= top
+        end
+        [right - left, bottom - top]
+      end
+
+      def branch(body, parent, wedge, distance)
+        radians = (wedge.bearing * (2.0 * Math::PI)) / 360
+        body.center = [distance * JsMath.cos(radians),
+                       distance * JsMath.sin(radians)]
+        place_children(body, parent, wedge, distance + @ring)
+      end
+
+      def place_children(body, parent, wedge, distance)
+        children = children_in_order(body, parent)
+        children.each_with_index do |child, index|
+          branch(child, body, wedge.slice(index, children.length), distance)
+        end
+      end
+
+      # The children start after the parent's link and wrap around.
+      def children_in_order(body, parent)
+        links = parent ? parent_first(body.links, body, parent) : body.links
+        others = links.map { |link| link.other_end(body) }
+        others.reject { |other| other.equal?(parent) }
+      end
+
+      # Rotates the parent's link to the front, so the others keep their
+      # order after it.
+      def parent_first(links, body, parent)
+        links.rotate(links.index { |link| link.other_end(body).equal?(parent) })
+      end
+    end
+  end
+end

data/lib/etassia/layout/mindmap_cose_wedge.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Etassia
+  module Layout
+    # The angular slice of the circle a branch of the tree is laid out in,
+    # in degrees.
+    class MindmapCoseWedge
+      attr_reader :start_angle, :end_angle
+
+      def initialize(start_angle, end_angle)
+        @start_angle = start_angle
+        @end_angle = end_angle
+      end
+
+      # @return [Float] the direction the branch's own node sits in
+      def bearing
+        (midpoint + start_angle).remainder(360)
+      end
+
+      # @param index [Integer] which child, counting from zero
+      # @param count [Integer] how many children share this wedge
+      # @return [MindmapCoseWedge] the child's share of this wedge
+      def slice(index, count)
+        step = (end_angle - start_angle).abs / count.to_f
+        first = (start_angle + (index * step)).remainder(360)
+        self.class.new(first, (first + step).remainder(360))
+      end
+
+      private
+
+      def midpoint
+        half = ((end_angle - start_angle) + 1) / 2.0
+        half.negative? ? half + 180 : half
+      end
+    end
+  end
+end