lithop 0.1.0

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

@@ -0,0 +1,114 @@
+# frozen_string_literal: true
+
+module Lithop
+  # Serializes model resources and build items into a 3MF model document.
+  class ThreeMFModelWriter
+    CUSTOM_NAMESPACE = "https://github.com/ogom/lithop/3mf/v1"
+    BASE_MATERIALS_ID = 1
+    COLOR_GROUP_ID = 2
+    FIRST_OBJECT_ID = 3
+    Result = Data.define(:vertex_count, :triangle_count, :triangle_counts_by_material)
+
+    def initialize(archive, parts, profile, instrumentation: Instrumentation.new, settings: nil)
+      @archive = archive
+      @parts = parts
+      @profile = profile
+      @instrumentation = instrumentation
+      @settings = settings
+    end
+
+    def write
+      measure_xml do
+        @archive.write(model_header)
+        write_materials
+      end
+      object_ids, result = write_parts
+      assembly_id = object_ids.max + 1
+      measure_xml do
+        write_assembly(assembly_id, object_ids)
+        @archive.write("  </resources>\n  <build>\n    <item objectid=\"#{assembly_id}\"/>\n  </build>\n</model>\n")
+        ThreeMFBambuMetadata.new(
+          archive: @archive,
+          assembly_id:,
+          object_ids:,
+          parts: @parts,
+          profile: @profile,
+          settings: @settings
+        ).write
+      end
+      result
+    end
+
+    private
+
+    def write_materials
+      @archive.write("    <m:basematerials id=\"#{BASE_MATERIALS_ID}\">\n")
+      @profile.materials.each { |material| @archive.write(material_xml(material)) }
+      @archive.write("    </m:basematerials>\n    <m:colorgroup id=\"#{COLOR_GROUP_ID}\">\n")
+      @profile.materials.each { |material| @archive.write("      <m:color color=\"#{material.display_color}\"/>\n") }
+      @archive.write("    </m:colorgroup>\n")
+    end
+
+    def write_parts
+      vertex_count = 0
+      triangle_counts = {}
+      object_ids = @parts.each_with_index.map do |part, index|
+        object_id = index + FIRST_OBJECT_ID
+        mesh = @instrumentation.measure(:three_mf_indexing) do
+          ThreeMFMesh.new(triangles: part.triangles)
+        end
+        measure_xml do
+          ThreeMFPartWriter.new(archive: @archive, profile: @profile).write(object_id, part.material, mesh)
+        end
+        part.triangles.release_cache! if part.triangles.respond_to?(:release_cache!)
+        vertex_count += mesh.vertices.length
+        triangle_counts[part.material] = mesh.triangle_count
+        object_id
+      end
+      result = Result.new(
+        vertex_count:,
+        triangle_count: triangle_counts.values.sum,
+        triangle_counts_by_material: triangle_counts.freeze
+      )
+      [object_ids, result]
+    end
+
+    def measure_xml(&)
+      @instrumentation.measure(:three_mf_xml_zip, &)
+    end
+
+    def write_assembly(assembly_id, object_ids)
+      @archive.write("    <object id=\"#{assembly_id}\" type=\"model\" name=\"Lithop CMYW lithophane\">\n")
+      @archive.write("      <components>\n")
+      object_ids.each { |object_id| @archive.write("        <component objectid=\"#{object_id}\"/>\n") }
+      @archive.write("      </components>\n    </object>\n")
+    end
+
+    def model_header
+      <<~XML
+        <?xml version="1.0" encoding="UTF-8"?>
+        <model unit="millimeter" xml:lang="en-US" requiredextensions="m"
+          xmlns="#{ThreeMF::CORE_NAMESPACE}"
+          xmlns:m="#{ThreeMF::MATERIAL_NAMESPACE}"
+          xmlns:lithop="#{CUSTOM_NAMESPACE}">
+          <metadata name="Title">Lithop CMYW lithophane</metadata>
+          <metadata name="Application">Lithop #{Lithop::VERSION}</metadata>
+          <metadata name="Description">Physical CMY subtractive layers with variable White luminance thickness.</metadata>
+          <metadata name="lithop:FilamentBundle" preserve="1">#{@profile.name}</metadata>
+          <metadata name="lithop:FilamentProduct" preserve="1">#{@profile.product_url}</metadata>
+          <metadata name="lithop:PrintingGuide" preserve="1">#{@profile.reference_url}</metadata>
+          <resources>
+      XML
+    end
+
+    def material_xml(material)
+      name = "#{@profile.manufacturer} #{material.name} (#{material.color_code})"
+      <<~XML
+        <m:base name="#{name}" displaycolor="#{material.display_color}"
+          lithop:channel="#{material.channel}" lithop:manufacturer="#{@profile.manufacturer}"
+          lithop:product="#{material.name}" lithop:colorcode="#{material.color_code}"
+          lithop:diameter="#{material.diameter_mm}"/>
+      XML
+    end
+  end
+end

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

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module Lithop
+  # Serializes one indexed material mesh into a 3MF model document.
+  class ThreeMFPartWriter
+    def initialize(archive:, profile:)
+      @archive = archive
+      @profile = profile
+    end
+
+    def write(object_id, material, mesh)
+      material_index = @profile.materials.index { |candidate| candidate.channel == material }
+      name = @profile.materials.fetch(material_index).name
+      @archive.write(
+        "    <object id=\"#{object_id}\" type=\"model\" name=\"#{name}\" " \
+        "pid=\"#{ThreeMFModelWriter::COLOR_GROUP_ID}\" pindex=\"#{material_index}\" " \
+        "lithop:channel=\"#{material}\">\n"
+      )
+      @archive.write("      <mesh>\n        <vertices>\n")
+      write_vertices(mesh)
+      @archive.write("        </vertices>\n        <triangles>\n")
+      write_triangles(mesh)
+      @archive.write("        </triangles>\n      </mesh>\n    </object>\n")
+    end
+
+    private
+
+    def write_vertices(mesh)
+      mesh.vertices.each do |x, y, z|
+        @archive.write("          <vertex x=\"#{number(x)}\" y=\"#{number(y)}\" z=\"#{number(z)}\"/>\n")
+      end
+    end
+
+    def write_triangles(mesh)
+      count = 0
+      mesh.each_indexed_triangle do |vertices|
+        @archive.write(
+          "          <triangle v1=\"#{vertices[0]}\" v2=\"#{vertices[1]}\" v3=\"#{vertices[2]}\"/>\n"
+        )
+        count += 1
+      end
+      return if count == mesh.triangle_count
+
+      raise InputError, "3MF triangle enumerables must be repeatable"
+    end
+
+    def number(value) = format("%.9g", value)
+  end
+end

