Luce packages
LuceLuce BaseLuciaOS

dymokomi/luce-ply

Source of release 0.1.0

0.1.0 / src / compressed.lucb

## PlayCanvas compressed PLY (SuperSplat, splat-transform): a `chunk` element
## of bounds per 256 splats, a `vertex` element of four packed u32s per splat
## and an optional `sh` element of u8 `f_rest_*`. It decodes to the raw 3DGS
## names the plain splat path gives (reader.lucb): positions, `f_dc_0..2`,
## `opacity` (a logit), `scale_0..2` (logs), `rot_0..3` (w, x, y, z) and the
## interleaved `f_rest` array. Decoding follows splat-transform's
## decompress-ply: positions and scales 11/10/11-bit unorms between the
## chunk's bounds, colors 8-bit unorms (between the chunk's color bounds when
## it has them), rotations smallest-three with 10 bits each and the largest
## component's index in the top two bits.
import memory
from luce_std import math, parallel
from luce_geocore.geocore import Vector3
from luce_geocore.core.growing import Growing
from luce_geocore.core.shared import Column
from luce_geocore.kernel import Float3, Attribute, AttributeStore, Domain, DataType, GeometrySet, empty_set, dispose_set, points_component, cloud_assembled
from header import Header, Format
from scalars import Scalar
from body import Sink, Lane, decode_element
from warnings import Warnings
import errors

## Splats per chunk.
let chunk_size: usize = 256
let chunk_names: str[18] = ["min_x", "min_y", "min_z", "max_x", "max_y", "max_z", "min_scale_x", "min_scale_y", "min_scale_z", "max_scale_x", "max_scale_y", "max_scale_z", "min_r", "min_g", "min_b", "max_r", "max_g", "max_b"]
let packed_names: str[4] = ["packed_position", "packed_rotation", "packed_scale", "packed_color"]
let output_names: str[11] = ["f_dc_0", "f_dc_1", "f_dc_2", "opacity", "scale_0", "scale_1", "scale_2", "rot_0", "rot_1", "rot_2", "rot_3"]
let sh_c0: f64 = 0.28209479177387814

## Whether `header` is a compressed PLY's: a binary body, `chunk` and
## `vertex` elements of the shapes above and at most an `sh` element more.
pub func is_compressed(header: const Header*) -> bool:
    if header.format == Format.ascii: return false
    let count = header.elements.count
    if count != 2 and count != 3: return false
    let chunk = header.find("chunk")
    let vertex = header.find("vertex")
    if chunk < 0 or vertex < 0: return false
    let bounds = header.properties_of((usize)chunk)
    if bounds.length != 12 and bounds.length != 18: return false
    for at in 0..<bounds.length:
        let index = header.property((usize)chunk, chunk_names[at])
        if index < 0 or bounds[(usize)index].kind != Scalar.float32 or bounds[(usize)index].is_list: return false
    let packed = header.properties_of((usize)vertex)
    if packed.length != 4: return false
    for name in packed_names:
        let index = header.property((usize)vertex, name)
        if index < 0 or packed[(usize)index].kind != Scalar.uint32 or packed[(usize)index].is_list: return false
    let splats = header.elements.items[(usize)vertex].count
    if (splats + chunk_size - 1) // chunk_size != header.elements.items[(usize)chunk].count: return false
    if count == 3:
        let sh = header.find("sh")
        if sh < 0: return false
        let rest = header.properties_of((usize)sh)
        if rest.length != 9 and rest.length != 24 and rest.length != 45: return false
        if header.elements.items[(usize)sh].count != splats: return false
        for property in rest:
            if property.kind != Scalar.uint8 or property.is_list: return false
    return true

## The decoded columns, freed together. `values` holds the eleven output
## columns one after another, `splats` floats each.
struct Decoded:
    var bounds: Growing[f32]
    var packed: Growing[i64]
    var sh: Growing[i32]
    var values: Growing[f32]
    var positions: Growing[Float3]
    var rest: Growing[f32]
    var rest_count: usize
    var chunk_columns: usize
    var splats: usize

    func close():
        self.bounds.close()
        self.packed.close()
        self.sh.close()
        self.values.close()
        self.positions.close()
        self.rest.close()

