dymokomi/luce-geocore
Source of release 0.7.8
0.7.8 / src / splats / conventions.lucb
## Gaussian splats are point clouds with conventional point attributes, as
## in Houdini ("GSplats are point clouds"). A cloud is a splat cloud when its
## points carry `orient`, `scale` and `opacity`:
##
## - `orient`: f32 × 4, a quaternion x, y, z, w (Houdini's order), a rotation
## once normalized: Bake keeps a file's unnormalized quaternion as it is
## - `scale`: 3 floats, standard deviations along the local axes, linear
## - `opacity`: a float, linear 0..1
## - `Cd`: 3 floats, the view-independent color, linear like every `Cd`
## (Bake writes `scale`, `opacity` and `Cd` in f64, through which the file's
## logs, logits and DC terms come back bit for bit; any float type reads)
## - `sh`: a ragged f32 × 3 array, the SH bands 1..d, coefficient-major,
## RGB per item, m = -l..l: 0, 3, 8 or 15 items, the same on every point
## - `restorient`: f32 × 4, optional: the orient the `sh` were authored in
## - detail `gsplat_color_space`: "srgb" or "linear", the encoding the `sh`
## (and the file's colors) are in
##
## Color: `Cd` is linear. A trained capture's colors are sRGB-encoded, and
## its SH bands are offsets in that encoding, so Bake GSplats decodes only
## the DC color into `Cd` and keeps the bands as they are. A splat's color
## toward a direction is then decode(encode(Cd) + bands), which is exactly
## the trained color, and export recovers the file's DC term as
## (encode(Cd) - 0.5) / C0 (`display_color`, `file_dc`, `unbaked_store`).
## Linearizing the bands instead (Houdini decodes only Cd and leaves them,
## which mixes encodings; scaling them by the curve's slope is approximate)
## would change the colors a capture shows.
from luce_std import math, sort
import memory
import strings
from luce_color import transfer
from core.shared import Column
from core.attributes import Attribute, AttributeStore, DataType, Domain, Role, Storage
import core.attribute_ops
import core.ranges
from math.vector import Vector3
from math.matrix import Matrix4
from core.float3 import Float3
## The splat attributes' names.
pub let orient_name: str = "orient"
pub let scale_name: str = "scale"
pub let opacity_name: str = "opacity"
pub let color_name: str = "Cd"
pub let sh_name: str = "sh"
pub let restorient_name: str = "restorient"
## The detail attribute naming the colors' encoding.
pub let color_space_name: str = "gsplat_color_space"
## How a cloud's `sh` (and its source file's colors) are encoded.
pub enum ColorSpace as u8:
## sRGB-encoded: trained captures, the default.
srgb = 0
## Linear: splats trained on linear renders.
linear = 1
## The detail attribute's text for `space`.
pub func color_space_text(space: ColorSpace) -> str:
return "linear" if space == ColorSpace.linear else "srgb"
## The space a `gsplat_color_space` text names; sRGB unless it says "linear".
pub func color_space_of(text: str) -> ColorSpace:
return ColorSpace.linear if text == "linear" else ColorSpace.srgb
## The color space of a set's detail attributes (sRGB without one).
pub func detail_color_space(detail: const AttributeStore*) -> ColorSpace:
let index = detail.find(color_space_name, Domain.detail)
if index < 0: return ColorSpace.srgb
return color_space_of(detail.entry((usize)index).text_at(0))
## The index of float point attribute `name` of `width` with one tuple per point,
## or -1.
pub func float_attribute(store: const AttributeStore*, name: str, width: usize) -> i64:
let index = store.find(name, Domain.point)
if index < 0: return -1
let entry = store.entry((usize)index)
if entry.width != width or entry.storage == Storage.ragged: return -1
if entry.kind != DataType.float32 and entry.kind != DataType.float64: return -1
return index
## Whether a cloud's attributes make it a splat cloud: `orient` (4 floats),
## `scale` (3) and `opacity` (1) on its points.
pub func is_splat_store(store: const AttributeStore*) -> bool:
return float_attribute(store, orient_name, 4) >= 0 and float_attribute(store, scale_name, 3) >= 0 and float_attribute(store, opacity_name, 1) >= 0
## The index of the `sh` array (ragged f32 × 3 on points), or -1.
pub func sh_attribute(store: const AttributeStore*) -> i64:
let index = store.find(sh_name, Domain.point)
if index < 0: return -1
let entry = store.entry((usize)index)
if not entry.is_ragged() or entry.kind != DataType.float32 or entry.width != 3: return -1
return index
## The most SH items any point has (0 without `sh`).
pub func sh_items(store: const AttributeStore*) -> usize:
let index = sh_attribute(store)
if index < 0: return 0
let entry = store.entry((usize)index)
var most: usize = 0
for element in 0..<entry.elements:
let count = entry.item_count(element)
if count > most: most = count
return most
## SH items of bands 1..`degree`: 0, 3, 8 or 15.
pub func sh_count(degree: usize) -> usize:
return (degree + 1) * (degree + 1) - 1
## The degree whose bands `items` fill: 0 for 0..2, 1 for 3..7, 2 for 8..14,
## 3 from 15.
pub func sh_degree(items: usize) -> usize:
if items >= 15: return 3
if items >= 8: return 2
if items >= 3: return 1
return 0
## The band (1..3) of SH item `item` (0 is the first item of band 1).
pub func sh_band(item: usize) -> usize:
if item < 3: return 1
if item < 8: return 2
return 3
## 3DGS's opacity activation: the PLY's logit to a linear opacity.
pub func sigmoid(x: f64) -> f64:
if x >= 0.0: return 1.0 / (1.0 + math.exp(-x))
let e = math.exp(x)
return e / (1.0 + e)
## The inverse of `sigmoid`: a linear opacity to the PLY's logit. 0 and 1 are
## kept finite (±36.04, the logits of 2^-52 from the ends).
pub func logit(y: f64) -> f64:
let low: f64 = 2.220446049250313e-16
let clamped = math.clamp(y, low, 1.0 - low)
return math.log(clamped / (1.0 - clamped))
## A color component in `space` to linear (sRGB's curve, mirrored for
## negatives, so out-of-range values survive).
pub func to_linear(value: f64, space: ColorSpace) -> f64:
return transfer.srgb_decode(value) if space == ColorSpace.srgb else value
## A linear color component to `space`.
pub func from_linear(value: f64, space: ColorSpace) -> f64:
return transfer.srgb_encode(value) if space == ColorSpace.srgb else value