lithop 0.1.0 → 0.3.0

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

@@ -3,11 +3,15 @@
 module Lithop
   # Indexes vertices and triangles for a 3MF mesh resource.
   class ThreeMFMesh
-    attr_reader :vertices, :vertex_indices, :triangle_count
+    NATIVE_BATCH_SIZE = 8_192
+    MAXIMUM_NATIVE_TOPOLOGY_KEY = (2**63) - 1
+    class UnsupportedNativeTopology < StandardError; end
+
+    attr_reader :vertices, :vertex_indices, :triangle_count, :native_mesh
 
     def initialize(triangles:)
       @triangles = triangles
-      index_resources
+      Native.enabled? ? index_native_resources : index_ruby_resources
     end
 
     def each_indexed_triangle
@@ -18,9 +22,74 @@ module Lithop
       end
     end
 
+    def native_indexed? = !native_mesh.nil?
+
+    def vertex_count = native_indexed? ? native_mesh.vertex_count : vertices.length
+
+    def center
+      return native_mesh.center if native_indexed?
+
+      axes = vertices.transpose
+      axes.map { |values| (values.min + values.max) / 2.0 }
+    end
+
     private
 
-    def index_resources
+    def index_native_resources
+      if @triangles.respond_to?(:native_indexed_mesh)
+        @native_mesh = @triangles.native_indexed_mesh
+        raise InputError, "3MF mesh contains no triangles" if native_mesh.vertex_count.zero?
+
+        @triangle_count = native_mesh.triangle_count
+        @vertices = nil
+        @vertex_indices = nil
+        return
+      end
+
+      @native_mesh = Native::MeshBuilder.new
+      coordinates = []
+      topology_keys = []
+      count = 0
+      @triangles.each do |triangle|
+        validate_triangle!(triangle)
+        triangle.each do |vertex|
+          coordinates.concat(coordinates(vertex))
+          topology_keys << native_topology_key(vertex)
+        end
+        count += 1
+        flush_native_batch(coordinates, topology_keys) if (count % NATIVE_BATCH_SIZE).zero?
+      end
+      flush_native_batch(coordinates, topology_keys)
+      raise InputError, "3MF mesh contains no triangles" if native_mesh.vertex_count.zero?
+
+      @triangle_count = native_mesh.triangle_count
+      @vertices = nil
+      @vertex_indices = nil
+    rescue UnsupportedNativeTopology
+      @native_mesh = nil
+      index_ruby_resources
+    end
+
+    def flush_native_batch(coordinates, topology_keys)
+      return if coordinates.empty?
+
+      native_mesh.add_batch(coordinates, topology_keys)
+      coordinates.clear
+      topology_keys.clear
+    end
+
+    def native_topology_key(vertex)
+      return -1 unless vertex.respond_to?(:topology)
+
+      topology = vertex.topology
+      unless topology.is_a?(Integer) && topology.between?(0, MAXIMUM_NATIVE_TOPOLOGY_KEY)
+        raise UnsupportedNativeTopology
+      end
+
+      topology
+    end
+
+    def index_ruby_resources
       @vertices = []
       @vertex_indices = {}
       @triangle_count = 0

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

@@ -2,12 +2,18 @@
 
 module Lithop
   # Serializes model resources and build items into a 3MF model document.
+  # rubocop:disable-next Metrics/ClassLength
   class ThreeMFModelWriter
     CUSTOM_NAMESPACE = "https://github.com/ogom/lithop/3mf/v1"
+    BAMBU_STUDIO_NAMESPACE = "http://schemas.bambulab.com/package/2021"
+    BAMBU_STUDIO_APPLICATION = "BambuStudio-02.08.03.66"
+    PRODUCTION_NAMESPACE = "http://schemas.microsoft.com/3dmanufacturing/production/2015/06"
+    MODEL_PATH = "3D/3dmodel.model"
     BASE_MATERIALS_ID = 1
     COLOR_GROUP_ID = 2
     FIRST_OBJECT_ID = 3
     Result = Data.define(:vertex_count, :triangle_count, :triangle_counts_by_material)
+    Assembly = Data.define(:id, :name, :region, :object_ids, :component_origins)
 
     def initialize(archive, parts, profile, instrumentation: Instrumentation.new, settings: nil)
       @archive = archive
@@ -18,23 +24,20 @@ module Lithop
     end
 
     def write
+      object_ids = part_object_ids
+      assemblies = build_assemblies(object_ids)
+      return write_bambu_multi_plate(object_ids, assemblies) if bambu_multi_plate_project?
+
       measure_xml do
