lithop 0.1.0 → 0.3.0

data/lib/lithop/model/material_model.rb

@@ -17,6 +17,7 @@ module Lithop
         pigment_order: settings.pigment_order
       )
       @settings = settings
+      @material_arrays = {}
       validate_samples!(cmys, heights, cell_cmys)
       @cells = build_cells(cmys, heights, cell_cmys).freeze
       maximum_layers = cells.map { |cell| cell.materials.length }.max
@@ -31,7 +32,9 @@ module Lithop
     end
 
     def materials
-      @materials ||= cells.flat_map(&:materials).uniq.freeze
+      @materials ||= cells.each_with_object({}) do |cell, result|
+        cell.materials.each { |material| result[material] = true }
+      end.keys.freeze
     end
 
     def recipe_counts
@@ -63,12 +66,21 @@ module Lithop
     end
 
     def build_cells(cmys, heights, cell_cmys)
-      Array.new(rows * columns) do |index|
+      cell_heights = Array.new(rows * columns)
+      cell_colors = Array.new(rows * columns) do |index|
         row, column = index.divmod(columns)
         cmy = cell_cmys ? cell_cmys.fetch(index) : average(corners(cmys, row, column))
-        height = @settings.quantize_thickness(average(corners(heights, row, column)))
-        recipe = @palette.nearest(cmy)
-        Cell.new(height:, recipe:, materials: materials_for(recipe, height).freeze)
+        cell_heights[index] = @settings.quantize_thickness(average(corners(heights, row, column)))
+        cmy
+      end
+      recipes = if @palette.respond_to?(:nearest_many)
+                  @palette.nearest_many(cell_colors)
+                else
+                  cell_colors.map { |cmy| @palette.nearest(cmy) }
+                end
+      cell_heights.zip(recipes).map do |height, recipe|
+        materials = @material_arrays[[recipe, height]] ||= materials_for(recipe, height).freeze
+        Cell.new(height:, recipe:, materials:)
       end
     end
 

data/lib/lithop/model/palette.rb

@@ -49,13 +49,20 @@ module Lithop
       @layer_count = layer_count
       @pigment_order = pigment_order.dup.freeze
       @recipes = build_recipes.freeze
+      @native_coverages = recipes.flat_map(&:coverage_cmy).freeze
     end
 
     def nearest(cmy)
       validate_cmy!(cmy)
-      recipes.min_by do |recipe|
-        recipe.coverage_cmy.zip(cmy).sum { |coverage, target| (coverage - target)**2 }
-      end
+      nearest_validated(cmy)
+    end
+
+    def nearest_many(cmys)
+      cmys.each { |cmy| validate_cmy!(cmy) }
+      return cmys.map { |cmy| nearest_validated(cmy) } unless Native.enabled?
+
+      indices = Native.palette_indices(cmys.flatten, @native_coverages)
+      indices.map { |index| recipes.fetch(index) }
     end
 
     def display_color(recipe)
@@ -97,5 +104,16 @@ module Lithop
 
       raise InputError, "CMY must contain three values between 0 and 1"
     end
+
+    def squared_distance(coverage, target)
+      cyan = coverage[0] - target[0]
+      magenta = coverage[1] - target[1]
+      yellow = coverage[2] - target[2]
+      (cyan * cyan) + (magenta * magenta) + (yellow * yellow)
+    end
+
+    def nearest_validated(cmy)
+      recipes.min_by { |recipe| squared_distance(recipe.coverage_cmy, cmy) }
+    end
   end
 end

data/lib/lithop/native.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require "rbconfig"
+
+module Lithop
+  # Loads optional acceleration implemented by the bundled Rust extension.
+  module Native
+    class << self
+      def available? = @available == true
+
+      def enabled? = available? && ENV["LITHOP_DISABLE_NATIVE"] != "1"
+
+      def backend = enabled? ? :rust : :ruby
+
+      def loaded_extension_version
+        extension_version if available? && respond_to?(:extension_version)
+      end
+
+      def diagnostics
+        {
+          backend:,
+          available: available?,
+          enabled: enabled?,
+          extension_version: loaded_extension_version,
+          lithop_version: Lithop::VERSION,
+          ruby: RUBY_DESCRIPTION,
+          platform: RbConfig::CONFIG.fetch("host")
+        }
+      end
+    end
+  end
+end
+
+begin
+  require "lithop_native/lithop_native"
+  Lithop::Native.instance_variable_set(:@available, true)
+rescue LoadError
+  Lithop::Native.instance_variable_set(:@available, false)
+end

