lithop 0.1.0 → 0.2.0

data/lib/lithop/settings.rb

@@ -13,10 +13,13 @@ module Lithop
       validate_color_model!
       validate_layout_profile!
       validate_grid!
+      validate_tiles!
       validate_layer_structure!
+      validate_z_parts!
       validate_advanced_layer_structure!
       validate_margins!
       validate_image_placement!
+      validate_image_adjustments!
       validate_nozzle_diameter!
       validate_mesh_limit!
     end
@@ -73,6 +76,55 @@ module Lithop
       raise ConfigurationError, "grid_columns and grid_rows must be positive integers or null"
     end
 
+    def validate_tiles!
+      validate_tile_count!
+      validate_tile_layout!
+      validate_tile_grid!
+
+      if tile_count > columns * rows
+        raise ConfigurationError, "tile layout must leave at least one XY cell in every tile"
+      end
+
+      return if resolved_tile_columns <= columns && resolved_tile_rows <= rows
+
+      raise ConfigurationError, "tile layout must leave at least one XY cell in every tile"
+    end
+
+    def validate_tile_count!
+      return if tile_count.is_a?(Integer) && tile_count.positive?
+
+      raise ConfigurationError, "tile_count must be a positive integer"
+    end
+
+    def validate_tile_layout!
+      return if Settings::TILE_LAYOUTS.include?(tile_layout)
+
+      raise ConfigurationError, "tile_layout must be one of: #{Settings::TILE_LAYOUTS.join(", ")}"
+    end
+
+    def validate_tile_grid!
+      unless tile_layout == "grid"
+        return if tile_rows.nil? && tile_columns.nil?
+
+        raise ConfigurationError, "tile_rows and tile_columns may only be set for grid layout"
+      end
+      unless tile_rows.is_a?(Integer) && tile_rows.positive? &&
+             tile_columns.is_a?(Integer) && tile_columns.positive?
+        raise ConfigurationError, "tile_rows and tile_columns must be positive integers for grid layout"
+      end
+      return if tile_rows * tile_columns == tile_count
+
+      raise ConfigurationError, "tile_rows times tile_columns must equal tile_count"
+    end
+
+    def validate_z_parts!
+      raise ConfigurationError, "separate_z_parts must be a boolean" unless [true, false].include?(separate_z_parts)
+      unless color_region_parts.is_a?(Integer) && color_region_parts.positive? &&
+             color_region_parts <= color_layer_count
+        raise ConfigurationError, "color_region_parts must be an integer from 1 to color_layer_count"
+      end
+    end
+
     def validate_layer_structure!
       return if Settings::COLOR_LAYER_COUNTS.include?(color_layer_count)
 
@@ -128,6 +180,15 @@ module Lithop
       raise ConfigurationError, "crop_scale must be a finite number greater than 0 and at most 1"
     end
 
+    def validate_image_adjustments!
+      %i[brightness contrast saturation].each do |key|
+        value = public_send(key)
+        next if value.is_a?(Numeric) && value.finite? && value.between?(-100.0, 100.0)
+
+        raise ConfigurationError, "#{key} must be a finite percentage from -100 to 100"
+      end
+    end
+
     def validate_nozzle_diameter!
       return if Settings::NOZZLE_DIAMETERS.include?(nozzle_diameter)
 
@@ -174,6 +235,7 @@ module Lithop
     COLOR_LAYER_COUNTS = [4, 5, 7].freeze
     LAYOUT_PROFILES = ["standard"].freeze
     IMAGE_FITS = %w[cover contain].freeze
