lithop 0.1.0 → 0.2.0

data/lib/lithop/formats/three_mf.rb

@@ -19,7 +19,11 @@ module Lithop
     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)
+    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
+      end
+    end
     Result = Data.define(:vertex_count, :triangle_count, :material_count, :object_count,
                          :triangle_counts_by_material)
 
@@ -66,13 +70,13 @@ module Lithop
         unless valid_materials.include?(part.material)
           raise InputError, "3MF part uses an unknown material: #{part.material.inspect}"
         end
+        unless part.build_z_offset.is_a?(Numeric) && part.build_z_offset.finite?
+          raise InputError, "3MF part build_z_offset must be a finite number"
+        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
@@ -87,7 +91,6 @@ module Lithop
             @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

data/lib/lithop/image/pipeline.rb

@@ -26,6 +26,7 @@ module Lithop
       validate_input!(image)
       image = image.flatten(background: [255, 255, 255]) if image.has_alpha?
       image = to_srgb(image)
+      image = adjust_image(image)
       sampled = @placement.call(image, @settings.sampling_grid).cast(:uchar)
 
       rgbs = rgb_components(sampled)
@@ -72,6 +73,22 @@ module Lithop
       image.icc_import(embedded: true, pcs: :xyz).colourspace(:srgb)
     end
 
+    def adjust_image(image)
+      return image if image_adjustments.none?(&:nonzero?)
+
+      adjusted = image.cast(:float)
+      adjusted += @settings.brightness.fdiv(100) * 255
+      contrast_factor = 1.0 + @settings.contrast.fdiv(100)
+      adjusted = ((adjusted - 127.5) * contrast_factor) + 127.5
+      saturation_factor = 1.0 + @settings.saturation.fdiv(100)
+      luminance = (adjusted[0] * 0.299) + (adjusted[1] * 0.587) + (adjusted[2] * 0.114)
+      luminance + ((adjusted - luminance) * saturation_factor)
+    end
+
+    def image_adjustments
+      [@settings.brightness, @settings.contrast, @settings.saturation]
+    end
+
     def color_cells(image)
       return if @settings.color_pixel_size.nil?
 

data/lib/lithop/job_directory.rb

@@ -1,10 +1,15 @@
 # frozen_string_literal: true
 
 require "fileutils"
+require "json"
+require "time"
 
 module Lithop
   # Owns one temporary job directory and publishes it with an atomic rename.
   class JobDirectory
+    OWNER_FILE = ".lithop-owner.json"
+    Recovered = Data.define(:job_id, :path)
+
     attr_reader :destination, :temporary
 
     def initialize(project_dir:, job_id:)
@@ -24,6 +29,37 @@ module Lithop
       raise
     end
 
+    def self.recover(project_dir:)
+      build_dir = File.join(File.expand_path(project_dir), "build")
+      Dir.glob(File.join(build_dir, ".tmp-*")).filter_map do |path|
+        recover_directory(path)
+      end
+    end
+
+    def self.recover_directory(path)
+      return if File.symlink?(path) || !File.directory?(path)
+
+      owner = JSON.parse(File.read(File.join(path, OWNER_FILE)))
+      job_id = owner.fetch("job_id")
+      return unless File.basename(path) == ".tmp-#{job_id}"
+      return if process_alive?(Integer(owner.fetch("pid")))
+
+      FileUtils.rm_rf(path)
+      Recovered.new(job_id:, path:)
+    rescue JSON::ParserError, KeyError, ArgumentError, SystemCallError
+      nil
+    end
+
+    def self.process_alive?(pid)
+      Process.kill(0, pid)
+      true
+    rescue Errno::ESRCH
+      false
+    rescue Errno::EPERM
+      true
+    end
+    private_class_method :recover_directory, :process_alive?
+
     private
 
     def acquire
@@ -32,6 +68,10 @@ module Lithop
 
       Dir.mkdir(temporary)
       @owned = true
+      File.write(
+        File.join(temporary, OWNER_FILE),
+        JSON.generate(job_id: File.basename(destination), pid: Process.pid, created_at: Time.now.utc.iso8601(6))
+      )
     rescue Errno::EEXIST
       raise Error, "output already exists: #{File.exist?(destination) ? destination : temporary}"
     end
@@ -39,6 +79,7 @@ module Lithop
     def publish
       raise Error, "output already exists: #{destination}" if File.exist?(destination)
 
+      FileUtils.rm_f(File.join(temporary, OWNER_FILE))
       File.rename(temporary, destination)
       @owned = false
     end

data/lib/lithop/job_execution.rb