+        @archive.put_next_entry(MODEL_PATH)
         @archive.write(model_header)
         write_materials
       end
-      object_ids, result = write_parts
-      assembly_id = object_ids.max + 1
+      result = write_parts(object_ids)
       measure_xml do
-        write_assembly(assembly_id, object_ids)
-        @archive.write("  </resources>\n  <build>\n    <item objectid=\"#{assembly_id}\"/>\n  </build>\n</model>\n")
-        ThreeMFBambuMetadata.new(
-          archive: @archive,
-          assembly_id:,
-          object_ids:,
-          parts: @parts,
-          profile: @profile,
-          settings: @settings
-        ).write
+        assemblies.each { |assembly| write_assembly(assembly) }
+        write_build(assemblies)
+        write_bambu_metadata(object_ids, assemblies)
       end
       result
     end
@@ -49,42 +52,230 @@ module Lithop
       @archive.write("    </m:colorgroup>\n")
     end
 
-    def write_parts
+    def part_object_ids
+      return @parts.each_index.map { |index| index + FIRST_OBJECT_ID }.freeze unless bambu_multi_plate_project?
+
+      next_id = 1
+      @parts.group_by(&:region).values.flat_map do |parts|
+        ids = Array.new(parts.length) do
+          value = next_id
+          next_id += 1
+          value
+        end
+        next_id += 1
+        ids
+      end.freeze
+    end
+
+    def write_parts(object_ids)
       vertex_count = 0
       triangle_counts = {}
-      object_ids = @parts.each_with_index.map do |part, index|
-        object_id = index + FIRST_OBJECT_ID
+      object_ids.zip(@parts).each do |object_id, part|
         mesh = @instrumentation.measure(:three_mf_indexing) do
           ThreeMFMesh.new(triangles: part.triangles)
         end
         measure_xml do
-          ThreeMFPartWriter.new(archive: @archive, profile: @profile).write(object_id, part.material, mesh)
+          ThreeMFPartWriter.new(archive: @archive, profile: @profile).write(object_id, part, mesh)
         end
         part.triangles.release_cache! if part.triangles.respond_to?(:release_cache!)
-        vertex_count += mesh.vertices.length
-        triangle_counts[part.material] = mesh.triangle_count
-        object_id
+        vertex_count += mesh.vertex_count
+        triangle_counts[part.material] = triangle_counts.fetch(part.material, 0) + mesh.triangle_count
+      end
+      Result.new(
+        vertex_count:,
+        triangle_count: triangle_counts.values.sum,
+        triangle_counts_by_material: triangle_counts.freeze
+      )
+    end
+
+    def write_bambu_multi_plate(object_ids, assemblies)
+      result = write_external_parts(object_ids, assemblies)
+      write_root_model(assemblies)
+      write_model_relationships(assemblies)
+      write_bambu_metadata(object_ids, assemblies)
+      result
+    end
+
+    # rubocop:disable-next Metrics/AbcSize, Metrics/MethodLength
+    def write_external_parts(object_ids, assemblies)
+      parts_by_object_id = object_ids.zip(@parts).to_h
+      vertex_count = 0
+      triangle_counts = {}
+      assemblies.each_with_index do |assembly, index|
+        @archive.put_next_entry("3D/Objects/object_#{index + 1}.model")
+        measure_xml do
+          @archive.write(submodel_header)
+          write_materials
+        end
+        assembly.object_ids.each do |object_id|
+          part = parts_by_object_id.fetch(object_id)
+          mesh = @instrumentation.measure(:three_mf_indexing) do
+            ThreeMFMesh.new(triangles: part.triangles)
+          end
+          center = mesh_center(mesh)
+          assembly.component_origins[object_id] = component_origin(
+            center, assembly.component_origins.fetch(object_id)
+          )
+          measure_xml do
+            ThreeMFPartWriter.new(
+              archive: @archive, profile: @profile, production: true, origin: center
+            ).write(object_id, part, mesh)
+          end
+          part.triangles.release_cache! if part.triangles.respond_to?(:release_cache!)
+          vertex_count += mesh.vertex_count
+          triangle_counts[part.material] = triangle_counts.fetch(part.material, 0) + mesh.triangle_count
+        end
+        measure_xml do
+          @archive.write("  </resources>\n  <build/>\n</model>\n")
+        end
       end
