lithop 0.1.0

data/lib/lithop/model/filament_profile.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+module Lithop
+  # Describes and validates the filament materials used by multipart models.
+  module FilamentProfile
+    REQUIRED_CHANNELS = %i[cyan magenta yellow white].freeze
+
+    Material = Data.define(:channel, :name, :color_code, :display_color, :diameter_mm) do
+      def to_h
+        {
+          channel:,
+          name:,
+          color_code:,
+          display_color:,
+          diameter_mm:
+        }
+      end
+    end
+
+    DisplaySample = Data.define(:cmy, :density)
+
+    Profile = Data.define(:id, :name, :manufacturer, :product_url, :reference_url, :materials) do
+      def to_h
+        {
+          id:,
+          name:,
+          manufacturer:,
+          product_url:,
+          reference_url:,
+          materials: materials.map(&:to_h)
+        }
+      end
+    end
+
+    BAMBU_LAB_PLA_CMYK = Profile.new(
+      id: "bambu_lab_pla_basic_cmyw",
+      name: "Bambu Lab PLA Basic CMYW",
+      manufacturer: "Bambu Lab",
+      product_url: "https://jp.store.bambulab.com/products/pla-cmyk-lithophane",
+      reference_url: "https://wiki.bambulab.com/en/knowledge-sharing/CMYK-color-lithophane-printing-instructions",
+      materials: [
+        Material.new(
+          channel: :cyan, name: "PLA Basic Cyan", color_code: "10603",
+          display_color: "#0086D6FF", diameter_mm: 1.75
+        ),
+        Material.new(
+          channel: :magenta, name: "PLA Basic Magenta", color_code: "10202",
+          display_color: "#EC008CFF", diameter_mm: 1.75
+        ),
+        Material.new(
+          channel: :yellow, name: "PLA Basic Yellow", color_code: "10400",
+          display_color: "#FCE300FF", diameter_mm: 1.75
+        ),
+        Material.new(
+          channel: :white, name: "PLA Basic White", color_code: "10100",
+          display_color: "#FFFFFFFF", diameter_mm: 1.75
+        )
+      ].freeze
+    ).freeze
+
+    module_function
+
+    def default = BAMBU_LAB_PLA_CMYK
+
+    def display_sample(rgb)
+      cmy, density = MaterialDisplayMap.call(rgb)
+      DisplaySample.new(cmy:, density:) if cmy
+    end
+
+    def display_cmy(rgb) = display_sample(rgb)&.cmy
+
+    def validate!(profile)
+      channels = profile.materials.map(&:channel)
+      return true if channels == REQUIRED_CHANNELS
+
+      raise ConfigurationError, "filament profile must contain only Cyan, Magenta, Yellow, and White"
+    end
+  end
+end

