gsplat 1.0.0

data/lib/gsplat/utils.rb

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+module Gsplat
+  # Point-cloud initialization and scene geometry utilities.
+  module Utils
+    # Degree-zero real spherical-harmonic basis constant.
+    SH_C0 = 0.28209479177387814
+
+    module_function
+
+    # Brute-force Euclidean nearest-neighbor distances, including self at zero.
+    # rubocop:disable Naming/MethodParameterName
+    def knn(points, k: 4)
+      validate_points!(points)
+      unless k.is_a?(Integer) && k.between?(1, points.shape[0])
+        raise ArgumentError, "k must be in 1..#{points.shape[0]}"
+      end
+
+      output = points.class.zeros(points.shape[0], k)
+      points.shape[0].times do |index|
+        distances = Numo::NMath.sqrt(((points - points[index, true])**2).sum(axis: 1))
+        output[index, true] = distances.sort[0...k]
+      end
+      output
+    end
+    # rubocop:enable Naming/MethodParameterName
+
+    def rgb_to_sh(rgb)
+      (rgb - 0.5) / SH_C0
+    end
+
+    # Converts degree-zero SH coefficients back to RGB values.
+    #
+    # @param coefficients [Numo::NArray] [...,3]
+    # @return [Numo::NArray] [...,3]
+    def sh_to_rgb(coefficients)
+      (coefficients * SH_C0) + 0.5
+    end
+
+    # Initializes raw trainable Gaussian parameters from colored 3D points.
+    # rubocop:disable Metrics/AbcSize
+    def init_from_points(points, colors, **options)
+      sh_degree = options.fetch(:sh_degree, 3)
+      init_opacity = options.fetch(:init_opacity, 0.1)
+      init_scale = options.fetch(:init_scale, 1.0)
+      rng = options.fetch(:rng, Gsplat.rng)
+      validate_initialization!(points, colors, sh_degree, init_opacity, init_scale)
+      count = points.shape[0]
+      neighbor_count = [4, count].min
+      squared = knn(points, k: neighbor_count)[true, 1...neighbor_count]**2
+      distance = Numo::NMath.sqrt(squared.mean(axis: 1))
+      epsilon = points.is_a?(Numo::DFloat) ? 1e-12 : 1e-6
+      distance[distance.lt(epsilon)] = epsilon
+      log_scales = Numo::NMath.log(distance * init_scale).reshape(count, 1)
+      scales = points.class.zeros(count, 3)
+      scales[true, true] = log_scales
+      quaternions = points.class.cast(Array.new(count * 4) { rng.rand }).reshape(count, 4)
+      opacity = ::Math.log(init_opacity / (1 - init_opacity))
+      sh0 = rgb_to_sh(points.class.cast(colors)).reshape(count, 1, 3)
+      shn = points.class.zeros(count, ((sh_degree + 1)**2) - 1, 3)
+      {
+        means: variable(points.dup),
+        scales: variable(scales),
+        quats: variable(quaternions),
+        opacities: variable(points.class.ones(count) * opacity),
+        sh0: variable(sh0),
+        shN: variable(shn)
+      }
+    end
+    # rubocop:enable Metrics/AbcSize
+
+    # Maximum camera-center distance from the mean center.
+    def scene_scale(camera_to_worlds)
+      unless camera_to_worlds.is_a?(Numo::NArray) &&
+             camera_to_worlds.ndim == 3 && camera_to_worlds.shape[1..] == [4, 4]
+        actual = camera_to_worlds.respond_to?(:shape) ? camera_to_worlds.shape.inspect : camera_to_worlds.class
+        raise ShapeError, "expected camera_to_worlds [C,4,4], got #{actual}"
+      end
+
+      locations = camera_to_worlds[true, 0...3, 3]
+      center = locations.mean(axis: 0)
+      Numo::NMath.sqrt(((locations - center)**2).sum(axis: 1)).max.to_f
+    end
+
+    def validate_points!(points)
+      valid = points.is_a?(Numo::NArray) &&
+              [Numo::SFloat, Numo::DFloat].include?(points.class) &&
+              points.ndim == 2 && points.shape[1] == 3 && points.shape[0].positive?
+      raise ShapeError, "expected points [N,3] floating array" unless valid
+    end
+    private_class_method :validate_points!
+
+    def validate_initialization!(points, colors, degree, opacity, scale)
+      validate_points!(points)
+      raise ArgumentError, "at least two points are required" if points.shape[0] < 2
+      unless colors.is_a?(Numo::NArray) && colors.shape == [points.shape[0], 3]
+        raise ShapeError, "expected colors [#{points.shape[0]},3], got #{colors.shape.inspect}"
+      end
+      raise ArgumentError, "sh_degree must be in 0..4" unless degree.is_a?(Integer) && degree.between?(0, 4)
+      raise ArgumentError, "init_opacity must be in (0,1)" unless opacity.positive? && opacity < 1
+      raise ArgumentError, "init_scale must be positive" unless scale.positive?
+    end
+    private_class_method :validate_initialization!
+
+    def variable(data)
+      Autograd::Variable.new(data, requires_grad: true)
+    end
+    private_class_method :variable
+  end
+end

