pymomentum.camera

Camera classes for projection and rendering in pymomentum.

class pymomentum.camera.Camera

Bases: pybind11_object

Camera for rendering

property T_eye_from_world: Transform from world space to camera/eye space

property T_world_from_eye: Transform from world space to camera/eye space

__init__(self: pymomentum.camera.Camera, intrinsics_model: pymomentum.camera.IntrinsicsModel, eye_from_world: numpy.ndarray[numpy.float32[4, 4]] | None = None) → None

Create a camera with specified intrinsics and pose.

Parameters:

intrinsics_model – Camera intrinsics model defining focal length, principal point, and image dimensions.
eye_from_world – Optional 4x4 transformation matrix from world space to camera/eye space. Defaults to identity matrix if not provided.

Returns:

A new Camera instance with the specified intrinsics and pose.

property center_of_projection: Position of the camera center in world space

crop(self: pymomentum.camera.Camera, top: int, left: int, width: int, height: int) → pymomentum.camera.Camera

Create a new camera with cropped image region.

Parameters:

top – Top offset in pixels.
left – Left offset in pixels.
width – New width in pixels after cropping.
height – New height in pixels after cropping.

Returns:

A new Camera instance with cropped intrinsics and same pose.

frame(self: pymomentum.camera.Camera, points: numpy.ndarray[numpy.float32], min_z: float = 0.10000000149011612, edge_padding: float = 0.05000000074505806) → pymomentum.camera.Camera

Adjust the camera position to ensure all specified points are in view.

Parameters:

points – (N x 3) array of 3D points that should be visible in the camera view.
min_z – Minimum distance from camera to maintain. Defaults to 0.1.
edge_padding – Padding factor to add around the points as a fraction of the image size. Defaults to 0.05.

Returns:

A new Camera instance positioned to frame all the specified points.

property fx: Focal length in x direction (pixels)

property fy: Focal length in y direction (pixels)

property image_height: Height of the image in pixels

property image_width: Width of the image in pixels

property intrinsics_model: The camera’s intrinsics model

look_at(self: pymomentum.camera.Camera, position: numpy.ndarray[numpy.float32[3, 1]], target: numpy.ndarray[numpy.float32[3, 1]] | None = None, up: numpy.ndarray[numpy.float32[3, 1]] | None = None) → pymomentum.camera.Camera

Position the camera to look at a specific target point.

Parameters:

position – 3D position where the camera should be placed.
target – 3D point the camera should look at. Defaults to origin (0,0,0) if not provided.
up – Up vector for camera orientation. Defaults to (0,1,0) if not provided.

Returns:

A new Camera instance positioned to look at the target.

project(self: pymomentum.camera.Camera, world_points: numpy.ndarray[numpy.float32]) → numpy.ndarray[numpy.float32]

Project 3D points from world space to 2D image coordinates.

Parameters:: world_points – (N x 3) array of 3D points in world coordinate space to project.
Returns:: (N x 3) array of projected points where columns are [x, y, depth] in image coordinates.

unproject(self: pymomentum.camera.Camera, image_points: numpy.ndarray[numpy.float32]) → numpy.ndarray[numpy.float32]

Unproject 3D image coordinates to 3D points in world space.

Parameters:: image_points – (N x 3) array of 3D points in image coordinates [x, y, depth].
Returns:: (N x 3) array of 3D points in world coordinate space.

upsample(self: pymomentum.camera.Camera, factor: float) → pymomentum.camera.Camera

Create a new camera with upsampled resolution by the given factor.

Parameters:: factor – Upsampling factor (e.g., 2.0 doubles the resolution).
Returns:: A new Camera instance with upsampled intrinsics and same pose.

property world_space_principle_axis: Camera world-space principal axis (direction the camera is looking)

class pymomentum.camera.IntrinsicsModel

Bases: pybind11_object

Base class for camera intrinsics models

__init__(*args, **kwargs)

clone(self: pymomentum.camera.IntrinsicsModel) → pymomentum.camera.IntrinsicsModel

Create a deep copy of this intrinsics model.

The returned model is mutable and can be modified for optimization purposes.

Returns:: A new IntrinsicsModel instance that is an independent copy.

crop(self: pymomentum.camera.IntrinsicsModel, top: int, left: int, width: int, height: int) → pymomentum.camera.IntrinsicsModel

Create a new intrinsics model cropped to a sub-region of the image.

Parameters:

