Detector

giant.ufo.detector:

class giant.ufo.detector.Detector(sopnav, scene=None, dn_offset=0, image_information_function=None, magnitude_function=None, update_attitude_kwargs=None, find_ufos_kwargs=None, unmatched_star_threshold=3, hot_pixel_threshold=5, create_hashed_index=True)[source]

This class is used to identify possible non-cooperative unresolved targets in optical images.

This is done by first extracting bright points from the image, then fitting point spread functions to the bright spots in an image, and finally removing bright points that correspond to stars. All of this is primarily handled by the :class:.StellarOpNav` class, and this class serves as a wrapper for collecting data from the StellarOpNav class and for packaging each possible detection (with additional information) into a pandas Dataframe for easy export/processing.

To use this class simply provide the required initialization inputs, call update_attitude(), call find_ufos(), call package_results(), call remove_duplicates(), and then optionally call save_results() to save the results to a csv file.

For more details on tuning for detection and the full UFO process, including tacking, see the ufo package documentation.

Parameters:

  • sopnav (StellarOpNav) – The stellar opnav instance that will be used for star and UFO identification/attitude estimation

  • scene (Scene | None) – The optional scene instance defining the location of the light source and any extended bodies

  • dn_offset (Real) – The dn offset of the detector, used for computing magnitude/statistics about the observed UFO

  • image_information_function (Callable[[OpNavImage], Tuple[float, float, float, Sequence | ndarray | Real]] | None) – A function that gives the quantization noise, read noise, and electron to DN conversion factor for the detector and predicts the dark current for a input OpNavImage object (or None). If None then the SNR values will be less meaningful.

  • magnitude_function (Callable[[List[float], OpNavImage], ndarray | List[float]] | None) – A function that computes the apparent magnitude for detections based off of the input 5x5 summed DN for the detections and the image the detection came from. If None then the magnitude will not be computed and will be stored as 0 for all detections.

  • update_attitude_kwargs (Dict[str, Dict[str, Any]] | None) – A dictionary of str -> dictionary where the keys are “star_id_kwargs”, “image_processing_kwargs”, or “attitude_estimator_kwargs” and the values are dictionaries specifying the key word argument -> value pairs for the appropriate class. This is used to update the settings before attempting to solve for the attitude in each image. (update_attitude())

  • find_ufos_kwargs (Dict[str, Dict[str, Any]] | None) – A dictionary of str -> dictionary where the keys are “star_id_kwargs”, “image_processing_kwargs”, or “attitude_estimator_kwargs” and the values are dictionaries specifying the key word argument -> value pairs for the appropriate class. This is used to update the settings before attempting to identify ufos in the image (find_ufos())

  • hot_pixel_threshold (int) – The minimum number of images a (x_raw, y_raw) pair must appear in for the detections to be labeled a possible hot pixel

  • unmatched_star_threshold (int) – The minimum number of images a (ra, dec) pair must appear in for the detections to be labeled a possible unmatched star

  • create_hashed_index (bool) – This boolean flag indicates that when packaging the results (package_results()) the index of the resulting dataframe should be build from a hash of 'image_file_{x_raw}_{y_raw}' instead of just using an index. This makes it easier to identify the detections uniquely and is recommended to be left True

Summary of Methods

add_images

This is essentially an alias to the StellarOpNav.add_images() method, but it also expands various lists to account for the new number of images.

clear_results

This clears all extracted UFOs/Stars from the instance with the exception of the detection_data_frame for memory purposes.

find_ufos

This method finds unidentified bright spots (not matching a star or an extended body) in the images turned on in the camera.

identify_hot_pixels_and_unmatched_stars

This method is used to attempt to autonomously identify detections due to consistent hot-pixels (where the same pixel is very bring in many images) or do to an unmatched star (where the same inertial direction is observed in multiple images).

package_results

This method packages information about UFOs (and matched stars) into attributes in this class and as a Pandas DataFrame that can be stored to any number of table formats.

remove_duplicates

Removes duplicates from the dataframe.

save_results

This method saves the results into csv files.

update_attitude

This method estimates the attitude for each turned on image in the camera.