Luce packages
LuceLuce BaseLuciaOS

dymokomi/luce-ply

Source of release 0.1.0

0.1.0 / tests / ply / splat_checks.lucb

## 3D Gaussian splats: the reference layout round trips byte for byte, the
## channel-major f_rest become interleaved items, compressed PLY decodes,
## and a 1M-splat file's read and write times are reported.
import memory
import strings
import c
import time
from luce_std import math, files
from luce_geocore.core.growing import Growing
from luce_geocore.kernel import GeometrySet, Attribute, AttributeStore, Domain, PointCloud, dispose_set, points_component, cloud_store, set_mesh
from luce_ply.kernel import Format, Warnings, decode, encode, read_file, write_file, invalid
from build import Bytes

## The reference header for `count` splats with `rest` f_rest properties.
func splat_header(count: usize, rest: usize, out: Growing[u8]*) -> !:
    var line: u8[96]
    try put(out, "ply\nformat binary_little_endian 1.0\n")
    try put(out, try strings.format(line, f"element vertex {count}\n"))
    let leading: str[9] = ["x", "y", "z", "nx", "ny", "nz", "f_dc_0", "f_dc_1", "f_dc_2"]
    for name in leading: try put(out, try strings.format(line, f"property float {name}\n"))
    for index in 0..<rest: try put(out, try strings.format(line, f"property float f_rest_{index}\n"))
    let trailing: str[8] = ["opacity", "scale_0", "scale_1", "scale_2", "rot_0", "rot_1", "rot_2", "rot_3"]
    for name in trailing: try put(out, try strings.format(line, f"property float {name}\n"))
    try put(out, "end_header\n")

func put(out: Growing[u8]*, text: str) -> !:
    for byte in text.bytes: try out.push(byte)

## A 3DGS file of `count` splats with `rest` f_rest values each: pseudo-random
## floats from a fixed seed, normals zero. `value(row, property)` is what the
## hand-built checks expect when `seeded` is false.
func splat_file(count: usize, rest: usize, seeded: bool, out: Growing[u8]*) -> !:
    try splat_header(count, rest, out)
    let floats = 17 + rest
    let start = out.count
    try out.extend(start + count * floats * 4, 0)
    let body = out.items[start..<start + count * floats * 4]
    var state: u64 = 0x9E3779B97F4A7C15
    for row in 0..<count:
        for property in 0..<floats:
            var value: f32 = 0.0
            if property >= 3 and property < 6:
                value = 0.0
            elif seeded:
                state = state *% 6364136223846793005 +% 1442695040888963407
                value = (f32)((f64)(state >> 40) / 16777216.0 * 8.0 - 4.0)
            else:
                value = (f32)(row * 100 + property)
            memory.write[u32]((void*)&body[(row * floats + property) * 4], value.bits())

func cloud_of(geometry: const GeometrySet*) -> const PointCloud*!:
    let data = geometry.find(points_component()) else error(invalid, "no cloud")
    return (const PointCloud*)data

func entry(attributes: const AttributeStore*, name: str) -> const Attribute*!:
    let index = attributes.find(name, Domain.point)
    if index < 0:
        print(f"missing attribute {name}")
        error(invalid, "a missing attribute")
    return attributes.entry((usize)index)

func same_bytes(a: const u8[], b: const u8[]) -> bool:
    if a.length != b.length: return false
    for at in 0..<a.length:
        if a[at] != b[at]: return false
    return true

## Read and write a 3DGS file of each degree: the same bytes come back.
pub func round_trips() -> !:
    let rests: usize[4] = [0, 9, 24, 45]
    for rest in rests:
        var file = Growing[u8]()
        defer file.close()
        try splat_file(1000, rest, true, &file)
        var warnings = Warnings()
        defer warnings.close()
        let geometry = try decode(file.view(), &warnings)
        defer dispose_set(geometry)
        let attributes = cloud_store(try cloud_of(geometry))
        # Zero normals are dropped; the raw names stay.
        assert(attributes.find("N", Domain.point) < 0 and attributes.find("opacity", Domain.point) >= 0)
        assert((attributes.find("f_rest", Domain.point) >= 0) == (rest > 0))
        let data = try encode(geometry, Format.little_endian, &warnings)
        defer free(data) in memory.heap
        if not same_bytes(data, file.view()): print(f"the {rest}-f_rest round trip differs")
        assert(same_bytes(data, file.view()))
        assert(warnings.text.count == 0)

## A hand-built file: f_rest_k of splat r holds r * 100 + 9 + k. Item i of
## splat r's f_rest array must hold f_rest_{c * 15 + i} in channel c.
pub func interleaving() -> !:
    var file = Growing[u8]()
    defer file.close()
    try splat_file(2, 45, false, &file)
    var warnings = Warnings()
    defer warnings.close()
    let geometry = try decode(file.view(), &warnings)
    defer dispose_set(geometry)
    let cloud = try cloud_of(geometry)
    assert(cloud.count() == 2 and cloud.point(1).x == 100.0 and cloud.point(1).z == 102.0)
    let attributes = cloud_store(cloud)
    let rest = try entry(attributes, "f_rest")
    assert(rest.is_ragged() and rest.width == 3)
    for row in 0..<(usize)2:
        assert(rest.item_count(row) == 15)
        for item in 0..<(usize)15:
            for channel in 0..<(usize)3:
                assert(rest.item(row, item, channel) == (f64)(row * 100 + 9 + channel * 15 + item))
    # The other properties keep their PLY names and values.
    assert((try entry(attributes, "f_dc_2")).number(1, 0) == 108.0)
    assert((try entry(attributes, "opacity")).number(1, 0) == 154.0)
    assert((try entry(attributes, "rot_3")).number(0, 0) == 61.0)

