gsplat 1.0.0

data/lib/gsplat/ops/accumulate.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+require_relative "../backend/ruby/accumulate"
+require_relative "../backend/ruby/accumulate_backward"
+
+# Brute-force reference rasterization API.
+module Gsplat
+  # Differentiable operation classes and low-level tensor adapters.
+  module Ops
+    # Differentiable reference alpha compositor.
+    class Accumulate < Autograd::Function
+      class << self
+        # rubocop:disable Metrics/ParameterLists
+        def forward(context, means2d, conics, opacities, colors, backgrounds, width, height)
+          # rubocop:enable Metrics/ParameterLists
+          render_colors, render_alphas, last_ids = Backend.dispatch(
+            :accumulate_forward,
+            means2d,
+            conics,
+            opacities,
+            colors,
+            backgrounds,
+            width,
+            height
+          )
+          context.save(
+            means2d, conics, opacities, colors, backgrounds, width, height,
+            render_alphas, last_ids
+          )
+          [render_colors, render_alphas]
+        end
+
+        # Propagates color and alpha gradients through the reference compositor.
+        # @api private
+        def backward(context, grad_render_colors, grad_render_alphas)
+          saved = context.saved_values
+          gradients = Backend.dispatch(
+            :accumulate_backward,
+            *saved,
+            grad_render_colors,
+            grad_render_alphas
+          )
+          [*gradients, nil, nil]
+        end
+      end
+    end
+  end
+
+  class << self
+    # Composites every Gaussian over every pixel without tile acceleration.
+    # rubocop:disable Metrics/ParameterLists
+    def accumulate(means2d, conics, opacities, colors, width:, height:, backgrounds: nil)
+      # rubocop:enable Metrics/ParameterLists
+      inputs = [means2d, conics, opacities, colors, backgrounds]
+      return Ops::Accumulate.apply(*inputs, width, height) if inputs.any?(Autograd::Variable)
+
+      Backend.dispatch(
+        :accumulate_forward,
+        *inputs,
+        width,
+        height
+      ).first(2)
+    end
+  end
+
+  Backend.register(:accumulate_forward, :ruby, Backend::RubyAccumulate.method(:forward))
+  Backend.register(:accumulate_backward, :ruby, Backend::RubyAccumulateBackward.method(:backward))
+end

data/lib/gsplat/ops/eval3d_rasterize.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+require_relative "../backend/ruby/eval3d_rasterizer"
+
+module Gsplat
+  module Ops
+    # Differentiable world-space reference rasterizer with optional normals.
+    class Eval3dRasterize < Autograd::Function
+      class << self
+        # rubocop:disable Metrics/ParameterLists
+        def forward(context, means, quats, scales, colors, opacities, backgrounds, **options)
+          # rubocop:enable Metrics/ParameterLists
+          context.save(means, quats, scales, colors, opacities, backgrounds, options)
+          Backend::RubyEval3dRasterizer.forward(
+            means, quats, scales, colors, opacities, backgrounds, **options
+          )
+        end
+
+        # Computes a central-difference VJP for the portable eval3d path.
+        # @api private
+        def backward(context, grad_rendered, grad_alphas, grad_normals)
+          *inputs, options = context.saved_values
+          gradient_outputs = [grad_rendered, grad_alphas, grad_normals]
+          context.needs_input_grad.each_with_index.map do |needed, input_index|
+            next unless needed
+
+            numerical_vjp(inputs, input_index, gradient_outputs, options)
+          end
+        end
+
+        private
+
+        def numerical_vjp(inputs, input_index, gradient_outputs, options)
+          input = inputs[input_index]
+          epsilon = input.is_a?(Numo::DFloat) ? 1e-5 : 1e-3
+          gradient = input.class.zeros(*input.shape)
+          input.size.times do |element|
+            positive_inputs = inputs.dup
+            negative_inputs = inputs.dup
+            positive_inputs[input_index] = perturb(input, element, epsilon)
+            negative_inputs[input_index] = perturb(input, element, -epsilon)
+            positive = objective(positive_inputs, gradient_outputs, options)
+            negative = objective(negative_inputs, gradient_outputs, options)
+            gradient[element] = (positive - negative) / (2 * epsilon)
+          end
+          gradient
+        end
+
+        def perturb(input, index, amount)
+          flat = input.flatten.dup
+          flat[index] += amount
+          flat.reshape(*input.shape)
+        end
+
+        def objective(inputs, gradient_outputs, options)
+          outputs = Backend::RubyEval3dRasterizer.forward(*inputs, **options)
+          outputs.zip(gradient_outputs).sum { |output, gradient| (output * gradient).sum }.to_f
+        end
+      end
+    end
+  end
+end

