Camera models¶

Camera models for projecting between 3D world and 2D pixel coordinates.

class orthority.camera.Camera(**kwargs)¶

Bases: ABC

Base camera class.

property im_size: tuple[int, int]¶: Image (width, height) in pixels.

abstractmethod world_to_pixel(xyz)¶

Transform from 3D world to 2D pixel coordinates.

Parameters:: xyz (ndarray) – 3D world (x, y, z) coordinates to transform, as a 3-by-N array, with (x, y, z) along the first dimension.
Returns:: Pixel (j=column, i=row) coordinates as a 2-by-N array, with (j, i) along the first dimension.
Return type:: ndarray

abstractmethod pixel_to_world_z(ji, z)¶

Transform from 2D pixel to 3D world coordinates at a specified z.

Allows broadcasting of the pixel coordinate(s) and z value(s) i.e. can transform multiple pixel coordinates to a single z value, or a single pixel coordinate to multiple z values.

Parameters:

ji (ndarray) – Pixel (j=column, i=row) coordinates as a 2-by-N array, with (j, i) along the first dimension.
z (float | ndarray) – Z values(s) to project to as a 1-by-N array.

Returns:

3D world (x, y, z) coordinates as a 3-by-N array, with (x, y, z) along the first dimension.

Return type:

ndarray

pixel_boundary(num_pts=None)¶

A rectangle of 2D pixel coordinates along the image boundary.

Parameters:: num_pts (int) – Number of boundary points to include. If set to None (the default), eight points are included, with points at the image corners and mid-points of the sides.
Returns:: Boundary pixel (j=column, i=row) coordinates as a 2-by-N array, with (j, i) along the first dimension.
Return type:: ndarray

world_boundary(z, num_pts=None, transform=None, interp=cubic, **kwargs)¶

A polygon of (x, y, z) world coordinates along the image boundary, at a specified z value or surface (DEM) intersection.

Parameters:

z (float | ndarray) – Z values(s) as a single value or a 2D array (surface).
num_pts (int) – Number of boundary points to include. If set to None (the default), eight points are included, with points at the image corners and mid-points of the sides.
transform (Affine) – Affine transform defining the (x, y) world coordinates of z when it is an array. Required when z is an array and not used otherwise.
interp (str | Interp) – Interpolation method to use for finding boundary intersections with z when it is an array. Not used when z is a single value.
kwargs – Not used.

Returns:

Boundary world (x, y, z) coordinates as a 3-by-N array, with (x, y, z) along the first dimension. Boundary points that lie outside z bounds, when z is an array, are given at the minimum of z.

Return type:

ndarray

read(im_file, indexes=None, dtype=None, **kwargs)¶

Read image band(s) from a given file. Sub-classes may add a processing step.

Parameters:

im_file (str | PathLike | OpenFile | DatasetReader) – Image file to read. Can be a path or URI string, OpenFile object in binary mode ('rb'), or dataset reader.
indexes (Sequence[int] | int) – Band index(es) to read (1 based). Defaults to all bands if not supplied.
dtype (str) – Data type of the returned array. If set to None (the default), the im_file dtype is used.
kwargs – Not used.

Returns:

Image as 3D array with band(s) along the first dimension (Rasterio ordering).

Return type:

ndarray

remap(im_array, x, y, z, nodata=None, interp=cubic, **kwargs)¶

Remap an image to an ortho image at the given world coordinates.

Parameters:

im_array (ndarray) – Image to remap as a 3D array with band(s) along the first dimension (Rasterio ordering). Typically, this is the image returned by Camera.read(), with the same size as the camera im_size.
x (ndarray) – X world coordinates to remap to, as a M-by-N 2D array with float64 data type. NaN coordinate pixels are mapped to nodata.
y (ndarray) – Y world coordinates to remap to, as a M-by-N 2D array with float64 data type. NaN coordinate pixels are mapped to nodata.
z (ndarray) – Z world coordinates to remap to, as a M-by-N 2D array with float64 data type. NaN coordinate pixels are mapped to nodata.
nodata (float | int) – Value to use for masking invalid pixels in the remapped image. If set to None (the default), a value based on the im_array data type is chosen automatically.
interp (str | Interp) – Interpolation method to use for remapping.
kwargs – Not used.

Returns:

Remapped image as a L-by-M-by-N 3D array, where L is the number of im_array bands. Same data type as im_array.
Nodata mask of the remapped image, as a M-by-N 2D boolean array.

Return type:

tuple[ndarray, ndarray]

class orthority.camera.RpcCamera(im_size, rpc, rpc_options=None, crs=None)¶

Bases: Camera

RPC camera.

Parameters:

im_size (tuple[int, int]) – Image (width, height) in pixels.
rpc (RPC | dict) – RPC parameters as a RPC object or dictionary.
rpc_options (dict | None) – Options for GDALCreateRPCTransformerV2(). Only used for the reverse pixel to world coordinate transform.
crs (str | CRS) – World / ortho CRS as an EPSG, proj4 or WKT string, or CRS object. If its vertical CRS is defined, it should be ellipsoidal height (m), otherwise ellipsoidal height is assumed. If crs is set to None (the default), the 3D WGS84 geographic CRS is used.

property crs: CRS | None¶: World / ortho CRS.

world_to_pixel(xyz)¶

Transform from 3D world to 2D pixel coordinates.

Parameters:: xyz (ndarray) – 3D world (x, y, z) coordinates to transform, as a 3-by-N array, with (x, y, z) along the first dimension.
Returns:: Pixel (j=column, i=row) coordinates as a 2-by-N array, with (j, i) along the first dimension.
Return type:: ndarray

pixel_to_world_z(ji, z, **kwargs)¶

Transform from 2D pixel to 3D world coordinates at a specified z.

Allows broadcasting of the pixel coordinate(s) and z value(s) i.e. can transform multiple pixel coordinates to a single z value, or a single pixel coordinate to multiple z values.

Parameters:

ji (ndarray) – Pixel (j=column, i=row) coordinates as a 2-by-N array, with (j, i) along the first dimension.
z (float | ndarray) – Z values(s) to project to as a 1-by-N array.

Returns:

3D world (x, y, z) coordinates as a 3-by-N array, with (x, y, z) along the first dimension.

Return type:

ndarray

class orthority.camera.GcpCamera(im_size, gcps)¶

Bases: Camera

GCP camera (UNTESTED).

Parameters:

im_size (tuple[int, int]) – Image (width, height) in pixels.
gcps (Sequence[GroundControlPoint, dict]) – GCPs as a sequence of GroundControlPoint objects or dictionaries.

world_to_pixel(xyz)¶

Transform from 3D world to 2D pixel coordinates.

Parameters:: xyz (ndarray) – 3D world (x, y, z) coordinates to transform, as a 3-by-N array, with (x, y, z) along the first dimension.
Returns:: Pixel (j=column, i=row) coordinates as a 2-by-N array, with (j, i) along the first dimension.
Return type:: ndarray

pixel_to_world_z(ji, z, **kwargs)¶

Transform from 2D pixel to 3D world coordinates at a specified z.

Allows broadcasting of the pixel coordinate(s) and z value(s) i.e. can transform multiple pixel coordinates to a single z value, or a single pixel coordinate to multiple z values.

Parameters:

ji (ndarray) – Pixel (j=column, i=row) coordinates as a 2-by-N array, with (j, i) along the first dimension.
z (float | ndarray) – Z values(s) to project to as a 1-by-N array.

Returns:

3D world (x, y, z) coordinates as a 3-by-N array, with (x, y, z) along the first dimension.

Return type:

ndarray

class orthority.camera.FrameCamera(im_size, focal_len, sensor_size=None, cx=0.0, cy=0.0, xyz=None, opk=None, distort=True, alpha=1.0)¶

Bases: Camera

Pinhole camera with no distortion.

The xyz and opk exterior parameters must be supplied here, or via update(), before calling any methods that generate or require world coordinates.

Parameters:

im_size (tuple[int, int]) – Image (width, height) in pixels.
focal_len (float | tuple[float, float]) – Focal length(s) with the same units/scale as sensor_size. Can be a single value or (x, y) tuple.
sensor_size (tuple[float, float] | None) – Sensor (width, height) with the same units/scale as focal_len. If set to None (the default), pixels are assumed square and focal_len normalised and unitless (i.e. focal_len = focal length / max(sensor width & height)).
cx (float) – Principal point offsets in normalised image coordinates.
cy (float)
xyz (tuple[float, float, float] | None) – Camera (x, y, z) position in world coordinates.
opk (tuple[float, float, float] | None) – Camera (omega, phi, kappa) angles in radians to rotate from camera (PATB convention) to world coordinates.
distort (bool) – Not used for the pinhole camera model.
alpha (float) – Not used for the pinhole camera model.