@@ -0,0 +1,250 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "json"
+require "time"
+
+module Lithop
+  class JobCancelled < Error; end
+
+  # Persists one conversion's state and limits a project to one active conversion.
+  # rubocop:disable-next Metrics/ClassLength
+  class JobExecution
+    SCHEMA_VERSION = 1
+    ACTIVE_STATES = %w[queued running cancelling].freeze
+    FINAL_STATES = %w[completed failed cancelled].freeze
+    Progress = Data.define(:job_id, :state, :phase, :percent, :message, :updated_at)
+
+    attr_reader :job_id, :status_path
+
+    def initialize(project_dir:, job_id:, progress: nil, clock: Time)
+      validate_job_id!(job_id)
+      @project_dir = File.expand_path(project_dir)
+      @job_id = job_id
+      @progress_callback = progress
+      @clock = clock
+      @build_dir = File.join(@project_dir, "build")
+      @jobs_dir = File.join(@build_dir, ".jobs")
+      @status_path = File.join(@jobs_dir, "#{job_id}.json")
+      @cancel_path = File.join(@jobs_dir, "#{job_id}.cancel")
+      @lock_path = File.join(@build_dir, ".lithop.lock")
+      @lock = nil
+      @record = base_record
+    end
+
+    def call
+      prepare
+      transition("queued", phase: "queued", percent: 0, message: "Waiting to start")
+      acquire_lock
+      recover_temporary_directories
+      raise_if_cancelled!
+      transition("running", phase: "starting", percent: 0, message: "Conversion started", started_at: timestamp)
+      result = yield self
+      raise_if_cancelled!
+      complete(result)
+      result
+    rescue JobCancelled, Interrupt => e
+      record_terminal_state(
+        "cancelled", phase: "cancelled", message: "Conversion cancelled", error: e
+      )
+      raise
+    rescue StandardError => e
+      record_terminal_state("failed", phase: "failed", message: "Conversion failed", error: e)
+      raise
+    ensure
+      release_lock
+      remove_cancel_request if prepared?
+    end
+
+    def progress(phase:, percent:, message:)
+      raise_if_cancelled!
+      transition("running", phase: phase.to_s, percent: normalize_percent(percent), message: message.to_s)
+      raise_if_cancelled!
+    end
+
+    def self.request_cancel(project_dir:, job_id:, clock: Time)
+      validate_job_id!(job_id)
+      jobs_dir = File.join(File.expand_path(project_dir), "build", ".jobs")
+      FileUtils.mkdir_p(jobs_dir)
+      status_path = File.join(jobs_dir, "#{job_id}.json")
+      path = File.join(jobs_dir, "#{job_id}.cancel")
+      requested_at = clock.now.utc.iso8601(6)
+      atomic_write(path, JSON.generate(job_id:, requested_at:))
+      mark_cancelling(status_path, requested_at)
+      path
+    end
+
+    class << self
+      private
+
+      def validate_job_id!(job_id)
+        return if job_id.is_a?(String) && job_id.match?(/\A[0-9A-Za-z][0-9A-Za-z._-]*\z/)
+
+        raise Error, "invalid job ID: #{job_id.inspect}"
+      end
+
+      def atomic_write(path, contents)
+        temporary = "#{path}.tmp-#{Process.pid}-#{Thread.current.object_id}"
+        File.write(temporary, contents)
+        File.rename(temporary, path)
+      ensure
+        FileUtils.rm_f(temporary) if defined?(temporary)
+      end
+
+      def mark_cancelling(path, requested_at)
+        return unless File.file?(path)
+
+        record = JSON.parse(File.read(path))
+        return unless ACTIVE_STATES.include?(record["state"])
+
+        record.merge!(
+          "state" => "cancelling",
+          "phase" => "cancelling",
+          "message" => "Cancellation requested",
+          "updated_at" => requested_at
+        )
+        atomic_write(path, JSON.pretty_generate(record) << "\n")
+      rescue JSON::ParserError, SystemCallError
+        nil
+      end
+    end
+
+    private
+
+    def validate_job_id!(value) = self.class.send(:validate_job_id!, value)
+
+    def prepare
+      FileUtils.mkdir_p(@jobs_dir)
+      raise Error, "job state already exists: #{@status_path}" if File.exist?(@status_path)
+
+      @prepared = true
+    end
+
+    def prepared? = @prepared
+
+    def acquire_lock
+      @lock = File.open(@lock_path, File::RDWR | File::CREAT, 0o600)
+      return if @lock.flock(File::LOCK_EX | File::LOCK_NB)
+
+      raise Error, "another conversion is already running in project: #{@project_dir}"
+    end
+
+    def release_lock
+      return unless @lock
+
+      @lock.flock(File::LOCK_UN)
+      @lock.close
+      @lock = nil
+    rescue IOError, SystemCallError
+      @lock = nil
+    end
+
+    def recover_temporary_directories
+      JobDirectory.recover(project_dir: @project_dir).each do |recovered|
+        mark_recovered_job(recovered)
+      end
+    end
+
+    def mark_recovered_job(recovered)
+      path = File.join(@jobs_dir, "#{recovered.job_id}.json")
+      return unless File.file?(path)
+
+      record = JSON.parse(File.read(path))
+      return unless ACTIVE_STATES.include?(record["state"])
+
+      now = timestamp
+      record.merge!(
+        "state" => "failed",
+        "phase" => "recovered",
+        "message" => "Abandoned temporary data recovered",
+        "updated_at" => now,
+        "finished_at" => now,
+        "error" => { "class" => "Lithop::Error", "message" => "conversion process ended before completion" }
+      )
+      self.class.send(:atomic_write, path, JSON.pretty_generate(record) << "\n")
+    rescue JSON::ParserError, SystemCallError
+      nil
+    end
+
+    def complete(result)
+      additions = { finished_at: timestamp }
+      additions[:output_path] = result.path if result.respond_to?(:path)
+      additions[:files] = result.files if result.respond_to?(:files)
+      transition("completed", phase: "completed", percent: 100, message: "Conversion completed", **additions)
+    end
+
+    def transition(state, phase:, percent:, message:, **additions)
+      now = timestamp
+      @record.merge!(
+        state:,
+        phase:,
+        percent: normalize_percent(percent),
+        message:,
+        updated_at: now,
+        **additions
+      )
+      self.class.send(:atomic_write, @status_path, JSON.pretty_generate(@record) << "\n")
+      notify
+    end
+
+    def notify
+      return unless @progress_callback
+
+      @progress_callback.call(
+        Progress.new(
+          job_id:,
+          state: @record.fetch(:state),
+          phase: @record.fetch(:phase),
+          percent: @record.fetch(:percent),
+          message: @record.fetch(:message),
+          updated_at: @record.fetch(:updated_at)
+        )
+      )
+    rescue StandardError
+      nil
+    end
+
+    def record_terminal_state(state, phase:, message:, error:)
+      return unless prepared?
+
+      transition(state, phase:, percent: current_percent, message:, finished_at: timestamp,
+                        error: error_record(error))
+    rescue StandardError
+      nil
+    end
+
+    def raise_if_cancelled!
+      raise JobCancelled, "job #{job_id} was cancelled" if File.file?(@cancel_path)
+    end
+
+    def remove_cancel_request
+      FileUtils.rm_f(@cancel_path) if @cancel_path
+    rescue SystemCallError
+      nil
+    end
+
+    def base_record
+      now = timestamp
+      {
+        schema_version: SCHEMA_VERSION,
+        job_id:,
+        state: "queued",
+        phase: "queued",
+        percent: 0,
+        message: "Waiting to start",
+        created_at: now,
+        updated_at: now,
+        started_at: nil,
+        finished_at: nil,
+        output_path: nil,
+        files: nil,
+        error: nil
+      }
+    end
+
+    def error_record(error) = { class: error.class.name, message: error.message }
+    def timestamp = @clock.now.utc.iso8601(6)
+    def current_percent = @record.fetch(:percent, 0)
+    def normalize_percent(value) = Float(value).clamp(0.0, 100.0)
+  end
+end