data/lib/lithop/model/material_display_map.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module Lithop
+  # Recognizes the material-display mixtures used by the bundled CMY chart.
+  module MaterialDisplayMap
+    CMY_BLACK = [0.2, 0.4, 0.4].freeze
+    CMY_BLACK_DENSITIES = {
+      0xF4F4F5 => 0.05, 0xE8E8E9 => 0.1, 0xCFD1D2 => 0.2, 0xB8BABD => 0.3,
+      0x9FA3A6 => 0.4, 0x878B8F => 0.5, 0x707479 => 0.6, 0x575D62 => 0.7,
+      0x40464D => 0.8, 0x272F36 => 0.9, 0x101820 => 1.0
+    }.freeze
+    COLOR_CMYS = {
+      0x760081 => [0.4, 0.6, 0.0].freeze,
+      0x000075 => [0.4, 0.6, 0.0].freeze,
+      0x0043A6 => [0.6, 0.4, 0.0].freeze,
+      0x0086D6 => [1.0, 0.0, 0.0].freeze,
+      0x007F6B => [0.6, 0.0, 0.4].freeze,
+      0x007700 => [0.4, 0.0, 0.6].freeze,
+      0x7EAD00 => [0.4, 0.0, 0.6].freeze,
+      0xFCE300 => [0.0, 0.0, 1.0].freeze,
+      0xF37200 => [0.0, 0.4, 0.6].freeze,
+      0xE90000 => [0.0, 0.4, 0.6].freeze,
+      0xEB0046 => [0.0, 0.6, 0.4].freeze,
+      0xEC008C => [0.0, 1.0, 0.0].freeze
+    }.freeze
+    COLOR_LINES = COLOR_CMYS.map do |packed, cmy|
+      rgb = [packed >> 16, (packed >> 8) & 0xFF, packed & 0xFF]
+      direction = rgb.map { |component| component - 255 }
+      [direction.freeze, direction.sum { |component| component * component }, cmy]
+    end.freeze
+    MAXIMUM_ERROR = 3.0
+
+    module_function
+
+    def call(rgb)
+      channels = rgb.map { |component| (component * 255).round.clamp(0, 255) }
+      packed = channels.reduce(0) { |value, component| (value << 8) | component }
+      return [[0.0, 0.0, 0.0], 0.0] if packed == 0xFFFFFF
+      return [CMY_BLACK, CMY_BLACK_DENSITIES.fetch(packed)] if CMY_BLACK_DENSITIES.key?(packed)
+      return [COLOR_CMYS.fetch(packed), 1.0] if COLOR_CMYS.key?(packed)
+
+      match = closest_line(channels)
+      return unless match && match.first <= MAXIMUM_ERROR
+
+      _error, density, cmy = match
+      [cmy, density]
+    end
+
+    def closest_line(channels)
+      offset = channels.map { |component| component - 255 }
+      COLOR_LINES.filter_map do |direction, magnitude, cmy|
+        density = offset.zip(direction).sum { |value, axis| value * axis }.fdiv(magnitude)
+        next unless density.between?(0.0, 1.0)
+
+        error = offset.zip(direction).sum { |value, axis| (value - (density * axis))**2 }
+        [error, density, cmy]
+      end.min_by(&:first)
+    end
+    private_class_method :closest_line
+  end
+end

data/lib/lithop/model/material_model.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+module Lithop
+  # Builds the printable material grid from sampled colors and thicknesses.
+  class MaterialModel
+    Cell = Data.define(:height, :recipe, :materials)
+
+    attr_reader :columns, :rows, :x_boundaries, :y_boundaries, :z_boundaries, :cells
+
+    def initialize(cmys:, heights:, settings:, palette: nil, cell_cmys: nil)
+      @columns = settings.columns
+      @rows = settings.rows
+      @x_boundaries = settings.x_boundaries
+      @y_boundaries = settings.y_boundaries
+      @palette = palette || Palette.new(
+        layer_count: settings.color_layer_count,
+        pigment_order: settings.pigment_order
+      )
+      @settings = settings
+      validate_samples!(cmys, heights, cell_cmys)
+      @cells = build_cells(cmys, heights, cell_cmys).freeze
+      maximum_layers = cells.map { |cell| cell.materials.length }.max
+      @z_boundaries = @settings.layer_structure.z_boundaries(maximum_layers).freeze
+    end
+
+    def material_at(layer, row, column)
+      return if layer.negative? || row.negative? || column.negative?
+      return if row >= rows || column >= columns
+
+      cells.fetch((row * columns) + column).materials[layer]
+    end
+
+    def materials
+      @materials ||= cells.flat_map(&:materials).uniq.freeze
+    end
+
+    def recipe_counts
+      cells.each_with_object(Hash.new(0)) do |cell, counts|
+        key = Palette::MATERIALS.map { |material| cell.recipe.public_send(material) }.join(":")
+        counts[key] += 1
+      end.freeze
+    end
+
+    def recipe_summaries
+      counts = cells.each_with_object(Hash.new(0)) { |cell, result| result[cell.recipe] += 1 }
+      @palette.recipes.filter_map do |recipe|
+        cell_count = counts[recipe]
+        next if cell_count.zero?
+
+        { counts: recipe.to_h.fetch(:counts), cells: cell_count }
+      end.freeze
+    end
+
+    private
+
+    def validate_samples!(cmys, heights, cell_cmys)
+      expected = (columns + 1) * (rows + 1)
+      raise InputError, "expected #{expected} CMY samples, got #{cmys.length}" unless cmys.length == expected
+      raise InputError, "expected #{expected} height samples, got #{heights.length}" unless heights.length == expected
+      return if cell_cmys.nil? || cell_cmys.length == columns * rows
+
+      raise InputError, "expected #{columns * rows} color cells, got #{cell_cmys.length}"
+    end
+
+    def build_cells(cmys, heights, cell_cmys)
+      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)
+      end
+    end
+
+    def corners(values, row, column)
+      stride = columns + 1
+      top_left = (row * stride) + column
+      [
+        values.fetch(top_left),
+        values.fetch(top_left + 1),
+        values.fetch(top_left + stride),
+        values.fetch(top_left + stride + 1)
+      ]
+    end
+
+    def average(values)
+      return values.sum.fdiv(values.length) unless values.first.is_a?(Array)
+
+      values.transpose.map { |components| components.sum.fdiv(components.length) }
+    end
+
+    def materials_for(recipe, height)
+      top_white_layers = @settings.layer_structure.top_white_layer_count(height, pigment_layers: @palette.layer_count)
+      if top_white_layers < @settings.minimum_top_white_layers
+        raise ConfigurationError,
+              "physical CMYW output requires at least #{minimum_thickness} mm thickness"
+      end
+
+      @settings.layer_structure.materials_for(recipe.layers, height)
+    end
+
+    def minimum_thickness
+      @settings.layer_structure.minimum_physical_thickness
+    end
+  end
+end