property pos: tuple[float, float, float] | None¶: Camera (x, y, z) position in units of the world / ortho CRS.

property distort: bool¶: Include distortion in the camera model, and return the original (distorted) image from read() (True). Or, exclude distortion from the camera model, and return an undistorted image from read() (False). remap() of an image returned by read() is faster with distort=False, but may reduce remap quality.

property alpha: float¶: Scaling (0-1) of the undistorted image returned by read() when distort is False. 0 includes the largest portion of the source image that allows all undistorted pixels to be valid. 1 includes all source pixels in the undistorted image. Its value affects scaling of the camera model intrinsic matrix. Not used when distort is True.

update(xyz, opk)¶

Update exterior parameters.

Parameters:

xyz (tuple[float, float, float]) – Camera (x, y, z) position in world coordinates.
opk (tuple[float, float, float]) – Camera (omega, phi, kappa) angles in radians to rotate camera (PATB convention) to world coordinates.

Return type:

None

world_to_pixel(xyz)¶

Transform from 3D world to 2D pixel coordinates.

Parameters:: xyz (ndarray) – 3D world (x, y, z) coordinates to transform, as a 3-by-N array, with (x, y, z) along the first dimension.
Returns:: Pixel (j=column, i=row) coordinates as a 2-by-N array, with (j, i) along the first dimension.
Return type:: ndarray

pixel_to_world_z(ji, z)¶

Transform from 2D pixel to 3D world coordinates at a specified z.

Allows broadcasting of the pixel coordinate(s) and z value(s) i.e. can transform multiple pixel coordinates to a single z value, or a single pixel coordinate to multiple z values.

Parameters:

ji (ndarray) – Pixel (j=column, i=row) coordinates as a 2-by-N array, with (j, i) along the first dimension.
z (float | ndarray) – Z values(s) to project to as a 1-by-N array.

Returns:

3D world (x, y, z) coordinates as a 3-by-N array, with (x, y, z) along the first dimension.

Return type:

ndarray

pixel_boundary(num_pts=None)¶

A polygon of 2D pixel coordinates along the image boundary. If distort is False, coordinates will be along the boundary of the valid area in the undistorted image returned by read().

Parameters:: num_pts (int) – Number of boundary points to include in the polygon. If set to None (the default), eight points are included, with points at the image corners and mid-points of the sides.
Returns:: Boundary pixel (j=column, i=row) coordinates as a 2-by-N array, with (j, i) along the first dimension.
Return type:: ndarray

world_boundary(z, num_pts=None, transform=None, interp=cubic, clip=True)¶

A polygon of (x, y, z) world coordinates along the image boundary, at a specified z value or surface (DEM).

Parameters:

z (float | ndarray) – Z values(s) as a single value or a 2D array (surface).
num_pts (int) – Number of boundary points to include. If set to None (the default), eight points are included, with points at the image corners and mid-points of the sides.
transform (Affine) – Affine transform defining the (x, y) world coordinates of z when it is an array. Required when z is an array and not used otherwise.
interp (str | Interp) – Interpolation method to use for finding boundary intersections with z when it is an array. Not used when z is a single value.
clip (bool) – Clip the z coordinate of boundary points to the camera height.

Returns:

Boundary world (x, y, z) coordinates as a 3-by-N array, with (x, y, z) along the first dimension. Boundary points that lie outside z bounds, when z is an array, are given at the minimum of z.

Return type:

ndarray

read(im_file, indexes=None, dtype=None, nodata=None, interp=cubic)¶

Read image band(s) from a given file, undistorting when distort is False.

Parameters:

im_file (str | PathLike | OpenFile | DatasetReader) – Image file to read. Can be a path or URI string, OpenFile object in binary mode ('rb'), or dataset reader.
indexes (Sequence[int]) – Band index(es) to read (1 based).
dtype (str) – Data type of the returned array. If set to None (the default), the im_file dtype is used.
nodata (float | int) – Value to use for masking invalid pixels in the undistorted image. If set to None (the default), a value based on dtype is chosen automatically. Not used if distort is True.
interp (str | Interp) – Interpolation method to use when undistorting the image. Not used if distort is True.