data/lib/lithop/layer_structure.rb

@@ -61,6 +61,17 @@ module Lithop
     def color_region_thickness = (color_layer_count * layer_height).round(9)
     def base_white_thickness = (base_white_layers * first_layer_height).round(9)
     def minimum_top_white_thickness = (minimum_physical_thickness - color_end).round(9)
+    def color_region_start = base_white_thickness
+    def color_region_end = color_end
+
+    def color_region_layer_ranges(part_count)
+      size, remainder = color_layer_count.divmod(part_count)
+      start = base_white_layers
+      Array.new(part_count) do |index|
+        finish = start + size + (index < remainder ? 1 : 0)
+        (start...finish).tap { start = finish }
+      end
+    end
 
     def materials_for(recipe_layers, height)
       top_white_layers = top_white_layer_count(height, pigment_layers: recipe_layers.length)

data/lib/lithop/mesh/box_geometry.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module Lithop
+  # Generates a closed axis-aligned box with outward-facing triangles.
+  class BoxGeometry
+    attr_reader :triangle_count
+
+    def initialize(width:, height:, z_min:, z_max:)
+      @width = width
+      @height = height
+      @z_min = z_min
+      @z_max = z_max
+      @triangle_count = 12
+      raise InputError, "box dimensions must be positive" unless width.positive? && height.positive? && z_max > z_min
+    end
+
+    def each_triangle(&block)
+      return enum_for(__method__) unless block
+
+      x0 = 0.0
+      y0 = 0.0
+      x1 = @width
+      y1 = @height
+      z0 = @z_min
+      z1 = @z_max
+      quad([x0, y0, z0], [x0, y1, z0], [x1, y1, z0], [x1, y0, z0], &block)
+      quad([x0, y0, z1], [x1, y0, z1], [x1, y1, z1], [x0, y1, z1], &block)
+      quad([x0, y0, z0], [x1, y0, z0], [x1, y0, z1], [x0, y0, z1], &block)
+      quad([x1, y0, z0], [x1, y1, z0], [x1, y1, z1], [x1, y0, z1], &block)
+      quad([x1, y1, z0], [x0, y1, z0], [x0, y1, z1], [x1, y1, z1], &block)
+      quad([x0, y1, z0], [x0, y0, z0], [x0, y0, z1], [x0, y1, z1], &block)
+    end
+
+    private
+
+    def quad(a, b, c, d)
+      yield [a, b, c]
+      yield [a, c, d]
+    end
+  end
+end

