lithop 0.1.0 → 0.3.0

data/lib/lithop/image/svg_loader.rb

@@ -141,14 +141,14 @@ module Lithop
       @validator = SVGDocumentValidator.new
     end
 
-    def call(path, access:)
+    def call(path, access:, sampling_grids: nil)
       data = read(path)
       @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:)
@@ -180,8 +180,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 +189,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_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,378 @@
+# 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")
+      @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
+
+    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! unless @publication_committed
+      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
+      release_transition_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 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)
+      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/)
+
+        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
+
+      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
+
+    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 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)
+      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
@@ -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/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