Coverage for trimesh/exchange/ply.py: 92%

434 statements  

« prev     ^ index     » next       coverage.py v7.17.0, created at 2026-11-12 17:18 +0000

1import collections 

2import subprocess 

3import tempfile 

4from string import Template 

5 

6import numpy as np 

7from numpy.lib.recfunctions import structured_to_unstructured, unstructured_to_structured 

8 

9from .. import grouping, resources, util, visual 

10from ..constants import log 

11from ..geometry import triangulate_quads 

12from ..resolvers import Resolver 

13from ..typed import ArrayLike 

14 

15# from ply specification, and additional dtypes found in the wild 

16_dtypes = { 

17 "char": "i1", 

18 "uchar": "u1", 

19 "short": "i2", 

20 "ushort": "u2", 

21 "int": "i4", 

22 "int8": "i1", 

23 "int16": "i2", 

24 "int32": "i4", 

25 "int64": "i8", 

26 "uint": "u4", 

27 "uint8": "u1", 

28 "uint16": "u2", 

29 "uint32": "u4", 

30 "uint64": "u8", 

31 "float": "f4", 

32 "float16": "f2", 

33 "float32": "f4", 

34 "float64": "f8", 

35 "double": "f8", 

36} 

37 

38# Inverse of the above dict, collisions on numpy type were removed 

39_inverse_dtypes = { 

40 "i1": "char", 

41 "u1": "uchar", 

42 "i2": "short", 

43 "u2": "ushort", 

44 "i4": "int", 

45 "i8": "int64", 

46 "u4": "uint", 

47 "u8": "uint64", 

48 "f4": "float", 

49 "f2": "float16", 

50 "f8": "double", 

51} 

52 

53 

54def _numpy_type_to_ply_type(_numpy_type): 

55 """ 

56 Returns the closest ply equivalent of a numpy type 

57 

58 Parameters 

59 --------- 

60 _numpy_type : a numpy datatype 

61 

62 Returns 

63 --------- 

64 ply_type : string 

65 """ 

66 return _inverse_dtypes[_numpy_type.str[1:]] 

67 

68 

69def load_ply( 

70 file_obj, 

71 resolver: Resolver | None = None, 

72 fix_texture: bool = True, 

73 prefer_color: str | None = None, 

74 skip_materials: bool = False, 

75 *args, 

76 **kwargs, 

77): 

78 """ 

79 Load a PLY file from an open file object. 

80 

81 Parameters 

82 --------- 

83 file_obj : an open file- like object 

84 Source data, ASCII or binary PLY 

85 resolver 

86 Object which can resolve assets 

87 fix_texture 

88 If True, will re- index vertices and faces 

89 so vertices with different UV coordinates 

90 are disconnected. 

91 skip_materials 

92 If True, will not load texture (if present). 

93 prefer_color 

94 None, 'vertex', or 'face' 

95 Which kind of color to prefer if both defined 

96 

97 Returns 

98 --------- 

99 mesh_kwargs : dict 

100 Data which can be passed to 

101 Trimesh constructor, eg: a = Trimesh(**mesh_kwargs) 

102 """ 

103 

104 # OrderedDict which is populated from the header 

105 elements, is_ascii, image_name = _parse_header(file_obj) 

106 

107 # functions will fill in elements from file_obj 

108 if is_ascii: 

109 _ply_ascii(elements, file_obj) 

110 else: 

111 _ply_binary(elements, file_obj) 

112 

113 # try to load the referenced image 

114 image = None 

115 if not skip_materials: 

116 try: 

117 # soft dependency 

118 import PIL.Image 

119 

120 # if an image name is passed try to load it 

121 if image_name is not None: 

122 data = resolver.get(image_name) 

123 image = PIL.Image.open(util.wrap_as_stream(data)) 

124 except ImportError: 

125 log.debug("textures require `pip install pillow`") 

126 except BaseException: 

127 log.warning("unable to load image!", exc_info=True) 

128 

129 # translate loaded PLY elements to kwargs 

130 kwargs = _elements_to_kwargs( 

131 image=image, elements=elements, fix_texture=fix_texture, prefer_color=prefer_color 

132 ) 

133 

134 return kwargs 

135 

136 

137def _add_attributes_to_dtype(dtype, attributes): 

138 """ 

139 Parses attribute datatype to populate a numpy dtype list 

140 

141 Parameters 

142 ---------- 

143 dtype : list of numpy datatypes 

144 operated on in place 

145 attributes : dict 

146 contains all the attributes to parse 

147 

148 Returns 

149 ---------- 

150 dtype : list of numpy datatypes 

151 """ 

152 for name, data in attributes.items(): 

153 # force little-endian to match PLY binary format 

154 field_dtype = data.dtype.newbyteorder("<") 

155 if data.ndim > 1: 

156 dtype.extend([(f"{name}_count", "<u1"), (name, field_dtype, data.shape[1])]) 

157 else: 

