StarID

giant.stellar_opnav.star_identification:

class giant.stellar_opnav.star_identification.StarID(model, extracted_image_points=None, catalogue=None, max_magnitude=7, min_magnitude=-10, max_combos=100, tolerance=20, a_priori_rotation_cat2camera=None, ransac_tolerance=5, second_closest_check=True, camera_velocity=None, camera_position=None, unique_check=True, use_mp=False, lost_in_space_catalogue_file=None)

The StarID class operates on the result of image processing algorithms to attempt to match image points of interest with catalogue 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 catalogue 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 catalogue to query. This should come from the catalogues package and provides all of the necessary information for retrieving and projecting the expected stars in an image. Both the star catalogue 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 catalogue is stored in the catalogue 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 ImageProcessing routines, although they don’t need to be. The camera attitude, position, and velocity are generally passed from the OpNavImage metadata. The image attitude is used for querying the catalogue and rotating the catalogue 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. All of these attributes need to be updated for each new image being considered (the StarID class does not directly operate on the OpNavImage objects). The image points of interest are stored and updated in the extracted_image_points attribute, the camera attitude is stored in the a_priori_rotation_cat2camera attribute, and the camera position and velocity are stored in the camera_position and camera_velocity attributes respectively. They can also be specified in the class constructor as keyword arguments of the same name.

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.

Warning

This class will load data for the lost in space catalogue. The lost is space catalogue is a pickle file. Pickle files can be used to execute arbitrary code, so you should never open one from an untrusted source. While this code should only be reading pickle files generated by GIANT itself that are safe, you should verify that the lost_in_space_catalogue_file and the file it points to have not been tampered with to be absolutely sure.

Parameters:

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

• extracted_image_points (ndarray) – A 2xn array of the image points of interest to be identified. The first row should correspond to the y locations (rows) and the second row should correspond to the x locations (columns).

• catalogue (Catalogue) – The catalogue object to use to query for potential stars in an image.

• max_magnitude (Real) – the maximum magnitude to return when querying the star catalogue

• min_magnitude (Real) – the minimum magnitude to return when querying the star catalogue

• max_combos (int) – The maximum number of random samples to try in the RANSAC routine

• tolerance (Real) – The maximum distance between a catalogue star and a image point of interest for a potential pair to be formed before the RANSAC algorithm

• a_priori_rotation_cat2camera (Rotation) – The rotation matrix to go from the inertial frame to the camera frame

• ransac_tolerance (Real) – The maximum distance between a catalogue star and an image point of interest after correcting the attitude for a pair to be considered an inlier in the RANSAC algorithm.

• second_closest_check (bool) – A flag specifying whether to reject pairs where 2 catalogue stars are close to an image point of interest

• camera_velocity (ndarray) – The velocity of the camera in km/s with respect to the solar system barycenter in the inertial frame at the time the image was taken

• camera_position (ndarray) – The position of the camera in km with respect to the solar system barycenter in the inertial frame at the time the image was taken

• unique_check (bool) – A flag specifying whether to allow a single catalogue star to be potentially paired with multiple image points of interest

• use_mp (bool) – A flag specifying whether to use the multi-processing library to accelerate the RANSAC algorithm

• lost_in_space_catalogue_file (Path | str | None) – The file containing the lost in space catalogue

model: CameraModel

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

camera_position: ndarray

The position of the camera with respect to the solar system barycenter in the inertial frame at the time the image was captured as a length 3 numpy array of floats.

Typically this is stored in the OpNavImage.position attribute

camera_velocity: ndarray

The velocity of the camera with respect to the solar system barycenter in the inertial frame at the time the image was captured as a length 3 numpy array of floats.

Typically this is stored in the OpNavImage.velocity attribute

extracted_image_points: ndarray

a 2xn array of the image points of interest to be paired with catalogue stars.

the first row should correspond to the x locations (columns) and the second row should correspond to the y locations (rows).

typically this is retrieved from a call to ImageProcessing.locate_subpixel_poi_in_roi().

catalogue: Catalogue

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

This typically should be a subclass of the Catalogue class. It defaults to the GIANTCatalogue.

a_priori_rotation_cat2camera: Rotation

This contains the a priori rotation knowledge from the catalogue frame (typically the inertial frame) to the camera frame at the time of the image.

This typically is stored as the OpNavImage.rotation_inertial_to_camera attribute.

max_magnitude: Real

The maximum star magnitude to query from the star catalogue.

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: Real

The minimum star magnitude to query from the star catalogue.

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.

tolerance: Real

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

max_combos: int

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

ransac_tolerance: Real

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

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

unique_check: bool

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

use_mp: bool

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.

queried_catalogue_image_points: Sequence | ndarray | None

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

Each column corresponds to the same row in queried_catalogue_star_records.

Until project_stars() is called this will be None.

queried_catalogue_star_records: DataFrame | None

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

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

Until project_stars() is called this will be None.

queried_catalogue_unit_vectors: Sequence | ndarray | None

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

Each column corresponds to the same row in queried_catalogue_star_records.

Until project_stars() is called this will be None.

queried_weights_inertial: Sequence | ndarray | None

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

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

Until id_stars() is called this will be None.

queried_weights_picture: Sequence | ndarray | None

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

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

Until id_stars() is called this will be None.

unmatched_catalogue_image_points

A 2xn numpy array of points containing the projected image points for all catalogue 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_catalogue_star_records.

Until id_stars() is called this will be None.

unmatched_catalogue_star_records: Sequence | ndarray | None

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

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

Until id_stars() is called this will be None.

unmatched_catalogue_unit_vectors: Sequence | ndarray | None

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

Each column corresponds to the same row in matched_catalogue_star_records.

Until id_stars() is called this will be None.

unmatched_weights_inertial: Sequence | ndarray | None

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

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

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

unmatched_weights_picture: Sequence | ndarray | None

This contains the formal total uncertainty for each projected pixel location from the queried catalogue 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_catalogue_star_records.

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

matched_catalogue_image_points: Sequence | ndarray | None

A 2xn numpy array of points containing the projected image points for all catalogue 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_catalogue_star_records.

Until id_stars() is called this will be None.

matched_catalogue_star_records: Sequence | ndarray | None

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

See the Catalogue 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_catalogue_unit_vectors: Sequence | ndarray | None

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

Each column corresponds to the same row in matched_catalogue_star_records.

Until id_stars() is called this will be None.

matched_extracted_image_points: Sequence | ndarray | None

A 2xn array of the image points of interest that were not paired with a catalogue 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_catalogue_star_records for its pairing.

Until id_stars() is called this will be None.

matched_weights_inertial: Sequence | ndarray | None

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

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

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

matched_weights_picture: Sequence | ndarray | None

This contains the formal total uncertainty for each projected pixel location from the queried catalogue 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_catalogue_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 catalogue stars.
ransac	This method performs RANSAC on the image poi-catalogue 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 catalogue for predicted stars within the field of view and projects those stars onto the image using the camera model.
query_catalogue	This method queries stars from the catalogue within the field of view.
ransac_iter_test	This performs a single ransac iteration.