+    TILE_LAYOUTS = %w[auto columns rows grid].freeze
     PIGMENTS = %i[cyan magenta yellow].freeze
     MINIMUM_TOP_WHITE_LAYERS = LayerStructure::MINIMUM_TOP_WHITE_LAYERS
     DEFAULTS = {
@@ -188,12 +250,21 @@ module Lithop
       crop_position_x: 0.5,
       crop_position_y: 0.5,
       crop_scale: 1.0,
+      brightness: 0.0,
+      contrast: 0.0,
+      saturation: 0.0,
       minimum_thickness: 1.0,
       maximum_thickness: 2.14689422,
       pixel_size: 0.22,
       color_pixel_size: nil,
       grid_columns: 637,
       grid_rows: 473,
+      tile_count: 1,
+      tile_layout: "auto",
+      tile_rows: nil,
+      tile_columns: nil,
+      separate_z_parts: false,
+      color_region_parts: 3,
       first_layer_height: 0.1,
       layer_height: 0.1,
       base_white_layers: 2,
@@ -232,6 +303,7 @@ module Lithop
       end
 
       validate_physical_minimum!
+      validate_separated_top_white!
     end
 
     def without_default_grid(values)
@@ -250,6 +322,18 @@ module Lithop
     def pixel_size_x = width.fdiv(columns)
     def pixel_size_y = height.fdiv(rows)
 
+    def resolved_tile_shape
+      case tile_layout
+      when "columns" then [1, tile_count]
+      when "rows" then [tile_count, 1]
+      when "grid" then [tile_rows, tile_columns]
+      else automatic_tile_shape
+      end
+    end
+
+    def resolved_tile_rows = resolved_tile_shape.fetch(0)
+    def resolved_tile_columns = resolved_tile_shape.fetch(1)
+
     def estimated_triangles
       (4 * columns * rows) + (4 * (columns + rows))
     end
@@ -288,8 +372,39 @@ module Lithop
         effective_color_pixel_size: effective_color_pixel_size,
         effective_minimum_thickness: effective_minimum_thickness,
         effective_maximum_thickness: effective_maximum_thickness,
-        columns: columns, rows: rows, pixel_size_x: pixel_size_x, pixel_size_y: pixel_size_y
+        columns: columns, rows: rows, pixel_size_x: pixel_size_x, pixel_size_y: pixel_size_y,
+        resolved_tile_rows: resolved_tile_rows, resolved_tile_columns: resolved_tile_columns
       )
     end
+
+    private
+
+    def automatic_tile_shape
+      factors = factor_shapes.map do |row_count, column_count|
+        tile_width = width.fdiv(column_count)
+        tile_height = height.fdiv(row_count)
+        [[Math.log(tile_width.fdiv(tile_height)).abs, -column_count], [row_count, column_count]]
+      end
+      feasible = factors.select do |_score, (row_count, column_count)|
+        row_count <= rows && column_count <= columns
+      end
+      (feasible.empty? ? factors : feasible).min_by(&:first).last
+    end
+
+    def factor_shapes
+      (1..Math.sqrt(tile_count).floor).flat_map do |row_count|
+        next [] unless (tile_count % row_count).zero?
+
+        column_count = tile_count / row_count
+        row_count == column_count ? [[row_count, column_count]] : [[row_count, column_count], [column_count, row_count]]
+      end
+    end
+
+    def validate_separated_top_white!
+      return unless separate_z_parts
+      return if effective_minimum_thickness > layer_structure.color_region_end
+
+      raise ConfigurationError, "separate_z_parts requires a positive top White thickness"
+    end
   end
 end

data/lib/lithop/settings_file.rb

@@ -26,10 +26,7 @@ module Lithop
 
       validate_keys!(data, expanded)
       validate_schema!(data, expanded)
-      values = data.except("schema_version").transform_keys(&:to_sym)
-      values[:color_model] = values[:color_model].downcase if values[:color_model].is_a?(String)
-      values[:image_fit] = values[:image_fit].downcase if values[:image_fit].is_a?(String)
-      values[:layout_profile] = values[:layout_profile].downcase if values[:layout_profile].is_a?(String)
+      values = normalize_values(data.except("schema_version").transform_keys(&:to_sym))
       Result.new(path: expanded, values:)
     rescue JSON::ParserError => e
       raise ConfigurationError, "settings file is not valid JSON: #{expanded}: #{e.message}"
@@ -37,6 +34,15 @@ module Lithop
       raise ConfigurationError, "could not read settings file: #{expanded}: #{e.message}"
     end
 
+    def normalize_values(values)
+      values[:color_model] = values[:color_model].downcase if values[:color_model].is_a?(String)
+      values[:image_fit] = values[:image_fit].downcase if values[:image_fit].is_a?(String)
+      values[:layout_profile] = values[:layout_profile].downcase if values[:layout_profile].is_a?(String)
+      values[:tile_layout] = values[:tile_layout].downcase if values[:tile_layout].is_a?(String)
+      values
+    end
+    private_class_method :normalize_values
+
     def validate_keys!(data, path)
       unknown = data.keys - ALLOWED_KEYS
       return if unknown.empty?

