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

1""" 

2threedxml.py 

3------------- 

4 

5Load 3DXML files, a scene format from Dassault products like Solidworks, Abaqus, Catia 

6""" 

7 

8import numpy as np 

9 

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 

18 

19 Image = ExceptionWrapper(E) 

20 

21import collections 

22import json 

23 

24from .. import util 

25from ..visual.color import color_to_uv 

26from ..visual.material import SimpleMaterial, pack 

27from ..visual.texture import TextureVisuals 

28 

29 

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 

34 

35 Parameters 

36 ------------ 

37 file_obj : file object 

38 Open and containing 3DXML data 

39 

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") 

46 

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) 

59 

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"] 

66 

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]) 

97 

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) 

105 

106 # references which hold the 3DXML scene structure as a dict 

107 # element id : {key : value} 

108 references = collections.defaultdict(dict) 

109 

110 def get_rgba(color): 

111 """ 

112 Return (4,) uint8 color array defined by Color element attributes. 

113 

114 Parameters 

115 ----------- 

116 color : lxml.Element 

117 Element containing RGBA colors. 

118 

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) 

132 

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 

146 

147 # geometries will hold meshes 

148 geometries = {} 

149 

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 

163 

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 = [] 

172 

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 

178 

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 

186 

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 ) 

195 

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 ) 

203 

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)) 

216 

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) 

229 

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)) 

244 

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 ) 

251 

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)) 

259 

260 rep_faces.extend(triangles) 

261 count = sum(len(t) for t in triangles) 

262 

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 ) 

277 

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) 

333 

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" 

338 

339 geometries[part_id] = mesh 

340 references[part_id]["geometry"] = part_id 

341 

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 } 

348 

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 

354 

355 references[current].update( 

356 {"aggregate": aggregate, "instance": instance, "type": "InstanceRep"} 

357 ) 

358 

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) 

365 

366 # rotation component 

367 matrix[:3, :3] = relative[:9].reshape((3, 3)).T 

368 # translation component 

369 matrix[:3, 3] = relative[9:] 

370 

371 current = Instance3D.attrib["id"] 

372 name = Instance3D.attrib["name"] 

373 instance = Instance3D.find("{*}IsInstanceOf").text 

374 aggregate = Instance3D.find("{*}IsAggregatedBy").text 

375 

376 references[current].update( 

377 { 

378 "aggregate": aggregate, 

379 "instance": instance, 

380 "matrix": matrix, 

381 "name": name, 

382 "type": "Instance3D", 

383 } 

384 ) 

385 

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"]) 

395 

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)) 

401 

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 

406 

407 graph_kwargs = [{"frame_to": root_name, "matrix": np.eye(4)}] 

408 

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) 

422 

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) 

431 

432 graph_kwargs.append( 

433 { 

434 "matrix": matrix, 

435 "frame_from": root_name, 

436 "frame_to": node_name, 

437 "geometry": path[-1], 

438 } 

439 ) 

440 

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"]] 

452 

453 # create the kwargs for load_kwargs 

454 result = {"class": "Scene", "geometry": geom_final, "graph": graph_kwargs} 

455 

456 return result 

457 

458 

459def print_element(element): 

460 """ 

461 Pretty-print an lxml.etree element. 

462 

463 Parameters 

464 ------------ 

465 element : etree element 

466 """ 

467 pretty = etree.tostring(element, pretty_print=True).decode("utf-8") 

468 return pretty 

469 

470 

471try: 

472 # soft dependencies 

473 import networkx as nx 

474 from lxml import etree 

475 

476 from .common import XML_PARSER_OPTIONS 

477 

478 _threedxml_loaders = {"3dxml": load_3DXML} 

479except BaseException as E: 

480 # set loader to exception wrapper 

481 from ..exceptions import ExceptionWrapper 

482 

483 _threedxml_loaders = {"3dxml": ExceptionWrapper(E)}