data/lib/gsplat/version.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module Gsplat
+  # Semantic package version.
+  VERSION = "1.0.0"
+end

data/lib/gsplat.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+require "logger"
+require "numo/narray"
+
+require_relative "gsplat/version"
+require_relative "gsplat/backend"
+require_relative "gsplat/autograd/context"
+require_relative "gsplat/autograd/function"
+require_relative "gsplat/autograd/variable"
+require_relative "gsplat/math/mat"
+require_relative "gsplat/math/quaternion"
+require_relative "gsplat/math/camera_distortion"
+require_relative "gsplat/math/camera_projection"
+require_relative "gsplat/math/spherical_harmonic_basis"
+require_relative "gsplat/math/ssim"
+require_relative "gsplat/ops/accumulate"
+require_relative "gsplat/ops/isect_tiles"
+require_relative "gsplat/ops/projection"
+require_relative "gsplat/ops/quat_scale_to_covar_preci"
+require_relative "gsplat/ops/rasterize_to_indices_in_range"
+require_relative "gsplat/ops/rasterize_to_pixels"
+require_relative "gsplat/ops/eval3d_rasterize"
+require_relative "gsplat/ops/relocation"
+require_relative "gsplat/ops/spherical_harmonics"
+require_relative "gsplat/ops/tensor_shape_ops"
+require_relative "gsplat/ops/tensor_value_ops"
+require_relative "gsplat/rasterization_validation"
+require_relative "gsplat/rasterization_helpers"
+require_relative "gsplat/rasterization"
+require_relative "gsplat/rasterization_2dgs"
+require_relative "gsplat/training/image_fitter"
+require_relative "gsplat/training/losses"
+require_relative "gsplat/training/config"
+require_relative "gsplat/training/scene"
+require_relative "gsplat/training/trainer"
+require_relative "gsplat/optim/adam"
+require_relative "gsplat/optim/selective_adam"
+require_relative "gsplat/optim/lr_scheduler"
+require_relative "gsplat/strategy/base"
+require_relative "gsplat/strategy/ops"
+require_relative "gsplat/strategy/mcmc_ops"
+require_relative "gsplat/strategy/default"
+require_relative "gsplat/strategy/mcmc"
+require_relative "gsplat/io/colmap"
+require_relative "gsplat/io/checkpoint"
+require_relative "gsplat/io/image"
+require_relative "gsplat/io/npy"
+require_relative "gsplat/io/ply"
+require_relative "gsplat/compression/png"
+require_relative "gsplat/utils"
+require_relative "gsplat/native"
+require_relative "gsplat/native_ops"
+
+# Differentiable 3D Gaussian splatting for Ruby.
+module Gsplat
+  # Base error for invalid runtime state and malformed serialized data.
+  class Error < StandardError; end
+
+  # Error raised when tensor dimensions do not satisfy an API contract.
+  class ShapeError < Error; end
+
+  # Error raised when a requested model, format, or backend is unavailable.
+  class NotSupportedError < Error; end
+
+  class << self
+    attr_writer :logger, :rng
+
+    # Logger used for backend fallbacks and unsupported option warnings.
+    #
+    # @return [Logger]
+    def logger
+      @logger ||= Logger.new($stderr, level: Logger::WARN)
+    end
+
+    # Shared deterministic random source used by initialization and strategies.
+    #
+    # @return [Random]
+    def rng
+      @rng ||= Random.new
+    end
+
+    # Active operation backend.
+    #
+    # @return [Symbol] :auto, :ruby, or :native
+    def backend
+      @backend ||= Backend.normalize_backend(ENV.fetch("GSPLAT_BACKEND", "auto"))
+    end
+
+    # Selects the operation backend.
+    #
+    # @param value [Symbol, String] :auto, :ruby, or :native
+    # @return [Symbol] normalized backend
+    def backend=(value)
+      @backend = Backend.normalize_backend(value)
+    end
+  end
+end