data/lib/gsplat/ops/isect_tiles.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require_relative "../backend/ruby/isect_tiles"
+
+# Tile intersection APIs.
+module Gsplat
+  class << self
+    # Enumerates Gaussian/tile intersections.
+    # rubocop:disable Metrics/ParameterLists
+    def isect_tiles(means2d, radii, depths, tile_size, tile_width, tile_height, sort: true)
+      # rubocop:enable Metrics/ParameterLists
+      Backend.dispatch(
+        :isect_tiles,
+        means2d,
+        radii,
+        depths,
+        tile_size,
+        tile_width,
+        tile_height,
+        sort: sort
+      )
+    end
+
+    # Encodes the starting intersection index for every camera tile.
+    def isect_offset_encode(isect_ids, camera_count, tile_width, tile_height)
+      Backend.dispatch(
+        :isect_offset_encode,
+        isect_ids,
+        camera_count,
+        tile_width,
+        tile_height
+      )
+    end
+  end
+
+  Backend.register(:isect_tiles, :ruby, Backend::RubyIsectTiles.method(:forward))
+  Backend.register(:isect_offset_encode, :ruby, Backend::RubyIsectTiles.method(:offset_encode))
+end

data/lib/gsplat/ops/projection.rb

@@ -0,0 +1,154 @@
+# frozen_string_literal: true
+
+require_relative "../backend/ruby/projection"
+require_relative "../backend/ruby/projection_backward"
+require_relative "../backend/ruby/projection_covariance_vjp"
+require_relative "../backend/ruby/projection_input_vjp"
+
+# Differentiable camera projection operations.
+module Gsplat
+  module Ops
+    # Fused world-to-camera transform, covariance projection, and culling.
+    class FullyFusedProjection < Autograd::Function
+      class << self
+        # Adds the optional compensation placeholder used by the public tuple.
+        # @api private
+        def apply(*inputs, calc_compensations: false, **options)
+          outputs = super
+          calc_compensations ? outputs : [*outputs, nil]
+        end
+
+        # rubocop:disable Metrics/ParameterLists
+        def forward(context, means, covars, quaternions, scales, viewmats, intrinsics, width, height, **options)
+          # rubocop:enable Metrics/ParameterLists
+          context.save(means, covars, quaternions, scales, viewmats, intrinsics, width, height, options)
+          outputs = Backend.dispatch(
+            :fully_fused_projection_forward,
+            means,
+            covars,
+            quaternions,
+            scales,
+            viewmats,
+            intrinsics,
+            width,
+            height,
+            **options
+          )
+          options.fetch(:calc_compensations) ? outputs : outputs.first(4)
+        end
+
+        # rubocop:disable Metrics/ParameterLists
+        def backward(context, _grad_radii, grad_means2d, grad_depths, grad_conics, grad_compensations = nil)
+          # rubocop:enable Metrics/ParameterLists
+          means, covars, quaternions, scales, viewmats, intrinsics, width, height, options = context.saved_values
+          input_gradients = Backend.dispatch(
+            :fully_fused_projection_backward,
+            means,
+            covars,
+            quaternions,
+            scales,
+            viewmats,
+            intrinsics,
+            width,
+            height,
+            grad_means2d,
+            grad_depths,
+            grad_conics,
+            grad_compensations,
+            **options
+          )
+          [*input_gradients, nil, nil, nil, nil]
+        end
+      end
+    end
+  end
+
+  class << self
+    # Transforms world-space means/covariances into camera space.
+    #
+    # @param means [Numo::NArray] [N,3]
+    # @param covars [Numo::NArray] [N,3,3] or packed [N,6]
+    # @param viewmats [Numo::NArray] [C,4,4] world-to-camera transforms
+    # @return [Array<Numo::NArray>] camera means `[C,N,3]` and covariances `[C,N,3,3]`
+    def world_to_cam(means, covars, viewmats)
+      Math::CameraProjection.world_to_cam(means, covars, viewmats)
+    end
+
+    # Projects camera-space means/covariances with a pinhole model.
+    #
+    # @param means [Numo::NArray] [C,N,3]
+    # @param covars [Numo::NArray] [C,N,3,3]
+    # @param intrinsics [Numo::NArray] [C,3,3]
+    # @return [Array<Numo::NArray>] projected means `[C,N,2]` and covariances `[C,N,2,2]`
+    def persp_proj(means, covars, intrinsics, width, height)
+      Math::CameraProjection.persp_proj(means, covars, intrinsics, width, height)
+    end
+
+    # Projects camera-space means/covariances with an orthographic model.
+    #
+    # @param means [Numo::NArray] [C,N,3]
+    # @param covars [Numo::NArray] [C,N,3,3]
+    # @param intrinsics [Numo::NArray] [C,3,3]
+    # @return [Array<Numo::NArray>] projected means `[C,N,2]` and covariances `[C,N,2,2]`
+    def ortho_proj(means, covars, intrinsics, width, height)
+      Math::CameraProjection.ortho_proj(means, covars, intrinsics, width, height)
+    end
+
+    # Projects and culls a dense camera batch.
+    #
+    # Inputs use float32/float64 Numo arrays or {Autograd::Variable}; geometry is
+    # `[N,3]`, views `[C,4,4]`, intrinsics `[C,3,3]`, and outputs are
+    # radii `[C,N,2]`, means `[C,N,2]`, depths `[C,N]`, conics `[C,N,3]`,
+    # plus optional compensations `[C,N]`.
+    #
+    # @return [Array<(Numo::NArray, Autograd::Variable, nil)>]
+    # rubocop:disable Metrics/ParameterLists, Naming/MethodParameterName
+    def fully_fused_projection(means, viewmats:, ks:, width:, height:, covars: nil, quats: nil, scales: nil,
+                               eps2d: 0.3, near_plane: 0.01, far_plane: 1e10, radius_clip: 0.0,
+                               calc_compensations: false, camera_model: "pinhole",
+                               radial_coeffs: nil, tangential_coeffs: nil, thin_prism_coeffs: nil,
+                               global_z_order: true)
+      # rubocop:enable Metrics/ParameterLists, Naming/MethodParameterName
+      inputs = [means, covars, quats, scales, viewmats, ks]
+      options = {
+        eps2d: eps2d,
+        near_plane: near_plane,
+        far_plane: far_plane,
+        radius_clip: radius_clip,
+        calc_compensations: calc_compensations,
+        camera_model: camera_model,
+        radial_coeffs: radial_coeffs,
+        tangential_coeffs: tangential_coeffs,
+        thin_prism_coeffs: thin_prism_coeffs,
+        global_z_order: global_z_order
+      }
+      if inputs.any?(Autograd::Variable)
+        return Ops::FullyFusedProjection.apply(
+          *inputs,
+          width,
+          height,
+          **options
+        )
+      end
+
+      Backend.dispatch(
+        :fully_fused_projection_forward,
+        *inputs,
+        width,
+        height,
+        **options
+      )
+    end
+  end
+
+  Backend.register(
+    :fully_fused_projection_forward,
+    :ruby,
+    Backend::RubyProjection.method(:forward)
+  )
+  Backend.register(
+    :fully_fused_projection_backward,
+    :ruby,
+    Backend::RubyProjectionBackward.method(:backward)
+  )
+end

