Coverage for trimesh/util.py: 88%

781 statements  

« prev     ^ index     » next       coverage.py v7.17.0, created at 2026-11-12 17:18 +0000

1""" 

2Grab bag of utility functions. 

3""" 

4 

5import abc 

6import base64 

7import collections 

8import json 

9import logging 

10import random 

11import shutil 

12import time 

13import uuid 

14import warnings 

15import zipfile 

16from collections.abc import ( 

17 Callable, 

18 Collection, 

19 Hashable, 

20 Iterator, 

21 Mapping, 

22 MutableMapping, 

23 MutableSet, 

24 Sequence, 

25) 

26from copy import deepcopy 

27from dataclasses import asdict as dataclass_to_dict 

28from io import BytesIO, StringIO 

29from typing import TYPE_CHECKING 

30 

31import numpy as np 

32 

33from .iteration import chain 

34 

35# use our wrapped types for wider version compatibility 

36from .typed import ( 

37 Any, 

38 ArrayLike, 

39 BoolIsFile, 

40 Floating, 

41 Integer, 

42 Iterable, 

43 NDArray, 

44 NDArray1D, 

45 NDArray2D, 

46 Number, 

47 Seed, 

48 Stream, 

49) 

50 

51# imported only so type checkers can resolve the dotted forward-ref 

52# string return below — never imported at runtime, and beartype 

53# re-imports the dotted path itself when the function is first called 

54if TYPE_CHECKING: 

55 import trimesh.parent 

56 

57# create a default logger 

58log: logging.Logger = logging.getLogger(__name__) 

59 

60ABC = abc.ABC 

61now = time.time 

62which = shutil.which 

63 

64# include constants here so we don't have to import 

65# a floating point threshold for 0.0 

66# we are setting it to 100x the resolution of a float64 

67# which works out to be 1e-13 

68TOL_ZERO: float = float(np.finfo(np.float64).resolution * 100) 

69# how close to merge vertices 

70TOL_MERGE: float = 1e-8 

71# enable additional potentially slow checks 

72_STRICT: bool = False 

73 

74# beartype is unable to resolve `NDArray[float64]` for globals 

75_IDENTITY: np.ndarray = np.eye(4, dtype=np.float64) 

76_IDENTITY.flags["WRITEABLE"] = False 

77 

78# one process-wide generator for the unseeded case: constructing one 

79# collects OS entropy which costs ~200x more than the draw it feeds 

80_RANDOM_DEFAULT = np.random.default_rng() 

81 

82 

83def random_generator(seed: Seed = None) -> np.random.Generator: 

84 """ 

85 Get a random generator, optionally seeded for deterministic results. 

86 

87 Parameters 

88 ---------- 

89 seed 

90 If None use a shared generator seeded from OS entropy. An integer 

91 seeds a fresh generator. A `Generator` is returned unaltered which 

92 lets a caller thread one stream through nested calls rather than 

93 re-seeding each of them to identical values. 

94 

95 Returns 

96 ------- 

97 generator 

98 Draw random values from this. 

99 """ 

100 if seed is None: 

101 # numpy locks the bit generator on every draw so sharing 

102 # this between threads is as safe as `numpy.random.random` 

103 return _RANDOM_DEFAULT 

104 return np.random.default_rng(seed) 

105 

106 

107def has_module(name: str) -> bool: 

108 """ 

109 Check to see if a module is installed by name without 

110 actually importing the module. 

111 

112 Parameters 

113 ------------ 

114 name : str 

115 The name of the module to check 

116 

117 Returns 

118 ------------ 

119 installed : bool 

120 True if module is installed 

121 """ 

122 from importlib.util import find_spec 

123 

124 return find_spec(name) is not None 

125 

126 

127def unitize( 

128 vectors: ArrayLike, 

129 check_valid: bool = False, 

130 threshold: Number | None = None, 

131): 

132 """ 

133 Unitize a vector or an array or row-vectors. 

134 

135 Parameters 

136 ------------ 

137 vectors : (n,m) or (j) float 

138 Vector or vectors to be unitized 

139 check_valid : bool 

140 If set, will return mask of nonzero vectors 

141 threshold : float 

142 Cutoff for a value to be considered zero. 

143 

144 Returns 

145 --------- 

146 unit : (n,m) or (j) float 

147 Input vectors but unitized 

148 valid : (n,) bool or bool 

149 Mask of nonzero vectors returned if `check_valid` 

150 """ 

151 # make sure we have a numpy array 

152 vectors = np.asanyarray(vectors) 

153 

154 # allow user to set zero threshold 

155 if threshold is None: 

156 threshold = TOL_ZERO 

157 

158 if len(vectors.shape) == 2: 

159 # for (m, d) arrays take the per-row unit vector 

160 # using sqrt and avoiding exponents is slightly faster 

161 # also dot with ones is faser than .sum(axis=1) 

162 norm = np.sqrt(np.dot(vectors * vectors, [1.0] * vectors.shape[1])) 

163 # non-zero norms 

164 valid = norm > threshold 

165 # in-place reciprocal of nonzero norms 

166 norm[valid] **= -1 

167 # multiply by reciprocal of norm 

168 unit = vectors * norm.reshape((-1, 1)) 

169 

170 elif len(vectors.shape) == 1: 

171 # treat 1D arrays as a single vector 

172 norm = np.sqrt(np.dot(vectors, vectors)) 

173 valid = norm > threshold 

174 if valid: 

175 unit = vectors / norm 

176 else: 

177 unit = vectors.copy() 

178 else: 

179 raise ValueError("vectors must be (n, ) or (n, d)!") 

180 

181 if check_valid: 

182 return unit[valid], valid 

183 return unit 

184 

185 

186def euclidean(a: ArrayLike, b: ArrayLike) -> np.float64: 

187 """ 

188 DEPRECATED: use `np.linalg.norm(a - b)` instead of this. 

189 """ 

190 warnings.warn( 

191 "`trimesh.util.euclidean` is deprecated " 

192 + "and will be removed in January 2025. " 

193 + "replace with `np.linalg.norm(a - b)`", 

194 category=DeprecationWarning, 

195 stacklevel=2, 

196 ) 

197 

198 a = np.asanyarray(a, dtype=np.float64) 

199 b = np.asanyarray(b, dtype=np.float64) 

200 return np.sqrt(((a - b) ** 2).sum()) 

201 

202 

203def is_file(obj: Any) -> BoolIsFile: 

204 """ 

205 Check if an object is file-like 

206 

207 Parameters 

208 ------------ 

209 obj : object 

210 Any object type to be checked 

211 

212 Returns 

213 ----------- 

214 is_file : bool 

215 True if object is a file 

216 """ 

217 return hasattr(obj, "read") or hasattr(obj, "write") 

218 

219 

220def is_pathlib(obj: object) -> bool: 

221 """ 

222 Check if the object is a `pathlib.Path` or subclass. 

223 

224 Parameters 

225 ------------ 

226 obj : object 

227 Object to be checked 

228 

229 Returns 

230 ------------ 

231 is_pathlib : bool 

232 Is the input object a pathlib path 

233 """ 

234 # check class name rather than a pathlib import 

235 name = obj.__class__.__name__ 

236 return hasattr(obj, "absolute") and name.endswith("Path") 

237 

238 

239def is_string(obj: object) -> bool: 

240 """ 

241 DEPRECATED : this is not necessary since we dropped Python 2. 

242 

243 Replace with `isinstance(obj, str)` 

244 """ 

245 warnings.warn( 

246 "`trimesh.util.is_string` is deprecated " 

247 + "and will be removed in January 2025. " 

248 + "replace with `isinstance(obj, str)`", 

249 category=DeprecationWarning, 

250 stacklevel=2, 

251 ) 

252 

253 return isinstance(obj, str) 

254 

255 

256def is_sequence(obj: Any) -> bool: 

257 """ 

258 Check if an object is a sequence or not. 

259 

260 Parameters 

261 ------------- 

262 obj : object 

263 Any object type to be checked 

264 

265 Returns 

266 ------------- 

267 is_sequence : bool 

268 True if object is sequence 

269 """ 

270 seq = (not hasattr(obj, "strip") and hasattr(obj, "__getitem__")) or hasattr( 

271 obj, "__iter__" 

272 ) 

273 

274 # check to make sure it is not a set, string, or dictionary 

275 seq = seq and all(not isinstance(obj, i) for i in (dict, set, str)) 

276 

277 # PointCloud objects can look like an array but are not 

278 seq = seq and type(obj).__name__ not in ["PointCloud"] 

279 

280 # numpy sometimes returns objects that are single float64 values 

281 # but sure look like sequences, so we check the shape 

282 if hasattr(obj, "shape"): 

283 seq = seq and obj.shape != () 

284 

285 return seq 

286 

287 

288def is_shape( 

289 obj: NDArray | Any, 

290 shape: Sequence[int | tuple[int, ...]], 

291 allow_zeros: bool = False, 

292) -> bool: 

293 """ 

294 Compare the shape of a numpy.ndarray to a target shape, 

295 with any value less than zero being considered a wildcard 

296 

297 Note that if a list-like object is passed that is not a numpy 

298 array, this function will not convert it and will return False. 

299 

300 Parameters 

301 ------------ 

302 obj : np.ndarray 

303 Array to check the shape on 

304 shape : list or tuple 

305 Any negative term will be considered a wildcard 

306 Any tuple term will be evaluated as an OR 

307 allow_zeros: bool 

308 if False, zeros do not match negatives in shape 

309 

310 Returns 

311 --------- 

312 shape_ok : bool 

313 True if shape of obj matches query shape 

314 

315 Examples 

316 ------------------------ 

317 In [1]: a = np.random.random((100, 3)) 

318 

319 In [2]: a.shape 

320 Out[2]: (100, 3) 

321 

322 In [3]: trimesh.util.is_shape(a, (-1, 3)) 

323 Out[3]: True 

324 

325 In [4]: trimesh.util.is_shape(a, (-1, 3, 5)) 

326 Out[4]: False 

327 

328 In [5]: trimesh.util.is_shape(a, (100, -1)) 

329 Out[5]: True 

330 

331 In [6]: trimesh.util.is_shape(a, (-1, (3, 4))) 

332 Out[6]: True 

333 

334 In [7]: trimesh.util.is_shape(a, (-1, (4, 5))) 

335 Out[7]: False 

336 """ 

337 

338 # if the obj.shape is different length than 

339 # the goal shape it means they have different number 

340 # of dimensions and thus the obj is not the query shape 

341 if not hasattr(obj, "shape") or len(obj.shape) != len(shape): 

342 return False 

343 

344 # empty lists with any flexible dimensions match 

345 if len(obj) == 0 and -1 in shape: 

346 return True 

347 

348 # loop through each integer of the two shapes 

349 # multiple values are sequences 

350 # wildcards are less than zero (i.e. -1) 

351 for i, target in zip(obj.shape, shape): 

352 # check if current field has multiple acceptable values 

353 # an explicit tuple/list check narrows `target` for type 

354 # checkers — `is_sequence` is not a type guard 

355 if isinstance(target, (list, tuple)): 

356 if i in target: 

357 # obj shape is in the accepted values 

358 continue 

359 else: 

360 return False 

361 

362 # check if current field is a wildcard 

363 if int(target) < 0: 

364 if i == 0 and not allow_zeros: 