data/lib/lithop/mesh/column_geometry.rb

@@ -7,8 +7,8 @@ module Lithop
     include Enumerable
 
     def initialize(model:, material:)
-      unless Palette::PIGMENTS.include?(material)
-        raise InputError, "column geometry requires a CMY pigment: #{material.inspect}"
+      unless Palette::MATERIALS.include?(material)
+        raise InputError, "column geometry requires a CMYW material: #{material.inspect}"
       end
 
       @model = model

data/lib/lithop/mesh/geometry.rb

@@ -2,16 +2,23 @@
 
 module Lithop
   # Generates the closed triangle mesh for a monochrome height field.
+  # rubocop:disable-next Metrics/ClassLength
   class Geometry
-    def initialize(heights:, columns:, rows:, x_boundaries:, y_boundaries:, optimize_bottom: false)
+    # rubocop:disable-next Metrics/ParameterLists
+    def initialize(
+      heights:, columns:, rows:, x_boundaries:, y_boundaries:, optimize_bottom: false, base_height: 0.0
+    )
       @heights = heights
       @columns = columns
       @rows = rows
       @x = x_boundaries
       @y = y_boundaries
       @optimize_bottom = optimize_bottom
+      @base_height = base_height
       expected = (columns + 1) * (rows + 1)
       raise InputError, "expected #{expected} vertex heights, got #{heights.length}" unless heights.length == expected
+      raise InputError, "base height must be finite" unless base_height.is_a?(Numeric) && base_height.finite?
+      raise InputError, "vertex heights must not be below the base" if heights.any? { |height| height < base_height }
     end
 
     def each_triangle(&block)
@@ -40,7 +47,8 @@ module Lithop
       yield [top_left, bottom_right, top_right]
       return if @optimize_bottom
 
-      quad([x0, y1, 0.0], [x1, y1, 0.0], [x1, y0, 0.0], [x0, y0, 0.0], &)
+      quad([x0, y1, @base_height], [x1, y1, @base_height],
+           [x1, y0, @base_height], [x0, y0, @base_height], &)
     end
 
     def emit_perimeter(&)
@@ -58,8 +66,8 @@ module Lithop
       y0 = @y.last - @y.fetch(row + 1)
       y1 = @y.last - @y.fetch(row)
       quad(
-        [0.0, y0, 0.0], [0.0, y0, height(row + 1, 0)],
-        [0.0, y1, height(row, 0)], [0.0, y1, 0.0], &
+        [0.0, y0, @base_height], [0.0, y0, height(row + 1, 0)],
+        [0.0, y1, height(row, 0)], [0.0, y1, @base_height], &
       )
     end
 
@@ -68,7 +76,7 @@ module Lithop
       y0 = @y.last - @y.fetch(row + 1)
       y1 = @y.last - @y.fetch(row)
       quad(
-        [x, y0, 0.0], [x, y1, 0.0],
+        [x, y0, @base_height], [x, y1, @base_height],
         [x, y1, height(row, @columns)], [x, y0, height(row + 1, @columns)], &
       )
     end