metadata

@@ -0,0 +1,181 @@
+--- !ruby/object:Gem::Specification
+name: gsplat
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Yudai Takada
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: numo-narray
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.9'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.9'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+description: A CPU differentiable 3D Gaussian splatting renderer, trainer, and IO
+  toolkit with Numo::NArray and optional OpenMP acceleration.
+email:
+- t.yudai92@gmail.com
+executables: []
+extensions:
+- ext/gsplat_native/extconf.rb
+extra_rdoc_files:
+- LICENSE.txt
+- README.md
+files:
+- LICENSE.txt
+- README.md
+- docs/ACCEPTANCE.md
+- docs/BENCHMARKS.md
+- docs/DECISIONS.md
+- docs/MIGRATION.md
+- docs/PROFILE.md
+- docs/PROGRESS.md
+- docs/decisions/0000-template.md
+- docs/decisions/0001-pin-golden-reference-and-cpu-validation.md
+- docs/decisions/0002-retain-ruby-fallbacks-for-native-backend.md
+- docs/decisions/0003-share-projection-for-distorted-cameras.md
+- docs/decisions/0004-use-portable-world-space-reference-paths.md
+- docs/decisions/0005-reuse-ewa-core-for-2dgs.md
+- docs/decisions/0006-keep-eval3d-as-portable-reference.md
+- docs/decisions/0007-share-compositor-semantics-for-contribution-indices.md
+- examples/data/README.md
+- examples/data/colmap/images/view_000.png
+- examples/data/colmap/images/view_001.png
+- examples/data/colmap/images/view_002.png
+- examples/data/colmap/sparse/0/cameras.txt
+- examples/data/colmap/sparse/0/images.txt
+- examples/data/colmap/sparse/0/points3D.txt
+- examples/data/splats.ply
+- examples/fit_image.rb
+- examples/generate_sample_data.rb
+- examples/render_path.rb
+- examples/simple_trainer.rb
+- ext/gsplat_native/common.h
+- ext/gsplat_native/extconf.rb
+- ext/gsplat_native/gsplat_native.c
+- ext/gsplat_native/intersections.c
+- ext/gsplat_native/projection.c
+- ext/gsplat_native/raster_backward.c
+- ext/gsplat_native/raster_backward_bridge.c
+- ext/gsplat_native/raster_forward.c
+- ext/gsplat_native/rasterization.h
+- ext/gsplat_native/spherical_harmonics.c
+- gsplat.gemspec
+- lib/gsplat.rb
+- lib/gsplat/autograd/context.rb
+- lib/gsplat/autograd/function.rb
+- lib/gsplat/autograd/variable.rb
+- lib/gsplat/backend.rb
+- lib/gsplat/backend/ruby/accumulate.rb
+- lib/gsplat/backend/ruby/accumulate_backward.rb
+- lib/gsplat/backend/ruby/eval3d_rasterizer.rb
+- lib/gsplat/backend/ruby/isect_tiles.rb
+- lib/gsplat/backend/ruby/projection.rb
+- lib/gsplat/backend/ruby/projection_backward.rb
+- lib/gsplat/backend/ruby/projection_covariance_vjp.rb
+- lib/gsplat/backend/ruby/projection_input_vjp.rb
+- lib/gsplat/backend/ruby/quat_scale_to_covar_preci.rb
+- lib/gsplat/backend/ruby/rasterize_to_indices_in_range.rb
+- lib/gsplat/backend/ruby/rasterize_to_pixels.rb
+- lib/gsplat/backend/ruby/rasterize_to_pixels_backward.rb
+- lib/gsplat/backend/ruby/spherical_harmonics.rb
+- lib/gsplat/backend/ruby/tile_compositor.rb
+- lib/gsplat/backend/ruby/tile_compositor_backward.rb
+- lib/gsplat/compression/grid_sort.rb
+- lib/gsplat/compression/kmeans.rb
+- lib/gsplat/compression/png.rb
+- lib/gsplat/compression/png_codec.rb
+- lib/gsplat/compression/quantizer.rb
+- lib/gsplat/io/checkpoint.rb
+- lib/gsplat/io/colmap.rb
+- lib/gsplat/io/colmap_binary.rb
+- lib/gsplat/io/colmap_text.rb
+- lib/gsplat/io/image.rb
+- lib/gsplat/io/image_backends.rb
+- lib/gsplat/io/npy.rb
+- lib/gsplat/io/ply.rb
+- lib/gsplat/io/ply_reader.rb
+- lib/gsplat/io/zip_archive.rb
+- lib/gsplat/math/camera_distortion.rb
+- lib/gsplat/math/camera_projection.rb
+- lib/gsplat/math/mat.rb
+- lib/gsplat/math/quaternion.rb
+- lib/gsplat/math/small_matrix_primitives.rb
+- lib/gsplat/math/spherical_harmonic_basis.rb
+- lib/gsplat/math/ssim.rb
+- lib/gsplat/native.rb
+- lib/gsplat/native_ops.rb
+- lib/gsplat/native_raster_ops.rb
+- lib/gsplat/ops/accumulate.rb
+- lib/gsplat/ops/eval3d_rasterize.rb
+- lib/gsplat/ops/isect_tiles.rb
+- lib/gsplat/ops/projection.rb
+- lib/gsplat/ops/quat_scale_to_covar_preci.rb
+- lib/gsplat/ops/rasterize_to_indices_in_range.rb
+- lib/gsplat/ops/rasterize_to_pixels.rb
+- lib/gsplat/ops/relocation.rb
+- lib/gsplat/ops/spherical_harmonics.rb
+- lib/gsplat/ops/tensor_shape_ops.rb
+- lib/gsplat/ops/tensor_value_ops.rb
+- lib/gsplat/optim/adam.rb
+- lib/gsplat/optim/lr_scheduler.rb
+- lib/gsplat/optim/selective_adam.rb
+- lib/gsplat/rasterization.rb
+- lib/gsplat/rasterization_2dgs.rb
+- lib/gsplat/rasterization_helpers.rb
+- lib/gsplat/rasterization_validation.rb
+- lib/gsplat/strategy/base.rb
+- lib/gsplat/strategy/default.rb
+- lib/gsplat/strategy/mcmc.rb
+- lib/gsplat/strategy/mcmc_ops.rb
+- lib/gsplat/strategy/ops.rb
+- lib/gsplat/training/config.rb
+- lib/gsplat/training/image_fitter.rb
+- lib/gsplat/training/losses.rb
+- lib/gsplat/training/scene.rb
+- lib/gsplat/training/trainer.rb
+- lib/gsplat/utils.rb
+- lib/gsplat/version.rb
+homepage: https://github.com/ydah/gsplat
+licenses:
+- Apache-2.0
+metadata:
+  rubygems_mfa_required: 'true'
+  source_code_uri: https://github.com/ydah/gsplat
+  documentation_uri: https://rubydoc.info/gems/gsplat/1.0.0
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.6
+specification_version: 4
+summary: Differentiable 3D Gaussian splatting for Ruby
+test_files: []