kaolin.io.ply

API

kaolin.io.ply.export_gaussiancloud(file_path, positions, orientations, scales, opacities, sh_coeff, features=None, sh_degree=None, overwrite=False)

Write a 3D Gaussian splatting-style PLY (f_dc_*, f_rest_*, opacity, scale_*, rot_*).

Values are stored in the same raw space expected by import_gaussiancloud() when apply_activations=True (log-density, log-scale, unnormalized quaternion components).

Parameters

  • file_path (str) – path to the PLY file.

  • positions (torch.Tensor) – position of each gaussian, of shape \(( ext{num_gaussians}, 3)\).

  • orientations (torch.Tensor) – orientation of each gaussian as quaternions, as \((w, x, y, z)\), of shape \(( ext{num_gaussians}, 4)\).

  • scales (torch.Tensor) – scale of each gaussian, of shape \(( ext{num_gaussians}, 3)\).

  • opacities (torch.Tensor) – opacity of each gaussian, of shape \(( ext{num_gaussians})\).

  • sh_coeff (torch.Tensor) – spherical harmonics coefficients of each gaussian, of shape \(( ext{num_gaussians}, ( ext{num_degrees} + 1)^2, 3)\).

  • features (dict, optional) – extra per-gaussian fields to serialize alongside the standard schema. Must be a dict mapping str name -> torch.Tensor of shape \(( ext{num_gaussians}, K)\). Each entry is written as flat properties {name}_0 ... {name}_{K-1} and is round-trippable through import_gaussiancloud() (which restores it under GaussianSplatModel.features[name]). Defaults to None.

  • sh_degree (int) – optionally pass for sanity checking, otherwise will guess the value

  • overwrite (bool, optional) – whether to overwrite the file if it already exists. Defaults to False.

Raises

  • RuntimeError – if the file already exists and overwrite is False.

  • ValueError – if features has an invalid type/shape or a key collides with the standard schema prefixes.

kaolin.io.ply.import_gaussiancloud(filename: str, apply_activations=True, scale_activation=<built-in method exp of type object>, rotation_activation=<function normalize>, density_activation=<built-in method sigmoid of type object>)

Import a 3D Gaussian Splat cloud from a PLY file.

Parameters

  • filename (str) – path to the PLY file.

  • apply_activations (bool, optional) – whether to apply the activations to the data. Defaults to True.

  • scale_activation (callable, optional) – activation function to apply to the scale. Defaults to torch.exp.

  • rotation_activation (callable, optional) – activation function to apply to the rotation. Defaults to torch.nn.functional.normalize.

  • density_activation (callable, optional) – activation function to apply to the density. Defaults to torch.sigmoid.

Returns

A single gaussian cloud object.

Return type

(GaussianSplatModel)