data/lib/lithop/model/palette.rb

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+module Lithop
+  # Maps CMY samples to printable CMYW layer recipes.
+  class Palette
+    PIGMENTS = %i[cyan magenta yellow].freeze
+    MATERIALS = [*PIGMENTS, :white].freeze
+    SUBTRACTIVE_MIXES = {
+      green: %i[cyan yellow].freeze,
+      purple: %i[cyan magenta].freeze,
+      red: %i[magenta yellow].freeze
+    }.freeze
+    DEFAULT_LAYER_COUNT = 7
+
+    Recipe = Data.define(:cyan, :magenta, :yellow, :white, :coverage_cmy, :ordered_layers) do
+      def layer_count
+        cyan + magenta + yellow + white
+      end
+
+      def layers = ordered_layers
+
+      def pigments
+        PIGMENTS.select { |pigment| public_send(pigment).positive? }
+      end
+
+      def to_h
+        {
+          counts: MATERIALS.to_h { |material| [material, public_send(material)] },
+          layers:,
+          pigments:,
+          coverage_cmy:
+        }
+      end
+    end
+
+    attr_reader :layer_count, :pigment_order, :recipes
+
+    def initialize(layer_count: DEFAULT_LAYER_COUNT, pigment_order: PIGMENTS)
+      unless layer_count.is_a?(Integer) && layer_count.positive?
+        raise ConfigurationError, "palette layer_count must be a positive integer"
+      end
+
+      valid_pigment_order = pigment_order.is_a?(Array) && pigment_order.length == PIGMENTS.length &&
+                            pigment_order.sort == PIGMENTS.sort
+      unless valid_pigment_order
+        raise ConfigurationError, "palette pigment_order must contain cyan, magenta, and yellow exactly once"
+      end
+
+      @layer_count = layer_count
+      @pigment_order = pigment_order.dup.freeze
+      @recipes = build_recipes.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
+    end
+
+    def display_color(recipe)
+      channels = recipe.coverage_cmy.map { |component| ((1.0 - component) * 255).round.clamp(0, 255) }
+      format("#%<red>02X%<green>02X%<blue>02XFF", red: channels[0], green: channels[1], blue: channels[2])
+    end
+
+    private
+
+    def build_recipes
+      recipes = []
+      (0..layer_count).each do |cyan|
+        (0..(layer_count - cyan)).each do |magenta|
+          (0..(layer_count - cyan - magenta)).each do |yellow|
+            white = layer_count - cyan - magenta - yellow
+            counts = { cyan:, magenta:, yellow: }
+            recipes << Recipe.new(
+              cyan:,
+              magenta:,
+              yellow:,
+              white:,
+              coverage_cmy: coverage_cmy(cyan:, magenta:, yellow:),
+              ordered_layers: pigment_order.flat_map { |pigment| [pigment] * counts.fetch(pigment) } +
+                Array.new(white, :white)
+            )
+          end
+        end
+      end
+      recipes
+    end
+
+    def coverage_cmy(cyan:, magenta:, yellow:)
+      [cyan, magenta, yellow].map { |layers| layers.fdiv(layer_count) }.freeze
+    end
+
+    def validate_cmy!(cmy)
+      return if cmy.is_a?(Array) && cmy.length == 3 &&
+                cmy.all? { |value| value.is_a?(Numeric) && value.finite? && value.between?(0.0, 1.0) }
+
+      raise InputError, "CMY must contain three values between 0 and 1"
+    end
+  end
+end

