SurfaceFeatureNavigationOptions

giant.relative_opnav.estimators.sfn.sfn_class:

class giant.relative_opnav.estimators.sfn.sfn_class.SurfaceFeatureNavigationOptions(brdf=None, rays=None, grid_size=1, peak_finder=<function quadric_peak_finder_2d>, min_corr_score=0.5, blur=True, search_region=10, run_pnp_solver=False, pnp_ransac_iterations=0, second_search_region=None, measurement_sigma=1, position_sigma=None, attitude_sigma=None, state_sigma=None, max_lsq_iterations=None, lsq_relative_error_tolerance=1e-08, lsq_relative_update_tolerance=1e-08, cf_results=None, cf_index=None, show_templates=False)

This dataclass serves as one way to control the settings for the SurfaceFeatureNavigation class.

You can set any of the options on an instance of this dataclass and pass it to the SurfaceFeatureNavigation class at initialization (or through the method SurfaceFeatureNavigation.apply_options()) to set the settings on the class. This class is the preferred way of setting options on the class due to ease of use in IDEs.

Parameters:

• brdf (IlluminationModel | None) –

• rays (Rays | None | List[Rays | None]) –

• grid_size (int) –

• peak_finder (Callable[[ndarray, bool], ndarray]) –

• min_corr_score (float) –

• blur (bool) –

• search_region (int) –

• run_pnp_solver (bool) –

• pnp_ransac_iterations (int) –

• second_search_region (int | None) –

• measurement_sigma (Sequence | ndarray | Real) –

• position_sigma (Sequence | ndarray | Real | None) –

• attitude_sigma (Sequence | ndarray | Real | None) –

• state_sigma (Sequence | ndarray | None) –

• max_lsq_iterations (int | None) –

• lsq_relative_error_tolerance (float) –

• lsq_relative_update_tolerance (float) –

• cf_results (ndarray | None) –

• cf_index (List[int] | None) –

• show_templates (bool) –

min_corr_score: float = 0.5

The minimum correlation score to accept for something to be considered found in an image. The correlation score is the Pearson Product Moment Coefficient between the image and the template. This should be a number between -1 and 1, and in nearly every cast a number between 0 and 1. Setting this to -1 essentially turns the minimum correlation score check off.

search_region: int = 10

The number of pixels to search around the a priori predicted center for the peak of the correlation surface.

run_pnp_solver: bool = False

A flag specifying whether to use the PnP solver to correct errors in the initial relative state between the camera and the target body

pnp_ransac_iterations: int = 0

The number of RANSAC iterations to attempt in the PnP solver. Set to 0 to turn the RANSAC component of the PnP solver

second_search_region: int | None = None

The distance around the nominal location to search for each feature in the image after correcting errors using the PnP solver.

measurement_sigma: Sequence | ndarray | Real = 1

The uncertainty to assume for each measurement in pixels. This is used to set the relative weight between the observed landmarks are the a priori knowledge in the PnP problem. See the measurement_sigma documentation for a description of valid inputs.

position_sigma: Sequence | ndarray | Real | None = None

The uncertainty to assume for the relative position vector in kilometers. This is used to set the relative weight between the observed landmarks and the a priori knowledge in the PnP problem. See the position_sigma documentation for a description of valid inputs. If the state_sigma input is not None then this is ignored.

attitude_sigma: Sequence | ndarray | Real | None = None

The uncertainty to assume for the relative orientation rotation vector in radians. This is used to set the relative weight between the observed landmarks and the a priori knowledge in the PnP problem. See the attitude_sigma documentation for a description of valid inputs. If the state_sigma input is not None then this is ignored.

state_sigma: Sequence | ndarray | None = None

The uncertainty to assume for the relative position vector and orientation rotation vector in kilometers and radians respectively. This is used to set the relative weight between the observed landmarks and the a priori knowledge in the PnP problem. See the state_sigma documentation for a description of valid inputs. If this input is not None then the attitude_sigma and position_sigma inputs are ignored.

max_lsq_iterations: int | None = None

The maximum number of iterations to make in the least squares solution to the PnP problem.

lsq_relative_error_tolerance: float = 1e-08

The relative tolerance in the residuals to signal convergence in the least squares solution to the PnP problem.

lsq_relative_update_tolerance: float = 1e-08

The relative tolerance in the update vector to signal convergence in the least squares solution to the PnP problem

cf_results: ndarray | None = None

A numpy array containing the center finding residuals for the target that the feature catalogue is a part of. If present this is used to correct errors in the a priori line of sight to the target before searching for features in the image.

cf_index: List[int] | None = None

A list that maps the features catalogues contained in the scene (in order) to the appropriate column of the cf_results matrix. If left blank the mapping is assumed to be in like order

show_templates: bool = False

A flag to show the rendered templates for each feature “live”. This is useful for debugging but in general should not be used.

blur: bool = True

A flag to perform a Gaussian blur on the correlation surface before locating the peak to remove high frequency noise

brdf: IlluminationModel | None = None

The illumination model that transforms the geometric ray tracing results (see ILLUM_DTYPE) into an intensity values. Typically this is one of the options from the illumination module).

grid_size: int = 1

The subsampling to use per pixel when rendering the template. This should be the number of sub-pixels per side of a pixel (that is if grid_size=3 then subsampling will be in an equally spaced 3x3 grid -> 9 sub-pixels per pixel). If rays is not None then this is ignored

rays: Rays | None | List[Rays | None] = None

The rays to use when rendering the template. If None then the rays required to render the template will be automatically computed. Optionally, a list of Rays objects where each element corresponds to the rays to use for the corresponding template in the Scene.target_objs list. Typically this should be left as None.

Summary of Methods

peak_finder

This function returns a numpy array containing the (x, y) location of the maximum surface value which corresponds to the peak of the fitted quadric surface to subpixel accuracy.