asp_plot.csm_io

asp_plot.csm_io#

Camera-model I/O helpers mirrored from the NASA Ames Stereo Pipeline (ASP).

The functions in this module are kept function-based and as close to verbatim as practical to the upstream orbit_plot.py so they can be re-synced when ASP changes. Do not refactor these into classes or rename them without a corresponding upstream change – that would make future syncing painful.

Upstream source: NeoGeographyToolkit/StereoPipeline

Related CSM/CsmUtils references are noted inline on the individual functions.

Attributes#

ASP_TO_CSM_SHIFT

Functions#

`estim_satellite_orientation`(positions)	Estimate satellite orientation at each position.
`getLineAtTime`(time, model)	Get the line number at a given time in a linescan camera model.
`getTimeAtLine`(model, line)	Find the time at a given line in a linescan camera model.
`isLinescan`(cam_file)	Check if a camera file is for a linescan sensor.
`read_angles`(orig_cams, opt_cams, ref_cams)	Extract and convert camera orientations to roll, pitch, yaw angles.
`read_csm_cam`(json_file)	Read a CSM model state file in JSON format.
`read_frame_cam_dict`(cam)	Read a frame camera model file into a dictionary.
`read_frame_csm_cam`(json_file)	Read position and orientation from a CSM Frame camera file.
`read_linescan_pos_rot`(json_file)	Read positions and rotations from a CSM linescan camera file.
`read_positions_rotations`(cams)	Read positions and rotations from multiple camera files.
`read_positions_rotations_from_file`(cam_file)	Read positions and rotations from a camera file.
`read_tsai_cam`(tsai)	Read a TSAI frame camera model into a dictionary.
`roll_pitch_yaw`(rot_mat, ref_rot_mat)	Calculate roll, pitch, and yaw angles relative to a reference orientation.
`toCsmPixel`(asp_pix)	Convert an ASP pixel coordinate to a CSM pixel coordinate.
`tsai_list_to_gdf`(tsai_fn_list)	Convert a list of TSAI camera files to a GeoDataFrame.

Module Contents#

asp_plot.csm_io.estim_satellite_orientation(positions)#

Estimate satellite orientation at each position.

Parameters:: positions (list of array-like) – List of satellite positions in ECEF coordinates
Returns:: List of rotation matrices representing satellite orientation
Return type:: list of numpy.ndarray

Notes

For each position, computes a local coordinate system where: - x axis is the direction of motion - z points roughly down (towards Earth center) - y is perpendicular to both x and z

asp_plot.csm_io.getLineAtTime(time, model)#

Get the line number at a given time in a linescan camera model.

Parameters:

time (float) – Time to convert to line number
model (dict) – CSM camera model parameters

Returns:

Line number corresponding to the given time

Return type:

float

Raises:

Exception – If the model does not have a linear relationship between time and lines

Notes

This function computes the line number in the image corresponding to the given time, assuming a linear relationship between time and line number. Code adapted from get_line_at_time() in CsmUtils.cc.

asp_plot.csm_io.getTimeAtLine(model, line)#

Find the time at a given line in a linescan camera model.

Parameters:

model (dict) – CSM camera model parameters
line (int) – Line number in the image (0-based)

Returns:

Time corresponding to the given line

Return type:

float

Notes

The time is computed using the linear mapping between line number and time defined in the CSM model. Code adapted from get_time_at_line() in CsmUtils.cc and getImageTime() in UsgsAstroLsSensorModel.cpp.

asp_plot.csm_io.isLinescan(cam_file)#

Check if a camera file is for a linescan sensor.

Parameters:: cam_file (str) – Path to the camera file
Returns:: True if the camera is a linescan sensor, False otherwise
Return type:: bool

Notes

This function reads the first line of the camera file to check if it contains the string “LINE_SCAN”, which indicates a linescan camera.

asp_plot.csm_io.read_angles(orig_cams, opt_cams, ref_cams)#

Extract and convert camera orientations to roll, pitch, yaw angles.

Parameters:

orig_cams (list of str) – List of paths to original camera files
opt_cams (list of str) – List of paths to optimized camera files
ref_cams (list of str) – List of paths to reference camera files (can be empty)

Returns:

Tuple containing (orig_rotation_angles, opt_rotation_angles) where: - orig_rotation_angles is a list of Euler angles for original cameras - opt_rotation_angles is a list of Euler angles for optimized cameras

Return type:

tuple

Raises:

SystemExit – If the number of original and reference cameras don’t match

Notes

This function extracts the orientation of cameras and converts them to Euler angles (roll, pitch, yaw) relative to a reference orientation. If reference cameras are not provided, it estimates the reference orientation from the camera positions.

