Coverage for trimesh/exchange/threemf.py: 91%
197 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 io
2import uuid
3import zipfile
4from collections import defaultdict
6import numpy as np
8from .. import graph, util
9from ..constants import log
10from ..util import unique_name
13def _read_mesh(mesh):
14 """
15 Read a `<mesh ` XML element into Numpy vertices and faces.
17 This is generally the most expensive operation in the load as it
18 has to operate in Python-space on every single vertex and face.
20 Parameters
21 ----------
22 mesh : lxml.etree.Element
23 Input mesh element with `vertex` and `triangle` children.
25 Returns
26 ----------
27 vertex_array : (n, 3) float64
28 Vertices
29 face_array : (n, 3) int64
30 Indexes of vertices forming triangles.
31 """
32 # get the XML elements for vertices and faces
33 vertices = mesh.find("{*}vertices")
34 faces = mesh.find("{*}triangles")
36 # get every value as a flat space-delimited string
37 # this is very sensitive as it is large, i.e. it is
38 # much faster with the full list comprehension before
39 # the `.join` as the giant string can be fully allocated
40 vs = " ".join(
41 [
42 f"{i.attrib['x']} {i.attrib['y']} {i.attrib['z']}"
43 for i in vertices.iter("{*}vertex")
44 ]
45 )
46 # convert every value to floating point in one-shot rather than in a loop
47 v_array = np.fromstring(vs, dtype=np.float64, sep=" ").reshape((-1, 3))
49 # do the same behavior for faces but as an integer
50 fs = " ".join(
51 [
52 f"{i.attrib['v1']} {i.attrib['v2']} {i.attrib['v3']}"
53 for i in faces.iter("{*}triangle")
54 ]
55 )
56 f_array = np.fromstring(fs, dtype=np.int64, sep=" ").reshape((-1, 3))
58 return v_array, f_array
61def load_3MF(file_obj, postprocess=True, **kwargs):
62 """
63 Load a 3MF formatted file into a Trimesh scene.
65 Parameters
66 ------------
67 file_obj : file-like
68 Contains 3MF formatted data
70 Returns
71 ------------
72 kwargs : dict
73 Constructor arguments for `trimesh.Scene`
74 """
76 # dict, {name in archive: BytesIo}
77 archive = util.decompress(file_obj, file_type="zip")
78 # get model with case-insensitive keys
79 model = next(iter(v for k, v in archive.items() if "3d/3dmodel.model" in k.lower()))
81 # read root attributes only from XML first
82 _event, root = next(
83 etree.iterparse(model, tag=("{*}model"), events=("start",), **XML_PARSER_OPTIONS)
84 )
85 # collect unit information from the tree
86 if "unit" in root.attrib:
87 metadata = {"units": root.attrib["unit"]}
88 else:
89 # the default units, defined by the specification
90 metadata = {"units": "millimeters"}
92 # { mesh id : mesh name}
93 id_name = {}
94 # { mesh id: (n,3) float vertices}
95 v_seq = defaultdict(list)
96 # { mesh id: (n,3) int faces}
97 f_seq = defaultdict(list)
98 # components are objects that contain other objects
99 # {id : [other ids]}
100 components = defaultdict(list)
101 # load information about the scene graph
102 # each instance is a single geometry
103 build_items = []
105 # keep track of names we can use
106 consumed_counts = {}
107 consumed_names = set()
109 # iterate the XML object and build elements with an LXML iterator
110 # loaded elements are cleared to avoid ballooning memory
111 model.seek(0)
112 for _, obj in etree.iterparse(
113 model, tag=("{*}object", "{*}build"), events=("end",), **XML_PARSER_OPTIONS
114 ):
115 # parse objects
116 if "object" in obj.tag:
117 # id is mandatory
118 index = obj.attrib["id"]
120 # start with stored name
121 # apparently some exporters name multiple meshes
122 # the same thing so check to see if it's been used
123 name = unique_name(
124 obj.attrib.get("name", str(index)), consumed_names, consumed_counts
125 )
126 consumed_names.add(name)
127 # store name reference on the index
128 id_name[index] = name
130 # if the object has actual geometry data parse here
131 for mesh in obj.iter("{*}mesh"):
132 v, f = _read_mesh(mesh)
133 v_seq[index].append(v)
134 f_seq[index].append(f)
136 # components are references to other geometries
137 for c in obj.iter("{*}component"):
138 mesh_index = c.attrib["objectid"]
139 transform = _attrib_to_transform(c.attrib)
140 components[index].append((mesh_index, transform))
142 # if this references another file as the `path` attrib
143 path = next(
144 (v.strip("/") for k, v in c.attrib.items() if k.endswith("path")),
145 None,
146 )
147 if path is not None and path in archive:
148 archive[path].seek(0)
149 name = unique_name(
150 obj.attrib.get("name", str(mesh_index)),
151 consumed_names,
152 consumed_counts,
153 )
154 consumed_names.add(name)
155 # store name reference on the index
156 id_name[mesh_index] = name
158 for _, m in etree.iterparse(
159 archive[path],
160 tag=("{*}mesh"),
161 events=("end",),
162 **XML_PARSER_OPTIONS,
163 ):
164 v, f = _read_mesh(m)
165 v_seq[mesh_index].append(v)
166 f_seq[mesh_index].append(f)
168 # parse build
169 if "build" in obj.tag:
170 # scene graph information stored here, aka "build" the scene
171 for item in obj.iter("{*}item"):
172 # get a transform from the item's attributes
173 transform = _attrib_to_transform(item.attrib)
174 partnumber = item.attrib.get("partnumber", None)
175 # the index of the geometry this item instantiates
176 build_items.append((item.attrib["objectid"], transform, partnumber))
178 # have one mesh per 3MF object
179 # one mesh per geometry ID, store as kwargs for the object
180 meshes = {}
181 for gid in v_seq.keys():
182 v, f = util.append_faces(v_seq[gid], f_seq[gid])
183 name = id_name[gid]
184 meshes[name] = {
185 "vertices": v,
186 "faces": f,
187 "metadata": metadata.copy(),
188 }
189 # apply any keyword arguments that aren't None
190 meshes[name].update({k: v for k, v in kwargs.items() if v is not None})
192 # turn the item / component representation into
193 # a MultiDiGraph to compound our pain
194 g = nx.MultiDiGraph()
195 # build items are the only things that exist according to 3MF
196 # so we accomplish that by linking them to the base frame
197 # if partnumbers are None, the key will be an int
198 for gid, tf, partnumber in build_items:
199 g.add_edge("world", gid, key=partnumber, matrix=tf)
200 # components are instances which need to be linked to base
201 # frame by a build_item
202 for start, group in components.items():
203 for gid, tf in group:
204 g.add_edge(start, gid, matrix=tf)
206 # turn the graph into kwargs for a scene graph
207 # flatten the scene structure and simplify to
208 # a single unique node per instance
209 graph_args = []
210 parents = defaultdict(set)
211 used_names = set()
212 for path in graph.multigraph_paths(G=g, source="world"):
213 # collect all the transform on the path
214 transforms = graph.multigraph_collect(G=g, traversal=path, attrib="matrix")
215 # combine them into a single transform
216 if len(transforms) == 1:
217 transform = transforms[0]
218 else:
219 transform = util.multi_dot(transforms)
221 # the last element of the path should be the geometry
222 last = path[-1][0]
223 # if someone included an undefined component, skip it
224 if last not in id_name:
225 log.warning(f"id {last} included but not defined!")
226 continue
228 if len(path[-1]) > 1 and isinstance(path[-1][1], str):
229 # use the `partnumber` as the name
230 name = path[-1][1]
231 else:
232 # use the name from the id
233 name = id_name[last]
235 # make the name unique
236 name = unique_name(name, used_names)
237 used_names.add(name)
239 # index in meshes
240 geom = id_name[last]
242 # collect parents if we want to combine later
243 if len(path) > 2:
244 parent = path[-2][0]
245 parents[parent].add(last)
247 graph_args.append(
248 {
249 "frame_from": "world",
250 "frame_to": name,
251 "matrix": transform,
252 "geometry": geom,
253 }
254 )
256 # solidworks will export each body as its own mesh with the part
257 # name as the parent so optionally rename and combine these bodies
258 if postprocess and all("body" in i.lower() for i in meshes.keys()):
259 # don't rename by default
260 rename = {k: k for k in meshes.keys()}
261 for parent, mesh_name in parents.items():
262 # only handle the case where a parent has a single child
263 # if there are multiple children we would do a combine op
264 if len(mesh_name) != 1:
265 continue
266 # rename the part
267 rename[id_name[next(iter(mesh_name))]] = id_name[parent].split("(")[0]
269 # apply the rename operation meshes
270 meshes = {rename[k]: m for k, m in meshes.items()}
271 # rename geometry references in the scene graph
272 for arg in graph_args:
273 if "geometry" in arg:
274 arg["geometry"] = rename[arg["geometry"]]
276 # construct the kwargs to load the scene
277 kwargs = {
278 "base_frame": "world",
279 "graph": graph_args,
280 "geometry": meshes,
281 "metadata": metadata,
282 }
284 return kwargs
287def export_3MF(mesh, batch_size=4096, compression=zipfile.ZIP_DEFLATED, compresslevel=5):
288 """
289 Converts a Trimesh object into a 3MF file.
291 Parameters
292 ---------
293 mesh trimesh.trimesh
294 Mesh or Scene to export.
295 batch_size : int
296 Number of nodes to write per batch.
297 compression : zipfile.ZIP_*
298 Type of zip compression to use in this export.
299 compresslevel : int
300 Specify the 0-9 compression level.
302 Returns
303 ---------
304 export : bytes
305 Represents geometry as a 3MF file.
306 """
308 from ..scene.scene import Scene
310 if not isinstance(mesh, Scene):
311 mesh = Scene(mesh)
313 geometry = mesh.geometry
314 graph = mesh.graph.to_networkx()
315 base_frame = mesh.graph.base_frame
317 # xml namespaces
318 model_nsmap = {
319 None: "http://schemas.microsoft.com/3dmanufacturing/core/2015/02",
320 "m": "http://schemas.microsoft.com/3dmanufacturing/material/2015/02",
321 "p": "http://schemas.microsoft.com/3dmanufacturing/production/2015/06",
322 "b": "http://schemas.microsoft.com/3dmanufacturing/beamlattice/2017/02",
323 "s": "http://schemas.microsoft.com/3dmanufacturing/slice/2015/07",
324 "sc": "http://schemas.microsoft.com/3dmanufacturing/securecontent/2019/04",
325 }
327 rels_nsmap = {None: "http://schemas.openxmlformats.org/package/2006/relationships"}
329 # model ids
330 models = []
332 def model_id(x):
333 if x not in models:
334 models.append(x)
335 return str(models.index(x) + 1)
337 def object_id(node, data):
338 # nodes with children are written as a `components` object
339 # which also references the node's own geometry
340 if len(graph[node]) > 0:
341 return model_id(("node", node))
342 return model_id(data.get("geometry", node))
344 # 3mf archive dict {path: BytesIO}
345 file_obj = io.BytesIO()
347 # specify the parameters for the zip container
348 zip_kwargs = {"compression": compression, "compresslevel": compresslevel}
350 with zipfile.ZipFile(file_obj, mode="w", **zip_kwargs) as z:
351 # 3dmodel.model
352 with (
353 z.open("3D/3dmodel.model", mode="w") as f,
354 etree.xmlfile(f, encoding="utf-8") as xf,
355 ):
356 xf.write_declaration()
358 # stream elements
359 with xf.element("model", {"unit": "millimeter"}, nsmap=model_nsmap):
360 # objects with mesh data and/or references to other objects
361 with xf.element("resources"):
362 # stream objects with actual mesh data
363 for i, (name, m) in enumerate(geometry.items()):
364 # attributes for object
365 attribs = {
366 "id": model_id(name),
367 "name": name,
368 "type": "model",
369 "p:UUID": str(uuid.uuid4()),
370 }
371 with xf.element("object", **attribs):
372 with xf.element("mesh"):
373 with xf.element("vertices"):
374 # vertex nodes are written directly to the file
375 # so make sure lxml's buffer is flushed
376 xf.flush()
377 for i in range(0, len(m.vertices), batch_size):
378 batch = m.vertices[i : i + batch_size]
379 fragment = (
380 '<vertex x="{}" y="{}" z="{}" />' * len(batch)
381 )
382 f.write(
383 fragment.format(*batch.flatten()).encode(
384 "utf-8"
385 )
386 )
387 with xf.element("triangles"):
388 xf.flush()
389 for i in range(0, len(m.faces), batch_size):
390 batch = m.faces[i : i + batch_size]
391 fragment = (
392 '<triangle v1="{}" v2="{}" v3="{}" />'
393 * len(batch)
394 )
395 f.write(
396 fragment.format(*batch.flatten()).encode(
397 "utf-8"
398 )
399 )
401 # stream components
402 for node in graph.nodes:
403 if node == base_frame or node.startswith("camera"):
404 continue
405 if len(graph[node]) == 0:
406 continue
408 attribs = {
409 "id": model_id(("node", node)),
410 "name": node,
411 "type": "model",
412 "p:UUID": str(uuid.uuid4()),
413 }
414 with xf.element("object", **attribs):
415 with xf.element("components"):
416 geom = mesh.graph.transforms.node_data[node].get(
417 "geometry"
418 )
419 if geom is not None:
420 xf.write(
421 etree.Element(
422 "component", {"objectid": model_id(geom)}
423 )
424 )
425 for next, data in graph[node].items():
426 transform = " ".join(
427 str(i)
428 for i in np.array(data["matrix"])[
429 :3, :4
430 ].T.flatten()
431 )
432 xf.write(
433 etree.Element(
434 "component",
435 {
436 "objectid": object_id(next, data),
437 "transform": transform,
438 },
439 )
440 )
442 # stream build (objects on base_frame)
443 with xf.element("build", {"p:UUID": str(uuid.uuid4())}):
444 for node, data in graph[base_frame].items():
445 if node.startswith("camera"):
446 continue
447 transform = " ".join(
448 str(i) for i in np.array(data["matrix"])[:3, :4].T.flatten()
449 )
450 uuid_tag = "{{{}}}UUID".format(model_nsmap["p"])
451 xf.write(
452 etree.Element(
453 "item",
454 {
455 "objectid": object_id(node, data),
456 "transform": transform,
457 uuid_tag: str(uuid.uuid4()),
458 "partnumber": node,
459 },
460 nsmap=model_nsmap,
461 )
462 )
464 # .rels
465 with z.open("_rels/.rels", "w") as f, etree.xmlfile(f, encoding="utf-8") as xf:
466 xf.write_declaration()
467 # stream elements
468 with xf.element("Relationships", nsmap=rels_nsmap):
469 rt = "http://schemas.microsoft.com/3dmanufacturing/2013/01/3dmodel"
470 xf.write(
471 etree.Element(
472 "Relationship",
473 Type=rt,
474 Target="/3D/3dmodel.model",
475 Id="rel0",
476 )
477 )
479 # [Content_Types].xml
480 with (
481 z.open("[Content_Types].xml", "w") as f,
482 etree.xmlfile(f, encoding="utf-8") as xf,
483 ):
484 xf.write_declaration()
485 # xml namespaces
486 nsmap = {None: "http://schemas.openxmlformats.org/package/2006/content-types"}
488 # stream elements
489 types = [
490 ("jpeg", "image/jpeg"),
491 ("jpg", "image/jpeg"),
492 ("model", "application/vnd.ms-package.3dmanufacturing-3dmodel+xml"),
493 ("png", "image/png"),
494 ("rels", "application/vnd.openxmlformats-package.relationships+xml"),
495 (
496 "texture",
497 "application/vnd.ms-package.3dmanufacturing-3dmodeltexture",
498 ),
499 ]
500 with xf.element("Types", nsmap=nsmap):
501 for ext, ctype in types:
502 xf.write(etree.Element("Default", Extension=ext, ContentType=ctype))
504 return file_obj.getvalue()
507def _attrib_to_transform(attrib):
508 """
509 Extract a homogeneous transform from a dictionary.
511 Parameters
512 ------------
513 attrib: dict, optionally containing 'transform'
515 Returns
516 ------------
517 transform: (4, 4) float, homogeonous transformation
518 """
520 transform = np.eye(4, dtype=np.float64)
521 if "transform" in attrib:
522 # wangle their transform format
523 values = np.array(attrib["transform"].split(), dtype=np.float64).reshape((4, 3)).T
524 transform[:3, :4] = values
525 return transform
528# do import here to keep lxml a soft dependency
529try:
530 import networkx as nx
531 from lxml import etree
533 from .common import XML_PARSER_OPTIONS
535 _three_loaders = {"3mf": load_3MF}
536 _3mf_exporters = {"3mf": export_3MF}
537except BaseException as E:
538 from ..exceptions import ExceptionWrapper
540 _three_loaders = {"3mf": ExceptionWrapper(E)}
541 _3mf_exporters = {"3mf": ExceptionWrapper(E)}