365 # if a dimension is 0, we don't allow 

366 # that to match to a wildcard 

367 # it would have to be explicitly called out as 0 

368 return False 

369 else: 

370 continue 

371 # since we have a single target and a single value, 

372 # if they are not equal we have an answer 

373 if target != i: 

374 return False 

375 

376 # since none of the checks failed the obj.shape 

377 # matches the pattern 

378 return True 

379 

380 

381def make_sequence(obj: Any) -> list: 

382 """ 

383 Given an object, if it is a sequence return, otherwise 

384 add it to a length 1 sequence and return. 

385 

386 Useful for wrapping functions which sometimes return single 

387 objects and other times return lists of objects. 

388 

389 Parameters 

390 ------------- 

391 obj : object 

392 An object to be made a sequence 

393 

394 Returns 

395 -------------- 

396 as_sequence : (n,) sequence 

397 Contains input value 

398 """ 

399 if is_sequence(obj): 

400 return list(obj) 

401 else: 

402 return [obj] 

403 

404 

405def vector_hemisphere( 

406 vectors: ArrayLike, 

407 return_sign: bool = False, 

408): 

409 """ 

410 For a set of 3D vectors alter the sign so they are all in the 

411 upper hemisphere. 

412 

413 If the vector lies on the plane all vectors with negative Y 

414 will be reversed. 

415 

416 If the vector has a zero Z and Y value vectors with a 

417 negative X value will be reversed. 

418 

419 Parameters 

420 ------------ 

421 vectors : (n, 3) float 

422 Input vectors 

423 return_sign : bool 

424 Return the sign mask or not 

425 

426 Returns 

427 ---------- 

428 oriented: (n, 3) float 

429 Vectors with same magnitude as source 

430 but possibly reversed to ensure all vectors 

431 are in the same hemisphere. 

432 sign : (n,) float 

433 [OPTIONAL] sign of original vectors 

434 """ 

435 # vectors as numpy array 

436 vectors = np.asanyarray(vectors, dtype=np.float64) 

437 

438 if is_shape(vectors, (-1, 2)): 

439 # 2D vector case 

440 # check the Y value and reverse vector 

441 # direction if negative. 

442 negative = vectors < -TOL_ZERO 

443 zero = np.logical_not(np.logical_or(negative, vectors > TOL_ZERO)) 

444 

445 signs = np.ones(len(vectors), dtype=np.float64) 

446 # negative Y values are reversed 

447 signs[negative[:, 1]] = -1.0 

448 

449 # zero Y and negative X are reversed 

450 signs[np.logical_and(zero[:, 1], negative[:, 0])] = -1.0 

451 

452 elif is_shape(vectors, (-1, 3)): 

453 # 3D vector case 

454 negative = vectors < -TOL_ZERO 

455 zero = np.logical_not(np.logical_or(negative, vectors > TOL_ZERO)) 

456 # move all negative Z to positive 

457 # then for zero Z vectors, move all negative Y to positive 

458 # then for zero Y vectors, move all negative X to positive 

459 signs = np.ones(len(vectors), dtype=np.float64) 

460 # all vectors with negative Z values 

461 signs[negative[:, 2]] = -1.0 

462 # all on-plane vectors with negative Y values 

463 signs[np.logical_and(zero[:, 2], negative[:, 1])] = -1.0 

464 # all on-plane vectors with zero Y values 

465 # and negative X values 

466 signs[ 

467 np.logical_and(np.logical_and(zero[:, 2], zero[:, 1]), negative[:, 0]) 

468 ] = -1.0 

469 

470 else: 

471 raise ValueError("vectors must be (n, 3)!") 

472 

473 # apply the signs to the vectors 

474 oriented = vectors * signs.reshape((-1, 1)) 

475 

476 if return_sign: 

477 return oriented, signs 

478 

479 return oriented 

480 

481 

482def vector_to_spherical(cartesian: ArrayLike) -> NDArray2D[np.float64]: 

483 """ 

484 Convert a set of cartesian points to (n, 2) spherical unit 

485 vectors. 

486 

487 Parameters 

488 ------------ 

489 cartesian : (n, 3) float 

490 Points in space 

491 

492 Returns 

493 ------------ 

494 spherical : (n, 2) float 

495 Angles, in radians 

496 """ 

497 cartesian = np.asanyarray(cartesian, dtype=np.float64) 

498 if not is_shape(cartesian, (-1, 3)): 

499 raise ValueError("Cartesian points must be (n, 3)!") 

500 

501 unit, valid = unitize(cartesian, check_valid=True) 

502 unit[np.abs(unit) < TOL_MERGE] = 0.0 

503 

504 x, y, z = unit.T 

505 spherical = np.zeros((len(cartesian), 2), dtype=np.float64) 

506 spherical[valid] = np.column_stack((np.arctan2(y, x), np.arccos(z))) 

507 return spherical 

508 

509 

510def spherical_to_vector(spherical: ArrayLike) -> NDArray2D[np.float64]: 

511 """ 

512 Convert an array of `(n, 2)` spherical angles to `(n, 3)` unit vectors. 

513 

514 Parameters 

515 ------------ 

516 spherical : (n , 2) float 

517 Angles, in radians 

518 

519 Returns 

520 ----------- 

521 vectors : (n, 3) float 

522 Unit vectors 

523 """ 

524 spherical = np.asanyarray(spherical, dtype=np.float64) 

525 if not is_shape(spherical, (-1, 2)): 

526 raise ValueError("spherical coordinates must be (n, 2)!") 

527 

528 theta, phi = spherical.T 

529 st, ct = np.sin(theta), np.cos(theta) 

530 sp, cp = np.sin(phi), np.cos(phi) 

531 return np.column_stack((ct * sp, st * sp, cp)) 

532 

533 

534def pairwise(iterable: Iterable[Any]): 

535 """ 

536 For an iterable, group values into pairs. 

537 

538 Parameters 

539 ------------ 

540 iterable : (m, ) list 

541 A sequence of values 

542 

543 Returns 

544 ----------- 

545 pairs: (n, 2) 

546 Pairs of sequential values 

547 

548 Example 

549 ----------- 

550 In [1]: data 

551 Out[1]: [0, 1, 2, 3, 4, 5, 6] 

552 

553 In [2]: list(trimesh.util.pairwise(data)) 

554 Out[2]: [(0, 1), (1, 2), (2, 3), (3, 4), (4, 5), (5, 6)] 

555 

556 """ 

557 # looping through a giant numpy array would be dumb 

558 # so special case ndarrays and use numpy operations 

559 if isinstance(iterable, np.ndarray): 

560 iterable = iterable.reshape(-1) 

561 stacked = np.column_stack((iterable, iterable)) 

562 pairs = stacked.reshape(-1)[1:-1].reshape((-1, 2)) 

563 return pairs 

564 

565 # if we have a normal iterable use itertools 

566 import itertools 

567 

568 a, b = itertools.tee(iterable) 

569 # pop the first element of the second item 

570 next(b) 

571 

572 return zip(a, b) 

573 

574 

575multi_dot = np.linalg.multi_dot 

576 

577 

578def diagonal_dot(a: ArrayLike, b: ArrayLike) -> np.ndarray[tuple[int], np.dtype[Any]]: 

579 """ 

580 Dot product by row of a and b. 

581 

582 There are a lot of ways to do this though 

583 performance varies very widely. This method 

584 uses a dot product to sum the row and avoids 

585 function calls if at all possible. 

586 

587 Comparing performance of some equivalent versions: 

588 ``` 

589 In [1]: import numpy as np; import trimesh 

590 

591 In [2]: a = np.random.random((10000, 3)) 

592 

593 In [3]: b = np.random.random((10000, 3)) 

594 

595 In [4]: %timeit (a * b).sum(axis=1) 

596 1000 loops, best of 3: 181 us per loop 

597 

598 In [5]: %timeit np.einsum('ij,ij->i', a, b) 

599 10000 loops, best of 3: 62.7 us per loop 

600 

601 In [6]: %timeit np.diag(np.dot(a, b.T)) 

602 1 loop, best of 3: 429 ms per loop 

603 

604 In [7]: %timeit np.dot(a * b, np.ones(a.shape[1])) 

605 10000 loops, best of 3: 61.3 us per loop 

606 

607 In [8]: %timeit trimesh.util.diagonal_dot(a, b) 

608 10000 loops, best of 3: 55.2 us per loop 

609 ``` 

610 

611 Parameters 

612 ------------ 

613 a : (m, d) float 

614 First array 

615 b : (m, d) float 

616 Second array 

617 

618 Returns 

619 ------------- 

620 result : (m,) float 

621 Dot product of each row 

622 """ 

623 # make sure `a` is numpy array 

624 # doing it for `a` will force the multiplication to 

625 # convert `b` if necessary and avoid function call otherwise 

626 a = np.asanyarray(a) 

627 # 3x faster than (a * b).sum(axis=1) 

628 # avoiding np.ones saves 5-10% sometimes 

629 return np.dot(a * b, [1.0] * a.shape[1]) 

630 

631 

632def row_norm(data: NDArray2D[Any]) -> NDArray1D[np.float64]: 

633 """ 

634 Compute the norm per-row of a numpy array. 

635 

636 This is identical to np.linalg.norm(data, axis=1) but roughly 

637 three times faster due to being less general. 

638 

639 In [3]: %timeit trimesh.util.row_norm(a) 

640 76.3 us +/- 651 ns per loop 

641 

642 In [4]: %timeit np.linalg.norm(a, axis=1) 

643 220 us +/- 5.41 us per loop 

644 

645 Parameters 

646 ------------- 

647 data : (n, d) float 

648 Input 2D data to calculate per-row norm of 

649 

650 Returns 

651 ------------- 

652 norm : (n,) float 

653 Norm of each row of input array 

654 """ 

655 return np.sqrt(np.dot(data**2, [1] * data.shape[1])) 

656 

657 

658def stack_3D( 

659 points: ArrayLike, 

660 return_2D: bool = False, 

661) -> NDArray2D[np.float64] | tuple[NDArray2D[np.float64], bool]: 

662 """ 

663 For a list of (n, 2) or (n, 3) points return them 

664 as (n, 3) 3D points, 2D points on the XY plane. 

665 

666 Parameters 

667 ------------ 

668 points : (n, 2) or (n, 3) float 

669 Points in either 2D or 3D space 

670 return_2D : bool 

671 Were the original points 2D? 

672 

673 Returns 

674 ---------- 

675 points : (n, 3) float 

676 Points in space 

677 is_2D : bool 

678 [OPTIONAL] if source points were (n, 2) 

679 """ 

680 points = np.asanyarray(points, dtype=np.float64) 

681 shape = points.shape 

682 

683 if shape == (0,): 

684 is_2D = False 

685 elif len(shape) != 2: 

686 raise ValueError("Points must be 2D array!") 

687 elif shape[1] == 2: 

688 points = np.column_stack((points, np.zeros(len(points)))) 

689 is_2D = True 

690 elif shape[1] == 3: 

691 is_2D = False 

692 else: 

693 raise ValueError("Points must be (n, 2) or (n, 3)!") 

694 

695 if return_2D: 

696 return points, is_2D 

697 

698 return points 

699 

700 

701def grid_arange(bounds: ArrayLike, step: Number | ArrayLike) -> NDArray2D[np.float64]: 

