StarID

giant.stellar_opnav.star_identification:

class giant.stellar_opnav.star_identification.StarID(model, options=None)

The StarID class operates on the result of image processing algorithms to attempt to match image points of interest with catalog star records.

This is a necessary step in all forms of stellar OpNav and is a critical component of GIANT.

In general, the user will not directly interface with the StarID class and instead will use the StellarOpNav class. Below we give a brief description of how to use this class directly for users who are just curious or need more direct control over the class.

There are a couple things that the StarID class needs to operate. The first is a camera model, which should be a subclass of CameraModel. The camera model is used to both project catalog star locations onto the image, as well as generate unit vectors through the image points of interest in the camera frame. The next thing the StarID class needs is a star catalog to query. This should come from the catalogs package and provides all of the necessary information for retrieving and projecting the expected stars in an image. Both the star catalog and camera model are generally set at the construction of the class and apply to every image being considered, so they are rarely updated. The camera model is stored in the model attribute and is also specified as the first positional argument for the class constructor. The catalog is stored in the catalog attribute and can also be specified in the class constructor as a keyword argument of the same name.

The StarID class also needs some information about the current image being considered. This information includes points of interest for the image that need to be matched to stars, the a priori attitude of the image, and the position/velocity of the camera at the time the image was captured. The points of interest are generally returned from the PointOfInterestFinder routines, although they don’t need to be. The camera attitude, position, velocity, and a priori orientation are generally passed from the OpNavImage metadata. The a priori image attitude is used for querying the catalog and rotating the catalog stars into the image frame. The camera positions and velocity are used for correcting the star locations for parallax and stellar aberration. The camera position and velocity are not required but are generally recommended as they will give a more accurate representation.

Finally, there are a number of tuning parameters that need set. These parameters are discussed in depth in the Tuning Parameters Table.

When everything is correctly set in an instance of StarID, then generally all that needs to be called is the id_stars() method, which accepts the observation date of the image being considered as an optional epoch keyword argument. This method will go through the whole processed detailed above, storing the results in a number of attributes that are detailed below.

Parameters:

• model (CameraModel) – The camera model to use to relate vectors in the camera frame with points on the image

• options (StarIDOptions | None) – StarIDOptions

model: CameraModel

The camera model which relates points in the camera frame to points in the image and vice-versa.

queried_catalog_image_points: DOUBLE_ARRAY | None

A 2xn numpy array of points containing the projected image points for all catalog stars that were queried from the star catalog with x (columns) in the first row and y (rows) in the second row.

Each column corresponds to the same row in queried_catalog_star_records.

Until project_stars() is called this will be None.

queried_catalog_star_records: DataFrame | None

A pandas DataFrame of all the catalog star records that were queried.

See the Catalog class for a description of the columns of the dataframe.

Until project_stars() is called this will be None.

queried_catalog_unit_vectors: DOUBLE_ARRAY | None

A 3xn numpy array of unit vectors in the inertial frame for all catalog stars that were queried from the star catalog.

Each column corresponds to the same row in queried_catalog_star_records.

Until project_stars() is called this will be None.

queried_weights_inertial: DOUBLE_ARRAY | None

This contains the formal total uncertainty for each unit vector from the queried catalog stars.

Each element in this array corresponds to the same row in the queried_catalog_star_records.

Until id_stars() is called this will be None.

queried_weights_picture: DOUBLE_ARRAY | None

This contains the formal total uncertainty for each projected pixel location from the queried catalog stars in units of pixels..

Each element in this array corresponds to the same row in the queried_catalog_star_records.

Until id_stars() is called this will be None.

unmatched_catalog_image_points: DOUBLE_ARRAY | None

A 2xn numpy array of points containing the projected image points for all catalog stars that not matched with an extracted image point, with x (columns) in the first row and y (rows) in the second row.

Each column corresponds to the same row in unmatched_catalog_star_records.

Until id_stars() is called this will be None.

catalog: Catalog

The star catalog to use when pairing image points with star locations.

This typically should be a subclass of the Catalog class. It defaults to the Gaia.

max_magnitude: float = 7

The maximum star magnitude to query from the star catalog.

This specifies how dim stars are expected to be in the extracted_image_points data set. This is typically dependent on both the detector and the exposure length of the image under consideration.

min_magnitude: float = -10

The minimum star magnitude to query from the star catalog.

This specifies how dim stars are expected to be in the extracted_image_points data set. This is typically dependent on both the detector and the exposure length of the image under consideration.

Generally this should be left alone unless you are worried about over exposed stars (in which case ImageProcessing.reject_saturation may be more useful) or you are doing some special analysis.