data/lib/gsplat/ops/quat_scale_to_covar_preci.rb

@@ -0,0 +1,118 @@
+# frozen_string_literal: true
+
+require_relative "../backend/ruby/quat_scale_to_covar_preci"
+
+# Differentiable quaternion/scale covariance operation.
+module Gsplat
+  module Ops
+    # Differentiable conversion from wxyz quaternions/scales to covariance and precision.
+    class QuatScaleToCovarPreci < Autograd::Function
+      class << self
+        # Applies the operation while retaining Python gsplat's two tuple positions.
+        #
+        # @param quaternions [Autograd::Variable, Numo::NArray] [...,4]
+        # @param scales [Autograd::Variable, Numo::NArray] [...,3]
+        # @param compute_covar [Boolean]
+        # @param compute_preci [Boolean]
+        # @param triu [Boolean] return [...,6] upper triangles when true
+        # @return [Array<(Autograd::Variable, nil)>]
+        def apply(quaternions, scales, compute_covar: true, compute_preci: true, triu: false)
+          validate_selection!(compute_covar, compute_preci)
+          outputs = super
+          return outputs if compute_covar && compute_preci
+          return [outputs, nil] if compute_covar
+
+          [nil, outputs]
+        end
+
+        # Evaluates covariance/precision tensors and records inputs for VJP.
+        # @api private
+        def forward(context, quaternions, scales, **options)
+          compute_covar = options.fetch(:compute_covar)
+          compute_preci = options.fetch(:compute_preci)
+          triu = options.fetch(:triu)
+          context.save(quaternions, scales, compute_covar, compute_preci, triu)
+          covariance, precision = Backend.dispatch(
+            :quat_scale_to_covar_preci_forward,
+            quaternions,
+            scales,
+            compute_covar: compute_covar,
+            compute_preci: compute_preci,
+            triu: triu
+          )
+          return [covariance, precision] if compute_covar && compute_preci
+
+          compute_covar ? covariance : precision
+        end
+
+        # Propagates matrix gradients to quaternions and scales.
+        # @api private
+        def backward(context, *grad_outputs)
+          quaternions, scales, compute_covar, compute_preci, triu = context.saved_values
+          grad_covar = compute_covar ? grad_outputs.shift : nil
+          grad_preci = compute_preci ? grad_outputs.shift : nil
+          Backend.dispatch(
+            :quat_scale_to_covar_preci_backward,
+            quaternions,
+            scales,
+            grad_covar,
+            grad_preci,
+            triu: triu
+          )
+        end
+
+        private
+
+        def validate_selection!(compute_covar, compute_preci)
+          return if compute_covar || compute_preci
+
+          raise ArgumentError, "at least one of compute_covar or compute_preci must be true"
+        end
+      end
+    end
+  end
+
+  class << self
+    # Converts wxyz quaternions and scales to covariance and/or precision matrices.
+    #
+    # @param quaternions [Autograd::Variable, Numo::NArray] [...,4]
+    # @param scales [Autograd::Variable, Numo::NArray] [...,3]
+    # @param compute_covar [Boolean]
+    # @param compute_preci [Boolean]
+    # @param triu [Boolean] return [...,6] upper triangles when true
+    # @return [Array<(Autograd::Variable, Numo::NArray, nil)>]
+    def quat_scale_to_covar_preci(quaternions, scales, compute_covar: true, compute_preci: true, triu: false)
+      if [quaternions, scales].any?(Autograd::Variable)
+        return Ops::QuatScaleToCovarPreci.apply(
+          quaternions,
+          scales,
+          compute_covar: compute_covar,
+          compute_preci: compute_preci,
+          triu: triu
+        )
+      end
+
+      raise ArgumentError, "at least one output must be requested" unless compute_covar || compute_preci
+
+      Backend.dispatch(
+        :quat_scale_to_covar_preci_forward,
+        quaternions,
+        scales,
+        compute_covar: compute_covar,
+        compute_preci: compute_preci,
+        triu: triu
+      )
+    end
+  end
+
+  Backend.register(
+    :quat_scale_to_covar_preci_forward,
+    :ruby,
+    Backend::RubyQuatScaleToCovarPreci.method(:forward)
+  )
+  Backend.register(
+    :quat_scale_to_covar_preci_backward,
+    :ruby,
+    Backend::RubyQuatScaleToCovarPreci.method(:backward)
+  )
+end

