lithop 0.1.0

data/lib/lithop/mesh/column_topology.rb

@@ -0,0 +1,262 @@
+# frozen_string_literal: true
+
+module Lithop
+  # Finds columns that must become separate shells to remove four-face edge contacts.
+  # rubocop:disable-next Metrics/ClassLength
+  class ColumnIsolation
+    def initialize(model:, intervals:)
+      @model = model
+      @intervals = intervals
+    end
+
+    def groups
+      isolated = {}
+      each_edge_contact do |endpoints, owners|
+        next unless endpoints.all? { |endpoint| merged_at?(endpoint, owners) }
+
+        _layer, row, column = owners.max
+        isolated[[row, column]] = true
+      end
+      isolated.each_key.with_index(1).to_h.freeze
+    end
+
+    private
+
+    def each_edge_contact(&)
+      each_x_edge_contact(&)
+      each_row_edge_contact(&)
+      each_z_edge_contact(&)
+    end
+
+    def each_x_edge_contact
+      @model.columns.times do |column|
+        (1...@model.rows).each do |row_boundary|
+          upper = interval_at(row_boundary - 1, column)
+          lower = interval_at(row_boundary, column)
+          contact = touching_layers(upper, lower)
+          next unless contact
+
+          z_index, upper_layer, lower_layer = contact
+          owners = [[upper_layer, row_boundary - 1, column], [lower_layer, row_boundary, column]]
+          yield [[column, row_boundary, z_index], [column + 1, row_boundary, z_index]], owners
+        end
+      end
+    end
+
+    def each_row_edge_contact
+      @model.rows.times do |row|
+        (1...@model.columns).each do |x_index|
+          left = interval_at(row, x_index - 1)
+          right = interval_at(row, x_index)
+          contact = touching_layers(left, right)
+          next unless contact
+
+          z_index, left_layer, right_layer = contact
+          owners = [[left_layer, row, x_index - 1], [right_layer, row, x_index]]
+          yield [[x_index, row, z_index], [x_index, row + 1, z_index]], owners
+        end
+      end
+    end
+
+    def each_z_edge_contact
+      (1...@model.rows).each do |row_boundary|
+        (1...@model.columns).each do |x_index|
+          columns = [
+            [row_boundary - 1, x_index - 1], [row_boundary - 1, x_index],
+            [row_boundary, x_index - 1], [row_boundary, x_index]
+          ]
+          intervals = columns.map { |row, column| interval_at(row, column) }
+          [[0, 3, 1, 2], [1, 2, 0, 3]].each do |first, second, lower_bridge, upper_bridge|
+            layer = vertical_contact(
+              intervals[first], intervals[second], intervals[lower_bridge], intervals[upper_bridge]
+            )
+            next unless layer
+
+            owners = [first, second].map do |index|
+              row, column = columns[index]
+              [layer, row, column]
+            end
+            yield [[x_index, row_boundary, layer], [x_index, row_boundary, layer + 1]], owners
+          end
+        end
+      end
+    end
+
+    def vertical_contact(first, second, lower_bridge, upper_bridge)
+      return unless first && second && lower_bridge && upper_bridge
+
+      layer = if lower_bridge.last + 1 == upper_bridge.first
+                lower_bridge.last
+              elsif upper_bridge.last + 1 == lower_bridge.first
+                upper_bridge.last
+              end
+      return unless layer
+      return unless [first, second].all? { |interval| interval.first <= layer - 1 && interval.last >= layer + 2 }
+
+      layer
+    end
+
+    def merged_at?(endpoint, owners)
+      x_index, row_boundary, z_index = endpoint
+      incident = [z_index - 1, z_index].product(
+        [row_boundary - 1, row_boundary],
+        [x_index - 1, x_index]
+      ).select { |owner| occupied?(*owner) }
+      connected?(owners.first, owners.last, incident)
+    end
+
+    def connected?(start, target, incident)
+      visited = {}
+      pending = [start]
+      until pending.empty?
+        current = pending.pop
+        next if visited[current]
+        return true if current == target
+
+        visited[current] = true
+        pending.concat(incident.reject do |candidate|
+          visited[candidate] || !face_neighbours?(current, candidate)
+        end)
+      end
+      false
+    end
+
+    def face_neighbours?(left, right)
+      left.zip(right).sum { |a, b| (a - b).abs } == 1
+    end
+
+    def touching_layers(first, second)
+      return unless first && second
+      return [first.last, first.last - 1, second.first] if first.last == second.first
+
+      [second.last, first.first, second.last - 1] if second.last == first.first
+    end
+
+    def interval_at(row, column)
+      return if row.negative? || column.negative? || row >= @model.rows || column >= @model.columns
+
+      @intervals.fetch((row * @model.columns) + column)
+    end
+
+    def occupied?(layer, row, column)
+      return false if layer.negative? || row.negative? || column.negative?
+      return false if row >= @model.rows || column >= @model.columns
+
+      interval = @intervals.fetch((row * @model.columns) + column)
+      interval && layer >= interval.first && layer < interval.last
+    end
+  end
+
+  # Assigns stable vertex identities after exceptional columns are isolated.
+  class ColumnTopology
+    Vertex = VoxelTopology::Vertex
+    COMPONENT_ROOTS = Array.new(256) do |mask|
+      roots = Array.new(8)
+      8.times do |start|
+        next if mask.nobits?(1 << start) || roots[start]
+
+        component = []
+        pending = [start]
+        until pending.empty?
+          current = pending.pop
+          next if component.include?(current)
+
+          component << current
+          8.times do |candidate|
+            next if mask.nobits?(1 << candidate) || component.include?(candidate)
+
+            pending << candidate if (current ^ candidate).then { |difference| [1, 2, 4].include?(difference) }
+          end
+        end
+        root = component.min
+        component.each { |member| roots[member] = root }
+      end
+      roots.freeze
+    end.freeze
+
+    def initialize(model:, intervals:)
+      @model = model
+      @intervals = intervals
+      isolated = ColumnIsolation.new(model:, intervals:).groups
+      @group_ids = Array.new(model.rows * model.columns, 0)
+      isolated.each { |(row, column), group| @group_ids[(row * model.columns) + column] = group }
+      @group_count = isolated.length + 1
+      @z_count = model.z_boundaries.length
+      @mask_cache = {}
+      @vertex_cache = {}
+    end
+
+    def same_group?(left_row, left_column, right_row, right_column)
+      group_at(left_row, left_column) == group_at(right_row, right_column)
+    end
+
+    def vertex(x_index, row_boundary, z_index, owner)
+      _layer, row, column = owner
+      group = group_at(row, column)
+      topology = topology_key(x_index, row_boundary, z_index, owner, group)
+      @vertex_cache[topology] ||= Vertex.new(
+        x: @model.x_boundaries.fetch(x_index),
+        y: @model.y_boundaries.last - @model.y_boundaries.fetch(row_boundary),
+        z: @model.z_boundaries.fetch(z_index),
+        topology:
+      )
+    end
+
+    def release_cache!
+      @mask_cache.clear
+      @vertex_cache.clear
+    end
+
+    private
+
+    def topology_key(x_index, row_boundary, z_index, owner, group)
+      coordinate_key = (((x_index * (@model.rows + 1)) + row_boundary) * @z_count) + z_index
+      cache_key = (coordinate_key * @group_count) + group
+      mask = @mask_cache[cache_key] ||= occupancy_mask(x_index, row_boundary, z_index, group)
+      owner_bit = owner_bit(owner, x_index, row_boundary, z_index)
+      component = COMPONENT_ROOTS.fetch(mask).fetch(owner_bit)
+      (cache_key * 8) + component
+    end
+
+    def occupancy_mask(x_index, row_boundary, z_index, group)
+      mask = 0
+      2.times do |layer_offset|
+        2.times do |row_offset|
+          2.times do |column_offset|
+            bit = (layer_offset * 4) + (row_offset * 2) + column_offset
+            occupied = occupied?(
+              z_index - 1 + layer_offset,
+              row_boundary - 1 + row_offset,
+              x_index - 1 + column_offset,
+              group
+            )
+            mask |= (1 << bit) if occupied
+          end
+        end
+      end
+      mask
+    end
+
+    def owner_bit(owner, x_index, row_boundary, z_index)
+      layer, row, column = owner
+      ((layer - z_index + 1) * 4) + ((row - row_boundary + 1) * 2) + (column - x_index + 1)
+    end
+
+    def occupied?(layer, row, column, group)
+      interval = interval_at(row, column)
+      interval && layer >= interval.first && layer < interval.last && group_at(row, column) == group
+    end
+
+    def group_at(row, column)
+      return 0 if row.negative? || column.negative? || row >= @model.rows || column >= @model.columns
+
+      @group_ids.fetch((row * @model.columns) + column)
+    end
+
+    def interval_at(row, column)
+      return if row.negative? || column.negative? || row >= @model.rows || column >= @model.columns
+
+      @intervals.fetch((row * @model.columns) + column)
+    end
+  end
+end

