Camera¶

class cameratransform.Camera(projection: CameraProjection, orientation: SpatialOrientation = None, lens: LensDistortion = None)[source]¶: This class is the core of the CameraTransform package and represents a camera. Each camera has a projection (subclass of CameraProjection), a spatial orientation (SpatialOrientation) and optionally a lens distortion (subclass of LensDistortion).

Save/Load Functions¶

Camera.save(filename: str)[source]¶

Saves the camera parameters to a json file.

Parameters:: filename (str) – the filename where to store the parameters.

Camera.load(filename: str)[source]¶

Load the camera parameters from a json file.

Parameters:: filename (str) – the filename of the file to load.

cameratransform.load_camera(filename: str) → Camera[source]¶

Create a Camera instance with the parameters from the file.

Parameters:: filename (str) – the filename of the file to load.
Returns:: camera – the camera with the given parameters.
Return type:: Camera

Transformations¶

Note

This section only covers transformations from image coordinates to space coordinates for gps coordinates see section Earth Position (GPS).

Convert points (Nx3) from the space coordinate system to the image coordinate system.

Parameters:: points (ndarray) – the points in space coordinates to transform, dimensions (3), (Nx3)
Returns:: points – the points in the image coordinate system, dimensions (2), (Nx2)
Return type:: ndarray

Examples

>>> import cameratransform as ct
>>> cam = ct.Camera(ct.RectilinearProjection(focallength_px=3729, image=(4608, 2592)),
>>>                    ct.SpatialOrientation(elevation_m=15.4, tilt_deg=85))

transform a single point from the space to the image:

>>> cam.imageFromSpace([-4.17, 45.32, 0.])
[1969.52 2209.73]

or multiple points in one go:

>>> cam.imageFromSpace([[-4.03, 43.96,  0.], [-8.57, 47.91, 0.]]))
[[1971.05 2246.95]
 [1652.73 2144.53]]

As the transformation from the image coordinate system to the space coordinate system is not unique, image points can only be uniquely mapped to a ray in space coordinates.

Parameters:

points (ndarray) – the points in image coordinates for which to get the ray, dimensions (2), (Nx2)

Returns:

offset (ndarray) – the origin of the camera (= starting point of the rays) in space coordinates, dimensions (3)
rays (ndarray) – the rays in the space coordinate system, dimensions (3), (Nx3)

Examples

>>> import cameratransform as ct
>>> cam = ct.Camera(ct.RectilinearProjection(focallength_px=3729, image=(4608, 2592)),
>>>                    ct.SpatialOrientation(elevation_m=15.4, tilt_deg=85))

get the ray of a point in the image:

>>> offset, ray = cam.getRay([1968, 2291]))
>>> offset
[0.00 0.00 15.40]
>>> ray
[-0.09 0.97 -0.35]

or the rays of multiple points in the image:

>>> offset, ray, cam.getRay([[1968, 2291], [1650, 2189]])
>>> offset
[0.00 0.00 15.40]
>>> ray
[[-0.09 0.97 -0.35]
 [-0.18 0.98 -0.33]]

Convert points (Nx2) from the image coordinate system to the space coordinate system. This is not a unique transformation, therefore an additional constraint has to be provided. The X, Y, or Z coordinate(s) of the target points can be provided or the distance D from the camera.

Parameters:

points (ndarray) – the points in image coordinates to transform, dimensions (2), (Nx2)
X (number, ndarray, optional) – the X coordinate in space coordinates of the target points, dimensions scalar, (N)
Y (number, ndarray, optional) – the Y coordinate in space coordinates of the target points, dimensions scalar, (N)
Z (number, ndarray, optional) – the Z coordinate in space coordinates of the target points, dimensions scalar, (N), default 0
D (number, ndarray, optional) – the distance in space coordinates of the target points from the camera, dimensions scalar, (N)
mesh (ndarray, optional) – project the image coordinates onto the mesh in space coordinates. The mesh is a list of M triangles, consisting of three 3D points each. Dimensions, (3x3), (Mx3x3)

Returns:

points – the points in the space coordinate system, dimensions (3), (Nx3)

Return type:

ndarray

Examples

>>> import cameratransform as ct
>>> cam = ct.Camera(ct.RectilinearProjection(focallength_px=3729, image=(4608, 2592)),
>>>                    ct.SpatialOrientation(elevation_m=15.4, tilt_deg=85))

transform a single point (impliying the condition Z=0):

>>> cam.spaceFromImage([1968 , 2291])
[-3.93 42.45 0.00]

transform multiple points:

