Luce packages
LuceLuce BaseLuciaOS

dymokomi/luce-spz

Source of release 0.1.0

0.1.0 / src / writer.lucb

## A splat cloud as an SPZ file. The cloud is read in a 3DGS PLY's raw names
## (reader.lucb); a cloud in luce-geocore's conventions (`orient`, `scale`,
## `opacity`, `Cd`, `sh`) is unbaked to them first. Raw names are taken to be
## in a PLY's RDF axes, as unbaking a cloud baked from a Y-down file gives
## them; a baked cloud without `gsplat_up_axis` is already Y-up, SPZ's RUB.
## The splats are quantized as Niantic's packer quantizes them (in f32, the
## same rounding), in parallel blocks, and written as version 4 (zstd
## streams), or 3 or 2 (gzip) on request.
import memory
from luce_std import math32, parallel
from luce_geocore.kernel import Float3, AttributeStore, Attribute, Domain, DataType, GeometrySet, set_cloud, set_splats, set_detail, unbaked_set, dispose_set, cloud_positions, cloud_origin, cloud_store
from luce_geocore.splats import Floats, point_floats, up_axis_name, y_down_text
from format import Header, sh_dimension, max_kept_degree, latest_version, antialiased_flag
from container import Packed, write_container
from coordinates import Converter, rdf, rub
from reader import raw_names, antialiased_name
from warnings import Warnings
import errors

## How to write.
pub struct EncodeOptions:
    ## 2, 3 or 4.
    pub var version: u32 = 4
    ## Fractional bits of the 24-bit positions; fewer when the cloud is too
    ## large for them (with a warning).
    pub var fractional_bits: u32 = 12
    ## Bits kept of band 1's SH bytes, and of bands 2 and 3's (1 to 8): fewer
    ## bits compress better.
    pub var sh1_bits: u32 = 5
    pub var rest_bits: u32 = 4
    ## The zstd level of version 4's streams (luce-compress's 1 to 9; higher
    ## levels write as 9). On the 1.16M-splat Mip-NeRF 360 bonsai, level 3
    ## encodes in 0.15 s to 23.6 MB and level 9 in 0.58 s to 22.7 MB (4% less):
    ## 3 by default, as zstd's own default.
    pub var level: i32 = 3

## The SPZ file of `geometry`'s splats, on memory.heap (the caller frees it).
pub func encode(geometry: const GeometrySet*, options: const EncodeOptions*, warnings: Warnings*) -> u8[]!:
    if options.version < 2 or options.version > latest_version: error(errors.unsupported, "SPZ versions 2 to 4 are written")
    if options.sh1_bits < 1 or options.sh1_bits > 8 or options.rest_bits < 1 or options.rest_bits > 8:
        error(errors.invalid, "SH bits are 1 to 8")
    # A baked cloud goes back to the raw names; a Y-down one to RDF axes.
    var unbaked: GeometrySet*? = none
    defer:
        if let made = unbaked: dispose_set(made)
    var source: const GeometrySet* = geometry
    var system = rdf
    if set_splats(geometry) != none:
        let made = try unbaked_set(geometry)
        unbaked = made
        source = made
        let detail = set_detail(geometry)
        let up = detail.find(up_axis_name, Domain.detail)
        if up < 0 or detail.entry((usize)up).text_at(0) != y_down_text: system = rub
    let cloud = set_cloud(source) else error(errors.invalid, "the geometry has no point cloud to write as splats")
    var work = try PackWork.of(cloud_store(cloud), cloud.count(), options)
    work.positions = cloud_positions(cloud)
    work.origin = [cloud_origin(cloud).x, cloud_origin(cloud).y, cloud_origin(cloud).z]
    work.converter = Converter.between(system, rub)
    var header: Header
    header.version = options.version
    header.splats = cloud.count()
    header.degree = work.degree
    header.fractional_bits = try fitting_bits(&work, options.fractional_bits, warnings)
    header.flags = antialiased_flag if antialiased(set_detail(geometry)) else 0
    if header.splats == 0: error(errors.invalid, "an SPZ holds at least one splat")
    if header.splats > 0x7FFFFFFF: error(errors.limit, "an SPZ holds at most 2³¹ - 1 splats")
    var packed = try Packed.allocate(header)
    defer packed.close()
    work.packed = &packed
    try parallel.for_each_range(header.splats, 4096, (void*)&work, pack_range)
    return try write_container(&packed, options.level)