data/lib/lithop/model/thickness.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module Lithop
+  # Converts image density values into printable, layer-aligned thicknesses.
+  module Thickness
+    module_function
+
+    def from_cmy_density(densities, settings)
+      validate_densities!(densities)
+      densities = normalize_reference_densities(densities)
+      minimum = settings.effective_minimum_thickness
+      range = settings.effective_maximum_thickness - minimum
+
+      densities.map do |density|
+        unless density.is_a?(Numeric) && density.finite? && density.between?(0.0, 1.0)
+          raise InputError, "CMY density must be between 0 and 1"
+        end
+
+        settings.quantize_thickness(minimum + (density * range))
+      end
+    end
+
+    def continuous_from_density(densities, settings)
+      validate_densities!(densities)
+      normalized = normalize_reference_densities(densities)
+      minimum = settings.effective_minimum_thickness
+      range = settings.effective_maximum_thickness - minimum
+      normalized.map { |density| minimum + (density * range) }
+    end
+
+    def validate_densities!(densities)
+      return if densities.all? { |density| density.is_a?(Numeric) && density.finite? && density.between?(0.0, 1.0) }
+
+      raise InputError, "CMY density must be between 0 and 1"
+    end
+
+    def normalize_reference_densities(densities)
+      minimum, maximum = densities.minmax
+      return Array.new(densities.length, 0.0) if maximum == minimum
+
+      densities.map { |density| (density - minimum).fdiv(maximum - minimum) }
+    end
+    private_class_method :normalize_reference_densities, :validate_densities!
+  end
+end

data/lib/lithop/reference_three_mf.rb

