lithop 0.2.0 → 0.4.0

data/lib/lithop/export/planning.rb

@@ -1,13 +1,33 @@
 # frozen_string_literal: true
 
 module Lithop
-  # Splits the reference White carrier and CMY pigments into closed Z-region parts.
+  # Shared mesh counting and conversion helpers for export plans.
+  module MaterialMeshPlanningHelpers
+    private
+
+    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
+
+  # Slices the CMYW model into contiguous plates over strength-adjusted White supports.
   class ZSeparatedMaterialMeshPlan
+    include MaterialMeshPlanningHelpers
+
     Entry = Data.define(:material, :geometry, :name, :region, :build_z_offset)
 
-    def initialize(model:, base_geometry:, top_geometry:, settings:, maximum_triangles:, limit_message:)
+    def initialize(model:, top_geometry:, settings:, maximum_triangles:, limit_message:)
       @model = model
-      @base_geometry = base_geometry
       @top_geometry = top_geometry
       @settings = settings
       @maximum_triangles = maximum_triangles
@@ -36,42 +56,73 @@ module Lithop
 
     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
-        )
+      plate_ranges.each_with_index do |plate_range, index|
+        region = "z_part_#{index + 1}"
+        source_z_min = plate_range.begin
+        build_z_offset = @settings.z_part_base_white_thickness(index) - source_z_min
+        append_base_white_entry(entries, index:, region:)
+        append_color_entries(entries, index:, region:, build_z_offset:)
+        append_top_white_entry(entries, index:, plate_range:, region:, build_z_offset:)
+      end
+      entries
+    end
+
+    def append_base_white_entry(entries, index:, region:)
+      range = 0.0...@settings.z_part_base_white_thickness(index)
+      entries << Entry.new(
+        material: :white, geometry: box_geometry(range),
+        name: "Z plate #{index + 1} Base White", region:, build_z_offset: 0.0
+      )
+    end
+
+    def append_color_entries(entries, index:, region:, build_z_offset:)
+      range = color_ranges.fetch(index)
+      return unless range.begin < range.end
+
+      region_model = ZRegionModel.new(model: @model, z_range: range)
+      entries << Entry.new(
+        material: :white, geometry: color_region_white_geometry(region_model),
+        name: "Z plate #{index + 1} White", region:, build_z_offset:
+      )
+      Palette::PIGMENTS.each do |material|
+        next unless region_model.materials.include?(material)
+
         entries << Entry.new(
-          material: :white,
-          geometry: color_region_white_geometry(region_model),
-          name: "Color region #{index + 1} White",
-          region:,
-          build_z_offset:
+          material:, geometry: ColumnGeometry.new(model: region_model, material:),
+          name: "Z plate #{index + 1} #{material.to_s.capitalize}", 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
+    end
+
+    def append_top_white_entry(entries, index:, plate_range:, region:, build_z_offset:)
+      top_start = @settings.layer_structure.color_region_end
+      range = intersection(plate_range, top_start...@settings.z_separated_source_end)
+      return unless range
+
+      geometry = index == plate_ranges.length - 1 ? @top_geometry : box_geometry(range)
       entries << Entry.new(
-        material: :white, geometry: @top_geometry, name: "Top White",
-        region: "top_white", build_z_offset: -@settings.layer_structure.color_region_end
+        material: :white, geometry:, name: "Z plate #{index + 1} Top White",
+        region:, build_z_offset:
       )
-      entries
     end
 
     def color_ranges
-      @settings.layer_structure.color_region_layer_ranges(@settings.color_region_parts)
+      @settings.resolved_z_color_ranges
+    end
+
+    def plate_ranges = @settings.resolved_z_part_ranges
+
+    def intersection(left, right)
+      start = [left.begin, right.begin].max
+      finish = [left.end, right.end].min
+      start < finish ? start...finish : nil
+    end
+
+    def box_geometry(range)
+      BoxGeometry.new(
+        width: @model.x_boundaries.last, height: @model.y_boundaries.last,
+        z_min: range.begin, z_max: range.end
+      )
     end
 
     def color_region_white_geometry(model)
@@ -82,20 +133,6 @@ module Lithop
         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.

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

@@ -38,7 +38,7 @@ module Lithop
         - White thickness uses #{settings.pixel_size} mm XY cells; CMYW recipes use
           #{settings.effective_color_pixel_size} mm color cells.
         - Use 100% rectilinear infill and verify every layer in the slicer before printing.
-        - The effective thickness range is #{settings.effective_minimum_thickness}–#{settings.effective_maximum_thickness} mm.
+        - The effective thickness range is #{output_minimum_thickness(settings)}–#{output_maximum_thickness(settings)} mm.
       MARKDOWN
     end
 
@@ -52,8 +52,23 @@ module Lithop
     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."
+      "- The separated model uses #{settings.resolved_z_part_count} contiguous Z plates with Base White " \
+        "supports of #{settings.z_part_base_white_layers_by_plate.join("/")} layers " \
+        "(#{settings.z_part_base_white_thicknesses.join("/")} mm); every plate is at least " \
+        "#{settings.z_part_minimum_build_thickness} mm thick. The assembled thickness range is " \
+        "#{settings.z_separated_output_minimum_thickness}–#{settings.z_separated_output_maximum_thickness} mm."
+    end
+
+    def output_minimum_thickness(settings)
+      return settings.effective_minimum_thickness unless settings.separate_z_parts
+
+      settings.z_separated_output_minimum_thickness
+    end
+
+    def output_maximum_thickness(settings)
+      return settings.effective_maximum_thickness unless settings.separate_z_parts
+
+      settings.z_separated_output_maximum_thickness
     end
 
     def profile_material(profile, material)
@@ -81,7 +96,8 @@ 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 :model_instruction, :z_part_line, :profile_material, :calibration_line, :thickness_method,
+    private_class_method :model_instruction, :z_part_line, :output_minimum_thickness, :profile_material,
+                         :calibration_line, :thickness_method,
                          :base_layer_description, :layer_height_description
   end
 end

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

@@ -136,9 +136,7 @@ module Lithop
     end
 
     def source_object_id(assembly)
-      return 3 if assembly.region == "top_white"
-
-      assembly.region.delete_prefix("color_region_").to_i - 1
+      assembly.region.delete_prefix("z_part_").to_i - 1
     end
 
     def number(value) = format("%.9g", value)
@@ -150,12 +148,13 @@ module Lithop
 
     def layer_ranges_xml
       object_id = @assemblies.length
-      min_z = @settings.top_white_start
-      max_z = @settings.maximum_thickness
+      min_z = @settings.layer_structure.top_white_start
+      max_z = @settings.effective_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)
+        source_z_min = last_plate_source_z_min
+        base_white = @settings.z_part_base_white_thickness(@settings.resolved_z_part_count - 1)
+        min_z = (min_z - source_z_min + base_white).round(9)
+        max_z = (max_z - source_z_min + base_white).round(9)
       end
       <<~XML
         <?xml version="1.0" encoding="utf-8"?>
