Camera¶

giant.camera:

class giant.camera.Camera(images=None, model=None, name=None, spacecraft_name=None, frame=None, parse_data=True, psf=None, attitude_function=None, start_date=None, end_date=None, metadata_only=False, default_image_class=<class 'giant.image.OpNavImage'>)[source]¶

This class collects images, the CameraModel, and some relevant metadata about the camera into a single object for passing to the GIANT estimators and measurements.

The Camera class is primarily a container for collecting and manipulating images and metadata for a single physical camera. This container is passed to the various measurement and estimation routines throughout GIANT to provide them with the requisite images and data needed to complete their tasks. The Camera object is also an iterator over the images that are turned on. This means you could do something like:

>>> from giant.camera import Camera
>>> import numpy
>>> # generate the image data
>>> image_list = [numpy.random.randn(100, 100) for _ in range(10)]  # type: List[np.ndarray]
>>> # create an instance with the images included
>>> cam = Camera(images=image_list, parse_data=False)
>>> # turn off a few of the images
>>> cam.image_mask[1], cam.image_mask[5], cam.image_mask[8] = False, False, False
>>> # iterate over the images that are turned on
>>> for ind, image in cam:
>>>    print(ind, numpy.array_equal(image_list[ind], image))
0 True
2 True
3 True
4 True
6 True
7 True
9 True

The implementation of the Camera object here is fully functional, however, you may want to subclass this object for customization purposes. For instance you may want to implement the preprocessor() method to apply corrections to images immediately after loading. You may also want to update the image_check() method to use a custom OpNavImage subclass instead of the default (alternatively you could override the default_image_class argument to __init__), or provide more custom functionality.

Parameters:

images (Iterable[Path | str | Sequence[Sequence] | ndarray] | Path | str | Sequence[Sequence] | ndarray | None) – A single image, or a list of images to store in the camera object. The image data can either be a string (in which case it is represents the path to the image file), an array of image data (this is generally not recommended), an OpNavImage object already initialized, or a list containing any of these three options.
model (CameraModel | None) – A camera model that represents how 3D points project onto the 2D imaging plane
name (str | None) – The name of the camera that is represented by this object. Not Required
spacecraft_name (str | None) – The name of the spacecraft that hosts the camera. Not Required
frame (str | None) – The name of the frame for this camera. Not Required
parse_data (bool) – A flag specifying whether to parse the metadata for each image when it is being loaded.
psf (PointSpreadFunction | None) – A callable object that applies a PSF to a 2D image, and provides a :meth`~.PointSpreadFunction.apply_1d` method to apply the PSF to 1D scan lines. Typically this is a PointSpreadFunction subclass.
attitude_function (Callable | None) – A function that returns the attitude of the camera frame with respect to the inertial frame for an input datetime object. This is generally a call to a spice routine generated by the spice_interface helper functions. (see the create_callable_orientation() and et_callable_to_datetime_callable() functions in particular)
start_date (datetime | None) – The time at which images should start being processed
end_date (datetime | None) – The time at which images should start being processed
metadata_only (bool) – Only load image metadata to an empty OpNavImage instead of loading the full image data.
default_image_class (type) – The class that the images stored in this instance should be an instance of.

start_date¶

The initial time to start processing images.

Any images with an observation_date before this epoch are ignored. This typically should be set to None (no filtering) or a python datetime object. See the apply_date_range() method for more details.

end_date¶

The final time to stop processing images.

Any images with an observation_date after this epoch are ignored. This typically should be set to None (no filtering) or a python datetime object. See the apply_date_range() method for more details.

name¶

The name of the camera.

This attribute is provided for documentation and convenience, but isn’t used directly by core GIANT functions. For an example of how one might use this attribute, see the getting started page for more details.

spacecraft_name¶

The name of the spacecraft hosting this camera (typically set to a spice id).

This attribute is provided for documentation and convenience, but isn’t used directly by core GIANT functions. For an example of how one might use this attribute, see the getting started page for more details.

property images: List[OpNavImage]¶

The list of OpNavImages contained in this camera object that should be considered by the GIANT routines.

Note that this attribute is read only. To add or remove images from the list, use the add_images() method or remove_images() method respectively as these will ensure that the images and image_mask lists stay in sync.

property image_mask: list¶

This property contains a mask for turning images on or off in the GIANT estimation and measurement routines.

The mask is a list of boolean values, where a True indicates that the image should be considered in the GIANT routines and returned when iterating over the images using this class and a False indicates that the image should not be considered in the GIANT routines or returned when iterating over the images using this class.

In general, you should not write to, or update this mask directly, and you should never add or remove elements from the list directly. Instead you should use the add_images() or remove_images() methods to add/remove images entirely and use the *_on or *_off methods to adjust the boolean values within the array.