## A compressed PLY's splats as a point cloud set.
pub func decode(header: const Header*, data: const u8[], warnings: Warnings*) -> GeometrySet*!:
    _ = warnings
    let chunk = (usize)header.find("chunk")
    let vertex = (usize)header.find("vertex")
    let sh = header.find("sh")
    let splats = header.elements.items[vertex].count
    let chunks = header.elements.items[chunk].count
    let chunk_columns = header.properties_of(chunk).length
    let rest_count = header.properties_of((usize)sh).length if sh >= 0 else 0
    var decoded = Decoded(splats = splats, chunk_columns = chunk_columns, rest_count = rest_count)
    defer decoded.close()
    try decoded.bounds.fill(chunks * chunk_columns, 0.0)
    try decoded.packed.fill(splats * 4, 0)
    try decoded.sh.fill(splats * rest_count, 0)
    try decoded.values.fill(splats * 11, 0.0)
    try decoded.positions.fill(splats, Float3(0.0, 0.0, 0.0))
    try decoded.rest.fill(splats * rest_count, 0.0)
    # The elements, in file order.
    var at = header.body
    for element in 0..<header.elements.count:
        at = try decode_packed(header, element, chunk, vertex, data, at, &decoded)
    try parallel.for_each_range(splats, 4096, (void*)&decoded, unpack_block)
    # The cloud: positions and the attributes, copied out of the scratch columns.
    var store = AttributeStore()
    fill_store(&decoded, &store) catch failure:
        store.close()
        error(failure.code, failure.message)
    var positions = Column[Float3].copy_of(decoded.positions.items[..<splats]) catch failure:
        store.close()
        error(failure.code, failure.message)
    let geometry = empty_set() catch failure:
        positions.release()
        store.close()
        error(failure.code, failure.message)
    errdefer dispose_set(geometry)
    # cloud_assembled takes the positions and the store, even on failure.
    let cloud = try cloud_assembled(positions.take(), Vector3(), store)
    try geometry.put(points_component(), (void*)cloud)
    return geometry

