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, *, sh_color_space=ColorSpace.SRGB)[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, *, sh_color_space=ColorSpace.SRGB)#

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. SH radiance is treated as sRGB unless sh_color_space says otherwise. Requires Open3D 0.20 or newer.

Parameters:

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

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

  • sh_color_space (ColorSpace) – Color space of the SH radiance (default: SRGB, as 3DGS assets are display-referred).

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. The USD color space of the SH coefficient attribute that is read (the single-precision attribute, or the half-precision one when only that has a value) selects sh_color_space: untagged, srgb_rec709_scene and srgb_rec709_display radiance is SRGB, and lin_rec709_scene and other Rec.709 linear names are LINEAR. Other color spaces are imported without conversion and a warning is logged; see the USD parsing documentation for the full list of supported names.

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, *, sh_color_space=ColorSpace.SRGB)#

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).

  • sh_color_space (ColorSpace) – Color space of evaluated SH radiance. Defaults to sRGB (display-encoded); pass LINEAR for scene-linear radiance. Only SensorCamera honors this; the deprecated SensorTiledCamera ignores it.

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_color_space: ColorSpace#

Color space of evaluated spherical-harmonics radiance.

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.