asp_plot.stereopair_metadata_parser

asp_plot.stereopair_metadata_parser#

Attributes#

logger

Classes#

StereopairMetadataParser

Parse metadata from satellite sensor XML files for stereo pairs.

Functions#

`get_asymmetry_angle`(sat1_pos, sat2_pos, ground_point)	Calculate asymmetry angle between satellite positions and ground point.
`get_bh_ratio`(conv_ang)	Calculate base-to-height ratio from convergence angle.
`get_bie_angle`(az1, el1, az2, el2)	Calculate Bisector Elevation Angle for a stereo pair.
`get_convergence_angle`(az1, el1, az2, el2)	Calculate convergence angle between two satellite viewing directions.

Module Contents#

class asp_plot.stereopair_metadata_parser.StereopairMetadataParser(directory)#

Parse metadata from satellite sensor XML files for stereo pairs.

This class parses Digital Globe/Maxar or similar satellite XML files to extract metadata and compute stereo geometry parameters. It handles single XML files as well as multiple XML files per scene, where mosaicking is required.

directory#

Path to directory containing XML files

Type:: str

image_list#

List of XML files found in the directory

Type:: list

Examples

>>> parser = StereopairMetadataParser('/path/to/stereo/directory')
>>> pair_dict = parser.get_pair_dict()
>>> print(f"Convergence angle: {pair_dict['conv_ang']}")
>>> print(f"Base-to-height ratio: {pair_dict['bh']}")

getAtt(xml)#

Extract attitude data from XML file.

Retrieves satellite attitude (orientation quaternion and covariance) data from the XML file.

Parameters:: xml (str) – Path to the XML file
Returns:: Array of shape (N, 15) containing attitude data with columns: point_num, q1, q2, q3, q4, and 10 covariance matrix elements (upper triangle of 4x4 matrix)
Return type:: numpy.ndarray

getAtt_df(xml)#

Create a DataFrame from attitude data.

Converts attitude data to a DataFrame with time index.

Parameters:: xml (str) – Path to the XML file
Returns:: DataFrame with attitude quaternions and covariance, time-indexed
Return type:: pandas.DataFrame

getEphem(xml)#

Extract ephemeris data from XML file.

Retrieves satellite ephemeris (position and velocity) data from the XML file.

Parameters:: xml (str) – Path to the XML file
Returns:: Array containing ephemeris data with columns: point_num, Xpos, Ypos, Zpos, Xvel, Yvel, Zvel, and covariance matrix elements
Return type:: numpy.ndarray

Notes

All coordinates are in Earth-Centered Fixed (ECF) reference frame. Units are meters for positions, meters/sec for velocities, and m^2 for covariance.

getEphem_gdf(xml)#

Create a GeoDataFrame from ephemeris data.

Converts ephemeris data to a GeoDataFrame with time index and Point geometry.

Parameters:: xml (str) – Path to the XML file
Returns:: GeoDataFrame with ephemeris data and Point geometries in EPSG:4978
Return type:: geopandas.GeoDataFrame

Notes

The GeoDataFrame uses EPSG:4978 (Earth-Centered Earth-Fixed) CRS and has a time index corresponding to the acquisition times.

get_catid_dicts()#

Get dictionaries of metadata for each catalog ID.

Builds dictionaries of metadata for each catalog ID found in the XML files.

Returns:: List of dictionaries, one for each catalog ID, containing metadata
Return type:: list

get_catid_xmls()#

Get XML files associated with each catalog ID.

Checks for multiple XML files for each catalog ID and handles mosaicking if needed.

Returns:: Dictionary mapping catalog IDs to XML file paths
Return type:: dict

Notes

If more than two XML files are found, they will be mosaicked using dg_mosaic before proceeding.

get_centroid_projection(geom, proj_type='tmerc')#

Get a local projection centered on geometry centroid.

Creates a custom projection string centered on the centroid of the input geometry, which minimizes distortion for local analyses.

Parameters:

geom (shapely.geometry.BaseGeometry) – Shapely geometry object whose centroid will be used as projection center
proj_type (str, optional) – Type of projection to use, default is “tmerc” (Transverse Mercator) Other options include “ortho” (Orthographic)

Returns:

Proj4 string for local projection centered on geometry centroid

Return type:

str

Examples

>>> parser = StereopairMetadataParser('/path/to/stereo/directory')
>>> pair_dict = parser.get_pair_dict()
>>> local_proj = parser.get_centroid_projection(pair_dict['intersection'])
>>> print(local_proj)
+proj=tmerc +lat_0=XX.XXXXXXX +lon_0=XX.XXXXXXX

get_id_dict(catid, xml, geteph=True)#

Get a dictionary of metadata for a specific catalog ID.

Extracts metadata from XML file for a given catalog ID, including satellite parameters, acquisition angles, and geometry.

Parameters:

catid (str) – Catalog ID for the satellite image
xml (str) – Path to the XML file
geteph (bool, optional) – Whether to extract ephemeris data, default is True

Returns:

Dictionary containing metadata for the catalog ID

Return type:

dict

Notes

The dictionary includes satellite ID, acquisition date, scan direction, TDI level, geometry information, and various mean angles and parameters. If geteph is True, also includes ephemeris and footprint GeoDataFrames.

get_intersection_bounds(epsg=None)#

Get the bounding box of the stereo pair intersection area.

Returns the intersection of both image footprints as a bounding box, optionally reprojected to a given CRS.

Parameters:: epsg (int, optional) – EPSG code to reproject bounds into (e.g., 32616 for UTM Zone 16N). If None, returns bounds in EPSG:4326 (longitude/latitude).
Returns:: (min_x, min_y, max_x, max_y) in the requested CRS
Return type:: tuple