data/lib/lithop/mesh/geometry.rb

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+module Lithop
+  # Generates the closed triangle mesh for a monochrome height field.
+  class Geometry
+    def initialize(heights:, columns:, rows:, x_boundaries:, y_boundaries:, optimize_bottom: false)
+      @heights = heights
+      @columns = columns
+      @rows = rows
+      @x = x_boundaries
+      @y = y_boundaries
+      @optimize_bottom = optimize_bottom
+      expected = (columns + 1) * (rows + 1)
+      raise InputError, "expected #{expected} vertex heights, got #{heights.length}" unless heights.length == expected
+    end
+
+    def each_triangle(&block)
+      return enum_for(__method__) unless block
+
+      @rows.times do |row|
+        @columns.times { |column| emit_cell(row, column, &block) }
+      end
+      emit_perimeter(&block)
+      emit_bottom_fan(&block) if @optimize_bottom
+    end
+
+    private
+
+    def emit_cell(row, column, &)
+      x0 = @x.fetch(column)
+      x1 = @x.fetch(column + 1)
+      y0 = @y.last - @y.fetch(row + 1)
+      y1 = @y.last - @y.fetch(row)
+      top_left = [x0, y1, height(row, column)]
+      top_right = [x1, y1, height(row, column + 1)]
+      bottom_right = [x1, y0, height(row + 1, column + 1)]
+      bottom_left = [x0, y0, height(row + 1, column)]
+
+      yield [top_left, bottom_left, bottom_right]
+      yield [top_left, bottom_right, top_right]
+      return if @optimize_bottom
+
+      quad([x0, y1, 0.0], [x1, y1, 0.0], [x1, y0, 0.0], [x0, y0, 0.0], &)
+    end
+
+    def emit_perimeter(&)
+      @rows.times do |row|
+        emit_left_side(row, &)
+        emit_right_side(row, &)
+      end
+      @columns.times do |column|
+        emit_bottom_side(column, &)
+        emit_top_side(column, &)
+      end
+    end
+
+    def emit_left_side(row, &)
+      y0 = @y.last - @y.fetch(row + 1)
+      y1 = @y.last - @y.fetch(row)
+      quad(
+        [0.0, y0, 0.0], [0.0, y0, height(row + 1, 0)],
+        [0.0, y1, height(row, 0)], [0.0, y1, 0.0], &
+      )
+    end
+
+    def emit_right_side(row, &)
+      x = @x.last
+      y0 = @y.last - @y.fetch(row + 1)
+      y1 = @y.last - @y.fetch(row)
+      quad(
+        [x, y0, 0.0], [x, y1, 0.0],
+        [x, y1, height(row, @columns)], [x, y0, height(row + 1, @columns)], &
+      )
+    end
+
+    def emit_bottom_side(column, &)
+      x0 = @x.fetch(column)
+      x1 = @x.fetch(column + 1)
+      quad(
+        [x0, 0.0, 0.0], [x1, 0.0, 0.0],
+        [x1, 0.0, height(@rows, column + 1)], [x0, 0.0, height(@rows, column)], &
+      )
+    end
+
+    def emit_top_side(column, &)
+      x0 = @x.fetch(column)
+      x1 = @x.fetch(column + 1)
+      y = @y.last
+      quad(
+        [x0, y, 0.0], [x0, y, height(0, column)],
+        [x1, y, height(0, column + 1)], [x1, y, 0.0], &
+      )
+    end
+
+    def emit_bottom_fan
+      center = [@x.last.fdiv(2), @y.last.fdiv(2), 0.0]
+      rendered_y = @y.reverse.map { |y| @y.last - y }
+      perimeter = rendered_y.map { |y| [0.0, y, 0.0] }
+      @x.drop(1).each { |x| perimeter << [x, @y.last, 0.0] }
+      rendered_y.reverse.drop(1).each { |y| perimeter << [@x.last, y, 0.0] }
+      @x.reverse.drop(1).first(@x.length - 2).each { |x| perimeter << [x, 0.0, 0.0] }
+      perimeter.each_with_index do |from, index|
+        yield [center, from, perimeter.fetch((index + 1) % perimeter.length)]
+      end
+    end
+
+    def height(row, column)
+      @heights.fetch((row * (@columns + 1)) + column)
+    end
+
+    def quad(a, b, c, d)
+      yield [a, b, c]
+      yield [a, c, d]
+    end
+  end
+end

