tensorbay.sensor.intrinsics#

Basic concepts of camera intrinsics.

class tensorbay.sensor.intrinsics.CameraMatrix(fx=None, fy=None, cx=None, cy=None, skew=0, *, matrix=None)[source]#

Bases: tensorbay.utility.repr.ReprMixin, tensorbay.utility.attr.AttrsMixin

CameraMatrix represents camera matrix.

Camera matrix describes the mapping of a pinhole camera model from 3D points in the world to 2D points in an image.

Parameters
  • fx (float) – The x axis focal length expressed in pixels.

  • fy (float) – The y axis focal length expressed in pixels.

  • cx (float) – The x coordinate of the so called principal point that should be in the center of the image.

  • cy (float) – The y coordinate of the so called principal point that should be in the center of the image.

  • skew (float) – It causes shear distortion in the projected image.

  • matrix (Optional[Union[Sequence[Sequence[float]], numpy.ndarray]]) – A 3x3 Sequence of camera matrix.

Return type

None

fx#

The x axis focal length expressed in pixels.

Type

float

fy#

The y axis focal length expressed in pixels.

Type

float

cx#

The x coordinate of the so called principal point that should be in the center of the image.

Type

float

cy#

The y coordinate of the so called principal point that should be in the center of the image.

Type

float

skew#

It causes shear distortion in the projected image.

Type

float

Raises

TypeError – When only keyword arguments with incorrect keys are provided, or when no arguments are provided.

Parameters
  • fx (float) –

  • fy (float) –

  • cx (float) –

  • cy (float) –

  • skew (float) –

  • matrix (Optional[Union[Sequence[Sequence[float]], numpy.ndarray]]) –

Return type

None

Examples

>>> matrix = [[1, 3, 3],
...           [0, 2, 4],
...           [0, 0, 1]]

Initialazation Method 1: Init from 3x3 sequence array.

>>> camera_matrix = CameraMatrix(matrix=matrix)
>>> camera_matrix
CameraMatrix(
    (fx): 1,
    (fy): 2,
    (cx): 3,
    (cy): 4,
    (skew): 3
)

Initialazation Method 2: Init from camera calibration parameters, skew is optional.

>>> camera_matrix = CameraMatrix(fx=1, fy=2, cx=3, cy=4, skew=3)
>>> camera_matrix
CameraMatrix(
    (fx): 1,
    (fy): 2,
    (cx): 3,
    (cy): 4,
    (skew): 3
)
classmethod loads(contents)[source]#

Loads CameraMatrix from a dict containing the information of the camera matrix.

Parameters

contents (Mapping[str, float]) – A dict containing the information of the camera matrix.

Returns

A CameraMatrix instance contains the information from the contents dict.

Return type

tensorbay.sensor.intrinsics._T

Examples

>>> contents = {
...     "fx": 2,
...     "fy": 6,
...     "cx": 4,
...     "cy": 7,
...     "skew": 3
... }
>>> camera_matrix = CameraMatrix.loads(contents)
>>> camera_matrix
CameraMatrix(
    (fx): 2,
    (fy): 6,
    (cx): 4,
    (cy): 7,
    (skew): 3
)
dumps()[source]#

Dumps the camera matrix into a dict.

Returns

A dict containing the information of the camera matrix.

Return type

Dict[str, float]

Examples

>>> camera_matrix.dumps()
{'fx': 1, 'fy': 2, 'cx': 3, 'cy': 4, 'skew': 3}
as_matrix()[source]#

Return the camera matrix as a 3x3 numpy array.

Returns

A 3x3 numpy array representing the camera matrix.

Return type

numpy.ndarray

Examples

>>> numpy_array = camera_matrix.as_matrix()
>>> numpy_array
array([[1., 3., 3.],
       [0., 4., 4.],
       [0., 0., 1.]])
project(point)[source]#

Project a point to the pixel coordinates.

Parameters

point (Sequence[float]) – A Sequence containing the coordinates of the point to be projected.

Returns

The pixel coordinates.

Raises

TypeError – When the dimension of the input point is neither two nor three.

Return type

tensorbay.geometry.vector.Vector2D

Examples

Project a point in 2 dimensions

>>> camera_matrix.project([1, 2])
Vector2D(12, 19)

Project a point in 3 dimensions

>>> camera_matrix.project([1, 2, 4])
Vector2D(6.0, 10.0)
class tensorbay.sensor.intrinsics.DistortionCoefficients(**kwargs)[source]#

Bases: tensorbay.utility.repr.ReprMixin, tensorbay.utility.attr.AttrsMixin

DistortionCoefficients represents camera distortion coefficients.

Distortion is the deviation from rectilinear projection including radial distortion and tangential distortion.