Note

While it is strongly recommended to not directly modify this attribute, it is not write protected. Instead there is a setter method which ensures that anything set to this attribute is coerced to be the right length and type that is expected.

property psf: PointSpreadFunction | None¶

An object that applies a point spread function to 1D scan lines and 2D images.

This object should provide a __call__ method which applies the PSF to a 2D image, and an apply_1d method which applies the PSF to 1D scan lines (as the rows of a 2D array). Typically this is a subclass of PointSpreadFunction.

The PSF object is used when generating templates in GIANT for use with the surface feature and cross correlation techniques.

new_template = camera.psf(template)

property attitude_function: Callable¶

A function that returns the orientation of the camera frame with respect to the inertial frame as an Rotation object for a specific time input as a python datetime object.

This function is used in two different ways. First, it can be used to replace the attitude metadata in all of the images that are turned on directly using the update_attitude_from_function() method. This is useful when you are parsing the image metadata from an outdated source (such as the header information in a fits file) and want to update the attitude to reflect the most recent attitude knowledge. Second, this function can be used to compute delta quaternions in order to propagate a solved-for attitude from one image to another image using the update_short_attitude() method. This is useful when you are taking long-short exposure sequences and need to update the attitude of the short images based off of the solved-for attitude from the long images.

In both cases the call to this function passes a datetime object representing the UTC time we need the attitude for as the only argument and the function will return the attitude as an Rotation object.

In general, this function is a wrapper around spice calls to retrieve the attitude from a ck file. GIANT provides some helper routines in the spice_interface module to make it easy to generate this function. For instance, we can create a valid function for this attribute using the following:

>>> from giant.utilities.spice_interface import et_callable_to_datetime_callable
>>> from giant.utilities.spice_interface import create_callable_orientation
>>> attitude_function = et_callable_to_datetime_callable(create_callable_orientation('J2000', 'MyNavCam'))

and then we simply need to ensure we furnish a metakernel that provides enough information to compute the transformation from the J2000 inertial frame to the ‘MyNavCam’ frame. See the spice_interface documentation for more information about how this works.

property model: CameraModel¶

The camera model which describes how 3D points in the camera frame are transformed into 2D points in the image.

The object set to this class will be used by all GIANT routines that make use of a camera model to relate 3D and 2D points (which is nearly all of them).

For more information about camera models and their theories, refer to the camera_models module documentation.

Although not required, it is strongly recommended that the object assigned to this property be a subclass of CameraModel.

Summary of Methods

`add_images`	This method is used to add images to the `images` while also ensuring that the `image_mask` list remains the same size as the `images` list.
`short_on`	This method updates the `image_mask` attribute so that any image whose `exposure_type` is set to `SHORT` or `DUAL` is turned on (processed).
`short_off`	This method updates the `image_mask` attribute so that any image whose `exposure_type` is set to `SHORT` is turned off (not processed).
`only_short_on`	This method updated the `image_mask` list so that any image whose `exposure_type` attribute is set to `SHORT` or `DUAL` is turned on (processed) and any image whose `exposure_type` is set to `LONG` is turned off (not processed).
`long_on`	This method updates the `image_mask` attribute so that any image whose `exposure_type` is set to `LONG` or `DUAL` is turned on (processed).
`long_off`	This method updates the `image_mask` attribute so that any image whose `exposure_type` is set to `LONG` is turned off (not processed).
`only_long_on`	This method updated the `image_mask` list so that any image whose `exposure_type` attribute is set to `LONG` or `DUAL` is turned on (processed) and any image whose `exposure_type` is set to `SHORT` is turned off (not processed).
`all_on`	This method sets every element of the `image_mask` list to `True` so that all images are considered in the GIANT routines and returned when this class is iterated on.
`all_off`	This method sets every element of the `image_mask` list to `False` so that no images are considered in the GIANT routines or returned when this class is iterated on.
`sort_by_date`	This method is used to sort the images currently loaded to the `images` attribute by date.
`apply_date_range`	This method filters images by date, setting any whose `observation_date` is not between `start_date` and `end_date` to False.
`image_check`	This method is used to interpret the image data that is supplied by the user (either during initialization or through the `add_images()` method) and ensure that it is a subclass of `OpNavImage`
`preprocessor`	This method is used to globally apply corrections to all images contained in the `Camera` instance.
`remove_images`	This method is used to remove images from the `images` list while also ensuring that the `image_mask` list remains the same size as the `images` list.
`update_attitude_from_function`	This method is used ot overwrite the attitude information stored in all images that are turned on with information from the `attitude_function`.
`update_short_attitude`	This method updates the attitude metadata for short exposure images based off of the solved for attitudes in the long-exposure images.

Navigation

Related Topics

Camera¶