Blender V5.3
ply_import.cc
Go to the documentation of this file.
1/* SPDX-FileCopyrightText: 2023 Blender Authors
2 *
3 * SPDX-License-Identifier: GPL-2.0-or-later */
4
8
9#include <array>
10#include <charconv>
11#include <string>
12#include <utility>
13
14#include "BKE_context.hh"
15#include "BKE_layer.hh"
16#include "BKE_lib_id.hh"
17#include "BKE_library.hh"
18#include "BKE_mesh.hh"
19#include "BKE_object.hh"
20#include "BKE_report.hh"
21
23#include "DNA_object_types.h"
24#include "DNA_scene_types.h"
25
26#include "BLI_math_matrix_c.hh"
28#include "BLI_memory_utils.hh"
29#include "BLI_set.hh"
30#include "BLI_span.hh"
31#include "BLI_string.hh"
32
33#include "DEG_depsgraph.hh"
35
36#include "ply_data.hh"
37#include "ply_import.hh"
38
39#include "BKE_pointcloud.hh"
40#include "ply_import_buffer.hh"
41#include "ply_import_data.hh"
42#include "ply_import_gsplat.hh"
43#include "ply_import_mesh.hh"
44
45#include "CLG_log.h"
46
47namespace blender {
48
49static CLG_LogRef LOG = {"io.ply"};
50
51namespace io::ply {
52
53/* If line starts with keyword, returns true and drops it from the line. */
54static bool parse_keyword(Span<char> &str, StringRef keyword)
55{
56 const size_t keyword_len = keyword.size();
57 if (str.size() < keyword_len) {
58 return false;
59 }
60 if (memcmp(str.data(), keyword.data(), keyword_len) != 0) {
61 return false;
62 }
63 str = str.drop_front(keyword_len);
64 return true;
65}
66
68{
69 size_t len = 0;
70 while (len < str.size() && str[len] > ' ') {
71 ++len;
72 }
73 Span<char> word(str.begin(), len);
74 str = str.drop_front(len);
75 return word;
76}
77
79{
80 while (!str.is_empty() && str[0] <= ' ') {
81 str = str.drop_front(1);
82 }
83}
84
86{
87 StringRef input(word.data(), word.size());
88 if (ELEM(input, "uchar", "uint8")) {
90 }
91 if (ELEM(input, "char", "int8")) {
92 return PlyDataTypes::CHAR;
93 }
94 if (ELEM(input, "ushort", "uint16")) {
96 }
97 if (ELEM(input, "short", "int16")) {
99 }
100 if (ELEM(input, "uint", "uint32")) {
101 return PlyDataTypes::UINT;
102 }
103 if (ELEM(input, "int", "int32")) {
104 return PlyDataTypes::INT;
105 }
106 if (ELEM(input, "float", "float32")) {
107 return PlyDataTypes::FLOAT;
108 }
109 if (ELEM(input, "double", "float64")) {
111 }
112 return PlyDataTypes::NONE;
113}
114
115const char *read_header(PlyReadBuffer &file, PlyHeader &r_header)
116{
117 Span<char> word, line;
118 line = file.read_line();
119 if (StringRef(line.data(), line.size()) != "ply") {
120 return "Invalid PLY header.";
121 }
122
123 while (true) { /* We break when end_header is encountered. */
124 line = file.read_line();
125
126 if (parse_keyword(line, "format")) {
127 skip_space(line);
128 if (parse_keyword(line, "ascii")) {
129 r_header.type = PlyFormatType::ASCII;
130 }
131 else if (parse_keyword(line, "binary_big_endian")) {
133 }
134 else if (parse_keyword(line, "binary_little_endian")) {
136 }
137 else {
138 return "Unknown format.";
139 }
140 }
141 else if (parse_keyword(line, "element")) {
143
144 skip_space(line);
145 word = parse_word(line);
146 element.name = std::string(word.data(), word.size());
147 skip_space(line);
148 word = parse_word(line);
149 const std::from_chars_result res = std::from_chars(word.begin(), word.end(), element.count);
150 if (res.ec != std::errc() || res.ptr != word.end() || element.count < 0) {
151 return "Invalid element count.";
152 }
153 r_header.elements.append(element);
154 }
155 else if (parse_keyword(line, "property")) {
156 if (r_header.elements.is_empty()) {
157 return "Property without element.";
158 }
159 PlyProperty property;
160 bool unknown_count_type = false;
161 skip_space(line);
162 if (parse_keyword(line, "list")) {
163 skip_space(line);
164 property.count_type = type_from_string(parse_word(line));
165 unknown_count_type = property.count_type == PlyDataTypes::NONE;
166 }
167 skip_space(line);
168 property.type = type_from_string(parse_word(line));
169 if (unknown_count_type) {
170 /* Still a list, but of unknown type. So it can't be read from binary files,
171 * like other unknown types, while ASCII files don't need the type. */
172 property.count_type = PlyDataTypes::UINT;
173 property.type = PlyDataTypes::NONE;
174 }
175 skip_space(line);
176 word = parse_word(line);
177 property.name = std::string(word.data(), word.size());
178 r_header.elements.last().properties.append(property);
179 }
180 else if (parse_keyword(line, "end_header")) {
181 break;
182 }
183 else if (line.is_empty() || (line.first() >= '0' && line.first() <= '9') ||
184 line.first() == '-')
185 {
186 /* A value was found before we broke out of the loop. No end_header. */
187 return "No end_header.";
188 }
189 }
190
191 file.after_header(r_header.type != PlyFormatType::ASCII);
192 for (PlyElement &el : r_header.elements) {
193 el.calc_stride();
194 }
195 return nullptr;
196}
197
198static void report_exception(const PLYImportParams &import_params,
199 const StringRefNull ob_name,
200 const std::exception &ex)
201{
202 /* Read buffer errors for malformed files, or allocation failure for huge counts. */
203 CLOG_ERROR(&LOG, "PLY Importer: %s: %s", ob_name.c_str(), ex.what());
205 import_params.reports, RPT_ERROR, "PLY Importer: %s: %s", ob_name.c_str(), ex.what());
206}
207
208static std::unique_ptr<PlyData> read_ply_to_data(const PLYImportParams &import_params,
209 const StringRefNull ob_name)
210{
211 try {
212 /* Parse header. */
213 PlyReadBuffer file(import_params.filepath, 64 * 1024);
214
215 PlyHeader header;
216 const char *err = read_header(file, header);
217 if (err != nullptr) {
218 CLOG_ERROR(&LOG, "PLY Importer: %s: %s", ob_name.c_str(), err);
219 BKE_reportf(import_params.reports, RPT_ERROR, "PLY Importer: %s: %s", ob_name.c_str(), err);
220 return nullptr;
221 }
222
223 /* Parse actual file data. */
224 std::unique_ptr<PlyData> data = import_ply_data(file, header);
225 if (data == nullptr) {
226 CLOG_ERROR(&LOG, "PLY Importer: failed importing %s, unknown error", ob_name.c_str());
228 import_params.reports, RPT_ERROR, "PLY Importer: failed importing, unknown error");
229 return nullptr;
230 }
231 if (!data->error.empty()) {
233 &LOG, "PLY Importer: failed importing %s: %s", ob_name.c_str(), data->error.c_str());
234 BKE_reportf(import_params.reports,
235 RPT_ERROR,
236 "PLY Importer: failed importing %s: %s",
237 ob_name.c_str(),
238 data->error.c_str());
239 return nullptr;
240 }
241 if (!data->warning.empty()) {
242 CLOG_WARN(&LOG, "PLY Importer: %s: %s", ob_name.c_str(), data->warning.c_str());
243 BKE_reportf(import_params.reports,
245 "PLY Importer: %s: %s",
246 ob_name.c_str(),
247 data->warning.c_str());
248 }
249 if (data->vertices.is_empty()) {
250 CLOG_ERROR(&LOG, "PLY Importer: file %s contains no vertices", ob_name.c_str());
251 BKE_report(import_params.reports, RPT_ERROR, "PLY Importer: failed importing, no vertices");
252 return nullptr;
253 }
254
255 return data;
256 }
257 catch (const std::exception &ex) {
258 report_exception(import_params, ob_name, ex);
259 return nullptr;
260 }
261}
262
264{
265 /* If PLY is not just vertices, it is not a gaussian splat.
266 *
267 * Ignore possible vertex normals, as some gaussian splats in the PLY format include vertex
268 * normals. For example, spz_to_ply writes vertex normals explaining that some applications
269 * require them to present (they are written as (0, 0, 0)).
270 */
271 if (!data.edges.is_empty() || !data.face_vertices.is_empty() || !data.face_sizes.is_empty() ||
272 !data.uv_coordinates.is_empty())
273 {
274 return false;
275 }
276
277 Set<std::string> attr_names;
278 for (const PlyCustomAttribute &attr : data.vertex_custom_attr) {
279 attr_names.add(attr.name);
280 }
281
282 constexpr auto required_attr_names = std::to_array<const char *>({"f_dc_0",
283 "f_dc_1",
284 "f_dc_2",
285 "opacity",
286 "scale_0",
287 "scale_1",
288 "scale_2",
289 "rot_0",
290 "rot_1",
291 "rot_2",
292 "rot_3"});
293 for (const char *required_attr_name : required_attr_names) {
294 if (!attr_names.contains(required_attr_name)) {
295 return false;
296 }
297 }
298
299 /* TODO(sergey): Check the f_rest_<i> attributes are consistent? */
300
301 return true;
302}
303
304/* File base name used for object and object-data. */
305static std::string get_datablock_name(const StringRefNull filepath)
306{
307 char datablock_name[FILE_MAX];
308 STRNCPY(datablock_name, BLI_path_basename(filepath.c_str()));
309 BLI_path_extension_strip(datablock_name);
310 return std::string(datablock_name);
311}
312
313Mesh *import_mesh(const PLYImportParams &import_params)
314{
315 const std::string datablock_name = get_datablock_name(import_params.filepath);
316 try {
317 std::unique_ptr<PlyData> data = read_ply_to_data(import_params, datablock_name);
318 if (!data) {
319 return nullptr;
320 }
321 return convert_ply_to_mesh(*data, import_params);
322 }
323 catch (const std::exception &ex) {
324 report_exception(import_params, datablock_name, ex);
325 return nullptr;
326 }
327}
328
330{
331 const std::string datablock_name = get_datablock_name(import_params.filepath);
332 try {
333 std::unique_ptr<PlyData> data = read_ply_to_data(import_params, datablock_name);
334 if (!data) {
335 return nullptr;
336 }
338 return nullptr;
339 }
340 return convert_gsplat_ply_to_point_cloud(*data, import_params);
341 }
342 catch (const std::exception &ex) {
343 report_exception(import_params, datablock_name, ex);
344 return nullptr;
345 }
346}
347
349{
350 const std::string datablock_name = get_datablock_name(import_params.filepath);
351 try {
352 std::unique_ptr<PlyData> data = read_ply_to_data(import_params, datablock_name);
353 if (!data) {
354 return bke::GeometrySet();
355 }
356
357 /* Free the geometry if an exception is thrown before the geometry set owns it. */
358 Mesh *mesh = nullptr;
359 PointCloud *point_cloud = nullptr;
360 BLI_SCOPED_DEFER([&]() {
361 if (mesh) {
362 BKE_id_free(nullptr, mesh);
363 }
364 if (point_cloud) {
365 BKE_id_free(nullptr, point_cloud);
366 }
367 });
368
370 point_cloud = convert_gsplat_ply_to_point_cloud(*data, import_params);
372 point_cloud = nullptr;
373 return geometry;
374 }
375 mesh = convert_ply_to_mesh(*data, import_params);
377 mesh = nullptr;
378 return geometry;
379 }
380 catch (const std::exception &ex) {
381 report_exception(import_params, datablock_name, ex);
382 return bke::GeometrySet();
383 }
384}
385
386void importer_main(bContext *C, const PLYImportParams &import_params)
387{
388 Main *bmain = CTX_data_main(C);
389 Scene *scene = CTX_data_scene(C);
390 ViewLayer *view_layer = CTX_data_view_layer(C);
391 importer_main(bmain, scene, view_layer, import_params);
392}
393
394static void importer_main_impl(Main *bmain,
395 Scene *scene,
396 ViewLayer *view_layer,
397 const PLYImportParams &import_params,
398 const std::string &datablock_name)
399{
400 std::unique_ptr<PlyData> data = read_ply_to_data(import_params, datablock_name);
401 if (!data) {
402 return;
403 }
404
405 ObjectType ob_type = OB_EMPTY;
406 ID *ob_data = nullptr;
407 Mesh *mesh = nullptr;
408 Mesh *mesh_in_main = nullptr;
409 PointCloud *point_cloud = nullptr;
410 /* Free the geometry if an exception like std::bad_alloc is thrown before moving it to Main. */
411 BLI_SCOPED_DEFER([&]() {
412 if (mesh) {
413 BKE_id_free(nullptr, mesh);
414 }
415 if (point_cloud) {
416 BKE_id_free(nullptr, point_cloud);
417 }
418 });
419
421 point_cloud = convert_gsplat_ply_to_point_cloud(*data, import_params);
422 if (!point_cloud) {
423 return;
424 }
425 PointCloud *point_cloud_in_main = BKE_pointcloud_add(bmain, datablock_name.c_str());
426 ob_type = OB_POINTCLOUD;
427 ob_data = id_cast<ID *>(point_cloud_in_main);
428 BKE_pointcloud_nomain_to_pointcloud(std::exchange(point_cloud, nullptr), point_cloud_in_main);
429 }
430 else {
431 mesh = convert_ply_to_mesh(*data, import_params);
432 if (!mesh) {
433 return;
434 }
435 ob_type = OB_MESH;
436 mesh_in_main = BKE_mesh_add(bmain, datablock_name.c_str());
437 ob_data = id_cast<ID *>(mesh_in_main);
438 /* Delay conversion of mesh to mesh_in_main until the object is known. */
439 }
440
441 BLI_assert(ob_data);
442 BLI_assert(ob_type != OB_EMPTY);
443
444 /* Create mesh and do all prep work. */
445 BKE_view_layer_base_deselect_all(*bmain, scene, view_layer);
447 if (!ID_IS_EDITABLE(lc->collection)) {
448 BKE_report(import_params.reports,
450 "Could not find an editable collection in current scene, imported data will not be "
451 "instantiated");
452 }
453 Object *obj = BKE_object_add_only_object(bmain, ob_type, datablock_name.c_str());
454 obj->data = ob_data;
456 BKE_view_layer_synced_ensure(*bmain, scene, view_layer);
457 if (Base *base = BKE_view_layer_base_find(view_layer, obj)) {
458 /* `base` will be nullptr if the Object could not be instantiated in the current viewlayer. */
460 }
461
462 if (ob_type == OB_MESH) {
464 BLI_assert(mesh_in_main);
465 BKE_mesh_nomain_to_mesh(std::exchange(mesh, nullptr), mesh_in_main, obj);
466 }
467
468 /* Object matrix and finishing up. */
469 float global_scale = import_params.global_scale;
470 if ((scene->unit.system != USER_UNIT_NONE) && import_params.use_scene_unit) {
471 global_scale /= scene->unit.scale_length;
472 }
473 float scale_vec[3] = {global_scale, global_scale, global_scale};
474 float obmat3x3[3][3];
475 unit_m3(obmat3x3);
476 float obmat4x4[4][4];
477 unit_m4(obmat4x4);
478 /* +Y-forward and +Z-up are the Blender's default axis settings. */
480 IO_AXIS_Y, IO_AXIS_Z, import_params.forward_axis, import_params.up_axis, obmat3x3);
481 copy_m4_m3(obmat4x4, obmat3x3);
482 rescale_m4(obmat4x4, scale_vec);
483 /* Note that this applies rot/scale on the object level, it does not affect the geometry.
484 * Meaning, it works correctly for both meshes and gaussian splats without anything else needed
485 * to transform the spherical harmonics. */
486 BKE_object_apply_mat4(obj, obmat4x4, true, false);
487
491 DEG_id_tag_update_ex(bmain, &obj->id, flags);
494}
495
496void importer_main(Main *bmain,
497 Scene *scene,
498 ViewLayer *view_layer,
499 const PLYImportParams &import_params)
500{
501 const std::string datablock_name = get_datablock_name(import_params.filepath);
502 try {
503 importer_main_impl(bmain, scene, view_layer, import_params, datablock_name);
504 }
505 catch (const std::exception &ex) {
506 report_exception(import_params, datablock_name, ex);
507 }
508}
509
510} // namespace io::ply
511} // namespace blender
General operations, lookup, etc. for blender objects.
General operations for point clouds.
#define BLI_SCOPED_DEFER(function_to_defer)
#define FILE_MAX
#define CLOG_ERROR(clg_ref,...)
Definition CLG_log.h:188
#define CLOG_WARN(clg_ref,...)
Definition CLG_log.h:189
#define ID_IS_EDITABLE(_id)
Definition DNA_ID.h:708
Object groups, one object can be in many groups at once.
Object is a sort of wrapper for general info.
#define C
Definition RandGen.cpp:29
#define ELEM(...)
bool contains(const Key &key) const
Definition BLI_set.hh:310
bool add(const Key &key)
Definition BLI_set.hh:248
constexpr const T * data() const
Definition BLI_span.hh:219
constexpr const T & first() const
Definition BLI_span.hh:319
constexpr int64_t size() const
Definition BLI_span.hh:256
constexpr const T * end() const
Definition BLI_span.hh:228
constexpr const T * begin() const
Definition BLI_span.hh:224
constexpr bool is_empty() const
Definition BLI_span.hh:264
constexpr const char * c_str() const
constexpr StringRef()
constexpr int64_t size() const
constexpr const char * data() const
#define str(s)
ccl_device_inline dual1 len(const ccl_private dual< T > &a)
Definition math_dual.h:263
static PlyDataTypes type_from_string(Span< char > word)
Definition ply_import.cc:85
static void skip_space(Span< char > &str)
Definition ply_import.cc:78
void importer_main(bContext *C, const PLYImportParams &import_params)
static std::string get_datablock_name(const StringRefNull filepath)
PointCloud * import_point_cloud(const PLYImportParams &import_params)
std::unique_ptr< PlyData > import_ply_data(PlyReadBuffer &file, PlyHeader &header)
static bool is_data_gaussian_splat(const PlyData &data)
static Span< char > parse_word(Span< char > &str)
Definition ply_import.cc:67
static bool parse_keyword(Span< char > &str, StringRef keyword)
Definition ply_import.cc:54
static std::unique_ptr< PlyData > read_ply_to_data(const PLYImportParams &import_params, const StringRefNull ob_name)
static void importer_main_impl(Main *bmain, Scene *scene, ViewLayer *view_layer, const PLYImportParams &import_params, const std::string &datablock_name)
Mesh * convert_ply_to_mesh(PlyData &data, const PLYImportParams &params)
const char * read_header(PlyReadBuffer &file, PlyHeader &r_header)
Mesh * import_mesh(const PLYImportParams &import_params)
bke::GeometrySet import_geometry_set(const PLYImportParams &import_params)
static void report_exception(const PLYImportParams &import_params, const StringRefNull ob_name, const std::exception &ex)
PointCloud * convert_gsplat_ply_to_point_cloud(const PlyData &data, const PLYImportParams &params)
BMesh Iterators.
bool bool BLI_path_extension_strip(char *path) ATTR_NONNULL(1)
BLI_assert(slot->slot_subtype.map==BMO_OP_SLOT_SUBTYPE_MAP_FLT)
char * STRNCPY(char(&dst)[N], const char *src)
LayerCollection * BKE_layer_collection_get_active_editable(ViewLayer *view_layer)
void BKE_view_layer_base_select_and_set_active(ViewLayer *view_layer, Base *selbase)
@ RPT_WARNING
Definition BKE_report.hh:40
void BKE_pointcloud_nomain_to_pointcloud(PointCloud *pointcloud_src, PointCloud *pointcloud_dst)
void copy_m4_m3(float m1[4][4], const float m2[3][3])
void BKE_mesh_nomain_to_mesh(Mesh *mesh_src, Mesh *mesh_dst, Object *ob, bool process_shape_keys=true)
ViewLayer * CTX_data_view_layer(const bContext *C)
void BKE_object_apply_mat4(Object *ob, const float mat[4][4], bool use_compat, bool use_parent)
Definition object.cc:3663
void void void const char * BLI_path_basename(const char *path) ATTR_NONNULL(1) ATTR_WARN_UNUSED_RESULT
void DEG_id_tag_update_ex(Main *bmain, ID *id, unsigned int flags)
void DEG_id_tag_update(ID *id, unsigned int flags)
void BKE_report(ReportList *reports, eReportType type, const char *message)
Definition report.cc:162
BMesh const char void * data
PointCloud * BKE_pointcloud_add(Main *bmain, const char *name)
bool mat3_from_axis_conversion(int src_forward, int src_up, int dst_forward, int dst_up, float r_mat[3][3])
bool BKE_view_layer_synced_ensure(const Main &bmain, const Scene *scene, ViewLayer *view_layer)
bool BKE_collection_object_add(Main *bmain, Collection *collection, Object *ob)
void unit_m4(float m[4][4])
void BKE_id_free(Main *bmain, void *idv)
void BKE_view_layer_base_deselect_all(const Main &bmain, const Scene *scene, ViewLayer *view_layer)
void BKE_reportf(ReportList *reports, eReportType type, const char *format,...) ATTR_PRINTF_FORMAT(3
Definition report.cc:191
Main * CTX_data_main(const bContext *C)
void unit_m3(float m[3][3])
@ ID_RECALC_ANIMATION
Definition DNA_ID.h:1077
@ ID_RECALC_TRANSFORM
Definition DNA_ID.h:1054
@ ID_RECALC_SYNC_TO_EVAL
Definition DNA_ID.h:1118
@ ID_RECALC_GEOMETRY
Definition DNA_ID.h:1074
@ ID_RECALC_BASE_FLAGS
Definition DNA_ID.h:1104
Base * BKE_view_layer_base_find(ViewLayer *view_layer, Object *ob)
void rescale_m4(float mat[4][4], const float scale[3])
static CLG_LogRef LOG
Definition logging.cpp:12
void DEG_relations_tag_update(Main *bmain)
Scene * CTX_data_scene(const bContext *C)
Object * BKE_object_add_only_object(Main *bmain, ObjectType type, const char *name) ATTR_RETURNS_NONNULL
Definition object.cc:2265
Mesh * BKE_mesh_add(Main *bmain, const char *name)
ATTR_WARN_UNUSED_RESULT const void * element
struct Collection * collection
ReportList * reports
Definition IO_ply.hh:76
char filepath[FILE_MAX]
Definition IO_ply.hh:67
struct UnitSettings unit
static GeometrySet from_mesh(Mesh *mesh, GeometryOwnershipType ownership=GeometryOwnershipType::Owned)
static GeometrySet from_pointcloud(PointCloud *pointcloud, GeometryOwnershipType ownership=GeometryOwnershipType::Owned)
Vector< PlyElement > elements
Definition ply_data.hh:61