data/lib/lithop/formats/three_mf.rb

@@ -0,0 +1,128 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "zip"
+require_relative "three_mf/mesh"
+require_relative "three_mf/bambu_metadata"
+require_relative "three_mf/part_writer"
+require_relative "three_mf/model_writer"
+
+module Lithop
+  # Writes multipart 3D Manufacturing Format (3MF) packages.
+  # rubocop:disable-next Metrics/ClassLength
+  class ThreeMF
+    CORE_NAMESPACE = "http://schemas.microsoft.com/3dmanufacturing/core/2015/02"
+    MATERIAL_NAMESPACE = "http://schemas.microsoft.com/3dmanufacturing/material/2015/02"
+    RELATIONSHIP_NAMESPACE = "http://schemas.openxmlformats.org/package/2006/relationships"
+    CONTENT_TYPE_NAMESPACE = "http://schemas.openxmlformats.org/package/2006/content-types"
+    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.
+    Part = Data.define(:material, :triangles)
+    Result = Data.define(:vertex_count, :triangle_count, :material_count, :object_count,
+                         :triangle_counts_by_material)
+
+    def self.write(path, parts:, profile: FilamentProfile.default, instrumentation: nil, settings: nil)
+      new(parts:, profile:, instrumentation:, settings:).write(path)
+    end
+
+    def initialize(parts:, profile:, instrumentation: nil, settings: nil)
+      FilamentProfile.validate!(profile)
+      @profile = profile
+      @parts = build_parts(parts)
+      @settings = settings
+      @instrumentation = if instrumentation.is_a?(Instrumentation)
+                           instrumentation
+                         else
+                           Instrumentation.new(instrumentation)
+                         end
+    end
+
+    def write(path)
+      destination = File.expand_path(path)
+      FileUtils.rm_f(destination)
+      package = write_package(destination)
+      Result.new(
+        vertex_count: package.vertex_count,
+        triangle_count: package.triangle_count,
+        material_count: @parts.map(&:material).uniq.length,
+        object_count: @parts.length,
+        triangle_counts_by_material: package.triangle_counts_by_material
+      )
+    rescue Zip::Error => e
+      FileUtils.rm_f(destination) if destination
+      raise Error, "could not write 3MF: #{e.message}"
+    rescue StandardError
+      FileUtils.rm_f(destination) if destination
+      raise
+    end
+
+    private
+
+    def build_parts(parts)
+      valid_materials = @profile.materials.map(&:channel)
+      validated = parts.map do |part|
+        unless valid_materials.include?(part.material)
+          raise InputError, "3MF part uses an unknown material: #{part.material.inspect}"
+        end
+
+        part
+      end
+      raise InputError, "3MF requires at least one material part" if validated.empty?
+      if validated.map(&:material).uniq.length != validated.length
+        raise InputError, "3MF material parts must have unique materials"
+      end
+
+      validated.freeze
+    end
+
+    def write_package(destination)
+      package = nil
+      ZIP_MUTEX.synchronize do
+        zip64 = Zip.write_zip64_support
+        begin
+          Zip.write_zip64_support = false
+          Zip::OutputStream.open(destination, suppress_extra_fields: true) do |archive|
+            @instrumentation.measure(:three_mf_xml_zip) do
+              write_entry(archive, "[Content_Types].xml", content_types_xml)
+              write_entry(archive, "_rels/.rels", relationships_xml)
+              archive.put_next_entry("3D/3dmodel.model")
+            end
+            package = ThreeMFModelWriter.new(
+              archive, @parts, @profile, instrumentation: @instrumentation, settings: @settings
+            ).write
+          end
+        ensure
+          Zip.write_zip64_support = zip64
+        end
+      end
+      package
+    end
+
+    def content_types_xml
+      <<~XML
+        <?xml version="1.0" encoding="UTF-8"?>
+        <Types xmlns="#{CONTENT_TYPE_NAMESPACE}">
+          <Default Extension="rels" ContentType="application/vnd.openxmlformats-package.relationships+xml"/>
+          <Default Extension="model" ContentType="#{MODEL_CONTENT_TYPE}"/>
+          <Default Extension="config" ContentType="application/xml"/>
+        </Types>
+      XML
+    end
+
+    def relationships_xml
+      <<~XML
+        <?xml version="1.0" encoding="UTF-8"?>
+        <Relationships xmlns="#{RELATIONSHIP_NAMESPACE}">
+          <Relationship Target="/3D/3dmodel.model" Id="rel-1" Type="#{MODEL_RELATIONSHIP}"/>
+        </Relationships>
+      XML
+    end
+
+    def write_entry(archive, name, contents)
+      archive.put_next_entry(name)
+      archive.write(contents)
+    end
+  end
+end

