lithop 0.1.0

data/lib/lithop/calibration/target_svg.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+module Lithop
+  module Calibration
+    # Writes an editable SVG reference with the same patch layout as the calibration 3MF.
+    module TargetSVG
+      module_function
+
+      def write(path, target)
+        File.write(path, document(target))
+      end
+
+      def document(target)
+        patches = target.patches.to_h { |patch| [[patch.row, patch.column], patch] }
+        cells = Array.new(target.rows * target.columns) do |index|
+          row, column = index.divmod(target.columns)
+          patch = patches[[row, column]]
+          cell(target, row, column, patch)
+        end
+        dimensions = "width=\"#{number(target.width)}mm\" height=\"#{number(target.height)}mm\" " \
+                     "viewBox=\"0 0 #{number(target.width)} #{number(target.height)}\""
+
+        <<~SVG
+          <?xml version="1.0" encoding="UTF-8"?>
+          <svg xmlns="http://www.w3.org/2000/svg" #{dimensions}
+               role="img" aria-labelledby="title desc">
+            <title id="title">CMYW calibration target</title>
+            <desc id="desc">56 CMYW recipes, eight White thickness stages, and a right orientation column.</desc>
+            <rect width="#{number(target.width)}" height="#{number(target.height)}" fill="#fff"/>
+          #{cells.join}
+          </svg>
+        SVG
+      end
+
+      def cell(target, row, column, patch)
+        x0 = target.x_boundaries.fetch(column)
+        x1 = target.x_boundaries.fetch(column + 1)
+        y0 = target.y_boundaries.fetch(row)
+        y1 = target.y_boundaries.fetch(row + 1)
+        return orientation_cell(x0, y0, x1 - x0, y1 - y0, row) unless patch
+
+        fill = patch_color(patch)
+        text_fill = dark_color?(fill) ? "#fff" : "#111"
+        <<~SVG.lines.map { |line| "  #{line}" }.join
+          <g class="patch #{patch.kind}" id="#{patch.id}">
+            <rect x="#{number(x0)}" y="#{number(y0)}" width="#{number(x1 - x0)}" height="#{number(y1 - y0)}"
+                  fill="#{fill}" stroke="#777" stroke-width="0.2"/>
+            <text x="#{number((x0 + x1) / 2)}" y="#{number((y0 + y1) / 2)}" fill="#{text_fill}"
+                  font-family="monospace" font-size="3" text-anchor="middle" dominant-baseline="middle">#{patch.id}</text>
+          </g>
+        SVG
+      end
+
+      def orientation_cell(x, y, width, height, row)
+        label = row.zero? ? "TOP" : ""
+        <<~SVG.lines.map { |line| "  #{line}" }.join
+          <g class="patch orientation">
+            <rect x="#{number(x)}" y="#{number(y)}" width="#{number(width)}" height="#{number(height)}"
+                  fill="#fff" stroke="#777" stroke-width="0.2"/>
+            <text x="#{number(x + (width / 2))}" y="#{number(y + (height / 2))}" fill="#111"
+                  font-family="monospace" font-size="3" text-anchor="middle" dominant-baseline="middle">#{label}</text>
+          </g>
+        SVG
+      end
+
+      def patch_color(patch)
+        return recipe_color(patch.recipe) if patch.kind == :recipe
+
+        stage = patch.id.delete_prefix("W").to_i
+        value = (255 * (1.0 - stage.fdiv(Target::WHITE_STAGE_COUNT - 1))).round
+        format("#%<value>02X%<value>02X%<value>02X", value:)
+      end
+
+      def recipe_color(recipe)
+        channels = recipe.coverage_cmy.map { |component| ((1.0 - component) * 255).round }
+        format("#%<red>02X%<green>02X%<blue>02X", red: channels[0], green: channels[1], blue: channels[2])
+      end
+
+      def dark_color?(color)
+        red, green, blue = color.scan(/[0-9A-F]{2}/).map { |channel| channel.to_i(16) }
+        ((red * 299) + (green * 587) + (blue * 114)) < 128_000
+      end
+
+      def number(value)
+        format("%.6f", value).sub(/\.?0+\z/, "")
+      end
+    end
+  end
+end