## The eleven scalar attributes and the f_rest array, from the scratch columns.
func fill_store(decoded: const Decoded*, store: AttributeStore*) -> !:
    let splats = decoded.splats
    let rest_count = decoded.rest_count
    for index in 0..<(usize)11:
        var attribute = try Attribute.create(output_names[index], Domain.point, DataType.float32, 1, splats)
        let out = attribute.data.span()
        memory.copy(f32[]((f32*)out.data, splats), decoded.values.items[index * splats..<(index + 1) * splats], splats)
        try store.put(attribute)
    if rest_count == 0: return
    var offsets = try Column[u8].allocate((splats + 1) * 4)
    errdefer offsets.release()
    let bounds = offsets.span()
    for row in 0..<splats + 1: memory.write[u32]((void*)&bounds[row * 4], (u32)(row * (rest_count // 3)))
    var values = try Column[u8].copy_of(u8[]((u8*)decoded.rest.items.data, splats * rest_count * 4))
    errdefer values.release()
    try store.put(try Attribute.ragged("f_rest", Domain.point, DataType.float32, 3, offsets.take(), values.take()))

## Decode element `element` of a compressed file into `decoded`'s scratch
## columns: chunk bounds in chunk_names order, packed words in
## packed_names order, and the sh bytes.
func decode_packed(header: const Header*, element: usize, chunk: usize, vertex: usize, data: const u8[], at: usize, decoded: Decoded*) -> usize!:
    let properties = header.properties_of(element)
    var sinks = Growing[Sink]()
    defer sinks.close()
    for index in 0..<properties.length:
        _ = index
        try sinks.push(Sink())
    let sink = sinks.items[..<sinks.count]
    if element == chunk:
        for name_at in 0..<decoded.chunk_columns:
            let index = (usize)header.property(chunk, chunk_names[name_at])
            sink[index] = Sink(data = (u8*)decoded.bounds.items.data + name_at * 4, lane = Lane.float32, stride = decoded.chunk_columns * 4)
    elif element == vertex:
        for name_at in 0..<(usize)4:
            let index = (usize)header.property(vertex, packed_names[name_at])
            sink[index] = Sink(data = (u8*)decoded.packed.items.data + name_at * 8, lane = Lane.int64, stride = 32)
    else:
        for index in 0..<properties.length:
            sink[index] = Sink(data = (u8*)decoded.sh.items.data + index * 4, lane = Lane.int32, stride = decoded.rest_count * 4)
    return try decode_element(header, element, data, at, sink)

func unorm(value: u64, bits: u64) -> f64:
    let most = ((u64)1 << bits) - 1
    return (f64)(value & most) / (f64)most

func lerp(a: f32, b: f32, t: f64) -> f64:
    return (f64)a * (1.0 - t) + (f64)b * t

func unpack_block(context: void*, first: usize, end: usize, worker: usize):
    _ = worker
    let decoded = (Decoded*)context
    let width = decoded.chunk_columns
    let norm = 1.0 / (math.sqrt(2.0) * 0.5)
    let per_channel = decoded.rest_count // 3
    for splat in first..<end:
        let bounds = decoded.bounds.items[(splat // chunk_size) * width..<(splat // chunk_size + 1) * width]
        let position = (u64)decoded.packed.items[splat * 4]
        let rotation = (u64)decoded.packed.items[splat * 4 + 1]
        let scale = (u64)decoded.packed.items[splat * 4 + 2]
        let color = (u64)decoded.packed.items[splat * 4 + 3]
        decoded.positions.items[splat] = Float3((f32)lerp(bounds[0], bounds[3], unorm(position >> 21, 11)), (f32)lerp(bounds[1], bounds[4], unorm(position >> 11, 10)), (f32)lerp(bounds[2], bounds[5], unorm(position, 11)))
        let n_splats = decoded.splats
        let c = decoded.values.items
        c[4 * n_splats + splat] = (f32)lerp(bounds[6], bounds[9], unorm(scale >> 21, 11))
        c[5 * n_splats + splat] = (f32)lerp(bounds[7], bounds[10], unorm(scale >> 11, 10))
        c[6 * n_splats + splat] = (f32)lerp(bounds[8], bounds[11], unorm(scale, 11))
        var channels: f64[3] = [unorm(color >> 24, 8), unorm(color >> 16, 8), unorm(color >> 8, 8)]
        if width == 18:
            for lane in 0..<(usize)3: channels[lane] = lerp(bounds[12 + lane], bounds[15 + lane], channels[lane])
        for lane in 0..<(usize)3: c[lane * n_splats + splat] = (f32)((channels[lane] - 0.5) / sh_c0)
        c[3 * n_splats + splat] = (f32)(-math.log(1.0 / unorm(color, 8) - 1.0))
        let a = (unorm(rotation >> 20, 10) - 0.5) * norm
        let b = (unorm(rotation >> 10, 10) - 0.5) * norm
        let d = (unorm(rotation, 10) - 0.5) * norm
        let m = math.sqrt(math.max(0.0, 1.0 - (a * a + b * b + d * d)))
        var quaternion: f64[4] = [a, b, d, 0.0]
        let largest = (usize)(rotation >> 30)
        var source: usize = 0
        for lane in 0..<(usize)4:
            if lane == largest:
                c[(7 + lane) * n_splats + splat] = (f32)m
            else:
                c[(7 + lane) * n_splats + splat] = (f32)quaternion[source]
                source += 1
        if decoded.rest_count > 0:
            for index in 0..<decoded.rest_count:
                let value = decoded.sh.items[splat * decoded.rest_count + index]
                let n = 0.0 if value == 0 else (1.0 if value == 255 else ((f64)value + 0.5) / 256.0)
                let channel = index // per_channel
                let coefficient = index % per_channel
                decoded.rest.items[splat * decoded.rest_count + coefficient * 3 + channel] = (f32)((n - 0.5) * 8.0)