data/lib/lithop/image/pipeline.rb

@@ -0,0 +1,175 @@
+# frozen_string_literal: true
+
+module Lithop
+  # Loads, normalizes, and samples an input image for model generation.
+  # rubocop:disable-next Metrics/ClassLength
+  class ImagePipeline
+    REFERENCE_WHITE_MAXIMUM_DENSITY = 0.04
+    REFERENCE_WHITE_MAXIMUM_CHROMA = 0.08
+    REFERENCE_DARK_MAXIMUM_VALUE = 0.75
+    REFERENCE_NEUTRAL_MAXIMUM_CHROMA = 0.25
+    REFERENCE_BROWN_LINE_CMY_COVERAGE = 1.0 / 7
+    Result = Data.define(:width, :height, :cmys, :cmy_densities, :white_densities, :color_cells)
+
+    def initialize(settings)
+      @settings = settings
+      @placement = ImagePlacement.new(settings)
+      @svg_loader = SVGLoader.new(settings)
+    end
+
+    def call(path)
+      require "vips"
+
+      access = @settings.color_pixel_size ? :random : :sequential
+      image = load_image(path, access:)
+      image = image.autorot
+      validate_input!(image)
+      image = image.flatten(background: [255, 255, 255]) if image.has_alpha?
+      image = to_srgb(image)
+      sampled = @placement.call(image, @settings.sampling_grid).cast(:uchar)
+
+      rgbs = rgb_components(sampled)
+      color_samples = rgbs.map { |rgb| color_sample(rgb) }
+      result_color_cells = if @settings.color_pixel_size
+                             color_cells(image)
+                           else
+                             standard_color_cells(color_samples, @settings.columns, @settings.rows)
+                           end
+      Result.new(
+        width: sampled.width,
+        height: sampled.height,
+        cmys: color_samples.map(&:first),
+        cmy_densities: color_samples.map(&:last),
+        white_densities: rgbs.map { |rgb| white_density(rgb) },
+        color_cells: result_color_cells
+      )
+    rescue SystemCallError, Vips::Error => e
+      raise InputError, "could not read image: #{e.message}"
+    end
+
+    private
+
+    def load_image(path, access:)
+      signature = File.binread(path, 8)
+      raster = signature.start_with?("\xFF\xD8\xFF".b) || signature.start_with?("\x89PNG\r\n\x1A\n".b)
+      return Vips::Image.new_from_file(path.to_s, access:) if raster
+
+      @svg_loader.call(path, access:)
+    end
+
+    def validate_input!(image)
+      unless %w[jpegload pngload svgload_buffer].include?(image.get("vips-loader"))
+        raise InputError, "input must be a JPEG, PNG, or SVG image"
+      end
+      return unless image.width * image.height > @settings.maximum_input_pixels
+
+      raise InputError, "input image exceeds #{@settings.maximum_input_pixels} pixels"
+    end
+
+    def to_srgb(image)
+      return image.colourspace(:srgb) if image.get_typeof("icc-profile-data").zero?
+
+      image.icc_import(embedded: true, pcs: :xyz).colourspace(:srgb)
+    end
+
+    def color_cells(image)
+      return if @settings.color_pixel_size.nil?
+
+      grid = @settings.color_sampling_grid
+      sampled = @placement.call(image, grid).cast(:uchar)
+      samples = rgb_components(sampled).map { |rgb| color_sample(rgb) }
+      coarse_cells = standard_color_cells(samples, grid.columns, grid.rows)
+      expand_color_cells(coarse_cells, grid)
+    end
+
+    def standard_color_cells(color_samples, columns, rows)
+      stride = columns + 1
+      Array.new(rows * columns) do |index|
+        row, column = index.divmod(columns)
+        top_left = (row * stride) + column
+        samples = [
+          color_samples.fetch(top_left), color_samples.fetch(top_left + 1),
+          color_samples.fetch(top_left + stride), color_samples.fetch(top_left + stride + 1)
+        ]
+        if samples.any? { |sample| standard_brown_line_sample?(sample.first) }
+          next Array.new(3, REFERENCE_BROWN_LINE_CMY_COVERAGE)
+        end
+
+        density = samples.sum(&:last).fdiv(samples.length)
+        cmy = samples.map(&:first).transpose.map { |components| components.sum.fdiv(components.length) }
+        next [0.0, 0.0, 0.0] if standard_white?(density, cmy)
+
+        cmy
+      end
+    end
+
+    def expand_color_cells(coarse_cells, grid)
+      Array.new(@settings.rows * @settings.columns) do |index|
+        row, column = index.divmod(@settings.columns)
+        x = cell_center(@settings.x_boundaries, column)
+        y = cell_center(@settings.y_boundaries, row)
+        coarse_column = containing_cell(grid.x_boundaries, x)
+        coarse_row = containing_cell(grid.y_boundaries, y)
+        coarse_cells.fetch((coarse_row * grid.columns) + coarse_column)
+      end
+    end
+
+    def cell_center(boundaries, index)
+      (boundaries.fetch(index) + boundaries.fetch(index + 1)).fdiv(2)
+    end
+
+    def containing_cell(boundaries, coordinate)
+      upper = boundaries.bsearch_index { |boundary| boundary > coordinate } || (boundaries.length - 1)
+      (upper - 1).clamp(0, boundaries.length - 2)
+    end
+
+    def rgb_components(image)
+      pixels = image.write_to_memory
+      bands = image.bands
+      count = image.width * image.height
+
+      Array.new(count) do |index|
+        offset = index * bands
+        3.times.map { |band| pixels.getbyte(offset + band).fdiv(255) }
+      end
+    end
+
+    def color_sample(rgb)
+      display_sample = FilamentProfile.display_sample(rgb)
+      return [display_sample.cmy, display_sample.density] if display_sample
+
+      maximum = rgb.max
+      cmy = standard_cmy(rgb, maximum)
+      density = rgb.sum { |component| 1.0 - component }.fdiv(3)
+      [cmy, density]
+    end
+
+    def standard_cmy(rgb, maximum)
+      chroma = rgb.map { |component| maximum - component }
+      return chroma unless maximum <= REFERENCE_DARK_MAXIMUM_VALUE &&
+                           chroma.max <= REFERENCE_NEUTRAL_MAXIMUM_CHROMA
+
+      Array.new(3, REFERENCE_BROWN_LINE_CMY_COVERAGE)
+    end
+
+    def standard_brown_line_sample?(cmy)
+      cmy.all? { |component| (component - REFERENCE_BROWN_LINE_CMY_COVERAGE).abs < 1e-12 }
+    end
+
+    def standard_white?(density, cmy)
+      return false if density > REFERENCE_WHITE_MAXIMUM_DENSITY
+
+      pale_yellow = cmy.fetch(2) == cmy.max && cmy.fetch(2) > REFERENCE_WHITE_MAXIMUM_CHROMA &&
+                    cmy.fetch(0) <= 0.05
+      !pale_yellow
+    end
+
+    def rec601_density(rgb)
+      1.0 - rgb.zip([0.299, 0.587, 0.114]).sum { |component, weight| component * weight }
+    end
+
+    def white_density(rgb)
+      FilamentProfile.display_sample(rgb)&.density || rec601_density(rgb)
+    end
+  end
+end