data/lib/lithop/calibration/thickness_selector.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Lithop
+  module Calibration
+    # Maps White display density to the closest measured White thickness stage.
+    class ThicknessSelector
+      def initialize(profile:, settings:)
+        profile.validate_complete!
+        @settings = settings
+        @stages = profile.measurements(:white_thickness)
+        @brightest = @stages.map(&:luminance).max
+        @darkest = @stages.map(&:luminance).min
+        return unless @brightest == @darkest
+
+        raise InputError, "calibration White thickness measurements must span more than one luminance"
+      end
+
+      def call(densities)
+        densities.map { |density| thickness_for(density) }
+      end
+
+      private
+
+      def thickness_for(density)
+        unless density.is_a?(Numeric) && density.finite? && density.between?(0.0, 1.0)
+          raise InputError, "White density must be between 0 and 1"
+        end
+
+        target = @brightest - (density * (@brightest - @darkest))
+        stage = @stages.min_by { |candidate| (candidate.luminance - target).abs }
+        @settings.quantize_thickness(stage.height)
+      end
+    end
+  end
+end

data/lib/lithop/cli/calibration.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Lithop
+  # Handles calibration target generation and measured profile loading for the CLI.
+  module CLICalibration
+    CALIBRATION_SETTING_KEYS = %i[
+      minimum_thickness maximum_thickness first_layer_height layer_height nozzle_diameter
+      color_model color_layer_count pigment_order maximum_triangles
+    ].freeze
+
+    private
+
+    def calibrate(argv)
+      options = {}
+      parser = CLIOptions.calibration(options, @out)
+      arguments = parser.parse(argv)
+      raise OptionParser::InvalidArgument, arguments.join(" ") unless arguments.empty?
+
+      project_dir, settings, = load_settings(options, keys: CALIBRATION_SETTING_KEYS)
+      result = Calibration::Export.new(settings:, project_dir:).call
+      @out.puts "Generated #{result.patch_count} calibration patches and #{result.triangle_count} 3MF triangles"
+      @out.puts "in #{result.path}"
+      result.files.each { |file| @out.puts "  #{file}" }
+      0
+    rescue OptionParser::ParseError, Error, SystemCallError => e
+      @err.puts "lithop: #{e.message}"
+      1
+    end
+
+    def load_calibration_profile(path, settings)
+      return [nil, nil] unless path
+
+      expanded = File.expand_path(path, @cwd)
+      profile = Calibration::Profile.load(expanded)
+      profile.validate_for!(settings)
+      profile.validate_complete!
+      [profile, expanded]
+    end
+  end
+end

data/lib/lithop/cli/image_options.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module Lithop
+  # Adds dimensions, image placement, thickness, and sampling options.
+  module CLIImageOptions
+    module_function
+
+    def add(parser, options)
+      add_dimensions(parser, options)
+      add_margins(parser, options)
+      add_placement(parser, options)
+      add_thickness(parser, options)
+      add_sampling(parser, options)
+    end
+
+    def add_dimensions(parser, options)
+      parser.on("--layout-profile NAME", "Layout profile: standard") do |value|
+        options[:layout_profile] = value
+      end
+      parser.on("--width MM", Float, "Model width (default: 130)") { |value| options[:width] = value }
+      parser.on("--height MM", Float, "Model height (default: 100)") { |value| options[:height] = value }
+    end
+    private_class_method :add_dimensions
+
+    def add_margins(parser, options)
+      parser.on("--margin-top MM", Float, "Top margin (default: 0)") { |value| options[:margin_top] = value }
+      parser.on("--margin-right MM", Float, "Right margin (default: 0)") { |value| options[:margin_right] = value }
+      parser.on("--margin-bottom MM", Float, "Bottom margin (default: 0)") { |value| options[:margin_bottom] = value }
+      parser.on("--margin-left MM", Float, "Left margin (default: 0)") { |value| options[:margin_left] = value }
+    end
+    private_class_method :add_margins
+
+    def add_placement(parser, options)
+      parser.on("--image-fit MODE", "Image fit: cover/contain (default: cover)") do |value|
+        options[:image_fit] = value.downcase
+      end
+      parser.on("--crop-position-x FRACTION", Float, "Horizontal image position: 0..1 (default: 0.5)") do |value|
+        options[:crop_position_x] = value
+      end
+      parser.on("--crop-position-y FRACTION", Float, "Vertical image position: 0..1 (default: 0.5)") do |value|
+        options[:crop_position_y] = value
+      end
+      parser.on("--crop-scale FRACTION", Float, "Crop rectangle scale: >0..1 (default: 1)") do |value|
+        options[:crop_scale] = value
+      end
+    end
+    private_class_method :add_placement
+
+    def add_thickness(parser, options)
+      parser.on("--min-thickness MM", Float, "Requested minimum model thickness (default: 1.0)") do |value|
+        options[:minimum_thickness] = value
+      end
+      parser.on("--max-thickness MM", Float, "Requested maximum model thickness (default: 2.14689422)") do |value|
+        options[:maximum_thickness] = value
+      end
+    end
+    private_class_method :add_thickness
+
+    def add_sampling(parser, options)
+      parser.on("--pixel-size MM", Float, "XY pixel size (default: 0.22)") do |value|
+        options[:pixel_size] = value
+      end
+      parser.on("--color-pixel-size MM", Float, "Color-cell size >= pixel size (default: pixel size)") do |value|
+        options[:color_pixel_size] = value
+      end
+    end
+    private_class_method :add_sampling
+  end
+end

