Blender V5.3
spz_read_common.cc
Go to the documentation of this file.
1/* SPDX-FileCopyrightText: 2026 Blender Authors
2 *
3 * SPDX-License-Identifier: GPL-2.0-or-later */
4
5#include "spz_read_common.hh"
6
7#include <array>
8
9#include "BLI_array.hh"
10#include "BLI_assert.hh"
12#include "BLI_math_rotation.hh"
13
14#include "IO_gsplat.hh"
15
16namespace blender::io::spz {
17
18namespace {
19
20/* Spherical harmonics rotation matrices for R_x(+pi/2).
21 * Each entry operates on the 2l+1 coefficients of band l (l = 1..4).
22 *
23 * The table is adopted from the SPZ Library project:
24 *
25 * MIT License
26 * Copyright (c) 2024 Niantic Labs
27 *
28 * There are modifications in the code to use Blender utilities, and also to operate on float3
29 * elements rather than on scalars.
30 *
31 * The matrices structure seems to match description given in the
32 *
33 * Didier Pinchon1 and Philip E. Hoggan
34 * "Rotation matrices for real spherical harmonics: general rotations of atomic orbitals in
35 * space-fixed axes" (2007)
36 * Journal of Physics A: Mathematical and Theoretical.
37 * DOI:10.1088/1751-8113/40/7/011
38 *
39 * This could also be confirmed by checking against a naive implementation of the Wigner D-matrix
40 * [WignerDMatrix]. When doing so a basis conversion needs to be applied to convert complex
41 * spherical harmonics to real [SphericalRealForm].
42 *
43 * References:
44 * [WignerDMatrix] https://en.wikipedia.org/wiki/Wigner_D-matrix
45 * [SphericalRealForm] https://en.wikipedia.org/wiki/Spherical_harmonics#Real_form */
46inline constexpr std::array<void (*)(MutableSpan<float3>), 4>
47 ANALYTIC_ROTATE_PLUS_PI_HALF_ABOUT_X_TABLE = {
48 [](const MutableSpan<float3> p) {
49 BLI_assert(p.size() == 3);
50 const float3 t0 = p[0], t1 = p[1], t2 = p[2];
51 p[0] = t1;
52 p[1] = -t0;
53 p[2] = t2;
54 },
55 [](const MutableSpan<float3> p) {
56 BLI_assert(p.size() == 5);
57 std::array<float3, 5> s;
58 MutableSpan(s).copy_from(p);
59 const float s3 = std::sqrt(3.0f);
60 p[0] = s[3];
61 p[1] = -s[1];
62 p[2] = -0.5f * s[2] - (s3 / 2.0f) * s[4];
63 p[3] = -s[0];
64 p[4] = -(s3 / 2.0f) * s[2] + 0.5f * s[4];
65 },
66 [](const MutableSpan<float3> p) {
67 BLI_assert(p.size() == 7);
68 std::array<float3, 7> s{};
69 MutableSpan(s).copy_from(p);
70 const float s15 = std::sqrt(15.0f);
71 p[0] = -std::sqrt(5.0f / 8.0f) * s[3] + std::sqrt(3.0f / 8.0f) * s[5];
72 p[1] = -s[1];
73 p[2] = -std::sqrt(3.0f / 8.0f) * s[3] - std::sqrt(5.0f / 8.0f) * s[5];
74 p[3] = std::sqrt(5.0f / 8.0f) * s[0] + std::sqrt(3.0f / 8.0f) * s[2];
75 p[4] = -0.25f * s[4] - (s15 / 4.0f) * s[6];
76 p[5] = -std::sqrt(3.0f / 8.0f) * s[0] + std::sqrt(5.0f / 8.0f) * s[2];
77 p[6] = -(s15 / 4.0f) * s[4] + 0.25f * s[6];
78 },
79 [](const MutableSpan<float3> p) {
80 BLI_assert(p.size() == 9);
81 std::array<float3, 9> s{};
82 MutableSpan(s).copy_from(p);
83 const float s2 = std::sqrt(2.0f);
84 const float s5 = std::sqrt(5.0f);
85 const float s7 = std::sqrt(7.0f);
86 const float s14 = std::sqrt(14.0f);
87 const float s35 = std::sqrt(35.0f);
88 p[0] = -(s14 / 4.0f) * s[5] + (s2 / 4.0f) * s[7];
89 p[1] = -0.75f * s[1] + (s7 / 4.0f) * s[3];
90 p[2] = -(s2 / 4.0f) * s[5] - (s14 / 4.0f) * s[7];
91 p[3] = (s7 / 4.0f) * s[1] + 0.75f * s[3];
92 p[4] = (3.0f / 8.0f) * s[4] + (s5 / 4.0f) * s[6] + (s35 / 8.0f) * s[8];
93 p[5] = (s14 / 4.0f) * s[0] + (s2 / 4.0f) * s[2];
94 p[6] = (s5 / 4.0f) * s[4] + 0.5f * s[6] - (s7 / 4.0f) * s[8];
95 p[7] = -(s2 / 4.0f) * s[0] + (s14 / 4.0f) * s[2];
96 p[8] = (s35 / 8.0f) * s[4] - (s7 / 4.0f) * s[6] + 0.125f * s[8];
97 },
98};
99
100} // namespace
101
103 const MutableSpan<math::Quaternion> rotations,
104 const Span<MutableSpan<float3>> sh_attrs)
105{
106 /* By default, SPZ stores data in an RUB (Right, Up, Back) coordinate system following the OpenGL
107 * and three.js convention. Blender is RFU (Right, Forward, Up). */
108
109 /* TODO(sergey): Handle extensions that define coordinate system. */
110 /* Example: SPZ_ADOBE_coordinate_system. */
111
112 const int sh_degrees = gsplat::degree_for_dimension(sh_attrs.size());
113
114 struct LocalData {
115 Array<float3> sh_data;
116 };
118 threading::parallel_for(IndexRange(positions.size()), 32, [&](const IndexRange range) {
119 LocalData &tls = all_tls.local();
120 for (const int i : range) {
121 positions[i] = {positions[i].x, -positions[i].z, positions[i].y};
122
123 /* Simplified expression for the following:
124 * math::to_quaternion(math::AxisAngle(math::AxisSigned::X_POS, M_PI_2)) * rotations[i]. */
125 rotations[i] = math::Quaternion(M_SQRT1_2 * (rotations[i].w - rotations[i].x),
126 M_SQRT1_2 * (rotations[i].x + rotations[i].w),
127 M_SQRT1_2 * (rotations[i].y - rotations[i].z),
128 M_SQRT1_2 * (rotations[i].z + rotations[i].y));
129
130 if (sh_degrees == 0) {
131 continue;
132 }
133
134 if (tls.sh_data.is_empty()) {
135 tls.sh_data.reinitialize(sh_attrs.size());
136 }
137
138 MutableSpan<float3> sh_data = tls.sh_data;
139 gsplat::get_spherical_harmonics(sh_attrs, i, sh_data);
140 for (int band = 0; band < sh_degrees; ++band) {
141 ANALYTIC_ROTATE_PLUS_PI_HALF_ABOUT_X_TABLE[band](
142 sh_data.slice(band * (band + 2), 2 * (band + 1) + 1));
143 }
144 gsplat::set_spherical_harmonics(sh_attrs, i, sh_data);
145 }
146 });
147}
148
149} // namespace blender::io::spz
#define BLI_assert(a)
constexpr IndexRange()=default
constexpr MutableSpan()=default
constexpr int64_t size() const
Definition BLI_span.hh:499
int degree_for_dimension(const int dimension)
Definition IO_gsplat.hh:44
void convert_axis_to_blender(const MutableSpan< float3 > positions, const MutableSpan< math::Quaternion > rotations, const Span< MutableSpan< float3 > > sh_attrs)
void parallel_for(const IndexRange range, const int64_t grain_size, const Function &function, const TaskSizeHints &size_hints=detail::TaskSizeHints_Static(1))
Definition BLI_task.hh:69
VecBase< float, 3 > float3
void s2(float4 &a, float4 &b)