702 """ 

703 Return a grid from an (2,dimension) bounds with samples step distance apart. 

704 

705 Parameters 

706 ------------ 

707 bounds: (2,dimension) list of [[min x, min y, etc], [max x, max y, etc]] 

708 step: float, or (dimension) floats, separation between points 

709 

710 Returns 

711 --------- 

712 grid: (n, dimension), points inside the specified bounds 

713 """ 

714 bounds = np.asanyarray(bounds, dtype=np.float64) 

715 if len(bounds) != 2: 

716 raise ValueError("bounds must be (2, dimension!") 

717 

718 # allow single float or per-dimension spacing 

719 step = np.asanyarray(step, dtype=np.float64) 

720 if step.shape == (): 

721 step = np.tile(step, bounds.shape[1]) 

722 

723 grid_elements = [np.arange(*b, step=s) for b, s in zip(bounds.T, step)] 

724 grid = ( 

725 np.vstack(np.meshgrid(*grid_elements, indexing="ij")) 

726 .reshape(bounds.shape[1], -1) 

727 .T 

728 ) 

729 return grid 

730 

731 

732def grid_linspace(bounds: ArrayLike, count: Integer | ArrayLike) -> NDArray2D[np.float64]: 

733 """ 

734 Return a grid spaced inside a bounding box with edges spaced using np.linspace. 

735 

736 Parameters 

737 ------------ 

738 bounds: (2,dimension) list of [[min x, min y, etc], [max x, max y, etc]] 

739 count: int, or (dimension,) int, number of samples per side 

740 

741 Returns 

742 --------- 

743 grid: (n, dimension) float, points in the specified bounds 

744 """ 

745 bounds = np.asanyarray(bounds, dtype=np.float64) 

746 if len(bounds) != 2: 

747 raise ValueError("bounds must be (2, dimension!") 

748 

749 count = np.asanyarray(count, dtype=np.int64) 

750 if count.shape == (): 

751 count = np.tile(count, bounds.shape[1]) 

752 

753 grid_elements = [np.linspace(*b, num=c) for b, c in zip(bounds.T, count)] 

754 grid = ( 

755 np.vstack(np.meshgrid(*grid_elements, indexing="ij")) 

756 .reshape(bounds.shape[1], -1) 

757 .T 

758 ) 

759 return grid 

760 

761 

762def multi_dict( 

763 pairs: ArrayLike | Iterable[tuple[Hashable, Any]], 

764) -> collections.defaultdict[Hashable, list]: 

765 """ 

766 Given a set of key value pairs, create a dictionary. 

767 If a key occurs multiple times, stack the values into an array. 

768 

769 Can be called like the regular dict(pairs) constructor 

770 

771 Parameters 

772 ------------ 

773 pairs: (n, 2) array of key, value pairs 

774 

775 Returns 

776 ---------- 

777 result: dict, with all values stored (rather than last with regular dict) 

778 

779 """ 

780 result = collections.defaultdict(list) 

781 for k, v in pairs: 

782 result[k].append(v) 

783 return result 

784 

785 

786def tolist(data: object) -> Any: 

787 """ 

788 Ensure that any arrays or dicts passed containing 

789 numpy arrays are properly converted to lists 

790 

791 Parameters 

792 ------------- 

793 data : any 

794 Usually a dict with some numpy arrays as values 

795 

796 Returns 

797 ---------- 

798 result : any 

799 JSON-serializable version of data 

800 """ 

801 result = json.loads(jsonify(data)) 

802 return result 

803 

804 

805def is_binary_file(file_obj: Stream) -> bool: 

806 """ 

807 Returns True if file has non-ASCII characters (> 0x7F, or 127) 

808 """ 

809 start = file_obj.tell() 

810 fbytes = file_obj.read(1024) 

811 file_obj.seek(start) 

812 is_str = isinstance(fbytes, str) 

813 for fbyte in fbytes: 

814 if is_str: 

815 code = ord(fbyte) 

816 else: 

817 code = fbyte 

818 if code > 127: 

819 return True 

820 return False 

821 

822 

823def distance_to_end(file_obj: Stream) -> int: 

824 """ 

825 For an open file object how far is it to the end 

826 

827 Parameters 

828 ------------ 

829 file_obj: open file-like object 

830 

831 Returns 

832 ---------- 

833 distance: int, bytes to end of file 

834 """ 

835 position_current = file_obj.tell() 

836 file_obj.seek(0, 2) 

837 position_end = file_obj.tell() 

838 file_obj.seek(position_current) 

839 distance = position_end - position_current 

840 return distance 

841 

842 

843def decimal_to_digits(decimal: Floating, min_digits: Integer | None = None) -> int: 

844 """ 

845 Return the number of digits to the first nonzero decimal. 

846 

847 Parameters 

848 ----------- 

849 decimal: float 

850 min_digits: int, minimum number of digits to return 

851 

852 Returns 

853 ----------- 

854 

855 digits: int, number of digits to the first nonzero decimal 

856 """ 

857 digits = abs(int(np.log10(decimal))) 

858 if min_digits is not None: 

859 digits = np.clip(digits, min_digits, 20) 

860 return int(digits) 

861 

862 

863def attach_to_log( 

864 level: Integer = logging.DEBUG, 

865 handler: logging.Handler | None = None, 

866 loggers: MutableSet[logging.Logger] | None = None, 

867 colors: bool = True, 

868 capture_warnings: bool = True, 

869 blacklist: Iterable[str] | None = None, 

870 only_parent: bool = True, 

871) -> None: 

872 """ 

873 Attach a stream handler to all loggers. 

874 

875 Parameters 

876 ------------ 

877 level : enum 

878 Logging level, like logging.INFO 

879 handler : None or logging.Handler 

880 Handler to attach 

881 loggers : None or (n,) logging.Logger 

882 If None, will try to attach to all available 

883 colors : bool 

884 If True try to use colorlog formatter 

885 blacklist : (n,) str 

886 Names of loggers NOT to attach to 

887 only_parent 

888 Only attach to parent loggers, i.e. `trimesh`, `trimesh.sub1`, `trimesh.sub2` 

889 will only attach to `trimesh` and not the sub-loggers 

890 """ 

891 

892 # default blacklist includes ipython debugging stuff 

893 if blacklist is None: 

894 blacklist = [ 

895 "TerminalIPythonApp", 

896 "PYREADLINE", 

897 "pyembree", 

898 "shapely", 

899 "matplotlib", 

900 "parso.cache", 

901 "parso", 

902 "parso.python.diff", 

903 "asyncio", 

904 "prompt_toolkit.buffer", 

905 ] 

906 

907 # make sure we log warnings from the warnings module 

908 logging.captureWarnings(capture_warnings) 

909 

910 # create a basic formatter 

911 formatter = logging.Formatter( 

912 "[%(asctime)s] %(levelname)-7s (%(filename)s:%(lineno)3s) %(message)s", 

913 "%Y-%m-%d %H:%M:%S", 

914 ) 

915 if colors: 

916 try: 

917 from colorlog import ColoredFormatter 

918 

919 formatter = ColoredFormatter( 

920 ( 

921 "%(log_color)s%(levelname)-8s%(reset)s " 

922 + "%(filename)17s:%(lineno)-4s %(blue)4s%(message)s" 

923 ), 

924 datefmt=None, 

925 reset=True, 

926 log_colors={ 

927 "DEBUG": "cyan", 

928 "INFO": "green", 

929 "WARNING": "yellow", 

930 "ERROR": "red", 

931 "CRITICAL": "red", 

932 }, 

933 ) 

934 except ImportError: 

935 pass 

936 

937 # if no handler was passed use a StreamHandler 

938 if handler is None: 

939 handler = logging.StreamHandler() 

940 

941 # add the formatters and set the level 

942 handler.setFormatter(formatter) 

943 # numpy integers aren't `int` subclasses — coerce for the stdlib stubs 

944 handler.setLevel(int(level)) 

945 

946 # if nothing passed use all available loggers 

947 if loggers is None: 

948 # de-duplicate loggers using a set 

949 loggers = set(logging.Logger.manager.loggerDict.values()) 

950 

951 # add the warnings logging 

952 loggers.add(logging.getLogger("py.warnings")) 

953 

954 # disable pyembree warnings 

955 logging.getLogger("pyembree").disabled = True 

956 

957 # cull loggers that are not actually loggers or are on the blacklist 

958 loggers_dict = { 

959 L.name: L 

960 for L in loggers 

961 if hasattr(L, "name") 

962 and isinstance(L, logging.Logger) 

963 and L.name not in blacklist 

964 } 

965 

966 if only_parent: 

967 # create a new dict to store only parent loggers 

968 parent_loggers = {} 

969 # sort logger names to process in hierarchical order 

970 for name in sorted(loggers_dict.keys()): 

971 # if it's not a child of any existing parent, add it as a parent 

972 if not any(name.startswith(f"{p}.") for p in parent_loggers.keys()): 

973 parent_loggers[name] = loggers_dict[name] 

974 # replace loggers dict with only parent loggers 

975 loggers_dict = parent_loggers 

976 

977 # loop through all available loggers 

978 for logger in loggers_dict.values(): 

979 logger.addHandler(handler) 

980 logger.setLevel(int(level)) 

981 

982 # set nicer numpy print options 

983 np.set_printoptions(precision=5, suppress=True) 

984 

985 

986def stack_lines(indices: ArrayLike) -> NDArray: 

987 """ 

988 Stack a list of values that represent a polyline into 

989 individual line segments with duplicated consecutive values. 

990 

991 Parameters 

992 ------------ 

993 indices : (m,) any 

994 List of items to be stacked 

995 

996 Returns 

997 --------- 

998 stacked : (n, 2) any 

999 Stacked items 

1000 

1001 Examples 

1002 ---------- 

1003 In [1]: trimesh.util.stack_lines([0, 1, 2]) 

1004 Out[1]: 

1005 array([[0, 1], 

1006 [1, 2]]) 

1007 

1008 In [2]: trimesh.util.stack_lines([0, 1, 2, 4, 5]) 

1009 Out[2]: 

1010 array([[0, 1], 

1011 [1, 2], 

1012 [2, 4], 

1013 [4, 5]]) 

1014 

1015 In [3]: trimesh.util.stack_lines([[0, 0], [1, 1], [2, 2], [3, 3]]) 

1016 Out[3]: 

1017 array([[0, 0], 

1018 [1, 1], 

1019 [1, 1], 

1020 [2, 2], 

1021 [2, 2], 

1022 [3, 3]]) 

1023 

1024 """ 

1025 indices = np.asanyarray(indices) 

1026 if len(indices) == 0: 

1027 return np.array([]) 

1028 elif is_sequence(indices[0]): 

1029 shape = (-1, len(indices[0])) 

1030 else: 

1031 shape = (-1, 2) 

1032 return np.column_stack((indices[:-1], indices[1:])).reshape(shape) 

1033 

1034 

1035def append_faces( 

1036 vertices_seq: Iterable[ArrayLike], 

1037 faces_seq: Iterable[ArrayLike], 

1038) -> tuple[NDArray2D[np.floating], NDArray2D[np.integer]]: 