## Whether the detail attributes set the antialiased flag.
func antialiased(detail: const AttributeStore*) -> bool:
    let index = detail.find(antialiased_name, Domain.detail)
    if index < 0: return false
    let entry = detail.entry((usize)index)
    return entry.kind != DataType.text and entry.number(0, 0) != 0.0

## The fractional bits to write: `wanted`, or fewer until every converted
## position fits 24 signed bits.
func fitting_bits(work: const PackWork*, wanted: u32, warnings: Warnings*) -> u32!:
    var largest: f32 = 0.0
    for at in 0..<work.positions.length:
        let p = work.position(at)
        for k in 0..<(usize)3:
            let size = p[k] if p[k] >= 0.0 else -p[k]
            if size > largest or not (size == size): largest = size
    if not (largest == largest) or largest > 8.0e6: error(errors.limit, "positions past ±8388607 do not fit an SPZ")
    var bits = wanted if wanted < 24 else 23
    while bits > 0 and math32.round(largest * (f32)((u32)1 << bits)) > 8388607.0: bits -= 1
    if bits < wanted: try warnings.add("Positions were written with fewer fractional bits: the cloud is too large for the ones asked")
    return bits

## The columns packed and where they go.
struct PackWork:
    var packed: Packed*?
    var converter: Converter
    var positions: const Float3[]
    var origin: f64[3]
    var columns: Floats[11]
    var rest: const Attribute*?
    var degree: usize
    var sh1_bucket: i32
    var rest_bucket: i32

    static func of(store: const AttributeStore*, count: usize, options: const EncodeOptions*) -> PackWork!:
        var work: PackWork
        for index in 0..<(usize)11:
            work.columns[index] = point_floats(store, raw_names[index], 1) else error(errors.invalid, "the cloud has no 3DGS splat attributes (f_dc_0..2, opacity, scale_0..2, rot_0..3)")
        let found = store.find("f_rest", Domain.point)
        if found >= 0:
            let entry = store.entry((usize)found)
            if not entry.is_ragged() or entry.width != 3 or entry.kind != DataType.float32: error(errors.invalid, "f_rest is not an array of RGB items")
            var most: usize = 0
            for element in 0..<count:
                if entry.item_count(element) > most: most = entry.item_count(element)
            work.rest = entry
            work.degree = 3 if most >= 15 else (2 if most >= 8 else (1 if most >= 3 else 0))
        work.sh1_bucket = (i32)1 << (8 - options.sh1_bits)
        work.rest_bucket = (i32)1 << (8 - options.rest_bits)
        return work

    ## Splat `at`'s position in SPZ's axes, in f32 as the reference holds it.
    func position(at: usize) -> f32[3]:
        let offset = self.positions[at]
        var p: f32[3] = [(f32)(self.origin[0] + (f64)offset.x), (f32)(self.origin[1] + (f64)offset.y), (f32)(self.origin[2] + (f64)offset.z)]
        self.converter.position(p)
        return p

