pyvale.render.cameratools module¶

Camera placement, orientation, projection, and stereo configuration helpers.

class EFrameFit(*values)[source]¶

Bases: IntEnum

Rule used to fit world coordinates within the camera field of view.

CONTAIN = 0¶

COVER = 1¶

HORIZONTAL = 2¶

VERTICAL = 3¶

class StereoAngles(relative_euler_xyz_degrees, convergence_degrees)[source]¶

Bases: object

Relative orientation and optical axis convergence of a stereo pair.

Parameters:

relative_euler_xyz_degrees (np.ndarray) – Relative Euler angles (XYZ) in degrees with shape (3,) and dtype float64.
convergence_degrees (float) – Optical axis convergence angle in degrees.

relative_euler_xyz_degrees¶

convergence_degrees¶

__init__(relative_euler_xyz_degrees, convergence_degrees)¶

StereoCameras¶

The ordered pair of cameras that defines a stereo rig.

alias of tuple[Camera, Camera]

class StereoExtrinsics(rotation_cam1_from_cam0, translation_cam1_in_cam0)[source]¶

Bases: object

Transform from camera zero coordinates to camera one coordinates.

The relation is point_cam1 = rotation_cam1_from_cam0.apply(point_cam0) + translation_cam1_in_cam0. The camera rotations stored by Camera transform camera coordinates into world coordinates.

Parameters:

rotation_cam1_from_cam0 (scipy.spatial.transform.Rotation) – Relative rotation from camera zero frame to camera one frame.
translation_cam1_in_cam0 (np.ndarray) – Translation vector array with shape (3,) and dtype float64 representing the position of camera zero in camera one frame.

rotation_cam1_from_cam0¶

translation_cam1_in_cam0¶

__init__(rotation_cam1_from_cam0, translation_cam1_in_cam0)¶

average_subpixel_image(image, subsample)[source]¶

Average square sub pixel blocks into output pixels.

Parameters:

image (np.ndarray) – Sub sampled image array with shape (subsample * height, subsample * width) and float or int dtype.
subsample (int) – Sub pixel factor per dimension.

Returns:

np.ndarray – Averaged image array with shape (height, width) and dtype float64.

cam_calc_leng_per_px(camera, target=None)[source]¶

Calculate average simulation length per image pixel at a target.

Riley evaluates the camera normal plane through the target and averages its horizontal and vertical scaling. The camera ROI centre is used when target is omitted.

Parameters:

camera (Camera) – Camera model.
target (np.ndarray or None, optional) – Target position array with shape (3,) and dtype float64 representing (X, Y, Z) coordinates. If None, uses camera.roi_cent_world.

Returns:

float – Average world length per pixel in simulation length units.

Raises:

ValueError – If target is not finite or has invalid shape.

cam_calc_px_per_leng(camera, target=None)[source]¶

Calculate average image pixels per simulation length at a target.

Parameters:

camera (Camera) – Camera model.
target (np.ndarray or None, optional) – Target position array with shape (3,) and dtype float64 representing (X, Y, Z) coordinates. If None, uses camera.roi_cent_world.

Returns:

float – Average image pixels per world length unit.

cam_coverage_to_fov_scale(coverage)[source]¶

Convert target image coverage to Riley’s field of view scale.

Parameters:: coverage (float) – Target image coverage fraction (e.g. 0.9 for 90% sensor coverage).
Returns:: float – Riley field of view scale parameter.
Raises:: ValueError – If coverage is not positive.

cam_fov_scale_to_coverage(fov_scale)[source]¶

Convert Riley’s field of view scale to target image coverage.

Parameters:: fov_scale (float) – Riley field of view scale parameter.
Returns:: float – Target image coverage fraction.
Raises:: ValueError – If fov_scale is not positive.

cam_frame_mesh(camera, mesh, fov_scale=1.0, fit_mode=EFrameFit.CONTAIN, target=None)[source]¶

Position a camera along its view direction to frame a mesh.

Parameters:

camera (Camera) – Camera to position.
mesh (Mesh3D) – Surface mesh whose coordinates to fit inside the sensor.
fov_scale (float, optional) – Scale applied to the fitted field of view (default is 1.0).
fit_mode (EFrameFit, optional) – Rule used to select the fitted sensor dimension. Defaults to EFrameFit.CONTAIN.
target (np.ndarray or None, optional) – Point array with shape (3,) placed at the image centre. The bounds centre is used when omitted.

Returns:

Camera – A copy of the camera positioned to frame the mesh.

cam_frame_points(camera, points, fov_scale=1.0, fit_mode=EFrameFit.CONTAIN, target=None)[source]¶

Move a camera along its view direction to frame a set of points.

Parameters:

camera (Camera) – Camera to position.
points (numpy.ndarray) – Array of 3D point coordinates to fit inside the sensor.
fov_scale (float, optional) – Scale applied to the fitted field of view (default is 1.0).
fit_mode (EFrameFit, optional) – Rule used to select the fitted sensor dimension.
target (numpy.ndarray or None, optional) – Point placed at the image centre. The bounds centre is used when omitted.

Returns:

Camera – A copy of the camera positioned to frame the points.

cam_frame_scene(camera, meshes, fov_scale=1.0, fit_mode=EFrameFit.CONTAIN, target=None)[source]¶

Position a camera along its view direction to frame all meshes.

Parameters:

camera (Camera) – Camera to position.
meshes (Sequence[Mesh3D]) – Collection of surface meshes to frame.
fov_scale (float, optional) – Scale applied to the fitted field of view (default is 1.0).
fit_mode (EFrameFit, optional) – Rule used to select the fitted sensor dimension. Defaults to EFrameFit.CONTAIN.
target (np.ndarray or None, optional) – Point array with shape (3,) placed at the image centre. The bounds centre is used when omitted.

Returns:

Camera – A copy of the camera positioned to frame all meshes in the scene.

Raises:

ValueError – If no meshes provide valid coordinates.

cam_look_at(camera, target, up=array([0., 1., 0.]))[source]¶

Orient a camera so its optical axis points towards a target location.

Parameters:

camera (Camera) – Camera to reorient.
target (np.ndarray) – Target position array with shape (3,) and dtype float64 representing (X, Y, Z) world coordinates the camera should aim at.
up (np.ndarray, optional) – Preferred upward world direction array with shape (3,) and dtype float64 (default is +Y: (0, 1, 0)).

Returns:

Camera – A copy of the camera with updated rotation and ROI center.

Raises:

ValueError – If camera position and target are coincident.

cam_pos_frame_points(points, pixels_num, pixels_size, focal_length, rot_world=(0.0, 0.0, 0.0), fov_scale=1.0, fit_mode=EFrameFit.CONTAIN, target=None)[source]¶

Calculate a camera position that frames a set of world points.

Parameters:

points (numpy.ndarray) – Array of 3D point coordinates (e.g. mesh.coords) to frame.
pixels_num (tuple[int, int] or numpy.ndarray) – Camera sensor resolution in pixels (num_x, num_y).
pixels_size (tuple[float, float] or numpy.ndarray) – Pixel physical dimensions in metres.
focal_length (float) – Camera focal length in metres.
rot_world (tuple, numpy.ndarray, or Rotation, optional) – Euler angles in radians (xyz) or a scipy Rotation (default (0, 0, 0)).
fov_scale (float, optional) – Scale applied to the fitted field of view. Values greater than one leave a border and values below one crop the target (default 1.0).
fit_mode (EFrameFit, optional) – Rule used to select the fitted sensor dimension.
target (numpy.ndarray or None, optional) – Point placed at the image centre. The coordinate bounds centre is used when omitted.

Returns:

numpy.ndarray – Camera world coordinates [x, y, z] to frame the points.

cam_project_points(camera, points)[source]¶

Project 3D world points to 2D image pixel coordinates.

Parameters:

camera (Camera) – Perspective camera model.
points (np.ndarray) – Array of world coordinates with shape (N, 3) and dtype float64 representing (X, Y, Z) points.

Returns:

np.ndarray – Projected image coordinates array with shape (N, 2) and dtype float64 in pixel units (u, v).

crop_image_rectangle(image, pixels_num)[source]¶

Crop an image to its camera extent from the upper left corner.

Parameters:

image (np.ndarray) – Input image array with shape (height, width) or (height, width, channels).
pixels_num (np.ndarray) – Target pixel resolution array with shape (2,) and dtype int32 representing (width, height).

Returns:

np.ndarray – Cropped image array with shape (pixels_num[1], pixels_num[0], ...).

pixel_grid_leng(field_of_view, pixels_size)[source]¶

Build pixel centre coordinate grids for an orthographic camera.

Parameters:

field_of_view (np.ndarray) – Field of view dimensions with shape (2,) and dtype float64 representing (fov_x, fov_y).
pixels_size (float) – Physical pixel size in length units.

Returns:

tuple[np.ndarray, np.ndarray] – Tuple of 2D grid arrays (grid_x, grid_y) with dtype float64.

pixel_vec_leng(field_of_view, pixels_size)[source]¶

Build pixel centre coordinate vectors for an orthographic camera.

Parameters:

field_of_view (np.ndarray) – Field of view dimensions with shape (2,) and dtype float64 representing (fov_x, fov_y).
pixels_size (float) – Physical pixel size in length units.

Returns:

tuple[np.ndarray, np.ndarray] – Tuple of (px_vec_x, px_vec_y) coordinate vectors, each with 1D shape and dtype float64.

stereo_build_faceon(camera, convergence_degrees, roi_pos=None)[source]¶

Build a pair with camera zero face on and camera one converging.

