gsplat 1.0.0

data/lib/gsplat/strategy/default.rb

@@ -0,0 +1,188 @@
+# frozen_string_literal: true
+
+module Gsplat
+  module Strategy
+    # Original 3DGS densification strategy with gsplat refinements.
+    class Default < Base
+      # Upstream-compatible densification defaults.
+      DEFAULTS = {
+        prune_opa: 0.005,
+        grow_grad2d: 0.0002,
+        grow_scale3d: 0.01,
+        grow_scale2d: 0.05,
+        prune_scale3d: 0.1,
+        prune_scale2d: 0.15,
+        refine_scale2d_stop_iter: 0,
+        refine_start_iter: 500,
+        refine_stop_iter: 15_000,
+        reset_every: 3_000,
+        refine_every: 100,
+        pause_refine_after_reset: 0,
+        absgrad: false,
+        revised_opacity: false,
+        key_for_gradient: :means2d
+      }.freeze
+
+      attr_reader :absgrad, :grow_grad2d, :grow_scale2d, :grow_scale3d,
+                  :key_for_gradient, :pause_refine_after_reset, :prune_opa,
+                  :prune_scale2d, :prune_scale3d, :refine_every,
+                  :refine_scale2d_stop_iter, :refine_start_iter,
+                  :refine_stop_iter, :reset_every, :revised_opacity
+
+      def initialize(**options)
+        super()
+        unknown = options.keys - DEFAULTS.keys
+        raise ArgumentError, "unknown options: #{unknown.join(', ')}" unless unknown.empty?
+
+        DEFAULTS.merge(options).each { |name, value| instance_variable_set(:"@#{name}", value) }
+        validate_options!
+      end
+
+      # Creates mutable gradient/radius statistics for a scene.
+      #
+      # @param scene_scale [Numeric]
+      # @return [Hash]
+      def initialize_state(scene_scale:)
+        super.merge(grad2d: nil, count: nil, radii: nil)
+      end
+
+      # rubocop:disable Metrics/ParameterLists
+      def step_post_backward(params:, optimizers:, state:, step:, info:, **_options)
+        check_sanity(params, optimizers)
+        collect_statistics!(params, state, info)
+        refine!(params, optimizers, state, step) if should_refine?(step)
+        reset_due = step.positive? && (step % reset_every).zero?
+        Ops.reset_opacity!(params, optimizers, maximum: 2 * prune_opa) if reset_due
+        state
+      end
+      # rubocop:enable Metrics/ParameterLists
+
+      # rubocop:disable Metrics/AbcSize
+      def refinement_masks(params, state)
+        count = params.fetch(:means).data.shape[0]
+        average = params.fetch(:means).data.class.zeros(count)
+        observed = state[:count].gt(0)
+        average[observed] = state[:grad2d][observed] / state[:count][observed] if observed.any?
+        high = average.gt(grow_grad2d)
+        max_scale = Numo::NMath.exp(params.fetch(:scales).data).max(axis: 1)
+        small = max_scale.le(grow_scale3d * state.fetch(:scene_scale))
+        small &= state[:radii].le(grow_scale2d) if refine_scale2d_stop_iter.positive? && state[:radii]
+        [high & small, high & small.eq(0)]
+      end
+      # rubocop:enable Metrics/AbcSize
+
+      private
+
+      def validate_options!
+        valid_opacity = prune_opa.positive? && prune_opa < 0.5
+        raise ArgumentError, "prune_opa must be in (0,0.5)" unless valid_opacity
+
+        intervals = [refine_every, reset_every]
+        valid_intervals = intervals.all? { |value| value.is_a?(Integer) && value.positive? }
+        raise ArgumentError, "refinement intervals must be positive" unless valid_intervals
+        return if refine_start_iter <= refine_stop_iter
+
+        raise ArgumentError, "refine_start_iter must not exceed refine_stop_iter"
+      end
+
+      # rubocop:disable Metrics/AbcSize
+      def collect_statistics!(params, state, info)
+        projected = info.fetch(key_for_gradient)
+        gradient = if absgrad
+                     projected.respond_to?(:absgrad) ? projected.absgrad : info[:means2d_absgrad]
+                   else
+                     projected.respond_to?(:grad) ? projected.grad : nil
+                   end
+        return unless gradient
+
+        count = params.fetch(:means).data.shape[0]
+        initialize_statistics!(state, count, gradient.class)
+        width = info.fetch(:width)
+        height = info.fetch(:height)
+        normalized = gradient.dup
+        normalized[true, true, 0] *= width / 2.0
+        normalized[true, true, 1] *= height / 2.0
+        norm = (normalized**2).sum(axis: 2)**0.5
+        radii = Gsplat::Ops::TensorOps.data(info.fetch(:radii))
+        radii = radii.max(axis: radii.ndim - 1) if radii.ndim == 3 && radii.shape[-1] == 2
+        visible = radii.gt(0)
+        norm[visible.eq(0)] = 0
+        state[:grad2d] += norm.sum(axis: 0)
+        state[:count] += gradient.class.cast(visible).sum(axis: 0)
+        normalized_radii = radii / [width, height].max.to_f
+        camera_max = normalized_radii.max(axis: 0)
+        larger = camera_max.gt(state[:radii])
+        state[:radii][larger] = camera_max[larger] if larger.any?
+      end
+      # rubocop:enable Metrics/AbcSize
+
+      def initialize_statistics!(state, count, type)
+        return if state[:grad2d]&.shape == [count]
+
+        state[:grad2d] = type.zeros(count)
+        state[:count] = type.zeros(count)
+        state[:radii] = type.zeros(count)
+      end
+
+      def should_refine?(step)
+        return false unless step.between?(refine_start_iter, refine_stop_iter)
+        return false unless (step % refine_every).zero?
+        return true if pause_refine_after_reset.zero?
+
+        (step % reset_every) > pause_refine_after_reset
+      end
+
+      def refine!(params, optimizers, state, step)
+        duplicate_mask, split_mask = refinement_masks(params, state)
+        duplicate_count = Ops.duplicate!(params, optimizers, duplicate_mask)
+        revise_duplicated_opacity!(params, duplicate_mask, duplicate_count) if revised_opacity
+        extended_split = extend_mask(split_mask, duplicate_count)
+        Ops.split!(params, optimizers, extended_split)
+        prune!(params, optimizers, state, step)
+        initialize_statistics!(
+          state,
+          params.fetch(:means).data.shape[0],
+          params.fetch(:means).data.class
+        )
+      end
+
+      def revise_duplicated_opacity!(params, original_mask, duplicate_count)
+        return if duplicate_count.zero?
+
+        variable = params.fetch(:opacities)
+        indices = original_mask.where.to_a
+        active = sigmoid(variable.data[indices])
+        revised = 1 - Numo::NMath.sqrt(1 - active)
+        logits = Numo::NMath.log(revised / (1 - revised))
+        variable.data[indices] = logits
+        variable.data[-duplicate_count..] = logits
+      end
+
+      def extend_mask(mask, count)
+        return mask if count.zero?
+
+        output = Numo::Bit.zeros(mask.size + count)
+        output[0...mask.size] = mask
+        output
+      end
+
+      def prune!(params, optimizers, state, step)
+        opacity = sigmoid(params.fetch(:opacities).data)
+        prune = opacity.lt(prune_opa)
+        if step > reset_every
+          max_scale = Numo::NMath.exp(params.fetch(:scales).data).max(axis: 1)
+          prune |= max_scale.gt(prune_scale3d * state.fetch(:scene_scale))
+          if refine_scale2d_stop_iter.positive? && step < refine_scale2d_stop_iter &&
+             state[:radii]&.shape == prune.shape
+            prune |= state[:radii].gt(prune_scale2d)
+          end
+        end
+        Ops.remove!(params, optimizers, prune)
+      end
+
+      def sigmoid(values)
+        1.0 / (1 + Numo::NMath.exp(-values))
+      end
+    end
+  end
+end

