Coverage for trimesh/exchange/threedxml.py: 94%
218 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
1"""
2threedxml.py
3-------------
5Load 3DXML files, a scene format from Dassault products like Solidworks, Abaqus, Catia
6"""
8import numpy as np
10try:
11 # `pip install pillow`
12 # optional: used for textured meshes
13 from PIL import Image
14except BaseException as E:
15 # if someone tries to use Image re-raise
16 # the import error so they can debug easily
17 from ..exceptions import ExceptionWrapper
19 Image = ExceptionWrapper(E)
21import collections
22import json
24from .. import util
25from ..visual.color import color_to_uv
26from ..visual.material import SimpleMaterial, pack
27from ..visual.texture import TextureVisuals
30def load_3DXML(file_obj, *args, **kwargs):
31 """
32 Load a 3DXML scene into kwargs. 3DXML is a CAD format
33 that can be exported from Solidworks
35 Parameters
36 ------------
37 file_obj : file object
38 Open and containing 3DXML data
40 Returns
41 -----------
42 kwargs : dict
43 Can be passed to trimesh.exchange.load.load_kwargs
44 """
45 archive = util.decompress(file_obj, file_type="zip")
47 # a dictionary of file name : lxml etree
48 as_etree = {}
49 for k, v in archive.items():
50 # wrap in try statement, as sometimes 3DXML
51 # contains non- xml files, like JPG previews
52 try:
53 as_etree[k] = etree.fromstring(
54 v.read(), parser=etree.XMLParser(**XML_PARSER_OPTIONS)
55 )
56 except etree.XMLSyntaxError:
57 # move the file object back to the file start
58 v.seek(0)
60 # the file name of the root scene
61 root_file = as_etree["Manifest.xml"].find("{*}Root").text
62 # the etree of the scene layout
63 tree = as_etree[root_file]
64 # index of root element of directed acyclic graph
65 root_id = tree.find("{*}ProductStructure").attrib["root"]
67 # load the materials library from the materials elements
68 colors = {}
69 images = {}
70 # but only if it exists
71 material_key = "CATMaterialRef.3dxml"
72 if material_key in as_etree:
73 material_tree = as_etree[material_key]
74 for MaterialDomain in material_tree.iter("{*}MaterialDomain"):
75 material_id = MaterialDomain.attrib["id"]
76 material_file = MaterialDomain.attrib["associatedFile"].split("urn:3DXML:")[
77 -1
78 ]
79 rend = as_etree[material_file].find("{*}Feature[@Alias='RenderingFeature']")
80 diffuse = rend.find("{*}Attr[@Name='DiffuseColor']")
81 # specular = rend.find("{*}Attr[@Name='SpecularColor']")
82 # emissive = rend.find("{*}Attr[@Name='EmissiveColor']")
83 if diffuse is not None:
84 rgb = (np.array(json.loads(diffuse.attrib["Value"])) * 255).astype(
85 np.uint8
86 )
87 colors[material_id] = rgb
88 texture = rend.find("{*}Attr[@Name='TextureImage']")
89 if texture is not None:
90 tex_file, tex_id = texture.attrib["Value"].split(":")[-1].split("#")
91 rep_image = as_etree[tex_file].find(
92 f"{{*}}CATRepImage/{{*}}CATRepresentationImage[@id='{tex_id}']"
93 )
94 if rep_image is not None:
95 image_file = rep_image.get("associatedFile", "").split(":")[-1]
96 images[material_id] = Image.open(archive[image_file])
98 # copy indexes for instances of colors
99 for MaterialDomainInstance in material_tree.iter("{*}MaterialDomainInstance"):
100 instance = MaterialDomainInstance.find("{*}IsInstanceOf")
101 # colors[b.attrib['id']] = colors[instance.text]
102 for aggregate in MaterialDomainInstance.findall("{*}IsAggregatedBy"):
103 colors[aggregate.text] = colors.get(instance.text)
104 images[aggregate.text] = images.get(instance.text)
106 # references which hold the 3DXML scene structure as a dict
107 # element id : {key : value}
108 references = collections.defaultdict(dict)
110 def get_rgba(color):
111 """
112 Return (4,) uint8 color array defined by Color element attributes.
114 Parameters
115 -----------
116 color : lxml.Element
117 Element containing RGBA colors.
119 Returns
120 -----------
121 as_int : (4,) np.uint8
122 Colors as uint8 RGBA.
123 """
124 assert "RGBAColorType" in color.attrib.values()
125 # colors will be float 0.0 - 1.0
126 rgba = np.array(
127 [color.get(channel, 1.0) for channel in ("red", "green", "blue", "alpha")],
128 dtype=np.float64,
129 )
130 # convert to int colors
131 return (rgba * 255).astype(np.uint8)
133 # the 3DXML can specify different visual properties for occurrences
134 view = tree.find("{*}DefaultView")
135 if view is not None:
136 for ViewProp in view.iter("{*}DefaultViewProperty"):
137 color = ViewProp.find(
138 "{*}GraphicProperties/" + "{*}SurfaceAttributes/{*}Color"
139 )
140 if color is None:
141 continue
142 rgba = get_rgba(color)
143 for occurrence in ViewProp.findall("{*}OccurenceId/{*}id"):
144 reference_id = occurrence.text.split("#")[-1]
145 references[reference_id]["color"] = rgba
147 # geometries will hold meshes
148 geometries = {}
150 # get geometry
151 for ReferenceRep in tree.iter(tag="{*}ReferenceRep"):
152 # the str of an int that represents this meshes unique ID
153 part_id = ReferenceRep.attrib["id"]
154 # which part file in the archive contains the geometry we care about
155 part_file = ReferenceRep.attrib["associatedFile"].split(":")[-1]
156 # the format of the geometry file
157 part_format = ReferenceRep.attrib["format"]
158 if part_format not in ("TESSELLATED",):
159 util.log.warning(
160 f"ReferenceRep {part_file!r} unsupported format {part_format!r}"
161 )
162 continue
164 # load actual geometry
165 mesh_faces = []
166 mesh_colors = []
167 mesh_normals = []
168 mesh_vertices = []
169 mesh_uv = []
170 # the texture image of each Rep, or None for a Rep without one
171 rep_images = []
173 if part_file not in as_etree and part_file in archive:
174 # the data is stored in some binary format
175 util.log.warning(f"unable to load Rep {part_file!r}")
176 # data = archive[part_file]
177 continue
179 # the geometry is stored in a Rep
180 for Rep in as_etree[part_file].iter("{*}Rep"):
181 rep_faces = [] # faces sharing the same list of vertices
182 rep_colors = [] # (m, 3) uint8 color of each face in rep_faces
183 vertices = Rep.find("{*}VertexBuffer/{*}Positions")
184 if vertices is None:
185 continue
187 # they mix delimiters like we couldn't figure it out from the
188 # shape :(
189 # load vertices into (n, 3) float64
190 mesh_vertices.append(
191 np.fromstring(
192 vertices.text.replace(",", " "), sep=" ", dtype=np.float64
193 ).reshape((-1, 3))
194 )
196 # load vertex normals into (n, 3) float64
197 normals = Rep.find("{*}VertexBuffer/{*}Normals")
198 mesh_normals.append(
199 np.fromstring(
200 normals.text.replace(",", " "), sep=" ", dtype=np.float64
201 ).reshape((-1, 3))
202 )
204 mesh_image = None
205 uv = Rep.find("{*}VertexBuffer/{*}TextureCoordinates")
206 if uv is None:
207 mesh_uv.append(None)
208 else: # texture coordinates are available
209 rep_uv = np.fromstring(
210 uv.text.replace(",", " "), sep=" ", dtype=np.float64
211 )
212 if "1D" == uv.get("dimension"):
213 mesh_uv.append(np.stack([rep_uv, np.zeros(len(rep_uv))], axis=1))
214 else: # 2D
215 mesh_uv.append(rep_uv.reshape(-1, 2))
217 material = Rep.find(
218 "{*}SurfaceAttributes/" + "{*}MaterialApplication/" + "{*}MaterialId"
219 )
220 if material is None:
221 material_id = None
222 else:
223 (material_file, material_id) = (
224 material.attrib["id"].split("urn:3DXML:")[-1].split("#")
225 )
226 if uv is not None:
227 mesh_image = images.get(material_id) # texture for this Rep, if any
228 rep_images.append(mesh_image)
230 for faces in Rep.iter("{*}Faces"):
231 triangles = [] # mesh triangles for this Faces element
232 for face in faces.iter("{*}Face"):
233 # Each Face may have optional strips, triangles or fans attributes
234 if "strips" in face.attrib:
235 # triangle strips, sequence of arbitrary length lists
236 # np.fromstring is substantially faster than np.array(i.split())
237 # inside the list comprehension
238 strips = [
239 np.fromstring(i, sep=" ", dtype=np.int64)
240 for i in face.attrib["strips"].split(",")
241 ]
242 # convert strips to (m, 3) int triangles
243 triangles.append(util.triangle_strips_to_faces(strips))
245 if "triangles" in face.attrib:
246 triangles.append(
247 np.fromstring(
248 face.attrib["triangles"], sep=" ", dtype=np.int64
249 ).reshape((-1, 3))
250 )
252 if "fans" in face.attrib:
253 fans = [
254 np.fromstring(i, sep=" ", dtype=np.int64)
255 for i in face.attrib["fans"].split(",")
256 ]
257 # convert fans to (m, 3) int triangles
258 triangles.append(util.triangle_fans_to_faces(fans))
260 rep_faces.extend(triangles)
261 count = sum(len(t) for t in triangles)
263 # store the material information as (m, 3) uint8 FACE COLORS
264 faceColor = colors.get(material_id, [128, 128, 128])
265 # each Face may have its own color
266 colorElement = face.find("{*}SurfaceAttributes/{*}Color")
267 if colorElement is not None:
268 faceColor = get_rgba(colorElement)[:3]
269 rep_colors.append(np.tile(faceColor, (count, 1)))
270 # stack the (m, 3) chunks of this Rep into one array each
271 mesh_faces.append(
272 util.vstack_empty(rep_faces).reshape((-1, 3)).astype(np.int64, copy=False)
273 )
274 mesh_colors.append(
275 util.vstack_empty(rep_colors).reshape((-1, 3)).astype(np.uint8)
276 )
278 # save each mesh as the kwargs for a trimesh.Trimesh constructor
279 # aka, a Trimesh object can be created with trimesh.Trimesh(**mesh)
280 # this avoids needing trimesh- specific imports in this IO function
281 mesh = {}
282 # how far outside 0.0-1.0 a UV may be, as a fraction of the image,
283 # and still be clipped into an atlas: exporters leave edges a hair
284 # outside (SolidWorks wrote -0.003), while a tiled texture is far outside
285 uv_tolerance = 1e-2
286 # a Rep is textured when it carries both UVs and an image
287 textured = [
288 uv is not None and image is not None for uv, image in zip(mesh_uv, rep_images)
289 ]
290 if textured and all(textured) and all(i is rep_images[0] for i in rep_images):
291 # every Rep shares one image: use the UVs as they are,
292 # which keeps any tiling (UVs outside 0.0-1.0) intact
293 mesh["visual"] = TextureVisuals(uv=np.vstack(mesh_uv), image=rep_images[0])
294 elif any(textured) and all(
295 ((uv >= -uv_tolerance) & (uv <= 1.0 + uv_tolerance)).all()
296 for uv, is_textured in zip(mesh_uv, textured)
297 if is_textured
298 ):
299 # a part mixing images, or images and plain colors: bake the
300 # colors into UVs and pack everything into one atlas, which
301 # only works when no UV relies on wrapping
302 materials = []
303 uvs = []
304 for i, is_textured in enumerate(textured):
305 if is_textured:
306 materials.append(SimpleMaterial(image=rep_images[i]))
307 # pack wraps anything outside 0.0-1.0, which would
308 # move an edge a hair outside to the opposite side
309 uvs.append(np.clip(mesh_uv[i], 0.0, 1.0))
310 continue
311 # a vertex shared by faces of different colors cannot
312 # carry one color: give every face its own vertices and
313 # let the vertex merge after loading re-join the ones
314 # that share a position and a color
315 index = mesh_faces[i].reshape(-1)
316 mesh_vertices[i] = mesh_vertices[i][index]
317 mesh_normals[i] = mesh_normals[i][index]
318 mesh_faces[i] = np.arange(len(index)).reshape((-1, 3))
319 material, uv = color_to_uv(
320 vertex_colors=np.repeat(mesh_colors[i], 3, axis=0)
321 )
322 materials.append(material)
323 uvs.append(uv)
324 material, uv = pack(materials=materials, uvs=uvs)
325 mesh["visual"] = TextureVisuals(uv=uv, material=material)
326 else:
327 # no texture, or one that tiles across a part that has other
328 # images or plain faces: the UVs do not cover every vertex
329 # and cannot share an atlas, so keep the per-face colors
330 mesh["face_colors"] = np.vstack(mesh_colors)
331 (mesh["vertices"], mesh["faces"]) = util.append_faces(mesh_vertices, mesh_faces)
332 mesh["vertex_normals"] = np.vstack(mesh_normals)
334 # as far as I can tell, all 3DXML files are exported as
335 # implicit millimeters (it isn't specified in the file)
336 mesh["metadata"] = {"units": "mm"}
337 mesh["class"] = "Trimesh"
339 geometries[part_id] = mesh
340 references[part_id]["geometry"] = part_id
342 # a Reference3D maps to a subassembly or assembly
343 for Reference3D in tree.iter("{*}Reference3D"):
344 references[Reference3D.attrib["id"]] = {
345 "name": Reference3D.attrib["name"],
346 "type": "Reference3D",
347 }
349 # a node that is the connectivity between a geometry and the Reference3D
350 for InstanceRep in tree.iter("{*}InstanceRep"):
351 current = InstanceRep.attrib["id"]
352 instance = InstanceRep.find("{*}IsInstanceOf").text
353 aggregate = InstanceRep.find("{*}IsAggregatedBy").text
355 references[current].update(
356 {"aggregate": aggregate, "instance": instance, "type": "InstanceRep"}
357 )
359 # an Instance3D maps basically to a part
360 for Instance3D in tree.iter("{*}Instance3D"):
361 matrix = np.eye(4)
362 relative = Instance3D.find("{*}RelativeMatrix")
363 if relative is not None:
364 relative = np.array(relative.text.split(), dtype=np.float64)
366 # rotation component
367 matrix[:3, :3] = relative[:9].reshape((3, 3)).T
368 # translation component
369 matrix[:3, 3] = relative[9:]
371 current = Instance3D.attrib["id"]
372 name = Instance3D.attrib["name"]
373 instance = Instance3D.find("{*}IsInstanceOf").text
374 aggregate = Instance3D.find("{*}IsAggregatedBy").text
376 references[current].update(
377 {
378 "aggregate": aggregate,
379 "instance": instance,
380 "matrix": matrix,
381 "name": name,
382 "type": "Instance3D",
383 }
384 )
386 # turn references into directed graph for path finding
387 graph = nx.DiGraph()
388 for k, v in references.items():
389 # IsAggregatedBy points up to a parent
390 if "aggregate" in v:
391 graph.add_edge(v["aggregate"], k)
392 # IsInstanceOf indicates a child
393 if "instance" in v:
394 graph.add_edge(k, v["instance"])
396 # the 3DXML format is stored as a directed acyclic graph that needs all
397 # paths from the root to a geometry to generate the tree of the scene
398 paths = []
399 for geometry_id in geometries.keys():
400 paths.extend(nx.all_simple_paths(graph, source=root_id, target=geometry_id))
402 # the name of the root frame
403 root_name = references[root_id]["name"]
404 # create a list of kwargs to send to the scene.graph.update function
405 # start with a transform from the graphs base frame to our root name
407 graph_kwargs = [{"frame_to": root_name, "matrix": np.eye(4)}]
409 # we are going to collect prettier geometry names as we traverse paths
410 geom_names = {}
411 # loop through every simple path and generate transforms tree
412 # note that we are flattening the transform tree here
413 for path in paths:
414 name = ""
415 if "name" in references[path[-3]]:
416 name = references[path[-3]]["name"]
417 geom_names[path[-1]] = name
418 # we need a unique node name for our geometry instance frame
419 # due to the nature of the DAG names specified by the file may not
420 # be unique, so we add an Instance3D name then append the path ids
421 node_name = name + "#" + ":".join(path)
423 # pull all transformations in the path
424 matrices = [references[i]["matrix"] for i in path if "matrix" in references[i]]
425 if len(matrices) == 0:
426 matrix = np.eye(4)
427 elif len(matrices) == 1:
428 matrix = matrices[0]
429 else:
430 matrix = util.multi_dot(matrices)
432 graph_kwargs.append(
433 {
434 "matrix": matrix,
435 "frame_from": root_name,
436 "frame_to": node_name,
437 "geometry": path[-1],
438 }
439 )
441 # remap geometry names from id numbers to the name string
442 # we extracted from the 3DXML tree
443 geom_final = {}
444 for key, value in geometries.items():
445 if key in geom_names:
446 geom_final[geom_names[key]] = value
447 # change geometry names in graph kwargs in place
448 for kwarg in graph_kwargs:
449 if "geometry" not in kwarg:
450 continue
451 kwarg["geometry"] = geom_names[kwarg["geometry"]]
453 # create the kwargs for load_kwargs
454 result = {"class": "Scene", "geometry": geom_final, "graph": graph_kwargs}
456 return result
459def print_element(element):
460 """
461 Pretty-print an lxml.etree element.
463 Parameters
464 ------------
465 element : etree element
466 """
467 pretty = etree.tostring(element, pretty_print=True).decode("utf-8")
468 return pretty
471try:
472 # soft dependencies
473 import networkx as nx
474 from lxml import etree
476 from .common import XML_PARSER_OPTIONS
478 _threedxml_loaders = {"3dxml": load_3DXML}
479except BaseException as E:
480 # set loader to exception wrapper
481 from ..exceptions import ExceptionWrapper
483 _threedxml_loaders = {"3dxml": ExceptionWrapper(E)}