func pack_range(context: void*, first: usize, end: usize, worker: usize):
    _ = worker
    let work = (PackWork*)context
    let packed = work.packed else return
    let header = packed.header
    let positions = packed.stream(0)
    let alphas = packed.stream(1)
    let colors = packed.stream(2)
    let scales = packed.stream(3)
    let rotations = packed.stream(4)
    let sh = packed.stream(5)
    let scale = (f32)((u32)1 << header.fractional_bits)
    let items = sh_dimension(work.degree)
    for at in first..<end:
        let p = work.position(at)
        for k in 0..<(usize)3:
            let fixed = (i32)math32.round(p[k] * scale)
            # 24-bit two's complement (fitting_bits keeps it in range).
            let bits = (u32)(fixed + 0x1000000) if fixed < 0 else (u32)fixed
            for byte in 0..<(usize)3: positions[(at * 3 + k) * 3 + byte] = (u8)(bits >> (u32)(byte * 8))
        let c = work.columns
        for k in 0..<(usize)3:
            colors[at * 3 + k] = to_byte((f32)c[k].at(at, 0) * (0.15 * 255.0) + 0.5 * 255.0)
            scales[at * 3 + k] = to_byte(((f32)c[4 + k].at(at, 0) + 10.0) * 16.0)
        alphas[at] = to_byte(sigmoid((f32)c[3].at(at, 0)) * 255.0)
        # x, y, z, w from the PLY's w, x, y, z; normalized, then converted.
        var q: f32[4] = [(f32)c[8].at(at, 0), (f32)c[9].at(at, 0), (f32)c[10].at(at, 0), (f32)c[7].at(at, 0)]
        let length = math32.sqrt(q[0] * q[0] + q[1] * q[1] + q[2] * q[2] + q[3] * q[3])
        if length > 0.0:
            for k in 0..<(usize)4: q[k] = q[k] / length
        else: q = [0.0, 0.0, 0.0, 1.0]
        work.converter.rotation(q)
        if header.smallest_three(): pack_smallest_three(q, rotations[at * 4..<at * 4 + 4])
        else: pack_first_three(q, rotations[at * 3..<at * 3 + 3])
        if items == 0: continue
        var values: f32[45]
        if let rest = work.rest:
            let held = rest.item_count(at)
            for item in 0..<(held if held < items else items):
                for channel in 0..<(usize)3: values[item * 3 + channel] = (f32)rest.item(at, item, channel)
        work.converter.sh_items(values, items)
        for item in 0..<items:
            let bucket = work.sh1_bucket if item < 3 else work.rest_bucket
            for channel in 0..<(usize)3: sh[(at * items + item) * 3 + channel] = quantized_sh(values[item * 3 + channel], bucket)

## `x` rounded (halves away from zero) and clamped to a byte.
func to_byte(x: f32) -> u8:
    let rounded = math32.round(x)
    if not (rounded > 0.0): return 0
    if rounded > 255.0: return 255
    return (u8)rounded

func sigmoid(x: f32) -> f32:
    return 1.0 / (1.0 + math32.exp(-x))

## An SH coefficient as a byte: x · 128 + 128, then the nearest multiple of
## `bucket` (so 0 stays 128), clamped.
func quantized_sh(x: f32, bucket: i32) -> u8:
    var q = (i32)math32.round(x * 128.0) + 128
    q = (q + bucket // 2) // bucket * bucket
    if q < 0: return 0
    if q > 255: return 255
    return (u8)q

## Versions 3 and 4: the largest component made positive (q and -q are the
## same rotation) and left out; the others as sign and 9-bit magnitude, as the
## reference packs them (which tests `< 0`, so it differs only for a -0).
func pack_smallest_three(q: const f32[], out: u8[]):
    var largest: usize = 0
    for k in 1..<(usize)4:
        if math32.abs(q[k]) > math32.abs(q[largest]): largest = k
    let negate = q[largest] < 0.0
    var packed = (u32)largest
    for k in 0..<(usize)4:
        if k == largest: continue
        # The sign bit, not `< 0`: a decoded -0 (a tiny negative stored as
        # magnitude 0) keeps its bit, so decoding and encoding is exact.
        let negative = (q[k].bits() >> 31 != 0) != negate
        let magnitude = (u32)(511.0 * (math32.abs(q[k]) / sqrt_half) + 0.5)
        packed = (packed << 10) | ((1 if negative else 0) << 9) | magnitude
    for byte in 0..<(usize)4: out[byte] = (u8)(packed >> (u32)(byte * 8))

let sqrt_half: f32 = 0.70710678118654752

## Version 2: x, y and z of the quaternion with w ≥ 0, as bytes over -1..1.
func pack_first_three(q: const f32[], out: u8[]):
    let sign: f32 = -127.5 if q[3] < 0.0 else 127.5
    for k in 0..<(usize)3: out[k] = to_byte(q[k] * sign + 127.5)