lithop 0.2.0 → 0.4.0

data/lib/lithop/image/pipeline.rb

@@ -5,11 +5,13 @@ module Lithop
   # 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)
+    Result = Data.define(
+      :width, :height, :cmys, :cmy_densities, :white_densities, :color_cells, :corrected_preview_png
+    )
+    LoadedImage = Data.define(:image, :material_display)
 
     def initialize(settings)
       @settings = settings
@@ -21,18 +23,14 @@ module Lithop
       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)
-      image = adjust_image(image)
-      sampled = @placement.call(image, @settings.sampling_grid).cast(:uchar)
+      loaded = normalized_image(path, access:)
+      image = loaded.image
+      sampled = @placement.call(image, @settings.sampling_grid).cast(:uchar).copy_memory
 
       rgbs = rgb_components(sampled)
-      color_samples = rgbs.map { |rgb| color_sample(rgb) }
+      color_samples = rgbs.map { |rgb| color_sample(rgb, material_display: loaded.material_display) }
       result_color_cells = if @settings.color_pixel_size
-                             color_cells(image)
+                             color_cells(image, material_display: loaded.material_display)
                            else
                              standard_color_cells(color_samples, @settings.columns, @settings.rows)
                            end
@@ -41,21 +39,68 @@ module Lithop
         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
+        white_densities: rgbs.map { |rgb| white_density(rgb, material_display: loaded.material_display) },
+        color_cells: result_color_cells,
+        corrected_preview_png: sampled.write_to_buffer(".png")
       )
     rescue SystemCallError, Vips::Error => e
       raise InputError, "could not read image: #{e.message}"
     end
 
+    # Returns the same normalized and placed image used by conversion, bounded
+    # to a browser-friendly sampling grid and without running CMYW or mesh work.
+    def preview_png(path, maximum_width: 960, maximum_height: 720)
+      require "vips"
+
+      grid = preview_grid(maximum_width:, maximum_height:)
+      loaded = normalized_image(path, access: :sequential, sampling_grids: [grid])
+      @placement.call(loaded.image, grid).cast(:uchar).write_to_buffer(".png")
+    rescue SystemCallError, Vips::Error => e
+      raise InputError, "could not read image: #{e.message}"
+    end
+
     private
 
-    def load_image(path, access:)
+    def normalized_image(path, access:, sampling_grids: nil)
+      loaded = load_image(path, access:, sampling_grids:)
+      image = loaded.image
+      image = image.autorot
+      validate_input!(image)
+      image = image.flatten(background: [255, 255, 255]) if image.has_alpha?
+      LoadedImage.new(image: adjust_image(to_srgb(image)), material_display: loaded.material_display)
+    end
+
+    def load_image(path, access:, sampling_grids: nil)
       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
+      if raster
+        image = Vips::Image.new_from_file(path.to_s, access:)
+        return LoadedImage.new(image:, material_display: false)
+      end
 
-      @svg_loader.call(path, access:)
+      result = @svg_loader.call(path, access:, sampling_grids:)
+      LoadedImage.new(image: result.image, material_display: result.material_display)
+    end
+
+    def preview_grid(maximum_width:, maximum_height:)
+      maximum_width = Integer(maximum_width)
+      maximum_height = Integer(maximum_height)
+      raise InputError, "preview dimensions must be at least 2 pixels" if maximum_width < 2 || maximum_height < 2
+
+      pixel_size = [
+        @settings.width.fdiv(maximum_width - 1),
+        @settings.height.fdiv(maximum_height - 1),
+        0.01
+      ].max
+      SamplingGrid.new(
+        width: @settings.width, height: @settings.height, pixel_size:,
+        margins: {
+          top: @settings.margin_top, right: @settings.margin_right,
+          bottom: @settings.margin_bottom, left: @settings.margin_left
+        }
+      )
+    rescue ArgumentError, TypeError
+      raise InputError, "preview dimensions must be integers"
     end
 
     def validate_input!(image)
