dymokomi/luce-geocore
Source of release 0.7.2
0.7.2 / src / splats / axes.lucb
## A half turn about X, (x, y, z) -> (x, -y, -z): how a Y-down capture is
## stood up. COLMAP's cameras look down +Z with +Y pointing down, and a
## structure-from-motion model keeps the first camera's frame, so nearly
## every 3DGS capture (trained on COLMAP poses) has its up along -Y. Bake
## GSplats' Up Axis turns such a file over, and export turns it back (the
## turn is its own inverse).
##
## The turn is exact in floats: positions, vectors and normals negate two
## components; rotations, `orient` among them, become i · q, which only moves
## and negates components. A splat's SH must turn with it. With a
## `restorient`, the SH frame orient · restorient⁻¹ turns with `orient`, and
## the bands stay. Without one the frame is the identity, so the bands
## themselves turn: under the half turn each basis function of 3DGS's real
## SH is even or odd in (y, z), and the odd ones' coefficients change sign.
## The detail attribute recording that a cloud was turned from a Y-down file,
## and its value.
pub let up_axis_name: str = "gsplat_up_axis"
pub let y_down_text: str = "y_down"
## Whether SH item `item` (bands 1..3 in order) changes sign under the turn:
## the items whose basis functions hold an odd power of y and z together.
let odd_items: bool[15] = [true, true, false, true, false, false, true, false, true, false, true, true, false, true, false]
## `store` (a cloud's `count` point attributes) turned a half turn about X:
## float position, vector and normal triples, rotation quaternions and, for a
## splat cloud, `orient` and the SH (see above). The cloud's positions are the
## caller's to turn. Columns it does not change are shared. `back` turns by
## -i instead, so a cloud turned and turned back has its quaternions bit for
## bit (i · i · q is -q, the same rotation in other bits).
pub func half_turned_store(store: const AttributeStore*, count: usize, back: bool = false) -> AttributeStore!:
var result = try store.shared()
errdefer result.close()
let splats = is_splat_store(store)
let rest = float_attribute(store, restorient_name, 4) >= 0
for index in 0..<result.count():
let entry = result.entry(index)
if entry.storage != Storage.array or (entry.kind != DataType.float32 and entry.kind != DataType.float64): continue
let name = entry.name()
let wide = entry.kind == DataType.float64
if entry.width == 4 and (entry.role == Role.rotation or (splats and name == orient_name)):
# A restorient keeps the frame the SH were authored in.
if splats and name == restorient_name: continue
turn_quaternions(try result.writable(index), wide, count, back)
continue
let role = entry.role
if entry.width == 3 and (role == Role.position or role == Role.vector or role == Role.normal):
negate_lanes(try result.writable(index), wide, count)
if not splats or rest: return result
let sh_index = sh_attribute(&result)
if sh_index < 0: return result
let entry = result.entry((usize)sh_index)
var first_items = try new usize[count + 1] --- in memory.heap
defer free(first_items) in memory.heap
for element in 0..<count: first_items[element] = entry.first_item(element)
first_items[count] = entry.first_item(count - 1) + entry.item_count(count - 1) if count > 0 else 0
let values = try writable_sh(&result, (usize)sh_index)
var work = FlipWork(values, first_items)
ranges.each_range(count, 16384, (void*)&work, flip_range)
return result
## Component-wise half turns, on f32 or f64 storage.
func negate_lanes(bytes: u8[], wide: bool, count: usize):
for at in 0..<count:
if wide:
let values = attribute_ops.typed_mut[f64](bytes)
values[at * 3 + 1] = -values[at * 3 + 1]
values[at * 3 + 2] = -values[at * 3 + 2]
else:
let values = attribute_ops.typed_mut[f32](bytes)
values[at * 3 + 1] = -values[at * 3 + 1]
values[at * 3 + 2] = -values[at * 3 + 2]
## q -> i · q: (x, y, z, w) -> (w, -z, y, -x); `back`: -i · q.
func turn_quaternions(bytes: u8[], wide: bool, count: usize, back: bool):
for at in 0..<count:
let base = at * 4
if wide:
let v = attribute_ops.typed_mut[f64](bytes)
let (x, y, z, w) = (v[base], v[base + 1], v[base + 2], v[base + 3])
v[base] = -w if back else w
v[base + 1] = z if back else -z
v[base + 2] = -y if back else y
v[base + 3] = x if back else -x
else:
let v = attribute_ops.typed_mut[f32](bytes)
let (x, y, z, w) = (v[base], v[base + 1], v[base + 2], v[base + 3])
v[base] = -w if back else w
v[base + 1] = z if back else -z
v[base + 2] = -y if back else y
v[base + 3] = x if back else -x
struct FlipWork:
let values: f32[]
let first_items: const usize[]
func flip_range(context: void*, first: usize, end: usize, worker: usize):
_ = worker
let work = (FlipWork*)context
for element in first..<end:
let start = work.first_items[element]
let items = work.first_items[element + 1] - start
for item in 0..<(items if items < 15 else 15):
if not odd_items[item]: continue
for channel in 0..<(usize)3:
let at = (start + item) * 3 + channel
work.values[at] = -work.values[at]