GSplatBundle

from acron.gsplat import GSplatBundle

class GSplatBundle

Bases:

Bases: TypedReferenceCount

A Gaussian-splat bundle in the SOG v2 layout (“Spatially Ordered Gaussians”, the format PlayCanvas’s splat-transform writes), whatever it was read from: a .sog (a stored ZIP of meta.json + lossless webp planes, or a directory of the same files) or a 3DGS training .ply, which is packed into the same planes on load.

Every plane is an RGBA8 image of width x height texels with splat i at texel (i % width, i / width), row 0 first; get_plane() hands it out as a read-only CPTA_uchar in exactly that order (r, g, b, a per texel), so Python can wrap it zero-copy (memoryview, numpy.frombuffer) but cannot resize or write the bundle’s own storage. The planes:

• means_l / means_u: low / high bytes of a 16-bit position per axis, linear in sign(x)*log(1+|x|) between get_means_min() and get_means_max().

• quats: “smallest three” – a = 252 + the index (wxyz) of the dropped largest component, rgb the other three as (v / sqrt(2) + 0.5) * 255.

• scales: three indices into codebook column 0 (log scales).

• sh0: three indices into codebook column 1 (the DC SH term), opacity in a.

• shN_labels / shN_centroids: the higher-band SH palette. A label (16 bit in a .sog, 24 bit for a .ply’s direct palette) per splat into a centroid image holding get_sh_entries_per_row() entries per row, each entry get_sh_coeffs_per_channel() texels of codebook-column-2 indices.

The codebook is 256 x 4 floats (scales, sh0, shN, 0). The decode_*() methods are the CPU mirror of the shader’s decode, for sorting, tools and tests; from_arrays() / write_sog() / write_ply() are the inverse. The planes go to the GPU through make_plane_texture() (swizzled to Acron’s BGRA RAM order, nearest-filtered) undecoded.

Errors (an unreadable file, a malformed plane, arrays of the wrong size) return a null pointer or false and leave a message in get_last_error() (per thread; every call clears it first).

The readers treat their input as untrusted: header sizes are checked with overflow-safe arithmetic, every plane is checked against the splat count and its role, meta.json nesting is limited, and webp planes are capped at get_webp_max_pixels() pixels. The decode and derive methods are bounds-checked against the planes they read whatever the bundle holds.

Inheritance diagram

digraph inheritance93bdd47b3b { bgcolor=transparent; rankdir=BT; size="8.0, 12.0"; "DTOOL_SUPER_BASE" [fillcolor=white,fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=11,height=0.25,shape=box,style=""]; "GSplatBundle" [URL="acron.gsplat.GSplatBundle.html#acron.gsplat.GSplatBundle",fillcolor=white,fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=11,height=0.25,shape=box,style="",target="_top",tooltip="/**"]; "TypedReferenceCount" -> "GSplatBundle" [arrowsize=0.75,style=""]; "ReferenceCount" [URL="acron.core.ReferenceCount.html#acron.core.ReferenceCount",fillcolor=white,fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=11,height=0.25,shape=box,style="",target="_top",tooltip="/**"]; "DTOOL_SUPER_BASE" -> "ReferenceCount" [arrowsize=0.75,style=""]; "TypedObject" [URL="acron.core.TypedObject.html#acron.core.TypedObject",fillcolor=white,fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=11,height=0.25,shape=box,style="",target="_top",tooltip="/**"]; "DTOOL_SUPER_BASE" -> "TypedObject" [arrowsize=0.75,style=""]; "TypedReferenceCount" [URL="acron.core.TypedReferenceCount.html#acron.core.TypedReferenceCount",fillcolor=white,fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=11,height=0.25,shape=box,style="",target="_top",tooltip="/**"]; "TypedObject" -> "TypedReferenceCount" [arrowsize=0.75,style=""]; "ReferenceCount" -> "TypedReferenceCount" [arrowsize=0.75,style=""]; }

__init__()

An empty bundle (no splats, no planes).

property codebook → CPTA_float

property count → int

decimate()

Every step-th splat, repacked – a preview at a fraction of the cost (the first k splats of a bundle are a spatial chunk, this is a sample). A step of 1 or less gives a copy of the bundle.

decode_colors()

Colours: linear rgb from the DC term (unclamped) and the opacity, count x 4.

decode_log_scales()

Log scales per splat (count x 3), through the codebook.

decode_positions()

World positions, xyz per splat (count x 3 floats).

decode_quaternions()

Unit quaternions as (x, y, z, w) per splat (count x 4 floats).

decode_scales()

Linear scales (standard deviations along the local axes), count x 3.

decode_sh()