data/lib/lithop/cli/options.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+require "optparse"
+
+module Lithop
+  # Builds parsers for Lithop's generation and cleanup commands.
+  module CLIOptions
+    module_function
+
+    def generation(options, out)
+      OptionParser.new do |parser|
+        parser.banner = "Usage: lithop IMAGE [options]"
+        CLIImageOptions.add(parser, options)
+        add_print_settings(parser, options)
+        add_configuration(parser, options)
+        parser.on("--calibration-profile FILE", "Measured calibration profile JSON") do |value|
+          options[:calibration_profile] = value
+        end
+        add_information(parser, out)
+      end
+    end
+
+    def clean(options, out)
+      OptionParser.new do |parser|
+        parser.banner = "Usage: lithop clean [--project-dir DIR]"
+        parser.on("--project-dir DIR", "Project directory containing build/") do |value|
+          options[:project_dir] = value
+        end
+        parser.on("-h", "--help", "Print help") do
+          out.puts parser
+          exit 0
+        end
+      end
+    end
+
+    def calibration(options, out)
+      OptionParser.new do |parser|
+        parser.banner = "Usage: lithop calibrate [options]"
+        parser.on("--min-thickness MM", Float, "Requested minimum thickness (default: 1.0)") do |value|
+          options[:minimum_thickness] = value
+        end
+        parser.on("--max-thickness MM", Float, "Requested maximum thickness (default: 2.14689422)") do |value|
+          options[:maximum_thickness] = value
+        end
+        add_print_settings(parser, options)
+        add_configuration(parser, options)
+        add_information(parser, out)
+      end
+    end
+
+    def add_print_settings(parser, options)
+      parser.on("--first-layer-height MM", Float, "First layer height (default: 0.1)") do |value|
+        options[:first_layer_height] = value
+      end
+      parser.on("--layer-height MM", Float, "Layer height after first layer (default: 0.1)") do |value|
+        options[:layer_height] = value
+      end
+      parser.on("--nozzle-diameter MM", Float, "Nozzle diameter: 0.2/0.4 (default: 0.2)") do |value|
+        options[:nozzle_diameter] = value
+      end
+      parser.on("--color-model MODEL", "Color model (default: cmy)") do |value|
+        options[:color_model] = value.downcase
+      end
+      parser.on("--color-layer-count COUNT", Integer, "CMY/W color layers: 4/5/7 (default: 7)") do |value|
+        options[:color_layer_count] = value
+      end
+      parser.on("--pigment-order LIST", "Pigment order, e.g. cyan,magenta,yellow") do |value|
+        options[:pigment_order] = value
+      end
+    end
+    private_class_method :add_print_settings
+
+    def add_configuration(parser, options)
+      parser.on("--config FILE", "Input settings JSON (default: PROJECT/config/settings.json)") do |value|
+        options[:settings_file] = value
+      end
+      parser.on("--project-dir DIR", "Project directory containing config/ and build/") do |value|
+        options[:project_dir] = value
+      end
+    end
+    private_class_method :add_configuration
+
+    def add_information(parser, out)
+      parser.on("-v", "--version", "Print version") do
+        out.puts Lithop::VERSION
+        exit 0
+      end
+      parser.on("-h", "--help", "Print help") do
+        out.puts parser
+        exit 0
+      end
+    end
+    private_class_method :add_information
+  end
+end