data/lib/lithop/reference_three_mf.rb

@@ -7,6 +7,7 @@ require "zip"
 
 module Lithop
   # Streams structural measurements from an existing 3MF without retaining its meshes.
+  # rubocop:disable-next Metrics/ClassLength
   class ReferenceThreeMF
     def initialize(path)
       @path = File.expand_path(path)
@@ -63,6 +64,7 @@ module Lithop
     def start_object(event)
       {
         id: event[1]["id"], type: event[1]["type"], vertices: 0, triangles: 0, components: 0,
+        component_refs: [],
         minimum: [nil, nil, nil], maximum: [nil, nil, nil]
       }
     end
@@ -80,6 +82,10 @@ module Lithop
         current[:triangles] += 1
       when "component"
         current[:components] += 1
+        current[:component_refs] << {
+          object_id: event[1]["objectid"],
+          transform: transform_values(event[1]["transform"])
+        }
       end
     end
 
@@ -105,7 +111,11 @@ module Lithop
 
       document.get_elements("config/plate").map do |plate|
         metadata = plate.get_elements("metadata").to_h { |entry| [entry.attributes["key"], entry.attributes["value"]] }
-        { id: integer_or_nil(metadata["plater_id"]), name: metadata["plater_name"] }
+        object_ids = plate.get_elements("model_instance").filter_map do |instance|
+          entry = instance.get_elements("metadata").find { |item| item.attributes["key"] == "object_id" }
+          entry && entry.attributes["value"]
+        end
+        { id: integer_or_nil(metadata["plater_id"]), name: metadata["plater_name"], object_ids: }
       end
     end
 
@@ -115,5 +125,11 @@ module Lithop
     end
 
     def integer_or_nil(value) = value && Integer(value)
+
+    def transform_values(value)
+      return unless value
+
+      value.split.map { |number| Float(number) }
+    end
   end
 end

data/lib/lithop/settings.rb

@@ -13,10 +13,13 @@ module Lithop
       validate_color_model!
       validate_layout_profile!
       validate_grid!
+      validate_tiles!
       validate_layer_structure!
+      validate_z_parts!
       validate_advanced_layer_structure!
       validate_margins!
       validate_image_placement!
+      validate_image_adjustments!
       validate_nozzle_diameter!
       validate_mesh_limit!
     end
@@ -73,6 +76,55 @@ module Lithop
       raise ConfigurationError, "grid_columns and grid_rows must be positive integers or null"
     end
 
+    def validate_tiles!
+      validate_tile_count!
+      validate_tile_layout!
+      validate_tile_grid!
+
+      if tile_count > columns * rows
+        raise ConfigurationError, "tile layout must leave at least one XY cell in every tile"
+      end
+
+      return if resolved_tile_columns <= columns && resolved_tile_rows <= rows
+
+      raise ConfigurationError, "tile layout must leave at least one XY cell in every tile"
+    end
+
+    def validate_tile_count!
+      return if tile_count.is_a?(Integer) && tile_count.positive?
+
+      raise ConfigurationError, "tile_count must be a positive integer"
+    end
+
+    def validate_tile_layout!
+      return if Settings::TILE_LAYOUTS.include?(tile_layout)
+
+      raise ConfigurationError, "tile_layout must be one of: #{Settings::TILE_LAYOUTS.join(", ")}"
+    end
+
+    def validate_tile_grid!
+      unless tile_layout == "grid"
+        return if tile_rows.nil? && tile_columns.nil?
+
+        raise ConfigurationError, "tile_rows and tile_columns may only be set for grid layout"
+      end
+      unless tile_rows.is_a?(Integer) && tile_rows.positive? &&
+             tile_columns.is_a?(Integer) && tile_columns.positive?
+        raise ConfigurationError, "tile_rows and tile_columns must be positive integers for grid layout"
+      end
+      return if tile_rows * tile_columns == tile_count
+
+      raise ConfigurationError, "tile_rows times tile_columns must equal tile_count"
+    end
+
+    def validate_z_parts!
+      raise ConfigurationError, "separate_z_parts must be a boolean" unless [true, false].include?(separate_z_parts)
+      unless color_region_parts.is_a?(Integer) && color_region_parts.positive? &&
+             color_region_parts <= color_layer_count
+        raise ConfigurationError, "color_region_parts must be an integer from 1 to color_layer_count"
+      end
+    end
+
     def validate_layer_structure!
       return if Settings::COLOR_LAYER_COUNTS.include?(color_layer_count)
 