1039 """ 

1040 Given a sequence of zero-indexed faces and vertices 

1041 combine them into a single array of faces and 

1042 a single array of vertices. 

1043 

1044 Parameters 

1045 ----------- 

1046 vertices_seq : (n, ) sequence of (m, d) float 

1047 Multiple arrays of verticesvertex arrays 

1048 faces_seq : (n, ) sequence of (p, j) int 

1049 Zero indexed faces for matching vertices 

1050 

1051 Returns 

1052 ---------- 

1053 vertices : (i, d) float 

1054 Points in space 

1055 faces : (j, 3) int 

1056 Reference vertex indices 

1057 """ 

1058 # the length of each vertex array 

1059 vertices_len = np.array([len(i) for i in vertices_seq], dtype=np.int64) 

1060 # how much each group of faces needs to be offset 

1061 face_offset = np.append(0, np.cumsum(vertices_len)[:-1]) 

1062 

1063 new_faces = [] 

1064 for offset, faces in zip(face_offset, faces_seq): 

1065 if len(faces) == 0: 

1066 continue 

1067 # apply the index offset 

1068 new_faces.append(faces + offset) 

1069 # stack to clean (n, 3) float 

1070 vertices = vstack_empty(vertices_seq) 

1071 # stack to clean (n, 3) int 

1072 faces = vstack_empty(new_faces) 

1073 

1074 # an all-empty stack collapses to a 1d float array — restore the 

1075 # documented 2d shape and integer face dtype 

1076 if len(vertices) == 0: 

1077 vertices = vertices.reshape((0, 3)) 

1078 if len(faces) == 0: 

1079 faces = faces.reshape((0, 3)).astype(np.int64) 

1080 

1081 return vertices, faces 

1082 

1083 

1084def array_to_string( 

1085 array: ArrayLike, 

1086 col_delim: str = " ", 

1087 row_delim: str = "\n", 

1088 digits: Integer = 8, 

1089 value_format: str = "{}", 

1090) -> str: 

1091 """ 

1092 Convert a 1 or 2D array into a string with a specified number 

1093 of digits and delimiter. The reason this exists is that the 

1094 basic numpy array to string conversions are surprisingly slow. 

1095 

1096 Parameters 

1097 ------------ 

1098 array : (n,) or (n, d) float or int 

1099 Data to be converted 

1100 If shape is (n,) only column delimiter will be used 

1101 col_delim : str 

1102 What string should separate values in a column 

1103 row_delim : str 

1104 What string should separate values in a row 

1105 digits : int 

1106 How many digits should floating point numbers include 

1107 value_format : str 

1108 Format string for each value or sequence of values 

1109 If multiple values per value_format it must divide 

1110 into array evenly. 

1111 

1112 Returns 

1113 ---------- 

1114 formatted : str 

1115 String representation of original array 

1116 """ 

1117 # convert inputs to correct types 

1118 array = np.asanyarray(array) 

1119 digits = int(digits) 

1120 row_delim = str(row_delim) 

1121 col_delim = str(col_delim) 

1122 value_format = str(value_format) 

1123 

1124 # abort for non-flat arrays 

1125 if len(array.shape) > 2: 

1126 raise ValueError( 

1127 "conversion only works on 1D/2D arrays not %s!", str(array.shape) 

1128 ) 

1129 

1130 # abort for structured arrays 

1131 if array.dtype.names is not None: 

1132 raise ValueError("array is structured, use structured_array_to_string instead") 

1133 

1134 # allow a value to be repeated in a value format 

1135 repeats = value_format.count("{") 

1136 

1137 if array.dtype.kind in ["i", "u"]: 

1138 # integer types don't need a specified precision 

1139 format_str = value_format + col_delim 

1140 elif array.dtype.kind == "f": 

1141 # add the digits formatting to floats 

1142 format_str = value_format.replace("{}", "{:." + str(digits) + "f}") + col_delim 

1143 else: 

1144 raise ValueError("dtype %s not convertible!", array.dtype.name) 

1145 

1146 # length of extra delimiters at the end 

1147 end_junk = len(col_delim) 

1148 # if we have a 2D array add a row delimiter 

1149 if len(array.shape) == 2: 

1150 format_str *= array.shape[1] 

1151 # cut off the last column delimiter and add a row delimiter 

1152 format_str = format_str[: -len(col_delim)] + row_delim 

1153 end_junk = len(row_delim) 

1154 

1155 # expand format string to whole array 

1156 format_str *= len(array) 

1157 

1158 # if an array is repeated in the value format 

1159 # do the shaping here so we don't need to specify indexes 

1160 shaped = np.tile(array.reshape((-1, 1)), (1, repeats)).reshape(-1) 

1161 

1162 # run the format operation and remove the extra delimiters 

1163 formatted = format_str.format(*shaped)[:-end_junk] 

1164 

1165 return formatted 

1166 

1167 

1168def structured_array_to_string( 

1169 array: ArrayLike, 

1170 col_delim: str = " ", 

1171 row_delim: str = "\n", 

1172 digits: Integer = 8, 

1173 value_format: str = "{}", 

1174) -> str: 

1175 """ 

1176 Convert an unstructured array into a string with a specified 

1177 number of digits and delimiter. The reason thisexists is 

1178 that the basic numpy array to string conversions are 

1179 surprisingly slow. 

1180 

1181 Parameters 

1182 ------------ 

1183 array : (n,) or (n, d) float or int 

1184 Data to be converted 

1185 If shape is (n,) only column delimiter will be used 

1186 col_delim : str 

1187 What string should separate values in a column 

1188 row_delim : str 

1189 What string should separate values in a row 

1190 digits : int 

1191 How many digits should floating point numbers include 

1192 value_format : str 

1193 Format string for each value or sequence of values 

1194 If multiple values per value_format it must divide 

1195 into array evenly. 

1196 

1197 Returns 

1198 ---------- 

1199 formatted : str 

1200 String representation of original array 

1201 """ 

1202 # convert inputs to correct types 

1203 array = np.asanyarray(array) 

1204 digits = int(digits) 

1205 row_delim = str(row_delim) 

1206 col_delim = str(col_delim) 

1207 value_format = str(value_format) 

1208 

1209 # abort for non-flat arrays 

1210 if len(array.shape) > 1: 

1211 raise ValueError( 

1212 "conversion only works on 1D/2D arrays not %s!", str(array.shape) 

1213 ) 

1214 

1215 # abort for unstructured arrays 

1216 if array.dtype.names is None: 

1217 raise ValueError("array is not structured, use array_to_string instead") 

1218 

1219 # do not allow a value to be repeated in a value format 

1220 if value_format.count("{") > 1: 

1221 raise ValueError( 

1222 "value_format %s is invalid, repeating unstructured array " 

1223 + "values is unsupported", 

1224 value_format, 

1225 ) 

1226 

1227 format_str = "" 

1228 for name in array.dtype.names: 

1229 kind = array[name].dtype.kind 

1230 element_row_length = array[name].shape[1] if len(array[name].shape) == 2 else 1 

1231 if kind in ["i", "u"]: 

1232 # integer types need a no-decimal formatting 

1233 element_format_str = value_format.replace("{}", "{:0.0f}") + col_delim 

1234 elif kind == "f": 

1235 # add the digits formatting to floats 

1236 element_format_str = ( 

1237 value_format.replace("{}", "{:." + str(digits) + "f}") + col_delim 

1238 ) 

1239 else: 

1240 raise ValueError("dtype %s not convertible!", array.dtype) 

1241 format_str += element_row_length * element_format_str 

1242 

1243 # length of extra delimiters at the end 

1244 format_str = format_str[: -len(col_delim)] + row_delim 

1245 # expand format string to whole array 

1246 format_str *= len(array) 

1247 

1248 # loop through flat fields and flatten to single array 

1249 count = len(array) 

1250 # will upgrade everything to a float 

1251 flattened = np.hstack( 

1252 [array[k].reshape((count, -1)) for k in array.dtype.names] 

1253 ).reshape(-1) 

1254 

1255 # run the format operation and remove the extra delimiters 

1256 formatted = format_str.format(*flattened)[: -len(row_delim)] 

1257 

1258 return formatted 

1259 

1260 

1261def array_to_encoded( 

1262 array: ArrayLike, 

1263 dtype: np.typing.DTypeLike | None = None, 

1264 encoding: str = "base64", 

1265) -> Mapping[str, Any]: 

1266 """ 

1267 Export a numpy array to a compact serializable dictionary. 

1268 

1269 Parameters 

1270 ------------ 

1271 array : array 

1272 Any numpy array 

1273 dtype : str or None 

1274 Optional dtype to encode array 

1275 encoding : str 

1276 'base64' or 'binary' 

1277 

1278 Returns 

1279 --------- 

1280 encoded : dict 

1281 Has keys: 

1282 'dtype': str, of dtype 

1283 'shape': tuple of shape 

1284 'base64': str, base64 encoded string 

1285 """ 

1286 array = np.asanyarray(array) 

1287 shape = array.shape 

1288 # ravel also forces contiguous 

1289 flat = np.ravel(array) 

1290 if dtype is None: 

1291 dtype = array.dtype 

1292 

1293 encoded: dict[str, Any] = {"dtype": np.dtype(dtype).str, "shape": shape} 

1294 if encoding in ["base64", "dict64"]: 

1295 packed = base64.b64encode(flat.astype(dtype).tobytes()) 

1296 if hasattr(packed, "decode"): 

1297 packed = packed.decode("utf-8") 

1298 encoded["base64"] = packed 

1299 elif encoding == "binary": 

1300 encoded["binary"] = flat.astype(dtype, copy=False).tobytes() 

1301 else: 

1302 raise ValueError(f"encoding {encoding} is not available!") 

1303 return encoded 

1304 

1305 

1306# the store key type must be `Any` because the key type changes from `bytes` to `str` 

1307def decode_keys(store: dict[Any, Any], encoding: str = "utf-8") -> dict[str, Any]: 

1308 """ 

1309 If a dictionary has keys that are bytes decode them to a str. 

1310 

1311 Parameters 

1312 ------------ 

1313 store : dict 

1314 Dictionary with data 

1315 

1316 Returns 

1317 --------- 

1318 result : dict 

1319 Values are untouched but keys that were bytes 

1320 are converted to ASCII strings. 

1321 

1322 Example 

1323 ----------- 

1324 In [1]: d 

1325 Out[1]: {1020: 'nah', b'hi': 'stuff'} 

1326 

1327 In [2]: trimesh.util.decode_keys(d) 

1328 Out[2]: {1020: 'nah', 'hi': 'stuff'} 

1329 """ 

1330 keys = store.keys() 

1331 for key in keys: 

1332 if hasattr(key, "decode"): 

1333 decoded = key.decode(encoding) 

1334 if key != decoded: 

1335 store[key.decode(encoding)] = store[key] 

1336 store.pop(key) 

1337 return store 

1338 

1339 

1340def comment_strip(text: str, starts_with: str = "#", new_line: str = "\n") -> str: 

1341 """ 

1342 Strip comments from a text block. 

1343 

1344 Parameters 

1345 ----------- 

1346 text : str 

1347 Text to remove comments from 

1348 starts_with : str 

1349 Character or substring that starts a comment 

1350 new_line : str 

1351 Character or substring that ends a comment 

1352 

1353 Returns 

1354 ----------- 

1355 stripped : str 

1356 Text with comments stripped 

1357 """ 

1358 # if not contained exit immediately 

1359 if starts_with not in text: 

1360 return text 

1361 

1362 # start by splitting into chunks by the comment indicator 