@@ -89,12 +134,12 @@ module Lithop
       [@settings.brightness, @settings.contrast, @settings.saturation]
     end
 
-    def color_cells(image)
+    def color_cells(image, material_display:)
       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) }
+      samples = rgb_components(sampled).map { |rgb| color_sample(rgb, material_display:) }
       coarse_cells = standard_color_cells(samples, grid.columns, grid.rows)
       expand_color_cells(coarse_cells, grid)
     end
@@ -114,7 +159,7 @@ module Lithop
 
         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)
+        next [0.0, 0.0, 0.0] if standard_white?(density)
 
         cmy
       end
@@ -151,16 +196,28 @@ module Lithop
       end
     end
 
-    def color_sample(rgb)
-      display_sample = FilamentProfile.display_sample(rgb)
-      return [display_sample.cmy, display_sample.density] if display_sample
+    def color_sample(rgb, material_display:)
+      display_sample = FilamentProfile.display_sample(rgb, mixtures: material_display)
+      return [mix_yellow(display_sample.cmy), display_sample.density] if display_sample
 
       maximum = rgb.max
-      cmy = standard_cmy(rgb, maximum)
+      cmy = mix_yellow(standard_cmy(rgb, maximum))
       density = rgb.sum { |component| 1.0 - component }.fdiv(3)
       [cmy, density]
     end
 
+    def mix_yellow(cmy)
+      ratio = @settings.yellow_mix_percent.fdiv(100)
+      return cmy if ratio.zero? || cmy.fetch(2).zero?
+
+      mixed = cmy.dup
+      replacement = mixed.fetch(2) * ratio
+      mixed[2] -= replacement
+      index = @settings.yellow_mix_color == "cyan" ? 0 : 1
+      mixed[index] = [mixed.fetch(index) + replacement, 1.0].min
+      mixed
+    end
+
     def standard_cmy(rgb, maximum)
       chroma = rgb.map { |component| maximum - component }
       return chroma unless maximum <= REFERENCE_DARK_MAXIMUM_VALUE &&
@@ -173,20 +230,16 @@ module Lithop
       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
+    def standard_white?(density)
+      @settings.suppress_pale_colors && density <= REFERENCE_WHITE_MAXIMUM_DENSITY
     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)
+    def white_density(rgb, material_display:)
+      FilamentProfile.display_sample(rgb, mixtures: material_display)&.density || rec601_density(rgb)
     end
   end
 end

data/lib/lithop/image/svg_loader.rb

@@ -6,6 +6,8 @@ require "rexml/xpath"
 module Lithop
   # Applies the self-contained, static subset accepted for SVG input.
   class SVGDocumentValidator
+    MATERIAL_DISPLAY_ATTRIBUTE = "data-lithop-color-encoding"
+    MATERIAL_DISPLAY_VALUE = "material-display"
     FORBIDDEN_ELEMENTS = %w[script foreignobject animate animatemotion animatetransform set].freeze
     LENGTH = /\A\+?(?:\d+(?:\.\d*)?|\.\d+)(?:[eE][+-]?\d+)?(?:px|mm|in)?\z/i
     NUMBER = /[+-]?(?:\d+(?:\.\d*)?|\.\d+)(?:[eE][+-]?\d+)?/
@@ -15,6 +17,7 @@ module Lithop
       validate_declarations!(data)
       document = parse(data)
       validate_document!(document)
+      document
     rescue REXML::ParseException => e
       raise InputError, "invalid SVG XML: #{e.message.lines.first.to_s.strip}"
     end
@@ -133,6 +136,7 @@ module Lithop
 
   # Rasterizes a validated SVG at the resolution required by the sampling grids.
   class SVGLoader
+    Result = Data.define(:image, :material_display)
     BASE_DPI = 96.0
     MAXIMUM_FILE_BYTES = 15_000_000
 
@@ -141,23 +145,28 @@ module Lithop
       @validator = SVGDocumentValidator.new
     end
 
-    def call(path, access:)
+    def call(path, access:, sampling_grids: nil)
       data = read(path)