Parameters
  • **kwargs – Float values with keys: k1, k2, … and p1, p2, …

  • kwargs (float) –

Raises

TypeError – When tangential and radial distortion is not provided to initialize class.

Return type

None

Examples

>>> distortion_coefficients = DistortionCoefficients(p1=1, p2=2, k1=3, k2=4)
>>> distortion_coefficients
DistortionCoefficients(
    (p1): 1,
    (p2): 2,
    (k1): 3,
    (k2): 4
)
classmethod loads(contents)[source]#

Loads DistortionCoefficients from a dict containing the information.

Parameters

contents (Mapping[str, float]) – A dict containig distortion coefficients of a camera.

Returns

A DistortionCoefficients instance containing information from the contents dict.

Return type

tensorbay.sensor.intrinsics._T

Examples

>>> contents = {
...     "p1": 1,
...     "p2": 2,
...     "k1": 3,
...     "k2": 4
... }
>>> distortion_coefficients = DistortionCoefficients.loads(contents)
>>> distortion_coefficients
DistortionCoefficients(
    (p1): 1,
    (p2): 2,
    (k1): 3,
    (k2): 4
)
dumps()[source]#

Dumps the distortion coefficients into a dict.

Returns

A dict containing the information of distortion coefficients.

Return type

Dict[str, float]

Examples

>>> distortion_coefficients.dumps()
{'p1': 1, 'p2': 2, 'k1': 3, 'k2': 4}
distort(point, is_fisheye=False)[source]#

Add distortion to a point.

Parameters
  • point (Sequence[float]) – A Sequence containing the coordinates of the point to be distorted.

  • is_fisheye (bool) – Whether the sensor is fisheye camera, default is False.

Raises

TypeError – When the dimension of the input point is neither two nor three.

Returns

Distorted 2d point.

Return type

tensorbay.geometry.vector.Vector2D

Examples

Distort a point with 2 dimensions

>>> distortion_coefficients.distort((1.0, 2.0))
Vector2D(134.0, 253.0)

Distort a point with 3 dimensions

>>> distortion_coefficients.distort((1.0, 2.0, 3.0))
Vector2D(3.3004115226337447, 4.934156378600823)

Distort a point with 2 dimensions, fisheye is True

>>> distortion_coefficients.distort((1.0, 2.0), is_fisheye=True)
Vector2D(6.158401093771876, 12.316802187543752)
class tensorbay.sensor.intrinsics.CameraIntrinsics(fx=None, fy=None, cx=None, cy=None, skew=0, *, camera_matrix=None, **kwargs)[source]#

Bases: tensorbay.utility.repr.ReprMixin, tensorbay.utility.attr.AttrsMixin

CameraIntrinsics represents camera intrinsics.

Camera intrinsic parameters including camera matrix and distortion coeffecients. They describe the mapping of the scene in front of the camera to the pixels in the final image.

Parameters
  • fx (Optional[float]) – The x axis focal length expressed in pixels.

  • fy (Optional[float]) – The y axis focal length expressed in pixels.

  • cx (Optional[float]) – The x coordinate of the so called principal point that should be in the center of the image.

  • cy (Optional[float]) – The y coordinate of the so called principal point that should be in the center of the image.

  • skew (float) – It causes shear distortion in the projected image.

  • camera_matrix (tensorbay.sensor.intrinsics.CameraMatrix) – A 3x3 Sequence of the camera matrix.

  • **kwargs – Float values to initialize DistortionCoefficients.

  • kwargs (float) –

Return type

None

camera_matrix#

A 3x3 Sequence of the camera matrix.

Type

tensorbay.sensor.intrinsics.CameraMatrix

distortion_coefficients#

It is the deviation from rectilinear projection. It includes

Type

tensorbay.sensor.intrinsics.DistortionCoefficients

radial distortion and tangential distortion.

Examples

>>> matrix = [[1, 3, 3],
...           [0, 2, 4],
...           [0, 0, 1]]

Initialization Method 1: Init from 3x3 sequence array.

>>> camera_intrinsics = CameraIntrinsics(camera_matrix=matrix, p1=5, k1=6)
>>> camera_intrinsics
CameraIntrinsics(
    (camera_matrix): CameraMatrix(
            (fx): 1,
            (fy): 2,
            (cx): 3,
            (cy): 4,
            (skew): 3
        ),
    (distortion_coefficients): DistortionCoefficients(
            (p1): 5,
            (k1): 6
        )
)

Initialization Method 2: Init from camera calibration parameters, skew is optional.