1363 split = (text + new_line).split(starts_with) 

1364 

1365 # special case files that start with a comment 

1366 if text.startswith(starts_with): 

1367 lead = "" 

1368 else: 

1369 lead = split[0] 

1370 

1371 # take each comment up until the newline 

1372 removed = [i.split(new_line, 1) for i in split] 

1373 # add the leading string back on 

1374 result = ( 

1375 lead 

1376 + new_line 

1377 + new_line.join(i[1] for i in removed if len(i) > 1 and len(i[1]) > 0) 

1378 ) 

1379 # strip leading and trailing whitespace 

1380 result = result.strip() 

1381 

1382 return result 

1383 

1384 

1385def encoded_to_array(encoded: ArrayLike | dict[Any, Any]) -> NDArray: 

1386 """ 

1387 Turn a dictionary with base64 encoded strings back into a numpy array. 

1388 

1389 Parameters 

1390 ------------ 

1391 encoded 

1392 Has keys: 

1393 dtype: string of dtype 

1394 shape: int tuple of shape 

1395 base64: base64 encoded string of flat array 

1396 binary: decode result coming from numpy.tobytes 

1397 

1398 Returns 

1399 ---------- 

1400 array 

1401 """ 

1402 

1403 if not isinstance(encoded, dict): 

1404 if is_sequence(encoded): 

1405 as_array = np.asanyarray(encoded) 

1406 return as_array 

1407 else: 

1408 raise ValueError("Unable to extract numpy array from input") 

1409 

1410 encoded_dict = decode_keys(encoded) 

1411 

1412 dtype = np.dtype(encoded_dict["dtype"]) 

1413 if "base64" in encoded_dict: 

1414 array = np.frombuffer(base64.b64decode(encoded_dict["base64"]), dtype) 

1415 elif "binary" in encoded_dict: 

1416 array = np.frombuffer(encoded_dict["binary"], dtype=dtype) 

1417 else: 

1418 raise ValueError("Invalid encoded array, no 'base64' or 'binary' key found") 

1419 if "shape" in encoded_dict: 

1420 array = array.reshape(encoded_dict["shape"]) 

1421 return array 

1422 

1423 

1424def is_instance_named(obj: object, name: str | list[str]) -> bool: 

1425 """ 

1426 Given an object, if it is a member of the class 'name', 

1427 or a subclass of 'name', return True. 

1428 

1429 Parameters 

1430 ------------ 

1431 obj : instance 

1432 Some object of some class 

1433 name: str 

1434 The name of the class we want to check for 

1435 

1436 Returns 

1437 --------- 

1438 is_instance : bool 

1439 Whether the object is a member of the named class 

1440 """ 

1441 try: 

1442 if isinstance(name, list): 

1443 return any(is_instance_named(obj, i) for i in name) 

1444 else: 

1445 type_named(obj, name) 

1446 return True 

1447 except ValueError: 

1448 return False 

1449 

1450 

1451def type_bases(obj: object, depth: Integer = 4) -> list[type]: 

1452 """ 

1453 Return the bases of the object passed. 

1454 """ 

1455 bases: collections.deque[list] = collections.deque([list(obj.__class__.__bases__)]) 

1456 for i in range(depth): 

1457 bases.append([i.__base__ for i in bases[-1] if i is not None]) 

1458 try: 

1459 bases_flat = np.hstack(bases) 

1460 except IndexError: 

1461 return [] 

1462 return [i for i in bases_flat if hasattr(i, "__name__")] 

1463 

1464 

1465def type_named(obj: object, name: str) -> type: 

1466 """ 

1467 Similar to the type() builtin, but looks in class bases 

1468 for named instance. 

1469 

1470 Parameters 

1471 ------------ 

1472 obj : any 

1473 Object to look for class of 

1474 name : str 

1475 Name of class 

1476 

1477 Returns 

1478 ---------- 

1479 class : type 

1480 Named class, raises ValueError if not found 

1481 """ 

1482 # if obj is a member of the named class, return True 

1483 name = str(name) 

1484 if obj.__class__.__name__ == name: 

1485 return obj.__class__ 

1486 for base in type_bases(obj): 

1487 if base.__name__ == name: 

1488 return base 

1489 raise ValueError("Unable to extract class of name " + name) 

1490 

1491 

1492def concatenate(a, b=None) -> "trimesh.parent.Geometry": 

1493 """ 

1494 Concatenate two or more meshes. 

1495 

1496 Parameters 

1497 ------------ 

1498 a : trimesh.Trimesh 

1499 Mesh or list of meshes to be concatenated 

1500 object, or list of such 

1501 b : trimesh.Trimesh 

1502 Mesh or list of meshes to be concatenated 

1503 

1504 Returns 

1505 ---------- 

1506 result 

1507 Concatenated mesh 

1508 """ 

1509 dump = [] 

1510 for i in chain(a, b): 

1511 if is_instance_named(i, "Scene"): 

1512 # get every mesh in the final frame. 

1513 dump.extend(i.dump()) 

1514 else: 

1515 # just append to our flat list 

1516 dump.append(i) 

1517 

1518 if len(dump) == 1: 

1519 # if there is only one geometry just return the first 

1520 return dump[0].copy() 

1521 elif len(dump) == 0: 

1522 # if there are no meshes return an empty mesh 

1523 from .base import Trimesh 

1524 

1525 return Trimesh() 

1526 

1527 is_mesh = [f for f in dump if is_instance_named(f, "Trimesh")] 

1528 is_path = [f for f in dump if is_instance_named(f, "Path")] 

1529 

1530 # if we have more 

1531 if len(is_path) > len(is_mesh): 

1532 from .path.util import concatenate as concatenate_path 

1533 

1534 return concatenate_path(is_path) 

1535 

1536 if len(is_mesh) == 0: 

1537 # nothing concatenable was passed — match the empty-input 

1538 # branch above and hand back an empty mesh 

1539 from .base import Trimesh 

1540 

1541 return Trimesh() 

1542 

1543 # extract the trimesh type to avoid a circular import 

1544 # and assert that all inputs are Trimesh objects 

1545 trimesh_type = type_named(is_mesh[0], "Trimesh") 

1546 

1547 # append faces and vertices of meshes 

1548 vertices, faces = append_faces( 

1549 [m.vertices.copy() for m in is_mesh], [m.faces.copy() for m in is_mesh] 

1550 ) 

1551 

1552 # save face normals if already calculated 

1553 face_normals = None 

1554 if any("face_normals" in m._cache for m in is_mesh): 

1555 face_normals = vstack_empty([m.face_normals for m in is_mesh]) 

1556 assert face_normals.shape == faces.shape 

1557 

1558 # save vertex normals if any mesh has them 

1559 vertex_normals = None 

1560 if any("vertex_normals" in m._cache for m in is_mesh): 

1561 vertex_normals = vstack_empty([m.vertex_normals for m in is_mesh]) 

1562 assert vertex_normals.shape == vertices.shape 

1563 

1564 try: 

1565 # concatenate visuals 

1566 visual = is_mesh[0].visual.concatenate([m.visual for m in is_mesh[1:]]) 

1567 except BaseException as E: 

1568 log.debug(f"failed to combine visuals {_STRICT}", exc_info=True) 

1569 visual = None 

1570 if _STRICT: 

1571 raise E 

1572 

1573 metadata = {} 

1574 try: 

1575 _ = [metadata.update(deepcopy(m.metadata)) for m in is_mesh] 

1576 except BaseException: 

1577 pass 

1578 

1579 # concatenate vertex attributes that are valid for every mesh 

1580 vertex_attributes = {} 

1581 for key in is_mesh[0].vertex_attributes.keys(): 

1582 # make sure every mesh has a valid attribute 

1583 if all(len(m.vertex_attributes.get(key, [])) == len(m.vertices) for m in is_mesh): 

1584 try: 

1585 vertex_attributes[key] = np.concatenate( 

1586 [mesh.vertex_attributes.get(key, []) for mesh in is_mesh], axis=0 

1587 ) 

1588 except BaseException: 

1589 log.warning( 

1590 f"Failed to concatenate `vertex_attribute['{key}']`", exc_info=True 

1591 ) 

1592 

1593 # concatenate face attributes that are valid for every mesh 

1594 face_attributes = {} 

1595 for key in is_mesh[0].face_attributes.keys(): 

1596 # an attribute can only be concatenated if it's valid for every mesh 

1597 if all(len(m.face_attributes.get(key, [])) == len(m.faces) for m in is_mesh): 

1598 try: 

1599 # stack along axis 0 

1600 face_attributes[key] = np.concatenate( 

1601 [mesh.face_attributes.get(key, []) for mesh in is_mesh], axis=0 

1602 ) 

1603 except BaseException: 

1604 # could have failed because attribute had different shapes 

1605 log.warning( 

1606 f"Failed to concatenate `face_attribute['{key}']`", exc_info=True 

1607 ) 

1608 

1609 # create the mesh object 

1610 result = trimesh_type( 

1611 vertices=vertices, 

1612 faces=faces, 

1613 face_normals=face_normals, 

1614 vertex_normals=vertex_normals, 

1615 visual=visual, 

1616 vertex_attributes=vertex_attributes, 

1617 face_attributes=face_attributes, 

1618 metadata=metadata, 

1619 process=False, 

1620 ) 

1621 

1622 try: 

1623 result._source = deepcopy(is_mesh[0].source) 

1624 except BaseException: 

1625 pass 

1626 

1627 return result 

1628 

1629 

1630def submesh( 

1631 mesh, 

1632 faces_sequence: Iterable[ArrayLike], 

1633 repair: bool = True, 

1634 only_watertight: bool = False, 

1635 min_faces: Integer | None = None, 

1636 append: bool = False, 

1637 copy_material: bool = True, 

1638): 

1639 """ 

1640 Return a subset of a mesh. 

1641 

1642 Parameters 

1643 ------------ 

1644 mesh : Trimesh 

1645 Source mesh to take geometry from 

1646 faces_sequence : sequence (p,) int 

1647 Indexes of mesh.faces 

1648 repair 

1649 Try to make submeshes watertight 

1650 only_watertight 

1651 Only return submeshes which are watertight 

1652 min_faces 

1653 Minimum number of faces allowed in a submesh. 

1654 append : bool 

1655 Return a single mesh which has the faces appended, 

1656 if this flag is set, only_watertight is ignored 

1657 copy_material 

1658 If False textured submeshes share the material with the 

1659 source mesh instead of copying its texture image. 

1660 

1661 Returns 

1662 --------- 

1663 result : Trimesh | list[Trimesh] 

1664 Depending on if `append` is true or not. 

1665 """ 

1666 # evaluate generators so we can escape early 

1667 faces_sequence = list(faces_sequence) 

1668 

1669 if len(faces_sequence) == 0: 

1670 return [] 

1671 

1672 # avoid nuking the cache on the original mesh 

1673 original_faces = mesh.faces.view(np.ndarray) 

1674 original_vertices = mesh.vertices.view(np.ndarray) 

1675 

1676 faces = [] 

1677 vertices = [] 

1678 normals = [] 

1679 visuals = [] 

1680 

1681 # for reindexing faces 

1682 mask = np.arange(len(original_vertices)) 

1683 

1684 for index in faces_sequence: 

1685 # sanitize indices in case they are coming in as a set or tuple 

1686 index = np.asanyarray(index) 