158 dtype.append((name, field_dtype)) 

159 return dtype 

160 

161 

162def _add_attributes_to_header(header, attributes): 

163 """ 

164 Parses attributes in to ply header entries 

165 

166 Parameters 

167 ---------- 

168 header : list of ply header entries 

169 operated on in place 

170 attributes : dict 

171 contains all the attributes to parse 

172 

173 Returns 

174 ---------- 

175 header : list 

176 Contains ply header entries 

177 """ 

178 for name, data in attributes.items(): 

179 if data.ndim == 1: 

180 header.append(f"property {_numpy_type_to_ply_type(data.dtype)} {name}\n") 

181 else: 

182 header.append( 

183 f"property list uchar {_numpy_type_to_ply_type(data.dtype)} {name}\n" 

184 ) 

185 return header 

186 

187 

188def _add_attributes_to_data_array(data_array, attributes): 

189 """ 

190 Parses attribute data in to a custom array, assumes datatype has been defined 

191 appropriately 

192 

193 Parameters 

194 ---------- 

195 data_array : numpy array with custom datatype 

196 datatype reflects all the data to be stored for a given ply element 

197 attributes : dict 

198 contains all the attributes to parse 

199 

200 Returns 

201 ---------- 

202 data_array : numpy array with custom datatype 

203 """ 

204 for name, data in attributes.items(): 

205 if data.ndim > 1: 

206 data_array[f"{name}_count"] = data.shape[1] * np.ones(data.shape[0]) 

207 data_array[name] = data 

208 return data_array 

209 

210 

211def _assert_attributes_valid(attributes): 

212 """ 

213 Asserts that a set of attributes is valid for PLY export. 

214 

215 Parameters 

216 ---------- 

217 attributes : dict 

218 Contains the attributes to validate 

219 

220 Raises 

221 -------- 

222 ValueError 

223 If passed attributes aren't valid. 

224 """ 

225 for data in attributes.values(): 

226 if data.ndim not in [1, 2]: 

227 raise ValueError("PLY attributes are limited to 1 or 2 dimensions") 

228 # Inelegant test for structured arrays, reference: 

229 # https://numpy.org/doc/stable/user/basics.rec.html 

230 if data.dtype.names is not None: 

231 raise ValueError("PLY attributes must be of a single datatype") 

232 

233 

234def export_ply( 

235 mesh, 

236 encoding="binary", 

237 vertex_normal: bool | None = None, 

238 include_attributes: bool = True, 

239): 

240 """ 

241 Export a mesh in the PLY format. 

242 

243 Parameters 

244 ---------- 

245 mesh : trimesh.Trimesh 

246 Mesh to export. 

247 encoding : str 

248 PLY encoding: 'ascii' or 'binary_little_endian' 

249 vertex_normal : None or include vertex normals 

250 

251 Returns 

252 ---------- 

253 export : bytes of result 

254 """ 

255 # evaluate input args 

256 # allow a shortcut for binary 

257 if encoding == "binary": 

258 encoding = "binary_little_endian" 

259 elif encoding not in ["binary_little_endian", "ascii"]: 

260 raise ValueError("encoding must be binary or ascii") 

261 # if vertex normals aren't specifically asked for 

262 # only export them if they are stored in cache 

263 if vertex_normal is None: 

264 vertex_normal = "vertex_normals" in mesh._cache 

265 

266 # if we want to include mesh attributes in the export 

267 if include_attributes: 

268 if hasattr(mesh, "vertex_attributes"): 

269 vertex_attributes = mesh.vertex_attributes.copy() 

270 # make sure to export texture coordinates as well 

271 if ( 

272 hasattr(mesh, "visual") 

273 and hasattr(mesh.visual, "uv") 

274 and np.shape(mesh.visual.uv) == (len(mesh.vertices), 2) 

275 ): 

276 vertex_attributes["s"] = mesh.visual.uv[:, 0] 

277 vertex_attributes["t"] = mesh.visual.uv[:, 1] 

278 _assert_attributes_valid(vertex_attributes) 

279 if hasattr(mesh, "face_attributes"): 

280 _assert_attributes_valid(mesh.face_attributes) 

281 

282 # custom numpy dtypes for exporting 

283 dtype_face = [("count", "<u1"), ("index", "<i4", (3))] 

284 dtype_vertex = [("vertex", "<f4", (3))] 

285 # will be appended to main dtype if needed 

286 dtype_vertex_normal = ("normals", "<f4", (3)) 

287 dtype_color = ("rgba", "<u1", (4)) 

288 # for Path objects. 

289 dtype_edge = [("index", "<i4", (2))] 

290 

291 # get template strings in dict 

292 templates = resources.get_json("templates/ply.json") 

293 # start collecting elements into a string for the header 

294 header = [templates["intro"]] 

295 header_params = {"encoding": encoding} 

296 

297 # structured arrays for exports 

298 pack_edges: ArrayLike | None = None 