data/lib/gsplat/ops/rasterize_to_indices_in_range.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require_relative "../backend/ruby/accumulate"
+require_relative "../backend/ruby/rasterize_to_pixels"
+require_relative "../backend/ruby/rasterize_to_indices_in_range"
+
+# Differentiable Gaussian rasterization primitives.
+module Gsplat
+  class << self
+    # Enumerates Gaussian contributions for tile-list batches in depth order.
+    #
+    # @return [Array<Numo::Int64>] Gaussian, pixel, and image IDs
+    # rubocop:disable Metrics/ParameterLists
+    def rasterize_to_indices_in_range(range_start, range_end, transmittances, means2d, conics, opacities,
+                                      width, height, tile_size, isect_offsets, flatten_ids)
+      # rubocop:enable Metrics/ParameterLists
+      tensors = [transmittances, means2d, conics, opacities, isect_offsets, flatten_ids].map do |value|
+        Ops::TensorOps.data(value)
+      end
+      Backend.dispatch(
+        :rasterize_to_indices_in_range,
+        range_start,
+        range_end,
+        *tensors.first(4),
+        width,
+        height,
+        tile_size,
+        *tensors.last(2)
+      )
+    end
+  end
+
+  Backend.register(
+    :rasterize_to_indices_in_range,
+    :ruby,
+    Backend::RubyRasterizeToIndicesInRange.method(:forward)
+  )
+end