asp_plot.csm_io.read_csm_cam(json_file)#

Read a CSM model state file in JSON format.

Parameters:: json_file (str) – Path to the CSM JSON state file
Returns:: Dictionary containing the CSM model parameters
Return type:: dict

Notes

CSM JSON files sometimes have text before the actual JSON content. This function handles that by finding the first open brace and parsing the JSON from that point.

asp_plot.csm_io.read_frame_cam_dict(cam)#

Read a frame camera model file into a dictionary.

Parameters:: cam (str) – Path to the camera file (.tsai or .json)
Returns:: Dictionary containing camera parameters
Return type:: dict
Raises:: Exception – If the file extension is not recognized

asp_plot.csm_io.read_frame_csm_cam(json_file)#

Read position and orientation from a CSM Frame camera file.

Parameters:: json_file (str) – Path to the CSM JSON state file
Returns:: Dictionary containing camera center and rotation matrix
Return type:: dict

Notes

This function extracts the camera position and orientation from a CSM frame camera model. The camera position is given by the first three parameters, and the orientation is represented as a quaternion that is converted to a rotation matrix.

asp_plot.csm_io.read_linescan_pos_rot(json_file)#

Read positions and rotations from a CSM linescan camera file.

Parameters:: json_file (str) – Path to the CSM JSON state file
Returns:: Tuple containing (positions, rotations) where: - positions is a list of camera positions - rotations is a list of rotation matrices
Return type:: tuple

Notes

Linescan cameras have different positions and orientations for each line in the image. This function extracts the full list of positions and orientations from the CSM model.

asp_plot.csm_io.read_positions_rotations(cams)#

Read positions and rotations from multiple camera files.

Parameters:: cams (list of str) – List of paths to camera files
Returns:: Tuple containing (positions, rotations) where: - positions is a list of camera positions - rotations is a list of rotation matrices
Return type:: tuple
Raises:: SystemExit – If the number of positions and rotations don’t match

Notes

This function reads all the camera files and concatenates their positions and rotations into single lists.

asp_plot.csm_io.read_positions_rotations_from_file(cam_file)#

Read positions and rotations from a camera file.

Parameters:: cam_file (str) – Path to the camera file
Returns:: Tuple containing (positions, rotations) where: - positions is a list of camera positions - rotations is a list of rotation matrices
Return type:: tuple

Notes

This function handles both linescan and frame cameras. For linescan cameras, it returns multiple positions and rotations corresponding to different lines in the image. For frame cameras, it returns a single position and rotation.

asp_plot.csm_io.read_tsai_cam(tsai)#

Read a TSAI frame camera model into a dictionary.

Parameters:: tsai (str) – Path to ASP frame camera model file (.tsai)
Returns:: Dictionary containing camera model parameters
Return type:: dict

Notes

TSAI is a camera model format used by ASP. It contains parameters such as focal length, optical center, camera position, and orientation. See ASP documentation for more details: https://stereopipeline.readthedocs.io/en/latest/pinholemodels.html

asp_plot.csm_io.roll_pitch_yaw(rot_mat, ref_rot_mat)#

Calculate roll, pitch, and yaw angles relative to a reference orientation.

Parameters:

rot_mat (numpy.ndarray) – Rotation matrix for the camera
ref_rot_mat (numpy.ndarray) – Reference rotation matrix

Returns:

Array of Euler angles [roll, pitch, yaw] in degrees

Return type:

numpy.ndarray

Notes

This function calculates the orientation of a camera relative to a reference orientation, and returns the result as Euler angles in roll, pitch, yaw (rotation around x, y, z axes) in degrees.

asp_plot.csm_io.toCsmPixel(asp_pix)#

Convert an ASP pixel coordinate to a CSM pixel coordinate.

Parameters:: asp_pix (array-like) – ASP pixel coordinates as [x, y]
Returns:: CSM pixel coordinates
Return type:: numpy.ndarray

Notes

ASP and CSM use slightly different pixel coordinate conventions. CSM pixel coordinates are shifted by 0.5 pixels relative to ASP. Code copied from CsmModel.cc in ASP.

asp_plot.csm_io.tsai_list_to_gdf(tsai_fn_list)#

Convert a list of TSAI camera files to a GeoDataFrame.

Parameters:: tsai_fn_list (list of str) – List of paths to TSAI camera files
Returns:: GeoDataFrame containing camera model parameters with a Point geometry column for camera centers
Return type:: geopandas.GeoDataFrame

asp_plot.csm_io.ASP_TO_CSM_SHIFT = 0.5#