data/lib/lithop/mesh/validator.rb

@@ -0,0 +1,123 @@
+# frozen_string_literal: true
+
+module Lithop
+  # Validates that triangle meshes are closed and consistently oriented.
+  module MeshValidator
+    module_function
+
+    def validate!(triangles)
+      report!(triangles)
+      true
+    end
+
+    Report = Data.define(:triangle_count, :edge_count, :component_volumes, :volume)
+    Topology = Data.define(:edges, :triangle_volumes, :triangle_count)
+
+    # Vertex-only contacts remain separate components with positive volumes.
+    def report!(triangles)
+      topology = collect_topology(triangles)
+      validate_edges!(topology.edges)
+      component_volumes = component_volumes(
+        topology.triangle_count,
+        neighbours_for(topology.edges),
+        topology.triangle_volumes
+      )
+      raise InputError, "mesh is not outward-facing" if component_volumes.any? { |volume| volume <= 0.0 }
+
+      Report.new(
+        triangle_count: topology.triangle_count,
+        edge_count: topology.edges.length,
+        component_volumes: component_volumes.freeze,
+        volume: component_volumes.sum
+      )
+    end
+
+    def collect_topology(triangles)
+      edges = Hash.new { |hash, key| hash[key] = [] }
+      triangle_volumes = []
+      triangle_count = 0
+
+      triangles.each do |triangle|
+        validate_triangle!(triangle)
+        triangle_index = triangle_count
+        triangle_count += 1
+        triangle_volumes << signed_volume(triangle)
+        triangle.each_with_index do |from, index|
+          to = triangle[(index + 1) % 3]
+          key = { from => true, to => true }.freeze
+          edges[key] << [triangle_index, from, to]
+        end
+      end
+
+      raise InputError, "mesh contains no triangles" if triangle_count.zero?
+
+      Topology.new(edges:, triangle_volumes:, triangle_count:)
+    end
+
+    def validate_triangle!(triangle)
+      raise InputError, "triangle must contain three vertices" unless triangle.length == 3
+      raise InputError, "mesh contains a zero-area triangle" if zero_area?(triangle)
+    end
+
+    def validate_edges!(edges)
+      invalid = edges.find do |_key, faces|
+        faces.length != 2 || faces[0].drop(1) != faces[1].drop(1).reverse
+      end
+      raise InputError, "mesh is not a closed, consistently oriented surface" if invalid
+    end
+
+    def neighbours_for(edges)
+      edges.each_with_object(Hash.new { |hash, key| hash[key] = [] }) do |(_key, faces), neighbours|
+        left, right = faces.map(&:first)
+        neighbours[left] << right
+        neighbours[right] << left
+      end
+    end
+
+    def zero_area?(triangle)
+      a, b, c = triangle.map { |vertex| coordinates(vertex) }
+      ab = b.zip(a).map { |left, right| left - right }
+      ac = c.zip(a).map { |left, right| left - right }
+      cross = [
+        (ab[1] * ac[2]) - (ab[2] * ac[1]),
+        (ab[2] * ac[0]) - (ab[0] * ac[2]),
+        (ab[0] * ac[1]) - (ab[1] * ac[0])
+      ]
+      cross.all?(&:zero?)
+    end
+
+    def coordinates(vertex)
+      vertex.respond_to?(:coordinates) ? vertex.coordinates : vertex
+    end
+
+    def signed_volume(triangle)
+      a, b, c = triangle.map { |vertex| coordinates(vertex) }
+      (
+        (a[0] * ((b[1] * c[2]) - (b[2] * c[1]))) -
+        (a[1] * ((b[0] * c[2]) - (b[2] * c[0]))) +
+        (a[2] * ((b[0] * c[1]) - (b[1] * c[0])))
+      ) / 6.0
+    end
+
+    def component_volumes(triangle_count, neighbours, triangle_volumes)
+      visited = Array.new(triangle_count, false)
+      triangle_count.times.filter_map do |start|
+        next if visited[start]
+
+        pending = [start]
+        volume = 0.0
+        until pending.empty?
+          index = pending.pop
+          next if visited[index]
+
+          visited[index] = true
+          volume += triangle_volumes.fetch(index)
+          pending.concat(neighbours.fetch(index, []).reject { |candidate| visited[candidate] })
+        end
+        volume
+      end
+    end
+    private_class_method :coordinates, :zero_area?, :signed_volume, :component_volumes, :collect_topology,
+                         :validate_triangle!, :validate_edges!, :neighbours_for
+  end
+end