-      @validator.call(data)
+      document = @validator.call(data)
       ensure_loader!
 
       probe = render(data, scale: 1.0, access: :sequential)
       validate_rendered_image!(probe, pixels: false)
-      scale = render_scale(probe)
+      scale = render_scale(probe, sampling_grids || default_sampling_grids)
       validate_planned_pixels!(probe, scale)
 
       image = render(data, scale:, access:)
       validate_rendered_image!(image)
-      image
+      Result.new(image:, material_display: material_display?(document))
     end
 
     private
 
+    def material_display?(document)
+      document.root.attributes[SVGDocumentValidator::MATERIAL_DISPLAY_ATTRIBUTE] ==
+        SVGDocumentValidator::MATERIAL_DISPLAY_VALUE
+    end
+
     def read(path)
       raise InputError, "SVG input exceeds #{MAXIMUM_FILE_BYTES} bytes" if File.size(path) > MAXIMUM_FILE_BYTES
 
@@ -180,8 +189,8 @@ module Lithop
       raise InputError, "could not render SVG: #{e.message}"
     end
 
-    def render_scale(image)
-      scales = sampling_grids.map do |grid|
+    def render_scale(image, grids)
+      scales = grids.map do |grid|
         width, height = grid.content_sample_size
         ratios = [width.fdiv(image.width), height.fdiv(image.height)]
         @settings.image_fit == "contain" ? ratios.min * @settings.crop_scale : ratios.max / @settings.crop_scale
@@ -189,7 +198,7 @@ module Lithop
       [*scales, 1.0 / image.width, 1.0 / image.height].max
     end
 
-    def sampling_grids
+    def default_sampling_grids
       grids = [@settings.sampling_grid]
       grids << @settings.color_sampling_grid if @settings.color_pixel_size
       grids

data/lib/lithop/job_execution.rb

@@ -27,8 +27,10 @@ module Lithop
       @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")
+      @transition_lock_path = File.join(@jobs_dir, "#{job_id}.transition.lock")
       @lock_path = File.join(@build_dir, ".lithop.lock")
       @lock = nil
+      @transition_lock = nil
       @record = base_record
     end
 
@@ -40,7 +42,7 @@ module Lithop
       raise_if_cancelled!
       transition("running", phase: "starting", percent: 0, message: "Conversion started", started_at: timestamp)
       result = yield self
-      raise_if_cancelled!
+      raise_if_cancelled! unless @publication_committed
       complete(result)
       result
     rescue JobCancelled, Interrupt => e
@@ -53,6 +55,7 @@ module Lithop
       raise
     ensure
       release_lock
+      release_transition_lock
       remove_cancel_request if prepared?
     end
 
@@ -62,21 +65,95 @@ module Lithop
       raise_if_cancelled!
     end
 
+    def checkpoint!
+      @transition_mutex = self.class.send(:transition_mutex, @transition_lock_path)
+      @transition_mutex.lock
+      @transition_mutex_locked = true
+      @transition_lock = File.open(@transition_lock_path, File::RDWR | File::CREAT, 0o600)
+      @transition_lock.flock(File::LOCK_EX)
+      raise_if_cancelled!
+    rescue StandardError
+      release_transition_lock
+      raise
+    end
+
+    # Once JobDirectory has atomically published the output, late cancellation
+    # must not turn a complete artifact set into a cancelled job.
+    def publication_committed!(message: "Artifacts published")
+      @publication_committed = true
+      transition("running", phase: "publishing", percent: 99, message:)
+    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")
+      lock_path = File.join(jobs_dir, "#{job_id}.transition.lock")
       requested_at = clock.now.utc.iso8601(6)
