dymokomi/luce-ply
Source of release 0.1.0
## 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)