data/lib/lithop/tiling.rb

@@ -0,0 +1,126 @@
+# frozen_string_literal: true
+
+module Lithop
+  # Resolves a deterministic tile grid on existing XY cell boundaries.
+  class TileLayout
+    Tile = Data.define(
+      :id, :row, :column, :row_start, :row_end, :column_start, :column_end,
+      :x_min, :x_max, :y_min, :y_max
+    ) do
+      def width = x_max - x_min
+      def height = y_max - y_min
+      def offset = { x: x_min, y: y_min }
+      def bounds = { x_min:, x_max:, y_min:, y_max: }
+    end
+
+    attr_reader :rows, :columns, :tiles
+
+    def initialize(settings)
+      @settings = settings
+      @rows = settings.resolved_tile_rows
+      @columns = settings.resolved_tile_columns
+      @tiles = build_tiles.freeze
+    end
+
+    private
+
+    def build_tiles
+      row_spans = partition(@settings.rows, rows)
+      column_spans = partition(@settings.columns, columns)
+      row_spans.each_with_index.flat_map do |(row_start, row_end), row|
+        column_spans.each_with_index.map do |(column_start, column_end), column|
+          Tile.new(
+            id: format("tile_r%<row>02d_c%<column>02d", row: row + 1, column: column + 1),
+            row: row + 1,
+            column: column + 1,
+            row_start:, row_end:, column_start:, column_end:,
+            x_min: @settings.x_boundaries.fetch(column_start),
+            x_max: @settings.x_boundaries.fetch(column_end),
+            y_min: (@settings.height - @settings.y_boundaries.fetch(row_end)).round(9),
+            y_max: (@settings.height - @settings.y_boundaries.fetch(row_start)).round(9)
+          )
+        end
+      end
+    end
+
+    def partition(cell_count, part_count)
+      size, remainder = cell_count.divmod(part_count)
+      start = 0
+      Array.new(part_count) do |index|
+        finish = start + size + (index < remainder ? 1 : 0)
+        [start, finish].tap { start = finish }
+      end
+    end
+  end
+
+  # Presents one rectangular subset of a material model in tile-local coordinates.
+  class TileMaterialModel
+    attr_reader :columns, :rows, :x_boundaries, :y_boundaries, :z_boundaries, :cells
+
+    def initialize(model:, tile:)
+      @columns = tile.column_end - tile.column_start
+      @rows = tile.row_end - tile.row_start
+      @x_boundaries = local_boundaries(model.x_boundaries, tile.column_start, tile.column_end)
+      @y_boundaries = local_boundaries(model.y_boundaries, tile.row_start, tile.row_end)
+      @z_boundaries = model.z_boundaries
+      @cells = slice_cells(model, tile).freeze
+    end
+
+    def materials = @materials ||= cells.flat_map(&:materials).uniq.freeze
+
+    private
+
+    def local_boundaries(boundaries, first, last)
+      origin = boundaries.fetch(first)
+      boundaries[first..last].map { |value| (value - origin).round(9) }.freeze
+    end
+
+    def slice_cells(model, tile)
+      (tile.row_start...tile.row_end).flat_map do |row|
+        offset = (row * model.columns) + tile.column_start
+        model.cells.slice(offset, columns)
+      end
+    end
+  end
+
+  # Writes a physical-size overview of the tile IDs and assembled placement.
+  module TileLayoutSVG
+    module_function
+
+    def write(path, settings:, layout:)
+      File.write(path, document(settings:, layout:))
+    end
+
+    def document(settings:, layout:)
+      rectangles = layout.tiles.map { |tile| tile_element(settings, tile) }.join("\n")
+      <<~SVG
+        <?xml version="1.0" encoding="UTF-8"?>
+        <svg xmlns="http://www.w3.org/2000/svg" width="#{settings.width}mm" height="#{settings.height}mm"
+             viewBox="0 0 #{settings.width} #{settings.height}">
+          <rect width="#{settings.width}" height="#{settings.height}" fill="#fff" stroke="#000" stroke-width="0.4"/>
+        #{rectangles}
+        </svg>
+      SVG
+    end
+
+    def tile_element(settings, tile)
+      y = settings.height - tile.y_max
+      font_size = [[tile.width, tile.height].min * 0.12, 5.0].min
+      center_x = tile.x_min + (tile.width / 2.0)
+      center_y = y + (tile.height / 2.0)
+      <<~SVG.chomp
+        <g>
+          <rect x="#{tile.x_min}" y="#{y}" width="#{tile.width}" height="#{tile.height}"
+                fill="none" stroke="#333" stroke-width="0.25"/>
+          <text x="#{center_x}" y="#{center_y - (font_size * 0.6)}"
+                font-family="sans-serif" font-size="#{font_size}" text-anchor="middle"
+                dominant-baseline="middle">#{tile.id}</text>
+          <text x="#{center_x}" y="#{center_y + (font_size * 0.6)}"
+                font-family="sans-serif" font-size="#{font_size * 0.72}" text-anchor="middle"
+                dominant-baseline="middle">#{tile.width.round(3)} × #{tile.height.round(3)} mm</text>
+        </g>
+      SVG
+    end
+    private_class_method :tile_element
+  end
+end

