dymokomi/luce-usd
Source of release 0.9.3
0.9.3 / src / convert / export_splats.lucb
## A splat cloud written as ParticleField3DGaussianSplat prims (see
## particle_fields.lucb for the schema and the SH convention), one per value
## of the splats' `path` text, as meshes and Points split (all at the
## fallback path without one, or unsplit): positions with their extent, `orientations` (orient normalized), linear
## `scales` and `opacities`, and `radiance:sphericalHarmonicsCoefficients`
## per splat: the file DC (the cloud's `Cd` encoded back into its color
## space, as luce-geocore's unbaked_store gives f_dc) then its SH bands, in
## the world frame (a `restorient` is baked in). The hints come from the
## detail texts `gsplat_sorting_mode` and `gsplat_projection_mode` (zDepth
## and perspective by default); a linear cloud says so in the custom
## `luce:gsplatColorSpace`, and a cloud stood up from a Y-down file (detail
## `gsplat_up_axis`) in the custom `luce:gsplatUpAxis`. The coefficients
## carry `interpolation = "vertex"` and `elementSize = (d + 1)²`, as OpenUSD's
## converters write them. Other point attributes are left out.
##
## Arrays are floats, or halves (`positionsh`, `orientationsh`, `scalesh`,
## `opacitiesh`, `radiance:sphericalHarmonicsCoefficientsh`) when the export
## options ask for them or, by default, when the cloud came from halves
## (detail `usd.halfSplats`).
## `cloud`'s splats as ParticleField3DGaussianSplat prims under `base`, split
## by `path` (else at `fallback`); `detail` is the set's detail.
func export_splats(cloud: const PointCloud*, detail: const AttributeStore*, author: Author*, base: u32, fallback: u32, options: const ExportOptions*, warnings: Warnings*) -> !:
let store = cloud_store(cloud)
var parts = Growing[ElementPart]()
defer close_element_parts(&parts)
try split_elements(store, Domain.point, cloud.count(), author.names, base, fallback, options.split, &parts)
var half = options.splat_precision == 2
if options.splat_precision == 0:
let found = detail.find(half_splats_name, Domain.detail)
half = found >= 0 and detail.entry((usize)found).kind != DataType.text and detail.entry((usize)found).number(0, 0) != 0.0
let space = detail_color_space(detail)
var raw = try unbaked_store(store, cloud.count(), space)
defer raw.close()
for part in parts.view():
try export_splat_prim(cloud, detail, &raw, author, part.path, part.elements.view(), half)
for index in 0..<store.count():
let entry = store.entry(index)
if entry.domain != Domain.point: continue
let name = entry.name()
if name == orient_name or name == restorient_name or name == scale_name or name == opacity_name or name == color_name or name == sh_name or name == "path": continue
try warnings.add("Point attributes other than the splats' were left out of the ParticleField3DGaussianSplat")
break
## The splats `elements` names as one ParticleField3DGaussianSplat at `path`;
## `raw` is the cloud unbaked (f_dc, f_rest in the world frame).
func export_splat_prim(cloud: const PointCloud*, detail: const AttributeStore*, raw: const AttributeStore*, author: Author*, path: u32, elements: const i32[], half: bool) -> !:
let names = author.names
let store = cloud_store(cloud)
let count = elements.length
let space = detail_color_space(detail)
let items = sh_items(store)
let degree = sh_degree(items)
let per_particle = (degree + 1) * (degree + 1)
var work = SplatWrite(count = count, elements = elements, per_particle = per_particle, items = sh_count(degree), half = half)
for k in 0..<(usize)3:
work.dc[k] = point_floats(raw, f_dc_name(k), 1) else error(errors.invalid, "a splat cloud lost its DC color in unbaking")
work.orient = point_floats(store, orient_name, 4) else error(errors.invalid, "a splat cloud has no orient")
work.scale = point_floats(store, scale_name, 3) else error(errors.invalid, "a splat cloud has no scale")
work.opacity = point_floats(store, opacity_name, 1) else error(errors.invalid, "a splat cloud has no opacity")
let rest = raw.find("f_rest", Domain.point)
if rest >= 0: work.rest = raw.entry((usize)rest)
# Halves take 2 bytes a component, floats 4.
let size: usize = 2 if half else 4
var orientations = try Column[u8].allocate(count * 4 * size)
defer orientations.release()
var scales = try Column[u8].allocate(count * 3 * size)
defer scales.release()
var opacities = try Column[u8].allocate(count * size)
defer opacities.release()
var coefficients = try Column[u8].allocate(count * per_particle * 3 * size)
defer coefficients.release()
work.orientations = orientations.span()
work.scales = scales.span()
work.opacities = opacities.span()
work.coefficients = coefficients.span()
try parallel.for_each_range(count, grain, (void*)&work, write_splats)
let tokens = try GeomTokens.of(names)
let spec = try author.define(path, tokens.particle_field_splat, tokens.xform)
if half:
try write_half_positions(author, path, spec, cloud_positions(cloud), cloud_origin(cloud), elements)
_ = try author.attribute(path, spec, "orientationsh", "quath[]", false, Value.of_array(ValueKind.quath, count, orientations.take()))
_ = try author.attribute(path, spec, "scalesh", "half3[]", false, Value.of_array(ValueKind.vec3h, count, scales.take()))
_ = try author.attribute(path, spec, "opacitiesh", "half[]", false, Value.of_array(ValueKind.half, count, opacities.take()))
else:
try write_positions(author, path, spec, cloud_positions(cloud), cloud_origin(cloud), elements, false, "positions")
_ = try author.attribute(path, spec, "orientations", "quatf[]", false, Value.of_array(ValueKind.quatf, count, orientations.take()))
_ = try author.attribute(path, spec, "scales", "float3[]", false, Value.of_array(ValueKind.vec3f, count, scales.take()))
_ = try author.attribute(path, spec, "opacities", "float[]", false, Value.of_array(ValueKind.float, count, opacities.take()))
_ = try author.attribute(path, spec, "radiance:sphericalHarmonicsDegree", "int", true, Value.scalar(ValueKind.int, (u64)degree))
let coefficient_name = "radiance:sphericalHarmonicsCoefficientsh" if half else "radiance:sphericalHarmonicsCoefficients"
let radiance = try author.attribute(path, spec, coefficient_name, "half3[]" if half else "float3[]", false, Value.of_array(ValueKind.vec3h if half else ValueKind.vec3f, count * per_particle, coefficients.take()))
try author.token_field(radiance, tokens.interpolation, "vertex")
try author.layer.set(radiance, tokens.element_size, Value.scalar(ValueKind.int, (u64)per_particle))
_ = try author.attribute(path, spec, "sortingModeHint", "token", true, Value.scalar(ValueKind.token, (u64)(try names.token(detail_text(detail, "gsplat_sorting_mode", "zDepth")))))
_ = try author.attribute(path, spec, "projectionModeHint", "token", true, Value.scalar(ValueKind.token, (u64)(try names.token(detail_text(detail, "gsplat_projection_mode", "perspective")))))
if space == ColorSpace.linear:
let marked = try author.attribute(path, spec, "luce:gsplatColorSpace", "token", true, Value.scalar(ValueKind.token, (u64)(try names.token("linear"))))
try author.layer.set(marked, author.layer.keys.custom, Value.scalar(ValueKind.boolean, 1))
let up = detail_text(detail, up_axis_name, "")
if up.length > 0:
let axis = try author.attribute(path, spec, "luce:gsplatUpAxis", "token", true, Value.scalar(ValueKind.token, (u64)(try names.token(up))))
try author.layer.set(axis, author.layer.keys.custom, Value.scalar(ValueKind.boolean, 1))
## Positions of `points` placed back at the origin as `positionsh`
## (point3h[]), with their extent in floats.
func write_half_positions(author: Author*, path: u32, spec: usize, positions: const Float3[], origin: Vector3, points: const i32[]) -> !:
var low: f64[3] = [math.infinity, math.infinity, math.infinity]
var high: f64[3] = [-math.infinity, -math.infinity, -math.infinity]
var column = try Column[u8].allocate(points.length * 6)
errdefer column.release()
let out = column.span()
for at in 0..<points.length:
let p = positions[(usize)points[at]]
let xyz: f64[3] = [(f64)p.x + origin.x, (f64)p.y + origin.y, (f64)p.z + origin.z]
for axis in 0..<(usize)3:
# The extent bounds what the halves hold.
let stored = (f64)(f16)xyz[axis]
low[axis] = math.min(low[axis], stored)
high[axis] = math.max(high[axis], stored)
put_half(out, at * 3 + axis, xyz[axis])
_ = try author.attribute(path, spec, "positionsh", "point3h[]", false, Value.of_array(ValueKind.vec3h, points.length, column.take()))
let extent: f32[6] = [(f32)low[0], (f32)low[1], (f32)low[2], (f32)high[0], (f32)high[1], (f32)high[2]]
_ = try author.attribute(path, spec, "extent", "float3[]", false, try array_of(ValueKind.vec3f, 2, u8[]((u8*)&extent[0], 24)))
## Component `at` of a half or float array's bytes set to `value`.
func put_half(out: u8[], at: usize, value: f64):
# + 0.0 turns -0 into 0.
memory.write[u16]((void*)&out[at * 2], ((f16)(value + 0.0)).bits())
func put_number(out: u8[], at: usize, value: f64, half: bool):
if half: put_half(out, at, value)
else: memory.write[f32]((void*)&out[at * 4], (f32)value)
## "f_dc_0", "f_dc_1" or "f_dc_2".
func f_dc_name(k: usize) -> str:
return "f_dc_0" if k == 0 else ("f_dc_1" if k == 1 else "f_dc_2")
## Detail text `name`, or `fallback`.
func detail_text(detail: const AttributeStore*, name: str, fallback: str) -> str:
let index = detail.find(name, Domain.detail)
if index < 0 or detail.entry((usize)index).kind != DataType.text: return fallback
let text = detail.entry((usize)index).text_at(0)
return text if text.length > 0 else fallback
## A cloud's splats and the arrays they fill.
struct SplatWrite:
var count: usize
## The cloud's splats the prim holds, in order.
var elements: const i32[]
var per_particle: usize
## SH items written per splat (bands 1..degree).
var items: usize
var dc: Floats[3]
var orient: Floats
var scale: Floats
var opacity: Floats
var rest: const Attribute*?
## Halves rather than floats.
var half: bool
## The arrays' bytes.
var orientations: u8[]
var scales: u8[]
var opacities: u8[]
var coefficients: u8[]
func write_splats(context: void*, first: usize, end: usize, worker: usize):
_ = worker
let work = (SplatWrite*)context
let half = work.half
for at in first..<end:
let splat = (usize)work.elements[at]
let q = Quat(work.orient.at(splat, 0), work.orient.at(splat, 1), work.orient.at(splat, 2), work.orient.at(splat, 3)).normalized()
let values: f64[4] = [q.x, q.y, q.z, q.w]
for k in 0..<(usize)4: put_number(work.orientations, at * 4 + k, values[k], half)
for k in 0..<(usize)3: put_number(work.scales, at * 3 + k, work.scale.at(splat, k), half)
put_number(work.opacities, at, work.opacity.at(splat, 0), half)
let base = at * work.per_particle * 3
for k in 0..<(usize)3: put_number(work.coefficients, base + k, work.dc[k].at(splat, 0), half)
let rest = work.rest else continue
let held = rest.item_count(splat)
for item in 0..<work.items:
for channel in 0..<(usize)3:
put_number(work.coefficients, base + 3 + item * 3 + channel, rest.item(splat, item, channel) if item < held else 0.0, half)