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
« 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
6import numpy as np
7from numpy.lib.recfunctions import structured_to_unstructured, unstructured_to_structured
9from .. import grouping, resources, util, visual
10from ..constants import log
11from ..geometry import triangulate_quads
12from ..resolvers import Resolver
13from ..typed import ArrayLike
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}
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}
54def _numpy_type_to_ply_type(_numpy_type):
55 """
56 Returns the closest ply equivalent of a numpy type
58 Parameters
59 ---------
60 _numpy_type : a numpy datatype
62 Returns
63 ---------
64 ply_type : string
65 """
66 return _inverse_dtypes[_numpy_type.str[1:]]
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.
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
97 Returns
98 ---------
99 mesh_kwargs : dict
100 Data which can be passed to
101 Trimesh constructor, eg: a = Trimesh(**mesh_kwargs)
102 """
104 # OrderedDict which is populated from the header
105 elements, is_ascii, image_name = _parse_header(file_obj)
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)
113 # try to load the referenced image
114 image = None
115 if not skip_materials:
116 try:
117 # soft dependency
118 import PIL.Image
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)
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 )
134 return kwargs
137def _add_attributes_to_dtype(dtype, attributes):
138 """
139 Parses attribute datatype to populate a numpy dtype list
141 Parameters
142 ----------
143 dtype : list of numpy datatypes
144 operated on in place
145 attributes : dict
146 contains all the attributes to parse
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
162def _add_attributes_to_header(header, attributes):
163 """
164 Parses attributes in to ply header entries
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
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
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
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
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
211def _assert_attributes_valid(attributes):
212 """
213 Asserts that a set of attributes is valid for PLY export.
215 Parameters
216 ----------
217 attributes : dict
218 Contains the attributes to validate
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")
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.
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
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
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)
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))]
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}
297 # structured arrays for exports
298 pack_edges: ArrayLike | None = None
299 pack_vertex: ArrayLike | None = None
300 pack_faces: ArrayLike | None = None
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")
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]
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]))
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)))
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 )
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)
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)
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)
345 # add the values for the header
346 header_params.update(
347 {"edge_count": num_edges, "vertex_count": num_vertices}
348 )
350 elif hasattr(mesh, "vertices"):
351 header.append(templates["vertex"])
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)
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)
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
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
392 if include_attributes and vertex_attributes is not None:
393 _add_attributes_to_data_array(pack_vertex, vertex_attributes)
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)
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)
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)
413 if include_attributes and hasattr(mesh, "face_attributes"):
414 _add_attributes_to_data_array(pack_faces, mesh.face_attributes)
416 header.append(templates["outro"])
417 export = [Template("".join(header)).substitute(header_params).encode("utf-8")]
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 )
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 )
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")
455 else:
456 raise ValueError("encoding must be ascii or binary!")
458 return b"".join(export)
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.
466 Parameters
467 -----------
468 file_obj : open file object
469 Positioned at the start of the file
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 """
481 if "ply" not in str(file_obj.readline()).lower():
482 raise ValueError("Not a ply file!")
484 # collect the encoding: binary or ASCII
485 encoding = file_obj.readline().decode("utf-8").strip().lower()
486 is_ascii = "ascii" in encoding
488 # big or little endian
489 endian = ["<", ">"][int("big" in encoding)]
490 elements = collections.OrderedDict()
492 # store file name of TextureFiles in the header
493 image_name = None
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()
502 # we're done
503 if "end_header" in line:
504 break
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()
541 return elements, is_ascii, image_name
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.
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
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}}
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
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
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
595 # what keys do in-the-wild exporters use for vertices
596 index_names = ["vertex_index", "vertex_indices"]
597 texcoord = None
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"]
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"]
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
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)
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
658 shape = np.shape(faces)
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
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)
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))
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
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
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"])
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)
742 if edges is not None:
743 from ..path.exchange.misc import edges_to_path
745 kwargs.update(edges_to_path(edges, kwargs["vertices"]))
746 return kwargs
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.
754 Parameters
755 -------------
756 element : dict
757 Containing color keys
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
773def _load_element_different(properties, data):
774 """
775 Load elements which include lists of different lengths
776 based on the element's property-definitions.
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
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 )
815 return squeeze
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.
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 """
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
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
856 return columns
859def _ply_ascii(elements, file_obj):
860 """
861 Load data from an ASCII PLY file into an existing elements data structure.
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 """
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
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
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)
910 elements[key]["data"] = element_data
913def _ply_binary(elements, file_obj):
914 """
915 Load the data from a binary PLY file into the elements data structure.
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 """
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.
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)
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
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
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)
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)
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!")
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)
1028def export_draco(mesh, bits=28):
1029 """
1030 Export a mesh using Google's Draco compressed format.
1032 Only works if draco_encoder is in your PATH:
1033 https://github.com/google/draco
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
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
1068def load_draco(file_obj, **kwargs):
1069 """
1070 Load a mesh from Google's Draco format.
1072 Parameters
1073 ----------
1074 file_obj : file- like object
1075 Contains data
1077 Returns
1078 ----------
1079 kwargs : dict
1080 Keyword arguments to construct a Trimesh object
1081 """
1083 with tempfile.NamedTemporaryFile(suffix=".drc") as temp_drc:
1084 temp_drc.write(file_obj.read())
1085 temp_drc.flush()
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
1096_ply_loaders = {"ply": load_ply}
1097_ply_exporters = {"ply": export_ply}
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