Coverage for trimesh/scene/cameras.py: 93%

135 statements  

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

1import copy 

2 

3import numpy as np 

4 

5from .. import util 

6 

7 

8class Camera: 

9 def __init__( 

10 self, name=None, resolution=None, focal=None, fov=None, z_near=0.01, z_far=1000.0 

11 ): 

12 """ 

13 Create a new Camera object that stores camera intrinsic 

14 and extrinsic parameters. 

15 

16 TODO: skew is not supported 

17 TODO: cx and cy that are not half of width and height 

18 

19 Parameters 

20 ------------ 

21 name : str or None 

22 Name for camera to be used as node name 

23 resolution : (2,) int 

24 Pixel size in (height, width) 

25 focal : (2,) float 

26 Focal length in pixels. Either pass this OR FOV 

27 but not both. focal = (K[0][0], K[1][1]) 

28 fov : (2,) float 

29 Field of view (fovx, fovy) in degrees 

30 z_near : float 

31 What is the closest 

32 """ 

33 

34 if name is None: 

35 # if name is not passed, make it something unique 

36 self.name = f"camera_{util.unique_id(6).upper()}" 

37 else: 

38 # otherwise assign it 

39 self.name = name 

40 

41 if fov is None and focal is None: 

42 raise ValueError("either focal length or FOV required!") 

43 

44 # store whether or not we computed the focal length 

45 self._focal_computed = False 

46 

47 # set the passed (2,) float focal length 

48 self.focal = focal 

49 

50 # set the passed (2,) float FOV in degrees 

51 self.fov = fov 

52 

53 if resolution is None: 

54 # if unset make resolution 30 pixels per degree 

55 resolution = (self.fov * 30.0).round().astype(np.int64) 

56 self.resolution = resolution 

57 

58 # what is the farthest from the camera it should render 

59 self.z_far = float(z_far) 

60 # what is the closest to the camera it should render 

61 self.z_near = float(z_near) 

62 

63 def copy(self): 

64 """ 

65 Safely get a copy of the current camera. 

66 """ 

67 # only pass the intrinsic that was set so the copy 

68 # keeps the same one fixed when the resolution changes 

69 if self._focal_computed: 

70 intrinsic = {"fov": copy.deepcopy(self.fov)} 

71 else: 

72 intrinsic = {"focal": copy.deepcopy(self.focal)} 

73 return Camera( 

74 name=copy.deepcopy(self.name), 

75 resolution=copy.deepcopy(self.resolution), 

76 z_near=self.z_near, 

77 z_far=self.z_far, 

78 **intrinsic, 

79 ) 

80 

81 @property 

82 def resolution(self): 

83 """ 

84 Get the camera resolution in pixels. 

85 

86 Returns 

87 ------------ 

88 resolution (2,) float 

89 Camera resolution in pixels 

90 """ 

91 return self._resolution 

92 

93 @resolution.setter 

94 def resolution(self, values): 

95 """ 

96 Set the camera resolution in pixels. 

97 

98 Parameters 

99 ------------ 

100 resolution (2,) float 

101 Camera resolution in pixels 

102 """ 

103 values = np.asanyarray(values, dtype=np.int64) 

104 if values.shape != (2,): 

105 raise ValueError("resolution must be (2,) float") 

106 values.flags.writeable = False 

107 self._resolution = values 

108 # unset computed value that depends on the other plus resolution 

109 if self._focal_computed: 

110 self._focal = None 

111 else: 

112 # fov must be computed 

113 self._fov = None 

114 

115 @property 

116 def focal(self): 

117 """ 

118 Get the focal length in pixels for the camera. 

119 

120 Returns 

121 ------------ 

122 focal : (2,) float 

123 Focal length in pixels 

124 """ 

125 if self._focal is None: 

126 # calculate focal length from FOV 

127 focal = self._resolution / (2.0 * np.tan(np.radians(self._fov / 2.0))) 

128 focal.flags.writeable = False 

129 self._focal = focal 

130 

131 return self._focal 

132 

133 @focal.setter 

134 def focal(self, values): 

135 """ 

136 Set the focal length in pixels for the camera. 

137 

138 Returns 

139 ------------ 

140 focal : (2,) float 

141 Focal length in pixels. 

142 """ 

143 if values is None: 

144 self._focal = None 

145 else: 

146 # flag this as not computed (hence fov must be) 

147 # this is necessary so changes to resolution can reset the 

148 # computed quantity without changing the explicitly set quantity 

149 self._focal_computed = False 

150 values = np.asanyarray(values, dtype=np.float64) 

151 if values.shape != (2,): 

152 raise ValueError("focal length must be (2,) float") 

153 values.flags.writeable = False 

154 # assign passed values to focal length 

155 self._focal = values 

156 # focal overrides FOV 

157 self._fov = None 

158 

159 @property 