1687 if len(index) == 0: 

1688 # regardless of type empty arrays are useless 

1689 continue 

1690 if index.dtype.kind == "b": 

1691 # if passed a bool with no true continue 

1692 if not index.any(): 

1693 continue 

1694 # if fewer faces than minimum 

1695 if min_faces is not None and index.sum() < min_faces: 

1696 continue 

1697 elif min_faces is not None and len(index) < min_faces: 

1698 continue 

1699 

1700 current = original_faces[index] 

1701 unique = np.unique(current.reshape(-1)) 

1702 

1703 # redefine face indices from zero 

1704 mask[unique] = np.arange(len(unique)) 

1705 normals.append(mesh.face_normals[index]) 

1706 faces.append(mask[current]) 

1707 vertices.append(original_vertices[unique]) 

1708 

1709 visuals.append(mesh.visual.face_subset(index, copy_material=copy_material)) 

1710 

1711 if len(vertices) == 0: 

1712 return [] 

1713 

1714 # we use type(mesh) rather than importing Trimesh from base 

1715 # to avoid a circular import 

1716 trimesh_type = type_named(mesh, "Trimesh") 

1717 

1718 if append: 

1719 visual = None 

1720 try: 

1721 visuals = np.array(visuals) 

1722 visual = visuals[0].concatenate(visuals[1:]) 

1723 except Exception: 

1724 log.debug("failed to combine visuals", exc_info=True) 

1725 # re-index faces and stack 

1726 vertices, faces = append_faces(vertices, faces) 

1727 appended = trimesh_type( 

1728 vertices=vertices, 

1729 faces=faces, 

1730 face_normals=np.vstack(normals), 

1731 visual=visual, 

1732 metadata=deepcopy(mesh.metadata), 

1733 process=False, 

1734 ) 

1735 appended._source = deepcopy(mesh.source) 

1736 

1737 return appended 

1738 

1739 if visuals is None: 

1740 visuals = [None] * len(vertices) 

1741 

1742 # generate a list of Trimesh objects 

1743 result = [ 

1744 trimesh_type( 

1745 vertices=v, 

1746 faces=f, 

1747 face_normals=n, 

1748 visual=c, 

1749 metadata=deepcopy(mesh.metadata), 

1750 process=False, 

1751 ) 

1752 for v, f, n, c in zip(vertices, faces, normals, visuals) 

1753 ] 

1754 

1755 # assign the "source" information summarizing where a mesh was 

1756 # loaded from (i.e. file name) to each submesh of the result 

1757 [setattr(r, "_source", deepcopy(mesh.source)) for r in result] 

1758 

1759 if repair: 

1760 # fill_holes will attempt a repair and returns the 

1761 # watertight status at the end of the repair attempt 

1762 watertight = [len(i.faces) >= 4 and i.fill_holes() for i in result] 

1763 elif only_watertight: 

1764 # calculate watertightness without repairing 

1765 watertight = [i.is_watertight for i in result] 

1766 

1767 if only_watertight: 

1768 # return only the watertight meshes 

1769 return [i for i, w in zip(result, watertight) if w] 

1770 

1771 return result 

1772 

1773 

1774def zero_pad(data: NDArray, count: Integer, right: bool = True) -> NDArray: 

1775 """ 

1776 Parameters 

1777 ------------ 

1778 data : (n,) 

1779 1D array 

1780 count : int 

1781 Minimum length of result array 

1782 

1783 Returns 

1784 --------- 

1785 padded : (m,) 

1786 1D array where m >= count 

1787 """ 

1788 if len(data) == 0: 

1789 return np.zeros(count) 

1790 elif len(data) < count: 

1791 padded = np.zeros(count) 

1792 if right: 

1793 padded[-len(data) :] = data 

1794 else: 

1795 padded[: len(data)] = data 

1796 return padded 

1797 else: 

1798 return np.asanyarray(data) 

1799 

1800 

1801def jsonify(obj: object, **kwargs: Any) -> str: 

1802 """ 

1803 A version of json.dumps that can handle numpy arrays 

1804 by creating a custom encoder for numpy dtypes. 

1805 

1806 Parameters 

1807 -------------- 

1808 obj : list, dict 

1809 A JSON-serializable blob 

1810 kwargs : dict 

1811 Passed to json.dumps 

1812 

1813 Returns 

1814 -------------- 

1815 dumped : str 

1816 JSON dump of obj 

1817 """ 

1818 

1819 class EdgeEncoder(json.JSONEncoder): 

1820 def default(self, obj: Any): 

1821 # will work for numpy.ndarrays 

1822 # as well as their int64/etc objects 

1823 if hasattr(obj, "tolist"): 

1824 # this works on numpy arrays 

1825 return obj.tolist() 

1826 elif hasattr(obj, "timestamp"): 

1827 # serialize datetime as the float stamp 

1828 return obj.timestamp() 

1829 elif hasattr(obj, "__dataclass_fields__"): 

1830 # serialize dataclasses as dict 

1831 return dataclass_to_dict(obj) 

1832 return json.JSONEncoder.default(self, obj) 

1833 

1834 # run the dumps using our encoder 

1835 return json.dumps(obj, cls=EdgeEncoder, **kwargs) 

1836 

1837 

1838def convert_like(item, like): 

1839 """ 

1840 Convert an item to have the dtype of another item 

1841 

1842 Parameters 

1843 ------------ 

1844 item : any 

1845 Item to be converted 

1846 like : any 

1847 Object with target dtype 

1848 If None, item is returned unmodified 

1849 

1850 Returns 

1851 ---------- 

1852 result: item, but in dtype of like 

1853 """ 

1854 # if it's a numpy array 

1855 if isinstance(like, np.ndarray): 

1856 return np.asanyarray(item, dtype=like.dtype) 

1857 

1858 # if it's already the desired type just return it 

1859 if isinstance(item, like.__class__) or like is None: 

1860 return item 

1861 

1862 # if it's an array with one item return it 

1863 if is_sequence(item) and len(item) == 1 and isinstance(item[0], like.__class__): 

1864 return item[0] 

1865 

1866 if ( 

1867 isinstance(item, str) 

1868 and like.__class__.__name__ == "Polygon" 

1869 and item.startswith("POLYGON") 

1870 ): 

1871 # break our rule on imports but only a little bit 

1872 # the import was a WKT serialized polygon 

1873 from shapely import wkt 

1874 

1875 return wkt.loads(item) 

1876 

1877 # otherwise just run the conversion 

1878 item = like.__class__(item) 

1879 

1880 return item 

1881 

1882 

1883def bounds_tree(bounds: ArrayLike) -> Any: 

1884 """ 

1885 Given a set of axis aligned bounds create an r-tree for 

1886 broad-phase collision detection. 

1887 

1888 Parameters 

1889 ------------ 

1890 bounds : (n, 2D) or (n, 2, D) float 

1891 Non-interleaved bounds where D=dimension 

1892 E.G a 2D bounds tree: 

1893 [(minx, miny, maxx, maxy), ...] 

1894 

1895 Returns 

1896 --------- 

1897 tree : Rtree 

1898 Tree containing bounds by index 

1899 """ 

1900 import rtree 

1901 

1902 # make sure we've copied bounds 

1903 bounds = np.array(bounds, dtype=np.float64, copy=True) 

1904 if len(bounds.shape) == 3: 

1905 # should be min-max per bound 

1906 if bounds.shape[1] != 2: 

1907 raise ValueError("bounds not (n, 2, dimension)!") 

1908 # reshape to one-row-per-hyperrectangle 

1909 bounds = bounds.reshape((len(bounds), -1)) 

1910 elif len(bounds.shape) != 2 or bounds.size == 0: 

1911 raise ValueError("Bounds must be (n, dimension * 2)!") 

1912 

1913 # check to make sure we have correct shape 

1914 dimension = bounds.shape[1] 

1915 if (dimension % 2) != 0: 

1916 raise ValueError("Bounds must be (n,dimension*2)!") 

1917 dimension = int(dimension / 2) 

1918 

1919 properties = rtree.index.Property(dimension=dimension) 

1920 # stream load was verified working on import above 

1921 return rtree.index.Index( 

1922 zip(np.arange(len(bounds)), bounds, [None] * len(bounds)), properties=properties 

1923 ) 

1924 

1925 

1926def wrap_as_stream(item: str | bytes) -> StringIO | BytesIO: 

1927 """ 

1928 Wrap a string or bytes object as a file object. 

1929 

1930 Parameters 

1931 ------------ 

1932 item: str or bytes 

1933 Item to be wrapped 

1934 

1935 Returns 

1936 --------- 

1937 wrapped : file-like object 

1938 Contains data from item 

1939 """ 

1940 if isinstance(item, str): 

1941 return StringIO(item) 

1942 elif isinstance(item, bytes): 

1943 return BytesIO(item) 

1944 raise ValueError(f"{type(item).__name__} is not wrappable!") 

1945 

1946 

1947def sigfig_round(values: ArrayLike, sigfig: ArrayLike = 1) -> NDArray1D[np.float64]: 

1948 """ 

1949 Round a single value to a specified number of significant figures. 

1950 

1951 Parameters 

1952 ------------ 

1953 values : float 

1954 Value to be rounded 

1955 sigfig : int 

1956 Number of significant figures to reduce to 

1957 

1958 Returns 

1959 ---------- 

1960 rounded : float 

1961 Value rounded to the specified number of significant figures 

1962 

1963 

1964 Examples 

1965 ---------- 

1966 In [1]: trimesh.util.round_sigfig(-232453.00014045456, 1) 

1967 Out[1]: -200000.0 

1968 

1969 In [2]: trimesh.util.round_sigfig(.00014045456, 1) 

1970 Out[2]: 0.0001 

1971 

1972 In [3]: trimesh.util.round_sigfig(.00014045456, 4) 

1973 Out[3]: 0.0001405 

1974 """ 

1975 as_int, multiplier = sigfig_int(values, sigfig) 

1976 rounded = as_int * (10**multiplier) 

1977 

1978 return rounded 

1979 

1980 

1981def sigfig_int( 

1982 values: ArrayLike, sigfig: ArrayLike 

1983) -> tuple[NDArray1D[np.int64], NDArray1D[np.float64]]: 

1984 """ 

1985 Convert a set of floating point values into integers 

1986 with a specified number of significant figures and an 

1987 exponent. 

1988 

1989 Parameters 

1990 ------------ 

1991 values : (n,) float or int 

1992 Array of values 

1993 sigfig : (n,) int 

1994 Number of significant figures to keep 

1995 

1996 Returns 

1997 ------------ 

1998 as_int : (n,) int 

1999 Every value[i] has sigfig[i] digits 

2000 multiplier : (n,) float 

2001 Exponent, so as_int * 10 ** multiplier is 

2002 the same order of magnitude as the input 

2003 """ 

2004 values = np.asanyarray(values).reshape(-1) 

2005 sigfig = np.asanyarray(sigfig, dtype=np.int64).reshape(-1) 

2006 

2007 if sigfig.shape != values.shape: 

2008 raise ValueError("sigfig must match identifier") 

2009 

2010 exponent = np.zeros(len(values)) 

2011 nonzero = np.abs(values) > TOL_ZERO 

2012 exponent[nonzero] = np.floor(np.log10(np.abs(values[nonzero]))) 

2013 

