OwenModel¶
giant.camera_models.owen_model
:
- class giant.camera_models.owen_model.OwenModel(intrinsic_matrix=None, focal_length=1.0, field_of_view=None, use_a_priori=False, distortion_coefficients=None, misalignment=None, estimation_parameters='basic', kx=None, ky=None, kxy=None, kyx=None, px=None, py=None, radial2=None, radial4=None, tangential_x=None, tangential_y=None, pinwheel1=None, pinwheel2=None, e1=None, e2=None, e3=None, e4=None, e5=None, e6=None, a1=None, a2=None, a3=None, n_rows=1, n_cols=1, temperature_coefficients=None)[source]¶
Bases:
PinholeModel
This class provides an implementation of the Owen camera model for projecting 3D points onto images and performing camera calibration.
The
OwenModel
class is a subclass ofCameraModel
. This means that it includes implementations for all of the abstract methods defined in theCameraModel
class. This also means that it can be used throughout GIANT as the primary camera model, including within thecalibration
subpackage. If this class is going to be used with thecalibration
subpackage, the user can set which parameters are estimated and which are held fixed by using theestimation_parameters
key word argument when creating an instance of the class or by adjusting theestimation_parameters
instance variable on an instance of the class. Theestimation_parameters
input/attribute is a string or list of strings specifying which parameters to estimate. This means thatestimation_parameters
could be something like'basic'
which would indicate to estimate just eh usual parameters, or something like['focal_length', 'ky', 'px', 'py']
to estimate just the terms included in the list.In addition to the standard set of methods for a
CameraModel
subclass, theOwenModel
class provides the following additional methods which may or may not be useful to some people:Method
Use
computes the pinhole, image frame, and pixel locations of a 3D point
removes distortion from a point to get the corresponding pinhole location in units of distance
The Owen model also provides the following properties for easy getting/setting:
Property
Description
the diagonal field of view of the camera in units of degrees
\(k_x\), the pixel pitch in the x direction in units of pixels/distance
\(k_y\), the pixel pitch in the y direction in units of pixels/distance
\(k_{xy}\), A alpha term for non-rectangular pixels
\(k_{yx}\), A alpha term for non-rectangular pixels
\(p_{x}\), the x axis pixel location of the principal point of the camera in units of pixels
\(p_{y}\), the y axis pixel location of the principal point of the camera in units of pixels
\(\epsilon_2\), the radial distortion coefficient corresponding to \(r^2\)
\(\epsilon_4\), the radial distortion coefficient corresponding to \(r^4\)
\(\epsilon_5\), the tip/tilt/prism distortion coefficient corresponding to \(y_I\)
\(\epsilon_6\), the tip/tilt/prism distortion coefficient corresponding to \(x_I\)
\(\epsilon_1\), the pinwheel distortion coefficient corresponding to \(r\)
\(\epsilon_3\), the pinwheel distortion coefficient corresponding to \(r^3\)
\(a_1\), the linear coefficient for focal length dependent focal length
\(a_2\), the quadratic coefficient for focal length dependent focal length
\(a_3\), the cubic coefficient for focal length dependent focal length
The inverse of the intrinsic matrix
Note
The distortion attributes are aliases over each other and refer to the same data. Therefore setting a value to
radial2
would also change the value ofe2
- Parameters:
intrinsic_matrix (Sequence | ndarray | None) – the intrinsic matrix for the camera as a numpy shape (2, 3) array. Note that this is overwritten if
kx
,ky
,kxy
,kyx
,px
,py
are also specified.focal_length (Real) – The focal length of the camera in units of distance
field_of_view (Real | None) – The field of view of the camera in units of degrees.
use_a_priori (bool) – A flag to indicate whether to include the a priori state vector in the Jacobian matrix when performing a calibration
distortion_coefficients (Sequence | ndarray | None) – A numpy array of shape (6,) containing the six distortion coefficients in order. Note that this array is overwritten with any distortion coefficients that are specified independently.
misalignment (Sequence | ndarray | None) – either a numpy array of shape (3,) or a list of numpy arrays of shape(3,) with each array corresponding to a single image (the list of numpy arrays is only valid when estimating multiple misalignments)
estimation_parameters (str | Sequence) – A string or list of strings specifying which model parameters to include in the calibration
kx (Real | None) – The pixel pitch along the x axis in units of pixel/distance
ky (Real | None) – The pixel pitch along the y axis in units of pixel/distance
kxy (Real | None) – A alpha term for non-rectangular pixels
kyx (Real | None) – A alpha term for non-rectangular pixels
px (Real | None) – the x component of the pixel location of the principal point in the image in units of pixels
py (Real | None) – the y component of the pixel location of the principal point in the image in units of pixels
radial2 (Real | None) – the radial distortion coefficient corresponding to the r**2 term
e2 (Real | None) – the radial distortion coefficient corresponding to the r**2 term
radial4 (Real | None) – the radial distortion coefficient corresponding to the r**4 term
e4 (Real | None) – the radial distortion coefficient corresponding to the r**4 term
tangential_x (Real | None) – the tangential distortion coefficient corresponding to the x term
e6 (Real | None) – the tangential distortion coefficient corresponding to the x term
tangential_y (Real | None) – the tangential distortion coefficient corresponding to the y term
e5 (Real | None) – the tangential distortion coefficient corresponding to the y term
pinwheel1 (Real | None) – the pinwheel distortion coefficient corresponding to the r term
e1 (Real | None) – the pinwheel distortion coefficient corresponding to the r term
pinwheel2 (Real | None) – the pinwheel distortion coefficient corresponding to the r**2 term
e3 (Real | None) – the pinwheel distortion coefficient corresponding to the r**2 term
n_rows (int) – the number of rows of the active image array
n_cols (int) – the number of columns in the active image array
a1 (Real | None) – the linear coefficient of the focal length temperature dependence
a2 (Real | None) – the quadratic coefficient of the focal length temperature dependence
a3 (Real | None) – the cubic coefficient of the focal length temperature dependence
temperature_coefficients (Sequence | ndarray | None) – The temperature polynomial coefficients as a length 3 Sequence
- n_rows¶
The number of rows in the active pixel array for the camera
- n_cols¶
The number of columns in the active pixel array for the camera
- use_a_priori¶
This boolean value is used to determine whether to append the identity matrix to the Jacobian matrix returned by
compute_jacobian()
in order to include the current estimate of the camera model in the calibration process.
- intrinsic_matrix¶
The 2x3 intrinsic matrix contains the conversion from unitless gnomic locations to a location in an image with units of pixels.
It is defined as
\[\begin{split}\mathbf{K} = \left[\begin{array}{ccc} k_x & k_{xy} & p_x \\ k_{yx} & k_y & p_y \end{array}\right]\end{split}\]
- temperature_coefficients¶
The coefficients for the polynomial specifying the change in the focal length as a function of temperature.
- estimate_multiple_misalignments¶
This boolean value is used to determine whether multiple misalignments are being estimated/used per image.
If set to
True
then one misalignment is estimated for each image and used for each image when projecting through the camera model. When set toFalse
then a single misalignment is estimated for all images and used for all images when projecting through the camera model. Typically the user shouldn’t be setting this attribute directly as it is automatically handled when setting theestimation_parameters
attribute.
- estimation_parameters¶
A list of strings containing the parameters to estimate when performing calibration with this model.
This list is used in the methods
compute_jacobian()
andapply_update()
to determine which parameters are being estimated/updated. From thecompute_jacobian()
method, only columns of the Jacobian matrix corresponding to the parameters in this list are returned. In theapply_update()
method, the update vector elements are assumed to correspond to the order expressed in this list.Valid values for the elements of this list are shown in the following table. Generally, they correspond to attributes of this class, with a few convenient aliases that point to a collection of attributes.
Value
Description
'basic'
estimate focal length, kyx, ky, all 6 distortion parameters, and a single misalignment term for all images between the camera attitude and the spacecraft’s attitude: \(\left[\begin{array}{cccccccccc} f & k_y & k_{yx} & \epsilon_1 & \epsilon_2 & \epsilon_3 & \epsilon_4 & \epsilon_5 & \epsilon_6 & \boldsymbol{\delta\theta} \end{array}\right]\)
'intrinsic'
estimate focal length, kx, kxy, kyx, ky, px, py, and all 6 distortion parameters: \(\left[\begin{array}{ccccccccccccc} f & k_x & k_{xy} & k_y & k_{yx} & p_x & p_y & \epsilon_1 & \epsilon_2 & \epsilon_3 & \epsilon_4 & \epsilon_5 & \epsilon_6\end{array}\right]\)
'basic intrinsic'
estimate focal length, kyx, ky, and all 6 distortion parameters: \(\left[\begin{array}{ccccccccc} f & k_y & k_{yx} & \epsilon_1 & \epsilon_2 & \epsilon_3 & \epsilon_4 & \epsilon_5 & \epsilon_6 \end{array}\right]\)
'temperature dependence'
estimate a 3rd order polynomial for temperature dependence: \(\left[\begin{array}{ccc} a_1 & a_2 & a_3 \end{array}\right]\)
'focal_length'
the focal length of the camera: \(f\)
'kx'
pixel pitch along the x axis: \(k_x\)
'kxy'
alpha term for non-rectangular/rotated pixels: \(k_{xy}\)
'kyx'
alpha term for non-rectangular/rotated pixels: \(k_{yx}\)
'ky'
pixel pitch along the y axis: \(k_y\)
'px'
x location of the principal point: \(p_x\)
'py'
y location of the principal point: \(p_y\)
'radial2'
,'e2'
distortion coefficient corresponding to the \(r^2\) term: \(\epsilon_2\)
'radial4'
,'e4'
distortion coefficient corresponding to the \(r^4\) term: \(\epsilon_4\)
'tangential y'
,'e5'
distortion coefficient corresponding to the y tangential distortion: \(\epsilon_5\)
'tangential x'
,'e6'
distortion coefficient corresponding to the x tangential distortion: \(\epsilon_6\)
'pinwheel1'
,'e1'
distortion coefficient corresponding to the first order pinwheel distortion: \(\epsilon_1\)
'pinwheel2'
,'e3'
distortion coefficient corresponding to the third order pinwheel distortion: \(\epsilon_3\)
'a1'
estimate the linear coefficient for the temperature dependence: \(a_1\)
'a2'
estimate the quadratice coefficient for the temperature dependence: \(a_2\)
'a3'
estimate the cubic coefficient for the temperature dependence: \(a_3\)
'single misalignment'
estimate a single misalignment for all images: \(\boldsymbol{\delta\theta}\)
'multiple misalignments'
estimate a misalignment for each image: \(\left[\begin{array}{ccc}\boldsymbol{\delta\theta}_1 & \ldots & \boldsymbol{\delta\theta}_n \end{array}\right]\)
Note that it may not be possible to estimate all attributes simultaneously because this may result in a rank deficient matrix in the calibration process (for instance, without setting a priori weights, estimating
'px'
,'py'
, and'multiple misalignments'
together could result in a rank deficient matrix. Therefore, just because you can set something in this list doesn’t mean you should.For more details about calibrating a camera model, see the
calibration
package for details.
- distortion_coefficients¶
The distortion coefficients array contains the distortion coefficients for the Brown model [e2, e4, e5, e6, e1, e3].
- property field_of_view: float¶
A radial field of view of the camera specified in degrees.
The field of view should be set to at least the half width diagonal field of view of the camera. The field of view is used when querying star catalogues.
The diagonal field of view is defined as
+-----------+ | /| | / | | / | | V/ | | O/ | | F/ | | */ | | 2/ | | / | | / | |/ | +-----------+
If you specify this parameter to be
None
, the field of view will be computed using the camera model if possible.
- property kxy: float¶
A alpha term for non-rectangular pixels.
This corresponds to the [0, 1] component of the intrinsic matrix
- property kyx: float¶
A alpha term for non-rectangular pixels.
This corresponds to the [1, 0] component of the intrinsic matrix
- property kx: float¶
The inverse of the pixel pitch along the x axis in units of pix/distance.
This is the conversion factor to convert from gnomic coordinates (in units of distance) to units of pixels. It corresponds to the [0, 0] component of the intrinsic matrix
- property ky: float¶
The inverse of the pixel pitch along the y axis in units of pix/distance.
This is the conversion factor to convert from pinhole coordinates (in units of distance) to units of pixels. It corresponds to the [1, 1] component of the intrinsic matrix
- property px: float¶
The x pixel location of the principal point of the camera.
The principal point of the camera is the point in the image where the distortion is zero (the point where the optical axis pierces the image). This corresponds to the [0, 2] component of the intrinsic matrix
- property py: float¶
The y pixel location of the principal point of the camera.
The principal point of the camera is the point in the image where the distortion is zero (the point where the optical axis pierces the image). This corresponds to the [1, 2] component of the intrinsic matrix
- property a1: float¶
The linear coefficient for the focal length temperature dependence
This is the first term in the
temperature_coefficients
array and is multiplied by the temperature.
- property a2: float¶
The quadratic coefficient for the focal length temperature dependence
This is the second term in the
temperature_coefficients
array and is multiplied by the temperature squared.
- property a3: float¶
The cubic coefficient for the focal length temperature dependence
This is the third term in the
temperature_coefficients
array and is multiplied by the temperature cubed.
- property radial2: float¶
The radial distortion coefficient corresponding to the r**2 term
This corresponds to the [0] index of the distortion_coefficients array
- property e2: float¶
The radial distortion coefficient corresponding to the r**2 term
This corresponds to the [0] index of the distortion_coefficients array
- property radial4: float¶
The radial distortion coefficient corresponding to the r**4 term
This corresponds to the [1] index of the distortion_coefficients array
- property e4: float¶
The radial distortion coefficient corresponding to the r**4 term
This corresponds to the [1] index of the distortion_coefficients array
- property tangential_x: float¶
The tangential distortion coefficient corresponding to the x term
this corresponds to the [3] index of the distortion_coefficients array
- property e6: float¶
The tangential distortion coefficient corresponding to the x term
this corresponds to the [3] index of the distortion_coefficients array
- property tangential_y: float¶
The tangential distortion coefficient corresponding to the y term
this corresponds to the [2] index of the distortion_coefficients array
- property e5: float¶
The tangential distortion coefficient corresponding to the y term
this corresponds to the [2] index of the distortion_coefficients array
- property pinwheel1: float¶
The pinwheel distortion coefficient corresponding to the r term.
This corresponds to the [4] index of the distortion_coefficients array.
- property e1: float¶
The pinwheel distortion coefficient corresponding to the r term.
This corresponds to the [4] index of the distortion_coefficients array.
- property pinwheel2: float¶
The pinwheel distortion coefficient corresponding to the r**3 term.
This corresponds to the [5] index of the distortion_coefficients array.
- property e3: float¶
The pinwheel distortion coefficient corresponding to the r**3 term.
This corresponds to the [5] index of the distortion_coefficients array.
- property intrinsic_matrix_inv: ndarray¶
The inverse of the intrinsic matrix.
The inverse of the intrinsic matrix is used to convert from units of pixels with an origin at the upper left corner of the image to units of distance with an origin at the principal point of the image.
The intrinsic matrix has an analytic inverse which is given by
\[\begin{split}d=k_xk_y-k_{xy}k_{yx} \\ \mathbf{K}^{-1} = \left[\begin{array}{ccc} \frac{k_y}{d} & -\frac{k_{xy}}{d} & \frac{k_{xy}p_y-k_yp_x}{d} \\ -\frac{k_{yx}}{d} & \frac{k_x}{d} & \frac{k_{yx}p_x-k_xp_y}{d} \end{array}\right]\end{split}\]- To convert from units of pixels to units of distance you would do::
>>> from giant.camera_models import OwenModel >>> model = OwenModel(kx=5, ky=10, px=100, py=500) >>> ((model.intrinsic_matrix_inv[:, :2]@[[1, 2, 300], [4, 5, 600]]).T + model.intrinsic_matrix_inv[:, 2]).T array([[-19.8, -19.6, 40.] [-49.6, -49.5, 10.]])
Note
The above code will give you distorted gnomic location, while the
pixels_to_gnomic()
will give you undistorted gnomic locations (true pinhole points).Note
Since the intrinsic matrix is defined as a \(2\times 3\) matrix this isn’t a formal inverse. To get the true inverse you need to append a row of [0, 0, 1] to both the intrinsic matrix and intrinsic matrix inverse.
Methods
This method transforms 3D points or directions expressed in the camera frame into the corresponding 2D image locations. |
|
This method transforms 3D directions expressed in the camera frame into the corresponding 2D image directions. |
|
Calculates the Jacobian matrix for each observation in unit_vectors_camera for each parameter to be estimated as defined in the |
|
This method computes the Jacobian matrix \(\partial\mathbf{x}_P/\partial\mathbf{x}_C\) where \(\mathbf{x}_C\) is a vector in the camera frame that projects to \(\mathbf{x}_P\) which is the pixel location. |
|
This method computes the Jacobian matrix \(\partial\mathbf{x}_C/\partial\mathbf{x}_P\) where \(\mathbf{x}_C\) is a vector in the camera frame that projects to \(\mathbf{x}_P\) which is the pixel location. |
|
This method takes in a delta update to camera parameters (\(\Delta\mathbf{c}\)) and applies the update to the current instance in place. |
|
This method converts pixel image locations to unit vectors expressed in the camera frame. |
|
This method computes undistorted pixel locations (gnomic/pinhole locations) for given distorted pixel locations according to the current model. |
|
A method that takes gnomic pixel locations in units of pixels and applies the appropriate distortion to them. |
|
This method replaces self with the properties of |
|
This method computes the value of the distortion model across an entire image for use in creating distortion maps. |
|
This method takes in an entire image and warps it to remove the distortion specified by the current model. |
|
Returns a deep copy of this object, breaking all references with |
|
Stores this camera model in an |
|
This class method is used to construct a new instance of cls from an |
|
This method adjusts a pixel location to reflect a new image temperature. |
|
This method computes the scaling to the focal length caused by a shift in temperature. |
|
This method takes an input in pixels and computes the undistorted gnomic location in units of distance. |
|
This method prepares a SciPy RegularGridInterpolator for converting pixels into undistorted gnomic locations. |
|
This method takes an input in pixels and approximates the undistorted gnomic location in units of distance. |
|
This method computes and returns the pinhole, and pixel locations for a set of 3D points expressed in the camera frame. |
|
This method applies the distortion model to the specified pinhole (gnomic) locations in the image frame. |
|
Convert a list of estimation parameters into state label names. |
|
This method reset the misalignment terms to all be zero (no misalignment). |
|
This method returns the Rotation object for the misalignment for the requested image. |