newton.Gaussian#

class newton.Gaussian(positions, rotations=None, scales=None, opacities=None, sh_coeffs=None, sh_degree=None, min_response=0.1, sorting_mode=SortingMode.RAY_HIT_DISTANCE)[source]#

Bases: object

Represents a Gaussian splat asset for rendering and rigid body attachment.

A Gaussian splat is a collection of oriented, scaled 3D Gaussians with appearance data (color via spherical harmonics or flat RGB). Gaussian objects can be attached to rigid bodies as a shape type (GeoType.GAUSSIAN) for rendering, with collision handled by an optional proxy geometry.

Example

Load a Gaussian splat from a .ply file and inspect it:

import newton

gaussian = newton.Gaussian.create_from_ply("object.ply")
print(gaussian.count, gaussian.sh_degree)
class SortingMode(*values)#

Bases: IntEnum

Sorting strategy for ordering Gaussian splat hits along a ray.

Controls how per-ray Gaussian intersections are depth-sorted before front-to-back alpha compositing.

CAMERA_DISTANCE = 1#

Sort by projection of the Gaussian center onto the ray direction.

RAY_HIT_DISTANCE = 0#

Sort by closest-approach distance in the Gaussian’s canonical space.

Z_DEPTH = 2#

Sort by camera-forward depth of the Gaussian center.

static create_from_ply(filename, min_response=0.1)#

Load Gaussian splat data from a .ply file (standard 3DGS format).

Reads positions (x/y/z), rotations (rot_0..3), scales (scale_0..2, stored as log-scale), opacities (logit-space), and SH coefficients (f_dc_*, f_rest_*). Converts log-scale and logit-opacity to linear values.

Parameters:

  • filename (str) – Path to a .ply file in standard 3DGS format.

  • min_response (float) – Min response (default = 0.1).

Returns:

A new Gaussian instance.

Return type:

Gaussian

static create_from_usd(prim, min_response=0.1)#

Load Gaussian splat data from a USD prim.

Reads positions from attributes: positions, orientations, scales, opacities and radiance:sphericalHarmonicsCoefficients.

Parameters:

  • prim – A USD prim containing Gaussian splat data.

  • min_response (float) – Min response (default = 0.1).

Returns:

A new Gaussian instance.

Return type:

Gaussian

__init__(positions, rotations=None, scales=None, opacities=None, sh_coeffs=None, sh_degree=None, min_response=0.1, sorting_mode=SortingMode.RAY_HIT_DISTANCE)#

Construct a Gaussian splat asset from arrays.

Parameters:

  • positions (ndarray) – Gaussian centers in local space [m], shape (N, 3), float.

  • rotations (ndarray | None) – Quaternion orientations (x, y, z, w), shape (N, 4), float. If None, defaults to identity quaternions.

  • scales (ndarray | None) – Per-axis scales (linear), shape (N, 3), float. If None, defaults to ones.

  • opacities (ndarray | None) – Opacity values [0, 1], shape (N,), float. If None, defaults to ones (fully opaque).

  • sh_coeffs (ndarray | None) – Spherical harmonic coefficients, shape (N, C), float. The number of coefficients C determines the SH degree (C = 3 -> degree 0, C = 12 -> degree 1, etc.).

  • sh_degree (int | None) – Spherical harmonic degree.

  • min_response (float) – Minimum response required for alpha testing.

  • sorting_mode (SortingMode) – Sorting strategy for depth-ordering Gaussian intersections along each ray before alpha compositing (default: SortingMode.RAY_HIT_DISTANCE).

bvh_refit()#

Refit the Gaussian bvh in place for the current finalized data.

Recomputes per-Gaussian bounds from the finalized GPU data and refits the BVH in place, keeping its existing topology. Call this after mutating the finalized Data arrays (e.g. transforms or scales) on the device so the acceleration structure tracks the moved Gaussians. Structural changes (a different Gaussian count) require a full rebuild via finalize() instead.

This mirrors bvh_refit_shapes() for the scene shape BVH.

Raises:

RuntimeError – If finalize() has not been called yet.

compute_aabb()#

Compute axis-aligned bounding box of Gaussian centers.

Returns:

Tuple of (lower, upper) as (3,) arrays [m].

Return type:

tuple[ndarray, ndarray]

compute_proxy_mesh(method='convex_hull')#

Generate a proxy collision Mesh from Gaussian positions.

Parameters:

method (str) – "convex_hull" (default) or "alphashape" or "points".

Returns:

A Mesh for use as collision proxy.

Return type:

Mesh

finalize(device=None, *, bvh_constructor=None)#

Upload Gaussian data to the GPU as Warp arrays.

Parameters:

  • device (Device | str | None) – Device on which to allocate buffers.

  • bvh_constructor (str | None) – Optional Warp BVH constructor backend. If None, Warp’s default is used.

Returns:

Gaussian.Data struct containing the Warp arrays.

Return type:

Data

property bvh: Bvh | None#

The finalized Warp BVH over the Gaussians, or None before finalize().

Mirrors the scene shape BVH exposed as bvh_shapes. Use bvh_refit() to update it in place after the finalized Data arrays change.

property count: int#

Number of Gaussians in this asset.

property min_response: float#

Min response, float.

property opacities: ndarray#

Opacity values [0, 1], shape (N,), float.

property positions: ndarray#

Gaussian centers in local space [m], shape (N, 3), float.

property rotations: ndarray#

Quaternion orientations (x, y, z, w), shape (N, 4), float.

property scales: ndarray#

Per-axis linear scales, shape (N, 3), float.

property sh_coeffs: ndarray | None#

Spherical harmonic coefficients, shape (N, C), float.

property sh_degree: int#

Spherical harmonics degree (0-3), int

property sorting_mode: SortingMode#

Sorting mode, Gaussian.SortingMode.

property warp_bvh: Bvh | None#

Deprecated alias for bvh.

Deprecated since version 1.6: Use bvh instead.

property warp_data: Gaussian.Data | None#

Deprecated alias for the finalized Warp Gaussian data.

Deprecated since version 1.6: Use the Data object returned by finalize() instead.