Compression

gsplat provides handy APIs for compressing and decompressing the Gaussian parameters, which can significantly reduce the storage / streaming cost. For example, using PngCompression, 1 million Gaussians that are stored in 236 MB can be compressed to 16.5 MB, with only 0.5dB PSNR loss (29.18dB to 28.65dB).

Similar to the Densification, our compression APIs also has a specific expectation on the format of the Gaussian parameters. It is designed to work with the Gaussians defined as either a Dict of torch.Tensor with at least the following keys: {“means”, “scales”, “quats”, “opacities”, “sh0”, “shN”}. On top of these attributes, an arbitrary number of extra attributes are supported.

The following code snippet is an example of how to use the compression approach in gsplat:

from gsplat import PngCompression

splats: Dict[str, Tensor] = {
    "means": Tensor(N, 3), "scales": Tensor(N, 3), "quats": Tensor(N, 4), "opacities": Tensor(N),
    "sh0": Tensor(N, 1, 3), "shN": Tensor(N, 24, 3), "features1": Tensor(N, 128), "features2": Tensor(N, 64),
}

compression_method = PngCompression()
# run compression and save the compressed files to compress_dir
compression_method.compress(compress_dir, splats)
# decompress the compressed files
splats_c = compression_method.decompress(compress_dir)

Below is the API for the compression approaches we support in gsplat:

class PngCompression(use_sort: bool = True, verbose: bool = True)

Uses quantization and sorting to compress splats into PNG files and uses K-means clustering to compress the spherical harmonic coefficents.

Warning

This class requires the imageio, plas and torchpq packages to be installed.

Warning

This class might throw away a few lowest opacities splats if the number of splats is not a square number.

Note

The splats parameters are expected to be pre-activation values. It expects the following fields in the splats dictionary: “means”, “scales”, “quats”, “opacities”, “sh0”, “shN”. More fields can be added to the dictionary, but they will only be compressed using NPZ compression.

References

• Compact 3D Scene Representation via Self-Organizing Gaussian Grids

• Making Gaussian Splats more smaller

Parameters:

• use_sort (bool, optional) – Whether to sort splats before compression. Defaults to True.

• verbose (bool, optional) – Whether to print verbose information. Default to True.

compress(compress_dir: str, splats: Dict[str, Tensor]) → None

Run compression

Parameters:

• compress_dir (str) – directory to save compressed files

• splats (Dict[str, Tensor]) – Gaussian splats to compress

decompress(compress_dir: str) → Dict[str, Tensor]

Run decompression

Parameters:

compress_dir (str) – directory that contains compressed files

Returns:

decompressed Gaussian splats

Return type:

Dict[str, Tensor]