>>> camera_intrinsics = CameraIntrinsics(
...     fx=1,
...     fy=2,
...     cx=3,
...     cy=4,
...     p1=5,
...     k1=6,
...     skew=3
... )
>>> camera_intrinsics
CameraIntrinsics(
    (camera_matrix): CameraMatrix(
        (fx): 1,
        (fy): 2,
        (cx): 3,
        (cy): 4,
        (skew): 3
    ),
    (distortion_coefficients): DistortionCoefficients(
        (p1): 5,
        (k1): 6
    )
)
classmethod loads(contents)[source]#

Loads CameraIntrinsics from a dict containing the information.

Parameters

contents (Mapping[str, Mapping[str, float]]) – A dict containig camera matrix and distortion coefficients.

Returns

A CameraIntrinsics instance containing information from the contents dict.

Return type

tensorbay.sensor.intrinsics._T

Examples

>>> contents = {
...     "cameraMatrix": {
...         "fx": 1,
...         "fy": 2,
...         "cx": 3,
...         "cy": 4,
...     },
...     "distortionCoefficients": {
...         "p1": 1,
...         "p2": 2,
...         "k1": 3,
...         "k2": 4
...     },
... }
>>> camera_intrinsics = CameraIntrinsics.loads(contents)
>>> camera_intrinsics
CameraIntrinsics(
    (camera_matrix): CameraMatrix(
        (fx): 1,
        (fy): 2,
        (cx): 3,
        (cy): 4,
        (skew): 0
    ),
    (distortion_coefficients): DistortionCoefficients(
        (p1): 1,
        (p2): 2,
        (k1): 3,
        (k2): 4
    )
)
dumps()[source]#

Dumps the camera intrinsics into a dict.

Returns

A dict containing camera intrinsics.

Return type

Dict[str, Dict[str, float]]

Examples

>>> camera_intrinsics.dumps()
{'cameraMatrix': {'fx': 1, 'fy': 2, 'cx': 3, 'cy': 4, 'skew': 3},
'distortionCoefficients': {'p1': 5, 'k1': 6}}
set_camera_matrix(fx=None, fy=None, cx=None, cy=None, skew=0, *, matrix=None)[source]#

Set camera matrix of the camera intrinsics.

Parameters
  • fx (Optional[float]) – The x axis focal length expressed in pixels.

  • fy (Optional[float]) – The y axis focal length expressed in pixels.

  • cx (Optional[float]) – The x coordinate of the so called principal point that should be in the center of the image.

  • cy (Optional[float]) – The y coordinate of the so called principal point that should be in the center of the image.

  • skew (float) – It causes shear distortion in the projected image.

  • matrix (Optional[Union[Sequence[Sequence[float]], numpy.ndarray]]) – Camera matrix in 3x3 sequence.

Return type

None

Examples

>>> camera_intrinsics.set_camera_matrix(fx=11, fy=12, cx=13, cy=14, skew=15)
>>> camera_intrinsics
CameraIntrinsics(
    (camera_matrix): CameraMatrix(
        (fx): 11,
        (fy): 12,
        (cx): 13,
        (cy): 14,
        (skew): 15
    ),
    (distortion_coefficients): DistortionCoefficients(
        (p1): 1,
        (p2): 2,
        (k1): 3,
        (k2): 4
    )
)
set_distortion_coefficients(**kwargs)[source]#

Set distortion coefficients of the camera intrinsics.

Parameters
  • **kwargs – Contains p1, p2, …, k1, k2, …

  • kwargs (float) –

Return type

None

Examples

>>> camera_intrinsics.set_distortion_coefficients(p1=11, p2=12, k1=13, k2=14)
>>> camera_intrinsics
CameraIntrinsics(
    (camera_matrix): CameraMatrix(
        (fx): 11,
        (fy): 12,
        (cx): 13,
        (cy): 14,
        (skew): 15
    ),
    (distortion_coefficients): DistortionCoefficients(
        (p1): 11,
        (p2): 12,
        (k1): 13,
        (k2): 14
    )
)
project(point, is_fisheye=False)[source]#

Project a point to the pixel coordinates.

If distortion coefficients are provided, distort the point before projection.

Parameters
  • point (Sequence[float]) – A Sequence containing coordinates of the point to be projected.

  • is_fisheye (bool) – Whether the sensor is fisheye camera, default is False.

Returns

The coordinates on the pixel plane where the point is projected to.

Return type

tensorbay.geometry.vector.Vector2D

Examples

Project a point with 2 dimensions.

>>> camera_intrinsics.project((1, 2))
Vector2D(137.0, 510.0)

Project a point with 3 dimensions.

>>> camera_intrinsics.project((1, 2, 3))
Vector2D(6.300411522633745, 13.868312757201647)

Project a point with 2 dimensions, fisheye is True

>>> camera_intrinsics.project((1, 2), is_fisheye=True)
Vector2D(9.158401093771875, 28.633604375087504)