max_combos: int = 100

The maximum number of random combinations to try in the RANSAC algorithm.

If the total possible number of combinations is less than this attribute then an exhaustive search will be performed instead

tolerance: float = 20

The maximum distance in units of pixels between a projected catalog location and an extracted image point for a possible pairing to be made for consideration in the RANSAC algorithm.

ransac_tolerance: float = 5

The tolerance that is required after correcting for attitude errors for a pair to be considered an inlier in the RANSAC algorithm in units of pixels.

This should always be less than the tolerance attribute.

second_closest_check: bool = True

A boolean specifying whether to ignore extracted image points where multiple catalog points are within the specified tolerance.

unique_check: bool = True

A boolean specifying whether to ignore possible catalog to image point pairs where multiple image points are within the specified tolerance of a single catalog point.

use_mp: bool = False

A boolean flag specifying whether to use multi-processing to speed up the RANSAC process.

If this is set to True then all available CPU cores will be utilized to parallelize the RANSAC algorithm computations. For small combinations, the overhead associated with this can swamp any benefit that may be realized.

compute_weights: bool = False

A boolean specifying whether to compute the formal uncertainties for the unit vectors

and the pixel locations of the catalog stars.

unmatched_catalog_star_records: DataFrame | None

A pandas DataFrame of all the catalog star records that were not matched to an extracted image point in the star identification routine.

See the Catalog class for a description of the columns of the dataframe.

Until id_stars() is called this will be None.

unmatched_catalog_unit_vectors: DOUBLE_ARRAY | None

A 3xn numpy array of unit vectors in the inertial frame for all catalog stars that were not matched to an extracted image point in the star identification routine.

Each column corresponds to the same row in matched_catalog_star_records.

Until id_stars() is called this will be None.

unmatched_weights_inertial: DOUBLE_ARRAY | None

This contains the formal total uncertainty for each unit vector from the queried catalog stars that were not matched with an extracted image point.

Each element in this array corresponds to the same row in the unmatched_catalog_star_records.

Until method id_stars() is called this will be None.

unmatched_weights_picture: DOUBLE_ARRAY | None

This contains the formal total uncertainty for each projected pixel location from the queried catalog stars that were not matched with an extracted image point in units of pixels.

Each element in this array corresponds to the same row in the unmatched_catalog_star_records.

Until method id_stars() is called this will be None.

matched_catalog_image_points: DOUBLE_ARRAY | None

A 2xn numpy array of points containing the projected image points for all catalog stars that were matched with an extracted image point, with x (columns) in the first row and y (rows) in the second row.

Each column corresponds to the same row in matched_catalog_star_records.

Until id_stars() is called this will be None.

matched_catalog_star_records: DataFrame | None

A pandas DataFrame of all the catalog star records that were matched to an extracted image point in the star identification routine.

See the Catalog class for a description of the columns of the dataframe.

Each row of the dataframe corresponds to the same column index in the matched_extracted_image_points.

Until id_stars() is called this will be None.

matched_catalog_unit_vectors: DOUBLE_ARRAY | None

A 3xn numpy array of unit vectors in the inertial frame for all catalog stars that were matched to an extracted image point in the star identification routine.

Each column corresponds to the same row in matched_catalog_star_records.

Until id_stars() is called this will be None.

matched_extracted_image_points: DOUBLE_ARRAY | None

A 2xn array of the image points of interest that were not paired with a catalog star in the star identification routine.

The first row contains to the x locations (columns) and the second row contains to the y locations (rows).

Each column corresponds to the same row in the matched_catalog_star_records for its pairing.

Until id_stars() is called this will be None.

matched_weights_inertial: DOUBLE_ARRAY | None

This contains the formal total uncertainty for each unit vector from the queried catalog stars that were matched with an extracted image point.

Each element in this array corresponds to the same row in the matched_catalog_star_records.

Until methods id_stars() is called this will be None.

matched_weights_picture: DOUBLE_ARRAY | None

This contains the formal total uncertainty for each projected pixel location from the queried catalog stars that were matched with an extracted image point in units of pixels.

Each element in this array corresponds to the same row in the matched_catalog_star_records.

Until method id_stars() is called this will be None.

Summary of Methods

id_stars	This method attempts to match the image points of interest with catalog stars.
ransac	This method performs RANSAC on the image poi-catalog location pairs.
compute_pointing	This method computes the right ascension and declination of an axis of the camera frame in units of degrees.
project_stars	This method queries the star catalog for predicted stars within the field of view and projects those stars onto the image using the camera model.
query_catalog	This method queries stars from the catalog within the field of view.
ransac_iter_test	This performs a single ransac iteration.