SurfaceFeature

giant.relative_opnav.estimators.sfn.surface_features:

class giant.relative_opnav.estimators.sfn.surface_features.SurfaceFeature(shape, normal, body_fixed_center, name, ground_sample_distance=None, stale_count_unload_threshold=10, memory_percent_unload_threshold=90)

This class represents a surface feature in GIANT.

In GIANT, a surface feature is defined a small DEM of a patch of surface combined with a name, the average ground sample distance of the DEM in kilometers, and a best fit plane through the topography of the DEM. The DEM itself is represented by a traceable object from the ray_tracer module (typically either a KDTree or a Surface subclass) and is stored in the shape attribute. The best fit plane is represent by a normal vector, expressed in the body-fixed frame, and the location of the center of the plane, expressed in the body-fixed frame, which are stored in the normal and body_fixed_center attributes respectively. Finally, the name and the ground sample distance are stored in the name and ground_sample_distance attributes respectively. These are all typically set at initialization of an instance of a surface feature. We note here that typically all of these attributes stay in the original frame in which they are defined unless you are manually messing with things. This is important for exporting your results to orbit determination software, which typically needs to know feature locations in a body fixed frame.

Surface features are normally created through an external program, like SPC, or by tiling a very high resolution global shape model. Both the process of ingesting a set of SPC features (called Maplets) and tiling a high resolution global shape model, are available in the spc_to_feature_catalogue and tile_shape scripts respectively, therefore, it is rare that you will manually create surface features using this class.

As discussed above, when doing surface feature navigation, the feature catalogue is normally very large, as we typically globally tile a surface at very small ground sample distances with significant overlap between each tile. This means that it is usually infeasible to hold an entire feature catalogue in memory at once. To alleviate this issue, this class provides a lazy loading/unloading mechanism that only keeps the actual shape information (which is by far the biggest memory hog) in memory when it is needed. With this mechanism, the DEM shape data is only loaded once something trying to access the shape attribute of an instance of this class. When this happens, the class will check if the DEM information has already been loaded into memory, and if not, it will load it automatically. Then, after a specified number of images (controlled by the stale_count_unload_threshold attribute) have been processed which do not need the DEM information, it will automatically unload the information from memory. Additionally, features can be unloaded from memory every time their not found if the memory footprint of the current process as a percent of the total system memory exceeds the threshold specified in the memory_percent_unload_threshold. This also can be controlled for all features in a FeatureCatalogue through the FeatureCatalogue.memory_percent_unload_threshold property. This loading/unloading is managed by calls to the found() and not_found() methods of this class.

The automatic loading and unloading of data is generally pretty invisible to the user outside of log messages, as it all happens automatically in the SurfaceFeatureNavigation and FindVisibleFeatures classes. That being said, you may need to consider tuning how quickly things are unloaded from memory, which can easily be set for all features in a catalogue through the FeatureCatalogue.stale_count_unload_threshold attribute. Typically you want to set this sufficiently large enough that you are not frequently loading/unloading the same features over and over again, but small enough that you don’t overwhelm the memory capabilities of your filter. On modern solid state hard drives, the read speeds are generally fast enough that you can set this number fairly low, even if you end up loading/unloading more than absolutely necessary. On older hard drives with slower read speeds you will generally what to try to make this as large as possible without consistently forcing your system to use swap. It can take some experimentation to find the sweet spot, but we do want to stress that ultimately you are not affect the results you are generating here, just the speed at which those results can be generated.

To use this automatic loading/unloading, when initializing the class, instead of the providing the traceable DEM data to the shape argument, instead provide a string or Path object that points to a pickle file containing the DEM data as the first object in the file.

Generally you will not interact with surface features directly all that frequently, and instead will interact with a catalogue of surface features through the FeatureCatalogue class.

Warning

When using the lazy load/unload feature of this class pickle files are read. While in general these pickle files have been created by GIANT and are completely safe, if the pickle files are somehow compromised or you received them from an untrusted source they could be used to execute arbitrary code on your system, therefore you should carefully verify that your pickle files have not been tampered with before using them.

Parameters:

• shape (Path | str | KDTree | Shape) – The shape object that represents the DEM topography for the feature as a KDTree or Shape, or the path to the file containing the shape object as a str or Path.

• normal (Sequence | ndarray) – The normal vector for the best fit plane to the DEM topography in the body-fixed frame

• body_fixed_center (Sequence | ndarray) – The center of the best fit plane to the DEM topography in the body-fixed frame

• name (str) – The name of the feature

• ground_sample_distance (Real | None) – The average ground sample distance of the DEM topography in kilometers.

• stale_count_unload_threshold (int) – The number of times a feature must be marked as not_found() for it to be unloaded from memory.

• memory_percent_unload_threshold (Real) – The size of the memory footprint of the current process as the percent of the total system memory before features are unloaded from memory.

property shape: Shape | KDTree

This property gives the traceable object that represents the DEM.

This will always return a traceable object (either a KDTree or a Shape, but if the DEM data hasn’t been loaded from disk yet there may be a slight delay while it is retrieved.

property bounding_box: AxisAlignedBoundingBox | None

This property returns the bounding box for the feature by retrieving the bounding box from the traceable shape object.

If for some reason the traceable shape object does not have a bounding_box attribute, None is returned.

Note that this property will access the Shape property, so if the DEM shape data has not yet been loaded from disk it will be loaded and there may be a slight delay.

property loaded: bool

This property simply returns whether the shape data is actively loaded into memory or not.

Summary of Methods

found	This method is called when the feature is found in an image and will be processed.
load	This method loads the shape information from disk.
not_found	This method is called when the feature is not found in an image.
trace	This method traces the provided rays through the feature DEM.
update_file	This updates the pointer to the file containing the DEM data for this feature.
update_path	This updates the absolute directory structure to the file containing the DEM data for this shape.