asi_core.ocam

This module provides functionality related to geometric transformations of ASI images in particular image undistortion.

The internal camera model used here was described by: Scaramuzza, D., et al. (2006). A Toolbox for Easily Calibrating Omnidirectional Cameras. RSJ International Conference on Intelligent Robots and Systems Beijing, China.

The external camera orientation used here is defined according to: Luhmann, T. (2000). Nahbereichsphotogrammetrie: Grundlagen, Methoden und Anwendungen. Heidelberg, Germany, Wichmann Verlag.

Classes

UndistortionParameters	This dataclass contains all configurable parameters for the undistortion lookup table calculation. The parameters
OcamModel	Defines transformations based on the ocam camera model and stores corresponding parameters and lookup tables for an

Module Contents

class asi_core.ocam.UndistortionParameters

This dataclass contains all configurable parameters for the undistortion lookup table calculation. The parameters are stored with every call of create_undistortion_with_zenith_cropping_LUT to avoid unnecessary recalculations of the same lookup table for equal undistortion parameters.

eor: numpy.ndarray = None

camera_mask: numpy.ndarray = None

undistorted_resolution: Tuple = None

limit_angle: float = 78.0

subgrid_factor: int = 4

__eq__(other)

Compare the object’s parameter set the one of another object

Parameters:

other – UndistortionParameters instance

Returns:

Check result, True if equal

class asi_core.ocam.OcamModel(ss, invpol, x_center, y_center, c, d, e, width, height, diameter=None)

Defines transformations based on the ocam camera model and stores corresponding parameters and lookup tables for an individual camera sample

ss

invpol

x_center

y_center

diameter = None

c

d

e

width

height

undistortion_parameters = None

undistortion_lookup_table = None

static get_ocam_model_from_mat(filename)

Create OcamModel instance loading ocam parameters from .mat file, e.g. generated via Matlab OcamCalib Toolbox

Remarks:

• The order of “pol” needs to be flipped such that the coefficients fulfill the polynomial order

  P(x)=invpol[0]*x^0+…+invpol[N-1]*x^N-2

• The coordinates of the image center need to be subtracted by 1 to fulfill the C convention (start

  from 0)

Parameters:

filename – path to .mat file containing ocam model struct

Returns:

OcamModel object

static get_ocam_model_from_dict(ocam_dict)

Create OcamModel instance loading ocam parameters from a dictionary, as read from camera_data.yaml

All parameters in camera_data.yaml are stored in the right format for usage in Python.

Parameters:

ocam_dict – Dictionary with ocam calibration parameters

Returns:

OcamModel object

cam2world(point_2d)

Transform pixel coordinates to specific external cartesian coordinates

Based on the sfmt matlab function cam2world

Parameters:

point_2d (np.ndarray, shape (N,2)) – 2d pixel coordinates

Returns:

3d cartesian coordinates

Return type:

np.ndarray, shape (N,3)

world2cam(point3D)

Map a set of 3-D points in world coordinates to pixels in the camera image.

Parameters:

point3D (np.ndarray, shape (N,3)) – Vector of 3D-points in world coordinates

Returns:

Vector of 2D points in camera coordinates (pixel)

Return type:

np.ndarray, shape (N,2)

world2cam_ss(point3D)

Convert 3D world coordinates to 2D pixel coordinates in the camera image using the omni3d2pixel function

Apply an affine transformation to map the coordinates to the final pixel locations.

Parameters:

point3D – tuple or list, x, y, and z coordinates in world space.

Returns:

numpy.ndarray, x and y pixel coordinates of the points in the camera image.

omni3d2pixel(ss, xx, width, height)

Convert 3D world coordinates to 2D pixel coordinates in the camera image.

Parameters:

• ss – numpy.ndarray, coefficients for the polynomial function that relates the image pixel coordinates to the 3D world coordinates

• xx – numpy.ndarray (2D), world coordinates, where each row corresponds to a point in the 3D space

• width – int, width of the camera image

• height – int, height of the camera image

Returns:

1D numpy arrays containing the x and y pixel coordinates of the points in the camera image

