asp_plot.stereopair_metadata_parser

asp_plot.stereopair_metadata_parser#

Attributes#

logger

Classes#

StereopairMetadataParser

Parse metadata for a stereo pair and compute stereo-geometry parameters.

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=None, inputs=None)#

Parse metadata for a stereo pair and compute stereo-geometry parameters.

This class is sensor-agnostic: the work of discovering scene files and extracting per-scene metadata is delegated to a sensor-specific reader (see asp_plot.sensors), chosen automatically by inspecting the directory contents. The parser then computes pair-level geometry (convergence angle, base-to-height ratio, bisector elevation angle, asymmetry angle, footprint intersection, bounds) from the resulting scene dictionaries.

Adding support for a new sensor (ASTER, HiRISE, etc.) is a matter of writing a new asp_plot.sensors.SensorMetadata subclass; no changes to this class are required.

directory#

Path to directory containing the scene metadata files

Type:: str

reader#

The detected sensor-specific metadata reader

Type:: asp_plot.sensors.SensorMetadata

image_list#

List of scene metadata files found in the directory (delegated to the reader)

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']}")

get_catid_dicts()#

Get dictionaries of metadata for each catalog ID.

Delegates to the detected sensor reader to build a list of per-scene metadata dictionaries.

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

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_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 for exactly two scenes.

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
Raises:: ValueError – If the inputs do not contain exactly two scenes. Use get_pair_dicts() for the per-pair dictionaries of N scenes.

get_pair_dicts()#

Get per-pair dictionaries for every combination of scenes.

Builds one stereo-pair dictionary (see pair_dict()) for each of the N-choose-2 combinations of the discovered scenes, so N-scene inputs can be assessed pairwise. For exactly two scenes this returns a single-element list; get_pair_dict remains the canonical two-scene entry point.

Returns:: One stereo-pair dictionary per scene combination.
Return type:: list of dict
Raises:: ValueError – If fewer than two scenes are found (no pair can be formed).

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_map_projection(p, proj_type='tmerc')#

Local projection for a single pair’s map, robust to no overlap.

Centers on the pair intersection when the footprints overlap; otherwise falls back to the union of the two footprints so non-overlapping pairs (common in N-scene sets) still get a sensible map projection.

Parameters:

p (dict) – Stereo-pair dictionary from pair_dict().
proj_type (str, optional) – Projection type, default “tmerc”.

Returns:

Proj4 string centered on the pair’s intersection or footprint union.

Return type:

str

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

get_scenes_centroid_projection(proj_type='tmerc')#

Local projection centered on the union of all scene footprints.

Used for the N-scene overview map so the projection is centered on all scenes together rather than a single pair intersection.

Parameters:: proj_type (str, optional) – Projection type, default “tmerc” (see get_centroid_projection()).
Returns:: Proj4 string centered on the union of all scene footprints.
Return type:: str

pair_dict(catid1_dict, catid2_dict, pairname)#

property image_list#: List of scene metadata files (delegated to the sensor reader).

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#