@@ -170,6 +169,10 @@ module Lithop
       XML
     end
 
+    def last_plate_source_z_min
+      @settings.resolved_z_part_ranges.last.begin
+    end
+
     def project_settings
       {
         "filament_colour" => %w[#0086D6 #EC008C #FCE300 #FFFFFF],

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

@@ -3,11 +3,15 @@
 module Lithop
   # Indexes vertices and triangles for a 3MF mesh resource.
   class ThreeMFMesh
-    attr_reader :vertices, :vertex_indices, :triangle_count
+    NATIVE_BATCH_SIZE = 8_192
+    MAXIMUM_NATIVE_TOPOLOGY_KEY = (2**63) - 1
+    class UnsupportedNativeTopology < StandardError; end
+
+    attr_reader :vertices, :vertex_indices, :triangle_count, :native_mesh
 
     def initialize(triangles:)
       @triangles = triangles
-      index_resources
+      Native.enabled? ? index_native_resources : index_ruby_resources
     end
 
     def each_indexed_triangle
@@ -18,9 +22,74 @@ module Lithop
       end
     end
 
+    def native_indexed? = !native_mesh.nil?
+
+    def vertex_count = native_indexed? ? native_mesh.vertex_count : vertices.length
+
+    def center
+      return native_mesh.center if native_indexed?
+
+      axes = vertices.transpose
+      axes.map { |values| (values.min + values.max) / 2.0 }
+    end
+
     private
 
-    def index_resources
+    def index_native_resources
+      if @triangles.respond_to?(:native_indexed_mesh)
+        @native_mesh = @triangles.native_indexed_mesh
+        raise InputError, "3MF mesh contains no triangles" if native_mesh.vertex_count.zero?
+
+        @triangle_count = native_mesh.triangle_count
+        @vertices = nil
+        @vertex_indices = nil
+        return
+      end
+
+      @native_mesh = Native::MeshBuilder.new
+      coordinates = []
+      topology_keys = []
+      count = 0
+      @triangles.each do |triangle|
+        validate_triangle!(triangle)
+        triangle.each do |vertex|
+          coordinates.concat(coordinates(vertex))
+          topology_keys << native_topology_key(vertex)
+        end
+        count += 1
+        flush_native_batch(coordinates, topology_keys) if (count % NATIVE_BATCH_SIZE).zero?
+      end
+      flush_native_batch(coordinates, topology_keys)
+      raise InputError, "3MF mesh contains no triangles" if native_mesh.vertex_count.zero?
+
+      @triangle_count = native_mesh.triangle_count
+      @vertices = nil
+      @vertex_indices = nil
+    rescue UnsupportedNativeTopology
+      @native_mesh = nil
+      index_ruby_resources
+    end
+
+    def flush_native_batch(coordinates, topology_keys)
+      return if coordinates.empty?
+
+      native_mesh.add_batch(coordinates, topology_keys)
+      coordinates.clear
+      topology_keys.clear
+    end
+
+    def native_topology_key(vertex)
+      return -1 unless vertex.respond_to?(:topology)
+
+      topology = vertex.topology
+      unless topology.is_a?(Integer) && topology.between?(0, MAXIMUM_NATIVE_TOPOLOGY_KEY)
+        raise UnsupportedNativeTopology
+      end
+
+      topology
+    end
+
+    def index_ruby_resources
       @vertices = []
       @vertex_indices = {}
       @triangle_count = 0

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

@@ -78,7 +78,7 @@ module Lithop
           ThreeMFPartWriter.new(archive: @archive, profile: @profile).write(object_id, part, mesh)
         end
         part.triangles.release_cache! if part.triangles.respond_to?(:release_cache!)
-        vertex_count += mesh.vertices.length
+        vertex_count += mesh.vertex_count
         triangle_counts[part.material] = triangle_counts.fetch(part.material, 0) + mesh.triangle_count
       end
       Result.new(
@@ -96,7 +96,7 @@ module Lithop
       result
     end
 
-    # rubocop:disable-next Metrics/AbcSize
+    # rubocop:disable-next Metrics/AbcSize, Metrics/MethodLength
     def write_external_parts(object_ids, assemblies)
       parts_by_object_id = object_ids.zip(@parts).to_h
       vertex_count = 0
@@ -106,22 +106,26 @@ module Lithop
         measure_xml do
           @archive.write(submodel_header)
           write_materials
-          assembly.object_ids.each do |object_id|
-            part = parts_by_object_id.fetch(object_id)
-            mesh = @instrumentation.measure(:three_mf_indexing) do
-              ThreeMFMesh.new(triangles: part.triangles)
-            end
-            center = mesh_center(mesh)
-            assembly.component_origins[object_id] = component_origin(
-              center, assembly.component_origins.fetch(object_id)
-            )
+        end
+        assembly.object_ids.each do |object_id|
+          part = parts_by_object_id.fetch(object_id)
+          mesh = @instrumentation.measure(:three_mf_indexing) do
+            ThreeMFMesh.new(triangles: part.triangles)
+          end
+          center = mesh_center(mesh)
+          assembly.component_origins[object_id] = component_origin(
+            center, assembly.component_origins.fetch(object_id)
+          )
+          measure_xml do
             ThreeMFPartWriter.new(
               archive: @archive, profile: @profile, production: true, origin: center
             ).write(object_id, part, mesh)
-            part.triangles.release_cache! if part.triangles.respond_to?(:release_cache!)
-            vertex_count += mesh.vertices.length
-            triangle_counts[part.material] = triangle_counts.fetch(part.material, 0) + mesh.triangle_count
           end
+          part.triangles.release_cache! if part.triangles.respond_to?(:release_cache!)
+          vertex_count += mesh.vertex_count
+          triangle_counts[part.material] = triangle_counts.fetch(part.material, 0) + mesh.triangle_count
+        end
+        measure_xml do
           @archive.write("  </resources>\n  <build/>\n</model>\n")
         end
       end
@@ -194,9 +198,8 @@ module Lithop
 
     def assembly_name(region)
       return "Lithop CMYW lithophane" unless region
-      return "Top White" if region == "top_white"
 
-      region.sub("color_region_", "Color region ")
+      region.sub("z_part_", "Z plate ")
     end
 
     def write_assembly(assembly, submodel_index = nil)
@@ -252,8 +255,7 @@ module Lithop
     end
 
     def mesh_center(mesh)
-      axes = mesh.vertices.transpose
-      axes.map { |values| (values.min + values.max) / 2.0 }
+      mesh.center
     end
 
     def component_origin(center, base_origin)
@@ -261,9 +263,7 @@ module Lithop
     end
 
     def plate_index(assembly)
-      return 3 if assembly.region == "top_white"
-
-      assembly.region.delete_prefix("color_region_").to_i - 1
+      assembly.region.delete_prefix("z_part_").to_i - 1
     end
 
     def model_header

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

@@ -3,6 +3,8 @@
 module Lithop
   # Serializes one indexed material mesh into a 3MF model document.
   class ThreeMFPartWriter
+    XML_BATCH_SIZE = 8_192
+
     def initialize(archive:, profile:, production: false, origin: nil)
       @archive = archive
       @profile = profile
@@ -31,6 +33,9 @@ module Lithop
     private
 
     def write_vertices(mesh)
+      return write_indexed_native_vertices(mesh) if mesh.native_indexed?
+      return write_native_vertices(mesh) if Native.enabled?
+
       mesh.vertices.each do |x, y, z|
         @archive.write(
           "          <vertex x=\"#{number(x - @origin[0])}\" y=\"#{number(y - @origin[1])}\" " \
@@ -40,6 +45,9 @@ module Lithop
     end
 
     def write_triangles(mesh)
+      return write_indexed_native_triangles(mesh) if mesh.native_indexed?
+      return write_native_triangles(mesh) if Native.enabled?
+
       count = 0
       mesh.each_indexed_triangle do |vertices|
         @archive.write(
@@ -52,6 +60,35 @@ module Lithop
       raise InputError, "3MF triangle enumerables must be repeatable"
     end
 
+    def write_native_vertices(mesh)
+      mesh.vertices.each_slice(XML_BATCH_SIZE) do |vertices|
+        @archive.write(Native.vertex_xml(vertices.flatten, @origin))
+      end
+    end
+
+    def write_indexed_native_vertices(mesh)
+      0.step(mesh.vertex_count - 1, XML_BATCH_SIZE) do |offset|
+        @archive.write(mesh.native_mesh.vertex_xml(offset, XML_BATCH_SIZE, @origin))
+      end
+    end
+
+    def write_native_triangles(mesh)
+      count = 0
+      mesh.each_indexed_triangle.each_slice(XML_BATCH_SIZE) do |triangles|
+        @archive.write(Native.triangle_xml(triangles.flatten))
+        count += triangles.length
+      end
+      return if count == mesh.triangle_count
+
+      raise InputError, "3MF triangle enumerables must be repeatable"
+    end
+
+    def write_indexed_native_triangles(mesh)
+      0.step(mesh.triangle_count - 1, XML_BATCH_SIZE) do |offset|
+        @archive.write(mesh.native_mesh.triangle_xml(offset, XML_BATCH_SIZE))
+      end
+    end
+
     def number(value) = format("%.9g", value)
   end
 end

data/lib/lithop/formats/three_mf.rb

@@ -18,7 +18,7 @@ module Lithop
     MODEL_RELATIONSHIP = "http://schemas.microsoft.com/3dmanufacturing/2013/01/3dmodel"
     MODEL_CONTENT_TYPE = "application/vnd.ms-package.3dmanufacturing-3dmodel+xml"
     ZIP_MUTEX = Mutex.new
-    # Triangles are indexed and then serialized, so their enumerable must be replayable.
+    # The Rust indexer consumes triangles once; the Ruby comparison path requires replayable input.
     Part = Data.define(:material, :triangles, :name, :region, :build_z_offset) do
       def initialize(material:, triangles:, name: nil, region: nil, build_z_offset: 0.0)
         super