dymokomi/luce-spz
Source of release 0.1.0
0.1.0 / src / coordinates.lucb
## SPZ's sixteen coordinate systems and the conversions between them. A
## system names where its x, y and z axes point: systems 1-8 are x Left or
## Right, y Down or Up, z Back or Front (RUB, 4, is SPZ's own, OpenGL's; RDF,
## 6, is a 3DGS PLY's, COLMAP's); systems 9-16 are x Left or Right, y Front or
## Back, z Down or Up (Z-up worlds).
##
## A conversion is a signed permutation M of the axes. Positions take M p.
## Within a family M is diagonal, a set of axis flips, and the reference's
## exact sign rules apply: a quaternion's x, y and z flip by the products of
## the other two axes' signs (the rotation M R M), and each SH coefficient by
## the parity of its basis function. Across families M also turns 90° about
## X: quaternions turn by M (or -M when M reflects) and the SH by luce-geocore's
## SH transform of M.
from luce_geocore.splats import Quat, Mat3, ShSamples, ShRotation
## The system SPZ stores by default, and a 3DGS PLY's.
pub let rub: u32 = 4
pub let rdf: u32 = 6
## The systems are numbered 1 to this.
pub let system_count: u32 = 16
## Axis directions in RDF coordinates: right, down, front and their opposites.
func right(sign: i8) -> i8[3]:
return [sign, 0, 0]
func down(sign: i8) -> i8[3]:
return [0, sign, 0]
func front(sign: i8) -> i8[3]:
return [0, 0, sign]
## The matrix taking system `system`'s coordinates to RDF's (row-major, its
## columns the system's axes in RDF coordinates).
func to_rdf(system: u32) -> i8[9]:
let n = system - 1
let standard = n < 8
let bits = n % 8
let x = right(1 if bits % 2 == 1 else -1)
var y: i8[3]
var z: i8[3]
if standard:
y = down(-1 if (bits // 2) % 2 == 1 else 1)
z = front(1 if (bits // 4) % 2 == 1 else -1)
else:
y = front(-1 if (bits // 4) % 2 == 1 else 1)
z = down(-1 if (bits // 2) % 2 == 1 else 1)
var m: i8[9]
for row in 0..<(usize)3:
m[row * 3] = x[row]
m[row * 3 + 1] = y[row]
m[row * 3 + 2] = z[row]
return m
## The SH coefficients' signs under axis flips (x, y, z): bands 1 to 3 in the
## 3DGS order, each coefficient's basis function's parity in x, y and z.
func flip_signs(x: f32, y: f32, z: f32) -> f32[15]:
return [y, z, x, x * y, y * z, 1.0, x * z, 1.0, y, x * y * z, y, z, x, z, x]
## A conversion of splats from one system to another.
pub struct Converter:
## M, row-major, entries -1, 0 or 1.
var m: i8[9]
## Whether M is diagonal (flips only), and its signs then.
var flips: bool
var signs: f32[3]
var sh_signs: f32[15]
## Otherwise: the rotation quaternions turn by, and the SH transform.
var turn: Quat
var sh: ShRotation
## The conversion from system `source` to system `target` (1..16).
pub static func between(source: u32, target: u32) -> Converter:
let a = to_rdf(source)
let b = to_rdf(target)
# M = Bᵀ A: to RDF from the source, then from RDF to the target.
var result: Converter
for row in 0..<(usize)3:
for column in 0..<(usize)3:
var sum: i32 = 0
for k in 0..<(usize)3: sum += (i32)b[k * 3 + row] * (i32)a[k * 3 + column]
result.m[row * 3 + column] = (i8)sum
result.flips = result.m[1] == 0 and result.m[2] == 0 and result.m[3] == 0 and result.m[5] == 0 and result.m[6] == 0 and result.m[7] == 0
if result.flips:
result.signs = [(f32)result.m[0], (f32)result.m[4], (f32)result.m[8]]
result.sh_signs = flip_signs(result.signs[0], result.signs[1], result.signs[2])
return result
var values: f64[9]
for at in 0..<(usize)9: values[at] = (f64)result.m[at]
let matrix = Mat3(values)
# A reflection's rotation part is -M (its covariance is the same).
result.turn = Quat.of_matrix(matrix.scaled(-1.0 if matrix.determinant() < 0.0 else 1.0))
let samples = ShSamples.make()
result.sh = ShRotation.of_matrix(&samples, matrix)
return result
## Whether the conversion changes nothing.
pub func identity() -> bool:
return self.flips and self.signs[0] == 1.0 and self.signs[1] == 1.0 and self.signs[2] == 1.0
## A position (x, y, z) converted in place.
pub func position(p: f32[]):
if self.flips:
# Multiplied, as the reference does: a flipped zero is -0.
for k in 0..<(usize)3: p[k] = p[k] * self.signs[k]
return
let (x, y, z) = (p[0], p[1], p[2])
for row in 0..<(usize)3:
p[row] = (f32)self.m[row * 3] * x + (f32)self.m[row * 3 + 1] * y + (f32)self.m[row * 3 + 2] * z
## A rotation quaternion (x, y, z, w) converted in place.
pub func rotation(q: f32[]):
if self.flips:
q[0] = q[0] * self.signs[1] * self.signs[2]
q[1] = q[1] * self.signs[0] * self.signs[2]
q[2] = q[2] * self.signs[0] * self.signs[1]
return
let turned = self.turn.multiply(Quat((f64)q[0], (f64)q[1], (f64)q[2], (f64)q[3]))
q[0] = (f32)turned.x
q[1] = (f32)turned.y
q[2] = (f32)turned.z
q[3] = (f32)turned.w
## `items` SH coefficients (RGB interleaved, bands 1..3) converted in place.
pub func sh_items(values: f32[], items: usize):
if self.flips:
for item in 0..<(items if items < 15 else 15):
let sign = self.sh_signs[item]
for channel in 0..<(usize)3: values[item * 3 + channel] = values[item * 3 + channel] * sign
return
self.sh.apply(values, items)