surface_features¶
This module implements the idea of a surface feature and surface feature catalogue for GIANT.
Detailed Description¶
In GIANT, a surface feature refers to a small path of surface from a body that is treated as an individual target to
identify in an image. A feature catalogue is then a collection of these features that is used for tracking the features
together and determining which are visible/worthy to search for in a given image. These capabilities are implemented in
the SurfaceFeature, FeatureCatalogue, and VisibleFeatureFinder respectively.
In more detail, a SurfaceFeature in GIANT is essentially a wrapper around a DEM modeled as a traceable object
(a KDTree or Shape) that also contains some basic information about the DEM, including the normal
vector of the best fit plane through the DEM data, the center of the DEM, and the average ground sample distance of the
DEM. Additionally, the SurfaceFeature class provides functionality for storing the DEM information itself on
disk until it is needed as well as managing at which point it can be unloaded from memory, which can be important for
long running processes.
The FeatureCatalogue then stores a list of these features, as well as some numpy arrays which combine all of
the normal vectors, bounding box vertices, and locations into single contiguous arrays for computational efficiency.
These numpy arrays also get rotated/translated whenever the feature catalogue gets rotated/translated, which means that
they are always in the current frame (which normally ends up being the camera frame). Additionally, this class provides
an option for filtering the features that are included when a call to the trace method is made.
Finally, the VisibleFeatureFinder operates on a feature catalogue to identify which features are visible in an
image based on the current knowledge of the scene at the time of the image. This filtering considers things like the
incidence and reflection angles, the ratio of the camera ground sample distance to the feature ground sample distance,
and the percentage of the feature predicted to actually be within the field of view of the camera.
For more in-depth details on each of these classes we encourage you to consider their documentation.
Lazy Loading/Unloading¶
One of the key things about surface features are that they are usually pretty high resolution patches of surface (that is patches of surface with small ground sample distances). We can get away with these small ground sample distances because the surface area each feature covers is also small, which means the size of any given feature is small. Despite this, we frequently have enough patches to globally cover the surface of the body we are imaging, and many times have features that overlap each other so we actually have enough features to cover the surface 2-3 times over. Beyond that, we also typically have global coverage of the surface with features at varying ground sample distances. All of this combines to mean that feature catalogues are typically huge, particularly when compared with a typical global model for a body. In many cases, because of this size, it is infeasible or even impossible to store the entire feature catalogue in memory at once, even on modern systems.
To overcome this issue, we have implemented a lazy loading/unloading scheme for feature catalogues and surface features
in GIANT. The way this scheme works is when we create a SurfaceFeature, instead of providing the DEM data
that represents the feature, we instead provide an absolute file path to a pickle file which contains just the DEM data
for the feature. When doing this, the size of each SurfaceFeature object in the FeatureCatalogue is
very small. Then, when we actually need the DEM data for the feature, we load it into memory from the referenced file.
This dramatically decreases the memory footprint of our process, making it feasible to operate through a whole feature
catalogue without using hundreds of GB of memory.
Now, this lazy loading is great at the start, but if we have a long running process that keeps using more and more features we will eventually end up loading the entire feature catalogue into memory anyway, which would ultimately defeat the purpose of the lazy loading. Therefore, we also provide an unloading mechanism, where the “time” since the feature was last used (time here being the number of images since we last used the feature) is used to determine if we should remove the feature from memory. Additionally, we provide a check one the percentage of the total system memory that the process is using and if we are over a certain percentage, we start unloading features regardless of when they were last used.
The combination of the loading and unloading makes surface feature navigation possible in GIANT even on systems with
modest amounts of memory available to the system. If you are working on a system with huge amounts of memory, you can
bypass these features, but for most people, even with large amounts of memory, we encourage leaving them on. For more
details on how you can tune each of these capabilities, refer to the FeatureCatalogue and
SurfaceFeature documentation.
One thing to note about using an absolute path to the file containing the DEM information for each feature is that it
makes feature catalogues brittle. That is, unless the directory structure between 2 systems is the same, you cannot
directly transfer a feature catalogue built on one system to another. To help with doing this, we provide the methods
FeatureCatalogue.update_feature_paths() and SurfaceFeature.update_path() which can be used to specify a
a new path for the files containing the surface feature DEMs.
Use¶
Generally a user will have minimal direct interaction with the classes in this module, as all of the interaction is
handled either by the SurfaceFeatureNavigation class for doing navigation or the
spc_to_feature_catalogue and tile_shape scripts for importing/building a feature catalogue. If you do
need to interact directly with the classes in this documentation we encourage you to consult the class documentation
directly and to look at the use of these classes in the mentioned class/scripts for examples/insight.
Classes
This class represents a collection of |
|
This class represents a surface feature in GIANT. |
|
This class creates a callable which is used to filter features that are visible in an image. |
|
This dataclass serves as one way to control the settings for the |