Returns:

Image as 3D array with band(s) along the first dimension (Rasterio ordering).

Return type:

ndarray

remap(image, x, y, z, nodata=None, interp=cubic, kernel_size=(3, 3))¶

Remap an image to an ortho image at the given world coordinates.

Parameters:

im_array – Image to remap as a 3D array with band(s) along the first dimension (Rasterio ordering). Typically, this is the image returned by Camera.read(), with the same size as the camera im_size.
x (ndarray) – X world coordinates to remap to, as a M-by-N 2D array with float64 data type. NaN coordinate pixels are mapped to nodata.
y (ndarray) – Y world coordinates to remap to, as a M-by-N 2D array with float64 data type. NaN coordinate pixels are mapped to nodata.
z (ndarray) – Z world coordinates to remap to, as a M-by-N 2D array with float64 data type. NaN coordinate pixels are mapped to nodata.
nodata (float | int | None) – Value to use for masking invalid pixels in the remapped image. If set to None (the default), a value based on the im_array data type is chosen automatically.
interp (str | Interp) – Interpolation method to use for remapping.
kernel_size (tuple[int, int]) – Kernel (width, height) size in pixels, used for dilating the nodata mask. Removes blurring of boundary pixels with nodata areas in an undistorted im_array. Not used if blurring could not have occurred (e.g. if distort is True).
image (ndarray)

Returns:

Remapped image as a L-by-M-by-N 3D array, where L is the number of im_array bands. Same data type as im_array.
Nodata mask of the remapped image, as a M-by-N 2D boolean array.

Return type:

tuple[ndarray, ndarray]

orthority.camera.PinholeCamera¶: alias of FrameCamera

class orthority.camera.OpenCVCamera(im_size, focal_len, sensor_size=None, cx=0.0, cy=0.0, k1=0.0, k2=0.0, k3=0.0, p1=0.0, p2=0.0, k4=0.0, k5=0.0, k6=0.0, s1=0.0, s2=0.0, s3=0.0, s4=0.0, tx=0.0, ty=0.0, xyz=None, opk=None, distort=True, alpha=1.0)¶

Bases: FrameCamera

OpenCV camera model.

This is a wrapper around the OpenCV general model. Partial or special cases can be specified by omitting some or all of the distortion coefficients. E.g. if no distortion coefficients are specified, this model corresponds to PinholeCamera, or if the first 5 distortion coefficients are specified, this model corresponds to BrownCamera.

The xyz and opk exterior parameters must be supplied here, or via update(), before calling any methods that generate or require world coordinates.

Parameters:

im_size (tuple[int, int]) – Image (width, height) in pixels.
focal_len (float | tuple[float, float]) – Focal length(s) with the same units/scale as sensor_size. Can be a single value or (x, y) tuple.
sensor_size (tuple[float, float] | None) – Sensor (width, height) with the same units/scale as focal_len. If set to None (the default), pixels are assumed square and focal_len normalised and unitless (i.e. focal_len = focal length / max(sensor width & height)).
cx (float) – Principal point offsets in normalised image coordinates.
cy (float)
k1 (float) – Distortion coefficients - see the OpenCV docs.
k2 (float)
k3 (float)
p1 (float)
p2 (float)
k4 (float)
k5 (float)
k6 (float)
s1 (float)
s2 (float)
s3 (float)
s4 (float)
tx (float)
ty (float)
xyz (tuple[float, float, float] | None) – Camera (x, y, z) position in world coordinates.
opk (tuple[float, float, float] | None) – Camera (omega, phi, kappa) angles in radians to rotate from camera (PATB convention) to world coordinates.
distort (bool) – Include distortion in the camera model, and return the original (distorted) image from read() (True). Or, exclude distortion from the camera model, and return an undistorted image from read() (False). remap() of an image returned by read() is faster with distort=False, but may reduce remap quality.
alpha (float) – Scaling (0-1) of the undistorted image returned by read() when distort is False. 0 includes the largest portion of the source image that allows all undistorted pixels to be valid. 1 includes all source pixels in the undistorted image. Its value affects scaling of the camera model intrinsic matrix. Not used when distort is True.