@@ -128,6 +180,15 @@ module Lithop
       raise ConfigurationError, "crop_scale must be a finite number greater than 0 and at most 1"
     end
 
+    def validate_image_adjustments!
+      %i[brightness contrast saturation].each do |key|
+        value = public_send(key)
+        next if value.is_a?(Numeric) && value.finite? && value.between?(-100.0, 100.0)
+
+        raise ConfigurationError, "#{key} must be a finite percentage from -100 to 100"
+      end
+    end
+
     def validate_nozzle_diameter!
       return if Settings::NOZZLE_DIAMETERS.include?(nozzle_diameter)
 
@@ -174,6 +235,7 @@ module Lithop
     COLOR_LAYER_COUNTS = [4, 5, 7].freeze
     LAYOUT_PROFILES = ["standard"].freeze
     IMAGE_FITS = %w[cover contain].freeze
+    TILE_LAYOUTS = %w[auto columns rows grid].freeze
     PIGMENTS = %i[cyan magenta yellow].freeze
     MINIMUM_TOP_WHITE_LAYERS = LayerStructure::MINIMUM_TOP_WHITE_LAYERS
     DEFAULTS = {
@@ -188,12 +250,21 @@ module Lithop
       crop_position_x: 0.5,
       crop_position_y: 0.5,
       crop_scale: 1.0,
+      brightness: 0.0,
+      contrast: 0.0,
+      saturation: 0.0,
       minimum_thickness: 1.0,
       maximum_thickness: 2.14689422,
       pixel_size: 0.22,
       color_pixel_size: nil,
       grid_columns: 637,
       grid_rows: 473,
+      tile_count: 1,
+      tile_layout: "auto",
+      tile_rows: nil,
+      tile_columns: nil,
+      separate_z_parts: false,
+      color_region_parts: 3,
       first_layer_height: 0.1,
       layer_height: 0.1,
       base_white_layers: 2,
@@ -232,6 +303,7 @@ module Lithop
       end
 
       validate_physical_minimum!
+      validate_separated_top_white!
     end
 
     def without_default_grid(values)
@@ -250,6 +322,18 @@ module Lithop
     def pixel_size_x = width.fdiv(columns)
     def pixel_size_y = height.fdiv(rows)
 
+    def resolved_tile_shape
+      case tile_layout
+      when "columns" then [1, tile_count]
+      when "rows" then [tile_count, 1]
+      when "grid" then [tile_rows, tile_columns]
+      else automatic_tile_shape
+      end
+    end
+
+    def resolved_tile_rows = resolved_tile_shape.fetch(0)
+    def resolved_tile_columns = resolved_tile_shape.fetch(1)
+
     def estimated_triangles
       (4 * columns * rows) + (4 * (columns + rows))
     end
@@ -288,8 +372,39 @@ module Lithop
         effective_color_pixel_size: effective_color_pixel_size,
         effective_minimum_thickness: effective_minimum_thickness,
         effective_maximum_thickness: effective_maximum_thickness,
-        columns: columns, rows: rows, pixel_size_x: pixel_size_x, pixel_size_y: pixel_size_y
+        columns: columns, rows: rows, pixel_size_x: pixel_size_x, pixel_size_y: pixel_size_y,
+        resolved_tile_rows: resolved_tile_rows, resolved_tile_columns: resolved_tile_columns
       )
     end