data/lib/lithop/cli/settings.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Lithop
+  # Resolves project paths and merges CLI, JSON, and default generation settings.
+  class CLISettings
+    Result = Data.define(:project_dir, :settings, :input_settings_path)
+
+    def initialize(cwd:)
+      @cwd = File.expand_path(cwd)
+    end
+
+    def call(options, keys: nil)
+      values = options.dup
+      project_dir = File.expand_path(values.delete(:project_dir) || @cwd, @cwd)
+      explicit_settings_file = values.delete(:settings_file)
+      input_settings_path = settings_path(project_dir, explicit_settings_file)
+      file_settings = SettingsFile.load(input_settings_path, required: !explicit_settings_file.nil?)
+      configured = keys ? file_settings.values.slice(*keys) : file_settings.values
+      Result.new(
+        project_dir:,
+        settings: Settings.new(**configured, **values),
+        input_settings_path: file_settings.path
+      )
+    end
+
+    private
+
+    def settings_path(project_dir, explicit_settings_file)
+      return File.expand_path(explicit_settings_file, @cwd) if explicit_settings_file
+
+      File.join(project_dir, SettingsFile::DEFAULT_PATH)
+    end
+  end
+end

data/lib/lithop/cli.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+require "optparse"
+require "fileutils"
+
+module Lithop
+  # Command-line interface for generating and cleaning lithophane projects.
+  class CLI
+    include CLICalibration
+
+    def self.run(argv, out: $stdout, err: $stderr, cwd: Dir.pwd)
+      new(out:, err:, cwd:).run(argv)
+    end
+
+    def initialize(out:, err:, cwd:)
+      @out = out
+      @err = err
+      @cwd = File.expand_path(cwd)
+    end
+
+    def run(argv)
+      return clean(argv.drop(1)) if argv.first == "clean"
+      return calibrate(argv.drop(1)) if argv.first == "calibrate"
+
+      options = {}
+      parser = CLIOptions.generation(options, @out)
+      arguments = parser.parse(argv)
+      if arguments.length != 1
+        @err.puts parser
+        return 1
+      end
+
+      input = File.expand_path(arguments.first, @cwd)
+      raise InputError, "input file does not exist: #{input}" unless File.file?(input)
+
+      calibration_profile_path = options.delete(:calibration_profile)
+      project_dir, settings, settings_path = load_settings(options)
+      calibration_profile, calibration_profile_path = load_calibration_profile(calibration_profile_path, settings)
+      if calibration_profile
+        calibration = Export::CalibrationInput.new(profile: calibration_profile, path: calibration_profile_path)
+      end
+      result = Export.new(
+        settings:,
+        project_dir:,
+        input_settings_path: settings_path,
+        calibration:,
+        progress: method(:report_estimate)
+      ).call(input)
+      @out.puts "Generated #{result.triangle_count} STL and #{result.three_mf_triangle_count} CMYW 3MF triangles"
+      @out.puts "in #{result.path}"
+      result.files.each { |file| @out.puts "  #{file}" }
+      0
+    rescue OptionParser::ParseError, Error, SystemCallError => e
+      @err.puts "lithop: #{e.message}"
+      1
+    end
+
+    private
+
+    def report_estimate(estimate)
+      @out.puts(
+        "Estimated #{estimate.stl_triangle_count} STL and " \
+        "#{estimate.three_mf_triangle_count} CMYW 3MF triangles before writing"
+      )
+      counts = estimate.triangle_counts_by_material.map { |material, count| "#{material}=#{count}" }.join(", ")
+      @out.puts "  CMYW by material: #{counts}"
+    end
+
+    def load_settings(options, keys: nil)
+      resolved = CLISettings.new(cwd: @cwd).call(options, keys:)
+      [resolved.project_dir, resolved.settings, resolved.input_settings_path]
+    end
+
+    def clean(argv)
+      options = {}
+      parser = CLIOptions.clean(options, @out)
+      arguments = parser.parse(argv)
+      raise OptionParser::InvalidArgument, arguments.join(" ") unless arguments.empty?
+
+      project_dir = File.expand_path(options.fetch(:project_dir, @cwd), @cwd)
+      validate_clean_target!(project_dir)
+      build_dir = File.join(project_dir, "build")
+      return report_missing_build(build_dir) unless File.exist?(build_dir) || File.symlink?(build_dir)
+
+      raise Error, "refusing to remove a symbolic link: #{build_dir}" if File.symlink?(build_dir)
+      raise Error, "build path is not a directory: #{build_dir}" unless File.directory?(build_dir)
+
+      FileUtils.rm_r(build_dir)
+      @out.puts "Removed #{build_dir}"
+      0
+    rescue OptionParser::ParseError, Error, SystemCallError => e
+      @err.puts "lithop: #{e.message}"
+      1
+    end
+
+    def validate_clean_target!(project_dir)
+      raise Error, "refusing to clean the filesystem root" if project_dir == File::SEPARATOR
+    end
+
+    def report_missing_build(build_dir) = 0.tap { @out.puts "No build directory: #{build_dir}" }
+  end
+end

