lithop 0.1.0 → 0.3.0

data/lib/lithop/export/job.rb

@@ -15,35 +15,49 @@ module Lithop
     # rubocop:disable-next Metrics/ParameterLists
     def initialize(
       settings:, project_dir:, input_settings_path: nil, calibration: nil, progress: nil,
-      instrumentation: nil, clock: Time, random: SecureRandom
+      job_progress: nil, instrumentation: nil, clock: Time, random: SecureRandom, job_id: nil
     )
       @settings = settings
       @project_dir = File.expand_path(project_dir)
       @input_settings_path = input_settings_path
       @calibration = calibration
       @progress = progress
+      @job_progress = job_progress
       @clock = clock
       @random = random
-      @generation = ExportGeneration.new(
-        settings:, input_settings_path:, calibration:, progress:, instrumentation:
-      )
+      @instrumentation = instrumentation
+      @job_id = job_id
     end
 
     def call(input_path)
       source = File.expand_path(input_path)
-      job_id = "#{@clock.now.utc.strftime("%Y%m%dT%H%M%SZ")}-#{@random.hex(4)}"
-      destination, result = JobDirectory.new(project_dir: @project_dir, job_id:).call do |directory|
-        @generation.call(source:, directory:, job_id:)
-      end
-      Result.new(
-        job_id:,
-        path: destination,
-        files: result.files,
-        triangle_count: result.triangle_count,
-        three_mf_triangle_count: result.three_mf_triangle_count,
-        material_count: result.material_count,
-        object_count: result.object_count
+      job_id = @job_id || "#{@clock.now.utc.strftime("%Y%m%dT%H%M%SZ")}-#{@random.hex(4)}"
+      execution = JobExecution.new(
+        project_dir: @project_dir, job_id:, progress: @job_progress, clock: @clock
       )
+      execution.call do |job|
+        generation = ExportGeneration.new(
+          settings: @settings,
+          input_settings_path: @input_settings_path,
+          calibration: @calibration,
+          progress: @progress,
+          job_progress: job.method(:progress),
+          instrumentation: @instrumentation
+        )
+        destination, generated = JobDirectory.new(project_dir: @project_dir, job_id:).call do |directory|
+          generation.call(source:, directory:, job_id:).tap { job.checkpoint! }
+        end
+        job.publication_committed!
+        Result.new(
+          job_id:,
+          path: destination,
+          files: generated.files,
+          triangle_count: generated.triangle_count,
+          three_mf_triangle_count: generated.three_mf_triangle_count,
+          material_count: generated.material_count,
+          object_count: generated.object_count
+        )
+      end
     end
   end
 end

data/lib/lithop/export/metadata.rb

@@ -5,6 +5,7 @@ require "json"
 
 module Lithop
   # Builds and writes the resolved settings and export manifest.
+  # rubocop:disable-next Metrics/ClassLength
   class ExportMetadata
     def initialize(settings:, input_settings_path:, calibration:)
       @settings = settings
@@ -29,8 +30,8 @@ module Lithop
 
     private
 
+    # rubocop:disable-next Metrics/MethodLength
     def manifest_for(source, job_id, artifacts)
-      materials = material_names(used_materials(artifacts))
       {
         schema_version: 1,
         job_id:,
@@ -49,9 +50,21 @@ module Lithop
         },
         input_sha256: Digest::SHA256.file(source).hexdigest,
         filament_profile: FilamentProfile.default.to_h,
+        tile_layout: tile_layout_metadata(artifacts),
+        tiles: tile_metadata(artifacts),
         parts: [
           { file: artifacts.stl_name, material: "White", role: "monochrome_reference" },
-          { file: artifacts.three_mf_name, materials:, role: "cmyw_lithophane" }
+          *artifacts.tile_artifacts.map do |artifact|
+            tile_materials = Palette::MATERIALS.select do |material|
+              artifact.material_model.materials.include?(material)
+            end
+            {
+              file: artifact.name,
+              tile_id: artifact.tile.id,
+              materials: material_names(tile_materials),
+              role: artifacts.tile_artifacts.one? ? "cmyw_lithophane" : "cmyw_lithophane_tile"
+            }
+          end
         ],
         color_model: @color_metadata.call(artifacts),
         files: artifact_files(artifacts),
@@ -62,14 +75,51 @@ module Lithop
 
     def artifact_files(artifacts)
       files = [
-        artifacts.stl_name, artifacts.three_mf_name, "settings.json", "manifest.json",
-        "preview.png", "transmission.png", "thickness.png",
+        artifacts.stl_name, *artifacts.three_mf_names, "settings.json", "manifest.json",
+        "corrected-input.png", "preview.png", "transmission.png", "thickness.png",
         *Palette::MATERIALS.map { |material| "#{material}-mask.png" }, "PRINT_README.md"
       ]
+      if artifacts.tile_artifacts.length > 1
+        files.concat(artifacts.tile_artifacts.map { |artifact| ExportPreviews.tile_preview_name(artifact) })
+        files << "tile-layout.svg"
+      end
       files << "calibration-profile.json" if @calibration.profile
       files
     end
 
+    def tile_layout_metadata(artifacts)
+      {
+        requested: @settings.tile_layout,
+        tile_count: @settings.tile_count,
+        rows: artifacts.tile_layout.rows,
+        columns: artifacts.tile_layout.columns,
+        order: "left_to_right_then_top_to_bottom",
+        local_origin: "xy_min",
+        assembled_image_top: "+Y"
+      }
+    end
+
+    def tile_metadata(artifacts)
+      artifacts.tile_artifacts.map do |artifact|
+        tile = artifact.tile
+        used = Palette::MATERIALS.select { |material| artifact.material_model.materials.include?(material) }
+        metadata = {
+          id: tile.id,
+          file: artifact.name,
+          row: tile.row,
+          column: tile.column,
+          offset_mm: tile.offset,
+          bounds_mm: tile.bounds,
+          dimensions_mm: { width: tile.width, height: tile.height, depth: @settings.effective_maximum_thickness },
+          materials: material_names(used),
+          unused_materials: material_names(Palette::MATERIALS - used),
+          triangle_count: artifact.three_mf.triangle_count
+        }
+        metadata[:preview_file] = ExportPreviews.tile_preview_name(artifact) unless artifacts.tile_artifacts.one?
+        metadata
+      end
+    end
+
     def used_materials(artifacts)
       Palette::MATERIALS.select { |material| artifacts.material_model.materials.include?(material) }
     end

data/lib/lithop/export/planning.rb

@@ -1,6 +1,103 @@
 # frozen_string_literal: true
 
 module Lithop
+  # Splits the reference White carrier and CMY pigments into closed Z-region parts.
+  class ZSeparatedMaterialMeshPlan
+    Entry = Data.define(:material, :geometry, :name, :region, :build_z_offset)
+
+    def initialize(model:, base_geometry:, top_geometry:, settings:, maximum_triangles:, limit_message:)
+      @model = model
+      @base_geometry = base_geometry
+      @top_geometry = top_geometry
+      @settings = settings
+      @maximum_triangles = maximum_triangles
+      @limit_message = limit_message
+    end
+
+    def call
+      entries = build_entries
+      entry_counts = entries.map { |entry| triangle_count(entry.geometry) }
+      total = entry_counts.sum
+      raise ConfigurationError, @limit_message.call(total) if total > @maximum_triangles
+
+      MaterialMeshPlan::Result.new(
+        parts: entries.map do |entry|
+          ThreeMF::Part.new(
+            material: entry.material, triangles: triangle_source(entry.geometry),
+            name: entry.name, region: entry.region, build_z_offset: entry.build_z_offset
+          )
+        end,
+        triangle_count: total,
+        triangle_counts_by_material: counts_by_material(entries, entry_counts)
+      )
+    end
+
+    private
+
+    def build_entries
+      entries = []
+      color_ranges.each_with_index do |range, index|
+        region_model = LayerRegionModel.new(model: @model, layer_range: range)
+        region = "color_region_#{index + 1}"
+        build_z_offset = @settings.layer_structure.base_white_thickness - region_model.z_boundaries.first
+        entries << Entry.new(
+          material: :white, geometry: @base_geometry, name: "Color region #{index + 1} Base White",
+          region:, build_z_offset: 0.0
+        )
+        entries << Entry.new(
+          material: :white,
+          geometry: color_region_white_geometry(region_model),
+          name: "Color region #{index + 1} White",
+          region:,
+          build_z_offset:
+        )
+        Palette::PIGMENTS.each do |material|
+          next unless region_model.materials.include?(material)
+
+          entries << Entry.new(
+            material:,
+            geometry: ColumnGeometry.new(model: region_model, material:),
+            name: "Color region #{index + 1} #{material.to_s.capitalize}",
+            region:,
+            build_z_offset:
+          )
+        end
+      end
+      entries << Entry.new(
+        material: :white, geometry: @top_geometry, name: "Top White",
+        region: "top_white", build_z_offset: -@settings.layer_structure.color_region_end
+      )
+      entries
+    end
+
+    def color_ranges
+      @settings.layer_structure.color_region_layer_ranges(@settings.color_region_parts)
+    end
+
+    def color_region_white_geometry(model)
+      BoxGeometry.new(
+        width: model.x_boundaries.last,
+        height: model.y_boundaries.last,
+        z_min: model.z_boundaries.first,
+        z_max: model.z_boundaries.last
+      )
+    end
+
+    def triangle_count(geometry)
+      geometry.respond_to?(:triangle_count) ? geometry.triangle_count : geometry.each_triangle.count
+    end
+
+    def triangle_source(geometry)
+      geometry.is_a?(ColumnGeometry) ? geometry : geometry.each_triangle
+    end
+
+    def counts_by_material(entries, entry_counts)
+      entries.zip(entry_counts).each_with_object(Hash.new(0)) do |(entry, count), totals|
+        totals[entry.material] += count
+      end.freeze
+    end
+  end
+
   # Builds the reference-style overlapping White height field and contiguous CMY columns.
   class ReferenceMaterialMeshPlan
     def initialize(model:, white_geometry:, maximum_triangles:, limit_message:)

data/lib/lithop/export/previews.rb

@@ -5,7 +5,7 @@ module Lithop
   module ExportPreviews
     module_function
 
-    def write(directory, model:, settings:, white_heights: nil)
+    def write(directory, model:, settings:, white_heights: nil, corrected_input: nil)
       heights = white_heights && cell_heights(white_heights, settings.columns, settings.rows)
       options = {
         model:,
@@ -19,8 +19,32 @@ module Lithop
       Palette::MATERIALS.each do |material|
         Preview.write_mask(File.join(directory, "#{material}-mask.png"), model:, material:)
       end
+      File.binwrite(File.join(directory, "corrected-input.png"), corrected_input) if corrected_input
     end
 
+    def write_tiles(directory, tile_artifacts:, settings:, white_heights:)
+      return if tile_artifacts.one?
+
+      heights = cell_heights(white_heights, settings.columns, settings.rows)
+      tile_artifacts.each do |artifact|
+        tile = artifact.tile
+        tile_heights = (tile.row_start...tile.row_end).flat_map do |row|
+          offset = (row * settings.columns) + tile.column_start
+          heights.slice(offset, artifact.material_model.columns)
+        end
+        Preview.write_material(
+          File.join(directory, tile_preview_name(artifact)),
+          model: artifact.material_model,
+          minimum: settings.effective_minimum_thickness,
+          maximum: settings.effective_maximum_thickness,
+          heights: tile_heights,
+          transmission_gamma: 0.5
+        )
+      end
+    end
+
+    def tile_preview_name(artifact) = artifact.name.sub(/\.3mf\z/, "-preview.png")
+
     def cell_heights(vertex_heights, columns, rows)
       stride = columns + 1
       Array.new(columns * rows) do |index|

data/lib/lithop/export/print_readme.rb

@@ -5,7 +5,10 @@ module Lithop
   module PrintReadme
     module_function
 
-    def write(path, settings:, material_model:, calibration_profile: nil, profile: FilamentProfile.default)
+    def write(
+      path, settings:, material_model:, tile_artifacts:, calibration_profile: nil,
+      profile: FilamentProfile.default
+    )
       materials = Palette::MATERIALS.select { |material| material_model.materials.include?(material) }
       names = materials.map { |material| profile_material(profile, material).name }
       assignments = materials.map do |material|
@@ -18,14 +21,15 @@ module Lithop
         This is #{calibration_profile ? "a measured-profile calibrated" : "an uncalibrated"} CMYW lithophane
         generated in millimetres.
 
-        - Open `lithop.3mf` for the physical color model; it contains: #{names.join(", ")}.
+        - #{model_instruction(tile_artifacts, names)}
         #{calibration_line(calibration_profile)}
         - Bambu Studio assignments encoded for this job: #{assignments.join(", ")}.
         - The model uses #{settings.color_layer_count} CMY/W color layers #{base_layer_description(settings)}.
         - The backlight-to-view color-layer order is #{settings.pigment_order.map(&:capitalize).join(" -> ")} -> White.
         - White thickness above the color region follows #{thickness_method(settings, calibration_profile)}.
+        #{z_part_line(settings)}
         - `preview.png` shows nominal recipe colors with relative thickness shading; it is not a colorimetric prediction.
-        - `transmission.png`, `thickness.png`, and the four material masks use the same cells as `lithop.3mf`.
+        - `transmission.png`, `thickness.png`, and the four material masks use the same cells as the 3MF output.
         - `cmyk_white.stl` is a separate monochrome reference model, not the color model.
         - Product: #{profile.product_url}
         - Guide: #{profile.reference_url}
@@ -38,6 +42,20 @@ module Lithop
       MARKDOWN
     end
 
+    def model_instruction(tile_artifacts, names)
+      return "Open `lithop.3mf` for the physical color model; it contains: #{names.join(", ")}." if tile_artifacts.one?
+
+      "Open the #{tile_artifacts.length} 3MF files under `tiles/` and assemble them using " \
+        "`tile-layout.svg` and `manifest.json`; together they contain: #{names.join(", ")}."
+    end
+
+    def z_part_line(settings)
+      return "- Z regions remain combined into the material parts." unless settings.separate_z_parts
+
+      "- Z regions use #{settings.color_region_parts + 1} plates: each CMYW color region includes " \
+        "a Base White carrier, followed by Top White; every plate starts at Z=0."
+    end
+
     def profile_material(profile, material)
       profile.materials.find { |candidate| candidate.channel == material }
     end
@@ -63,7 +81,7 @@ module Lithop
       "- Use a #{settings.nozzle_diameter} mm nozzle, #{settings.first_layer_height} mm base layers,\n  " \
         "#{settings.layer_height} mm color layers, and #{upper_height} mm upper White layers."
     end
-    private_class_method :profile_material, :calibration_line, :thickness_method,
+    private_class_method :model_instruction, :z_part_line, :profile_material, :calibration_line, :thickness_method,
                          :base_layer_description, :layer_height_description
   end
 end

data/lib/lithop/export/result.rb

@@ -1,13 +1,35 @@
 # frozen_string_literal: true
 
 module Lithop
+  TileArtifact = Data.define(:tile, :name, :three_mf, :material_model)
+
   ExportArtifacts = Data.define(
     :stl_name,
-    :three_mf_name,
+    :tile_artifacts,
     :stl_triangle_count,
-    :three_mf,
-    :material_model
-  )
+    :material_model,
+    :tile_layout
+  ) do
+    def three_mf_names = tile_artifacts.map(&:name)
+
+    def three_mf_name
+      three_mf_names.fetch(0) if three_mf_names.one?
+    end
+
+    def three_mf
+      results = tile_artifacts.map(&:three_mf)
+      counts = results.each_with_object(Hash.new(0)) do |result, totals|
+        result.triangle_counts_by_material.each { |material, count| totals[material] += count }
+      end
+      ThreeMF::Result.new(
+        vertex_count: results.sum(&:vertex_count),
+        triangle_count: results.sum(&:triangle_count),
+        material_count: counts.length,
+        object_count: results.sum(&:object_count),
+        triangle_counts_by_material: counts.freeze
+      )
+    end
+  end
 
   ExportResult = Data.define(
     :job_id,

data/lib/lithop/formats/three_mf/bambu_metadata.rb

@@ -4,14 +4,14 @@ require "json"
 
 module Lithop
   # Writes Bambu Studio material-assignment metadata into a 3MF package.
+  # rubocop:disable-next Metrics/ClassLength
   class ThreeMFBambuMetadata
     PATH = "Metadata/model_settings.config"
-    FIRST_MODEL_OBJECT_INDEX = 1
 
-    def initialize(archive:, assembly_id:, object_ids:, parts:, profile:, settings: nil)
+    def initialize(archive:, object_ids:, assemblies:, parts:, profile:, settings: nil)
       @archive = archive
-      @assembly_id = assembly_id
       @object_ids = object_ids
+      @assemblies = assemblies
       @parts = parts
       @profile = profile
       @settings = settings
@@ -20,61 +20,148 @@ module Lithop
     def write
       @archive.put_next_entry(PATH)
       @archive.write("<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<config>\n")
-      @archive.write("  <object id=\"#{@assembly_id}\">\n")
-      @archive.write("    <metadata key=\"name\" value=\"Lithop CMYW lithophane\"/>\n")
+      @assemblies.each { |assembly| write_object(assembly) }
       if bambu_project?
-        @archive.write("    <metadata key=\"extruder\" value=\"1\"/>\n")
+        write_plates
+        write_assemble if separate_z_plates?
+      end
+      @archive.write("</config>\n")
+      write_project_entries if bambu_project?
+    end
+
+    private
+
+    def write_object(assembly)
+      @archive.write("  <object id=\"#{assembly.id}\">\n")
+      @archive.write("    <metadata key=\"name\" value=\"#{assembly.name}\"/>\n")
+      if bambu_project?
+        @archive.write("    <metadata key=\"extruder\" value=\"#{root_extruder(assembly)}\"/>\n")
         @archive.write("    <metadata key=\"layer_height\" value=\"#{@settings.layer_height}\"/>\n")
         @archive.write("    <metadata key=\"sparse_infill_density\" value=\"100%\"/>\n")
         @archive.write("    <metadata key=\"sparse_infill_pattern\" value=\"zig-zag\"/>\n")
       end
-      @object_ids.zip(@parts).each do |object_id, part|
-        write_part(object_id, part.material)
+      part_map = @object_ids.zip(@parts).to_h
+      assembly.object_ids.each_with_index do |object_id, volume_id|
+        part = part_map.fetch(object_id)
+        write_part(object_id, part, assembly, volume_id)
       end
       @archive.write("  </object>\n")
-      write_plate if bambu_project?
-      @archive.write("</config>\n")
-      write_project_entries if bambu_project?
     end
 
-    private
+    def root_extruder(assembly)
+      return 1 if @assemblies.one?
+
+      part_map = @object_ids.zip(@parts).to_h
+      material = part_map.fetch(assembly.object_ids.first).material
+      @profile.materials.index { |candidate| candidate.channel == material } + 1
+    end
 
-    def write_part(object_id, material)
+    def write_part(object_id, part, assembly, volume_id)
+      material = part.material
       profile_material = @profile.materials.find { |candidate| candidate.channel == material }
       extruder = @profile.materials.index(profile_material) + 1
-      @archive.write("    <part id=\"#{object_id}\" subtype=\"normal_part\">\n")
-      @archive.write("      <metadata key=\"name\" value=\"#{profile_material.name}\"/>\n")
+      uuid = separate_z_plates? ? %( uuid="#{part_uuid(object_id)}") : ""
+      @archive.write("    <part id=\"#{object_id}\" subtype=\"normal_part\"#{uuid}>\n")
+      @archive.write("      <metadata key=\"name\" value=\"#{part.name || profile_material.name}\"/>\n")
+      if separate_z_plates?
+        origin = assembly.component_origins.fetch(object_id)
+        @archive.write("      <metadata key=\"matrix\" value=\"#{matrix(origin)}\"/>\n")
+        @archive.write("      <metadata key=\"source_file\" value=\"lithop.3mf\"/>\n")
+        @archive.write("      <metadata key=\"source_object_id\" value=\"#{source_object_id(assembly)}\"/>\n")
+        @archive.write("      <metadata key=\"source_volume_id\" value=\"#{volume_id}\"/>\n")
+        @archive.write("      <metadata key=\"source_offset_x\" value=\"#{number(origin[0])}\"/>\n")
+        @archive.write("      <metadata key=\"source_offset_y\" value=\"#{number(origin[1])}\"/>\n")
+        source_z = number(origin[2] - part.build_z_offset)
+        @archive.write("      <metadata key=\"source_offset_z\" value=\"#{source_z}\"/>\n")
+      end
       @archive.write("      <metadata key=\"extruder\" value=\"#{extruder}\"/>\n")
       @archive.write("    </part>\n")
     end
 
     def bambu_project? = @settings&.bambu_project
 
-    def write_plate
-      @archive.write(<<~XML)
+    def part_uuid(object_id)
+      format("%08x-7f79-4c88-9311-43ae0fc671e7", object_id)
+    end
+
+    def write_plates
+      @assemblies.each_with_index { |assembly, index| write_plate(assembly, index + 1) }
+    end
+
+    def write_plate(assembly, plate_id)
+      name = @assemblies.one? ? "lithophane" : assembly.name
+      @archive.write(<<~XML.chomp)
         <plate>
-          <metadata key="plater_id" value="1"/>
-          <metadata key="plater_name" value="lithophane"/>
+          <metadata key="plater_id" value="#{plate_id}"/>
+          <metadata key="plater_name" value="#{name}"/>
           <metadata key="locked" value="false"/>
           <model_instance>
-            <metadata key="object_id" value="#{@assembly_id}"/>
+            <metadata key="object_id" value="#{assembly.id}"/>
             <metadata key="instance_id" value="0"/>
-          </model_instance>
-        </plate>
       XML
+      @archive.write("\n    <metadata key=\"identify_id\" value=\"#{identify_id(plate_id)}\"/>") if separate_z_plates?
+      @archive.write("\n  </model_instance>\n</plate>\n")
+    end
+
+    def write_assemble
+      @archive.write("<assemble>\n")
+      @assemblies.each do |assembly|
+        @archive.write(
+          "  <assemble_item object_id=\"#{assembly.id}\" instance_id=\"0\" " \
+          "transform=\"1 0 0 0 1 0 0 0 1 0 0 0\" offset=\"0 0 0\"/>\n"
+        )
+        assembly.object_ids.each_with_index do |object_id, volume_id|
+          transform = volume_transform(assembly.component_origins.fetch(object_id))
+          @archive.write(
+            "  <assemble_item object_id=\"#{assembly.id}\" volume_id=\"#{volume_id}\" " \
+            "transform=\"#{transform}\"/>\n"
+          )
+        end
+      end
+      @archive.write("</assemble>\n")
+    end
+
+    def separate_z_plates? = @settings&.separate_z_parts && @assemblies.length > 1
+
+    def identify_id(plate_id)
+      [218, 253, 276, 287].fetch(plate_id - 1, 287 + (plate_id * 32))
+    end
+
+    def volume_transform(origin)
+      "1 0 0 0 1 0 0 0 1 #{origin.map { |value| number(value) }.join(" ")}"
+    end
+
+    def matrix(origin)
+      "1 0 0 #{number(origin[0])} 0 1 0 #{number(origin[1])} 0 0 1 #{number(origin[2])} 0 0 0 1"
+    end
+
+    def source_object_id(assembly)
+      return 3 if assembly.region == "top_white"
+
+      assembly.region.delete_prefix("color_region_").to_i - 1
     end
 
+    def number(value) = format("%.9g", value)
+
     def write_project_entries
       write_entry("Metadata/layer_config_ranges.xml", layer_ranges_xml)
       write_entry("Metadata/project_settings.config", "#{JSON.pretty_generate(project_settings)}\n")
     end
 
     def layer_ranges_xml
+      object_id = @assemblies.length
+      min_z = @settings.top_white_start
+      max_z = @settings.maximum_thickness
+      if @settings.separate_z_parts
+        color_end = @settings.layer_structure.color_region_end
+        min_z = (min_z - color_end).round(9)
+        max_z = (max_z - color_end).round(9)
+      end
       <<~XML
         <?xml version="1.0" encoding="utf-8"?>
         <objects>
-          <object id="#{FIRST_MODEL_OBJECT_INDEX}">
-            <range min_z="#{@settings.top_white_start}" max_z="#{@settings.maximum_thickness}">
+          <object id="#{object_id}">
+            <range min_z="#{min_z}" max_z="#{max_z}">
               <option opt_key="extruder">4</option>
               <option opt_key="layer_height">#{@settings.top_layer_height}</option>
             </range>