+
+    private
+
+    def automatic_tile_shape
+      factors = factor_shapes.map do |row_count, column_count|
+        tile_width = width.fdiv(column_count)
+        tile_height = height.fdiv(row_count)
+        [[Math.log(tile_width.fdiv(tile_height)).abs, -column_count], [row_count, column_count]]
+      end
+      feasible = factors.select do |_score, (row_count, column_count)|
+        row_count <= rows && column_count <= columns
+      end
+      (feasible.empty? ? factors : feasible).min_by(&:first).last
+    end
+
+    def factor_shapes
+      (1..Math.sqrt(tile_count).floor).flat_map do |row_count|
+        next [] unless (tile_count % row_count).zero?
+
+        column_count = tile_count / row_count
+        row_count == column_count ? [[row_count, column_count]] : [[row_count, column_count], [column_count, row_count]]
+      end
+    end
+
+    def validate_separated_top_white!
+      return unless separate_z_parts
+      return if effective_minimum_thickness > layer_structure.color_region_end
+
+      raise ConfigurationError, "separate_z_parts requires a positive top White thickness"
+    end
   end
 end

data/lib/lithop/settings_file.rb

@@ -26,10 +26,7 @@ module Lithop
 
       validate_keys!(data, expanded)
       validate_schema!(data, expanded)
-      values = data.except("schema_version").transform_keys(&:to_sym)
-      values[:color_model] = values[:color_model].downcase if values[:color_model].is_a?(String)
-      values[:image_fit] = values[:image_fit].downcase if values[:image_fit].is_a?(String)
-      values[:layout_profile] = values[:layout_profile].downcase if values[:layout_profile].is_a?(String)
+      values = normalize_values(data.except("schema_version").transform_keys(&:to_sym))
       Result.new(path: expanded, values:)
     rescue JSON::ParserError => e
       raise ConfigurationError, "settings file is not valid JSON: #{expanded}: #{e.message}"
@@ -37,6 +34,15 @@ module Lithop
       raise ConfigurationError, "could not read settings file: #{expanded}: #{e.message}"
     end
 
+    def normalize_values(values)
+      values[:color_model] = values[:color_model].downcase if values[:color_model].is_a?(String)
+      values[:image_fit] = values[:image_fit].downcase if values[:image_fit].is_a?(String)
+      values[:layout_profile] = values[:layout_profile].downcase if values[:layout_profile].is_a?(String)
+      values[:tile_layout] = values[:tile_layout].downcase if values[:tile_layout].is_a?(String)
+      values
+    end
+    private_class_method :normalize_values
+
     def validate_keys!(data, path)
       unknown = data.keys - ALLOWED_KEYS
       return if unknown.empty?

data/lib/lithop/tiling.rb

