EllipseMatching

giant.relative_opnav.estimators.ellipse_matching:

class giant.relative_opnav.estimators.ellipse_matching.EllipseMatching(scene, camera, options=None)

This class implements GIANT’s version of limb based OpNav for regular bodies.

The class provides an interface to perform limb based OpNav for each target body that is predicted to be in an image. It does this by looping through each target object contained in the Scene.target_objs attribute that is requested. For each of the targets, the algorithm:

1. If using limb scanning to extract the limbs, and requested with recenter, identifies the center of brightness for each target using the moment_algorithm and moves the a priori target to be along that line of sight

2. Extracts the observed limbs from the image and pairs them to the target

3. Estimates the relative position between the target and the image using the observed limbs and the steps discussed in the :mod:.ellipse_matching` documentation

4. Uses the estimated position to get the predicted limb surface location and predicted limb locations in the image

When all of the required data has been successfully loaded into an instance of this class, the estimate() method is used to perform the estimation for the requested image. The results are stored into the observed_bearings attribute for the observed limb locations and the observed_positions attribute for the estimated relative position between the target and the camera. In addition, the predicted location for the limbs for each target are stored in the computed_bearings attribute and the a priori relative position between the target and the camera is stored in the computed_positions attribute. Finally, the details about the fit are stored as a dictionary in the appropriate element in the details attribute. Specifically, these dictionaries will contain the following keys.

Key	Description
'Covariance'	The 3x3 covariance matrix for the estimated relative position in the camera frame based on the residuals. This is only available if successful
'Surface Limb Points'	The surface points that correspond to the limb points in the target fixed target centered frame.
'Failed'	A message indicating why the fit failed. This will only be present if the fit failed (so you could do something like 'Failed' in limb_matching.details[target_ind] to check if something failed. The message should be a human readable description of what called the failure.

Warning

Before calling the estimate() method be sure that the scene has been updated to correspond to the correct image time. This class does not update the scene automatically.

Parameters:

• scene (Scene) – The Scene object containing the target, light, and obscuring objects.

• camera (Camera) – The Camera object containing the camera model and images to be utilized

• image_processing – The ImageProcessing object to be used to process the images

• options (EllipseMatchingOptions | None) – A dataclass specifying the options to set for this instance.

technique: str | None = 'ellipse_matching'

The name of the technique identifier in the RelativeOpNav class.

observable_type: List[RelNavObservablesType | str] | RelNavObservablesType | str | None = [RelNavObservablesType.LIMB, RelNavObservablesType.RELATIVE_POSITION]

The type of observables this technique generates.

property camera: Camera

The camera instance that represents the camera used to take the images we are performing Relative OpNav on.

This is the source of the camera model, and may be used for other information about the camera as well. See the Camera property for details.

generates_templates: bool = False

A flag specifying whether this RelNav estimator generates and stores templates in the templates attribute.

relnav_handler: Callable | None = None

A custom handler for doing estimation/packaging the results into the RelativeOpNav instance.

Typically this should be None, unless the observable_type is set to RelNavObservablesType.CUSTOM, in which case this must be a function where the first and only positional argument is the RelativeOpNav instance that this technique was registered to and there are 2 key word arguments image_ind and include_targets which should be used to control which image/target is processed.

If observable_type is not RelNavObservablesType.CUSTOM then this is ignored whether it is None or not.

property scene: Scene

The scene which defines the a priori locations of all targets and light sources with respect to the camera.

You can assume that the scene has been updated for the appropriate image time inside of the class.

details: List[Any | None]

This attribute should provide details from applying the technique to each target in the scene.

The list should be the same length at the Scene.target_objs. Typically, if the technique was not applied for some of the targets then the details for the corresponding element should be None. Beyond each element of the details should typically contain a dictionary providing information about the results that is not strictly needed for understanding what happened, however, this is not required and you can use whatever structure you want to convey the information. Whatever you do, however, you should clearly document it for each technique so that the user can know what to expect.

computed_positions: List[NONEARRAY]

A list of the computed relative position between the target and the camera in the image frame where each element corresponds to the same element in the Scene.target_objs list.

The list elements should be numpy arrays or None if the the target wasn’t considered or this type of measurement is not applicable. If numpy arrays they should contain the relative position between the camera and the target as a length 3 array with units of kilometers in the camera frame. This does not need to be populated for all RelNav techniques

This is were you should store results for RELATIVE-POSITION techniques.

computed_bearings: List[NONEARRAY]

A list of the computed (predicted) bearings in the image where each element corresponds to the same element in the Scene.target_objs list.

The list elements should be numpy arrays or None if the the target wasn’t considered for some reason. If numpy arrays they should contain the pixel locations as (x, y) or (col, row). This does not always need to be filled out.

This is were you should store results for CENTER-FINDING, LIMB, LANDMARK, CONSTRAINT techniques.

observed_positions: List[NONEARRAY]

A list of the observed relative position between the target and the camera in the image frame where each element corresponds to the same element in the Scene.target_objs list.

The list elements should be numpy arrays or None if the the target wasn’t considered or this type of measurement is not applicable. If numpy arrays they should contain the relative position between the camera and the target as a length 3 array with units of kilometers in the camera frame. This does not need to be populated for all RelNav techniques

This is were you should store results for RELATIVE-POSITION techniques.

observed_bearings: List[NONEARRAY]

A list of the observed bearings in the image where each element corresponds to the same element in the Scene.target_objs list.

The list elements should be numpy arrays or None if the the target wasn’t considered for some reason. If numpy arrays they should contain the pixel locations as (x, y) or (col, row). This does not always need to be filled out.

This is were you should store results for CENTER-FINDING, LIMB, LANDMARK, CONSTRAINT techniques.

extraction_method: LimbExtractionMethods = 'EDGE_DETECTION'

The method to use to extract the observed limbs from the image. Should be 'LIMB_SCANNING' or 'EDGE_DETECTION'. See LimbExtractionMethods for details.

limbs_camera: List[NONEARRAY]

The limb surface points with respect to the center of the target

Until estimate() is called this list will be filled with None.

Each element of this list corresponds to the same element in the Scene.target_objs list.

recenter: bool = True

A flag specifying whether to locate the center of the target using a moment algorithm before beginning.

If the a priori knowledge of the bearing to the target is poor (outside of the body) then this flag will help to correct the initial error. See the moment_algorithm module for details.

This is only used if the extraction method is set to LIMB_SCANNING as it does not affect the EDGE_DETECTION extraction method.

Summary of Methods

estimate	This method identifies the position of each target in the camera frame using ellipse matching.
extract_and_pair_limbs	Extract and pair limb points in an image to the surface point on a target that created it.
reset	This method resets the observed/computed attributes, the details attribute, and the limb attributes to have None.
target_generator	This method returns a generator which yields target_index, target pairs that are to be processed based on the input include_targets.