@@ -0,0 +1,119 @@
+# frozen_string_literal: true
+
+require "digest"
+require "rexml/document"
+require "rexml/parsers/pullparser"
+require "zip"
+
+module Lithop
+  # Streams structural measurements from an existing 3MF without retaining its meshes.
+  class ReferenceThreeMF
+    def initialize(path)
+      @path = File.expand_path(path)
+    end
+
+    def call
+      raise InputError, "reference 3MF does not exist: #{@path}" unless File.file?(@path)
+
+      Zip::File.open(@path) do |archive|
+        entries = archive.entries
+        {
+          path: @path,
+          sha256: Digest::SHA256.file(@path).hexdigest,
+          bytes: File.size(@path),
+          entry_count: entries.length,
+          entries: entries.map(&:name).sort,
+          uncompressed_bytes: entries.sum(&:size),
+          models: model_entries(archive),
+          parts: parts(archive),
+          plates: plates(archive)
+        }
+      end
+    rescue Zip::Error, REXML::ParseException => e
+      raise InputError, "could not inspect reference 3MF: #{e.message}"
+    end
+
+    private
+
+    def model_entries(archive)
+      archive.entries.filter_map do |entry|
+        next unless entry.name.start_with?("3D/") && entry.name.end_with?(".model")
+
+        entry.get_input_stream { |stream| inspect_model(entry.name, stream) }
+      end
+    end
+
+    def inspect_model(name, stream)
+      parser = REXML::Parsers::PullParser.new(stream)
+      objects = []
+      current = nil
+      while parser.has_next?
+        event = parser.pull
+        if event.start_element?
+          current = start_object(event) if event[0] == "object"
+          inspect_mesh_element(current, event) if current
+        elsif event.end_element? && event[0] == "object" && current
+          objects << finish_object(current)
+          current = nil
+        end
+      end
+      { file: name, objects: }
+    end
+
+    def start_object(event)
+      {
+        id: event[1]["id"], type: event[1]["type"], vertices: 0, triangles: 0, components: 0,
+        minimum: [nil, nil, nil], maximum: [nil, nil, nil]
+      }
+    end
+
+    def inspect_mesh_element(current, event)
+      case event[0]
+      when "vertex"
+        coordinates = %w[x y z].map { |axis| Float(event[1].fetch(axis)) }
+        current[:vertices] += 1
+        coordinates.each_index do |index|
+          current[:minimum][index] = [current[:minimum][index], coordinates[index]].compact.min
+          current[:maximum][index] = [current[:maximum][index], coordinates[index]].compact.max
+        end
+      when "triangle"
+        current[:triangles] += 1
+      when "component"
+        current[:components] += 1
+      end
+    end
+
+    def finish_object(object)
+      object.merge(size: object[:maximum].zip(object[:minimum]).map do |maximum, minimum|
+        maximum && minimum && (maximum - minimum)
+      end)
+    end
+
+    def parts(archive)
+      document = metadata_document(archive)
+      return [] unless document
+
+      document.get_elements("config/object/part").map do |part|
+        metadata = part.get_elements("metadata").to_h { |entry| [entry.attributes["key"], entry.attributes["value"]] }
+        { id: part.attributes["id"], name: metadata["name"], extruder: integer_or_nil(metadata["extruder"]) }
+      end
+    end
+
+    def plates(archive)
+      document = metadata_document(archive)
+      return [] unless document
+
+      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"] }
+      end
+    end
+
+    def metadata_document(archive)
+      entry = archive.find_entry("Metadata/model_settings.config")
+      entry && REXML::Document.new(entry.get_input_stream.read)
+    end
+
+    def integer_or_nil(value) = value && Integer(value)
+  end
+end

data/lib/lithop/sampling_grid.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module Lithop
+  # Calculates the XY sampling grid, partial edge cells, and sampled margins.
+  class SamplingGrid
+    attr_reader :columns, :rows, :x_boundaries, :y_boundaries, :margin_samples
+
+    def initialize(width:, height:, pixel_size:, margins:, columns: nil, rows: nil)
+      @columns = columns || (width / pixel_size).ceil
+      @rows = rows || (height / pixel_size).ceil
+      @x_boundaries = boundaries(width, pixel_size, @columns, fitted: !columns.nil?).freeze
+      @y_boundaries = boundaries(height, pixel_size, @rows, fitted: !rows.nil?).freeze
+      x_size = width.fdiv(@columns)
+      y_size = height.fdiv(@rows)
+      @margin_samples = {
+        top: (margins.fetch(:top) / y_size).round,
+        right: (margins.fetch(:right) / x_size).round,
+        bottom: (margins.fetch(:bottom) / y_size).round,
+        left: (margins.fetch(:left) / x_size).round
+      }.freeze
+    end
+
+    def sample_width = columns + 1
+    def sample_height = rows + 1
+
+    def content_sample_size
+      [
+        sample_width - margin_samples.fetch(:left) - margin_samples.fetch(:right),
+        sample_height - margin_samples.fetch(:top) - margin_samples.fetch(:bottom)
+      ]
+    end
+
+    private
+
+    def boundaries(length, pixel_size, count, fitted:)
+      return Array.new(count + 1) { |index| (length * index.fdiv(count)).round(9) } if fitted
+
+      Array.new(count + 1) { |index| index == count ? length : [index * pixel_size, length].min }
+    end
+  end
+end