data/lib/lithop/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Lithop
-  VERSION = "0.1.0"
+  VERSION = "0.2.0"
 end

data/lib/lithop.rb

@@ -13,17 +13,21 @@ require_relative "lithop/layer_structure"
 require_relative "lithop/settings"
 require_relative "lithop/settings_file"
 require_relative "lithop/job_directory"
+require_relative "lithop/job_execution"
 require_relative "lithop/instrumentation"
 require_relative "lithop/model/thickness"
 require_relative "lithop/model/palette"
 require_relative "lithop/model/material_display_map"
 require_relative "lithop/model/filament_profile"
 require_relative "lithop/model/material_model"
+require_relative "lithop/model/layer_region_model"
+require_relative "lithop/tiling"
 require_relative "lithop/image/placement"
 require_relative "lithop/image/svg_loader"
 require_relative "lithop/image/pipeline"
 require_relative "lithop/image/preview"
 require_relative "lithop/mesh/geometry"
+require_relative "lithop/mesh/box_geometry"
 require_relative "lithop/mesh/voxel_topology"
 require_relative "lithop/mesh/voxel_geometry"
 require_relative "lithop/mesh/column_topology"

data/sig/lithop.rbs

@@ -22,12 +22,21 @@ module Lithop
     attr_reader crop_position_x: Numeric
     attr_reader crop_position_y: Numeric
     attr_reader crop_scale: Numeric
+    attr_reader brightness: Numeric
+    attr_reader contrast: Numeric
+    attr_reader saturation: Numeric
     attr_reader minimum_thickness: Numeric
     attr_reader maximum_thickness: Numeric
     attr_reader pixel_size: Numeric
     attr_reader color_pixel_size: Numeric?
     attr_reader grid_columns: Integer?
     attr_reader grid_rows: Integer?
+    attr_reader tile_count: Integer
+    attr_reader tile_layout: String
+    attr_reader tile_rows: Integer?
+    attr_reader tile_columns: Integer?
+    attr_reader separate_z_parts: bool
+    attr_reader color_region_parts: Integer
     attr_reader first_layer_height: Numeric
     attr_reader layer_height: Numeric
     attr_reader base_white_layers: Integer
@@ -52,6 +61,9 @@ module Lithop
     def fitted_grid?: () -> bool
     def pixel_size_x: () -> Float
     def pixel_size_y: () -> Float
+    def resolved_tile_shape: () -> [Integer, Integer]
+    def resolved_tile_rows: () -> Integer
+    def resolved_tile_columns: () -> Integer
     def estimated_triangles: () -> Integer
     def triangle_limit_message: (String label, Integer triangle_count) -> String
     def x_boundaries: () -> Array[Numeric]
@@ -61,6 +73,33 @@ module Lithop
     def to_h: () -> Hash[Symbol, untyped]
   end
 
