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#

`resolve_xml_inputs`(inputs[, recursive])	Expand files, directories, and glob patterns into XML file paths.
`sensor_for_directory`(directory)	Detect and instantiate the appropriate sensor reader for a directory.
`sensor_for_inputs`(inputs)	Detect and instantiate the appropriate sensor reader for explicit inputs.

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

classmethod detect_files(image_list)#

Abstractmethod:

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

The file-list counterpart of detect(), used when the sensor must be chosen from an explicit list of inputs rather than a directory.

Parameters:: image_list (list of str) – Candidate metadata file paths.
Returns:: Whether this sensor’s metadata files are present in the list.
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=None, image_list=None)#

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

This class is named for the sensor family (the stable WorldView name) and governs which reader parses the XML. It is intentionally distinct from the attribution check asp_plot.utils.detect_vantor_satellite(), which is named for the rights-holder (Vantor) and decides whether the “© Vantor” overlay applies. The two concerns use different names on purpose; see #137.

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

classmethod detect_files(image_list)#

Return True if any file in image_list is a camera XML.

The file-list counterpart of detect(), used to choose a reader for an explicit list of inputs (see sensor_for_inputs()). A file is a camera XML if it survives the non-camera basename filter (so README.XML / *ortho*.xml alone do not match).

Parameters:: image_list (list of str) – Candidate XML file paths.
Returns:: Whether any camera XML files are present.
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 a single representative XML file for each catalog ID.

Groups the discovered XML files by their catalog ID (read from the XML content, not the filename) and resolves each scene to one XML: a scene delivered as a single XML is used as-is, while a scene tiled across multiple XMLs is mosaicked into one with dg_mosaic.

Returns:: Dictionary mapping catalog IDs to a single XML file path.
Return type:: dict
Raises:: ValueError – If none of the discovered XML files contain a CATID tag.

Notes

Mosaicking is decided per catalog ID, so a directory holding many distinct single-tile scenes is not mosaicked just because it contains more than two XML files. Mosaicking a tiled scene requires dg_mosaic from the NASA Ames Stereo Pipeline on the system path.

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

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

name = 'WorldView'#

asp_plot.sensors.resolve_xml_inputs(inputs, recursive=True)#

Expand files, directories, and glob patterns into XML file paths.

Lets a user point the tools at messy inputs without a fixed directory structure — e.g. geom_plot *.XML (already expanded by the shell), geom_plot scene1.xml scene2.xml, geom_plot delivery_dir/, or a mix.

Each item of inputs may be:

a path to an XML file (included directly),
a directory (searched with WorldViewMetadata._discover_xmls(), which is shallow-first and falls back to a recursive search), or
a glob pattern (expanded with glob.glob()).

Results are de-duplicated (by absolute path) and returned sorted. Note that sensor-specific filtering of non-camera XMLs (README.XML, ortho products) is applied by the reader, not here.

Parameters:

inputs (str or os.PathLike or iterable of those) – One or more files, directories, and/or glob patterns.
recursive (bool, optional) – Passed through to directory discovery and ** glob expansion. Default True.

Returns:

Sorted, de-duplicated XML file paths.

Return type:

list of str

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.sensor_for_inputs(inputs)#

Detect and instantiate the appropriate sensor reader for explicit inputs.

The file-list counterpart of sensor_for_directory(). Resolves inputs (files, directories, and/or globs) into a list of XML files, then returns an instance of the first registered reader whose SensorMetadata.detect_files() matches.

Parameters:: inputs (str or os.PathLike or iterable of those) – One or more files, directories, and/or glob patterns.
Returns:: An initialized reader for the detected sensor.
Return type:: SensorMetadata
Raises:: ValueError – If no XML files are found, or no registered sensor reader matches them.

asp_plot.sensors.SENSORS#

asp_plot.sensors.logger#