data/lib/lithop/mesh/voxel_geometry.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+module Lithop
+  # Generates the exposed triangles for one material in a voxel model.
+  class VoxelGeometry
+    Vertex = VoxelTopology::Vertex
+
+    def initialize(model:, material:)
+      raise InputError, "unknown material: #{material.inspect}" unless Palette::MATERIALS.include?(material)
+
+      @model = model
+      @material = material
+      @topology = VoxelTopology.new(model:, material:)
+    end
+
+    def each_triangle(&)
+      return enum_for(__method__) unless block_given?
+
+      (@model.z_boundaries.length - 1).times do |layer|
+        @model.rows.times do |row|
+          @model.columns.times do |column|
+            emit_voxel(layer, row, column, &) if occupied?(layer, row, column)
+          end
+        end
+      end
+    end
+
+    def triangle_count
+      count = 0
+      each_occupied_voxel do |layer, row, column|
+        count += 2 unless occupied?(layer - 1, row, column)
+        count += 2 unless occupied?(layer + 1, row, column)
+        count += 2 unless occupied?(layer, row, column - 1)
+        count += 2 unless occupied?(layer, row, column + 1)
+        count += 2 unless occupied?(layer, row + 1, column)
+        count += 2 unless occupied?(layer, row - 1, column)
+      end
+      count
+    end
+
+    private
+
+    def each_occupied_voxel
+      (@model.z_boundaries.length - 1).times do |layer|
+        @model.rows.times do |row|
+          @model.columns.times do |column|
+            yield layer, row, column if occupied?(layer, row, column)
+          end
+        end
+      end
+    end
+
+    def emit_voxel(layer, row, column, &)
+      owner = [layer, row, column]
+      x0 = column
+      x1 = column + 1
+      y0 = row + 1
+      y1 = row
+      z0 = layer
+      z1 = layer + 1
+
+      emit_bottom(x0, x1, y0, y1, z0, owner, &) unless occupied?(layer - 1, row, column)
+      emit_top(x0, x1, y0, y1, z1, owner, &) unless occupied?(layer + 1, row, column)
+      emit_left(x0, y0, y1, z0, z1, owner, &) unless occupied?(layer, row, column - 1)
+      emit_right(x1, y0, y1, z0, z1, owner, &) unless occupied?(layer, row, column + 1)
+      emit_front(x0, x1, y0, z0, z1, owner, &) unless occupied?(layer, row + 1, column)
+      emit_back(x0, x1, y1, z0, z1, owner, &) unless occupied?(layer, row - 1, column)
+    end
+
+    def occupied?(layer, row, column)
+      @model.material_at(layer, row, column) == @material
+    end
+
+    def emit_bottom(x0, x1, y0, y1, z, owner, &)
+      quad(vertex(x0, y0, z, owner), vertex(x0, y1, z, owner),
+           vertex(x1, y1, z, owner), vertex(x1, y0, z, owner), &)
+    end
+
+    def emit_top(x0, x1, y0, y1, z, owner, &)
+      quad(vertex(x0, y0, z, owner), vertex(x1, y0, z, owner),
+           vertex(x1, y1, z, owner), vertex(x0, y1, z, owner), &)
+    end
+
+    def emit_left(x, y0, y1, z0, z1, owner, &)
+      quad(vertex(x, y0, z0, owner), vertex(x, y0, z1, owner),
+           vertex(x, y1, z1, owner), vertex(x, y1, z0, owner), &)
+    end
+
+    def emit_right(x, y0, y1, z0, z1, owner, &)
+      quad(vertex(x, y0, z0, owner), vertex(x, y1, z0, owner),
+           vertex(x, y1, z1, owner), vertex(x, y0, z1, owner), &)
+    end
+
+    def emit_front(x0, x1, y, z0, z1, owner, &)
+      quad(vertex(x0, y, z0, owner), vertex(x1, y, z0, owner),
+           vertex(x1, y, z1, owner), vertex(x0, y, z1, owner), &)
+    end
+
+    def emit_back(x0, x1, y, z0, z1, owner, &)
+      quad(vertex(x0, y, z0, owner), vertex(x0, y, z1, owner),
+           vertex(x1, y, z1, owner), vertex(x1, y, z0, owner), &)
+    end
+
+    def vertex(x_index, row_boundary, z_index, owner)
+      @topology.vertex(x_index, row_boundary, z_index, owner)
+    end
+
+    def quad(a, b, c, d)
+      yield [a, b, c]
+      yield [a, c, d]
+    end
+  end
+end