+  class TileLayout
+    class Tile < Data
+      attr_reader id: String
+      attr_reader row: Integer
+      attr_reader column: Integer
+      attr_reader row_start: Integer
+      attr_reader row_end: Integer
+      attr_reader column_start: Integer
+      attr_reader column_end: Integer
+      attr_reader x_min: Numeric
+      attr_reader x_max: Numeric
+      attr_reader y_min: Numeric
+      attr_reader y_max: Numeric
+
+      def width: () -> Numeric
+      def height: () -> Numeric
+      def offset: () -> Hash[Symbol, Numeric]
+      def bounds: () -> Hash[Symbol, Numeric]
+    end
+
+    attr_reader rows: Integer
+    attr_reader columns: Integer
+    attr_reader tiles: Array[Tile]
+
+    def initialize: (Settings settings) -> void
+  end
+
   class Palette
     class Recipe < Data
       attr_reader cyan: Integer
@@ -186,7 +225,14 @@ module Lithop
         attr_reader patch_count: Integer
       end
 
-      def initialize: (settings: Settings, project_dir: String, ?clock: untyped, ?random: untyped) -> void
+      def initialize: (
+        settings: Settings,
+        project_dir: String,
+        ?job_progress: untyped,
+        ?clock: untyped,
+        ?random: untyped,
+        ?job_id: String?
+      ) -> void
       def call: () -> Result
     end
   end
@@ -243,6 +289,11 @@ module Lithop
     class Part < Data
       attr_reader material: Symbol
       attr_reader triangles: Enumerable[untyped]
+      attr_reader name: String?
+      attr_reader region: String?
+      attr_reader build_z_offset: Numeric
+
+      def initialize: (material: Symbol, triangles: Enumerable[untyped], ?name: String?, ?region: String?, ?build_z_offset: Numeric) -> void
     end
 
     class Result < Data
@@ -266,6 +317,28 @@ module Lithop
     attr_reader object_count: Integer
   end
 
+  class JobCancelled < Error
+  end
+
+  class JobExecution
+    class Progress < Data
+      attr_reader job_id: String
+      attr_reader state: String
+      attr_reader phase: String
+      attr_reader percent: Float
+      attr_reader message: String
+      attr_reader updated_at: String
+    end
+
+    attr_reader job_id: String
+    attr_reader status_path: String
+
+    def initialize: (project_dir: String, job_id: String, ?progress: untyped, ?clock: untyped) -> void
+    def call: [A] () { (JobExecution) -> A } -> A
+    def progress: (phase: String | Symbol, percent: Numeric, message: String) -> void
+    def self.request_cancel: (project_dir: String, job_id: String, ?clock: untyped) -> String
+  end
+
   class Export
     class CalibrationInput < Data
       attr_reader profile: Calibration::Profile
@@ -278,9 +351,11 @@ module Lithop
       ?input_settings_path: String?,
       ?calibration: CalibrationInput?,
       ?progress: untyped,
+      ?job_progress: untyped,
       ?instrumentation: untyped,
       ?clock: untyped,
-      ?random: untyped
+      ?random: untyped,
+      ?job_id: String?
     ) -> void
     def call: (String input_path) -> ExportResult
   end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: lithop
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - ogom
@@ -73,6 +73,7 @@ files:
 - docs/command.md
 - docs/config.md
 - docs/getting-started.md
+- docs/tiling.md
 - docs/troubleshooting.md
 - lib/lithop.rb
 - lib/lithop/calibration/export.rb
@@ -108,7 +109,9 @@ files:
 - lib/lithop/image/svg_loader.rb
 - lib/lithop/instrumentation.rb
 - lib/lithop/job_directory.rb
+- lib/lithop/job_execution.rb
 - lib/lithop/layer_structure.rb
+- lib/lithop/mesh/box_geometry.rb
 - lib/lithop/mesh/column_geometry.rb
 - lib/lithop/mesh/column_topology.rb
 - lib/lithop/mesh/geometry.rb
@@ -116,6 +119,7 @@ files:
 - lib/lithop/mesh/voxel_geometry.rb
 - lib/lithop/mesh/voxel_topology.rb
 - lib/lithop/model/filament_profile.rb
+- lib/lithop/model/layer_region_model.rb
 - lib/lithop/model/material_display_map.rb
 - lib/lithop/model/material_model.rb
 - lib/lithop/model/palette.rb
@@ -124,6 +128,7 @@ files:
 - lib/lithop/sampling_grid.rb
 - lib/lithop/settings.rb
 - lib/lithop/settings_file.rb
+- lib/lithop/tiling.rb
 - lib/lithop/version.rb
 - sig/lithop.rbs
 homepage: https://github.com/ogom/lithop