top – Top offset in pixels.
left – Left offset in pixels.
width – New width in pixels after cropping.
height – New height in pixels after cropping.

Returns:

A new IntrinsicsModel instance with cropped parameters.

downsample(self: pymomentum.camera.IntrinsicsModel, factor: float) → pymomentum.camera.IntrinsicsModel

Create a new intrinsics model downsampled by the given factor.

Parameters:: factor – Downsampling factor (e.g., 2.0 halves the resolution).
Returns:: A new IntrinsicsModel instance with downsampled parameters.

property fx: Focal length in x direction (pixels)

property fy: Focal length in y direction (pixels)

get_intrinsic_parameters(self: pymomentum.camera.IntrinsicsModel) → numpy.ndarray[numpy.float32[m, 1]]

Get all intrinsic parameters as a vector.

Parameter order is model-specific: - PinholeIntrinsicsModel: [fx, fy, cx, cy] (4 parameters) - OpenCVIntrinsicsModel: [fx, fy, cx, cy, k1, k2, k3, k4, k5, k6, p1, p2, p3, p4] (14 parameters) - OpenCVFisheyeIntrinsicsModel: [fx, fy, cx, cy, k1, k2, k3, k4] (8 parameters)

Returns:: Vector of intrinsic parameters.

property image_height: Height of the image in pixels

property image_width: Width of the image in pixels

property name: Name identifier for this camera (used in parameter transform naming)

property num_intrinsic_parameters: Number of intrinsic parameters for this model

property parameter_names: List of intrinsic parameter names (e.g., [‘fx’, ‘fy’, ‘cx’, ‘cy’]).

project(self: pymomentum.camera.IntrinsicsModel, points: numpy.ndarray[numpy.float32]) → numpy.ndarray[numpy.float32]

Project 3D points in camera space to 2D image coordinates.

Parameters:: points – (N x 3) array of 3D points in camera coordinate space to project.
Returns:: (N x 3) array of projected points where columns are [x, y, depth] in image coordinates.

project_intrinsics_jacobian(self: pymomentum.camera.IntrinsicsModel, point: numpy.ndarray[numpy.float32[3, 1]]) → tuple[numpy.ndarray[numpy.float32[3, 1]], numpy.ndarray[numpy.float32[m, n]], bool]

Compute the Jacobian of projection with respect to intrinsic parameters.

Parameters:: point – 3D point in camera coordinate space.
Returns:: Tuple of (projected point, Jacobian matrix [3 x num_params], valid flag). The Jacobian rows are [du/d*, dv/d*, 0] where * represents each intrinsic parameter.

resize(self: pymomentum.camera.IntrinsicsModel, image_width: int, image_height: int) → pymomentum.camera.IntrinsicsModel

Create a new intrinsics model resized to new image dimensions.

Parameters:

image_width – New image width in pixels.
image_height – New image height in pixels.

Returns:

A new IntrinsicsModel instance with resized parameters.

set_intrinsic_parameters(self: pymomentum.camera.IntrinsicsModel, params: numpy.ndarray[numpy.float32[m, 1]]) → None

Set all intrinsic parameters from a vector.

Parameter order must match get_intrinsic_parameters().

Parameters:: params – Vector of parameters (must match num_intrinsic_parameters).

upsample(self: pymomentum.camera.IntrinsicsModel, factor: float) → pymomentum.camera.IntrinsicsModel

Create a new intrinsics model upsampled by the given factor.

Parameters:: factor – Upsampling factor (e.g., 2.0 doubles the resolution).
Returns:: A new IntrinsicsModel instance with upsampled parameters.

class pymomentum.camera.OpenCVDistortionParameters

Bases: pybind11_object

OpenCV distortion parameters

__init__(self: pymomentum.camera.OpenCVDistortionParameters) → None: Initialize with default parameters (no distortion)

property k1: Radial distortion coefficient k1

property k2: Radial distortion coefficient k2

property k3: Radial distortion coefficient k3

property k4: Radial distortion coefficient k4

property k5: Radial distortion coefficient k5

property k6: Radial distortion coefficient k6

property p1: Tangential distortion coefficient p1

property p2: Tangential distortion coefficient p2

property p3: Tangential distortion coefficient p3

property p4: Tangential distortion coefficient p4

class pymomentum.camera.OpenCVFisheyeDistortionParameters

Bases: pybind11_object