160 def K(self): 

161 """ 

162 Get the intrinsic matrix for the Camera object. 

163 

164 Returns 

165 ----------- 

166 K : (3, 3) float 

167 Intrinsic matrix for camera 

168 """ 

169 K = np.eye(3, dtype=np.float64) 

170 K[0, 0] = self.focal[0] 

171 K[1, 1] = self.focal[1] 

172 K[:2, 2] = self.resolution / 2.0 

173 return K 

174 

175 @K.setter 

176 def K(self, values): 

177 if values is None: 

178 return 

179 values = np.asanyarray(values, dtype=np.float64) 

180 if values.shape != (3, 3): 

181 raise ValueError("matrix must be (3,3)!") 

182 

183 if not np.allclose(values.flatten()[[1, 3, 6, 7, 8]], [0, 0, 0, 0, 1]): 

184 raise ValueError("matrix should only have focal length and resolution!") 

185 

186 # set focal length from matrix 

187 self.focal = [values[0, 0], values[1, 1]] 

188 # set resolution from matrix 

189 self.resolution = values[:2, 2] * 2 

190 

191 @property 

192 def fov(self): 

193 """ 

194 Get the field of view in degrees. 

195 

196 Returns 

197 ------------- 

198 fov : (2,) float 

199 XY field of view in degrees 

200 """ 

201 if self._fov is None: 

202 fov = 2.0 * np.degrees(np.arctan((self._resolution / 2.0) / self._focal)) 

203 fov.flags.writeable = False 

204 self._fov = fov 

205 return self._fov 

206 

207 @fov.setter 

208 def fov(self, values): 

209 """ 

210 Set the field of view in degrees. 

211 

212 Parameters 

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

214 values : (2,) float 

215 Size of FOV to set in degrees 

216 """ 

217 if values is None: 

218 self._fov = None 

219 else: 

220 # flag this as computed (hence fov must not be) 

221 # this is necessary so changes to resolution can reset the 

222 # computed quantity without changing the explicitly set quantity 

223 self._focal_computed = True 

224 values = np.asanyarray(values, dtype=np.float64) 

225 if values.shape != (2,): 

226 raise ValueError("fov length must be (2,) int") 

227 values.flags.writeable = False 

228 # assign passed values to FOV 

229 self._fov = values 

230 # fov overrides focal 

231 self._focal = None 

232 

233 def to_rays(self): 

234 """ 

235 Calculate ray direction vectors. 

236 

237 Will return one ray per pixel, as set in self.resolution. 

238 

239 Returns 

240 -------------- 

241 vectors : (n, 3) float 

242 Ray direction vectors in camera frame with z == -1 

243 """ 

244 return camera_to_rays(self) 

245 

246 def angles(self): 

247 """ 

248 Get ray spherical coordinates in radians. 

249 

250 

251 Returns 

252 -------------- 

253 angles : (n, 2) float 

254 Ray spherical coordinate angles in radians. 

255 """ 

256 xy, _pixels = ray_pixel_coords(self) 

257 return np.arctan(-xy) 

258 

259 def look_at(self, points, **kwargs): 

260 """ 

261 Generate transform for a camera to keep a list 

262 of points in the camera's field of view. 

263 

264 Parameters 

265 ------------- 

266 points : (n, 3) float 

267 Points in space 

268 rotation : None, or (4, 4) float 

269 Rotation matrix for initial rotation 

270 distance : None or float 

271 Distance from camera to center 

272 center : None, or (3,) float 

273 Center of field of view. 

274 

275 Returns 

276 -------------- 

277 transform : (4, 4) float 

278 Transformation matrix from camera to world coordinates. 

279 Use its inverse to transform world points into camera coordinates. 

280 

281 Examples 

282 -------- 

283 Transform the camera origin into world coordinates, and the world 

284 origin into camera coordinates using the inverse pose. 

285 

286 >>> import numpy as np 

287 >>> import trimesh 

288 >>> camera = trimesh.scene.Camera(fov=(60, 45)) 

289 >>> pose = camera.look_at([[0, 0, 0]], distance=2.0) 

290 >>> trimesh.transform_points([[0, 0, 0]], pose).tolist() 

291 [[0.0, 0.0, 2.0]] 

292 >>> world_to_camera = np.linalg.inv(pose) 

293 >>> trimesh.transform_points([[0, 0, 0]], world_to_camera).tolist() 

294 [[0.0, 0.0, -2.0]] 

295 """ 

296 return look_at(points, fov=self.fov, **kwargs) 

297 

298 def __repr__(self): 

299 return f"<trimesh.scene.Camera> FOV: {self.fov} Resolution: {self.resolution}" 

300 

301 

302def look_at(points, fov, rotation=None, distance=None, center=None, pad=None): 