## A PlayCanvas compressed file: one chunk, two splats and degree-1 SH.
pub func compressed() -> !:
    var out = Bytes()
    defer out.close()
    try out.text("ply\nformat binary_little_endian 1.0\nelement chunk 1\n")
    let bounds: str[12] = ["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"]
    for name in bounds:
        var line: u8[64]
        try out.text(try strings.format(line, f"property float {name}\n"))
    try out.text("element vertex 2\nproperty uint packed_position\nproperty uint packed_rotation\nproperty uint packed_scale\nproperty uint packed_color\n")
    try out.text("element sh 2\n")
    for index in 0..<(usize)9:
        var line: u8[64]
        try out.text(try strings.format(line, f"property uchar f_rest_{index}\n"))
    try out.text("end_header\n")
    let values: f32[12] = [-1.0, -2.0, -3.0, 1.0, 2.0, 3.0, -5.0, -5.0, -5.0, 0.0, 0.0, 0.0]
    for value in values: try out.put_f32(value)
    # Splat 0: everything at the maximum; identity rotation (w largest).
    try out.put_u32(0xFFFFFFFF)
    try out.put_u32(((u32)0 << 30) | ((u32)512 << 20) | ((u32)512 << 10) | (u32)512)
    try out.put_u32(0xFFFFFFFF)
    try out.put_u32(0xFF000080)
    # Splat 1: everything at the minimum; z largest.
    try out.put_u32(0)
    try out.put_u32(((u32)3 << 30) | ((u32)512 << 20) | ((u32)512 << 10) | (u32)512)
    try out.put_u32(0)
    try out.put_u32(0x000000FF)
    for row in 0..<(usize)2:
        for index in 0..<(usize)9: try out.put_u8((u8)(0 if row == 0 else (255 if index == 4 else 128)))
    var warnings = Warnings()
    defer warnings.close()
    let geometry = try decode(out.view(), &warnings)
    defer dispose_set(geometry)
    let cloud = try cloud_of(geometry)
    assert(cloud.count() == 2)
    let top = cloud.point(0)
    let low = cloud.point(1)
    assert(top.x == 1.0 and top.y == 2.0 and top.z == 3.0 and low.x == -1.0 and low.z == -3.0)
    let attributes = cloud_store(cloud)
    assert((try entry(attributes, "scale_0")).number(0, 0) == 0.0 and (try entry(attributes, "scale_2")).number(1, 0) == -5.0)
    assert(math.abs((try entry(attributes, "rot_0")).number(0, 0) - 1.0) < 0.000002)
    assert(math.abs((try entry(attributes, "rot_3")).number(1, 0) - 1.0) < 0.000002)
    assert(math.abs((try entry(attributes, "rot_1")).number(0, 0)) < 0.001)
    assert(math.abs((try entry(attributes, "f_dc_0")).number(0, 0) - 0.5 / 0.28209479177387814) < 0.00001)
    assert(math.abs((try entry(attributes, "f_dc_0")).number(1, 0) + 0.5 / 0.28209479177387814) < 0.00001)
    assert(math.abs((try entry(attributes, "opacity")).number(0, 0) + math.log(255.0 / 128.0 - 1.0)) < 0.00001)
    let rest = try entry(attributes, "f_rest")
    assert(rest.item_count(0) == 3 and rest.item(0, 2, 1) == -4.0)
    # Splat 1: f_rest_4 (channel 1, coefficient 1) is 255, the rest 128.
    assert(rest.item(1, 1, 1) == 4.0 and rest.item(1, 0, 0) == (128.5 / 256.0 - 0.5) * 8.0)

## A synthetic 1M-splat degree-3 file: read and write times, reported.
pub func timings(scratch: str) -> !:
    let count: usize = 1000000
    var file = Growing[u8]()
    defer file.close()
    try splat_file(count, 45, true, &file)
    var path_buffer: u8[1024]
    let path = try strings.format(path_buffer, f"{scratch}/million.ply")
    try write_file(path, file.view())
    let megabytes = (f64)file.count / 1048576.0
    file.close()
    file = Growing[u8]()
    var warnings = Warnings()
    defer warnings.close()
    var best_read: f64 = 1.0e9
    var best_write: f64 = 1.0e9
    for attempt in 0..<(usize)3:
        _ = attempt
        let started = time.now()
        var mapped = try read_file(path)
        defer mapped.release()
        let geometry = try decode(mapped.value, &warnings)
        defer dispose_set(geometry)
        let read_seconds = (f64)time.since(started) / 1.0e9
        assert((try cloud_of(geometry)).count() == count)
        let encoding = time.now()
        let data = try encode(geometry, Format.little_endian, &warnings)
        defer free(data) in memory.heap
        let write_seconds = (f64)time.since(encoding) / 1.0e9
        assert(same_bytes(data, mapped.value))
        best_read = math.min(best_read, read_seconds)
        best_write = math.min(best_write, write_seconds)
    try files.remove_file((c.str)path)
    print(f"1M splats, degree 3, {megabytes:.0f} MB: read {best_read * 1000.0:.1f} ms ({megabytes / best_read:.0f} MB/s), encode {best_write * 1000.0:.1f} ms ({megabytes / best_write:.0f} MB/s)")