299 pack_vertex: ArrayLike | None = None 

300 pack_faces: ArrayLike | None = None 

301 

302 # check if scene has geometry 

303 # check if this is a `trimesh.path.Path` object. 

304 if hasattr(mesh, "entities"): 

305 if len(mesh.vertices) and mesh.vertices.shape[-1] != 3: 

306 raise ValueError("only Path3D export is supported for ply") 

307 

308 if len(mesh.vertices) > 0: 

309 # run the discrete curve step for each entity 

310 discrete = [e.discrete(mesh.vertices) for e in mesh.entities] 

311 

312 # how long was each discrete curve 

313 discrete_len = np.array([d.shape[0] for d in discrete]) 

314 # what's the index offset based on these lengths 

315 discrete_off = np.concatenate(([0], np.cumsum(discrete_len)[:-1])) 

316 

317 # pre-stack edges we can slice and offset 

318 longest = discrete_len.max() 

319 stack = np.column_stack((np.arange(0, longest - 1), np.arange(1, longest))) 

320 

321 # get the indexes that reconstruct the discrete curves when stacked 

322 edges = np.vstack( 

323 [ 

324 stack[:length] + offset 

325 for length, offset in zip(discrete_len - 1, discrete_off) 

326 ] 

327 ) 

328 

329 vertices = np.vstack(discrete) 

330 # create and populate the custom dtype for vertices 

331 num_vertices = len(vertices) 

332 # put mesh edge data into custom dtype to export 

333 num_edges = len(edges) 

334 

335 if num_edges > 0 and num_vertices > 0: 

336 header.append(templates["vertex"]) 

337 pack_vertex = np.zeros(num_vertices, dtype=dtype_vertex) 

338 pack_vertex["vertex"] = np.asarray(vertices, dtype=np.float32) 

339 

340 # add the edge info to the header 

341 header.append(templates["edge"]) 

342 # pack edges into our dtype 

343 pack_edges = unstructured_to_structured(edges, dtype=dtype_edge) 

344 

345 # add the values for the header 

346 header_params.update( 

347 {"edge_count": num_edges, "vertex_count": num_vertices} 

348 ) 

349 

350 elif hasattr(mesh, "vertices"): 

351 header.append(templates["vertex"]) 

352 

353 num_vertices = len(mesh.vertices) 

354 header_params["vertex_count"] = num_vertices 

355 # if we're exporting vertex normals add them 

356 # to the header and dtype 

357 if vertex_normal: 

358 header.append(templates["vertex_normal"]) 

359 dtype_vertex.append(dtype_vertex_normal) 

360 

361 # if mesh has a vertex color add it to the header 

362 vertex_color = ( 

363 hasattr(mesh, "visual") 

364 and mesh.visual.kind == "vertex" 

365 and len(mesh.visual.vertex_colors) == len(mesh.vertices) 

366 ) 

367 if vertex_color: 

368 header.append(templates["color"]) 

369 dtype_vertex.append(dtype_color) 

370 

371 if include_attributes: 

372 if hasattr(mesh, "vertex_attributes"): 

373 vertex_count = len(mesh.vertices) 

374 vertex_attributes = { 

375 k: v 

376 for k, v in vertex_attributes.items() 

377 if hasattr(v, "__len__") and len(v) == vertex_count 

378 } 

379 _add_attributes_to_header(header, vertex_attributes) 

380 _add_attributes_to_dtype(dtype_vertex, vertex_attributes) 

381 else: 

382 vertex_attributes = None 

383 

384 # create and populate the custom dtype for vertices 

385 pack_vertex = np.zeros(num_vertices, dtype=dtype_vertex) 

386 pack_vertex["vertex"] = mesh.vertices 

387 if vertex_normal: 

388 pack_vertex["normals"] = mesh.vertex_normals 

389 if vertex_color: 

390 pack_vertex["rgba"] = mesh.visual.vertex_colors 

391 

392 if include_attributes and vertex_attributes is not None: 

393 _add_attributes_to_data_array(pack_vertex, vertex_attributes) 

394 

395 if hasattr(mesh, "faces"): 

396 header.append(templates["face"]) 

397 if mesh.visual.kind == "face": 

398 header.append(templates["color"]) 

399 dtype_face.append(dtype_color) 

400 

401 if include_attributes and hasattr(mesh, "face_attributes"): 

402 _add_attributes_to_header(header, mesh.face_attributes) 

403 _add_attributes_to_dtype(dtype_face, mesh.face_attributes) 

404 

405 # put mesh face data into custom dtype to export 

406 pack_faces = np.zeros(len(mesh.faces), dtype=dtype_face) 

407 pack_faces["count"] = 3 

408 pack_faces["index"] = mesh.faces 

409 if mesh.visual.kind == "face": 

410 pack_faces["rgba"] = mesh.visual.face_colors 

411 header_params["face_count"] = len(mesh.faces) 

412 

413 if include_attributes and hasattr(mesh, "face_attributes"): 

