.SOG File Format

Introduction

SOG (Spatially Ordered Gaussians) is a compressed format for Gaussian splat scenes from PlayCanvas. It stores each attribute of the splats as the pixels of an image, one pixel a splat, saved as lossless WebP, with a meta.json file that says how to turn the pixels back into values. The images compress well because the splats are sorted so that neighbouring pixels hold splats that are close together in space.

A SOG scene is either a folder of these files or a ZIP archive of them, usually named .sog. The description below is of version 3, the current one; version 2 differs as listed at the end.

Structure

Every per-splat image has the same size, and splat i is the pixel at x = i mod W, y = ⌊i / W⌋, counting from the top left, for an image W pixels wide. The image may have more pixels than there are splats; the extra ones are ignored. The images must be lossless, because lossy compression would change the values.

meta.json

Readers ignore keys they do not know.

From the pixels to a Gaussian

• Position: for each axis, the high byte from means_u and the low byte from means_l make a 16-bit value q. Interpolate from mins to maxs by q / 65535 to get n, then undo the log transform: sign(n) × (e^|n| − 1).
• Rotation: each byte b of red, green and blue gives p = (b − 128) / 127, a vector (p_x, p_y, p_z). With r its length and θ = π/2 × r, the quaternion is w = cos θ and (x, y, z) = p × sin θ / r (zero when r is 0). The bytes 128, 128, 128 are no rotation.
• Scale: each channel is an index into the scales codebook, which holds logarithms; the scale is e to the power of the entry.
• Colour: each of red, green and blue in sh0 is an index into the sh0 codebook, and the colour is 0.5 + entry × SH_C0, with SH_C0 = 1 / (2√π).
• Opacity: (A / 204)², from the alpha byte A of sh0. 204 is an opacity of 1, and 255 about 1.5625, which a scene can use for splats that stand for several merged ones.

Spherical harmonics

The harmonics above degree 0 are shared through a palette. Each splat’s label in shN_labels is red + green × 256 + blue × 65536, the number of its palette entry. A palette entry has 3, 8, 15 or 24 coefficients a channel for 1, 2, 3 or 4 bands. shN_centroids holds 64 entries a row, so it is 64 × coefficients wide: coefficient c of entry n is the pixel at u = (n mod 64) × coefficients + c, v = ⌊n / 64⌋. Its red, green and blue are indices into the shN codebook for the three channels.

Version 2

Positions, scales, base colours, the palette layout and the file layout are the same in both.

Links