2014 multiplier = exponent - sigfig + 1 

2015 as_int = (values / (10**multiplier)).round().astype(np.int64) 

2016 

2017 return as_int, multiplier 

2018 

2019 

2020# skip ZIP members once declared uncompressed sizes exceed this 

2021_ARCHIVE_SKIP_SIZE = 32 * 1024**3 # 32 GiB 

2022 

2023 

2024def decompress( 

2025 file_obj: bytes | Stream, 

2026 file_type: str, 

2027) -> dict[str, Stream | None]: 

2028 """ 

2029 Given an open file object and a file type, return all components 

2030 of the archive as open file objects in a dict. 

2031 

2032 ZIP members are skipped once the total uncompressed size declared by 

2033 the archive exceeds `_ARCHIVE_SKIP_SIZE`. Other formats don't store a 

2034 per-member compressed size so there is nothing to check before reading. 

2035 

2036 Parameters 

2037 ------------ 

2038 file_obj : file-like 

2039 Containing compressed data. 

2040 file_type : str 

2041 File extension, 'zip', 'tar.gz', etc. 

2042 

2043 Returns 

2044 --------- 

2045 decompressed : dict 

2046 Data from archive in format {file name : file-like}. 

2047 """ 

2048 file_type = str(file_type).lower() 

2049 if isinstance(file_obj, bytes): 

2050 file_obj = BytesIO(file_obj) 

2051 

2052 if file_type.endswith("zip"): 

2053 archive = zipfile.ZipFile(file_obj) 

2054 result = {} 

2055 # running total of the sizes the central directory declared: this is 

2056 # an upper bound on what we can actually read as `ZipExtFile` stops 

2057 # at the declared size and then fails the CRC check 

2058 total = 0 

2059 for info in archive.infolist(): 

2060 if total + info.file_size > _ARCHIVE_SKIP_SIZE: 

2061 log.warning( 

2062 "skipping `%s`: declared %d bytes exceeds archive budget", 

2063 info.filename, 

2064 info.file_size, 

2065 ) 

2066 continue 

2067 total += info.file_size 

2068 with archive.open(info, mode="r") as src: 

2069 data = src.read() 

2070 result[info.filename] = wrap_as_stream(data) 

2071 return result 

2072 if file_type.endswith("bz2"): 

2073 import bz2 

2074 

2075 # get the file name if we have one otherwise default to "archive" 

2076 name = getattr(file_obj, "name", "archive1234")[:-4] 

2077 return {name: wrap_as_stream(bz2.open(file_obj, mode="r").read())} 

2078 if "tar" in file_type[-6:]: 

2079 import tarfile 

2080 

2081 archive = tarfile.open(fileobj=file_obj, mode="r") 

2082 result = {} 

2083 for info in archive.getmembers(): 

2084 if not info.isfile(): 

2085 continue 

2086 src = archive.extractfile(info) 

2087 if src is None: 

2088 continue 

2089 result[info.name] = wrap_as_stream(src.read()) 

2090 return result 

2091 raise ValueError("Unsupported type passed!") 

2092 

2093 

2094def compress( 

2095 info: Mapping[str, str | bytes | Stream], 

2096 **kwargs: Any, 

2097) -> bytes: 

2098 """ 

2099 Compress data stored in a dict. 

2100 

2101 Parameters 

2102 ----------- 

2103 info : dict 

2104 Data to compress in form: 

2105 {file name in archive: bytes or file-like object} 

2106 kwargs : dict 

2107 Passed to zipfile.ZipFile 

2108 Returns 

2109 ----------- 

2110 compressed : bytes 

2111 Compressed file data 

2112 """ 

2113 file_obj = BytesIO() 

2114 with zipfile.ZipFile( 

2115 file_obj, mode="w", compression=zipfile.ZIP_DEFLATED, **kwargs 

2116 ) as zipper: 

2117 for name, data_or_file in info.items(): 

2118 if isinstance(data_or_file, (str, bytes)): 

2119 data = data_or_file 

2120 else: 

2121 # a file-like object — read its contents 

2122 data = data_or_file.read() 

2123 zipper.writestr(name, data) 

2124 file_obj.seek(0) 

2125 compressed = file_obj.read() 

2126 return compressed 

2127 

2128 

2129def split_extension(file_name: str, special: Iterable[str] | None = None) -> str: 

2130 """ 

2131 Find the file extension of a file name, including support for 

2132 special case multipart file extensions (like .tar.gz) 

2133 

2134 Parameters 

2135 ------------ 

2136 file_name : str 

2137 File name 

2138 special : list of str 

2139 Multipart extensions 

2140 eg: ['tar.bz2', 'tar.gz'] 

2141 

2142 Returns 

2143 ---------- 

2144 extension : str 

2145 Last characters after a period, or 

2146 a value from 'special' 

2147 """ 

2148 file_name = str(file_name) 

2149 

2150 if special is None: 

2151 special = ["tar.bz2", "tar.gz"] 

2152 if file_name.endswith(tuple(special)): 

2153 for end in special: 

2154 if file_name.endswith(end): 

2155 return end 

2156 return file_name.split(".")[-1] 

2157 

2158 

2159def triangle_strips_to_faces( 

2160 strips: ArrayLike | Sequence[ArrayLike], 

2161) -> NDArray2D[np.int64]: 

2162 """ 

2163 Convert a sequence of triangle strips to (n, 3) faces. 

2164 

2165 Processes all strips at once using np.concatenate and is significantly 

2166 faster than loop-based methods. 

2167 

2168 From the OpenGL programming guide describing a single triangle 

2169 strip [v0, v1, v2, v3, v4]: 

2170 

2171 Draws a series of triangles (three-sided polygons) using vertices 

2172 v0, v1, v2, then v2, v1, v3 (note the order), then v2, v3, v4, 

2173 and so on. The ordering is to ensure that the triangles are all 

2174 drawn with the same orientation so that the strip can correctly form 

2175 part of a surface. 

2176 

2177 Parameters 

2178 ------------ 

2179 strips: (n,) list of (m,) int 

2180 Vertex indices 

2181 

2182 Returns 

2183 ------------ 

2184 faces : (m, 3) int 

2185 Vertex indices representing triangles 

2186 """ 

2187 

2188 # save the length of each list in the list of lists 

2189 lengths = np.array([len(i) for i in strips], dtype=np.int64) 

2190 # looping through a list of lists is extremely slow 

2191 # combine all the sequences into a blob we can manipulate 

2192 blob = np.concatenate(strips, dtype=np.int64) 

2193 

2194 # slice the blob into rough triangles 

2195 tri = np.array([blob[:-2], blob[1:-1], blob[2:]], dtype=np.int64).T 

2196 

2197 # if we only have one strip we can do a *lot* less work 

2198 # as we keep every triangle and flip every other one 

2199 if len(strips) == 1: 

2200 # flip in-place every other triangle 

2201 tri[1::2] = np.fliplr(tri[1::2]) 

2202 return tri 

2203 

2204 # remove the triangles which were implicit but not actually there 

2205 # because we combined everything into one big array for speed 

2206 length_index = np.cumsum(lengths)[:-1] 

2207 keep = np.ones(len(tri), dtype=bool) 

2208 keep[length_index - 2] = False 

2209 keep[length_index - 1] = False 

2210 tri = tri[keep] 

2211 

2212 # flip every other triangle so they generate correct normals/winding 

2213 length_index = np.append(0, np.cumsum(lengths - 2)) 

2214 flip = np.zeros(length_index[-1], dtype=bool) 

2215 for i in range(len(length_index) - 1): 

2216 flip[length_index[i] + 1 : length_index[i + 1]][::2] = True 

2217 tri[flip] = np.fliplr(tri[flip]) 

2218 

2219 return tri 

2220 

2221 

2222def triangle_fans_to_faces( 

2223 fans: Iterable[ArrayLike], 

2224) -> NDArray2D[np.int64]: 

2225 """ 

2226 Convert fans of m + 2 vertex indices in fan format to m triangles 

2227 

2228 Parameters 

2229 ---------- 

2230 fans: (n,) list of (m + 2,) int 

2231 Vertex indices 

2232 

2233 Returns 

2234 ------- 

2235 faces: (m, 3) int 

2236 Vertex indices representing triangles 

2237 """ 

2238 

2239 faces = [ 

2240 np.transpose([fan[0] * np.ones(len(fan) - 2, dtype=int), fan[1:-1], fan[2:]]) 

2241 for fan in fans 

2242 ] 

2243 return np.concatenate(faces, dtype=int) 

2244 

2245 

2246def vstack_empty(tup: Iterable[ArrayLike]) -> NDArray: 

2247 """ 

2248 A thin wrapper for numpy.vstack that ignores empty lists. 

2249 

2250 Parameters 

2251 ------------ 

2252 tup : tuple or list of arrays 

2253 With the same number of columns 

2254 

2255 Returns 

2256 ------------ 

2257 stacked : (n, d) array 

2258 With same number of columns as 

2259 constituent arrays. 

2260 """ 

2261 # filter out empty arrays 

2262 stackable = [i for i in tup if len(i) > 0] 

2263 # if we only have one array just return it 

2264 if len(stackable) == 1: 

2265 return np.asanyarray(stackable[0]) 

2266 # if we have nothing return an empty numpy array 

2267 elif len(stackable) == 0: 

2268 return np.array([]) 

2269 # otherwise just use vstack as normal 

2270 return np.vstack(stackable) 

2271 

2272 

2273def write_encoded( 

2274 file_obj: Stream, 

2275 stuff: str | bytes, 

2276 encoding: str = "utf-8", 

2277) -> str | bytes: 

2278 """ 

2279 If a file is open in binary mode and a 

2280 string is passed, encode and write. 

2281 

2282 If a file is open in text mode and bytes are 

2283 passed decode bytes to str and write. 

2284 

2285 Assumes binary mode if file_obj does not have 

2286 a 'mode' attribute (e.g. io.BufferedRandom). 

2287 

2288 Parameters 

2289 ----------- 

2290 file_obj : file object 

2291 With 'write' and 'mode' 

2292 stuff : str or bytes 

2293 Stuff to be written 

2294 encoding : str 

2295 Encoding of text 

2296 """ 

2297 binary_file = "b" in getattr(file_obj, "mode", "b") 

2298 string_stuff = isinstance(stuff, str) 

2299 binary_stuff = isinstance(stuff, bytes) 

2300 

2301 if binary_file and string_stuff: 

2302 file_obj.write(stuff.encode(encoding)) 

2303 elif not binary_file and binary_stuff: 

2304 file_obj.write(stuff.decode(encoding)) 

2305 else: 

2306 file_obj.write(stuff) 

2307 file_obj.flush() 

2308 return stuff 

2309 

2310 

2311def unique_id(length: Integer = 12) -> str: 

2312 """ 

2313 Generate a random alphaNumber unique identifier 

2314 using UUID logic. 

2315 

2316 Parameters 

2317 ------------ 

2318 length : int 

2319 Length of desired identifier 

2320 

2321 Returns 

2322 ------------ 

2323 unique : str 

2324 Unique alphaNumber identifier 

2325 """ 

2326 return uuid.UUID(int=random.getrandbits(128), version=4).hex[:length] 

2327 

2328 

2329def generate_basis(z: ArrayLike, epsilon: float = 1e-12) -> NDArray2D[np.float64]: 