414 _add_attributes_to_data_array(pack_faces, mesh.face_attributes) 

415 

416 header.append(templates["outro"]) 

417 export = [Template("".join(header)).substitute(header_params).encode("utf-8")] 

418 

419 if encoding == "binary_little_endian": 

420 if pack_vertex is not None: 

421 export.append(pack_vertex.tobytes()) 

422 if pack_faces is not None: 

423 export.append(pack_faces.tobytes()) 

424 if pack_edges is not None: 

425 export.append(pack_edges.tobytes()) 

426 elif encoding == "ascii": 

427 if pack_vertex is not None: 

428 export.append( 

429 util.structured_array_to_string( 

430 pack_vertex, col_delim=" ", row_delim="\n" 

431 ).encode("utf-8"), 

432 ) 

433 

434 if pack_faces is not None: 

435 export.extend( 

436 [ 

437 b"\n", 

438 util.structured_array_to_string( 

439 pack_faces, col_delim=" ", row_delim="\n" 

440 ).encode("utf-8"), 

441 ] 

442 ) 

443 

444 if pack_edges is not None: 

445 export.extend( 

446 [ 

447 b"\n", 

448 util.structured_array_to_string( 

449 pack_edges, col_delim=" ", row_delim="\n" 

450 ).encode("utf-8"), 

451 ] 

452 ) 

453 export.append(b"\n") 

454 

455 else: 

456 raise ValueError("encoding must be ascii or binary!") 

457 

458 return b"".join(export) 

459 

460 

461def _parse_header(file_obj): 

462 """ 

463 Read the ASCII header of a PLY file, and leave the file object 

464 at the position of the start of data but past the header. 

465 

466 Parameters 

467 ----------- 

468 file_obj : open file object 

469 Positioned at the start of the file 

470 

471 Returns 

472 ----------- 

473 elements : collections.OrderedDict 

474 Fields and data types populated 

475 is_ascii : bool 

476 Whether the data is ASCII or binary 

477 image_name : None or str 

478 File name of TextureFile 

479 """ 

480 

481 if "ply" not in str(file_obj.readline()).lower(): 

482 raise ValueError("Not a ply file!") 

483 

484 # collect the encoding: binary or ASCII 

485 encoding = file_obj.readline().decode("utf-8").strip().lower() 

486 is_ascii = "ascii" in encoding 

487 

488 # big or little endian 

489 endian = ["<", ">"][int("big" in encoding)] 

490 elements = collections.OrderedDict() 

491 

492 # store file name of TextureFiles in the header 

493 image_name = None 

494 

495 while True: 

496 raw = file_obj.readline() 

497 if raw is None: 

498 raise ValueError("Header not terminated properly!") 

499 raw = raw.decode("utf-8").strip() 

500 line = raw.split() 

501 

502 # we're done 

503 if "end_header" in line: 

504 break 

505 

506 # elements are groups of properties 

507 if "element" in line[0]: 

508 # we got a new element so add it 

509 name, length = line[1:] 

510 elements[name] = { 

511 "length": int(length), 

512 "properties": collections.OrderedDict(), 

513 } 

514 # a property is a member of an element 

515 elif "property" in line[0]: 

516 # a property must belong to an element declared before it; a header 

517 # with a property line before any element would otherwise reference 

518 # the unset `name` and raise an UnboundLocalError. 

519 if not elements: 

520 raise ValueError("Property defined before any element!") 

521 # is the property a simple single value, like: 

522 # `property float x` 

523 if len(line) == 3: 

524 dtype, field = line[1:] 

525 elements[name]["properties"][str(field)] = endian + _dtypes[dtype] 

526 # is the property a painful list, like: 

527 # `property list uchar int vertex_indices` 

528 elif "list" in line[1]: 

529 dtype_count, dtype, field = line[2:] 

530 elements[name]["properties"][str(field)] = ( 

531 endian + _dtypes[dtype_count] + ", ($LIST,)" + endian + _dtypes[dtype] 

532 ) 

533 # referenced as a file name 

534 elif "texturefile" in raw.lower(): 

535 # textures come listed like: 

536 # `comment TextureFile fuze_uv.jpg` 

537 index = raw.lower().index("texturefile") + 11 

538 # use the value from raw to preserve whitespace 

539 image_name = raw[index:].strip() 

540 

541 return elements, is_ascii, image_name 

542 

543 

544def _elements_to_kwargs(elements, fix_texture, image, prefer_color=None): 

545 """ 

546 Given an elements data structure, extract the keyword 

547 arguments that a Trimesh object constructor will expect. 

548 

549 Parameters 

550 ------------ 

551 elements : OrderedDict object 

552 With fields and data loaded 

553 fix_texture : bool 

554 If True, will re- index vertices and faces 

555 so vertices with different UV coordinates 

556 are disconnected. 

557 image : PIL.Image 

558 Image to be viewed 

559 prefer_color : None, 'vertex', or 'face' 

560 Which kind of color to prefer if both defined 

561 

562 Returns 

563 ----------- 

564 kwargs : dict 

565 Keyword arguments for Trimesh constructor 

566 """ 