Camera zero is retained unchanged. Camera one is translated along camera zero’s local positive X axis and aimed at roi_pos. When no ROI is supplied, camera.roi_cent_world is used.

Parameters:

camera (Camera) – Base camera for camera zero intrinsics and pose.
convergence_degrees (float) – Convergence angle in degrees.
roi_pos (np.ndarray or None, optional) – Region of interest target point array with shape (3,) and dtype float64. If None, uses camera.roi_cent_world.

Returns:

StereoCameras – Tuple of (camera_0, camera_1) representing the stereo rig.

stereo_build_from_calibration(calibration_path, pos_world_0, rot_world_0, focal_length)[source]¶

Build stereo cameras from a legacy PyVale YAML calibration file.

Parameters:

calibration_path (pathlib.Path) – Path to the calibration YAML file.
pos_world_0 (np.ndarray) – World position array for camera 0 with shape (3,) and dtype float64.
rot_world_0 (scipy.spatial.transform.Rotation) – World orientation for camera 0.
focal_length (float) – Focal length in world length units.

Returns:

StereoCameras – Tuple of (camera_0, camera_1) configured according to calibration.

stereo_build_symmetric(camera, convergence_degrees, roi_pos=None)[source]¶

Build a symmetric convergent pair centred on a reference camera.

The reference camera supplies the midpoint pose and intrinsics. Both returned cameras are placed on its local X axis and aimed at roi_pos.

Parameters:

camera (Camera) – Reference central camera defining midpoint pose and intrinsics.
convergence_degrees (float) – Total convergence angle between the two cameras in degrees.
roi_pos (np.ndarray or None, optional) – Region of interest target point array with shape (3,) and dtype float64. If None, uses camera.roi_cent_world.

Returns:

StereoCameras – Tuple of (camera_0, camera_1) representing the symmetric stereo rig.

stereo_calc_angles(camera_0, camera_1)[source]¶

Calculate relative Euler angles and optical axis convergence.

Parameters:

camera_0 (Camera) – First camera.
camera_1 (Camera) – Second camera.

Returns:

StereoAngles – Relative Euler angles (degrees) and convergence angle (degrees).

stereo_calc_baseline(camera_0, camera_1)[source]¶

Calculate the Euclidean distance between the camera centres.

Parameters:

camera_0 (Camera) – First camera.
camera_1 (Camera) – Second camera.

Returns:

float – Distance between camera positions in world length units.

stereo_calc_extrinsics(camera_0, camera_1)[source]¶

Calculate the camera zero to camera one rigid transformation.

Parameters:

camera_0 (Camera) – First camera (reference frame 0).
camera_1 (Camera) – Second camera (target frame 1).

Returns:

StereoExtrinsics – Rigid transformation containing rotation and translation.

stereo_calc_stand_off(camera_0, camera_1, roi_pos)[source]¶

Calculate midpoint to ROI standoff distance for a stereo pair.

Parameters:

camera_0 (Camera) – First camera.
camera_1 (Camera) – Second camera.
roi_pos (np.ndarray) – Region of interest target coordinate array with shape (3,) and dtype float64.

Returns:

float – Euclidean distance from stereo midpoint to ROI in world units.

stereo_save_calibration_matchid(camera_0, camera_1, calibration_path)[source]¶

Save two cameras in the legacy MatchID .caldat format.

Parameters:

camera_0 (Camera) – Camera 0.
camera_1 (Camera) – Camera 1.
calibration_path (pathlib.Path) – Output path to save the MatchID calibration file.

stereo_save_calibration_yaml(camera_0, camera_1, calibration_path)[source]¶

Save two cameras in PyVale’s legacy YAML calibration format.

Parameters:

camera_0 (Camera) – Camera 0.
camera_1 (Camera) – Camera 1.
calibration_path (pathlib.Path) – Output path to save the YAML file.

subpixel_grid_leng(field_of_view, pixels_size, subsample)[source]¶

Build sub pixel centre coordinate grids.

Parameters:

field_of_view (np.ndarray) – Field of view dimensions with shape (2,) and dtype float64 representing (fov_x, fov_y).
pixels_size (float) – Physical pixel size in length units.
subsample (int) – Number of sub pixel samples per pixel dimension.

Returns:

tuple[np.ndarray, np.ndarray] – Tuple of 2D sub pixel grid arrays (subgrid_x, subgrid_y) with dtype float64.

subpixel_vec_leng(field_of_view, pixels_size, subsample)[source]¶

Build sub pixel centre coordinate vectors.

Parameters:

field_of_view (np.ndarray) – Field of view dimensions with shape (2,) and dtype float64 representing (fov_x, fov_y).
pixels_size (float) – Physical pixel size in length units.
subsample (int) – Number of sub pixel samples per pixel dimension.

Returns:

tuple[np.ndarray, np.ndarray] – Tuple of (subpx_vec_x, subpx_vec_y) coordinate vectors with dtype float64.