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

1import io 

2import uuid 

3import zipfile 

4from collections import defaultdict 

5 

6import numpy as np 

7 

8from .. import graph, util 

9from ..constants import log 

10from ..util import unique_name 

11 

12 

13def _read_mesh(mesh): 

14 """ 

15 Read a `<mesh ` XML element into Numpy vertices and faces. 

16 

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. 

19 

20 Parameters 

21 ---------- 

22 mesh : lxml.etree.Element 

23 Input mesh element with `vertex` and `triangle` children. 

24 

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

35 

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

48 

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

57 

58 return v_array, f_array 

59 

60 

61def load_3MF(file_obj, postprocess=True, **kwargs): 

62 """ 

63 Load a 3MF formatted file into a Trimesh scene. 

64 

65 Parameters 

66 ------------ 

67 file_obj : file-like 

68 Contains 3MF formatted data 

69 

70 Returns 

71 ------------ 

72 kwargs : dict 

73 Constructor arguments for `trimesh.Scene` 

74 """ 

75 

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

80 

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

91 

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

104 

105 # keep track of names we can use 

106 consumed_counts = {} 

107 consumed_names = set() 

108 

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

119 

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 

129 

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) 

135 

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

141 

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 

157 

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) 

167 

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

177 

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

191 

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) 

205 

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) 

220 

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 

227 

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] 

234 

235 # make the name unique 

236 name = unique_name(name, used_names) 

237 used_names.add(name) 

238 

239 # index in meshes 

240 geom = id_name[last] 

241 

242 # collect parents if we want to combine later 

243 if len(path) > 2: 

244 parent = path[-2][0] 

245 parents[parent].add(last) 

246 

247 graph_args.append( 

248 { 

249 "frame_from": "world", 

250 "frame_to": name, 

251 "matrix": transform, 

252 "geometry": geom, 

253 } 

254 ) 

255 

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] 

268 

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

275 

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 } 

283 

284 return kwargs 

285 

286 

287def export_3MF(mesh, batch_size=4096, compression=zipfile.ZIP_DEFLATED, compresslevel=5): 

288 """ 

289 Converts a Trimesh object into a 3MF file. 

290 

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. 

301 

302 Returns 

303 --------- 

304 export : bytes 

305 Represents geometry as a 3MF file. 

306 """ 

307 

308 from ..scene.scene import Scene 

309 

310 if not isinstance(mesh, Scene): 

311 mesh = Scene(mesh) 

312 

313 geometry = mesh.geometry 

314 graph = mesh.graph.to_networkx() 

315 base_frame = mesh.graph.base_frame 

316 

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 } 

326 

327 rels_nsmap = {None: "http://schemas.openxmlformats.org/package/2006/relationships"} 

328 

329 # model ids 

330 models = [] 

331 

332 def model_id(x): 

333 if x not in models: 

334 models.append(x) 

335 return str(models.index(x) + 1) 

336 

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

343 

344 # 3mf archive dict {path: BytesIO} 

345 file_obj = io.BytesIO() 

346 

347 # specify the parameters for the zip container 

348 zip_kwargs = {"compression": compression, "compresslevel": compresslevel} 

349 

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

357 

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 ) 

400 

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 

407 

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 ) 

441 

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 ) 

463 

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 ) 

478 

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

487 

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

503 

504 return file_obj.getvalue() 

505 

506 

507def _attrib_to_transform(attrib): 

508 """ 

509 Extract a homogeneous transform from a dictionary. 

510 

511 Parameters 

512 ------------ 

513 attrib: dict, optionally containing 'transform' 

514 

515 Returns 

516 ------------ 

517 transform: (4, 4) float, homogeonous transformation 

518 """ 

519 

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 

526 

527 

528# do import here to keep lxml a soft dependency 

529try: 

530 import networkx as nx 

531 from lxml import etree 

532 

533 from .common import XML_PARSER_OPTIONS 

534 

535 _three_loaders = {"3mf": load_3MF} 

536 _3mf_exporters = {"3mf": export_3MF} 

537except BaseException as E: 

538 from ..exceptions import ExceptionWrapper 

539 

540 _three_loaders = {"3mf": ExceptionWrapper(E)} 

541 _3mf_exporters = {"3mf": ExceptionWrapper(E)}