567 # store the raw ply structure as an internal key in metadata 

568 kwargs = {"metadata": {"_ply_raw": elements}} 

569 

570 if "vertex" in elements and elements["vertex"]["length"]: 

571 vertices = np.column_stack([elements["vertex"]["data"][i] for i in "xyz"]) 

572 if not util.is_shape(vertices, (-1, 3)): 

573 raise ValueError("Vertices were not (n,3)!") 

574 else: 

575 # return empty geometry if there are no vertices 

576 kwargs["geometry"] = {} 

577 return kwargs 

578 

579 try: 

580 vertex_normals = np.column_stack( 

581 [elements["vertex"]["data"][j] for j in ("nx", "ny", "nz")] 

582 ) 

583 if len(vertex_normals) == len(vertices): 

584 kwargs["vertex_normals"] = vertex_normals 

585 except BaseException: 

586 pass 

587 

588 if "face" in elements and elements["face"]["length"]: 

589 face_data = elements["face"]["data"] 

590 else: 

591 # some PLY files only include vertices 

592 face_data = None 

593 faces = None 

594 

595 # what keys do in-the-wild exporters use for vertices 

596 index_names = ["vertex_index", "vertex_indices"] 

597 texcoord = None 

598 

599 if util.is_shape(face_data, (-1, (3, 4))): 

600 faces = face_data 

601 elif isinstance(face_data, dict): 

602 # get vertex indexes 

603 for i in index_names: 

604 if i in face_data: 

605 faces = face_data[i] 

606 break 

607 # if faces have UV coordinates defined use them 

608 if "texcoord" in face_data: 

609 texcoord = face_data["texcoord"] 

610 

611 elif isinstance(face_data, np.ndarray): 

612 face_blob = elements["face"]["data"] 

613 # some exporters set this name to 'vertex_index' 

614 # and some others use 'vertex_indices' but we really 

615 # don't care about the name unless there are multiple 

616 if len(face_blob.dtype.names) == 1: 

617 name = face_blob.dtype.names[0] 

618 elif len(face_blob.dtype.names) > 1: 

619 # loop through options 

620 for i in face_blob.dtype.names: 

621 if i in index_names: 

622 name = i 

623 break 

624 # get faces 

625 faces = face_blob[name]["f1"] 

626 

627 try: 

628 texcoord = face_blob["texcoord"]["f1"] 

629 except (ValueError, KeyError): 

630 # accessing numpy arrays with named fields 

631 # incorrectly is a ValueError 

632 pass 

633 

634 if faces is not None: 

635 shape = np.shape(faces) 

636 if len(shape) != 2: 

637 # we may have mixed quads and triangles handle them with function 

638 faces = triangulate_quads(faces) 

639 

640 if texcoord is None: 

641 # ply has no clear definition of how texture coordinates are stored, 

642 # unfortunately there are many common names that we need to try 

643 texcoord_names = [("texture_u", "texture_v"), ("u", "v"), ("s", "t")] 

644 for names in texcoord_names: 

645 # If texture coordinates are defined with vertices 

646 try: 

647 t_u = elements["vertex"]["data"][names[0]] 

648 t_v = elements["vertex"]["data"][names[1]] 

649 texcoord = np.stack( 

650 (t_u[faces.reshape(-1)], t_v[faces.reshape(-1)]), axis=-1 

651 ).reshape((faces.shape[0], -1)) 

652 # stop trying once succeeded 

653 break 

654 except (ValueError, KeyError): 

655 # if the fields didn't exist 

656 pass 

657 

658 shape = np.shape(faces) 

659 

660 # PLY stores texture coordinates per-face which is 

661 # slightly annoying, as we have to then figure out 

662 # which vertices have the same position but different UV 

663 if ( 

664 texcoord is not None 

665 and len(shape) == 2 

666 and texcoord.shape == (faces.shape[0], faces.shape[1] * 2) 

667 ): 

668 # vertices with the same position but different 

669 # UV coordinates can't be merged without it 

670 # looking like it went through a woodchipper 

671 # in- the- wild PLY comes with things merged that 

672 # probably shouldn't be so disconnect vertices 

673 if fix_texture: 

674 # do import here 

675 from ..visual.texture import unmerge_faces 

676 

677 # reshape to correspond with flattened faces 

678 uv_all = texcoord.reshape((-1, 2)) 

679 # UV coordinates defined for every triangle have 

680 # duplicates which can be merged so figure out 

681 # which UV coordinates are the same here 

682 unique, inverse = grouping.unique_rows(uv_all) 

683 

684 # use the indices of faces and face textures 

685 # to only merge vertices where the position 

686 # AND uv coordinate are the same 

