Summary

giant.utilities.stereophotoclinometry:

class giant.utilities.stereophotoclinometry.Summary(file_name=None, image_name=None, observation_date=None, num_cols=None, num_rows=None, min_illum=None, max_illum=None, focal_length=None, principle_point=None, position_camera_to_target=None, rotation_target_fixed_to_camera=None, direction_target_to_sun=None, intrinsic_matrix=None, near_dist_params=None, sig_pos_camera_to_target=None, sig_rot_target_fixed_to_camera=None)[source]

This class is used to read/write from the SPC summary (.SUM) files.

The summary files represent meta data about an Image. The image data itself is stored in a corresponding .DAT file which can be read/written with the Image class. When creating an instance of this class, you can enter the file_name argument, in which case the specified SUM file will be opened and read into the members of this class (if the sum file exists), or you can specify the individual components of the sum file as keyword arguments. If you specify both an existing SUM file and keyword arguments for the individual components of the SUM file, the keyword arguments will override whatever is read from the file.

The documentation for each instance attribute of this class specifies the corresponding location in the SUM file for clarification and reference.

Parameters:

  • file_name (Path | str | None) – The path to a summary file to read data from

  • image_name (str | None) – The name of the image this object corresponds to

  • observation_date (datetime | None) – The utc observation observation_date for the image as a python datetime object

  • num_cols (Real | None) – The number of columns in the image array

  • num_rows (Real | None) – The number of rows in the image array

  • min_illum (Real | None) – The minimum illumination value to allow for an image. SPC ignores pixels with DN values below this

  • max_illum (Real | None) – The maximum illumination value to allow for an image. SPC ignores pixels wiht DN values above this.

  • focal_length (Real | None) – The focal length of the camera in units of millimeters

  • principle_point (Sequence | ndarray | None) – The principal point of the camera (location where the optical axis pierces the image plane) in units of pixels.

  • position_camera_to_target (Sequence | ndarray | None) – The vector from the spacecraft to the target in the target body fixed frame as a length 3 numpy array

  • rotation_target_fixed_to_camera (Sequence | ndarray | None) – The 3x3 rotation matrix from the target body fixed frame to the camera frame

  • direction_target_to_sun (Sequence | ndarray | None) – The unit vector from the target to the sun in the target body fixed frame

  • intrinsic_matrix (Sequence | ndarray | None) – The intrinsic matrix of the camera (see the pinhole_model documentation for details

  • near_dist_params (Sequence | ndarray | None) – This obsolete array contains special distortion values for the cameras that were flown on NEAR. This should be all 0 for all modern SPC use.

  • sig_pos_camera_to_target (Sequence | ndarray | None) – This is the formal uncertainty on the position_camera_to_target vector (1 sigma)

  • sig_rot_target_fixed_to_camera (Sequence | ndarray | None) – This is the formal uncertainty on the spacecraft pointing (roll, pitch, yaw?) (1 sigma)

landmarks

A dictionary of observed SPC landmarks and their observed locations in units of pixels.

The keys to the dictionary are the SPC landmark names (typically 6 character alpha numeric names) and the values are the pixel location the landmark was identified at in the image. Each value is the x, y or column, row location as a length 2 list of floats

This corresponds to all of the lines between LANDMARKS and LIMB FITS or END FILE in the SUM file.

limb_fits

A dictionary of observed SPC landmarks that occur on the limb of the target in the image and their observed locations in units of pixels and formal uncertainty.

The keys to the dictionary are the SPC landmark names (typically 6 character alpha numeric names) and the values are the pixel location the landmark was identified at in the image followed by the uncertainty of the fit. Each value is the x, y, sigma or column, row, sigma as a length 3 list of floats

This corresponds to all of the lines between LIMB FITS and LANDMARKS or END FILE in the SUM file.

file_name: Path | str | None

The path to the summary file that this object was populated from.

This also will be the file that changes are written to if write() is called with no arguments.

Typically this is named according to SUMFILES/IMAGENAME.SUM where IMAGENAME is replaced with the SPC name of the image. This can be set to None, a str, or a Path.

image_name: str | None

The name of the image this object corresponds to.

This corresponds to the first line of the SUM file.

observation_date: datetime | None

The middle of the time in UTC that the image was exposed during as a python datetime object.

This corresponds to the second line of the SUM file.

num_cols: int | None

The integer number of columns in the image this Summary object corresponds to.

This corresponds to the first value of the line containing NPX, NLN, THRSH in the SUM file (typically the third line).

num_rows: int | None

The integer number of rows in the image this Summary object corresponds to.

This corresponds to the second value of the line containing NPX, NLN, THRSH in the SUM file (typically the third line).

min_illum: Real | None

The minimum DN value for a pixel to be used in SPC.

Pixels with DN values below this threshold are ignored when computing correlation coefficients and other values in SPC.

This corresponds to the third value of the line containing NPX, NLN, THRSH in the SUM file (typically the third line).

max_illum: Real | None

The maximum DN value for a pixel to be used in SPC.

Pixels with DN values above this threshold are ignored when computing correlation coefficients and other values in SPC.

This corresponds to the fourth value of the line containing NPX, NLN, THRSH in the SUM file (typically the third line).

focal_length: Real | None

The focal length of the camera in units of mm.

This corresponds to the first value of the line containing MMFL, CTR in the SUM file (typically the fourth line).

princ_point: ndarray

The principle point of the camera as a length 2 numpy array of floats.

This typically corresponds to the PinholeModel.px and PinholeModel.py attributes of the Pinhole based camera models in GIANT. The first component is for the x-axis (columns) and the second component is for the y-axis (rows).

This corresponds to the second and third values of the line containing MMFL, CTR in the SUM file (typically the fourth line).

position_camera_to_target: ndarray

The position vector from the spacecraft to the target in target body fixed coordinates at the time of the image with units of kilometers as a length 3 numpy array of floats.

This corresponds to all the values of the line containing SCOBJ in the SUM file (typically the fifth line).

rotation_target_fixed_to_camera: ndarray

The rotation matrix from the target body fixed frame to the camera frame at the time of the image as a shape 3x3 numpy array of floats.

This corresponds to all the values of the lines containing CX, CY, CZ in the SUM file (typically the sixth through the eighth lines). The matrix is formed according to np.vstack([CX, CY, CZ])

direction_target_to_sun: ndarray

The unit vector from the target to the sun in the target body fixed frame at the time of the image as a length 3 numpy array of floats.

This corresponds to all the values of the line containing SZ in the sum file (typically the ninth line).

intrinsic_matrix: ndarray

The intrinsic matrix of the camera as a shape 2x3 numpy array of floats.

This has an extra column that is kept for SPC compatibility reasons but which is not used anymore. Therefore, this does not directly correspond to the PinholeModel.intrinsic_matrix attribute of the Pinhole model and its subclasses in GIANT, but rather the first 2 columns of this matrix correspond to the first 2 columns of the intrinsic matrix in GIANT and the 3rd column should be discarded.

This corresponds to all of the values of the line containing K-MATRIX in the SUM file (typically the tenth line). Weirdly this is a row major flattening of the intrinsic matrix in the SUM file.

near_dist_params: ndarray

The deprecated NEAR distortion parameters.

Just leave these at 0.

This corresponds to all of the values of the line containing DISTORTION in the SUM file (typically the eleventh line).

sig_pos_camera_to_target: ndarray

The formal uncertainty on the position_camera_to_target vector as a length 3 numpy array of floats.

The formal uncertainty are the 1 sigma values for each component of the position vector.

This corresponds to all of the values of the line containing SIGMA_VSO in the SUM file (typically the twelfth line).

sig_rot_target_fixed_to_camera: ndarray

The formal uncertainty on the rotation from the target body frame to the spacecraft frame as a length 3 numpy array of floats.

The formal uncertainty are the 1 sigma values.

This corresponds to all of the values of the line containing SIGMA_PTG in the SUM file (typically the thirteenth line).

Summary of Methods

read

This method reads data from a SPC SUM file (normally SUMFILES/IMAGENAME.SUM) and populates the attributes of this class with that data.

write

This function writes the data contained in the current instance of the class into the specified file