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
« prev ^ index » next coverage.py v7.17.0, created at 2026-11-12 17:18 +0000
1import copy
3import numpy as np
5from .. import util
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.
16 TODO: skew is not supported
17 TODO: cx and cy that are not half of width and height
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 """
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
41 if fov is None and focal is None:
42 raise ValueError("either focal length or FOV required!")
44 # store whether or not we computed the focal length
45 self._focal_computed = False
47 # set the passed (2,) float focal length
48 self.focal = focal
50 # set the passed (2,) float FOV in degrees
51 self.fov = fov
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
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)
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 )
81 @property
82 def resolution(self):
83 """
84 Get the camera resolution in pixels.
86 Returns
87 ------------
88 resolution (2,) float
89 Camera resolution in pixels
90 """
91 return self._resolution
93 @resolution.setter
94 def resolution(self, values):
95 """
96 Set the camera resolution in pixels.
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
115 @property
116 def focal(self):
117 """
118 Get the focal length in pixels for the camera.
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
131 return self._focal
133 @focal.setter
134 def focal(self, values):
135 """
136 Set the focal length in pixels for the camera.
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
159 @property
160 def K(self):
161 """
162 Get the intrinsic matrix for the Camera object.
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
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)!")
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!")
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
191 @property
192 def fov(self):
193 """
194 Get the field of view in degrees.
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
207 @fov.setter
208 def fov(self, values):
209 """
210 Set the field of view in degrees.
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
233 def to_rays(self):
234 """
235 Calculate ray direction vectors.
237 Will return one ray per pixel, as set in self.resolution.
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)
246 def angles(self):
247 """
248 Get ray spherical coordinates in radians.
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)
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.
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.
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.
281 Examples
282 --------
283 Transform the camera origin into world coordinates, and the world
284 origin into camera coordinates using the inverse pose.
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)
298 def __repr__(self):
299 return f"<trimesh.scene.Camera> FOV: {self.fov} Resolution: {self.resolution}"
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.
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 ```
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.
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 """
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)
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
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)
351 # Re-center the points around the camera-frame origin
352 points_c -= center_c
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)
358 if distance is None:
359 distance = np.max(np.abs(points_c[:, :2]) / tfov + points_c[:, 2][:, np.newaxis])
361 if pad is not None:
362 distance *= pad
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]
369 return cam_pose
372def ray_pixel_coords(camera):
373 """
374 Get the x-y coordinates of rays in camera coordinates at
375 z == -1.
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.
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 ```
390 Parameters
391 --------------
392 camera : trimesh.scene.Camera
393 Camera object to generate rays from
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
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
415 # create a grid of vectors
416 xy = util.grid_linspace(
417 bounds=[[left, top], [right, bottom]], count=camera.resolution
418 )
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
426 return xy, pixels
429def camera_to_rays(camera: Camera):
430 """
431 Calculate the trimesh.scene.Camera object to direction vectors.
433 Will return one ray per pixel, as set in camera.resolution.
435 Parameters
436 --------------
437 camera : trimesh.scene.Camera
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