687 faces, mask_v, mask_vt = unmerge_faces( 

688 faces, inverse.reshape(faces.shape) 

689 ) 

690 # apply the mask to get resulting vertices 

691 vertices = vertices[mask_v] 

692 # apply the mask to get UV coordinates 

693 uv = uv_all[unique][mask_vt] 

694 else: 

695 # don't alter vertices, UV will look like crap 

696 # if it was exported with vertices merged 

697 uv = np.zeros((len(vertices), 2)) 

698 uv[faces.reshape(-1)] = texcoord.reshape((-1, 2)) 

699 

700 # create the visuals object for the texture 

701 kwargs["visual"] = visual.texture.TextureVisuals(uv=uv, image=image) 

702 elif texcoord is not None: 

703 # create a texture with an empty material 

704 from ..visual.texture import TextureVisuals 

705 

706 uv = np.zeros((len(vertices), 2)) 

707 uv[faces.reshape(-1)] = texcoord.reshape((-1, 2)) 

708 kwargs["visual"] = TextureVisuals(uv=uv) 

709 # faces were not none so assign them 

710 kwargs["faces"] = faces 

711 # kwargs for Trimesh or PointCloud 

712 kwargs["vertices"] = vertices 

713 

714 # if both vertex and face color are defined pick the one 

715 if "face" in elements: 

716 kwargs["face_colors"] = _element_colors(elements["face"]) 

717 if "vertex" in elements: 

718 kwargs["vertex_colors"] = _element_colors(elements["vertex"]) 

719 

720 # check if we have gotten path elements 

721 edge_data = elements.get("edge", {}).get("data", None) 

722 if edge_data is not None: 

723 # try to convert the data in the PLY file to (n, 2) edge indexes 

724 edges = None 

725 if isinstance(edge_data, dict): 

726 try: 

727 edges = np.column_stack((edge_data["vertex1"], edge_data["vertex2"])) 

728 except BaseException: 

729 log.debug( 

730 f"failed to convert PLY edges from keys: {edge_data.keys()}", 

731 exc_info=True, 

732 ) 

733 elif isinstance(edge_data, np.ndarray): 

734 # is this the best way to check for a structured dtype? 

735 if len(edge_data.shape) == 2 and edge_data.shape[1] == 2: 

736 edges = edge_data 

737 else: 

738 # we could also check `edge_data.dtype.kind in 'OV'` 

739 # but its not clear that that handles all the possibilities 

740 edges = structured_to_unstructured(edge_data) 

741 

742 if edges is not None: 

743 from ..path.exchange.misc import edges_to_path 

744 

745 kwargs.update(edges_to_path(edges, kwargs["vertices"])) 

746 return kwargs 

747 

748 

749def _element_colors(element): 

750 """ 

751 Given an element, try to extract RGBA color from 

752 properties and return them as an (n,3|4) array. 

753 

754 Parameters 

755 ------------- 

756 element : dict 

757 Containing color keys 

758 

759 Returns 

760 ------------ 

761 colors : (n, 3) or (n, 4) float 

762 Colors extracted from the element 

763 signal : float 

764 Estimate of range 

765 """ 

766 keys = ["red", "green", "blue", "alpha"] 

767 candidate_colors = [element["data"][i] for i in keys if i in element["properties"]] 

768 if len(candidate_colors) >= 3: 

769 return np.column_stack(candidate_colors) 

770 return None 

771 

772 

773def _load_element_different(properties, data): 

774 """ 

775 Load elements which include lists of different lengths 

776 based on the element's property-definitions. 

777 

778 Parameters 

779 ------------ 

780 properties : dict 

781 Property definitions encoded in a dict where the property name is the key 

782 and the property data type the value. 

783 data : array 

784 Data rows for this element. 

785 """ 

786 edata = {k: [] for k in properties.keys()} 

787 for row in data: 

788 start = 0 

789 for name, dt in properties.items(): 

790 length = 1 

791 if "$LIST" in dt: 

792 dt = dt.split("($LIST,)")[-1] 

793 # the first entry in a list-property is the number of elements 

794 # in the list 

795 length = int(row[start]) 

796 # skip the first entry (the length), when reading the data 

797 start += 1 

798 end = start + length 

799 edata[name].append(row[start:end].astype(dt)) 

800 # start next property at the end of this one 

801 start = end 

802 

803 # if the shape of any array is (n, 1) we want to 

804 # squeeze/concatenate it into (n,) 

805 squeeze = {k: np.array(v, dtype="object") for k, v in edata.items()} 

806 # squeeze and convert any clean 2D arrays 

807 squeeze.update( 

808 { 

809 k: v.squeeze().astype(edata[k][0].dtype) 

810 for k, v in squeeze.items() 

811 if len(v.shape) == 2 

812 } 

813 ) 

814 

815 return squeeze 

816 

817 

818def _load_element_single(properties, data): 