303 """ 

304 Generate transform for a camera to keep a list 

305 of points in the camera's field of view. 

306 

307 Examples 

308 ------------ 

309 ```python 

310 points = np.array([0, 0, 0], [1, 1, 1]) 

311 scene.camera_transform = scene.camera.look_at(points) 

312 ``` 

313 

314 Parameters 

315 ------------- 

316 points : (n, 3) float 

317 Points in space 

318 fov : (2,) float 

319 Field of view, in DEGREES 

320 rotation : None, or (4, 4) float 

321 Rotation matrix for initial rotation 

322 distance : None or float 

323 Distance from camera to center 

324 center : None, or (3,) float 

325 Center of field of view. 

326 

327 Returns 

328 -------------- 

329 transform : (4, 4) float 

330 Transformation matrix from camera to world coordinates. 

331 Use its inverse to transform world points into camera coordinates. 

332 """ 

333 

334 if rotation is None: 

335 rotation = np.eye(4) 

336 else: 

337 rotation = np.asanyarray(rotation, dtype=np.float64) 

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

339 

340 # Transform points to camera frame (just use the rotation part) 

341 rinv = rotation[:3, :3].T 

342 points_c = rinv.dot(points.T).T 

343 

344 if center is None: 

345 # Find the center of the points' AABB in camera frame 

346 center_c = points_c.min(axis=0) + 0.5 * np.ptp(points_c, axis=0) 

347 else: 

348 # Transform center to camera frame 

349 center_c = rinv.dot(center) 

350 

351 # Re-center the points around the camera-frame origin 

352 points_c -= center_c 

353 

354 # Find the minimum distance for the camera from the origin 

355 # so that all points fit in the view frustum 

356 tfov = np.tan(np.radians(fov) / 2.0) 

357 

358 if distance is None: 

359 distance = np.max(np.abs(points_c[:, :2]) / tfov + points_c[:, 2][:, np.newaxis]) 

360 

361 if pad is not None: 

362 distance *= pad 

363 

364 # set the pose translation 

365 center_w = rotation[:3, :3].dot(center_c) 

366 cam_pose = rotation.copy() 

367 cam_pose[:3, 3] = center_w + distance * cam_pose[:3, 2] 

368 

369 return cam_pose 

370 

371 

372def ray_pixel_coords(camera): 

373 """ 

374 Get the x-y coordinates of rays in camera coordinates at 

375 z == -1. 

376 

377 One coordinate pair will be given for each pixel as defined in 

378 camera.resolution. If reshaped, the returned array corresponds 

379 to pixels of the rendered image. 

380 

381 Examples 

382 ------------ 

383 ```python 

384 xy = ray_pixel_coords(camera).reshape( 

385 tuple(camera.coordinates) + (2,)) 

386 top_left == xy[0, 0] 

387 bottom_right == xy[-1, -1] 

388 ``` 

389 

390 Parameters 

391 -------------- 

392 camera : trimesh.scene.Camera 

393 Camera object to generate rays from 

394 

395 Returns 

396 -------------- 

397 xy : (n, 2) float 

398 x-y coordinates of intersection of each camera ray 

399 with the z == -1 frame 

400 """ 

401 # shorthand 

402 res = camera.resolution 

403 half_fov = np.radians(camera.fov) / 2.0 

404 

405 right_top = np.tan(half_fov) 

406 # move half a pixel width in 

407 right_top *= 1 - (1.0 / res) 

408 left_bottom = -right_top 

409 # we are looking down the negative z axis, so 

410 # right_top corresponds to maximum x/y values 

411 # bottom_left corresponds to minimum x/y values 

412 right, top = right_top 

413 left, bottom = left_bottom 

414 

415 # create a grid of vectors 

416 xy = util.grid_linspace( 

417 bounds=[[left, top], [right, bottom]], count=camera.resolution 

418 ) 

419 

420 # create a matching array of pixel indexes for the rays 

421 pixels = util.grid_linspace( 

422 bounds=[[0, res[1] - 1], [res[0] - 1, 0]], count=res 

423 ).astype(np.int64) 

424 assert xy.shape == pixels.shape 

425 

426 return xy, pixels 

427 

428 

429def camera_to_rays(camera: Camera): 

430 """ 

431 Calculate the trimesh.scene.Camera object to direction vectors. 

432 

433 Will return one ray per pixel, as set in camera.resolution. 

434 

435 Parameters 

436 -------------- 

437 camera : trimesh.scene.Camera 

438 

439 Returns 

440 -------------- 

441 vectors : (n, 3) float 

442 Ray direction vectors in camera frame with z == -1 

443 """ 

444 # get the on-plane coordinates 

445 xy, pixels = ray_pixel_coords(camera) 

446 # convert vectors to 3D unit vectors 

447 vectors = util.unitize(np.column_stack((xy, -np.ones_like(xy[:, :1])))) 

448 return vectors, pixels