data/lib/gsplat/ops/rasterize_to_pixels.rb

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+require_relative "../backend/ruby/tile_compositor"
+require_relative "../backend/ruby/rasterize_to_pixels"
+require_relative "../backend/ruby/tile_compositor_backward"
+require_relative "../backend/ruby/rasterize_to_pixels_backward"
+
+# Differentiable tile rasterization API.
+module Gsplat
+  module Ops
+    # Tile-accelerated alpha compositor.
+    class RasterizeToPixels < Autograd::Function
+      class << self
+        # rubocop:disable Metrics/ParameterLists
+        def forward(context, means2d, conics, colors, opacities, backgrounds, masks, width, height,
+                    tile_size, isect_offsets, flatten_ids, absgrad:)
+          # rubocop:enable Metrics/ParameterLists
+          render_colors, render_alphas, last_ids = Backend.dispatch(
+            :rasterize_to_pixels_forward,
+            means2d,
+            conics,
+            colors,
+            opacities,
+            backgrounds,
+            masks,
+            width,
+            height,
+            tile_size,
+            isect_offsets,
+            flatten_ids
+          )
+          context.save(
+            means2d, conics, colors, opacities, backgrounds, masks, width, height,
+            tile_size, isect_offsets, flatten_ids, render_alphas, last_ids, absgrad
+          )
+          [render_colors, render_alphas]
+        end
+
+        # Propagates pixel color and alpha gradients to projected attributes.
+        # @api private
+        def backward(context, grad_render_colors, grad_render_alphas)
+          saved = context.saved_values
+          means2d, conics, colors, opacities, backgrounds, masks, width, height,
+            tile_size, offsets, flatten_ids, render_alphas, last_ids, absgrad = saved
+          gradients, means2d_absgrad = Backend.dispatch(
+            :rasterize_to_pixels_backward,
+            means2d,
+            conics,
+            colors,
+            opacities,
+            backgrounds,
+            masks,
+            width,
+            height,
+            tile_size,
+            offsets,
+            flatten_ids,
+            render_alphas,
+            last_ids,
+            grad_render_colors,
+            grad_render_alphas,
+            absgrad: absgrad
+          )
+          if absgrad && context.inputs[0].is_a?(Autograd::Variable)
+            context.inputs[0].accumulate_absgrad(means2d_absgrad)
+          end
+          [*gradients, nil, nil, nil, nil, nil, nil]
+        end
+      end
+    end
+  end
+
+  class << self
+    # Alpha-composites sorted tile intersections.
+    #
+    # Projected inputs have shapes `means2d [C,N,2]`, `conics [C,N,3]`,
+    # `colors [C,N,D]`, and `opacities [C,N]`. Outputs are color
+    # `[C,H,W,D]` and alpha `[C,H,W,1]`.
+    #
+    # @return [Array<(Numo::NArray, Autograd::Variable)>]
+    # rubocop:disable Metrics/ParameterLists
+    def rasterize_to_pixels(means2d, conics, colors, opacities, width, height, tile_size,
+                            isect_offsets, flatten_ids, backgrounds: nil, masks: nil, absgrad: false)
+      # rubocop:enable Metrics/ParameterLists
+      inputs = [
+        means2d, conics, colors, opacities, backgrounds, masks, width, height,
+        tile_size, isect_offsets, flatten_ids
+      ]
+      return Ops::RasterizeToPixels.apply(*inputs, absgrad: absgrad) if inputs.any?(Autograd::Variable)
+
+      Backend.dispatch(:rasterize_to_pixels_forward, *inputs).first(2)
+    end
+  end
+
+  Backend.register(
+    :rasterize_to_pixels_forward,
+    :ruby,
+    Backend::RubyRasterizeToPixels.method(:forward)
+  )
+  Backend.register(
+    :rasterize_to_pixels_backward,
+    :ruby,
+    Backend::RubyRasterizeToPixelsBackward.method(:backward)
+  )
+end