-      atomic_write(path, JSON.generate(job_id:, requested_at:))
-      mark_cancelling(status_path, requested_at)
-      path
+      requested = false
+      transition_mutex(lock_path).synchronize do
+        File.open(lock_path, File::RDWR | File::CREAT, 0o600) do |lock|
+          lock.flock(File::LOCK_EX)
+          unless final_status?(status_path)
+            atomic_write(path, JSON.generate(job_id:, requested_at:))
+            mark_cancelling(status_path, requested_at)
+            requested = true
+          end
+        end
+      end
+      path if requested
+    end
+
+    def self.finalize_process_exit(project_dir:, job_id:, clock: Time)
+      validate_job_id!(job_id)
+      build_dir = File.join(File.expand_path(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")
+      record = if File.file?(status_path)
+                 JSON.parse(File.read(status_path))
+               else
+                 process_exit_record(job_id:, cancelled: File.file?(cancel_path), clock:)
+               end
+      return record unless ACTIVE_STATES.include?(record["state"])
+
+      now = clock.now.utc.iso8601(6)
+      output_path = File.join(build_dir, job_id)
+      finalize_exit_record(record, output_path:, cancelled: File.file?(cancel_path), now:)
+      atomic_write(status_path, JSON.pretty_generate(record) << "\n")
+      record
+    rescue JSON::ParserError, SystemCallError
+      nil
+    ensure
+      FileUtils.rm_f(cancel_path) if defined?(cancel_path)
     end
 
     class << self
       private
 
+      def finalize_exit_record(record, output_path:, cancelled:, now:)
+        if File.directory?(output_path) && !File.symlink?(output_path)
+          record.merge!(
+            "state" => "completed", "phase" => "completed", "percent" => 100.0,
+            "message" => "Conversion completed", "updated_at" => now, "finished_at" => now,
+            "output_path" => output_path, "files" => artifact_files(output_path), "error" => nil
+          )
+        elsif record["state"] == "cancelling" || cancelled
+          record.merge!(
+            "state" => "cancelled", "phase" => "cancelled", "message" => "Conversion cancelled",
+            "updated_at" => now, "finished_at" => now
+          )
+        else
+          record.merge!(
+            "state" => "failed", "phase" => "failed", "message" => "Conversion process exited",
+            "updated_at" => now, "finished_at" => now,
+            "error" => { "class" => "Lithop::Error", "message" => "conversion process exited before completion" }
+          )
+        end
+      end
+
       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/)
 
@@ -107,6 +184,39 @@ module Lithop
       rescue JSON::ParserError, SystemCallError
         nil
       end
+
+      def final_status?(path)
+        File.file?(path) && FINAL_STATES.include?(JSON.parse(File.read(path))["state"])
+      rescue JSON::ParserError, SystemCallError
+        false
+      end
+
+      def transition_mutex(path)
+        @transition_mutex_guard ||= Mutex.new
+        @transition_mutex_guard.synchronize do
+          @transition_mutexes ||= {}
+          @transition_mutexes[path] ||= Mutex.new
+        end
+      end
+
+      def artifact_files(output_path)
+        Dir.glob("**/*", base: output_path).select do |name|
+          path = File.join(output_path, name)
+          File.file?(path) && !File.symlink?(path)
+        end.sort
+      end
+
+      def process_exit_record(job_id:, cancelled:, clock:)
+        now = clock.now.utc.iso8601(6)
+        {
+          "schema_version" => SCHEMA_VERSION, "job_id" => job_id,
+          "state" => cancelled ? "cancelling" : "running",
+          "phase" => cancelled ? "cancelling" : "starting", "percent" => 0,
+          "message" => cancelled ? "Cancellation requested" : "Conversion process started",
+          "created_at" => now, "updated_at" => now, "started_at" => nil,
+          "finished_at" => nil, "output_path" => nil, "files" => nil, "error" => nil
+        }
+      end
     end
 
     private
@@ -139,6 +249,24 @@ module Lithop
       @lock = nil
     end
 
+    def release_transition_lock
+      if @transition_lock
+        @transition_lock.flock(File::LOCK_UN)
+        @transition_lock.close
+        @transition_lock = nil
+      end
+      if @transition_mutex_locked
+        @transition_mutex.unlock
+        @transition_mutex_locked = false
+      end
+    rescue IOError, SystemCallError
+      @transition_lock = nil
+      if @transition_mutex_locked
+        @transition_mutex.unlock
+        @transition_mutex_locked = false
+      end
+    end
+
     def recover_temporary_directories
       JobDirectory.recover(project_dir: @project_dir).each do |recovered|
         mark_recovered_job(recovered)

data/lib/lithop/layer_structure.rb

@@ -64,15 +64,6 @@ module Lithop
     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)
       [*Array.new(base_white_layers, :white), *recipe_layers, *Array.new(top_white_layers, :white)]

