Luce packages
LuceLuce BaseLuciaOS

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)