get_pair_dict()#

Get a dictionary with all stereo pair information.

Creates a comprehensive dictionary containing stereo pair information, including convergence angle, base-to-height ratio, bisector elevation angle, asymmetry angle, and more.

Returns:: Dictionary with stereo pair information and geometry parameters
Return type:: dict

Notes

Currently only supports exactly two scenes. Future versions will support N scenes.

get_pair_intersection(p)#

Calculate intersection geometry and area for a stereo pair.

Computes the intersection between two image footprints, calculates its area, and the percentage of each image covered by the intersection.

Parameters:: p (dict) – Stereo pair dictionary to update with intersection information
Returns:: Updates the input dictionary with intersection geometry and area information
Return type:: None

Notes

The dictionary ‘p’ is updated with the following keys: - intersection: Shapely geometry representing the intersection - intersection_area: Area in square kilometers - intersection_area_perc: Tuple with percentages of each image covered by the intersection

Areas are calculated in a local orthographic projection to minimize distortion.

get_pair_utm_epsg()#

Get the UTM EPSG code for the stereo pair’s intersection area.

Uses the centroid of the pair intersection footprint to determine the appropriate UTM zone.

Returns:: UTM EPSG code (e.g., 32616 for UTM Zone 16N)
Return type:: int

get_scene_bounds()#

Get the geographic bounds of the union of all scene footprints.

Computes the union of both image footprints and returns the bounding box in longitude/latitude (EPSG:4326).

Returns:: (min_lon, min_lat, max_lon, max_lat)
Return type:: tuple

mosaic_multiple_xmls()#

Mosaic multiple XML files for each catalog ID.

Uses dg_mosaic to merge multiple XML files for the same catalog ID into a single XML file. This is needed when a scene is composed of multiple image tiles.

Returns:: Updates the image_list attribute with mosaicked XML files
Return type:: None

Notes

Requires dg_mosaic from the NASA Ames Stereo Pipeline to be installed and available in the system path.

pair_dict(catid1_dict, catid2_dict, pairname)#

xml2poly(xml)#

Convert XML corner coordinates to Shapely Polygon.

Reads XML file and converts corner coordinates to a Shapely Polygon geometry.

Parameters:: xml (str) – Path to the XML file
Returns:: Polygon geometry representing the image footprint
Return type:: shapely.geometry.Polygon

xml2wkt(xml)#

Convert XML corner coordinates to WKT polygon string.

Extracts corner coordinates from XML file and converts them to a Well-Known Text (WKT) polygon string.

Parameters:: xml (str) – Path to the XML file
Returns:: WKT polygon string representation of image footprint
Return type:: str

Notes

Uses ULLON/ULLAT, URLON/URLAT, LRLON/LRLAT, LLLON/LLLAT tags (Upper-Left, Upper-Right, Lower-Right, Lower-Left corners).

directory#

image_list#

asp_plot.stereopair_metadata_parser.get_asymmetry_angle(sat1_pos, sat2_pos, ground_point)#

Calculate asymmetry angle between satellite positions and ground point.

The asymmetry angle measures how far the bisector of the two viewing rays deviates from the local vertical, projected onto the convergence plane. An asymmetry of 0 means perfectly symmetric stereo geometry.

Parameters:

sat1_pos (numpy.ndarray) – 3-D position of satellite during acquisition of first image (in ECEF)
sat2_pos (numpy.ndarray) – 3-D position of satellite during acquisition of second image (in ECEF)
ground_point (numpy.ndarray) – 3-D position of ground point viewed by both satellites (in ECEF)

Returns:

Asymmetry angle in degrees, rounded to 2 decimal places

Return type:

float

References

Jeong & Kim (2014), PE&RS 80(7), 653-662 Jeong & Kim (2016), PE&RS 82(8), 625-633, Eq. 3

asp_plot.stereopair_metadata_parser.get_bh_ratio(conv_ang)#

Calculate base-to-height ratio from convergence angle.

Parameters:: conv_ang (numeric) – Convergence angle in degrees
Returns:: Base-to-height ratio, rounded to 2 decimal places
Return type:: float

asp_plot.stereopair_metadata_parser.get_bie_angle(az1, el1, az2, el2)#

Calculate Bisector Elevation Angle for a stereo pair.

The BIE is the elevation angle of the bisector of the two viewing directions. Higher BIE means less oblique epipolar geometry and better positioning accuracy.

Parameters:

az1 (numeric) – Satellite azimuth angle for first image (degrees)
el1 (numeric) – Satellite elevation angle for first image (degrees)
az2 (numeric) – Satellite azimuth angle for second image (degrees)
el2 (numeric) – Satellite elevation angle for second image (degrees)

Returns:

Bisector Elevation Angle in degrees, rounded to 2 decimal places

Return type:

float

References

Jeong & Kim (2014), PE&RS 80(7), 653-662 Jeong & Kim (2016), PE&RS 82(8), 625-633, Eq. 2

asp_plot.stereopair_metadata_parser.get_convergence_angle(az1, el1, az2, el2)#

Calculate convergence angle between two satellite viewing directions.

Uses the spherical law of cosines to compute the angle between two unit vectors defined by their azimuth and elevation angles.

Parameters:

az1 (numeric) – Satellite azimuth angle for first image (degrees)
el1 (numeric) – Satellite elevation angle for first image (degrees)
az2 (numeric) – Satellite azimuth angle for second image (degrees)
el2 (numeric) – Satellite elevation angle for second image (degrees)

Returns:

Convergence angle in degrees, rounded to 2 decimal places

Return type:

float

References

Jeong & Kim (2016), PE&RS 82(8), 625-633, Eq. 1

asp_plot.stereopair_metadata_parser.logger#