Blender V5.3
spz_read_common.hh
Go to the documentation of this file.
1/* SPDX-FileCopyrightText: 2026 Blender Authors
2 *
3 * SPDX-License-Identifier: GPL-2.0-or-later */
4
8
9#pragma once
10
11#include <cmath>
12
13#include "BLI_array.hh"
14#include "BLI_math_constants.hh"
16#include "BLI_math_vector.hh"
18#include "BLI_span.hh"
19#include "BLI_unroll.hh"
20
21#include "IO_gsplat.hh"
22
23namespace blender::io::spz {
24
25namespace internal {
26
27template<class ReaderType>
28[[nodiscard]] inline bool read_single_position_as_fixed(ReaderType &reader, int3 &fixed)
29{
30 using PackedFloat = std::array<uint8_t, 3>;
31 using PackedFloat3 = std::array<PackedFloat, 3>;
32 PackedFloat3 packed;
33 if (!reader.read(packed)) {
34 return false;
35 }
36
37 unroll<3>([&](auto i) {
38 fixed[i] = packed[i][0];
39 fixed[i] |= packed[i][1] << 8;
40 fixed[i] |= packed[i][2] << 16;
41 fixed[i] |= (fixed[i] & 0x800000) ? 0xff000000 : 0;
42 });
43
44 return true;
45}
46
47inline float inv_sigmoid(const float x)
48{
49 return std::log(x / (1.0f - x));
50}
51
52} // namespace internal
53
54template<class ReaderType>
55[[nodiscard]] inline bool read_positions(ReaderType &reader,
56 const int fractional_bits,
57 const MutableSpan<float3> positions)
58{
59 /* From documentation:
60 *
61 * Positions are represented as (x, y, z) coordinates, each as a 24-bit fixed point signed
62 * integer. The number of fractional bits is determined by the fractionalBits field in the
63 * header. */
64 BLI_assert(fractional_bits >= 0 && fractional_bits < 24);
65 const float scale = 1.0f / (1 << fractional_bits);
66 for (float3 &position : positions) {
67 int3 fixed;
68 if (!internal::read_single_position_as_fixed(reader, fixed)) {
69 return false;
70 }
71 position = float3(fixed) * scale;
72 }
73 return true;
74}
75
76template<class ReaderType>
77[[nodiscard]] inline bool read_alphas(ReaderType &reader, const MutableSpan<float4> radiance_base)
78{
79 for (float4 &base : radiance_base) {
80 uint8_t alpha;
81 if (!reader.read(alpha)) {
82 return false;
83 }
84 if (false) {
85 /* The naive implementation.
86 * The inv_sigmoid() and decode_opacity() are actually canceling each other.
87 * Code kept for the reference and possible situation when other activation functions are
88 * used in the future. */
89 base.w = internal::inv_sigmoid(float(alpha) / 255.0f);
91 }
92 else {
93 base.w = float(alpha) / 255.0f;
94 }
95 }
96 return true;
97}
98
99template<class ReaderType>
100[[nodiscard]] inline bool read_colors(ReaderType &reader, const MutableSpan<float4> radiance_base)
101{
102 /* From SPZ:
103 * Scale factor for DC color components. To convert to RGB, we should multiply by 0.282, but it
104 * can be useful to represent base colors that are out of range if the higher spherical
105 * harmonics bands bring them back into range so we multiply by a smaller value. */
106 constexpr float COLOR_SCALE = 0.15f;
107 const float INV_COLOR_SCALE = 1.0f / COLOR_SCALE;
108
109 for (float4 &base : radiance_base) {
110 std::array<uint8_t, 3> color_buffer;
111 if (!reader.read_buffer(color_buffer)) {
112 return false;
113 }
114 base.x = ((color_buffer[0] / 255.0f) - 0.5f) * INV_COLOR_SCALE;
115 base.y = ((color_buffer[1] / 255.0f) - 0.5f) * INV_COLOR_SCALE;
116 base.z = ((color_buffer[2] / 255.0f) - 0.5f) * INV_COLOR_SCALE;
117 }
118
119 return true;
120}
121
122template<class ReaderType>
123[[nodiscard]] inline bool read_scales(ReaderType &reader, const MutableSpan<float3> scales)
124{
125 /* From documentation:
126 *
127 * Scales are represented as (x, y, z) components, each represented as an 8-bit log-encoded
128 * integer. */
129 for (float3 &scale : scales) {
130 std::array<uint8_t, 3> encoded;
131 if (!reader.read_buffer(encoded)) {
132 return false;
133 }
134 scale = float3(encoded[0], encoded[1], encoded[2]) / 16.0f - 10.0f;
136 }
137 return true;
138}
139
140template<class ReaderType>
141[[nodiscard]] inline bool read_rotations(ReaderType &reader,
142 const int version,
143 const MutableSpan<math::Quaternion> rotations)
144{
145 if (version == 2) {
146 /* From documentation:
147 *
148 * In version 2, rotations are represented as the (x, y, z) components of the normalized
149 * rotation quaternion. The w component can be derived from the others and is not stored.
150 * Each component is encoded as an 8-bit signed integer. */
151 for (math::Quaternion &rotation : rotations) {
152 std::array<uint8_t, 3> packed;
153 if (!reader.read_buffer(packed)) {
154 return false;
155 }
156
157 const float3 first3 = float3(packed[0], packed[1], packed[2]) / 127.5f - 1.0f;
158 rotation.w = std::sqrt(std::max(0.0f, 1.0f - math::dot(first3, first3)));
159 rotation.x = first3.x;
160 rotation.y = first3.y;
161 rotation.z = first3.z;
162 }
163
164 return true;
165 }
166
167 if (version >= 3) {
168 /* From documentation:
169 *
170 * In version 3, rotations are represented as the smallest three components of the normalized
171 * rotation quaternion, for optimal rotation accuracy. The largest component can be derived
172 * from the others and is not stored. Its index is stored on 2 bits and each of the smallest
173 * three components is encoded as a 10-bit signed integer. */
174 constexpr uint32_t COMPONENT_MASK = (1 << 9) - 1;
175 for (math::Quaternion &rotation : rotations) {
176 /* Read as individual bytes and re-pack to integer to ensure endianess. */
177 std::array<uint8_t, 4> packed_bytes;
178 if (!reader.read_buffer(packed_bytes)) {
179 return false;
180 }
181 float spz_rotation[4];
182 uint32_t packed = packed_bytes[0] + (packed_bytes[1] << 8) + (packed_bytes[2] << 16) +
183 (packed_bytes[3] << 24);
184 const int largest_index = packed >> 30;
185 float sum_sq = 0.0f;
186 for (int i = 3; i >= 0; --i) {
187 if (i == largest_index) {
188 continue;
189 }
190 const uint32_t mag = packed & COMPONENT_MASK;
191 const float sign = ((packed >> 9) & 0x1) == 1 ? -1.0f : 1.0f;
192 spz_rotation[i] = M_SQRT1_2 * ((float)mag) / float(COMPONENT_MASK) * sign;
193 sum_sq += spz_rotation[i] * spz_rotation[i];
194 packed = packed >> 10;
195 }
196 spz_rotation[largest_index] = sqrt(math::max(1.0f - sum_sq, 0.0f));
197 /* Convert to Blender's (w, x, y, z). */
198 rotation = math::Quaternion(
199 spz_rotation[3], spz_rotation[0], spz_rotation[1], spz_rotation[2]);
200 }
201 return true;
202 }
203
204 return false;
205}
206
207template<class ReaderType>
208[[nodiscard]] inline bool read_sh(ReaderType &reader, const Span<MutableSpan<float3>> sh)
209{
210 /* From documentation:
211 *
212 * The coefficients for a gaussian are organized such that the color channel is the inner
213 * (faster varying) axis, and the coefficient is the outer (slower varying) axis
214 * Each coefficient is represented as an 8-bit signed integer. Additional quantization can be
215 * performed to attain a higher compression ratio */
216
217 if (sh.is_empty()) {
218 return true;
219 }
220
221 const int64_t num_points = sh[0].size();
222 const int num_coefficients = sh.size();
223
224 Array<uint8_t> packed_coefficients(3 * num_coefficients);
225
226 for (int64_t i = 0; i < num_points; ++i) {
227 if (!reader.read_buffer(packed_coefficients)) {
228 return false;
229 }
230 for (int j = 0; j < num_coefficients; ++j) {
231 const float3 coefficients(packed_coefficients[3 * j + 0],
232 packed_coefficients[3 * j + 1],
233 packed_coefficients[3 * j + 2]);
234 sh[j][i] = (coefficients - 128.0f) / 128.0f;
235 }
236 }
237
238 return true;
239}
240
243 Span<MutableSpan<float3>> sh_attrs);
244
245} // namespace blender::io::spz
#define M_SQRT1_2
#define position
constexpr T sign(T) RET
float3x3 scale(float3x3 mat, float2 scale)
float inv_sigmoid(const float x)
bool read_single_position_as_fixed(ReaderType &reader, int3 &fixed)
bool read_sh(ReaderType &reader, const Span< MutableSpan< float3 > > sh)
bool read_positions(ReaderType &reader, const int fractional_bits, const MutableSpan< float3 > positions)
void convert_axis_to_blender(const MutableSpan< float3 > positions, const MutableSpan< math::Quaternion > rotations, const Span< MutableSpan< float3 > > sh_attrs)
bool read_colors(ReaderType &reader, const MutableSpan< float4 > radiance_base)
bool read_alphas(ReaderType &reader, const MutableSpan< float4 > radiance_base)
bool read_scales(ReaderType &reader, const MutableSpan< float3 > scales)
bool read_rotations(ReaderType &reader, const int version, const MutableSpan< math::Quaternion > rotations)
QuaternionBase< float > Quaternion
T dot(const QuaternionBase< T > &a, const QuaternionBase< T > &b)
T max(const T &a, const T &b)
BLI_assert(slot->slot_subtype.map==BMO_OP_SLOT_SUBTYPE_MAP_FLT)
__int64 int64_t
Definition BKE_text.h:90
VecBase< float, 4 > float4
unsigned int uint32_t
Definition BKE_text.h:81
VecBase< int32_t, 3 > int3
unsigned char uint8_t
Definition BKE_text.h:79
sqrt(x)+1/max(0
VecBase< float, 3 > float3
constexpr void unroll(Fn fn)
Definition BLI_unroll.hh:27
KERNEL_FEATURE_LIGHT_PASSES KERNEL_FEATURE_PATH_GUIDING float
static float decode_opacity(const float opacity)
Definition IO_gsplat.hh:114
static float3 decode_scale(const float3 scale)
Definition IO_gsplat.hh:118