data/lib/gsplat/strategy/mcmc.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+module Gsplat
+  module Strategy
+    # 3D Gaussian Splatting as Markov Chain Monte Carlo strategy.
+    class MCMC < Base
+      # Upstream-compatible relocation and noise defaults.
+      DEFAULTS = {
+        cap_max: 1_000_000,
+        noise_lr: 5e5,
+        refine_start_iter: 500,
+        refine_stop_iter: 25_000,
+        refine_every: 100,
+        min_opacity: 0.005,
+        verbose: false
+      }.freeze
+
+      attr_reader :cap_max, :min_opacity, :noise_lr, :refine_every,
+                  :refine_start_iter, :refine_stop_iter, :verbose
+
+      def initialize(**options)
+        super()
+        unknown = options.keys - DEFAULTS.keys
+        raise ArgumentError, "unknown options: #{unknown.join(', ')}" unless unknown.empty?
+
+        DEFAULTS.merge(options).each { |name, value| instance_variable_set(:"@#{name}", value) }
+        validate_options!
+      end
+
+      # Creates strategy state including the relocation binomial table.
+      #
+      # @param scene_scale [Numeric]
+      # @return [Hash]
+      def initialize_state(scene_scale: 1.0)
+        super.merge(binoms: Gsplat::Ops::Relocation.binomial_table(n_max: 51))
+      end
+
+      # rubocop:disable Metrics/ParameterLists
+      def step_post_backward(params:, optimizers:, state:, step:, info:, **options)
+        raise ArgumentError, "info must be a Hash" unless info.is_a?(Hash)
+
+        learning_rate = options.fetch(:lr)
+        check_sanity(params, optimizers)
+        if should_refine?(step)
+          relocated = relocate_dead!(params, optimizers, state)
+          added = add_new!(params, optimizers, state)
+          log_step(step, relocated, added) if verbose
+        end
+        Ops.inject_position_noise!(params, scaler: learning_rate * noise_lr)
+        state
+      end
+      # rubocop:enable Metrics/ParameterLists
+
+      private
+
+      def validate_options!
+        raise ArgumentError, "cap_max must be positive" unless cap_max.is_a?(Integer) && cap_max.positive?
+        raise ArgumentError, "noise_lr must be non-negative" unless noise_lr >= 0
+        unless refine_every.is_a?(Integer) && refine_every.positive?
+          raise ArgumentError, "refine_every must be positive"
+        end
+        raise ArgumentError, "min_opacity must be in (0,1)" unless min_opacity.positive? && min_opacity < 1
+        return if refine_start_iter <= refine_stop_iter
+
+        raise ArgumentError, "refine_start_iter must not exceed refine_stop_iter"
+      end
+
+      def should_refine?(step)
+        step < refine_stop_iter && step > refine_start_iter && (step % refine_every).zero?
+      end
+
+      def relocate_dead!(params, optimizers, state)
+        opacity = 1.0 / (1.0 + Numo::NMath.exp(-params.fetch(:opacities).data))
+        dead = opacity.le(min_opacity)
+        Ops.relocate!(
+          params,
+          optimizers,
+          dead,
+          binoms: state.fetch(:binoms),
+          min_opacity: min_opacity
+        )
+      end
+
+      def add_new!(params, optimizers, state)
+        current = params.fetch(:means).data.shape[0]
+        target = [cap_max, (1.05 * current).to_i].min
+        Ops.sample_add!(
+          params,
+          optimizers,
+          [target - current, 0].max,
+          binoms: state.fetch(:binoms),
+          min_opacity: min_opacity
+        )
+      end
+
+      def log_step(step, relocated, added)
+        Gsplat.logger.info(
+          "MCMC step #{step}: relocated #{relocated}, added #{added}"
+        )
+      end
+    end
+  end
+end