2330 """ 

2331 Generate an arbitrary basis (also known as a coordinate frame) 

2332 from a given z-axis vector. 

2333 

2334 Parameters 

2335 ------------ 

2336 z : (3,) float 

2337 A vector along the positive z-axis. 

2338 epsilon : float 

2339 Numbers smaller than this considered zero. 

2340 

2341 Returns 

2342 --------- 

2343 x : (3,) float 

2344 Vector along x axis. 

2345 y : (3,) float 

2346 Vector along y axis. 

2347 z : (3,) float 

2348 Vector along z axis. 

2349 """ 

2350 # get a copy of input vector 

2351 z = np.array(z, dtype=np.float64, copy=True) 

2352 # must be a 3D vector 

2353 if z.shape != (3,): 

2354 raise ValueError("z must be (3,) float!") 

2355 

2356 z_norm = np.linalg.norm(z) 

2357 if z_norm < epsilon: 

2358 return np.eye(3) 

2359 

2360 # normalize vector in-place 

2361 z /= z_norm 

2362 # X as arbitrary perpendicular vector 

2363 x = np.array([-z[1], z[0], 0.0]) 

2364 # avoid degenerate case 

2365 x_norm = np.linalg.norm(x) 

2366 if x_norm < epsilon: 

2367 # this means that 

2368 # so a perpendicular X is just X 

2369 x = np.array([-z[2], z[1], 0.0]) 

2370 x /= np.linalg.norm(x) 

2371 else: 

2372 # otherwise normalize X in-place 

2373 x /= x_norm 

2374 # get perpendicular Y with cross product 

2375 y = np.cross(z, x) 

2376 # append result values into (3, 3) vector 

2377 result = np.array([x, y, z], dtype=np.float64) 

2378 

2379 if _STRICT: 

2380 # run checks to make sure axis are perpendicular 

2381 assert np.abs(np.dot(x, z)) < 1e-8 

2382 assert np.abs(np.dot(y, z)) < 1e-8 

2383 assert np.abs(np.dot(x, y)) < 1e-8 

2384 # all vectors should be unit vector 

2385 assert np.allclose(np.linalg.norm(result, axis=1), 1.0) 

2386 

2387 return result 

2388 

2389 

2390def isclose( 

2391 a: Number | NDArray, 

2392 b: Number | NDArray, 

2393 atol: Floating = 1e-8, 

2394) -> np.bool_ | NDArray[np.bool_]: 

2395 """ 

2396 A replacement for np.isclose that does fewer checks 

2397 and validation and as a result is roughly 4x faster. 

2398 

2399 Note that this is used in tight loops, and as such 

2400 a and b MUST be np.ndarray, not list or "array-like" 

2401 

2402 Parameters 

2403 ------------ 

2404 a : np.ndarray 

2405 To be compared 

2406 b : np.ndarray 

2407 To be compared 

2408 atol : float 

2409 Acceptable distance between `a` and `b` to be "close" 

2410 

2411 Returns 

2412 ----------- 

2413 close : np.ndarray, bool 

2414 Per-element closeness 

2415 """ 

2416 diff = a - b 

2417 return np.logical_and(diff > -atol, diff < atol) 

2418 

2419 

2420def allclose(a: Number | NDArray, b: Number | NDArray, atol: Floating = 1e-8) -> bool: 

2421 """ 

2422 A replacement for np.allclose that does few checks 

2423 and validation and as a result is faster. 

2424 

2425 Parameters 

2426 ------------ 

2427 a : np.ndarray 

2428 To be compared 

2429 b : np.ndarray 

2430 To be compared 

2431 atol : float 

2432 Acceptable distance between `a` and `b` to be "close" 

2433 

2434 Returns 

2435 ----------- 

2436 bool indicating if all elements are within `atol`. 

2437 """ 

2438 # 

2439 return bool(float(np.ptp(a - b)) < atol) 

2440 

2441 

2442class FunctionRegistry(Mapping[str, Callable[..., Any]]): 

2443 """ 

2444 Non-overwritable mapping of string keys to functions. 

2445 

2446 This allows external packages to register additional implementations 

2447 of common functionality without risk of breaking implementations provided 

2448 by trimesh. 

2449 

2450 See trimesh.voxel.morphology for example usage. 

2451 """ 

2452 

2453 def __init__(self, **kwargs: Callable[..., Any]) -> None: 

2454 self._dict = {} 

2455 for k, v in kwargs.items(): 

2456 self[k] = v 

2457 

2458 def __getitem__(self, key: str) -> Callable[..., Any]: 

2459 return self._dict[key] 

2460 

2461 def __setitem__(self, key: str, value: Callable[..., object]) -> None: 

2462 if not isinstance(key, str): 

2463 raise ValueError(f"key must be a string, got {key!s}") 

2464 if key in self: 

2465 raise KeyError(f"Cannot set new value to existing key {key}") 

2466 if not callable(value): 

2467 raise ValueError("Cannot set value which is not callable.") 

2468 self._dict[key] = value 

2469 

2470 def __iter__(self) -> Iterator[str]: 

2471 return iter(self._dict) 

2472 

2473 def __len__(self) -> int: 

2474 return len(self._dict) 

2475 

2476 def __contains__(self, key: object) -> bool: 

2477 return key in self._dict 

2478 

2479 def __call__(self, key: str, *args: object, **kwargs: object) -> Any: 

2480 return self[key](*args, **kwargs) 

2481 

2482 

2483def decode_text(text: str | bytes, initial: str = "utf-8") -> str: 

2484 """ 

2485 Try to decode byte input as a string. 

2486 

2487 Tries initial guess (UTF-8) then if that fails it 

2488 uses charset_normalizer to try another guess before failing. 

2489 

2490 Parameters 

2491 ------------ 

2492 text : bytes 

2493 Data that might be a string 

2494 initial : str 

2495 Initial guess for text encoding. 

2496 

2497 Returns 

2498 ------------ 

2499 decoded : str 

2500 Data as a string 

2501 """ 

2502 # if it's already a string there is nothing to decode 

2503 if isinstance(text, str): 

2504 return text 

2505 

2506 try: 

2507 # initially guess file is UTF-8 or specified encoding 

2508 return text.decode(initial) 

2509 except UnicodeDecodeError: 

2510 # detect different file encodings 

2511 from charset_normalizer import detect as charset_normalizer_detect 

2512 

2513 # try to detect the encoding of the file 

2514 # only look at the first 1000 characters for speed 

2515 detect = charset_normalizer_detect(text[:1000]) 

2516 # warn on files that aren't UTF-8 

2517 log.debug( 

2518 "Data not {}! Trying {} (confidence {})".format( 

2519 initial, detect["encoding"], detect["confidence"] 

2520 ) 

2521 ) 

2522 # try to decode again ignoring errors 

2523 # if detect returned nothing just use the initial guess 

2524 return text.decode(detect["encoding"] or initial, errors="ignore") 

2525 

2526 

2527def to_ascii(text: Any) -> str: 

2528 """ 

2529 Force a string or other to ASCII text ignoring errors. 

2530 

2531 Parameters 

2532 ----------- 

2533 text : any 

2534 Input to be converted to ASCII string 

2535 

2536 Returns 

2537 ----------- 

2538 ascii : str 

2539 Input as an ASCII string 

2540 """ 

2541 if hasattr(text, "encode"): 

2542 # case for existing strings 

2543 return text.encode("ascii", errors="ignore").decode("ascii") 

2544 elif hasattr(text, "decode"): 

2545 # case for bytes 

2546 return text.decode("ascii", errors="ignore") 

2547 # otherwise just wrap as a string 

2548 return str(text) 

2549 

2550 

2551def is_ccw(points: ArrayLike, return_all: bool = False): 

2552 """ 

2553 Check if connected 2D points are counterclockwise. 

2554 

2555 Parameters 

2556 ----------- 

2557 points : (n, 2) float 

2558 Connected points on a plane 

2559 return_all : bool 

2560 Return polygon area and centroid or just counter-clockwise. 

2561 

2562 Returns 

2563 ---------- 

2564 ccw : bool 

2565 True if points are counter-clockwise 

2566 area : float 

2567 Only returned if `return_centroid` 

2568 centroid : (2,) float 

2569 Centroid of the polygon. 

2570 """ 

2571 points = np.array(points, dtype=np.float64) 

2572 

2573 if len(points.shape) != 2 or points.shape[1] != 2: 

2574 raise ValueError("only defined for `(n, 2)` points") 

2575 

2576 # the "shoelace formula" 

2577 product = np.subtract(*(points[:-1, [1, 0]] * points[1:]).T) 

2578 # the area of the polygon 

2579 area = product.sum() / 2.0 

2580 # check the sign of the area 

2581 ccw = area < 0.0 

2582 

2583 if not return_all: 

2584 return ccw 

2585 

2586 # the centroid of the polygon uses the same formula 

2587 centroid = ((points[:-1] + points[1:]) * product.reshape((-1, 1))).sum(axis=0) / ( 

2588 6.0 * area 

2589 ) 

2590 

2591 return ccw, area, centroid 

2592 

2593 

2594def unique_name( 

2595 start: str | None, 

2596 contains: Collection[str], 

2597 counts: MutableMapping[str | None, int] | None = None, 

2598) -> str: 

2599 """ 

2600 Deterministically generate a unique name not 

2601 contained in a dict, set or other grouping with 

2602 `__includes__` defined. Will create names of the 

2603 form "start_10" and increment accordingly. 

2604 

2605 Parameters 

2606 ----------- 

2607 start : str 

2608 Initial guess for name. 

2609 contains : dict, set, or list 

2610 Bundle of existing names we can *not* use. 

2611 counts : None or dict 

2612 Maps name starts encountered before to increments in 

2613 order to speed up finding a unique name as otherwise 

2614 it potentially has to iterate through all of contains. 

2615 Should map to "how many times has this `start` 

2616 been attempted, i.e. `counts[start]: int`. 

2617 Note that this *will be mutated* in-place by this function! 

2618 

2619 Returns 

2620 --------- 

2621 unique : str 

2622 A name that is not contained in `contains` 

2623 """ 

2624 # exit early if name is not in bundle 

2625 if start is not None and len(start) > 0 and start not in contains: 

2626 return start 

2627 

2628 # start checking with zero index unless found 

2629 if counts is None: 

2630 increment = 0 

2631 else: 

2632 increment = counts.get(start, 0) 

2633 if start is not None and len(start) > 0: 

2634 formatter = start + "_{}" 

2635 # split by our delimiter once 

2636 split = start.rsplit("_", 1) 

2637 if len(split) == 2 and increment == 0: 

2638 try: 

2639 # start incrementing from the existing 

2640 # trailing value 

2641 # if it is not an integer this will fail 

2642 increment = int(split[1]) 

2643 # include the first split value 

2644 formatter = split[0] + "_{}" 

2645 except BaseException: 

2646 pass 

2647 else: 

2648 formatter = "geometry_{}" 

2649 

2650 # if contains is empty we will only need to check once 

2651 for i in range(increment + 1, 2 + increment + len(contains)): 

2652 check = formatter.format(i) 

2653 if check not in contains: 

2654 if counts is not None: 

2655 counts[start] = i 

2656 return check 

2657 

2658 # this should really never happen since we looped 

2659 # through the full length of contains 

2660 raise ValueError("Unable to establish unique name!")