-      result = Result.new(
+      Result.new(
         vertex_count:,
         triangle_count: triangle_counts.values.sum,
         triangle_counts_by_material: triangle_counts.freeze
       )
-      [object_ids, result]
+    end
+
+    def write_root_model(assemblies)
+      @archive.put_next_entry(MODEL_PATH)
+      measure_xml do
+        @archive.write(bambu_multi_plate_model_header)
+        assemblies.each_with_index { |assembly, index| write_assembly(assembly, index + 1) }
+        write_build(assemblies)
+      end
+    end
+
+    def write_model_relationships(assemblies)
+      @archive.put_next_entry("3D/_rels/3dmodel.model.rels")
+      @archive.write("<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n")
+      @archive.write("<Relationships xmlns=\"#{ThreeMF::RELATIONSHIP_NAMESPACE}\">\n")
+      assemblies.each_with_index do |_assembly, index|
+        @archive.write(
+          " <Relationship Target=\"/3D/Objects/object_#{index + 1}.model\" Id=\"rel-#{index + 1}\" " \
+          "Type=\"#{ThreeMF::MODEL_RELATIONSHIP}\"/>\n"
+        )
+      end
+      @archive.write("</Relationships>\n")
+    end
+
+    def write_bambu_metadata(object_ids, assemblies)
+      ThreeMFBambuMetadata.new(
+        archive: @archive,
+        object_ids:,
+        assemblies:,
+        parts: @parts,
+        profile: @profile,
+        settings: @settings
+      ).write
     end
 
     def measure_xml(&)
       @instrumentation.measure(:three_mf_xml_zip, &)
     end
 
-    def write_assembly(assembly_id, object_ids)
-      @archive.write("    <object id=\"#{assembly_id}\" type=\"model\" name=\"Lithop CMYW lithophane\">\n")
+    def build_assemblies(object_ids)
+      groups = if separate_z_plates?
+                 object_ids.zip(@parts).group_by { |_object_id, part| part.region }
+               else
+                 { nil => object_ids.zip(@parts) }
+               end
+      groups.map do |region, entries|
+        Assembly.new(
+          id: entries.map(&:first).max + 1,
+          name: assembly_name(region),
+          region:,
+          object_ids: entries.map(&:first).freeze,
+          component_origins: entries.to_h { |object_id, part| [object_id, [0.0, 0.0, part.build_z_offset]] }
+        )
+      end.freeze
+    end
+
+    def separate_z_plates?
+      @settings&.separate_z_parts && @parts.all?(&:region)
+    end
+
+    def bambu_multi_plate_project? = @settings&.bambu_project && separate_z_plates?
+
+    def assembly_name(region)
+      return "Lithop CMYW lithophane" unless region
+      return "Top White" if region == "top_white"
+
+      region.sub("color_region_", "Color region ")
+    end
+
+    def write_assembly(assembly, submodel_index = nil)
+      uuid = submodel_index ? production_uuid(assembly.id) : ""
+      @archive.write("    <object id=\"#{assembly.id}\"#{uuid} type=\"model\" name=\"#{assembly.name}\">\n")
       @archive.write("      <components>\n")
-      object_ids.each { |object_id| @archive.write("        <component objectid=\"#{object_id}\"/>\n") }
+      assembly.object_ids.each_with_index do |object_id, index|
+        transform = component_transform(assembly.component_origins.fetch(object_id))
+        path = submodel_index ? %( p:path="/3D/Objects/object_#{submodel_index}.model") : ""
+        uuid = submodel_index ? production_uuid((assembly.id * 1000) + index + 1) : ""
+        @archive.write("        <component#{path} objectid=\"#{object_id}\"#{uuid}#{transform}/>\n")
+      end
       @archive.write("      </components>\n    </object>\n")
     end
 
+    def component_transform(origin)
+      return "" if origin.all?(&:zero?)
+
+      %( transform="1 0 0 0 1 0 0 0 1 #{origin.map { |value| format_number(value) }.join(" ")}")
+    end
+
+    def format_number(number) = format("%.9g", number)
+
+    def write_build(assemblies)
+      @archive.write("  </resources>\n  <build>\n")
+      assemblies.each do |assembly|
+        attributes = if bambu_multi_plate_project?
+                       %(#{build_uuid(assembly.id)} transform="#{build_transform(assembly)}" printable="1")
+                     else
+                       ""
+                     end
+        @archive.write("    <item objectid=\"#{assembly.id}\"#{attributes}/>\n")
+      end
+      @archive.write("  </build>\n</model>\n")
+    end
+
+    def production_uuid(identifier)
+      %( p:UUID="#{format("%08x", identifier)}-61cb-4c03-9d28-80fed5dfa1dc")
+    end
+
+    def build_uuid(identifier)
+      %( p:UUID="#{format("%08x", identifier)}-b1ec-4553-aec9-835e5b724bb4")
+    end
+
+    def build_transform(assembly)
+      x, y = [
+        [48.0, 30.0],
+        [300.160253, 37.8003226],
+        [52.2484968, -205.366274],
+        [288.0, -210.0]
+      ].fetch(plate_index(assembly))
+      "1 0 0 0 1 0 0 0 1 #{format_number(x)} #{format_number(y)} 0"
+    end
+
+    def mesh_center(mesh)
+      mesh.center
+    end
+
+    def component_origin(center, base_origin)
+      [center[0], center[1], center[2] + base_origin[2]]
+    end
+
+    def plate_index(assembly)
+      return 3 if assembly.region == "top_white"
+
+      assembly.region.delete_prefix("color_region_").to_i - 1
+    end
+
     def model_header
+      return bambu_multi_plate_model_header if bambu_multi_plate_project?
+
+      inline_model_header
+    end
+
+    def inline_model_header
       <<~XML
         <?xml version="1.0" encoding="UTF-8"?>
         <model unit="millimeter" xml:lang="en-US" requiredextensions="m"
@@ -101,6 +292,40 @@ module Lithop
       XML
     end
 
+    def bambu_multi_plate_model_header
+      <<~XML
+        <?xml version="1.0" encoding="UTF-8"?>
+        <model unit="millimeter" xml:lang="en-US" requiredextensions="p"
+          xmlns="#{ThreeMF::CORE_NAMESPACE}"
+          xmlns:BambuStudio="#{BAMBU_STUDIO_NAMESPACE}"
+          xmlns:p="#{PRODUCTION_NAMESPACE}"
+          xmlns:lithop="#{CUSTOM_NAMESPACE}">
+          <metadata name="Title">Lithop CMYW lithophane</metadata>
+          <metadata name="Application">#{BAMBU_STUDIO_APPLICATION}</metadata>
+          <metadata name="BambuStudio:3mfVersion">1</metadata>
+          <metadata name="lithop:Application" preserve="1">Lithop #{Lithop::VERSION}</metadata>
+          <metadata name="Description">Physical CMY subtractive layers with variable White luminance thickness.</metadata>
+          <metadata name="lithop:FilamentBundle" preserve="1">#{@profile.name}</metadata>
+          <metadata name="lithop:FilamentProduct" preserve="1">#{@profile.product_url}</metadata>
+          <metadata name="lithop:PrintingGuide" preserve="1">#{@profile.reference_url}</metadata>
+          <resources>
+      XML
+    end
+
+    def submodel_header
+      <<~XML
+        <?xml version="1.0" encoding="UTF-8"?>
+        <model unit="millimeter" xml:lang="en-US" requiredextensions="m p"
+          xmlns="#{ThreeMF::CORE_NAMESPACE}"
+          xmlns:m="#{ThreeMF::MATERIAL_NAMESPACE}"
+          xmlns:BambuStudio="#{BAMBU_STUDIO_NAMESPACE}"
+          xmlns:p="#{PRODUCTION_NAMESPACE}"
+          xmlns:lithop="#{CUSTOM_NAMESPACE}">
+          <metadata name="BambuStudio:3mfVersion">1</metadata>
+          <resources>
+      XML
+    end
+
     def material_xml(material)
       name = "#{@profile.manufacturer} #{material.name} (#{material.color_code})"
       <<~XML

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

@@ -3,18 +3,25 @@
 module Lithop
   # Serializes one indexed material mesh into a 3MF model document.
   class ThreeMFPartWriter
-    def initialize(archive:, profile:)
+    XML_BATCH_SIZE = 8_192
+
+    def initialize(archive:, profile:, production: false, origin: nil)
       @archive = archive
       @profile = profile
+      @production = production
+      @origin = origin || [0.0, 0.0, 0.0]
     end
 
-    def write(object_id, material, mesh)
+    def write(object_id, part, mesh)
+      material = part.material
       material_index = @profile.materials.index { |candidate| candidate.channel == material }
-      name = @profile.materials.fetch(material_index).name
+      name = part.name || @profile.materials.fetch(material_index).name
+      region = part.region ? " lithop:region=\"#{part.region}\"" : ""
+      uuid = @production ? %( p:UUID="00000000-0000-4000-8000-#{format("%012d", object_id)}") : ""
       @archive.write(
-        "    <object id=\"#{object_id}\" type=\"model\" name=\"#{name}\" " \
+        "    <object id=\"#{object_id}\"#{uuid} type=\"model\" name=\"#{name}\" " \
         "pid=\"#{ThreeMFModelWriter::COLOR_GROUP_ID}\" pindex=\"#{material_index}\" " \
-        "lithop:channel=\"#{material}\">\n"
+        "lithop:channel=\"#{material}\"#{region}>\n"
       )
       @archive.write("      <mesh>\n        <vertices>\n")
       write_vertices(mesh)
@@ -26,12 +33,21 @@ module Lithop
     private
 
     def write_vertices(mesh)
+      return write_indexed_native_vertices(mesh) if mesh.native_indexed?
+      return write_native_vertices(mesh) if Native.enabled?
+
       mesh.vertices.each do |x, y, z|
-        @archive.write("          <vertex x=\"#{number(x)}\" y=\"#{number(y)}\" z=\"#{number(z)}\"/>\n")
+        @archive.write(
+          "          <vertex x=\"#{number(x - @origin[0])}\" y=\"#{number(y - @origin[1])}\" " \
+          "z=\"#{number(z - @origin[2])}\"/>\n"
+        )
       end
     end
 
     def write_triangles(mesh)
+      return write_indexed_native_triangles(mesh) if mesh.native_indexed?
+      return write_native_triangles(mesh) if Native.enabled?
+
       count = 0
       mesh.each_indexed_triangle do |vertices|
         @archive.write(
@@ -44,6 +60,35 @@ module Lithop
       raise InputError, "3MF triangle enumerables must be repeatable"
     end
 
+    def write_native_vertices(mesh)
+      mesh.vertices.each_slice(XML_BATCH_SIZE) do |vertices|
+        @archive.write(Native.vertex_xml(vertices.flatten, @origin))
+      end
+    end
+
+    def write_indexed_native_vertices(mesh)
+      0.step(mesh.vertex_count - 1, XML_BATCH_SIZE) do |offset|
+        @archive.write(mesh.native_mesh.vertex_xml(offset, XML_BATCH_SIZE, @origin))
+      end
+    end
+
+    def write_native_triangles(mesh)
+      count = 0
+      mesh.each_indexed_triangle.each_slice(XML_BATCH_SIZE) do |triangles|
+        @archive.write(Native.triangle_xml(triangles.flatten))
+        count += triangles.length
+      end
+      return if count == mesh.triangle_count
+
+      raise InputError, "3MF triangle enumerables must be repeatable"
+    end
+
+    def write_indexed_native_triangles(mesh)
+      0.step(mesh.triangle_count - 1, XML_BATCH_SIZE) do |offset|
+        @archive.write(mesh.native_mesh.triangle_xml(offset, XML_BATCH_SIZE))
+      end
+    end
+
     def number(value) = format("%.9g", value)
   end
 end

data/lib/lithop/formats/three_mf.rb

@@ -18,8 +18,12 @@ module Lithop
     MODEL_RELATIONSHIP = "http://schemas.microsoft.com/3dmanufacturing/2013/01/3dmodel"
     MODEL_CONTENT_TYPE = "application/vnd.ms-package.3dmanufacturing-3dmodel+xml"
     ZIP_MUTEX = Mutex.new
-    # Triangles are indexed and then serialized, so their enumerable must be replayable.
-    Part = Data.define(:material, :triangles)
+    # The Rust indexer consumes triangles once; the Ruby comparison path requires replayable input.
+    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

@@ -9,7 +9,9 @@ module Lithop
     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
+    )
 
     def initialize(settings)
       @settings = settings
@@ -21,12 +23,8 @@ 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)
-      sampled = @placement.call(image, @settings.sampling_grid).cast(:uchar)
+      image = normalized_image(path, access:)
+      sampled = @placement.call(image, @settings.sampling_grid).cast(:uchar).copy_memory
 
       rgbs = rgb_components(sampled)
       color_samples = rgbs.map { |rgb| color_sample(rgb) }
@@ -41,20 +39,62 @@ module Lithop
         cmys: color_samples.map(&:first),
         cmy_densities: color_samples.map(&:last),
         white_densities: rgbs.map { |rgb| white_density(rgb) },
-        color_cells: result_color_cells
+        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:)
+      image = normalized_image(path, access: :sequential, sampling_grids: [grid])
+      @placement.call(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)
+      image = load_image(path, access:, sampling_grids:)
+      image = image.autorot
+      validate_input!(image)
+      image = image.flatten(background: [255, 255, 255]) if image.has_alpha?
+      adjust_image(to_srgb(image))
+    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
 
-      @svg_loader.call(path, access:)
+      @svg_loader.call(path, access:, sampling_grids:)
+    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)
@@ -72,6 +112,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?