FeatureCatalogue

giant.relative_opnav.estimators.sfn.surface_features:

class giant.relative_opnav.estimators.sfn.surface_features.FeatureCatalogue(features, map_info=None)

This class represents a collection of SurfaceFeatures for use in GIANT relative OpNav.

In GIANT, a surface feature is used to represent a small patch of surface which we look for in an image to generate a bearing measurement to in the process of SurfaceFeatureNavigation. Because we normally have many features in order to globally cover the surface, we need a special manager to handle all of these features, rather than making each one a SceneObject in a scene. That is the purpose of this class.

Essentially this class works as its own mini scene (in fact much of the code was copied from the Scene but without a Scene.light_obj. Somewhat confusingly though, this class is meant to be wrapped in a SceneObject and then stored as a Scene.target_obj for processing. To the user (and to the Scene) this will look like any other traceable object in GIANT for the most part.

Internally, the features are filtered with the include_features attribute, which is a list of integer indices into the features list of which features to include while tracing. Normally, however, a user won’t interact with this attribute, which is instead handled by the SurfaceFeatureNavigation class.

This class also collects some information about each feature into the feature_normals, feature_locations, and feature_bounds attributes, which are used to easily determine which features are visible for a given image in conjunction with the VisibleFeatureFinder class and the SurfaceFeatureNavigation class.

Similar to a KDTree, when something requests to rotate or translate the feature catalogue through the rotate() and translate() methods, the features themselves are not actually moved. Instead the rotation/translation is stored and is used to rotate/translate the rays into the original feature catalogue frame before ray tracing for performance reasons. These methods do update the feature_normals, feature_locations, and feature_bounds attributes though.

One of the keys of the SurfaceFeature class is that is provides a mechanism for lazy loading/unloading of the DEM data itself from memory. This class provides 2 easy properties to change the control of this lazy load/unload through the stale_count_unload_threshold and memory_percent_unload_threshold which can be used to change the corresponding settings for all features in the catalogue.

Creating a feature catalogue is a difficult process which has largely be automated into the spc_to_feature_catalogue and tile_shape scripts, which we encourage you to consider at least as examples if you are building your own. If you are making your own, once you have your list of SurfaceFeature objects, if you are using the lazy load/unload functionality, you should also provide a corresponding list of dictionaries which contain the bounding box vertices under key 'bounds' and the feature DEM order under key 'order'. Again, for an example of how to do this consider the tile_shape script.

Parameters:

• features (List[SurfaceFeature]) –

• map_info (List[Dict[str, int | ndarray]] | None) –

property stale_count_unload_threshold: int

The number of times not_found() must be called since the last found() was called for a feature to be unloaded from memory.

Setting to this property will change this value for all features contained in the catalogue.

property feature_finder: Callable[[CameraModel, Scene, Real], List[int]]

This property returns the feature finder for this class, which is a callable that takes in a camera model, scene, and temperature and returns a list of indices into the features list and related.

Typically this is an instance of VisibleFeatureFinder

property memory_percent_unload_threshold: Real

The memory percentage used by the current process at which point we begin unloading features that are not found regardless of how long its been since a feature was used.

If you trust your system to handle swap appropriately you can set this to some value greater than 100 which will effectively disable this check.

If you plan to run multiple instances of GIANT/SFN at the same time then you should probably set this value lower so that you limit the resources they are fighting over.

Setting to this property will change this value for all features contained in the catalogue.

property bounding_box: AxisAlignedBoundingBox

The approximate axis aligned bounding box of all of the features in the catalogue.

This is found by finding the minimum/maximum bound of the bounding box vertices (feature_bounds) rotated/translated into the current frame. As such, it is only a rough estimate.

Summary of Methods

get_first	This static method identifies the first intersection for each ray when there is more than 1 feature intersected.
rotate	Rotates the feature catalogue.
trace	This method traces rays through the feature catalogue, optionally filtering which features are included traced through the include_features attribute.
translate	Translates the feature catalogue.
update_feature_paths	This method goes through and updates the directory structure for each feature contained in the catalogue.