data/lib/gsplat/ops/relocation.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+# Closed-form relocation primitive and public wrapper.
+module Gsplat
+  module Ops
+    # Closed-form opacity and scale update from 3DGS-MCMC equation 9.
+    module Relocation
+      # Default maximum split ratio represented by {.binomial_table}.
+      DEFAULT_N_MAX = 51
+
+      module_function
+
+      # Builds the binomial coefficient lookup used by relocation.
+      #
+      # @param n_max [Integer] maximum split ratio, inclusive
+      # @param dtype [Class] Numo floating-point class
+      # @return [Numo::NArray] [n_max,n_max]
+      def binomial_table(n_max: DEFAULT_N_MAX, dtype: Numo::SFloat)
+        raise ArgumentError, "n_max must be a positive integer" unless n_max.is_a?(Integer) && n_max.positive?
+
+        output = dtype.zeros(n_max, n_max)
+        n_max.times do |n_value|
+          (n_value + 1).times { |k_value| output[n_value, k_value] = binomial(n_value, k_value) }
+        end
+        output
+      end
+
+      # Recalculates activated opacities and scales for a requested split ratio.
+      #
+      # @param opacities [Numo::NArray] [N], activated values in [0,1]
+      # @param scales [Numo::NArray] [N,3], activated positive scales
+      # @param ratios [Numo::NArray] [N], clamped to 1..n_max
+      # @param binoms [Numo::NArray] [n_max,n_max]
+      # @return [Array<Numo::NArray>] new opacities and scales
+      def compute(opacities, scales, ratios, binoms: binomial_table(dtype: opacities.class))
+        validate_inputs!(opacities, scales, ratios, binoms)
+        output_opacities = opacities.class.zeros(opacities.shape[0])
+        output_scales = scales.class.zeros(*scales.shape)
+        opacities.shape[0].times do |index|
+          ratio = ratios[index].to_i.clamp(1, binoms.shape[0])
+          opacity = opacities[index].to_f
+          new_opacity = 1.0 - ((1.0 - opacity)**(1.0 / ratio))
+          coefficient = opacity / denominator(new_opacity, ratio, binoms)
+          output_opacities[index] = new_opacity
+          output_scales[index, true] = scales[index, true] * coefficient
+        end
+        [output_opacities, output_scales]
+      end
+
+      def binomial(n_value, k_value)
+        return 1 if k_value.zero? || k_value == n_value
+
+        k_value = [k_value, n_value - k_value].min
+        (1..k_value).reduce(1) { |value, index| (value * (n_value - k_value + index)) / index }
+      end
+      private_class_method :binomial
+
+      def denominator(opacity, ratio, binoms)
+        (1..ratio).sum do |i_value|
+          (0...i_value).sum do |k_value|
+            sign = k_value.even? ? 1.0 : -1.0
+            binoms[i_value - 1, k_value].to_f * sign * (opacity**(k_value + 1)) / ::Math.sqrt(k_value + 1)
+          end
+        end
+      end
+      private_class_method :denominator
+
+      def validate_inputs!(opacities, scales, ratios, binoms)
+        unless opacities.is_a?(Numo::NArray) && [Numo::SFloat, Numo::DFloat].include?(opacities.class)
+          raise ArgumentError, "opacities must be Numo::SFloat or Numo::DFloat"
+        end
+
+        count = opacities.shape[0] if opacities.ndim == 1
+        valid = count && scales.shape == [count, 3] && ratios.shape == [count] &&
+                binoms.ndim == 2 && binoms.shape[0] == binoms.shape[1]
+        return if valid
+
+        raise ShapeError,
+              "expected opacities [N], scales [N,3], ratios [N], binoms [M,M]; " \
+              "got #{opacities.shape.inspect}, #{scales.shape.inspect}, " \
+              "#{ratios.shape.inspect}, #{binoms.shape.inspect}"
+      end
+      private_class_method :validate_inputs!
+    end
+  end
+
+  class << self
+    # Computes the deterministic 3DGS-MCMC relocation update.
+    def relocation(opacities, scales, ratios, binoms: nil)
+      options = binoms ? { binoms: binoms } : {}
+      Ops::Relocation.compute(opacities, scales, ratios, **options)
+    end
+  end
+end