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)")