data/lib/lithop/mesh/column_geometry.rb

@@ -35,6 +35,14 @@ module Lithop
 
     def release_cache! = @topology.release_cache!
 
+    def native_indexed_mesh
+      Native.column_mesh(
+        @model.columns, @model.rows, @model.x_boundaries, @model.y_boundaries, @model.z_boundaries,
+        @intervals.flat_map { |value| value || [-1, -1] },
+        @topology.group_ids, @topology.group_count
+      )
+    end
+
     def triangle_count
       @model.rows.times.sum do |row|
         @model.columns.times.sum do |column|

data/lib/lithop/mesh/column_topology.rb

@@ -174,6 +174,8 @@ module Lithop
       roots.freeze
     end.freeze
 
+    attr_reader :group_ids, :group_count
+
     def initialize(model:, intervals:)
       @model = model
       @intervals = intervals

data/lib/lithop/model/filament_profile.rb

@@ -62,12 +62,12 @@ module Lithop
 
     def default = BAMBU_LAB_PLA_CMYK
 
-    def display_sample(rgb)
-      cmy, density = MaterialDisplayMap.call(rgb)
+    def display_sample(rgb, mixtures: true)
+      cmy, density = MaterialDisplayMap.call(rgb, mixtures:)
       DisplaySample.new(cmy:, density:) if cmy
     end
 
-    def display_cmy(rgb) = display_sample(rgb)&.cmy
+    def display_cmy(rgb, mixtures: true) = display_sample(rgb, mixtures:)&.cmy
 
     def validate!(profile)
       channels = profile.materials.map(&:channel)

data/lib/lithop/model/material_display_map.rb

@@ -32,12 +32,13 @@ module Lithop
 
     module_function
 
-    def call(rgb)
+    def call(rgb, mixtures: true)
       channels = rgb.map { |component| (component * 255).round.clamp(0, 255) }
       packed = channels.reduce(0) { |value, component| (value << 8) | component }
       return [[0.0, 0.0, 0.0], 0.0] if packed == 0xFFFFFF
       return [CMY_BLACK, CMY_BLACK_DENSITIES.fetch(packed)] if CMY_BLACK_DENSITIES.key?(packed)
       return [COLOR_CMYS.fetch(packed), 1.0] if COLOR_CMYS.key?(packed)
+      return unless mixtures
 
       match = closest_line(channels)
       return unless match && match.first <= MAXIMUM_ERROR

data/lib/lithop/model/material_model.rb

@@ -17,6 +17,7 @@ module Lithop
         pigment_order: settings.pigment_order
       )
       @settings = settings
+      @material_arrays = {}
       validate_samples!(cmys, heights, cell_cmys)
       @cells = build_cells(cmys, heights, cell_cmys).freeze
       maximum_layers = cells.map { |cell| cell.materials.length }.max
@@ -31,7 +32,9 @@ module Lithop
     end
 
     def materials
-      @materials ||= cells.flat_map(&:materials).uniq.freeze
+      @materials ||= cells.each_with_object({}) do |cell, result|
+        cell.materials.each { |material| result[material] = true }
+      end.keys.freeze
     end
 
     def recipe_counts
@@ -63,12 +66,21 @@ module Lithop
     end
 
     def build_cells(cmys, heights, cell_cmys)
-      Array.new(rows * columns) do |index|
+      cell_heights = Array.new(rows * columns)
+      cell_colors = Array.new(rows * columns) do |index|
         row, column = index.divmod(columns)
         cmy = cell_cmys ? cell_cmys.fetch(index) : average(corners(cmys, row, column))