data/lib/gsplat/strategy/mcmc_ops.rb

@@ -0,0 +1,143 @@
+# frozen_string_literal: true
+
+module Gsplat
+  module Strategy
+    # MCMC-specific parameter edits synchronized with Adam state.
+    module Ops
+      module_function
+
+      # rubocop:disable Metrics/AbcSize
+      def relocate!(params, optimizers, mask, binoms:, **options)
+        min_opacity = options.fetch(:min_opacity, 0.005)
+        rng = options.fetch(:rng, Gsplat.rng)
+        count = params.fetch(:means).data.shape[0]
+        validate_mcmc_mask!(mask, count)
+        dead = Numo::Bit.cast(mask).where.to_a
+        return 0 if dead.empty?
+
+        alive = Numo::Bit.cast(mask).eq(0).where.to_a
+        raise Gsplat::Error, "cannot relocate when every Gaussian is dead" if alive.empty?
+
+        weights = sigmoid_mcmc(params.fetch(:opacities).data[alive])
+        sampled = weighted_indices(weights, dead.size, rng).map { |index| alive.fetch(index) }
+        update_relocation_sources!(params, sampled, binoms, min_opacity)
+        prepare_mcmc_optimizers!(optimizers)
+        params.each do |key, variable|
+          variable.data[*([dead] + Array.new(variable.data.ndim - 1, true))] =
+            variable.data[*([sampled] + Array.new(variable.data.ndim - 1, true))]
+          optimizers.fetch(key).zero_state_at!(sampled)
+          optimizers.fetch(key).zero_state_at!(dead)
+        end
+        dead.size
+      end
+      # rubocop:enable Metrics/AbcSize
+
+      def sample_add!(params, optimizers, count, binoms:, **options)
+        min_opacity = options.fetch(:min_opacity, 0.005)
+        rng = options.fetch(:rng, Gsplat.rng)
+        raise ArgumentError, "count must be a non-negative integer" unless count.is_a?(Integer) && !count.negative?
+        return 0 if count.zero?
+
+        weights = sigmoid_mcmc(params.fetch(:opacities).data)
+        sampled = weighted_indices(weights, count, rng)
+        update_relocation_sources!(params, sampled, binoms, min_opacity)
+        prepare_mcmc_optimizers!(optimizers)
+        params.each do |key, variable|
+          rows = variable.data[*([sampled] + Array.new(variable.data.ndim - 1, true))].dup
+          variable.replace_data!(append_mcmc_rows(variable.data, rows))
+          optimizers.fetch(key).append!(count)
+        end
+        count
+      end
+
+      # rubocop:disable Metrics/AbcSize
+      def inject_position_noise!(params, scaler:, rng: Gsplat.rng)
+        return params if scaler.zero?
+
+        opacities = sigmoid_mcmc(params.fetch(:opacities).data)
+        scales = Numo::NMath.exp(params.fetch(:scales).data)
+        covariances, = Gsplat.quat_scale_to_covar_preci(
+          params.fetch(:quats).data,
+          scales,
+          compute_preci: false
+        )
+        noise = params.fetch(:means).data.class.zeros(*params.fetch(:means).data.shape)
+        noise.shape[0].times do |index|
+          gate = 1.0 / (1.0 + ::Math.exp(-100.0 * ((1.0 - opacities[index].to_f) - 0.995)))
+          standard = noise.class.cast(Array.new(3) { normal_mcmc_sample(rng) })
+          noise[index, true] = covariances[index, true, true].dot(standard) * gate * scaler
+        end
+        params.fetch(:means).data[] = params.fetch(:means).data + noise
+        params
+      end
+      # rubocop:enable Metrics/AbcSize
+
+      def update_relocation_sources!(params, sampled, binoms, min_opacity)
+        source_opacities = sigmoid_mcmc(params.fetch(:opacities).data[sampled])
+        source_scales = Numo::NMath.exp(params.fetch(:scales).data[sampled, true])
+        counts = sampled.tally
+        ratios = Numo::Int32.cast(sampled.map { |index| counts.fetch(index) + 1 })
+        opacities, scales = Gsplat.relocation(source_opacities, source_scales, ratios, binoms: binoms)
+        epsilon = Numo::SFloat::EPSILON
+        opacities = clamp_mcmc(opacities, min_opacity, 1.0 - epsilon)
+        params.fetch(:opacities).data[sampled] = Numo::NMath.log(opacities / (1.0 - opacities))
+        params.fetch(:scales).data[sampled, true] = Numo::NMath.log(scales)
+      end
+      private_class_method :update_relocation_sources!
+
+      def weighted_indices(weights, count, rng)
+        cumulative = weights.to_a.each_with_object([]) do |weight, sums|
+          sums << (weight.to_f + (sums.last || 0.0))
+        end
+        valid_sum = cumulative.last&.positive? && cumulative.last.finite?
+        raise Gsplat::Error, "sampling weights must have positive finite sum" unless valid_sum
+
+        Array.new(count) do
+          draw = rng.rand * cumulative.last
+          cumulative.bsearch_index { |value| value > draw } || (cumulative.length - 1)
+        end
+      end
+      private_class_method :weighted_indices
+
+      def append_mcmc_rows(array, rows)
+        output = array.class.zeros(*([array.shape[0] + rows.shape[0]] + array.shape[1..]))
+        output[*([0...array.shape[0]] + Array.new(array.ndim - 1, true))] = array
+        output[*([array.shape[0]...output.shape[0]] + Array.new(array.ndim - 1, true))] = rows
+        output
+      end
+      private_class_method :append_mcmc_rows
+
+      def prepare_mcmc_optimizers!(optimizers)
+        optimizers.each_value(&:state)
+      end
+      private_class_method :prepare_mcmc_optimizers!
+
+      def validate_mcmc_mask!(mask, count)
+        return if mask.is_a?(Numo::NArray) && mask.shape == [count]
+
+        actual = mask.respond_to?(:shape) ? mask.shape.inspect : mask.class.to_s
+        raise ShapeError, "expected mask [#{count}], got #{actual}"
+      end
+      private_class_method :validate_mcmc_mask!
+
+      def sigmoid_mcmc(values)
+        1.0 / (1.0 + Numo::NMath.exp(-values))
+      end
+      private_class_method :sigmoid_mcmc
+
+      def clamp_mcmc(values, minimum, maximum)
+        output = values.dup
+        output[output.lt(minimum)] = minimum
+        output[output.gt(maximum)] = maximum
+        output
+      end
+      private_class_method :clamp_mcmc
+
+      def normal_mcmc_sample(rng)
+        radius = ::Math.sqrt(-2.0 * ::Math.log([rng.rand, Float::MIN].max))
+        radius * ::Math.cos(2.0 * ::Math::PI * rng.rand)
+      end
+      private_class_method :normal_mcmc_sample
+    end
+  end
+end

