Point Cloud Module API Reference

This document enumerates every public surface exposed under src/point_cloud. It mirrors the TypeScript signatures in src/point_cloud and explains how each piece interacts with the larger WebGPU pipeline.

Table of contents

• Module exports
• PointCloud
• DynamicPointCloud
• Bind group helpers & config
• Data contracts & helper types

---

Module exports

src/point_cloud/index.ts re-exports:

export { PointCloud } from './point_cloud';
export { DynamicPointCloud } from './dynamic_point_cloud';
export type { SplatBuffer } from './splat_buffer';
export * from './layouts'; // getBindGroupLayout, getRenderBindGroupLayout, BUFFER_CONFIG

---

PointCloud

Encapsulates GPU buffers, draw uniforms, model-parameter uniforms, and bind groups for a single Gaussian dataset.

Constructor

new PointCloud(
  device: GPUDevice,
  pc: GenericGaussianPointCloudTS,
  externalBuffers?: { gaussianBuffer: GPUBuffer; shBuffer: GPUBuffer }
);

• pc must conform to GenericGaussianPointCloudTS (alias of GaussianDataSource from IO).
• When externalBuffers is passed, the constructor skips CPU uploads and reuses those GPU buffers (useful for ONNX pipelines or runtime precision conversion).

Public properties

Property	Type	Description
numPoints	number	Total splat count derived from pc.numPoints().
shDeg	number	Spherical harmonics degree.
bbox	Aabb	World-space bounding box created from pc.bbox().
colorMode	'sh' | 'rgb'	Indicates how shaders should interpret color data (defaults to 'sh').
center	vec3	Optional camera-friendly center from the data source.
up	vec3 | null	Optional up vector.
uniforms	UniformBuffer	Draw-level metadata buffer.
modelParamsUniforms	UniformBuffer	128-byte block with transforms + precision data.
mipSplatting, kernelSize, backgroundColor	optional	Stored for renderer UI usage.

Buffer & bind-group access

Signature	Description
bindGroup(): GPUBindGroup	Returns the compute bind group (gaussians, SH, splat buffer, uniforms).
renderBindGroup(): GPUBindGroup	Returns the render bind group (projected splats).
getSplatBuffer(): SplatBuffer	Publishes the Gaussian/SH GPU buffers plus metadata for preprocess dispatch sizing.
replaceStorageBuffers(device, { gaussianBuffer, shBuffer })	Swaps Gaussian/SH buffers and rebuilds the compute bind group (splat buffer + uniforms are reused).

Uniform & transform helpers

Signature	Purpose
updateModelParamsBuffer(transformMatrix: Float32Array, baseOffset = 0)	Rebuilds the 128-byte model parameter block with the provided matrix/offset plus cached shading + precision fields.
updateModelParamsWithOffset(transformMatrix, baseOffset)	Alias kept for backwards compatibility.
setTransform(matrix: Float32Array | number[])	Updates the cached transform (deprecated) and immediately refreshes the GPU uniform via updateModelParamsBuffer.

Rendering knobs

All setters clamp inputs to safe ranges and log the applied value.

Setter	Getter	Notes
setGaussianScaling(scale)	getGaussianScaling()	Multiplies covariance scale; stored at byte offset 72.
setMaxShDeg(deg)	getMaxShDeg()	Clamped to [0, 3]; stored at byte offset 76.
setKernelSize(size)	getKernelSize()	Non-negative 2D kernel radius.
setOpacityScale(scale)	getOpacityScale()	Non-negative multiplier for opacity.
setCutoffScale(scale)	getCutoffScale()	Minimum of 0.1 to avoid collapse.
setRenderMode(mode)	getRenderMode()	0=Color, 1=Normal, 2=Depth.

After adjusting any parameter, call updateModelParamsBuffer (or setTransform) so the GPU copy receives the new values.

Static helpers (deprecated)

PointCloud.bindGroupLayout(device) and PointCloud.renderBindGroupLayout(device) proxy to layouts.ts but are kept only for legacy imports. Prefer using getBindGroupLayout and getRenderBindGroupLayout directly.

---

DynamicPointCloud

Subclasses PointCloud to support real-time ONNX generators, runtime precision metadata, optional indirect draw counts, and timeline-driven animation control.

Constructor

new DynamicPointCloud(
  device: GPUDevice,
  gaussianBuffer: GPUBuffer,
  shBuffer: GPUBuffer,
  maxPoints: number,
  countBuffer?: GPUBuffer,
  colorChannels = 48,
  precisionInfo?: {
    gaussian?: { dataType: PrecisionType; scale?: number; zeroPoint?: number };
    color?: { dataType: PrecisionType; scale?: number; zeroPoint?: number };
  }
);

• colorChannels determines the implied SH degree (3 → degree 0, 12 → degree 1, 27 → degree 2, 48 → degree 3). If 4 channels are provided the color mode switches to 'rgb'.
• countBuffer, when provided, is consumed by the renderer for indirect draws.
• PrecisionType is a string describing storage type ('float32' | 'float16' | 'int8' | 'uint8'); scale/zeroPoint are optional floats.

