giant.relative_opnav¶

This package provides the required routines and objects to extract observables to targets in an image.

Description¶

In GIANT, Relative OpNav refers to the process of extracting observables from monocular images of non-star targets. These observables can take many different forms, and are usually fed to some type of filter or estimator to use in refining the knowledge of the relative state between the camera and the target. Some of the most common forms of RelNav measurements are bearing observables to the center of figure of an object, bearing observables to a surface feature on a target, bearing measurements to points on the illuminated limb of a target, full 3DOF relative position measurements between the camera and the center of figure of the target, and constraint measurements (or bearing measurements to the same, possibly unknown, feature in multiple images. In addition to the different types of observables that can be extracted from images, there are also many different techniques for extracting these observables. Taken together, all of these choices can make doing RelNav and writing code to do RelNav confusing and difficult. Therefore, as with the StellarOpNav class, in GIANT we have made a single user interface to handle most of these techniques and make doing RelNav significantly easier in the form of the RelativeOpNav class.

The RelativeOpNav class is generally the only interface a user will require when performing relative OpNav. Indeed, in most cases, doing RelNav using this class is as simple as initializing the class with some basic settings and then calling auto_estimate(), which will attempt to automatically deduce what technique is best suited for extracting observables from the images based on what is expected to be seen in the images and apply those techniques to the images. This means it is largely possible to do RelNav without having a super in-depth understanding of what exactly is going on, though at least a basic understanding certainly helps. For those with an in-depth understanding, the RelativeOpNav class also provides easy access to many of the sub-steps required, allowing for more fine-grained control and more advanced analysis.

This package level documentation only focuses on the use of the class to do RelNav for typical cases. If you need a deeper understanding of what is going on, or you need to do some advanced analysis (or possibly even create your own RelNav technique) then we encourage you to read the sub-module/package documentation from this package (relative_opnav.estimators, relnav_class, and relative_opnav.visualizer)

Tuning for Successful Relative OpNav¶

Tuning is generally simple for most relative OpNav techniques, especially when compared to stellar OpNav. In most cases, the only tuning parameter you really need to worry about is the extended_body_cutoff. This knob tells the auto_estimate() method when to switch from using the unresolved technique, where the target in the image is assumed to be dominated by the point spread function of the camera, to using resolved techniques based on the shape representation of the target. Typically you want this set around 5-10 pixels, though if you have a particularly large PSF for your camera then you may want to increase this slightly. Beyond that, at least for method auto_estimate(), most of the default tuning parameters should be sufficient to get pretty good RelNav results. If you need more control over the tuning for individual techniques you should refer to their module documentation which you can get to from relative_opnav.estimators.

Modules

`relnav_class`	This module provides a subclass of the `OpNav` class for performing relative OpNav.
`estimators`	This package provides an abstract base class that defines the interface GIANT expects for Relative OpNav techniques as well as concrete implementations some of the most commonly used RelNav techniques.
`visualizers`	This module provides some basic visualization functions for various relnav results.

Classes

`RelativeOpNav`	This class serves as the main user interface for performing relative optical navigation.
`XCorrCenterFindingOptions`	This dataclass serves as one way to control the settings for the `XCorrCenterFinding` class.
`XCorrCenterFinding`	This class implements normalized cross correlation center finding for GIANT.
`UnresolvedCenterFindingOptions`
`UnresolvedCenterFinding`	This class implements GIANT's version of unresolved center finding for extracting bearing measurements to unresolved targets in an image.
`MomentAlgorithmOptions`
`MomentAlgorithm`	This class implements GIANT's version of moment based center finding for extracting bearing measurements to resolved or or unresolved targets in an image.
`EllipseMatchingOptions`	Options for configuring the EllipseMatching class
`EllipseMatching`	This class implements GIANT's version of limb based OpNav for regular bodies.
`LimbMatchingOptions`
`LimbMatching`	This class implements GIANT's version of limb based OpNav for irregular bodies.
`ConstraintMatchingOptions`	This dataclass serves as one way to control the settings for the `ConstraintMatching` class.
`ConstraintMatching`	This class implements constraint matching in GIANT.
`SurfaceFeatureNavigationOptions`	This dataclass serves as one way to control the settings for the `SurfaceFeatureNavigation` class.
`SurfaceFeatureNavigation`	This class implements surface feature navigation using normalized cross correlation template matching for GIANT.
`SurfaceFeature`	This class represents a surface feature in GIANT.
`FeatureCatalog`	This class represents a collection of `SurfaceFeatures` for use in GIANT relative OpNav.
`VisibleFeatureFinderOptions`	This dataclass serves as one way to control the settings for the `VisibleFeatureFinder` at initialization.
`VisibleFeatureFinder`	This class creates a callable which is used to filter features that are visible in an image.

Functions

`visualizers.show_templates`	Show the rendered template alongside of a specific image.
`visualizers.show_limbs`	Show the observed and computed limbs on a specific image.
`visualizers.limb_summary_gif`	Generate a GIF of the observed and predicted limbs
`visualizers.template_summary_gif`	Generate a GIF of the rendered templates from relnav
`visualizers.show_center_finding_residuals`	Plot the center finding residuals as a function of time.
`visualizers.scatter_residuals_sun_dependent`	Show observed minus computed residuals with units of pixels plotted in a frame rotated so that +x points towards the sun in the image.
`visualizers.plot_residuals_sun_dependent_time`	Show observed minus computed residuals with units of pixels plotted in a frame rotated so that +x points towards the sun in the image.