data/lib/lithop/export/calibration.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module Lithop
+  # Selects recipes and thicknesses for an optional measured calibration profile.
+  class ExportCalibration
+    attr_reader :profile, :path
+
+    def initialize(settings:, input:)
+      @settings = settings
+      @profile = input&.profile
+      @path = input&.path
+    end
+
+    def heights(densities)
+      return Thickness.continuous_from_density(densities, @settings) unless profile
+
+      Calibration::ThicknessSelector.new(profile:, settings: @settings).call(densities)
+    end
+
+    def palette
+      palette = Palette.new(
+        layer_count: @settings.color_layer_count,
+        pigment_order: @settings.pigment_order
+      )
+      return palette unless profile
+
+      Calibration::RecipeSelector.new(profile:, palette:)
+    end
+
+    def write(directory)
+      profile&.write(File.join(directory, "calibration-profile.json"))
+    end
+
+    def metadata
+      return "uncalibrated" unless profile
+
+      {
+        status: "measured",
+        profile_id: profile.profile_id,
+        source_path: path,
+        recipe_method: "nearest_normalized_transmitted_srgb",
+        thickness_method: "nearest_measured_white_luminance"
+      }
+    end
+  end
+end

data/lib/lithop/export/color_metadata.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+module Lithop
+  # Builds the color-model portion of an export manifest.
+  class ExportColorMetadata
+    def initialize(settings:, calibration:)
+      @settings = settings
+      @calibration = calibration
+    end
+
+    # rubocop:disable-next Metrics/MethodLength
+    def call(artifacts)
+      {
+        file: artifacts.three_mf_name,
+        format: "3MF",
+        property: "3MF color group and Bambu Studio part extruder assignments",
+        calibration: @calibration.metadata,
+        calibration_profile_id: @calibration.profile&.profile_id,
+        id: @settings.color_model,
+        color_layer_count: @settings.color_layer_count,
+        pigment_order: @settings.pigment_order,
+        color_layer_sequence: [*@settings.pigment_order, :white],
+        layout_profile: @settings.layout_profile,
+        base_white_layers: @settings.base_white_layers,
+        minimum_top_white_layers: @settings.minimum_top_white_layers,
+        thickness_mm: thickness_structure,
+        physical_material_layers_encoded: true,
+        bambu_studio_material_assignments_encoded: true,
+        pigments: Palette::PIGMENTS,
+        subtractive_mixes: Palette::SUBTRACTIVE_MIXES,
+        luminance_control: {
+          material: "White",
+          method: luminance_method
+        },
+        preview: {
+          method: "nominal_recipe_color_with_relative_thickness",
+          colorimetric: false,
+          source: "same_material_model_as_3mf",
+          calibration_profile_id: @calibration.profile&.profile_id
+        },
+        material_count: artifacts.three_mf.material_count,
+        object_count: artifacts.three_mf.object_count,
+        used_materials: material_names(used_materials(artifacts)),
+        unused_materials: material_names(Palette::MATERIALS - used_materials(artifacts)),
+        triangle_counts_by_material: artifacts.three_mf.triangle_counts_by_material,
+        recipe_counts: artifacts.material_model.recipe_counts,
+        recipe_summaries: artifacts.material_model.recipe_summaries
+      }
+    end
+
+    private
+
+    def thickness_structure
+      structure = @settings.layer_structure
+      {
+        base_white: structure.base_white_thickness,
+        color_region: structure.color_region_thickness,
+        minimum_top_white: structure.minimum_top_white_thickness,
+        top_layer_height: structure.top_layer_height,
+        minimum_total: structure.minimum_physical_thickness,
+        effective_minimum: @settings.effective_minimum_thickness,
+        effective_maximum: @settings.effective_maximum_thickness
+      }
+    end
+
+    def used_materials(artifacts)
+      Palette::MATERIALS.select { |material| artifacts.material_model.materials.include?(material) }
+    end
+
+    def luminance_method
+      return "measured_white_luminance" if @calibration.profile
+
+      "normalized_material_display_density_or_rec601_luminance_continuous"
+    end
+
+    def material_names(materials)
+      materials.map { |material| material.to_s.capitalize }
+    end
+  end
+end