data/lib/lithop/image/placement.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module Lithop
+  # Fits an image to one sampling grid and adds configured White margins.
+  class ImagePlacement
+    def initialize(settings)
+      @settings = settings
+    end
+
+    def call(image, grid)
+      target_width = grid.sample_width
+      target_height = grid.sample_height
+      margins = grid.margin_samples
+      content_width, content_height = grid.content_sample_size
+      raise InputError, "margins leave no image samples" unless content_width.positive? && content_height.positive?
+
+      place(image, content_width, content_height).embed(
+        margins.fetch(:left), margins.fetch(:top), target_width, target_height,
+        extend: :background, background: Array.new(image.bands, 255)
+      )
+    end
+
+    private
+
+    def place(image, target_width, target_height)
+      return contain(image, target_width, target_height) if @settings.image_fit == "contain"
+
+      cover(image, target_width, target_height)
+    end
+
+    def cover(image, target_width, target_height)
+      scale = [target_width.fdiv(image.width), target_height.fdiv(image.height)].max / @settings.crop_scale
+      resized = image.resize(scale)
+      left = position_offset(resized.width - target_width, @settings.crop_position_x)
+      top = position_offset(resized.height - target_height, @settings.crop_position_y)
+      resized.crop(left, top, target_width, target_height)
+    end
+
+    def contain(image, target_width, target_height)
+      scale = [target_width.fdiv(image.width), target_height.fdiv(image.height)].min * @settings.crop_scale
+      resized = image.resize(scale)
+      left = position_offset(target_width - resized.width, @settings.crop_position_x)
+      top = position_offset(target_height - resized.height, @settings.crop_position_y)
+      resized.embed(
+        left, top, target_width, target_height,
+        extend: :background, background: Array.new(image.bands, 255)
+      )
+    end
+
+    def position_offset(available, position)
+      [(available * position).floor, 0].max
+    end
+  end
+end