data/lib/gsplat/strategy/ops.rb

@@ -0,0 +1,165 @@
+# frozen_string_literal: true
+
+module Gsplat
+  # Densification and relocation policies for training.
+  module Strategy
+    # Structural parameter edits synchronized with Adam moment buffers.
+    module Ops
+      module_function
+
+      # Appends exact copies of selected Gaussian rows and zeroed moments.
+      #
+      # @return [Integer] number of rows appended
+      def duplicate!(params, optimizers, mask)
+        indices = selected_indices(mask, parameter_count(params))
+        return 0 if indices.empty?
+
+        prepare_optimizers!(optimizers)
+        params.each do |key, variable|
+          appended = select_rows(variable.data, indices)
+          variable.replace_data!(append_rows(variable.data, appended))
+          optimizers.fetch(key).append!(indices.size)
+        end
+        indices.size
+      end
+
+      # Removes selected Gaussian rows and matching optimizer moments.
+      #
+      # @return [Integer] number of rows removed
+      def remove!(params, optimizers, mask)
+        validate_mask!(mask, parameter_count(params))
+        keep = Numo::Bit.cast(mask).eq(0)
+        removed = mask.count_true
+        return 0 if removed.zero?
+
+        prepare_optimizers!(optimizers)
+        params.each do |key, variable|
+          variable.replace_data!(select_rows(variable.data, keep))
+          optimizers.fetch(key).select!(keep)
+        end
+        removed
+      end
+
+      # Replaces selected Gaussians with two sampled children.
+      #
+      # @return [Integer] number of parents split
+      def split!(params, optimizers, mask, rng: Gsplat.rng)
+        count = parameter_count(params)
+        indices = selected_indices(mask, count)
+        return 0 if indices.empty?
+
+        children = split_children(params, indices, rng)
+        keep = Numo::Bit.cast(mask).eq(0)
+        prepare_optimizers!(optimizers)
+        params.each do |key, variable|
+          retained = select_rows(variable.data, keep)
+          variable.replace_data!(append_rows(retained, children.fetch(key)))
+          optimizer = optimizers.fetch(key)
+          optimizer.select!(keep)
+          optimizer.append!(indices.size * 2)
+        end
+        indices.size
+      end
+
+      def reset_opacity!(params, optimizers, maximum:)
+        raise ArgumentError, "maximum opacity must be in (0,1)" unless maximum.positive? && maximum < 1
+
+        variable = params.fetch(:opacities)
+        cap = ::Math.log(maximum / (1 - maximum))
+        values = variable.data.dup
+        above = values.gt(cap)
+        values[above] = cap if above.any?
+        variable.replace_data!(values)
+        optimizer = optimizers.fetch(:opacities)
+        optimizer.state
+        optimizer.zero_state_at!(0...values.shape[0])
+        above.count_true
+      end
+
+      def parameter_count(params)
+        raise ArgumentError, "params must not be empty" if params.empty?
+
+        params.values.first.data.shape[0]
+      end
+      private_class_method :parameter_count
+
+      def selected_indices(mask, count)
+        validate_mask!(mask, count)
+        Numo::Bit.cast(mask).where.to_a
+      end
+      private_class_method :selected_indices
+
+      def validate_mask!(mask, count)
+        return if mask.is_a?(Numo::NArray) && mask.shape == [count]
+
+        actual = mask.respond_to?(:shape) ? mask.shape.inspect : mask.class.to_s
+        raise ShapeError, "expected mask [#{count}], got #{actual}"
+      end
+      private_class_method :validate_mask!
+
+      def prepare_optimizers!(optimizers)
+        optimizers.each_value(&:state)
+      end
+      private_class_method :prepare_optimizers!
+
+      def select_rows(array, selection)
+        array[*([selection] + Array.new(array.ndim - 1, true))].dup
+      end
+      private_class_method :select_rows
+
+      def append_rows(array, rows)
+        output = array.class.zeros(*([array.shape[0] + rows.shape[0]] + array.shape[1..]))
+        output[*([0...array.shape[0]] + Array.new(array.ndim - 1, true))] = array
+        output[*([array.shape[0]...output.shape[0]] + Array.new(array.ndim - 1, true))] = rows
+        output
+      end
+      private_class_method :append_rows
+
+      def split_children(params, indices, rng)
+        children = params.to_h do |key, variable|
+          selected = select_rows(variable.data, indices)
+          doubled = repeat_rows(selected, 2)
+          [key, doubled]
+        end
+        children[:scales] -= ::Math.log(1.6)
+        children[:means] += split_offsets(params, indices, rng)
+        children
+      end
+      private_class_method :split_children
+
+      def repeat_rows(array, repeat)
+        output = array.class.zeros(*([array.shape[0] * repeat] + array.shape[1..]))
+        array.shape[0].times do |index|
+          repeat.times do |copy|
+            output[*([(index * repeat) + copy] + Array.new(array.ndim - 1, true))] =
+              array[*([index] + Array.new(array.ndim - 1, true))]
+          end
+        end
+        output
+      end
+      private_class_method :repeat_rows
+
+      def split_offsets(params, indices, rng)
+        quaternions = select_rows(params.fetch(:quats).data, indices)
+        log_scales = select_rows(params.fetch(:scales).data, indices)
+        rotations = Math::Quaternion.to_rotmat(quaternions)
+        output = params.fetch(:means).data.class.zeros(indices.size * 2, 3)
+        indices.size.times do |index|
+          2.times do |child|
+            noise = output.class.cast(Array.new(3) { normal_sample(rng) })
+            scaled = noise * Numo::NMath.exp(log_scales[index, true])
+            output[(index * 2) + child, true] = rotations[index, true, true].dot(scaled)
+          end
+        end
+        output
+      end
+      private_class_method :split_offsets
+
+      def normal_sample(rng)
+        radius = ::Math.sqrt(-2 * ::Math.log([rng.rand, Float::MIN].max))
+        radius * ::Math.cos(2 * ::Math::PI * rng.rand)
+      end
+      private_class_method :normal_sample
+    end
+  end
+end