819 """ 

820 Load element data with lists of a single length 

821 based on the element's property-definitions. 

822 

823 Parameters 

824 ------------ 

825 properties : dict 

826 Property definitions encoded in a dict where 

827 the property name is the key and the property 

828 data type the value. 

829 data : array 

830 Data rows for this element, if the data contains 

831 list-properties all lists belonging to one property 

832 must have the same length. 

833 """ 

834 

835 first = data[0] 

836 columns = {} 

837 current = 0 

838 for name, dt in properties.items(): 

839 # if the current index has gone past the number 

840 # of items we actually have exit the loop early 

841 if current >= len(first): 

842 break 

843 if "$LIST" in dt: 

844 dtype = dt.split("($LIST,)")[-1] 

845 # the first entry in a list-property 

846 # is the number of elements in the list 

847 

848 length = int(first[current]) 

849 columns[name] = data[:, current + 1 : current + 1 + length].astype(dtype) 

850 # offset by length of array plus one for each uint index 

851 current += length + 1 

852 else: 

853 columns[name] = data[:, current : current + 1].astype(dt) 

854 current += 1 

855 

856 return columns 

857 

858 

859def _ply_ascii(elements, file_obj): 

860 """ 

861 Load data from an ASCII PLY file into an existing elements data structure. 

862 

863 Parameters 

864 ------------ 

865 elements : OrderedDict 

866 Populated from the file header, data will 

867 be added in-place to this object 

868 file_obj : file-like-object 

869 Current position at the start 

870 of the data section (past the header). 

871 """ 

872 

873 # get the file contents as a string 

874 text = str(file_obj.read().decode("utf-8")) 

875 # split by newlines 

876 lines = str.splitlines(text) 

877 # get each line as an array split by whitespace 

878 array = [np.fromstring(i, sep=" ") for i in lines] 

879 # store the line position in the file 

880 row_pos = 0 

881 

882 # loop through data we need 

883 for key, values in elements.items(): 

884 # if the element is empty ignore it 

885 if "length" not in values or values["length"] == 0: 

886 continue 

887 data = array[row_pos : row_pos + values["length"]] 

888 row_pos += values["length"] 

889 # try stacking the data, which simplifies column-wise access. this is only 

890 # possible, if all rows have the same length. 

891 try: 

892 data = np.vstack(data) 

893 col_count_equal = True 

894 except ValueError: 

895 col_count_equal = False 

896 

897 # number of list properties in this element 

898 list_count = sum(1 for dt in values["properties"].values() if "$LIST" in dt) 

899 if col_count_equal and list_count <= 1: 

900 # all rows have the same length and we only have at most one list 

901 # property where all entries have the same length. this means we can 

902 # use the quick numpy-based loading. 

903 element_data = _load_element_single(values["properties"], data) 

904 else: 

905 # there are lists of differing lengths. we need to fall back to loading 

906 # the data by iterating all rows and checking for list-lengths. this is 

907 # slower than the variant above. 

908 element_data = _load_element_different(values["properties"], data) 

909 

910 elements[key]["data"] = element_data 

911 

912 

913def _ply_binary(elements, file_obj): 

914 """ 

915 Load the data from a binary PLY file into the elements data structure. 

916 

917 Parameters 

918 ------------ 

919 elements : OrderedDict 

920 Populated from the file header. 

921 Object will be modified to add data by this function. 

922 file_obj : open file object 

923 With current position at the start 

924 of the data section (past the header) 

925 """ 

926 

927 def populate_listsize(file_obj, elements): 

928 """ 

929 Given a set of elements populated from the header if there are any 

930 list properties seek in the file the length of the list. 

931 

932 Note that if you have a list where each instance is different length 

933 (if for example you mixed triangles and quads) this won't work at all 

934 """ 

935 p_start = file_obj.tell() 

936 p_current = file_obj.tell() 

937 elem_pop = [] 

938 for element_key, element in elements.items(): 

939 props = element["properties"] 

940 prior_data = "" 

941 for k, dtype in props.items(): 

942 prop_pop = [] 

943 if "$LIST" in dtype: 

944 # every list field has two data types: 

945 # the list length (single value), and the list data (multiple) 

946 # here we are only reading the single value for list length 

947 field_dtype = np.dtype(dtype.split(",")[0]) 

948 if len(prior_data) == 0: 

949 offset = 0 

950 else: 

951 offset = np.dtype(prior_data).itemsize 

952 file_obj.seek(p_current + offset) 

953 blob = file_obj.read(field_dtype.itemsize) 

954 if len(blob) == 0: 

955 # no data was read for property 

956 prop_pop.append(k) 

957 break 

958 size = np.frombuffer(blob, dtype=field_dtype)[0] 

959 props[k] = props[k].replace("$LIST", str(size)) 

960 prior_data += props[k] + "," 

961 if len(prop_pop) > 0: 

962 # if a property was empty remove it 

963 for pop in prop_pop: 

964 props.pop(pop) 

965 # if we've removed all properties from 

966 # an element remove the element later 