-        height = @settings.quantize_thickness(average(corners(heights, row, column)))
-        recipe = @palette.nearest(cmy)
-        Cell.new(height:, recipe:, materials: materials_for(recipe, height).freeze)
+        cell_heights[index] = @settings.quantize_thickness(average(corners(heights, row, column)))
+        cmy
+      end
+      recipes = if @palette.respond_to?(:nearest_many)
+                  @palette.nearest_many(cell_colors)
+                else
+                  cell_colors.map { |cmy| @palette.nearest(cmy) }
+                end
+      cell_heights.zip(recipes).map do |height, recipe|
+        materials = @material_arrays[[recipe, height]] ||= materials_for(recipe, height).freeze
+        Cell.new(height:, recipe:, materials:)
       end
     end
 

data/lib/lithop/model/palette.rb

@@ -49,13 +49,20 @@ module Lithop
       @layer_count = layer_count
       @pigment_order = pigment_order.dup.freeze
       @recipes = build_recipes.freeze
+      @native_coverages = recipes.flat_map(&:coverage_cmy).freeze
     end
 
     def nearest(cmy)
       validate_cmy!(cmy)
-      recipes.min_by do |recipe|
-        recipe.coverage_cmy.zip(cmy).sum { |coverage, target| (coverage - target)**2 }
-      end
+      nearest_validated(cmy)
+    end
+
+    def nearest_many(cmys)
+      cmys.each { |cmy| validate_cmy!(cmy) }
+      return cmys.map { |cmy| nearest_validated(cmy) } unless Native.enabled?
+
+      indices = Native.palette_indices(cmys.flatten, @native_coverages)
+      indices.map { |index| recipes.fetch(index) }
     end
 
     def display_color(recipe)
@@ -97,5 +104,16 @@ module Lithop
 
       raise InputError, "CMY must contain three values between 0 and 1"
     end
+
+    def squared_distance(coverage, target)
+      cyan = coverage[0] - target[0]
+      magenta = coverage[1] - target[1]
+      yellow = coverage[2] - target[2]
+      (cyan * cyan) + (magenta * magenta) + (yellow * yellow)
+    end
+
+    def nearest_validated(cmy)
+      recipes.min_by { |recipe| squared_distance(recipe.coverage_cmy, cmy) }
+    end
   end
 end

data/lib/lithop/model/z_region_model.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module Lithop
+  # Restricts a material model to an arbitrary contiguous Z range.
+  class ZRegionModel
+    Cell = Data.define(:materials)
+
+    attr_reader :columns, :rows, :x_boundaries, :y_boundaries, :z_boundaries, :cells, :z_range
+
+    def initialize(model:, z_range:)
+      @columns = model.columns
+      @rows = model.rows
+      @x_boundaries = model.x_boundaries
+      @y_boundaries = model.y_boundaries
+      @z_range = z_range
+      source_layers = overlapping_layers(model.z_boundaries)
+      @z_boundaries = clipped_boundaries(model.z_boundaries, source_layers).freeze
+      @cells = model.cells.map do |cell|
+        Cell.new(materials: source_layers.map { |layer| cell.materials.fetch(layer) }.freeze)
+      end.freeze
+    end
+
+    def materials = @materials ||= cells.flat_map(&:materials).uniq.freeze
+
+    private
+
+    def overlapping_layers(boundaries)
+      layers = (0...(boundaries.length - 1)).select do |layer|
+        boundaries.fetch(layer) < z_range.end && boundaries.fetch(layer + 1) > z_range.begin
+      end
+      raise InputError, "Z region must overlap the material model" if layers.empty?
+
+      layers.freeze
+    end
+
+    def clipped_boundaries(boundaries, layers)
+      inner = layers.filter_map do |layer|
+        boundary = boundaries.fetch(layer + 1)
+        boundary if boundary > z_range.begin && boundary < z_range.end
+      end
+      [z_range.begin, *inner, z_range.end]
+    end
+  end
+end