asp_plot.csm_camera

Attributes

ASP_TO_CSM_SHIFT

Functions

csm_camera_summary_plot(cam1_list[, cam2_list, ...])	Generate a comprehensive summary plot comparing camera parameters.
estim_satellite_orientation(positions)	Estimate satellite orientation at each position.
format_stat_value(value)	Format a numeric value with appropriate precision.
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.
get_orbit_plot_gdf(original_camera, optimized_camera)	Create a GeoDataFrame containing camera positions and orientation differences.
isLinescan(cam_file)	Check if a camera file is for a linescan sensor.
plot_stats_text(ax, mean, std[, unit])	Add a text annotation showing statistics to a plot.
poly_fit(X, Y)	Fit a linear polynomial to data and return the fitted values.
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.
reproject_ecef(positions[, to_epsg])	Reproject ECEF coordinates to a specified EPSG coordinate system.
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_camera.csm_camera_summary_plot(cam1_list, cam2_list=None, map_crs=None, title=None, trim=True, shared_scales=False, log_scale_positions=False, log_scale_angles=False, upper_magnitude_percentile=95, figsize=(20, 15), save_dir=None, fig_fn=None, add_basemap=False, **ctx_kwargs)

Generate a comprehensive summary plot comparing camera parameters.

Parameters:

• cam1_list (list) – List containing paths to the original and optimized camera files for the first camera

• cam2_list (list or None, optional) – List containing paths to the original and optimized camera files for the second camera, default is None

• map_crs (int or None, optional) – EPSG code for the coordinate reference system for map plots, default is None (use ECEF)

• title (str or None, optional) – Additional title text to append to the default title, default is None

• trim (bool, optional) – Whether to trim data to image lines for linescan cameras, default is True

• shared_scales (bool, optional) – Whether to use the same y-axis scale for all position/angle plots, default is False

• log_scale_positions (bool, optional) – Whether to use logarithmic scale for position difference plots, default is False

• log_scale_angles (bool, optional) – Whether to use logarithmic scale for angle difference plots, default is False

• upper_magnitude_percentile (int, optional) – Percentile for setting colorbar upper limit, default is 95

• figsize (tuple, optional) – Figure size (width, height) in inches, default is (20, 15)

• save_dir (str or None, optional) – Directory to save the plot, default is None (don’t save)

• fig_fn (str or None, optional) – Filename for the saved plot, default is None

• add_basemap (bool, optional) – Whether to add a basemap to map plots, default is False

• **ctx_kwargs – Additional keyword arguments passed to contextily.add_basemap()

Notes

This function creates a comprehensive visualization comparing original and optimized camera parameters. It shows the spatial distribution of position and orientation differences, as well as detailed plots of individual components (x, y, z, roll, pitch, yaw). If two cameras are provided, the comparison is shown for both cameras in a larger figure.

asp_plot.csm_camera.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_camera.format_stat_value(value)

Format a numeric value with appropriate precision.

Parameters:

value (float) – The numeric value to format

Returns:

Formatted string representation of the value

Return type:

str

Notes

Uses scientific notation for very small values (abs(value) < 0.01) and fixed-point notation with 2 decimal places otherwise.

asp_plot.csm_camera.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_camera.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_camera.get_orbit_plot_gdf(original_camera, optimized_camera, map_crs=None, trim=True)

Create a GeoDataFrame containing camera positions and orientation differences.

Parameters:

• original_camera (str) – Path to the original camera file

• optimized_camera (str) – Path to the optimized camera file

• map_crs (int or None, optional) – EPSG code for the target coordinate system, default is None (keep ECEF)

• trim (bool, optional) – Whether to trim data to only the first and last image lines for linescan cameras, default is True

Returns:

A GeoDataFrame containing camera positions and orientation data with columns for position differences, angle differences, and original values

Return type:

geopandas.GeoDataFrame

Notes

This function compares the original and optimized camera models and calculates the differences in position and orientation. For linescan cameras, it optionally trims the data to only include samples corresponding to the actual image lines.

asp_plot.csm_camera.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_camera.plot_stats_text(ax, mean, std, unit='m')

Add a text annotation showing statistics to a plot.

Parameters:

• ax (matplotlib.axes.Axes) – The axis on which to add the text

• mean (float) – Mean value to display

• std (float) – Standard deviation value to display

• unit (str, optional) – Unit to use for display, default is ‘m’

Notes

The text is displayed in the lower left corner of the plot with a white background box for readability.

asp_plot.csm_camera.poly_fit(X, Y)

Fit a linear polynomial to data and return the fitted values.

Parameters:

• X (array-like) – Independent variable values

• Y (array-like) – Dependent variable values

Returns:

Fitted Y values from a degree 1 polynomial fit

Return type:

numpy.ndarray

asp_plot.csm_camera.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_camera.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_camera.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_camera.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_camera.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_camera.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_camera.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_camera.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_camera.reproject_ecef(positions, to_epsg=4326)

Reproject ECEF coordinates to a specified EPSG coordinate system.

Parameters:

• positions (numpy.ndarray) – A 2D array of ECEF coordinates, where each row represents a point

• to_epsg (int, optional) – The EPSG code of the target coordinate system, default is 4326 (WGS84)

Returns:

A 2D array of reprojected coordinates in the target EPSG coordinate system

Return type:

numpy.ndarray

Notes

ECEF (Earth-Centered, Earth-Fixed) coordinates are a 3D Cartesian coordinate system with the origin at the center of the Earth. This function converts those coordinates to a different coordinate system specified by an EPSG code.

asp_plot.csm_camera.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_camera.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_camera.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_camera.ASP_TO_CSM_SHIFT = 0.5