lithop 0.1.0

data/lib/lithop/image/svg_loader.rb

@@ -0,0 +1,218 @@
+# frozen_string_literal: true
+
+require "rexml/document"
+require "rexml/xpath"
+
+module Lithop
+  # Applies the self-contained, static subset accepted for SVG input.
+  class SVGDocumentValidator
+    FORBIDDEN_ELEMENTS = %w[script foreignobject animate animatemotion animatetransform set].freeze
+    LENGTH = /\A\+?(?:\d+(?:\.\d*)?|\.\d+)(?:[eE][+-]?\d+)?(?:px|mm|in)?\z/i
+    NUMBER = /[+-]?(?:\d+(?:\.\d*)?|\.\d+)(?:[eE][+-]?\d+)?/
+    URL_REFERENCE = /url\s*\(\s*(?:(['"])(.*?)\1|([^)]*))\s*\)/im
+
+    def call(data)
+      validate_declarations!(data)
+      document = parse(data)
+      validate_document!(document)
+    rescue REXML::ParseException => e
+      raise InputError, "invalid SVG XML: #{e.message.lines.first.to_s.strip}"
+    end
+
+    private
+
+    def parse(data)
+      utf8 = data.dup.force_encoding(Encoding::UTF_8)
+      raise InputError, "SVG input must use UTF-8 XML" unless utf8.valid_encoding?
+
+      document = REXML::Document.new(utf8)
+      root = document.root
+      raise InputError, "input must be a JPEG, PNG, or SVG image" unless root&.name&.casecmp?("svg")
+
+      encoding = document.xml_decl&.encoding
+      raise InputError, "SVG input must use UTF-8 XML" if encoding && !encoding.casecmp?("UTF-8")
+
+      document
+    end
+
+    def validate_declarations!(data)
+      return unless data.match?(/<!DOCTYPE\b|<!ENTITY\b|<\?xml-stylesheet\b/i)
+
+      raise InputError, "SVG DTDs, entities, and external stylesheets are not supported"
+    end
+
+    def validate_document!(document)
+      validate_dimensions!(document.root)
+      REXML::XPath.each(document, "//*") { |element| validate_element!(element) }
+    end
+
+    def validate_dimensions!(root)
+      width = root.attributes["width"]
+      height = root.attributes["height"]
+      view_box = root.attributes["viewBox"]
+
+      validate_explicit_dimensions!(width, height) if width || height
+      raise InputError, "SVG must define positive width and height or a viewBox" unless width || view_box
+
+      validate_view_box!(view_box) if view_box
+    end
+
+    def validate_explicit_dimensions!(width, height)
+      return if width && height && valid_length?(width) && valid_length?(height)
+
+      raise InputError, "SVG width and height must be positive values in px, mm, or in"
+    end
+
+    def validate_view_box!(view_box)
+      values = view_box.scan(NUMBER)
+      remainder = view_box.gsub(NUMBER, "").gsub(/[\s,]/, "")
+      valid = remainder.empty? && values.length == 4 && values.all? { |value| finite_number?(value) }
+      valid &&= values[2].to_f.positive? && values[3].to_f.positive?
+      raise InputError, "SVG viewBox must contain four finite numbers with positive width and height" unless valid
+    end
+
+    def valid_length?(value)
+      value = value.strip
+      value.match?(LENGTH) && finite_number?(value.sub(/(?:px|mm|in)\z/i, "")) && value.to_f.positive?
+    end
+
+    def finite_number?(value)
+      Float(value).finite?
+    rescue ArgumentError
+      false
+    end
+
+    def validate_element!(element)
+      if FORBIDDEN_ELEMENTS.include?(element.name.downcase)
+        raise InputError, "SVG element <#{element.name}> is not supported"
+      end
+
+      element.attributes.each_attribute do |attribute|
+        name = attribute.expanded_name.downcase
+        value = attribute.value.to_s
+        validate_href!(value) if name == "href" || name.end_with?(":href")
+        raise InputError, "SVG xml:base is not supported" if name == "xml:base"
+
+        validate_css_references!(value)
+      end
+
+      return unless element.name.casecmp?("style")
+
+      validate_css_references!(element.texts.map(&:value).join)
+    end
+
+    def validate_href!(value)
+      value = value.strip
+      return if value.match?(/\A#[^\s#]+\z/)
+
+      raise InputError, "SVG external and data references are not supported"
+    end
+
+    def validate_css_references!(value)
+      css = normalize_css(value)
+      raise InputError, "SVG external CSS imports are not supported" if css.match?(/@import\b/i)
+
+      remainder = css.gsub(URL_REFERENCE) do
+        reference = Regexp.last_match(2) || Regexp.last_match(3)
+        validate_href!(reference.strip)
+        ""
+      end
+      return unless remainder.match?(/url\s*\(/i)
+
+      raise InputError, "SVG contains an invalid CSS URL reference"
+    end
+
+    def normalize_css(value)
+      css = value.gsub(%r{/\*.*?\*/}m, "").gsub(/\\(?:\r\n|[\n\r\f])/, "")
+      css = css.gsub(/\\([0-9a-f]{1,6})[ \t\r\n\f]?/i) { [Regexp.last_match(1).to_i(16)].pack("U") }
+      css.gsub(/\\(.)/m, "\\1")
+    rescue RangeError
+      raise InputError, "SVG contains an invalid CSS escape"
+    end
+  end
+
+  # Rasterizes a validated SVG at the resolution required by the sampling grids.
+  class SVGLoader
+    BASE_DPI = 96.0
+    MAXIMUM_FILE_BYTES = 15_000_000
+
+    def initialize(settings)
+      @settings = settings
+      @validator = SVGDocumentValidator.new
+    end
+
+    def call(path, access:)
+      data = read(path)
+      @validator.call(data)
+      ensure_loader!
+
+      probe = render(data, scale: 1.0, access: :sequential)
+      validate_rendered_image!(probe, pixels: false)
+      scale = render_scale(probe)
+      validate_planned_pixels!(probe, scale)
+
+      image = render(data, scale:, access:)
+      validate_rendered_image!(image)
+      image
+    end
+
+    private
+
+    def read(path)
+      raise InputError, "SVG input exceeds #{MAXIMUM_FILE_BYTES} bytes" if File.size(path) > MAXIMUM_FILE_BYTES
+
+      data = File.binread(path, MAXIMUM_FILE_BYTES + 1)
+      raise InputError, "SVG input exceeds #{MAXIMUM_FILE_BYTES} bytes" if data.bytesize > MAXIMUM_FILE_BYTES
+      raise InputError, "compressed SVG (SVGZ) is not supported" if data.start_with?("\x1F\x8B".b)
+
+      data
+    end
+
+    def ensure_loader!
+      Vips::Operation.new("svgload_buffer")
+    rescue Vips::Error
+      raise InputError, "SVG input requires libvips with librsvg support; install libvips with SVG support"
+    end
+
+    def render(data, scale:, access:)
+      Vips::Image.new_from_buffer(data, "", dpi: BASE_DPI, scale:, unlimited: false, access:)
+    rescue Vips::Error => e
+      raise InputError, "could not render SVG: #{e.message}"
+    end
+
+    def render_scale(image)
+      scales = sampling_grids.map do |grid|
+        width, height = grid.content_sample_size
+        ratios = [width.fdiv(image.width), height.fdiv(image.height)]
+        @settings.image_fit == "contain" ? ratios.min * @settings.crop_scale : ratios.max / @settings.crop_scale
+      end
+      [*scales, 1.0 / image.width, 1.0 / image.height].max
+    end
+
+    def sampling_grids
+      grids = [@settings.sampling_grid]
+      grids << @settings.color_sampling_grid if @settings.color_pixel_size
+      grids
+    end
+
+    def validate_planned_pixels!(image, scale)
+      width = [(image.width * scale).ceil, 1].max
+      height = [(image.height * scale).ceil, 1].max
+      validate_pixel_count!(width, height, "SVG rasterization would exceed")
+    end
+
+    def validate_rendered_image!(image, pixels: true)
+      unless image.get("vips-loader") == "svgload_buffer" && image.width.positive? && image.height.positive?
+        raise InputError, "could not render SVG with positive dimensions"
+      end
+
+      validate_pixel_count!(image.width, image.height, "SVG rasterization exceeds") if pixels
+    end
+
+    def validate_pixel_count!(width, height, prefix)
+      return unless width * height > @settings.maximum_input_pixels
+
+      raise InputError, "#{prefix} #{@settings.maximum_input_pixels} pixels"
+    end
+  end
+end

data/lib/lithop/instrumentation.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Lithop
+  # Measures named generation stages for an optional benchmark listener.
+  class Instrumentation
+    def initialize(listener = nil)
+      @listener = listener
+    end
+
+    def measure(stage)
+      return yield unless @listener
+
+      started = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      yield
+    ensure
+      if @listener && started
+        elapsed = Process.clock_gettime(Process::CLOCK_MONOTONIC) - started
+        @listener.call(stage, elapsed)
+      end
+    end
+  end
+end

data/lib/lithop/job_directory.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+require "fileutils"
+
+module Lithop
+  # Owns one temporary job directory and publishes it with an atomic rename.
+  class JobDirectory
+    attr_reader :destination, :temporary
+
+    def initialize(project_dir:, job_id:)
+      build_dir = File.join(File.expand_path(project_dir), "build")
+      @destination = File.join(build_dir, job_id)
+      @temporary = File.join(build_dir, ".tmp-#{job_id}")
+      @owned = false
+    end
+
+    def call
+      acquire
+      result = yield temporary
+      publish
+      [destination, result]
+    rescue StandardError, Interrupt
+      cleanup
+      raise
+    end
+
+    private
+
+    def acquire
+      FileUtils.mkdir_p(File.dirname(temporary))
+      raise Error, "output already exists: #{destination}" if File.exist?(destination)
+
+      Dir.mkdir(temporary)
+      @owned = true
+    rescue Errno::EEXIST
+      raise Error, "output already exists: #{File.exist?(destination) ? destination : temporary}"
+    end
+
+    def publish
+      raise Error, "output already exists: #{destination}" if File.exist?(destination)
+
+      File.rename(temporary, destination)
+      @owned = false
+    end
+
+    def cleanup
+      return unless @owned
+
+      FileUtils.rm_rf(temporary)
+      @owned = false
+    rescue StandardError
+      @owned = false
+    end
+  end
+end

data/lib/lithop/layer_structure.rb

@@ -0,0 +1,134 @@
+# frozen_string_literal: true
+
+module Lithop
+  # Calculates printable Z boundaries and the physical CMYW layer structure.
+  # rubocop:disable-next Metrics/ClassLength
+  class LayerStructure
+    MICRONS_PER_MM = 1_000
+    MINIMUM_TOP_WHITE_LAYERS = 3
+
+    attr_reader :first_layer_height, :layer_height, :color_layer_count, :base_white_layers,
+                :top_layer_height, :top_white_start, :minimum_top_white_layers,
+                :effective_minimum_thickness, :effective_maximum_thickness
+
+    # rubocop:disable-next Metrics/ParameterLists
+    def initialize(
+      first_layer_height:, layer_height:, color_layer_count:, minimum_thickness:, maximum_thickness:,
+      base_white_layers: 1, top_layer_height: nil, top_white_start: nil,
+      minimum_top_white_layers: MINIMUM_TOP_WHITE_LAYERS, exact_maximum_thickness: false
+    )
+      @first_layer_height = first_layer_height
+      @layer_height = layer_height
+      @color_layer_count = color_layer_count
+      @base_white_layers = base_white_layers
+      @top_layer_height = top_layer_height || layer_height
+      @top_white_start = top_white_start || color_end
+      @minimum_top_white_layers = minimum_top_white_layers
+      @effective_minimum_thickness = aligned_at_or_above(minimum_thickness)
+      @effective_maximum_thickness = if exact_maximum_thickness
+                                       maximum_thickness.round(9)
+                                     else
+                                       aligned_at_or_below(maximum_thickness)
+                                     end
+    end
+
+    def minimum_physical_thickness
+      (top_white_start + (minimum_top_white_layers * top_layer_height)).round(9)
+    end
+
+    def quantize_thickness(value)
+      printable_thicknesses.min_by { |boundary| [(boundary - value).abs.round(12), -boundary] }
+    end
+
+    def normal_layer_count(height)
+      boundary_index(height) - base_white_layers
+    end
+
+    def top_white_layer_count(height, pigment_layers: color_layer_count)
+      boundary_index(height) - base_white_layers - pigment_layers
+    end
+
+    def top_white_thickness(height, pigment_layers: color_layer_count)
+      return 0.0 if pigment_layers != color_layer_count
+
+      (height - color_end).round(9)
+    end
+
+    def z_boundaries(material_layer_count)
+      all_boundaries.first(material_layer_count + 1)
+    end
+
+    def color_region_thickness = (color_layer_count * layer_height).round(9)
+    def base_white_thickness = (base_white_layers * first_layer_height).round(9)
+    def minimum_top_white_thickness = (minimum_physical_thickness - color_end).round(9)
+
+    def materials_for(recipe_layers, height)
+      top_white_layers = top_white_layer_count(height, pigment_layers: recipe_layers.length)
+      [*Array.new(base_white_layers, :white), *recipe_layers, *Array.new(top_white_layers, :white)]
+    end
+
+    private
+
+    def color_end
+      ((base_white_layers * first_layer_height) + color_region_thickness).round(9)
+    end
+
+    def aligned_at_or_above(value)
+      return top_white_start if value <= top_white_start
+
+      steps = (((value - top_white_start) / top_layer_height) - 1e-9).ceil
+      (top_white_start + (steps * top_layer_height)).round(9)
+    end
+
+    def aligned_at_or_below(value)
+      return 0.0 if value < top_white_start
+
+      steps = (((value - top_white_start) / top_layer_height) + 1e-9).floor
+      (top_white_start + (steps * top_layer_height)).round(9)
+    end
+
+    def printable_thicknesses
+      @printable_thicknesses ||= begin
+        values = []
+        value = effective_minimum_thickness
+        while value <= effective_maximum_thickness + 1e-9
+          values << value.round(9)
+          value += top_layer_height
+        end
+        values << effective_maximum_thickness unless values.any? do |candidate|
+          same_boundary?(candidate, effective_maximum_thickness)
+        end
+        values.freeze
+      end
+    end
+
+    # rubocop:disable-next Metrics/AbcSize
+    def all_boundaries
+      @all_boundaries ||= begin
+        values = [0.0]
+        base_white_layers.times { |index| values << ((index + 1) * first_layer_height).round(9) }
+        color_layer_count.times do |index|
+          values << (color_end - ((color_layer_count - index - 1) * layer_height)).round(9)
+        end
+        values << top_white_start unless same_boundary?(values.last, top_white_start)
+        value = (top_white_start + top_layer_height).round(9)
+        while value <= effective_maximum_thickness + 1e-9
+          values << value unless values.any? { |candidate| same_boundary?(candidate, value) }
+          value = (value + top_layer_height).round(9)
+        end
+        values << effective_maximum_thickness unless
+          values.any? { |candidate| same_boundary?(candidate, effective_maximum_thickness) }
+        values.freeze
+      end
+    end
+
+    def boundary_index(height)
+      index = all_boundaries.index { |boundary| same_boundary?(boundary, height) }
+      return index if index
+
+      raise ConfigurationError, "thickness #{height} is not a printable layer boundary"
+    end
+
+    def same_boundary?(left, right) = (left - right).abs < 1e-8
+  end
+end

data/lib/lithop/mesh/column_geometry.rb

@@ -0,0 +1,161 @@
+# frozen_string_literal: true
+
+module Lithop
+  # Builds one closed pigment solid from a single contiguous Z interval per XY cell.
+  # rubocop:disable-next Metrics/ClassLength
+  class ColumnGeometry
+    include Enumerable
+
+    def initialize(model:, material:)
+      unless Palette::PIGMENTS.include?(material)
+        raise InputError, "column geometry requires a CMY pigment: #{material.inspect}"
+      end
+
+      @model = model
+      @material = material
+      @intervals = model.cells.map { |cell| interval(cell.materials) }.freeze
+      @topology = ColumnTopology.new(model:, intervals: @intervals)
+    end
+
+    def each_triangle(&)
+      return enum_for(__method__) unless block_given?
+
+      @model.rows.times do |row|
+        @model.columns.times do |column|
+          current = interval_at(row, column)
+          next unless current
+
+          emit_caps(row, column, current, &)
+          emit_sides(row, column, current, &)
+        end
+      end
+    end
+
+    def each(&) = each_triangle(&)
+
+    def release_cache! = @topology.release_cache!
+
+    def triangle_count
+      @model.rows.times.sum do |row|
+        @model.columns.times.sum do |column|
+          current = interval_at(row, column)
+          next 0 unless current
+
+          side_layers = exposed_layer_count(current, grouped_interval(row, column, row, column - 1)) +
+                        exposed_layer_count(current, grouped_interval(row, column, row, column + 1)) +
+                        exposed_layer_count(current, grouped_interval(row, column, row + 1, column)) +
+                        exposed_layer_count(current, grouped_interval(row, column, row - 1, column))
+          4 + (side_layers * 2)
+        end
+      end
+    end
+
+    private
+
+    def interval(materials)
+      first = materials.index(@material)
+      return unless first
+
+      last = materials.rindex(@material)
+      [first, last + 1]
+    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 emit_caps(row, column, current, &)
+      bottom, top = current
+      bottom_owner = [bottom, row, column]
+      top_owner = [top - 1, row, column]
+      quad(
+        vertex(column, row + 1, bottom, bottom_owner), vertex(column, row, bottom, bottom_owner),
+        vertex(column + 1, row, bottom, bottom_owner), vertex(column + 1, row + 1, bottom, bottom_owner), &
+      )
+      quad(
+        vertex(column, row + 1, top, top_owner), vertex(column + 1, row + 1, top, top_owner),
+        vertex(column + 1, row, top, top_owner), vertex(column, row, top, top_owner), &
+      )
+    end
+
+    # Four directions intentionally stay together so their winding order is easy to compare.
+    # rubocop:disable-next Metrics/AbcSize
+    def emit_sides(row, column, current, &)
+      emit_side(current, grouped_interval(row, column, row, column - 1)) do |layer|
+        owner = [layer, row, column]
+        quad(
+          vertex(column, row + 1, layer, owner), vertex(column, row + 1, layer + 1, owner),
+          vertex(column, row, layer + 1, owner), vertex(column, row, layer, owner), &
+        )
+      end
+      emit_side(current, grouped_interval(row, column, row, column + 1)) do |layer|
+        owner = [layer, row, column]
+        quad(
+          vertex(column + 1, row + 1, layer, owner), vertex(column + 1, row, layer, owner),
+          vertex(column + 1, row, layer + 1, owner), vertex(column + 1, row + 1, layer + 1, owner), &
+        )
+      end
+      emit_side(current, grouped_interval(row, column, row + 1, column)) do |layer|
+        owner = [layer, row, column]
+        quad(
+          vertex(column, row + 1, layer, owner), vertex(column + 1, row + 1, layer, owner),
+          vertex(column + 1, row + 1, layer + 1, owner), vertex(column, row + 1, layer + 1, owner), &
+        )
+      end
+      emit_side(current, grouped_interval(row, column, row - 1, column)) do |layer|
+        owner = [layer, row, column]
+        quad(
+          vertex(column, row, layer, owner), vertex(column, row, layer + 1, owner),
+          vertex(column + 1, row, layer + 1, owner), vertex(column + 1, row, layer, owner), &
+        )
+      end
+    end
+
+    def emit_side(current, neighbour, &)
+      bottom, top = current
+      unless neighbour
+        emit_layers(bottom, top, &)
+        return
+      end
+      neighbour_bottom, neighbour_top = neighbour
+      if neighbour_top <= bottom || neighbour_bottom >= top
+        emit_layers(bottom, top, &)
+        return
+      end
+      emit_layers(bottom, [top, neighbour_bottom].min, &) if neighbour_bottom > bottom
+      return unless neighbour_top < top
+
+      emit_layers([bottom, neighbour_top].max, top, &)
+    end
+
+    def exposed_layer_count(current, neighbour)
+      bottom, top = current
+      return top - bottom unless neighbour
+
+      neighbour_bottom, neighbour_top = neighbour
+      overlap = [[top, neighbour_top].min - [bottom, neighbour_bottom].max, 0].max
+      (top - bottom) - overlap
+    end
+
+    def grouped_interval(row, column, neighbour_row, neighbour_column)
+      return unless @topology.same_group?(row, column, neighbour_row, neighbour_column)
+
+      interval_at(neighbour_row, neighbour_column)
+    end
+
+    def emit_layers(bottom, top, &)
+      (bottom...top).each(&)
+    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