data/lib/gsplat/training/config.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+module Gsplat
+  module Training
+    # Trainer hyperparameters matching the upstream simple trainer defaults.
+    class Config
+      # Default training, optimizer, evaluation, and output options.
+      DEFAULTS = {
+        max_steps: 30_000,
+        batch_size: 1,
+        sh_degree: 3,
+        sh_degree_interval: 1_000,
+        ssim_lambda: 0.2,
+        init_opacity: 0.1,
+        init_scale: 1.0,
+        means_lr: 1.6e-4,
+        means_lr_final: 1.6e-6,
+        scales_lr: 5e-3,
+        quats_lr: 1e-3,
+        opacities_lr: 5e-2,
+        sh0_lr: 2.5e-3,
+        shN_lr: 1.25e-4,
+        opacity_reg: 0.0,
+        scale_reg: 0.0,
+        eval_steps: [7_000, 30_000],
+        save_steps: [7_000, 30_000],
+        log_every: 100,
+        random_background: false,
+        near_plane: 0.01,
+        far_plane: 1e10,
+        tile_size: 16,
+        rasterize_mode: "classic",
+        model_type: :three_d,
+        output_dir: "results",
+        seed: 42
+      }.freeze
+
+      # rubocop:disable Naming/MethodName
+      attr_reader :batch_size, :eval_steps, :far_plane, :init_opacity,
+                  :init_scale, :log_every, :max_steps, :means_lr,
+                  :means_lr_final, :model_type, :near_plane, :opacities_lr,
+                  :opacity_reg, :output_dir, :quats_lr, :random_background,
+                  :rasterize_mode, :save_steps, :scales_lr, :scale_reg, :seed,
+                  :sh0_lr, :shN_lr, :sh_degree, :sh_degree_interval,
+                  :ssim_lambda, :tile_size
+      # rubocop:enable Naming/MethodName
+
+      def initialize(**options)
+        unknown = options.keys - DEFAULTS.keys
+        raise ArgumentError, "unknown trainer options: #{unknown.join(', ')}" unless unknown.empty?
+
+        DEFAULTS.merge(options).each do |name, value|
+          value = value.dup if value.is_a?(Array)
+          instance_variable_set(:"@#{name}", value)
+        end
+        validate!
+      end
+
+      # Returns an independent hash suitable for checkpoint metadata.
+      #
+      # @return [Hash{Symbol=>Object}]
+      def to_h
+        DEFAULTS.keys.to_h { |name| [name, public_send(name)] }
+      end
+
+      private
+
+      def validate!
+        positive_integers = %i[max_steps batch_size sh_degree_interval log_every tile_size]
+        invalid = positive_integers.find do |name|
+          value = public_send(name)
+          !value.is_a?(Integer) || !value.positive?
+        end
+        raise ArgumentError, "#{invalid} must be a positive integer" if invalid
+        raise ArgumentError, "sh_degree must be in 0..4" unless sh_degree.is_a?(Integer) && sh_degree.between?(0, 4)
+        raise ArgumentError, "ssim_lambda must be between 0 and 1" unless ssim_lambda.between?(0.0, 1.0)
+        unless %i[three_d two_d 3dgs 2dgs].include?(model_type.to_sym)
+          raise ArgumentError, "model_type must be :three_d/:3dgs or :two_d/:2dgs"
+        end
+
+        learning_rates = %i[means_lr means_lr_final scales_lr quats_lr opacities_lr sh0_lr shN_lr]
+        invalid_rate = learning_rates.find { |name| !public_send(name).positive? }
+        raise ArgumentError, "#{invalid_rate} must be positive" if invalid_rate
+
+        regularizers = %i[opacity_reg scale_reg]
+        invalid_regularizer = regularizers.find { |name| public_send(name).negative? }
+        raise ArgumentError, "#{invalid_regularizer} must be non-negative" if invalid_regularizer
+      end
+    end
+  end
+end