giant.camera_models.camera_model

This module provides an abstract base class (abc) for implementing GIANT camera models.

This abc provides a design guide for building GIANT compatible camera models. All user defined camera models should probably subclass this class to ensure that they implement all of the required properties and methods that GIANT expects a camera model to have [1]. In addition, this module provides the functions save() and load() which can be used to write/read camera models from disk in a human and machine readable format.

For a typical use case that doesn’t require a custom camera model, see the PinholeModel, BrownModel, OwenModel, or OpenCVModel classes which provide some of the most common models used in optical navigation. These also serve as examples of how to make a concrete implementation of the CameraModel abc.

Footnotes

[1]

GIANT will not error if you do not subclass CameraModel, but it will print warnings to the screen.

Use

To implement a fully functional custom camera model for GIANT, you must implement the following methods in addition to subclassing the CameraModel class.

Method	Use
project_onto_image()	projects a point from the camera frame onto the image
compute_jacobian()	returns the Jacobian matrix \(\partial\mathbf{x}_P/\partial\mathbf{c}\) where \(\mathbf{c}\) is a vector of camera model parameters (like focal length, pixel pitch, distortion coefficients, etc) and \(\mathbf{x}_P\) is a pixel location.
compute_pixel_jacobian()	returns the Jacobian matrix partialmathbf{x}_P/partialmathbf{x}_C` where \(\mathbf{x}_C\) is a vector in the camera frame that projects to \(\mathbf{x}_P\) which is the pixel location.
compute_unit_vector_jacobian()	returns the Jacobian matrix partialmathbf{x}_C/partialmathbf{x}_P` where \(\mathbf{x}_C\) is a unit vector in the camera frame that projects to \(\mathbf{x}_P\) which is the pixel location.
apply_update()	updates the camera model based on a vector of delta camera model parameters
pixels_to_unit()	transforms pixel coordinates into unit vectors in the camera frame
undistort_pixels()	takes a distorted pixel location and computes the corresponding undistorted gnomic location in units of pixels
distort_pixels()	applies the distortion model to gnomic points with units of pixels

In addition the following methods and attributes are already implemented for most cases but may need to be overridden for some special cases

Method/Attribute	Use
overwrite()	overwrites the calling instance with the attributes of another instance in place
distortion_map()	generates a set of pixel coordinates+distortion values that can be used to create a distortion quiver or contour map.
undistort_image()	undistorts an entire image based on the distortion model (returns a warped image)
copy()	returns a copy of the current model
to_elem()	a method that stores the model parameters in an element tree element for saving the model to file
from_elem()	a class method that retrieves the model parameters from an element tree element for loading a model from a file
n_rows	The number of rows in pixels in an image captured by the device modeled by this camera model
n_cols	The number of columns in pixels in an image captured by the device modeled by this camera model
field_of_view	Half the diagonal field of view of the detector in units of degrees.

Finally, if the to_elem() and from_elem() methods are not being overridden, the important_attributes attribute should be extended with a list of attributes that must be saved/loaded to completely reconstruct the camera model.

Classes

ReturnShape	This enumeration is used to specify what should be returned from method undistort_image().
CameraModel	This is the abstract base class for all camera models in GIANT.

Functions

save	This function is used to save a camera model to a GIANT xml file.
load	This function is used to retrieve a camera model from a GIANT xml file.