asp_plot.sensors ================ .. py:module:: asp_plot.sensors .. autoapi-nested-parse:: Sensor-specific metadata readers for stereo scenes. This module isolates the *sensor-specific* work of discovering scene files and extracting per-scene metadata from the *sensor-agnostic* stereo-pair geometry math in :mod:`asp_plot.stereopair_metadata_parser`. The goal is flexibility: today only WorldView (and other DigitalGlobe-heritage) XML camera files are supported, but adding a new sensor (ASTER, HiRISE, etc.) is a matter of writing a new :class:`SensorMetadata` subclass and registering it in ``SENSORS`` — no changes to the pair-level geometry code are required. Each reader is responsible for turning a directory of camera/metadata files into a list of *scene dicts*, one per scene, each containing the sensor-agnostic keys the geometry code consumes: ``xml_fn``, ``catid``, ``sensor``, ``date``, ``scandir``, ``tdi``, ``geom`` (a Shapely polygon footprint in EPSG:4326), the mean view-angle/GSD/sun attributes (``meansataz``, ``meansatel``, ``meanoffnadirviewangle``, ``meanintrackviewangle``, ``meancrosstrackviewangle``, ``meanproductgsd``, ``meansunaz``, ``meansunel``, ``cloudcover``), and — when ``geteph`` is True — ``eph_gdf`` (ephemeris GeoDataFrame in EPSG:4978), ``att_df`` (attitude DataFrame), and ``fp_gdf`` (footprint GeoDataFrame in EPSG:4326). Attributes ---------- .. autoapisummary:: asp_plot.sensors.SENSORS asp_plot.sensors.logger Classes ------- .. autoapisummary:: asp_plot.sensors.SensorMetadata asp_plot.sensors.WorldViewMetadata Functions --------- .. autoapisummary:: asp_plot.sensors.sensor_for_directory Module Contents --------------- .. py:class:: SensorMetadata(directory) Bases: :py:obj:`abc.ABC` Abstract base class for a single sensor's metadata reader. A concrete reader discovers the scene files for one sensor in a directory and extracts a list of sensor-agnostic *scene dicts* (see the module docstring for the schema) that the stereo-pair geometry code can consume without knowing which sensor produced them. Subclasses must implement :meth:`detect` (so the sensor can be chosen automatically) and :meth:`get_scene_dicts`. .. attribute:: name Human-readable sensor name (e.g. ``"WorldView"``). :type: str .. attribute:: directory Path to the directory containing the sensor's metadata files. :type: str .. py:method:: detect(directory) :classmethod: :abstractmethod: Return True if this reader can handle the files in ``directory``. :param directory: Path to directory to inspect. :type directory: str :returns: Whether this sensor's metadata files are present. :rtype: bool .. py:method:: get_scene_dicts() :abstractmethod: Return a list of per-scene metadata dictionaries. :returns: One sensor-agnostic scene dict per scene (see module docstring). :rtype: list of dict .. py:attribute:: directory .. py:attribute:: name :value: 'sensor' .. py:class:: WorldViewMetadata(directory) Bases: :py:obj:`SensorMetadata` Metadata reader for WorldView satellite XML camera files. Parses WorldView (and other DigitalGlobe-heritage products that share the same XML format, e.g. GeoEye-1, QuickBird, IKONOS) satellite XML files to extract per-scene metadata, handling both single XML files and multiple XML tiles per scene (mosaicked with ``dg_mosaic``). .. attribute:: directory Path to directory containing XML files. :type: str .. attribute:: image_list List of XML files found in the directory. :type: list .. py:method:: detect(directory) :classmethod: Return True if non-ortho XML camera files are present. :param directory: Path to directory to inspect. :type directory: str :returns: Whether WorldView XML camera files were found. :rtype: bool .. 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_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_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_scene_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:: 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:: 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:: image_list .. py:attribute:: name :value: 'WorldView' .. py:function:: sensor_for_directory(directory) Detect and instantiate the appropriate sensor reader for a directory. Iterates the ``SENSORS`` registry and returns an instance of the first reader whose :meth:`SensorMetadata.detect` matches the directory contents. :param directory: Path to directory containing camera/metadata files. :type directory: str :returns: An initialized reader for the detected sensor. :rtype: SensorMetadata :raises ValueError: If no registered sensor reader matches the directory contents. .. py:data:: SENSORS .. py:data:: logger