class orthority.camera.BrownCamera(im_size, focal_len, sensor_size=None, cx=0.0, cy=0.0, k1=0.0, k2=0.0, p1=0.0, p2=0.0, k3=0.0, xyz=None, opk=None, distort=True, alpha=1.0)¶

Bases: OpenCVCamera

Brown-Conrady camera model.

Compatible with OpenDroneMap / OpenSfM perspective, simple_radial, radial and brown model parameters, and the 4- and 5-coefficient versions of the OpenCV general model.

The xyz and opk exterior parameters must be supplied here, or via update(), before calling any methods that generate or require world coordinates.

Parameters:

im_size (tuple[int, int]) – Image (width, height) in pixels.
focal_len (float | tuple[float, float]) – Focal length(s) with the same units/scale as sensor_size. Can be a single value or (x, y) tuple.
sensor_size (tuple[float, float] | None) – Sensor (width, height) with the same units/scale as focal_len. If set to None (the default), pixels are assumed square and focal_len normalised and unitless (i.e. focal_len = focal length / max(sensor width & height)).
cx (float) – Principal point offsets in normalised image coordinates.
cy (float)
k1 (float) – Distortion coefficients.
k2 (float)
p1 (float)
p2 (float)
k3 (float)
xyz (tuple[float, float, float] | None) – Camera (x, y, z) position in world coordinates.
opk (tuple[float, float, float] | None) – Camera (omega, phi, kappa) angles in radians to rotate from camera (PATB convention) to world coordinates.
distort (bool) – Include distortion in the camera model, and return the original (distorted) image from read() (True). Or, exclude distortion from the camera model, and return an undistorted image from read() (False). remap() of an image returned by read() is faster with distort=False, but may reduce remap quality.
alpha (float) – Scaling (0-1) of the undistorted image returned by read() when distort is False. 0 includes the largest portion of the source image that allows all undistorted pixels to be valid. 1 includes all source pixels in the undistorted image. Its value affects scaling of the camera model intrinsic matrix. Not used when distort is True.

class orthority.camera.FisheyeCamera(im_size, focal_len, sensor_size=None, cx=0.0, cy=0.0, k1=0.0, k2=0.0, k3=0.0, k4=0.0, xyz=None, opk=None, distort=True, alpha=1.0)¶

Bases: FrameCamera

Fisheye camera model.

Compatible with OpenDroneMap / OpenSfM, and OpenCV fisheye model parameters.

The xyz and opk exterior parameters must be supplied here, or via update(), before calling any methods that generate or require world coordinates.

Parameters:

im_size (tuple[int, int]) – Image (width, height) in pixels.
focal_len (float | tuple[float, float]) – Focal length(s) with the same units/scale as sensor_size. Can be a single value or (x, y) tuple.
sensor_size (tuple[float, float] | None) – Sensor (width, height) with the same units/scale as focal_len. If set to None (the default), pixels are assumed square and focal_len normalised and unitless (i.e. focal_len = focal length / max(sensor width & height)).
cx (float) – Principal point offsets in normalised image coordinates.
cy (float)
k1 (float) – Distortion coefficients.
k2 (float)
k3 (float)
k4 (float)
xyz (tuple[float, float, float] | None) – Camera (x, y, z) position in world coordinates.
opk (tuple[float, float, float] | None) – Camera (omega, phi, kappa) angles in radians to rotate from camera (PATB convention) to world coordinates.
distort (bool) – Include distortion in the camera model, and return the original (distorted) image from read() (True). Or, exclude distortion from the camera model, and return an undistorted image from read() (False). remap() of an image returned by read() is faster with distort=False, but may reduce remap quality.
alpha (float) – Scaling (0-1) of the undistorted image returned by read() when distort is False. 0 includes the largest portion of the source image that allows all undistorted pixels to be valid. 1 includes all source pixels in the undistorted image. Its value affects scaling of the camera model intrinsic matrix. Not used when distort is True.

orthority.camera.create_camera(cam_type, *args, **kwargs)¶

Create a camera object given a camera type and parameters.

Parameters:

cam_type (str | CameraType) – Camera type.
args – Positional arguments to pass to camera constructor.
kwargs – Keyword arguments to pass to camera constructor.

Return type:

FrameCamera | RpcCamera