Distortion parameters for the OpenCV fisheye (equidistant) camera model.

This struct holds four radial distortion coefficients (k1-k4) used by the equidistant fisheye projection model. Unlike the standard OpenCV model, there are no tangential distortion terms.

See OpenCVFisheyeIntrinsicsModel for the projection equations.

__init__(self: pymomentum.camera.OpenCVFisheyeDistortionParameters) → None: Initialize with default parameters (no distortion)

property k1: First radial distortion coefficient

property k2: Second radial distortion coefficient

property k3: Third radial distortion coefficient

property k4: Fourth radial distortion coefficient

class pymomentum.camera.OpenCVFisheyeIntrinsicsModel

Bases: IntrinsicsModel

OpenCV fisheye (equidistant) camera intrinsics model with radial distortion.

This model implements the equidistant fisheye projection used by OpenCV’s cv::fisheye module. The projection equations are:

Normalize: a = x/z, b = y/z
r = sqrt(a² + b²), theta = atan(r)
theta_d = theta * (1 + k1*θ² + k2*θ⁴ + k3*θ⁶ + k4*θ⁸)
x' = (theta_d / r) * a, y' = (theta_d / r) * b
u = fx * x' + cx, v = fy * y' + cy

See OpenCVFisheyeDistortionParameters for the distortion coefficients.

__init__(self: pymomentum.camera.OpenCVFisheyeIntrinsicsModel, image_width: int, image_height: int, fx: float | None = None, fy: float | None = None, cx: float | None = None, cy: float | None = None, distortion_params: pymomentum.camera.OpenCVFisheyeDistortionParameters | None = None) → None

Create an OpenCV fisheye camera model with specified parameters and optional distortion.

Parameters:

image_width – Width of the image in pixels.
image_height – Height of the image in pixels.
fx – Focal length in x direction (pixels). Defaults to computed value based on 50mm equivalent lens.
fy – Focal length in y direction (pixels). Defaults to computed value based on 50mm equivalent lens.
cx – Principal point x-coordinate (pixels). Defaults to image center if not provided.
cy – Principal point y-coordinate (pixels). Defaults to image center if not provided.
distortion_params – Optional OpenCVFisheyeDistortionParameters. Defaults to no distortion if not provided.

Returns:

A new OpenCVFisheyeIntrinsicsModel instance.

property cx: Principal point x-coordinate (pixels)

property cy: Principal point y-coordinate (pixels)

class pymomentum.camera.OpenCVIntrinsicsModel

Bases: IntrinsicsModel

OpenCV camera intrinsics model with distortion

__init__(self: pymomentum.camera.OpenCVIntrinsicsModel, image_width: int, image_height: int, fx: float | None, fy: float | None, cx: float | None, cy: float | None, distortion_params: pymomentum.camera.OpenCVDistortionParameters | None = None) → None

Create an OpenCV camera model with specified parameters and optional distortion.

Parameters:

image_width – Width of the image in pixels.
image_height – Height of the image in pixels.
fx – Focal length in x direction (pixels).
fy – Focal length in y direction (pixels).
cx – Principal point x-coordinate (pixels).
cy – Principal point y-coordinate (pixels).
distortion_params – Optional OpenCV distortion parameters. Defaults to no distortion if not provided.

Returns:

A new OpenCVIntrinsicsModel instance.

property cx: Principal point x-coordinate (pixels)

property cy: Principal point y-coordinate (pixels)

class pymomentum.camera.PinholeIntrinsicsModel

Bases: IntrinsicsModel

Pinhole camera intrinsics model without distortion

__init__(self: pymomentum.camera.PinholeIntrinsicsModel, image_width: int, image_height: int, fx: float | None = None, fy: float | None = None, cx: float | None = None, cy: float | None = None) → None

Create a pinhole camera model with specified focal lengths and image dimensions.

Parameters:

image_width – Width of the image in pixels.
image_height – Height of the image in pixels.
fx – Focal length in x direction (pixels). Defaults to computed value based on 50mm equivalent lens.
fy – Focal length in y direction (pixels). Defaults to computed value based on 50mm equivalent lens.
cx – Principal point x-coordinate (pixels). Defaults to image center if not provided.
cy – Principal point y-coordinate (pixels). Defaults to image center if not provided.

Returns:

A new PinholeIntrinsicsModel instance.

property cx: Principal point x-coordinate (pixels)

property cy: Principal point y-coordinate (pixels)