Blender V5.3
ply_import_gsplat.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
8
10
11#include "BLI_memory_utils.hh"
12#include "BLI_string_ref.hh"
13#include "BLI_vector.hh"
14
15#include "BKE_lib_id.hh"
16#include "BKE_pointcloud.hh"
17#include "BKE_report.hh"
18
19#include "IO_gsplat.hh"
20#include "IO_validate.hh"
21
22namespace blender::io::ply {
23
24static std::optional<Span<float>> find_custom_attribute(const PlyData &data,
25 const StringRefNull name)
26{
27 for (const PlyCustomAttribute &attr : data.vertex_custom_attr) {
28 if (attr.name == name) {
29 return attr.data;
30 }
31 }
32 return std::nullopt;
33}
34
35/* Spherical harmonics up to degree 4 are supported, matching SH_MAX_DEGREE of the SPZ library.
36 * This corresponds to 24 coefficients per channel, or 72 f_rest_<i> properties. */
37constexpr int MAX_SH_DEGREE = 4;
38constexpr int MAX_REST_ATTRIBUTES = 24 * 3;
39
40/* Get f_rest_<i> attributes from the PLY data.
41 * The result is indexed by <i>. */
43{
45 for (int i = 0; i < MAX_REST_ATTRIBUTES; i++) {
46 std::optional<Span<float>> attr = find_custom_attribute(data, "f_rest_" + std::to_string(i));
47 if (!attr.has_value()) {
48 break;
49 }
50 result.append(*attr);
51 }
52 return result;
53}
54
56{
57 if (name == "f_dc_0" || name == "f_dc_1" || name == "f_dc_2") {
58 return true;
59 }
60
61 if (name == "opacity") {
62 return true;
63 }
64
65 if (name == "scale_0" || name == "scale_1" || name == "scale_2") {
66 return true;
67 }
68
69 if (name == "rot_0" || name == "rot_1" || name == "rot_2" || name == "rot_3") {
70 return true;
71 }
72
73 if (name.startswith("f_rest_")) {
74 return true;
75 }
76
77 return false;
78}
79
81{
82 if (!validate::size_fits_in_int(data.vertices.size())) {
84 }
85
86 /* Radiance base attributes in the PLY (r, g, b stored as a DC component of SH), and opacity.
87 * Despite the name it seems to be alpha (at least according to the conversion in SPZ. */
88 const std::optional<Span<float>> ply_f_dc_0_attr = find_custom_attribute(data, "f_dc_0");
89 const std::optional<Span<float>> ply_f_dc_1_attr = find_custom_attribute(data, "f_dc_1");
90 const std::optional<Span<float>> ply_f_dc_2_attr = find_custom_attribute(data, "f_dc_2");
91 if (!ply_f_dc_0_attr || !ply_f_dc_1_attr || !ply_f_dc_2_attr) {
92 return nullptr;
93 }
94 Span<float> ply_f_dc[3] = {*ply_f_dc_0_attr, *ply_f_dc_1_attr, *ply_f_dc_2_attr};
95
96 const std::optional<Span<float>> ply_opacity_attr = find_custom_attribute(data, "opacity");
97 if (!ply_opacity_attr) {
98 return nullptr;
99 }
100 Span<float> ply_opacity = *ply_opacity_attr;
101
102 /* Scale. */
103 const std::optional<Span<float>> ply_scale_0_attr = find_custom_attribute(data, "scale_0");
104 const std::optional<Span<float>> ply_scale_1_attr = find_custom_attribute(data, "scale_1");
105 const std::optional<Span<float>> ply_scale_2_attr = find_custom_attribute(data, "scale_2");
106 if (!ply_scale_0_attr || !ply_scale_1_attr || !ply_scale_2_attr) {
107 return nullptr;
108 }
109 const Span<float> ply_scale[3] = {*ply_scale_0_attr, *ply_scale_1_attr, *ply_scale_2_attr};
110
111 /* Rotation (w, x, y, z). */
112 const std::optional<Span<float>> ply_rot_0_attr = find_custom_attribute(data, "rot_0");
113 const std::optional<Span<float>> ply_rot_1_attr = find_custom_attribute(data, "rot_1");
114 const std::optional<Span<float>> ply_rot_2_attr = find_custom_attribute(data, "rot_2");
115 const std::optional<Span<float>> ply_rot_3_attr = find_custom_attribute(data, "rot_3");
116 if (!ply_rot_0_attr || !ply_rot_1_attr || !ply_rot_2_attr || !ply_rot_3_attr) {
117 return nullptr;
118 }
119 Span<float> ply_rot[4] = {*ply_rot_0_attr, *ply_rot_1_attr, *ply_rot_2_attr, *ply_rot_3_attr};
120
122 data.vertices.size());
123 /* Free the new point cloud if an exception like std::bad_alloc is thrown. */
124 bool success = false;
125 BLI_SCOPED_DEFER([&]() {
126 if (!success) {
127 BKE_id_free(nullptr, point_cloud);
128 }
129 });
130
131 point_cloud->positions_for_write().copy_from(data.vertices);
132
133 /* f_rest_<i>
134 *
135 * The f_rest layout is channel-major: all per-channel coefficients of R first, then all of G,
136 * then all of B. The offset between channels is therefore the file's own per-channel count,
137 * independent of how many of those coefficients end up imported. */
139 int num_file_coefficients = int(f_rest.size() / 3);
140 int sh_degree = 0;
141
142 if (f_rest.size() == MAX_REST_ATTRIBUTES &&
143 find_custom_attribute(data, "f_rest_" + std::to_string(MAX_REST_ATTRIBUTES)))
144 {
145 /* More coefficients than the maximum supported degree: the channel offsets of such a file do
146 * not line up with any supported layout, so no coefficients can be imported. */
147 BKE_reportf(params.reports,
149 "PLY Importer: Spherical harmonics degree above the supported %d, spherical "
150 "harmonics are not imported",
152 num_file_coefficients = 0;
153 }
154 else if (f_rest.size() % 3 != 0) {
155 BKE_reportf(params.reports,
157 "PLY Importer: Unexpected number of f_rest properties %d, spherical harmonics "
158 "are not imported",
159 int(f_rest.size()));
160 num_file_coefficients = 0;
161 }
162 else {
163 sh_degree = gsplat::degree_for_dimension(num_file_coefficients);
164 if (gsplat::dimension_for_degree(sh_degree) != num_file_coefficients) {
165 BKE_reportf(params.reports,
167 "PLY Importer: Incomplete spherical harmonics band, importing %d of %d "
168 "coefficients",
170 num_file_coefficients);
171 }
172 }
173
174 const int num_sh_dimensions = gsplat::dimension_for_degree(sh_degree);
175
176 gsplat::GsplatMutableAttributeAccessor accessor(*point_cloud, sh_degree);
177 MutableSpan<float4> radiance_base = accessor.radiance_base_for_write();
180 Span<MutableSpan<float3>> sh_attrs = accessor.sh_for_write();
181
182 for (int i = 0; i < data.vertices.size(); i++) {
183 radiance_base[i] = float4(ply_f_dc[0][i], ply_f_dc[1][i], ply_f_dc[2][i], ply_opacity[i]);
184 scale[i] = float3(ply_scale[0][i], ply_scale[1][i], ply_scale[2][i]);
185 rotation[i] = math::normalize(
186 math::Quaternion(ply_rot[0][i], ply_rot[1][i], ply_rot[2][i], ply_rot[3][i]));
187
188 radiance_base[i].w = gsplat::OriginalActivationFunctions::decode_opacity(radiance_base[i].w);
190
191 for (int dimension = 0; dimension < num_sh_dimensions; dimension++) {
192 sh_attrs[dimension][i] = float3(f_rest[dimension][i],
193 f_rest[dimension + num_file_coefficients][i],
194 f_rest[dimension + 2 * num_file_coefficients][i]);
195 }
196 }
197
198 /* TODO(sergey): Handle coordinate system conversion denoted in the params. */
199 /* For "regular" import (via UI, using File -> Import or by dropping PLY file onto the viewport)
200 * this is handled via object matrix in `importer_main()`. However, some code paths might use
201 * this code directly: for example, geometry nodes. Currently geometry nodes do not provide axis
202 * control for import nodes, so handling coordinate system conversion here is not required. */
203
204 accessor.finish();
205
206 if (params.import_attributes) {
207 bke::MutableAttributeAccessor attributes = point_cloud->attributes_for_write();
208 for (const PlyCustomAttribute &attr : data.vertex_custom_attr) {
210 continue;
211 }
212 attributes.add<float>(attr.name,
215 }
216 }
217
218 success = true;
219 return point_cloud;
220}
221
222} // namespace blender::io::ply
General operations for point clouds.
#define BLI_SCOPED_DEFER(function_to_defer)
SIMD_FORCE_INLINE const btScalar & w() const
Return the w value.
Definition btQuadWord.h:119
static VArray from_span(Span< T > values)
int64_t size() const
bool add(const StringRef name, const AttrDomain domain, const AttrType data_type, const AttributeInit &initializer)
constexpr bool startswith(StringRef prefix) const
MutableSpan< math::Quaternion > rotations_for_write()
Definition gsplat.cc:48
Span< MutableSpan< float3 > > sh_for_write()
Definition gsplat.cc:53
float3x3 scale(float3x3 mat, float2 scale)
int degree_for_dimension(const int dimension)
Definition IO_gsplat.hh:44
int dimension_for_degree(const int degree)
Definition IO_gsplat.hh:61
static Vector< Span< float > > get_rest_custom_attributes(const PlyData &data)
constexpr int MAX_REST_ATTRIBUTES
static std::optional< Span< float > > find_custom_attribute(const PlyData &data, const StringRefNull name)
static bool is_builtin_gsplat_attribute(StringRefNull name)
PointCloud * convert_gsplat_ply_to_point_cloud(const PlyData &data, const PLYImportParams &params)
constexpr int MAX_SH_DEGREE
bool size_fits_in_int(const int64_t size)
QuaternionBase< float > Quaternion
MatBase< T, NumCol, NumRow > normalize(const MatBase< T, NumCol, NumRow > &a)
@ RPT_WARNING
Definition BKE_report.hh:40
VecBase< float, 4 > float4
BMesh const char void * data
void BKE_id_free(Main *bmain, void *idv)
void BKE_reportf(ReportList *reports, eReportType type, const char *format,...) ATTR_PRINTF_FORMAT(3
Definition report.cc:191
PointCloud * BKE_pointcloud_new_nomain(PointCloudType type, int totpoint)
VecBase< float, 3 > float3
ReportList * reports
Definition IO_ply.hh:76
static float decode_opacity(const float opacity)
Definition IO_gsplat.hh:114
static float3 decode_scale(const float3 scale)
Definition IO_gsplat.hh:118