asp_plot.stereopair_metadata_parser =================================== .. py:module:: asp_plot.stereopair_metadata_parser Attributes ---------- .. autoapisummary:: asp_plot.stereopair_metadata_parser.logger Classes ------- .. autoapisummary:: asp_plot.stereopair_metadata_parser.StereopairMetadataParser Functions --------- .. autoapisummary:: asp_plot.stereopair_metadata_parser.get_asymmetry_angle asp_plot.stereopair_metadata_parser.get_bh_ratio asp_plot.stereopair_metadata_parser.get_bie_angle asp_plot.stereopair_metadata_parser.get_convergence_angle Module Contents --------------- .. py:class:: 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. .. attribute:: directory Path to directory containing XML files :type: str .. attribute:: image_list List of XML files found in the directory :type: list .. rubric:: 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']}") .. py:method:: getAtt(xml) Extract attitude data from XML file. Retrieves satellite attitude (orientation quaternion and covariance) data from the XML file. :param xml: Path to the XML file :type xml: str :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) :rtype: numpy.ndarray .. py:method:: getAtt_df(xml) Create a DataFrame from attitude data. Converts attitude data to a DataFrame with time index. :param xml: Path to the XML file :type xml: str :returns: DataFrame with attitude quaternions and covariance, time-indexed :rtype: pandas.DataFrame .. py:method:: getEphem(xml) Extract ephemeris data from XML file. Retrieves satellite ephemeris (position and velocity) data from the XML file. :param xml: Path to the XML file :type xml: str :returns: Array containing ephemeris data with columns: point_num, Xpos, Ypos, Zpos, Xvel, Yvel, Zvel, and covariance matrix elements :rtype: numpy.ndarray .. rubric:: 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. .. py:method:: getEphem_gdf(xml) Create a GeoDataFrame from ephemeris data. Converts ephemeris data to a GeoDataFrame with time index and Point geometry. :param xml: Path to the XML file :type xml: str :returns: GeoDataFrame with ephemeris data and Point geometries in EPSG:4978 :rtype: geopandas.GeoDataFrame .. rubric:: Notes The GeoDataFrame uses EPSG:4978 (Earth-Centered Earth-Fixed) CRS and has a time index corresponding to the acquisition times. .. py:method:: 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 :rtype: list .. py:method:: 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 :rtype: dict .. rubric:: Notes If more than two XML files are found, they will be mosaicked using dg_mosaic before proceeding. .. py:method:: 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. :param geom: Shapely geometry object whose centroid will be used as projection center :type geom: shapely.geometry.BaseGeometry :param proj_type: Type of projection to use, default is "tmerc" (Transverse Mercator) Other options include "ortho" (Orthographic) :type proj_type: str, optional :returns: Proj4 string for local projection centered on geometry centroid :rtype: str .. rubric:: 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 .. py:method:: 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. :param catid: Catalog ID for the satellite image :type catid: str :param xml: Path to the XML file :type xml: str :param geteph: Whether to extract ephemeris data, default is True :type geteph: bool, optional :returns: Dictionary containing metadata for the catalog ID :rtype: dict .. rubric:: 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. .. py:method:: 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. :param epsg: EPSG code to reproject bounds into (e.g., 32616 for UTM Zone 16N). If None, returns bounds in EPSG:4326 (longitude/latitude). :type epsg: int, optional :returns: (min_x, min_y, max_x, max_y) in the requested CRS :rtype: tuple .. py:method:: 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 :rtype: dict .. rubric:: Notes Currently only supports exactly two scenes. Future versions will support N scenes. .. py:method:: 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. :param p: Stereo pair dictionary to update with intersection information :type p: dict :returns: Updates the input dictionary with intersection geometry and area information :rtype: None .. rubric:: 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. .. py:method:: 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) :rtype: int .. py:method:: 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) :rtype: tuple .. py:method:: 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 :rtype: None .. rubric:: Notes Requires dg_mosaic from the NASA Ames Stereo Pipeline to be installed and available in the system path. .. py:method:: pair_dict(catid1_dict, catid2_dict, pairname) .. py:method:: xml2poly(xml) Convert XML corner coordinates to Shapely Polygon. Reads XML file and converts corner coordinates to a Shapely Polygon geometry. :param xml: Path to the XML file :type xml: str :returns: Polygon geometry representing the image footprint :rtype: shapely.geometry.Polygon .. py:method:: 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. :param xml: Path to the XML file :type xml: str :returns: WKT polygon string representation of image footprint :rtype: str .. rubric:: Notes Uses ULLON/ULLAT, URLON/URLAT, LRLON/LRLAT, LLLON/LLLAT tags (Upper-Left, Upper-Right, Lower-Right, Lower-Left corners). .. py:attribute:: directory .. py:attribute:: image_list .. py:function:: 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. :param sat1_pos: 3-D position of satellite during acquisition of first image (in ECEF) :type sat1_pos: numpy.ndarray :param sat2_pos: 3-D position of satellite during acquisition of second image (in ECEF) :type sat2_pos: numpy.ndarray :param ground_point: 3-D position of ground point viewed by both satellites (in ECEF) :type ground_point: numpy.ndarray :returns: Asymmetry angle in degrees, rounded to 2 decimal places :rtype: float .. rubric:: References Jeong & Kim (2014), PE&RS 80(7), 653-662 Jeong & Kim (2016), PE&RS 82(8), 625-633, Eq. 3 .. py:function:: get_bh_ratio(conv_ang) Calculate base-to-height ratio from convergence angle. :param conv_ang: Convergence angle in degrees :type conv_ang: numeric :returns: Base-to-height ratio, rounded to 2 decimal places :rtype: float .. py:function:: 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. :param az1: Satellite azimuth angle for first image (degrees) :type az1: numeric :param el1: Satellite elevation angle for first image (degrees) :type el1: numeric :param az2: Satellite azimuth angle for second image (degrees) :type az2: numeric :param el2: Satellite elevation angle for second image (degrees) :type el2: numeric :returns: Bisector Elevation Angle in degrees, rounded to 2 decimal places :rtype: float .. rubric:: References Jeong & Kim (2014), PE&RS 80(7), 653-662 Jeong & Kim (2016), PE&RS 82(8), 625-633, Eq. 2 .. py:function:: 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. :param az1: Satellite azimuth angle for first image (degrees) :type az1: numeric :param el1: Satellite elevation angle for first image (degrees) :type el1: numeric :param az2: Satellite azimuth angle for second image (degrees) :type az2: numeric :param el2: Satellite elevation angle for second image (degrees) :type el2: numeric :returns: Convergence angle in degrees, rounded to 2 decimal places :rtype: float .. rubric:: References Jeong & Kim (2016), PE&RS 82(8), 625-633, Eq. 1 .. py:data:: logger