967 if len(props) == 0: 

968 elem_pop.append(element_key) 

969 continue 

970 # get the size of the items in bytes 

971 itemsize = np.dtype(", ".join(props.values())).itemsize 

972 # offset the file based on read size 

973 p_current += element["length"] * itemsize 

974 # move the file back to where we found it 

975 file_obj.seek(p_start) 

976 # if there were elements without properties remove them 

977 for pop in elem_pop: 

978 elements.pop(pop) 

979 

980 def populate_data(file_obj, elements): 

981 """ 

982 Given the data type and field information from the header, 

983 read the data and add it to a 'data' field in the element. 

984 """ 

985 for key in elements.keys(): 

986 items = list(elements[key]["properties"].items()) 

987 dtype = np.dtype(items) 

988 data = file_obj.read(elements[key]["length"] * dtype.itemsize) 

989 try: 

990 elements[key]["data"] = np.frombuffer(data, dtype=dtype) 

991 except BaseException: 

992 log.warning(f"PLY failed to populate: {key}") 

993 elements[key]["data"] = None 

994 return elements 

995 

996 def _elements_size(elements): 

997 """ 

998 Given an elements data structure populated from the header, 

999 calculate how long the file should be if it is intact. 

1000 """ 

1001 size = 0 

1002 for element in elements.values(): 

1003 dtype = np.dtype(",".join(element["properties"].values())) 

1004 size += element["length"] * dtype.itemsize 

1005 return size 

1006 

1007 # some elements are passed where the list dimensions 

1008 # are not included in the header, so this function goes 

1009 # into the meat of the file and grabs the list dimensions 

1010 # before we to the main data read as a single operation 

1011 populate_listsize(file_obj, elements) 

1012 

1013 # how many bytes are left in the file 

1014 size_file = util.distance_to_end(file_obj) 

1015 # how many bytes should the data structure described by 

1016 # the header take up 

1017 size_elements = _elements_size(elements) 

1018 

1019 # if the number of bytes is not the same the file is probably corrupt 

1020 if size_file != size_elements: 

1021 raise ValueError("PLY is unexpected length!") 

1022 

1023 # with everything populated and a reasonable confidence the file 

1024 # is intact, read the data fields described by the header 

1025 populate_data(file_obj, elements) 

1026 

1027 

1028def export_draco(mesh, bits=28): 

1029 """ 

1030 Export a mesh using Google's Draco compressed format. 

1031 

1032 Only works if draco_encoder is in your PATH: 

1033 https://github.com/google/draco 

1034 

1035 Parameters 

1036 ---------- 

1037 mesh : Trimesh object 

1038 Mesh to export 

1039 bits : int 

1040 Bits of quantization for position 

1041 tol.merge=1e-8 is roughly 25 bits 

1042 

1043 Returns 

1044 ---------- 

1045 data : str or bytes 

1046 DRC file bytes 

1047 """ 

1048 with tempfile.NamedTemporaryFile(suffix=".ply") as temp_ply: 

1049 temp_ply.write(export_ply(mesh)) 

1050 temp_ply.flush() 

1051 with tempfile.NamedTemporaryFile(suffix=".drc") as encoded: 

1052 subprocess.check_output( 

1053 [ 

1054 draco_encoder, 

1055 "-qp", 

1056 str(int(bits)), 

1057 "-i", 

1058 temp_ply.name, 

1059 "-o", 

1060 encoded.name, 

1061 ] 

1062 ) 

1063 encoded.seek(0) 

1064 data = encoded.read() 

1065 return data 

1066 

1067 

1068def load_draco(file_obj, **kwargs): 

1069 """ 

1070 Load a mesh from Google's Draco format. 

1071 

1072 Parameters 

1073 ---------- 

1074 file_obj : file- like object 

1075 Contains data 

1076 

1077 Returns 

1078 ---------- 

1079 kwargs : dict 

1080 Keyword arguments to construct a Trimesh object 

1081 """ 

1082 

1083 with tempfile.NamedTemporaryFile(suffix=".drc") as temp_drc: 

1084 temp_drc.write(file_obj.read()) 

1085 temp_drc.flush() 

1086 

1087 with tempfile.NamedTemporaryFile(suffix=".ply") as temp_ply: 

1088 subprocess.check_output( 

1089 [draco_decoder, "-i", temp_drc.name, "-o", temp_ply.name] 

1090 ) 

1091 temp_ply.seek(0) 

1092 kwargs = load_ply(temp_ply) 

1093 return kwargs 

1094 

1095 

1096_ply_loaders = {"ply": load_ply} 

1097_ply_exporters = {"ply": export_ply} 

1098 

1099draco_encoder = util.which("draco_encoder") 

1100draco_decoder = util.which("draco_decoder") 

1101if draco_decoder is not None: 

1102 _ply_loaders["drc"] = load_draco 

1103if draco_encoder is not None: 

1104 _ply_exporters["drc"] = export_draco