world2cam_eor(eor, object_coo, cam_pos=np.zeros((3,)), use_ss=False)

Transform coordinates from an external cartesian coordinate system to pixel coordinates.

Parameters:

• eor – Vector containing the camera position and orientation.

• object_coo –

  3D object coordinates with or without point numbers. Either shape (N,3) with (Y, X, Z) in each row or shape (N,4) with (Point_Id, Y, X, Z) in each row. If cam_pos is zero, the origin is in the camera and the following applies:

  North (1, 0, 0) East (0, 1, 0) Zenith (0, 0, 1)

• cam_pos – Offset in world coordinates between camera and origin

• use_ss – If True, the slower method using the “forward” polynomial ss is used.

Returns:

2D image coordinates in pixels with or without point numbers depending on input. Origin is located in the upper left corner. If shape is (N,2) data is interpreted as (X, Y); if (N, 3), data is interpreted as (Point_Id, X, Y). Increasing X means moving right in image. Increasing Y means moving down in image

cam2world_eor(eor, image_coo, cam_pos=np.zeros((3,)))

Transform pixel coordinates to coordinates in an external cartesian coordinate system.

Note: based on sfmt_matlab function call_cam2world

Parameters:

• eor – External orientation as a list or 1-D array of 3 entries with the angles roll, pitch, yaw (order and relation to axes should be documented).

• image_coo – 2D image coordinates in pixels with or without point numbers depending on input. Origin is located in the upper left corner. If shape is (N,2) data is interpreted as (X, Y); if (N, 3), data is interpreted as (Point_Id, X, Y). Increasing X means moving right in image. Increasing Y means moving down in image

• cam_pos – Offset in world coordinates between camera and origin

Returns:

3D object coordinates with or without point numbers depending on input data. Either shape (N,3) with (Y, X, Z) in each row or shape (N,4) with (Point_Id, Y, X, Z) in each row. If cam_pos is zero, the origin is in the camera and the following applies:

North (1, 0, 0) East (0, 1, 0) Zenith (0, 0, 1)

create_undistortion_with_zenith_cropping_LUT(eor, camera_mask, undistorted_resolution=None, limit_angle=78.0, subgrid_factor=4)

Create a look-up table between pixels of the ASI image and pixels of a undistorted georeferenced map.

This functions doesn’t only undistort images, it also does the EOR correction and cropping around the zenith as specified in the function arguments.

The returned map’s size and the map grid cell’s size is not defined by this function. It depends on the height of the observed object relative to the camera (i.e. cloud base height).

Parameters:

• eor – ndarray, shape(3,) 3-D array with external orientation (euler angles) [Rx, Ry, Rz].

• camera_mask – ndarray, shape(H,W) Defines masked pixels in origin image. True means that the pixel is mapped onto a valid pixel.

• undistorted_resolution – array_like, shape(2,) Resolution of undistorted image [H,W].

• limit_angle – Angle in degrees from zenith that shall be visible in the undistorted image.

• subgrid_factor – Factor by which to increase the resolution of the grid used for undistortion. Higher values result in finer grids, improving the precision of the undistortion process.

Returns:

lookup_table: dict, look-up table from georeferenced map, centered around camera, to image pixels lookup_table[‘mapx’]: ndarray, shape(H,W), ascending south-north (1st dim) and west-east (2nd dim),

each element contains the x-coord (2nd dim) of the image pixel monitoring the grid cell’s location

lookup_table[‘mapy’]: ndarray, shape(H,W), ascending south-north (1st dim) and west-east (2nd dim),

each element contains the y-coord (1st dim) of the image pixel monitoring the grid cell’s location

lookup_table[‘is_inside_mask’]: ndarray, shape(H,W),

static findinvpoly(ss, width, height)

Approximate pol from ss. Adapted from Scaramuzza Matlab toolbox.

Parameters:

• ss – list-like, ss polynomial coefficients of ocam model

• width – int, image width from ocam model

• height – int, image height from ocam model

Returns:

numpy 1-D array of polynomial coefficients of inverse polynomial to be used in world2cam