asp_plot.sensors.base

asp_plot.sensors.base#

Abstract base class and shared helpers for sensor metadata readers.

See the asp_plot.sensors package docstring for an overview. This module defines the two contracts every reader participates in:

File detection is content-based: each reader supplies a SensorMetadata._is_camera_file() predicate that inspects a candidate file (cheaply, e.g. with iterparse stopping early) and claims only files its sensor format actually produced. Discovery, filtering, detect, and detect_files are implemented here once, on top of that predicate, so a reader never claims another sensor’s files just because they end in .xml (issue #162).

The scene-dict schema splits into a required core and optional blocks:

identity core (required, a reader must raise if it cannot fill these): xml_fn, catid, sensor, date, geom
summary block (optional): the mean view-angle/GSD/sun fields and cloudcover default to NaN; scandir and tdi default to None
trajectory block (optional, when geteph is True): eph_gdf, att_df, fp_gdf

Readers call fill_scene_defaults() so a format that lacks a field degrades to the documented “not provided” value instead of omitting the key, and consumers rely on one convention (None/NaN render as omitted/”nan”/”N/A”) rather than per-key accidents (issue #163).

Two small geodesy helpers live here as well (_ecef_to_lonlat(), _lonlat_to_ecef() and _enu_basis()), because the two derived-geometry readers — asp_plot.sensors.aster and asp_plot.sensors.rpc — both need to express a look direction in the local east/north/up frame at a ground point.

Attributes#

`IMAGE_EXTENSIONS`
`OPTIONAL_SCENE_FIELDS`

Classes#

SensorMetadata

Abstract base class for a single sensor's metadata reader.

Functions#

`fill_scene_defaults`(scene_dict)	Fill missing optional scene-dict fields with "not provided" values.
`list_candidate_images`(directory[, recursive])	List candidate camera images in `directory`, by extension only.
`list_candidate_xmls`(directory[, recursive])	List camera-candidate XMLs in `directory`, name-filtered only.
`resolve_input_files`(sensor_cls, directory, image_list)	Resolve a reader's `(directory, image_list)` constructor arguments.

Module Contents#

class asp_plot.sensors.base.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 package docstring for the schema) that the stereo-pair geometry code can consume without knowing which sensor produced them.

Subclasses must implement _is_camera_file() (the content check that decides which files the sensor claims; discovery and detection are built on it here) and get_scene_dicts().

name#

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

Type:: str

fallback#

Whether this reader is a last-resort match, tried only after every other reader has failed at every search depth. Set on readers that claim files a more specific reader’s delivery also contains — the RPC reader claims images, and every WorldView or Pléiades delivery ships images next to its camera XMLs (issue #177).

Type:: bool

directory#

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

Type:: str

classmethod detect(directory, recursive=True)#

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

Parameters:

directory (str) – Path to directory to inspect.
recursive (bool, optional) – If True (default), also match metadata files nested in subdirectories. asp_plot.sensors.sensor_for_directory() first asks every sensor to detect shallowly and only then recursively, so a sensor matching at the top level wins over one matching a nested delivery.

Returns:

Whether this sensor’s metadata files are present.

Return type:

bool

classmethod detect_files(image_list)#

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 package docstring).
Return type:: list of dict

directory#

fallback = False#

name = 'sensor'#

asp_plot.sensors.base.fill_scene_defaults(scene_dict)#

Fill missing optional scene-dict fields with “not provided” values.

Mutates and returns scene_dict. Fields already present (even as None/NaN) are left alone; the required identity-core fields are not checked here — a reader that cannot fill those must raise instead.

asp_plot.sensors.base.list_candidate_images(directory, recursive=True)#

List candidate camera images in directory, by extension only.

The image counterpart of list_candidate_xmls(), for products whose camera model is embedded in the image rather than delivered as a sidecar XML (RPC-only products, issue #177). Shallow-first with a recursive fallback for the same reason: a flat delivery or an ASP processing directory keeps its images at the top level.

No content check is applied here — deciding whether an image actually carries RPCs is the reader’s job (see SensorMetadata._is_camera_file()), and it costs a raster header read per file.

asp_plot.sensors.base.list_candidate_xmls(directory, recursive=True)#

List camera-candidate XMLs in directory, name-filtered only.

Searches the top level of directory first: a flat delivery or an ASP processing directory keeps its camera XMLs there, so those take precedence and unrelated XMLs in subdirectories are not pulled in. Only when the top level has no candidate XML does it fall back to a recursive search, because some satellite deliveries nest the camera XML several subdirectories deep (e.g. .../<order>/DVD_VOL_1/<order>/<scene>_PAN/<scene>.XML).

Non-camera XMLs (*ortho*.xml, README.XML) are excluded by basename; no sensor-specific content check is applied — that is the readers’ job (see SensorMetadata._is_camera_file()). Used by asp_plot.sensors.resolve_xml_inputs() to expand directory inputs for any sensor.

asp_plot.sensors.base.resolve_input_files(sensor_cls, directory, image_list)#

Resolve a reader’s (directory, image_list) constructor arguments.

Every reader can be built either from a directory (its camera files are discovered) or from an explicit image_list (e.g. a shell-expanded stereo_geom *.XML). Both paths end in the same place: a list filtered by the sensor’s own SensorMetadata._is_camera_file() content check, plus a directory to use for outputs and pair naming.

Returns the resolved pair without raising on an empty result — each reader raises its own “missing files” error naming its format.

Parameters:

sensor_cls (type) – The SensorMetadata subclass being constructed.
directory (str or None) – Directory to discover files in, or the base directory for an explicit image_list.
image_list (list of str or None) – Explicit candidate files.

Returns:

The reader’s directory and its filtered file list.

Return type:

tuple of (str, list of str)

Raises:

ValueError – If neither directory nor image_list is given.

asp_plot.sensors.base.IMAGE_EXTENSIONS = ('.ntf', '.nitf', '.tif', '.tiff', '.jp2')#

asp_plot.sensors.base.OPTIONAL_SCENE_FIELDS#