The higher-order SH coefficients through the palette and its codebook: count x coeffs x 3 floats (coefficient-major; the .ply’s f_rest is channel-major), bands (-1 = all the bundle’s) limiting how many. Empty (with an error) if the bundle was read without its palette. A label naming an entry the centroid image does not hold decodes as zeros.

static decode_webp()

not BLOCKING: it fills a caller-owned (Python) image

Decodes a lossless webp into image (4 channels, maxval 255). Returns false (see get_last_error()) for anything else, lossy webp included.

static encode_webp()

A lossless webp of the image (RGBA; a grey or alpha-less image is expanded). Empty on failure (an image over 16384 texels a side).

static encode_webp_rgba()

A lossless webp of tightly packed RGBA8 texels, row 0 first (a plane as get_plane() returns it). Empty if the sizes disagree.

static eval_sh()

The colour offset of higher-order SH coefficients for unit directions – the CPU mirror of the work-buffer shader’s evalSH (the real SH basis of the 3DGS reference). coeffs holds stride coefficients x 3 channels per splat (coefficient-major), dirs xyz per splat; the result is rgb per splat. Evaluated in double precision.

static from_arrays()

A bundle in memory from flat float arrays – the encoder’s first half, the inverse of the decode. positions xyz per splat, quaternions (x, y, z, w), scales linear, colors linear rgb + opacity; sh, if given, holds sh_coeffs (3 / 8 / 15) coefficients x 3 channels per splat (coefficient major). palette lays out the SH palette: “sog” (64 entries per row, 16-bit labels; n <= 65536), “direct” (one entry per splat, as many per row as a texture row fits, 24-bit labels) or “auto” (“sog” when it fits).

get_bounds_max()

get_bounds_min()

World-space bounds of the encoded range (the inverse log transform of the means range).

static get_class_type()

get_codebook()

get_count()

get_height()

static get_last_error()

The message of the last failed call on this thread (empty after a call that succeeded: every call clears it first).

get_means_max()

get_means_min()

get_meta_json()

The bundle’s meta.json: the file’s own text for a bundle read from a .sog, else one generated from the bundle (what write_sog() writes).

get_name()

get_plane()

The plane as RGBA8 texels, row 0 first (an empty array if absent): a read-only view of the bundle’s own storage, no copy.

get_plane_height()

get_plane_width()

get_sh_bands()

get_sh_coeffs_per_channel()

Coefficients per colour channel the palette holds (3 / 8 / 15 for 1 / 2 / 3 bands), from the centroid image’s width; 0 without a palette.

get_sh_entries_per_row()

static get_webp_max_pixels()

get_width()

has_plane()

has_sh_palette()

True if the bundle holds its SH palette (labels and centroids).

head()

The first count splats (a spatial chunk: tests and probes).

property height → int

make_codebook_texture()

The 256 x 1 RGBA32F codebook texture (scales, sh0, shN, 0 in r, g, b, a), nearest-filtered.

make_plane_texture()

The plane as a nearest-filtered, clamped RGBA8 texture, texel row 0 = plane row 0, swizzled into Acron’s BGRA RAM order so .rgba in GLSL reads the SOG’s channels. Null if the bundle has no such plane.

property name → string

static read()

A bundle from a .sog (file or directory) or a 3DGS .ply, by extension.

static read_ply()

Reads a 3DGS .ply (a trainer’s output: per-vertex x y z, f_dc_0..2, opacity as a logit, scale_0..2 as logs, rot_0..3 as (w, x, y, z) and f_rest_* channel-major) and packs it into the SOG planes. Binary (either endianness) and ASCII files are read. With with_sh the higher bands are kept, as a direct palette when there are more than 65536 splats.

static read_sog()

Reads a .sog bundle: a ZIP of meta.json and webp planes, or a directory holding the same files. The SH palette planes are read only with with_sh (the band count is known either way).

select()

The listed splats, repacked into planes of their own (the SH centroid image is shared, read-only; the codebook is copied). Indices out of range are an error, and so is a bundle whose per-splat planes hold fewer texels than its count.

set_name()

static set_webp_max_pixels()

The largest width x height a webp plane may declare (process-wide; the default is 64 Mpixel, 8192^2). A larger plane is refused before anything is allocated: a 28-byte file can declare 16384^2 pixels. 0 restores the default.

property sh_bands → int

property sh_coeffs_per_channel → int

Coefficients per colour channel the palette holds (3 / 8 / 15 for 1 / 2 / 3 bands), from the centroid image’s width; 0 without a palette.

property sh_entries_per_row → int

property width → int

static write_ply()

Writes a 3DGS .ply (binary little-endian) from flat arrays – the inverse of read_ply(), for tests and tools. Arguments as from_arrays().

write_sog()

Serialises the bundle as a .sog: a stored ZIP of meta.json and lossless webp planes. A direct (wide) SH palette is not a .sog layout and is refused.