@@ -0,0 +1,127 @@
+# frozen_string_literal: true
+
+module Lithop
+  # Resolves a deterministic tile grid on existing XY cell boundaries.
+  class TileLayout
+    Tile = Data.define(
+      :id, :row, :column, :row_start, :row_end, :column_start, :column_end,
+      :x_min, :x_max, :y_min, :y_max
+    ) do
+      def width = x_max - x_min
+      def height = y_max - y_min
+      def offset = { x: x_min, y: y_min }
+      def bounds = { x_min:, x_max:, y_min:, y_max: }
+    end
+
+    attr_reader :rows, :columns, :tiles
+
+    def initialize(settings)
+      @settings = settings
+      @rows = settings.resolved_tile_rows
+      @columns = settings.resolved_tile_columns
+      @tiles = build_tiles.freeze
+    end
+
+    private
+
+    def build_tiles
+      row_spans = partition(@settings.rows, rows)
+      column_spans = partition(@settings.columns, columns)
+      row_spans.each_with_index.flat_map do |(row_start, row_end), row|
+        column_spans.each_with_index.map do |(column_start, column_end), column|
+          Tile.new(
+            id: format("tile_r%<row>02d_c%<column>02d", row: row + 1, column: column + 1),
+            row: row + 1,
+            column: column + 1,
+            row_start:, row_end:, column_start:, column_end:,
+            x_min: @settings.x_boundaries.fetch(column_start),
+            x_max: @settings.x_boundaries.fetch(column_end),
+            y_min: (@settings.height - @settings.y_boundaries.fetch(row_end)).round(9),
+            y_max: (@settings.height - @settings.y_boundaries.fetch(row_start)).round(9)
+          )
+        end
+      end
+    end
+
+    def partition(cell_count, part_count)
+      size, remainder = cell_count.divmod(part_count)
+      start = 0
+      Array.new(part_count) do |index|
+        finish = start + size + (index < remainder ? 1 : 0)
+        [start, finish].tap { start = finish }
+      end
+    end
+  end
+
+  # Presents one rectangular subset of a material model in tile-local coordinates.
+  class TileMaterialModel
+    attr_reader :columns, :rows, :x_boundaries, :y_boundaries, :z_boundaries, :cells
+
+    def initialize(model:, tile:)
+      @columns = tile.column_end - tile.column_start
+      @rows = tile.row_end - tile.row_start
+      @x_boundaries = local_boundaries(model.x_boundaries, tile.column_start, tile.column_end)
+      @y_boundaries = local_boundaries(model.y_boundaries, tile.row_start, tile.row_end)
+      @z_boundaries = model.z_boundaries
+      @cells = slice_cells(model, tile).freeze
+    end
+
+    def materials = @materials ||= cells.flat_map(&:materials).uniq.freeze
+
+    private
+
+    def local_boundaries(boundaries, first, last)
+      origin = boundaries.fetch(first)
+      boundaries[first..last].map { |value| (value - origin).round(9) }.freeze
+    end
+
+    def slice_cells(model, tile)
+      (tile.row_start...tile.row_end).flat_map do |row|
+        offset = (row * model.columns) + tile.column_start
+        model.cells.slice(offset, columns)
+      end
+    end
+  end
+
+  # Writes a physical-size overview of the tile IDs and assembled placement.
+  module TileLayoutSVG
+    module_function
+
+    def write(path, settings:, layout:)
+      File.write(path, document(settings:, layout:))
+    end
+
+    def document(settings:, layout:, background: true)
+      rectangles = layout.tiles.map { |tile| tile_element(settings, tile) }.join("\n")
+      fill = background ? "#fff" : "none"
+      <<~SVG
+        <?xml version="1.0" encoding="UTF-8"?>
+        <svg xmlns="http://www.w3.org/2000/svg" width="#{settings.width}mm" height="#{settings.height}mm"
+             viewBox="0 0 #{settings.width} #{settings.height}">
+          <rect width="#{settings.width}" height="#{settings.height}" fill="#{fill}" stroke="#000" stroke-width="0.4"/>
+        #{rectangles}
+        </svg>
+      SVG
+    end
+
+    def tile_element(settings, tile)
+      y = settings.height - tile.y_max
+      font_size = [[tile.width, tile.height].min * 0.12, 5.0].min
+      center_x = tile.x_min + (tile.width / 2.0)
+      center_y = y + (tile.height / 2.0)
+      <<~SVG.chomp
+        <g>
+          <rect x="#{tile.x_min}" y="#{y}" width="#{tile.width}" height="#{tile.height}"
+                fill="none" stroke="#333" stroke-width="0.25"/>
+          <text x="#{center_x}" y="#{center_y - (font_size * 0.6)}"
+                font-family="sans-serif" font-size="#{font_size}" text-anchor="middle"
+                dominant-baseline="middle">#{tile.id}</text>
+          <text x="#{center_x}" y="#{center_y + (font_size * 0.6)}"
+                font-family="sans-serif" font-size="#{font_size * 0.72}" text-anchor="middle"
+                dominant-baseline="middle">#{tile.width.round(3)} × #{tile.height.round(3)} mm</text>
+        </g>
+      SVG
+    end
+    private_class_method :tile_element
+  end
+end

data/lib/lithop/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Lithop
-  VERSION = "0.1.0"
+  VERSION = "0.3.0"
 end