RelativeOpNav

giant.relative_opnav.relnav_class:

class giant.relative_opnav.relnav_class.RelativeOpNav(camera, scene, extended_body_cutoff=3, save_templates=False, image_processing=None, image_processing_kwargs=None, cross_correlation=None, cross_correlation_kwargs=None, unresolved=None, unresolved_kwargs=None, ellipse_matching=None, ellipse_matching_kwargs=None, limb_matching=None, limb_matching_kwargs=None, moment_algorithm=None, moment_algorithm_kwargs=None, sfn=None, sfn_kwargs=None, **kwargs)[source]

This class serves as the main user interface for performing relative optical navigation.

The class acts as a container for the Camera, ImageProcessing, and Scene instances as well as for instance of all of the registered RelNav techniques. By default the registered RelNav techniques are XCorrCenterFinding to cross_correlation, EllipseMatching' to :attr:`ellipse_matching, LimbMatching to limb_matching, MomentAlgorithm to moment_algorithm, and UnresolvedCenterFinding to unresolved. Besides storing all of these objects, it handles data transfer and collection between the different objects. Therefore, in general this class will be the exclusive interface for doing Relative OpNav.

For each registered technique, this class provides a few useful capabilities. First, it creates a property that returns the current instance of the class that implements the technique to make it easy to edit/modify properties. Second, it provides a {technique}_estimate method which can be used to apply the technique to specific or all image/target pairs. These _estimate methods also handle collecting and storing the data from the initialized objects as well as providing the appropriate data to the objects. Finally, for each registered technique this class provides the opportunity to pass either a pre-initialized instance of the object as a key word argument (using {technique}=instance) or the keyword arguments to use to initialize the instance (using {technique}_kwargs=dict) as part of the __init__ method for this class.

This class also provides a simple method for automatically determining which RelNav technique to use based on the expected apparent diameter of a target in the image, as well as the type of the shape representing the target in the scene. This method, auto_estimate() is generally sufficient for use for most missions that are doing typical RelNav type work and really makes doing RelNav easy.

For most RelNav types, the results will be collected and stored in the center_finding_results, relative_position_results, landmark_results, limb_results and saved_templates, depending on the type of RelNav used (where each type is stored will be described in the class documentation for the technique). In addition, each technique can store more details about what occurred in the fit to the {technique}_details attributes which are lists of lists where the outer list corresponds to the images and the inner lists corresponds to the targets in the scene. Typically these details are stored as dictionaries with detailed key names to indicate what each value means, but they can technically be any python object. The documentation for each technique will describe what is included in the details output.

When initializing this class, most of the initial options can be set using the *_kwargs inputs with dictionaries specifying the keyword arguments and values. Alternatively, you can provide already initialized instances of the objects if you want a little more control or want to use a subclass instead of the registered class itself. You should see the documentation for the registered techniques and the ImageProcessing class for more details about what settings can be specified at initialization.

It is possible to register new techniques to use with this class, which will automatically create many of the benefits just discussed. For details on how to do this, refer to the relnav_class, relnav_estimators, and register() documentation for details.

Parameters
property camera: giant.camera.Camera

The camera instance to perform OpNav on.

This should be an instance of the Camera class or one of its subclasses.

See the Camera class documentation for more details

property image_processing: giant.image_processing.ImageProcessing

The ImageProcessing instance to use when doing image processing on the images

This must be an instance of the ImageProcessing class.

See the ImageProcessing class documentation for more details

property model: giant.camera_models.camera_model.CameraModel

This alias returns the current camera model from the camera attribute.

It is provided for convenience since the camera model is used frequently.

property scene: giant.ray_tracer.scene.Scene

This property stores the scene describing the a priori conditions that the camera observed.

This is used to communicate both where to expect the target in the image, as well as how to render what we think the target should look like for techniques that use cross correlation. For more details see the scene documentation.

property cross_correlation: giant.relative_opnav.estimators.cross_correlation.XCorrCenterFinding

The XCorrCenterFinding instance to use when extracting center finding observables from images using cross-correlation.

This should be an instance of the XCorrCenterFinding class or a subclass.

See the XCorrCenterFinding documentation for more details.

property ellipse_matching: giant.relative_opnav.estimators.ellipse_matching.EllipseMatching

The EllipseMatching instance to use when extracting center finding observables from images using cross-correlation.

This should be an instance of the EllipseMatching class or a subclass.

See the EllipseMatching documentation for more details.

property limb_matching: giant.relative_opnav.estimators.limb_matching.LimbMatching

The LimbMatching instance to use when extracting center finding observables from images using cross-correlation.

This should be an instance of the LimbMatching class or a subclass.

See the LimbMatching documentation for more details.

property moment_algorithm: giant.relative_opnav.estimators.moment_algorithm.MomentAlgorithm

The MomentAlgorithm instance to use when extracting center finding observables from images using cross-correlation.

This should be an instance of the MomentAlgorithm class or a subclass.

See the MomentAlgorithm documentation for more details.

property unresolved: giant.relative_opnav.estimators.unresolved.UnresolvedCenterFinding

The UnresolvedCenterFinding instance to use when extracting center finding observables from images using cross-correlation.

This should be an instance of the UnresolvedCenterFinding class or a subclass.

See the UnresolvedCenterFinding documentation for more details.

Summary of Methods

add_images

This is essentially an alias to the Camera.add_images() method, but it also expands various lists to account for the new number of images.

auto_estimate

This method attempts to automatically determine the best RelNav technique to use for each image/target pair considered out of the most common RelNav techniques, unresolved, ellipse_matching, cross_correlation, and sfn.

cross_correlation_estimate

This method loops applies the cross_correlation technique to image/target pairs.

default_estimator

This method extracts observables from image(s) using the requested worker and stores them according to the types of observables generated by the technique.

ellipse_matching_estimate

This method loops applies the ellipse_matching technique to image/target pairs.

limb_matching_estimate

This method loops applies the limb_matching technique to image/target pairs.

moment_algorithm_estimate

This method loops applies the moment_algorithm technique to image/target pairs.

process_image

This is the default setup for processing an image through a RelNav technique and storing the results for a single image.

register

This class method registers a new RelNav technique with the RelativeOpNav class.

reset_image_processing

This method replaces the existing image processing instance with a new instance using the initial image_processing_kwargs argument passed to the constructor.

unresolved_estimate

This method loops applies the unresolved technique to image/target pairs.

update_image_processing

This method updates the attributes of the image_processing instance.