>>> cam.spaceFromImage([[1968 , 2291], [1650, 2189]])
[[-3.93 42.45 0.00]
 [-8.29 46.11 -0.00]]

points that cannot be projected on the image, because they are behind the camera (for the RectilinearProjection) are returned with nan entries:

>>> cam.imageFromSpace([-4.17, -10.1, 0.])
[nan nan]

specify a y coordinate as for the back projection.

>>> cam.spaceFromImage([[1968 , 2291], [1650, 2189]], Y=45)
[[-4.17 45.00 -0.93]
 [-8.09 45.00 0.37]]

or different y coordinates for each point:

>>> cam.spaceFromImage([[1968 , 2291], [1650, 2189]], Y=[43, 45])
[[-3.98 43.00 -0.20]
 [-8.09 45.00 0.37]]

Image Transformations¶

Applies the undistortion of the lens model to the image. The purpose of this function is mainly to check the sanity of a lens transformation. As CameraTransform includes the lens transformation in any calculations, it is not necessary to undistort images before using them.

Parameters:

image (ndarray) – the image to undistort.
extent (list, optional) – the extent in pixels of the resulting image. This can be used to crop the resulting undistort image.
scaling (number, optional) – the number of old pixels that are used to calculate a new pixel. A higher value results in a smaller target image.
do_plot (bool, optional) – whether to plot the resulting image directly in a matplotlib plot.
alpha (number, optional) – when plotting an alpha value can be specified, useful when comparing multiple images.
skip_size_check (bool, optional) – if true, the size of the image is not checked to match the size of the cameras image.

Returns:

image – the undistorted image

Return type:

ndarray

Project an image to a top view projection. This will be done using a grid with the dimensions of the extent ([x_min, x_max, y_min, y_max]) in meters and the scaling, giving a resolution. For convenience, the image can be plotted directly. The projected grid is cached, so if the function is called a second time with the same parameters, the second call will be faster.

Parameters:

image (ndarray) – the image as a numpy array.
extent (list, optional) – the extent of the resulting top view in meters: [x_min, x_max, y_min, y_max]. If no extent is given a suitable extent is guessed. If a horizon is visible in the image, the guessed extent will in most cases be too streched.
scaling (number, optional) – the scaling factor, how many meters is the side length of each pixel in the top view. If no scaling factor is given, a good scaling factor is guessed, trying to get about the same number of pixels in the top view as in the original image.
do_plot (bool, optional) – whether to directly plot the resulting image in a matplotlib figure.
alpha (number, optional) – an alpha value used when plotting the image. Useful if multiple images should be overlaid.
Z (number, optional) – the “height” of the plane on which to project.
skip_size_check (bool, optional) – if true, the size of the image is not checked to match the size of the cameras image.

Returns:

image – the top view projected image

Return type:

ndarray

Helper Functions¶

Camera.distanceToHorizon() → float[source]¶

Calculates the distance of the camera’s position to the horizon of the earth. The horizon depends on the radius of the earth and the elevation of the camera.

Returns:: distance – the distance to the horizon.
Return type:: number

This function calculates the position of the horizon in the image sampled at the points x=0, x=im_width/2, x=im_width.

Parameters:: pointsX (ndarray, optional) – the x positions of the horizon to determine, default is [0, image_width/2, image_width], dimensions () or (N)
Returns:: horizon – the points im camera image coordinates of the horizon, dimensions (2), or (Nx2).
Return type:: ndarray

Get the border of the image in a top view. Useful for drawing the field of view of the camera in a map.

Parameters:: resolution (number, optional) – the pixel distance between neighbouring points.
Returns:: border – the border of the image in space coordinates, dimensions (Nx3)
Return type:: ndarray

The cone of the camera’s field of view. This includes the border of the image and lines to the origin of the camera.

Returns:: cone – the cone of the camera in space coordinates, dimensions (Nx3)
Return type:: ndarray

Calculate the height of objects in the image, assuming the Z position of the objects is known, e.g. they are assumed to stand on the Z=0 plane.

Parameters:

point_feet (ndarray) – the positions of the feet, dimensions: (2) or (Nx2)
point_heads (ndarray) – the positions of the heads, dimensions: (2) or (Nx2)
Z (number, ndarray, optional) – the Z position of the objects, dimensions: scalar or (N), default 0

Returns:

heights – the height of the objects in meters, dimensions: () or (N)

Return type:

ndarray

Generate LUT to calculate area covered by one pixel in the image dependent on y position in the image

Parameters:

undef_value (number, optional) – what values undefined positions should have, default=0
whole_image (bool, optional) – whether to generate the look up table for the whole image or just for a y slice

Returns:

LUT – same length as image height

Return type:

ndarray