Additional properties

Property	Description
colorMode	'sh' or 'rgb' derived from colorChannels.
colorChannels	Number of color coefficients per point.
countBuffer()	Getter returning the optional draw-count buffer.

ONNX & precision helpers

Signature	Description
setOnnxGenerator(generator: OnnxGenerator)	Links the ONNX runtime wrapper responsible for mutating GPU buffers.
async update(cameraMatrix: mat4, modelTransform: Float32Array, time?: number, projectionMatrix?: mat4, rafNow?: number)	Combines matrices, computes timeline-driven frame time, calls generator.generate(...), and leaves fresh data inside the GPU buffers.
getGaussianPrecision() / getColorPrecision()	Returns the stored precision metadata objects (if any).
setPrecisionForShader()	Rewrites bytes 96–119 of the model parameters buffer (data type enums + scales/zero points) based on precisionInfo. Call this after modifying precision metadata.
applyFP16(device, newGauss, newColor)	Convenience method that replaces both storage buffers with FP16 versions, records the new precision metadata, and refreshes shader descriptors.

Animation & time control

All animation methods proxy to the internal TimelineController, so they are safe to call each frame.

Signature	Description
startAnimation(speed = 1) / pauseAnimation() / resumeAnimation() / stopAnimation()	Standard playback controls.
setAnimationTime(time)	Jump to a normalized time (0–1).
setAnimationSpeed(speed) / getAnimationSpeed()	Configure timeline multiplier.
setAnimationIsLoop(isLoop: boolean)	Toggle looping vs clamped playback.
setTimeScale(scale) / getTimeScale()	Additional scaling factor applied to the computed frame time.
setTimeOffset(offset) / getTimeOffset()	Additive offset before wrapping/clamping.
resetFrameTime()	Resets accumulated time to zero.
getFrameTime()	Returns the raw timeline time prior to offset/loop adjustments.
setTimeUpdateMode(mode: TimeUpdateMode) / getTimeUpdateMode()	Switch between FIXED_DELTA and VARIABLE_DELTA update strategies.
isAnimationRunning, isAnimationPaused, isAnimationStopped	Read-only getters that reflect the timeline status.

Diagnostics & lifecycle

Signature	Description
getPerformanceStats()	Returns timeline statistics plus ONNX linkage/point count metadata for UI overlays.
dispose()	Clears timeline event listeners. GPU buffers are not destroyed (they belong to the caller).

---

Bind group helpers & config

Located in src/point_cloud/layouts.ts.

getBindGroupLayout(device: GPUDevice): GPUBindGroupLayout

Returns (and caches) the compute layout:

Binding	Visibility	Buffer type	Contents
0	GPUShaderStage.COMPUTE	read-only-storage	Gaussian buffer.
1	GPUShaderStage.COMPUTE	read-only-storage	SH buffer.
2	GPUShaderStage.COMPUTE	storage	2D splat buffer (output).
3	GPUShaderStage.COMPUTE	uniform	Draw uniforms.

getRenderBindGroupLayout(device: GPUDevice): GPUBindGroupLayout

Returns (and caches) the render layout:

Binding	Visibility	Buffer type	Contents
2	GPUShaderStage.VERTEX	read-only-storage	Projected splat buffer shared with compute step.

BUFFER_CONFIG

export const BUFFER_CONFIG = {
  SPLAT_STRIDE: 32,
} as const;

Use SPLAT_STRIDE when allocating custom buffers that must match the WGSL struct consumed by preprocessing and rendering shaders.

---

Data contracts & helper types

SplatBuffer

type SplatBuffer = {
  gaussianBuffer: GPUBuffer;
  shBuffer: GPUBuffer;
  numPoints: number;
  shDegree: number;
  bbox: Aabb;
};

Returned by PointCloud.getSplatBuffer() so preprocessing code can schedule work without directly depending on PointCloud.

GenericGaussianPointCloud

Shape of the CPU-side data passed to PointCloud when bypassing the IO alias:

interface GenericGaussianPointCloud {
  gaussianBuffer(): ArrayBuffer;
  shCoefsBuffer(): ArrayBuffer;
  numPoints(): number;
  shDegree(): number;
  bbox(): Aabb;
  center?: [number, number, number];
  up?: [number, number, number] | null;
  kernelSize?: number;
  mipSplatting?: boolean;
  backgroundColor?: [number, number, number];
}

GaussianCompressed & Gaussian

Utility wrappers that mirror WGSL/Rust layouts should you need to manipulate splat data on the CPU:

class GaussianCompressed {
  bytes: Uint8Array;
  constructor(bytes: ArrayBuffer);
}

class Gaussian {
  xyz: [number, number, number];
  opacity: number;
  cov: [number, number, number, number, number, number];
  constructor(xyz: [number, number, number], opacity: number, cov: [number, number, number, number, number, number]);
}

These are thin helpers; production code typically works with packed ArrayBuffers sourced from the IO module.