data/lib/lithop/mesh/voxel_topology.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+module Lithop
+  # Assigns stable topological identities to multipart voxel vertices.
+  class VoxelTopology
+    Vertex = Data.define(:x, :y, :z, :topology) do
+      def coordinates
+        [x, y, z]
+      end
+
+      def hash = topology.hash
+
+      def eql?(other) = other.is_a?(self.class) && topology.eql?(other.topology)
+
+      alias_method :==, :eql?
+    end
+
+    def initialize(model:, material:)
+      @model = model
+      @material = material
+      @component_cache = {}
+    end
+
+    def vertex(x_index, row_boundary, z_index, owner)
+      Vertex.new(
+        x: @model.x_boundaries.fetch(x_index),
+        y: @model.y_boundaries.last - @model.y_boundaries.fetch(row_boundary),
+        z: @model.z_boundaries.fetch(z_index),
+        topology: topology_key(x_index, row_boundary, z_index, owner)
+      )
+    end
+
+    private
+
+    def topology_key(x_index, row_boundary, z_index, owner)
+      cache_key = [x_index, row_boundary, z_index]
+      components = @component_cache[cache_key] ||= components_at(x_index, row_boundary, z_index)
+      [x_index, row_boundary, z_index, components.fetch(owner)]
+    end
+
+    def components_at(x_index, row_boundary, z_index)
+      incident = incident_voxels(x_index, row_boundary, z_index)
+      components = {}
+      incident.each do |owner|
+        next if components.key?(owner)
+
+        component = []
+        pending = [owner]
+        until pending.empty?
+          current = pending.pop
+          next if component.include?(current)
+
+          component << current
+          pending.concat(incident.reject do |candidate|
+            component.include?(candidate) || !face_neighbours?(current, candidate)
+          end)
+        end
+        root = component.min
+        component.each { |member| components[member] = root }
+      end
+      components.freeze
+    end
+
+    def incident_voxels(x_index, row_boundary, z_index)
+      [z_index - 1, z_index].product(
+        [row_boundary - 1, row_boundary],
+        [x_index - 1, x_index]
+      ).select { |layer, row, column| occupied?(layer, row, column) }
+    end
+
+    def face_neighbours?(left, right)
+      left.zip(right).sum { |a, b| (a - b).abs } == 1
+    end
+
+    def occupied?(layer, row, column)
+      @model.material_at(layer, row, column) == @material
+    end
+  end
+end