@@ -77,7 +85,7 @@ module Lithop
       x0 = @x.fetch(column)
       x1 = @x.fetch(column + 1)
       quad(
-        [x0, 0.0, 0.0], [x1, 0.0, 0.0],
+        [x0, 0.0, @base_height], [x1, 0.0, @base_height],
         [x1, 0.0, height(@rows, column + 1)], [x0, 0.0, height(@rows, column)], &
       )
     end
@@ -87,18 +95,18 @@ module Lithop
       x1 = @x.fetch(column + 1)
       y = @y.last
       quad(
-        [x0, y, 0.0], [x0, y, height(0, column)],
-        [x1, y, height(0, column + 1)], [x1, y, 0.0], &
+        [x0, y, @base_height], [x0, y, height(0, column)],
+        [x1, y, height(0, column + 1)], [x1, y, @base_height], &
       )
     end
 
     def emit_bottom_fan
-      center = [@x.last.fdiv(2), @y.last.fdiv(2), 0.0]
+      center = [@x.last.fdiv(2), @y.last.fdiv(2), @base_height]
       rendered_y = @y.reverse.map { |y| @y.last - y }
-      perimeter = rendered_y.map { |y| [0.0, y, 0.0] }
-      @x.drop(1).each { |x| perimeter << [x, @y.last, 0.0] }
-      rendered_y.reverse.drop(1).each { |y| perimeter << [@x.last, y, 0.0] }
-      @x.reverse.drop(1).first(@x.length - 2).each { |x| perimeter << [x, 0.0, 0.0] }
+      perimeter = rendered_y.map { |y| [0.0, y, @base_height] }
+      @x.drop(1).each { |x| perimeter << [x, @y.last, @base_height] }
+      rendered_y.reverse.drop(1).each { |y| perimeter << [@x.last, y, @base_height] }
+      @x.reverse.drop(1).first(@x.length - 2).each { |x| perimeter << [x, 0.0, @base_height] }
       perimeter.each_with_index do |from, index|
         yield [center, from, perimeter.fetch((index + 1) % perimeter.length)]
       end

data/lib/lithop/model/layer_region_model.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Lithop
+  # Restricts a material model to one contiguous Z-layer range while preserving global Z coordinates.
+  class LayerRegionModel
+    Cell = Data.define(:materials)
+
+    attr_reader :columns, :rows, :x_boundaries, :y_boundaries, :z_boundaries, :cells, :layer_range
+
+    def initialize(model:, layer_range:)
+      @columns = model.columns
+      @rows = model.rows
+      @x_boundaries = model.x_boundaries
+      @y_boundaries = model.y_boundaries
+      @layer_range = layer_range
+      @z_boundaries = model.z_boundaries[layer_range.begin..layer_range.end].freeze
+      @cells = model.cells.map do |cell|
+        Cell.new(materials: cell.materials.slice(layer_range).to_a.freeze)
+      end.freeze
+    end
+
+    def materials = @materials ||= cells.flat_map(&:materials).uniq.freeze
+  end
+end

data/lib/lithop/reference_three_mf.rb

@@ -7,6 +7,7 @@ require "zip"
 
 module Lithop
   # Streams structural measurements from an existing 3MF without retaining its meshes.
+  # rubocop:disable-next Metrics/ClassLength
   class ReferenceThreeMF
     def initialize(path)
       @path = File.expand_path(path)
@@ -63,6 +64,7 @@ module Lithop
     def start_object(event)
       {
         id: event[1]["id"], type: event[1]["type"], vertices: 0, triangles: 0, components: 0,
+        component_refs: [],
         minimum: [nil, nil, nil], maximum: [nil, nil, nil]
       }
     end
@@ -80,6 +82,10 @@ module Lithop
         current[:triangles] += 1
       when "component"
         current[:components] += 1
+        current[:component_refs] << {
+          object_id: event[1]["objectid"],
+          transform: transform_values(event[1]["transform"])
+        }
       end
     end
 
@@ -105,7 +111,11 @@ module Lithop
 
       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"] }
+        object_ids = plate.get_elements("model_instance").filter_map do |instance|
+          entry = instance.get_elements("metadata").find { |item| item.attributes["key"] == "object_id" }
+          entry && entry.attributes["value"]
+        end
+        { id: integer_or_nil(metadata["plater_id"]), name: metadata["plater_name"], object_ids: }
       end
     end
 
@@ -115,5 +125,11 @@ module Lithop
     end
 
     def integer_or_nil(value) = value && Integer(value)
+
+    def transform_values(value)
+      return unless value
+
+      value.split.map { |number| Float(number) }
+    end
   end
 end