asp_plot.sensors

asp_plot.sensors#

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 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 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#

`SENSORS`
`logger`

Classes#

`SensorMetadata`	Abstract base class for a single sensor's metadata reader.
`WorldViewMetadata`	Metadata reader for WorldView satellite XML camera files.

Functions#

sensor_for_directory(directory)

Detect and instantiate the appropriate sensor reader for a directory.

Module Contents#

class asp_plot.sensors.SensorMetadata(directory)#

Bases: 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 detect() (so the sensor can be chosen automatically) and get_scene_dicts().

name#

Human-readable sensor name (e.g. "WorldView").

Type:: str

directory#

Path to the directory containing the sensor’s metadata files.

Type:: str

classmethod detect(directory)#

Abstractmethod:

Return True if this reader can handle the files in directory.

Parameters:: directory (str) – Path to directory to inspect.
Returns:: Whether this sensor’s metadata files are present.
Return type:: bool

abstractmethod get_scene_dicts()#

Return a list of per-scene metadata dictionaries.

Returns:: One sensor-agnostic scene dict per scene (see module docstring).
Return type:: list of dict

directory#

name = 'sensor'#

class asp_plot.sensors.WorldViewMetadata(directory)#

Bases: 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).

directory#

Path to directory containing XML files.

Type:: str

image_list#

List of XML files found in the directory.

Type:: list

classmethod detect(directory)#

Return True if non-ortho XML camera files are present.

Parameters:: directory (str) – Path to directory to inspect.
Returns:: Whether WorldView XML camera files were found.
Return type:: bool

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_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_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_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
Return type:: list

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.

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).

image_list#

name = 'WorldView'#

asp_plot.sensors.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 SensorMetadata.detect() matches the directory contents.

Parameters:: directory (str) – Path to directory containing camera/metadata files.
Returns:: An initialized reader for the detected sensor.
Return type:: SensorMetadata
Raises:: ValueError – If no registered sensor reader matches the directory contents.

asp_plot.sensors.SENSORS#

asp_plot.sensors.logger#