pyblenderSDIC.Camera#

class Camera(frame: ~py3dframe.frame.Frame = Frame(origin=[[0.] [0.] [0.]], x_axis=[[1.] [0.] [0.]], y_axis=[[0.] [1.] [0.]], z_axis=[[0.] [0.] [1.]], intrinsic_matrix: ~numpy.ndarray | None = None, resolution: ~typing.Sequence[~numbers.Integral] | ~numpy.ndarray | None = None, pixel_size: ~typing.Sequence[~numbers.Number] | ~numpy.ndarray | None = None, clip_distance: ~typing.Sequence[~numbers.Number] | ~numpy.ndarray | None = None)[source]#

Bases: object

Represents a camera in 3D space with intrinsic parameters, orientation, and position.

The camera orientation is defined by the frame.

The frame of the camera defines the orientation of the camera in 3D space with (convention OPENCV):

origin: The position of the camera in 3D space.
x-axis: The right direction of the camera (left to right).
y-axis: The up direction of the camera (up to down).
z-axis: The optical axis of the camera (from the camera to the scene).

../_images/opencv_camera_frame.png — OpenCV camera frame convention (source: OpenCV)#

The intrinsic parameters of the camera are defined by the following parameters:

focal_length: The focal length of the camera in pixels along the x-axis and y-axis.
principal_point: The principal point of the camera in pixels.

They are represented by the intrinsic matrix of the camera:

\[\begin{split}K = \begin{bmatrix} f_x & 0 & c_x \\ 0 & f_y & c_y \\ 0 & 0 & 1 \end{bmatrix}\end{split}\]

Other parameters of the camera can be stored in the camera object:

resolution: The resolution of the camera in numbers of pixels. A 2-element array representing the resolution of the camera in numbers of pixels along the x and y axes.
pixel_size: The pixel size of the camera in millimeters (distance unit). A 2-element array representing the pixel size of the camera in millimeters along the x and y axes.
clip_distance: The distances in millimeters to the near and far clipping planes. A 2-element array representing the distances of the near and far clipping planes of the camera in millimeters. Only points between the near and far clipping planes are visible in the camera view.

Parameters:

frame (Frame, optional) – The frame of the camera. (see py3dframe : https://https://artezaru.github.io/py3dframe/), default Frame().
intrinsic_matrix (Optional[numpy.ndarray], optional) – The intrinsic matrix of the camera. (3x3 matrix), by default None. The intrinsic matrix is a 3x3 matrix representing the intrinsic parameters of the camera.
resolution (Optional[Union[Sequence[Integral], numpy.ndarray]], optional) – The resolution of the camera in numbers of pixels, by default None. The two values are used for x and y axes respectively.
pixel_size (Optional[Union[Sequence[Number], numpy.ndarray]], optional) – The pixel size of the camera in the millimeters of the camera, by default None. The two values are used for x and y axes respectively. The pixel size is the size of a single pixel in the millimeters of the camera.
clip_distance (Optional[Union[NSequence[Number], numpy.ndarray]], optional) – The distance of the near and far clipping planes of the camera, by default None. The two values are used for near and far clipping planes respectively.

property OpenCV_rvec: ndarray#

Get or set the rotation vector of the camera in the OpenCV format.

The axis of the camera frame for OpenCV are the same as the Camera frame. Furthermore, the convention for OpenCV is \(X_{cam} = R X_{world} + T\), convention=4 for py3dframe.

Returns:: The rotation vector of the camera with shape (3,).
Return type:: numpy.ndarray

property OpenCV_tvec: ndarray#

Get or set the translation vector of the camera in the OpenCV format.

The axis of the camera frame for OpenCV are the same as the Camera frame. Furthermore, the convention for OpenCV is \(X_{cam} = R X_{world} + T\), convention=4 for py3dframe.

Returns:: The translation vector of the camera with shape (3,).
Return type:: numpy.ndarray

property aspect_ratio: float | None#

Get the aspect ratio of the camera.

The aspect ratio is a float representing the aspect ratio of the camera.

The aspect ratio is calculated as the ratio of the pixel aspect in y direction to the pixel aspect in x direction.

Returns:: The aspect ratio of the camera. (or None if fx or fy is not set)
Return type:: Optional[float]

property clfar: float#

property clip_distance: Tuple[float | None, float | None]#

Get or set the near and far clipping planes of the camera in millimeters.

The near and far clipping planes are a tuple of two floats representing the near and far clipping planes of the camera in millimeters. Only points between the near and far clipping planes are visible in the camera view.

Returns:: The near and far clipping planes of the camera in millimeters. (or None if not set)
Return type:: Tuple[Optional[float], Optional[float]]

property clip_distance_far: float | None#

Get or set the far clipping plane of the camera in millimeters.

The far clipping plane is a float representing the far clipping plane of the camera in millimeters. Only points between the near and far clipping planes are visible in the camera view.

Note

An alias for clip_distance_far is clfar.

See also

pyblenderSDIC.Camera.clip_distance_near() or clnear to set the near clipping plane in millimeters.

Returns:: The far clipping plane of the camera in millimeters. (or None if not set)
Return type:: Optional[float]

property clip_distance_near: float | None#

Get or set the near clipping plane of the camera in millimeters.

The near clipping plane is a float representing the near clipping plane of the camera in millimeters. Only points between the near and far clipping planes are visible in the camera view.

Note

An alias for clip_distance_near is clnear.

See also

pyblenderSDIC.Camera.clip_distance_far() or clfar to set the far clipping plane in millimeters.

Returns:: The near clipping plane of the camera in millimeters. (or None if not set)
Return type:: Optional[float]

property clnear: float#

property cx: float#

property cy: float#

property focal_length: Tuple[float | None, float | None]#

Get or set the focal length of the camera in pixels.

The focal length is a tuple of two floats representing the focal length of the camera in pixels in x and y directions.

Returns:: The focal length of the camera in pixels. (or None if not set)
Return type:: Tuple[Optional[float], Optional[float]]

property focal_length_x: float | None#

Get or set the focal length of the camera in pixels in x direction.

The focal length is a float representing the focal length of the camera in pixels in x direction.

This parameter is the component K[0, 0] of the intrinsic matrix K of the camera.

Note

An alias for focal_length_x is fx.

See also

pyblenderSDIC.Camera.focal_length_y() or fy to set the focal length in pixels in y direction.

Returns:: The focal length of the camera in pixels in x direction. (or None if not set)
Return type:: Optional[float]

property focal_length_y: float | None#

Get or set the focal length of the camera in pixels in y direction.

The focal length is a float representing the focal length of the camera in pixels in y direction.

This parameter is the component K[1, 1] of the intrinsic matrix K of the camera.

Note

An alias for focal_length_y is fy.

See also

pyblenderSDIC.Camera.focal_length_x() or fx to set the focal length in pixels in x direction.

Returns:: The focal length of the camera in pixels in y direction. (or None if not set)
Return type:: Optional[float]

property frame: Frame#

Get or set the frame of the camera.

The frame of the camera defines the orientation of the camera in 3D space. The camera observes the scene along the z-axis of the frame.

The frame of the camera defines the orientation of the camera in 3D space with (convention OPENCV):

origin: The position of the camera in 3D space.
x-axis: The right direction of the camera (left to right).
y-axis: The up direction of the camera (up to down).
z-axis: The optical axis of the camera (from the camera to the scene).

See also

https://artezaru.github.io/py3dframe/ for more information about the frame.

Returns:: The frame of the camera.
Return type:: Frame

classmethod from_dict(data: Dict) → Camera[source]#

Create a Camera instance from a dictionary.

The structure of the dictionary should be as provided by the pysdic.Camera.save_to_dict() method.

If focal_length, resolution, pixel_size, or principal_point are not provided, the default values are used.

The other keys are ignored.

Parameters:: data (dict) – A dictionary containing the camera’s data.
Returns:: The Camera instance.
Return type:: Camera
Raises:: ValueError – If the data is not a dictionary.

classmethod from_json(filename: str) → Camera[source]#

Create a Camera instance from a JSON file.

The structure of the JSON file follows the pysdic.camera.Camera.to_dict() method.

Parameters:: filename (str) – The path to the JSON file.
Returns:: A Camera instance.
Return type:: Camera
Raises:: FileNotFoundError – If the filename is not a valid path.

property fx: float#

property fy: float#

get_OpenCV_RT() → Tuple[Rotation, ndarray][source]#

Get the rotation and translation of the camera in the OpenCV format.

The axis of the camera frame for OpenCV are the same as the Camera frame. Furthermore, the convention for OpenCV is \(X_{cam} = R X_{world} + T\), convention=4 for py3dframe.

Returns:

Rotation – The rotation of the camera.
numpy.ndarray – The translation of the camera with shape (3, 1).

get_OpenGL_RT() → Tuple[Rotation, ndarray][source]#

Get the rotation and translation of the camera in the OpenGL format.

The axis of the camera frame for OpenGL are different from the Camera frame: - x-axis: The same as the Camera frame : right direction of the camera (left to right). - y-axis: The opposite of the Camera frame : up direction of the camera (down to up). - z-axis: The opposite of the Camera frame : (from the scene to the camera).

Furthermore, the convention for OpenGL is \(X_{world} = R X_{cam} + T\), convention=0 for py3dframe.

Returns:

Rotation – The rotation of the camera.
numpy.ndarray – The translation of the camera with shape (3, 1).

property intrinsic_matrix: ndarray | None#

Get or set the intrinsic matrix of the camera.

The intrinsic matrix is a 3x3 matrix representing the intrinsic parameters of the camera.

\[\begin{split}K = \begin{bmatrix} f_x & 0 & c_x \\ 0 & f_y & c_y \\ 0 & 0 & 1 \end{bmatrix}\end{split}\]

Returns:: The intrinsic matrix of the camera. (or None if not set)
Return type:: Optional[numpy.ndarray]

is_complete() → bool[source]#

Check if the camera is complete.

A camera is complete if all intrinsic parameters are set.

Returns:: True if the camera is complete, False otherwise.
Return type:: bool

property lens: float | None#

Get the lens of the camera in millimeters.

The lens is a float representing the focal length of the camera in millimeters.

The lens is calculated as follows:

\[f = \frac{f_x \cdot s}{vf}\]

where \(f_x\) is the focal length in pixels in x direction, \(s\) is the sensor size in millimeters and \(vf\) is the view factor of the camera.

Warning

This lens is only for Blender. No reel physical meaning.

Returns:: The lens of the camera in millimeters. (or None if fx, fy, px, py, rx or ry is not set)
Return type:: Optional[float]

property pixel_aspect_x: float | None#

Get the pixel aspect of the camera in x direction.

The pixel aspect is a float representing the pixel aspect of the camera in x direction.

If \(f_x < f_y\), the pixel aspect is calculated as \(\frac{f_y}{f_x}\). If \(f_x \geq f_y\), the aspect ratio is 1.

Returns:: The pixel aspect of the camera in x direction. (or None if fx or fy is not set)
Return type:: Optional[float]

property pixel_aspect_y: float | None#

Get the pixel aspect of the camera in y direction.

The pixel aspect is a float representing the pixel aspect of the camera in y direction.

If \(f_y < f_x\), the pixel aspect is calculated as \(\frac{f_x}{f_y}\). If \(f_y \geq f_x\), the aspect ratio is 1.

Returns:: The pixel aspect of the camera in y direction. (or None if fx or fy is not set)
Return type:: Optional[float]

property pixel_size: Tuple[float | None, float | None]#

Get or set the pixel size of the camera in millimeters.

The pixel size is a tuple of two floats representing the pixel size of the camera in millimeters in x and y directions.

Returns:: The pixel size of the camera in millimeters. (or None if not set)
Return type:: Tuple[Optional[float], Optional[float]]

property pixel_size_x: float | None#

Get or set the pixel size of the camera in millimeters in x direction.

The pixel size is a float representing the pixel size of the camera in millimeters in x direction.

Note

An alias for pixel_size_x is px.

See also

pyblenderSDIC.Camera.pixel_size_y() or py to set the pixel size in millimeters in y direction.

Returns:: The pixel size of the camera in millimeters in x direction. (or None if not set)
Return type:: Optional[float]

property pixel_size_y: float | None#

Get or set the pixel size of the camera in millimeters in y direction.

The pixel size is a float representing the pixel size of the camera in millimeters in y direction.

Note

An alias for pixel_size_y is py.

See also

pyblenderSDIC.Camera.pixel_size_x() or px to set the pixel size in millimeters in x direction.

Returns:: The pixel size of the camera in millimeters in y direction. (or None if not set)
Return type:: Optional[float]

property principal_point: Tuple[float | None, float | None]#

Get or set the principal point of the camera in pixels.

The principal point is a tuple of two floats representing the principal point of the camera in pixels in x and y directions.

Returns:: The principal point of the camera in pixels. (or None if not set)
Return type:: Tuple[Optional[float], Optional[float]]

property principal_point_x: float | None#

Get or set the principal point of the camera in pixels in x direction.

The principal point is a float representing the principal point of the camera in pixels in x direction.

This parameter is the component K[0, 2] of the intrinsic matrix K of the camera.

Note

An alias for principal_point_x is cx.

See also

pyblenderSDIC.Camera.principal_point_y() or cy to set the principal point in pixels in y direction.

Returns:: The principal point of the camera in pixels in x direction. (or None if not set)
Return type:: Optional[float]

property principal_point_y: float | None#

Get or set the principal point of the camera in pixels in y direction.

The principal point is a float representing the principal point of the camera in pixels in y direction.

This parameter is the component K[1, 2] of the intrinsic matrix K of the camera.

Note

An alias for principal_point_y is cy.

See also

pyblenderSDIC.Camera.principal_point_x() or cx to set the principal point in pixels in x direction.

Returns:: The principal point of the camera in pixels in y direction. (or None if not set)
Return type:: Optional[float]

property px: float#

property py: float#

property resolution: Tuple[float | None, float | None]#

Get or set the resolution of the camera in number of pixels.

The resolution is a tuple of two floats representing the resolution of the camera in number of pixels in x and y directions.

Returns:: The resolution of the camera in number of pixels. (or None if not set)
Return type:: Tuple[Optional[float], Optional[float]]

property resolution_x: float | None#

Get or set the resolution of the camera in number of pixels in x direction.

The resolution is a float representing the resolution of the camera in number of pixels in x direction.

Note

An alias for resolution_x is rx.

See also

pyblenderSDIC.Camera.resolution_y() or ry to set the resolution in number of pixels in y direction.

Returns:: The resolution of the camera in number of pixels in x direction. (or None if not set)
Return type:: Optional[float]

property resolution_y: float | None#

Get or set the resolution of the camera in number of pixels in y direction.

The resolution is a float representing the resolution of the camera in number of pixels in y direction.

Note

An alias for resolution_y is ry.

See also

pyblenderSDIC.Camera.resolution_x() or rx to set the resolution in number of pixels in x direction.

Returns:: The resolution of the camera in number of pixels in y direction. (or None if not set)
Return type:: Optional[float]

property rx: float#

property ry: float#

property sensor_fit: str | None#

Get the sensor fit of the camera (“HORIZONTAL” or “VERTICAL”).

The sensor fit is a string representing the sensor fit of the camera.

If \(a_x \cdot r_x \geq a_y \cdot r_y\), the sensor fit is “HORIZONTAL”. If \(a_x \cdot r_x < a_y \cdot r_y\), the sensor fit is “VERTICAL”.

where \(a_x\) and \(a_y\) are the pixel aspect in x and y direction respectively and \(r_x\) and \(r_y\) are the resolution in number of pixels in x and y direction respectively.

Returns:: The sensor fit of the camera. (or None if fx, fy or rx, ry is not set)
Return type:: str

property sensor_height: float | None#

property sensor_size: float | None#

Get the sensor size of the camera in millimeters.

If the sensor fit is “HORIZONTAL”, the sensor size is directly the sensor size in x direction. If the sensor fit is “VERTICAL”, the sensor size is directly the sensor size in y direction.

Warning

This sensor size is only for Blender. No reel physical meaning.

Returns:: The sensor size of the camera in millimeters. (or None if fx, fy, px, py, rx or ry is not set)
Return type:: Optional[float]

property sensor_size_x: float | None#

Get the sensor size of the camera in millimeters in x direction.

The sensor size is a float representing the sensor size of the camera in millimeters in x direction.

The sensor size is calculated as the product of the pixel size and the resolution of the camera.

Note

An alias for sensor_size_x is sensor_width.

Returns:: The sensor size of the camera in millimeters in x direction. (or None if px or rx is not set)
Return type:: Optional[float]

property sensor_size_y: float | None#

Get the sensor size of the camera in millimeters in y direction.

The sensor size is a float representing the sensor size of the camera in millimeters in y direction.

The sensor size is calculated as the product of the pixel size and the resolution of the camera.

Note

An alias for sensor_size_y is sensor_height.

Returns:: The sensor size of the camera in millimeters in y direction. (or None if py or ry is not set)
Return type:: Optional[float]

property sensor_width: float | None#

set_OpenCV_RT(rotation: Rotation, translation: ndarray) → None[source]#

Set the rotation and translation of the camera in the OpenCV format.

The axis of the camera frame for OpenCV are the same as the Camera frame. Furthermore, the convention for OpenCV is \(X_{cam} = R X_{world} + T\), convention=4 for py3dframe.

Parameters:

rotation (Rotation) – The rotation of the camera.
translation (numpy.ndarray) – The translation of the camera with shape (3, 1).

set_OpenGL_RT(rotation: Rotation, translation: ndarray) → None[source]#

Set the rotation and translation of the camera in the OpenGL format.

Furthermore, the convention for OpenGL is \(X_{world} = R X_{cam} + T\), convention=0 for py3dframe.

Parameters:

rotation (Rotation) – The rotation of the camera.
translation (numpy.ndarray) – The translation of the camera with shape (3, 1).

property shift_x: float | None#

Get the shift x of the camera in pixels.

The shift x is a float representing the shift x of the camera in pixels.

The shift x is calculated as follows:

\[sx = \frac{c_x - (r_x - 1) / 2}{vf}\]

where \(c_x\) is the principal point in pixels in x direction, \(r_x\) is the resolution in number of pixels in x direction and \(vf\) is the view factor of the camera.

Warning

This shift x is only for Blender. No reel physical meaning.

Returns:: The shift x of the camera in pixels. (or None if fx, fy, px, py, rx or ry is not set)
Return type:: Optional[float]

property shift_y: float | None#

Get the shift y of the camera in pixels.

The shift y is a float representing the shift y of the camera in pixels.

The shift y is calculated as follows:

\[sy = \frac{(c_y - (r_y - 1) / 2) ar}{vf}\]

where \(c_y\) is the principal point in pixels in y direction, \(r_y\) is the resolution in number of pixels in y direction, \(vf\) is the view factor of the camera and \(ar\) is the aspect ratio of the camera.

Warning

This shift y is only for Blender. No reel physical meaning.

Returns:: The shift y of the camera in pixels. (or None if fx, fy, px, py, rx or ry is not set)
Return type:: Optional[float]

to_dict(description: str | None = None) → Dict[source]#

Export the Camera’s data to a dictionary.

The structure of the dictionary is as follows:

{
    "type": "Camera [pyblenderSDIC]",
    "description": "Description of the camera",
    "frame": {
        "translation": [float, float, float],
        "rotvec": [float, float, float],
        "convention": 0,
        "parent": None
    },
    "fx": float,
    "fy": float,
    "cx": float,
    "cy": float,
    "rx": int,
    "ry": int,
    "px": float,
    "py": float,
    "clnear": float,
    "clfar": float
    }
}

Parameters:: description (Optional[str]) – A description of the camera, by default None. This message will be included in the dictionary under the key “description” if provided.
Returns:: A dictionary containing the camera’s data.
Return type:: dict
Raises:: ValueError – If the description is not a string.

to_json(filename: str, description: str | None = None) → None[source]#

Export the Camera’s data to a JSON file.

The structure of the JSON file follows the pysdic.camera.Camera.to_dict() method.

Parameters:

filename (str) – The path to the JSON file.
description (Optional[str]) – A description of the camera, by default None. This message will be included in the JSON file under the key “description” if provided.

Raises:

FileNotFoundError – If the filename is not a valid path.

property view_factor: float | None#

Get the view factor of the camera.

The view factor is a float representing the view factor of the camera.

If the sensor fit is “HORIZONTAL”, the view factor is directly the resolution in number of pixels in x direction. If the sensor fit is “VERTICAL”, the view factor is calculated as the product of the aspect ratio and the resolution in number of pixels in y direction.

Warning

This view factor is only for Blender. No reel physical meaning.

Returns:: The view factor of the camera. (or None if fx, fy or rx, ry is not set)
Return type:: Optional[float]

pyblenderSDIC.Camera#

This Page