data/lib/lithop/image/preview.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module Lithop
+  # Writes cell-based previews from the same material model as the 3MF.
+  module Preview
+    module_function
+
+    def write_thickness(path, model:, minimum:, maximum:, heights: nil)
+      range = maximum - minimum
+      pixels = resolved_heights(model, heights).map { |height| thickness_level(height, minimum, range) }
+      write(path, model, pixels, bands: 1)
+    end
+
+    def write_transmission(path, model:, minimum:, maximum:, heights: nil)
+      range = maximum - minimum
+      pixels = resolved_heights(model, heights).map { |height| 255 - thickness_level(height, minimum, range) }
+      write(path, model, pixels, bands: 1)
+    end
+
+    def write_material(path, model:, minimum:, maximum:, heights: nil, transmission_gamma: 1.0)
+      range = maximum - minimum
+      cell_heights = resolved_heights(model, heights)
+      pixels = model.cells.each_with_index.flat_map do |cell, index|
+        transmission = (255 - thickness_level(cell_heights.fetch(index), minimum, range)).fdiv(255)
+        transmission **= transmission_gamma
+        cell.recipe.coverage_cmy.map do |coverage|
+          ((1.0 - coverage) * transmission * 255).round.clamp(0, 255)
+        end
+      end
+      write(path, model, pixels, bands: 3)
+    end
+
+    def write_mask(path, model:, material:)
+      maximum_layers = model.cells.map { |cell| cell.materials.length }.max
+      pixels = model.cells.map do |cell|
+        (cell.materials.count(material).fdiv(maximum_layers) * 255).round.clamp(0, 255)
+      end
+      write(path, model, pixels, bands: 1)
+    end
+
+    def thickness_level(height, minimum, range)
+      return 0 if range.zero?
+
+      (((height - minimum) / range) * 255).round.clamp(0, 255)
+    end
+
+    def resolved_heights(model, heights)
+      return model.cells.map(&:height) unless heights
+      return heights if heights.length == model.cells.length
+
+      raise InputError, "expected #{model.cells.length} preview heights, got #{heights.length}"
+    end
+    private_class_method :thickness_level, :resolved_heights
+
+    def write(path, model, pixels, bands:)
+      require "vips"
+
+      data = pixels.pack("C*")
+      Vips::Image.new_from_memory(data, model.columns, model.rows, bands, :uchar).pngsave(path.to_s)
+    end
+    private_class_method :write
+  end
+end