aws.osml.elevation¶

I/O-aware implementations of the elevation model abstractions defined in aws.osml.photogrammetry. This package reads DEM raster tiles from disk (StoredDEMTileFactory), derives geo-transforms from raster metadata, applies geoid offsets from raster grids (RasterOffsetProvider), evaluates spatial conditions backed by shapefiles (GeometryCondition, ShapefileQuery), and composes all of these into a ready-to-use elevation model via the fluent ElevationModelBuilder.

This package does not contain the abstract interfaces themselves (those live in photogrammetry) nor any pixel display operations (image_processing).

Dependencies¶

Imports photogrammetry for all elevation ABCs (ElevationModel, DigitalElevationModelTileFactory, DigitalElevationModelTileSet, ElevationModelCondition, ElevationOffsetProvider). Uses osml-imagery-io for raster reads and shapely / fiona for geometry queries. Does not import image_processing, features, or metadata.

Design¶

Interface/implementation split — photogrammetry defines the ABCs; this package provides the concrete implementations that perform actual file I/O.

ElevationModelBuilder (fluent builder) — composes DEM sources, conditions, geoid offsets, and normalization into a single ElevationModel instance suitable for use with any sensor model.

StoredDEMTileFactory — implements DigitalElevationModelTileFactory by reading DTED or GeoTIFF raster files from a local directory.

RasterOffsetProvider — implements ElevationOffsetProvider by interpolating values from a geoid raster grid (e.g. EGM96/EGM2008).

GeometryCondition — implements ElevationModelCondition by testing point-in-polygon against a GeometryQuery.

        flowchart LR
    B[ElevationModelBuilder]
    B -->|add_source| F[StoredDEMTileFactory]
    B -->|with_geoid| R[RasterOffsetProvider]
    B -->|build| EM[Composed ElevationModel]
    EM --- M[Multi]
    EM --- O[Offset]
    EM --- N[Normalized]

Contributor rules¶

New DEM data sources — implement DigitalElevationModelTileFactory.
New spatial conditions — implement ElevationModelCondition or wrap a GeometryQuery.
Keep ABCs in photogrammetry; I/O implementations belong here.

Builder¶

class aws.osml.elevation.ElevationModelBuilder¶

Bases: object

Fluent builder for composing multi-source elevation models.

Sources are tried in the order they are added (first = highest priority). Each source can optionally be guarded by a spatial condition. A geoid offset is applied globally to the final result. Coordinate normalization is applied by default.

Example:

model = (
    ElevationModelBuilder()
    .add_source(StoredDEMTileFactory("/srtm"), SRTMTileSet())
    .with_geoid("/path/to/egm96.tif")
    .build()
)

add_source(tile_factory, tile_set, condition=None, invert_condition=False, raster_cache_size=10)¶

Add a DEM source. Sources are tried in order; first success wins.

Return type:: ElevationModelBuilder

add_elevation_model(elevation_model, condition=None, invert_condition=False)¶

Add an arbitrary ElevationModel as a source.

Return type:: ElevationModelBuilder

add_fallback(elevation=0.0)¶

Add a constant elevation fallback as the lowest-priority source.

Return type:: ElevationModelBuilder

with_geoid(offset_path, scale_factor=1.0)¶

Apply geoid correction to the final elevation result.

The offset is applied globally to all sources. This assumes all sources use the same vertical datum (e.g., all orthometric heights). If mixing sources with different vertical datums, compose the OffsetElevationModel manually around only the orthometric source and use add_elevation_model().

Return type:: ElevationModelBuilder

build(normalize=True)¶

Assemble the elevation model composition.

Parameters:: normalize (bool) – wrap in NormalizedElevationModel (default True, opt-out)
Return type:: ElevationModel

Tile Factory¶

class aws.osml.elevation.StoredDEMTileFactory(tile_directory)¶

Bases: DigitalElevationModelTileFactory

Tile factory that loads DEM rasters (DTED, GeoTIFF) using osml-imagery-io.

get_tile(tile_path)¶

Load a DEM tile and return its elevation data, sensor model, and region summary.

Parameters:: tile_path (str) – relative path to the tile within the tile directory
Return type:: Tuple[Optional[Any], Optional[SensorModel], Optional[ElevationRegionSummary]]
Returns:: (elevation_array, sensor_model, summary) or (None, None, None) if unavailable

Offset Provider¶

class aws.osml.elevation.RasterOffsetProvider(offset_path, scale_factor=1.0, tol=1e-06)¶

Bases: ElevationOffsetProvider

Provide WGS84 elevation offsets from any raster supported by osml-imagery-io. Builds a bilinear spline interpolator for fast queries at arbitrary coordinates.

get_offset(geodetic_world_coordinate)¶

Interpolate a WGS84 offset from the grid.

Parameters:: geodetic_world_coordinate (GeodeticWorldCoordinate) – a normalized world coordinate (radians)
Return type:: float
Returns:: offset in meters
Raises:: ValueError – if coordinate is outside valid bounds

Geometry Conditions¶

class aws.osml.elevation.GeometryCondition(geometry_query, invert=False)¶

Bases: ElevationModelCondition

Elevation model condition that evaluates True when a point is inside a geometry from the query (or False when invert=True).

is_true(world_coordinate)¶

Return if the condition for supplied coordinate is True.

Parameters:: world_coordinate (GeodeticWorldCoordinate) – the coordinate to evaluate
Return type:: bool
Returns:: True if condition passes, else False

class aws.osml.elevation.ShapefileQuery(vector_filepath, geom_cache_size=10, tol=1e-06)¶

Bases: GeometryQuery

Geometry query backed by pyshp (pure Python) and Shapely STRtree. Returns the first intersection geometry from a shapefile source. Uses 1-degree tile caching with LRU eviction.

get_geometry(world_coordinate)¶

Get a geometry (first, if many) containing a supplied point.

Parameters:: world_coordinate (GeodeticWorldCoordinate) – the point of interest (radians)
Return type:: Optional[Geometry]
Returns:: the geometry, or None if the point is not within any geometry

Utilities¶

aws.osml.elevation.derive_geo_transform(metadata)¶

Derive a 6-coefficient affine geo transform from image metadata. Tries GeoTIFF tags first, then DTED header fields.

Parameters:: metadata (Dict) – image metadata dictionary from osml-imagery-io
Return type:: Optional[List[float]]
Returns:: 6-coefficient geo transform [x_origin, x_res, x_rot, y_origin, y_rot, y_res], or None

aws.osml.elevation.read_single_band(image_asset)¶

Read all blocks from a single-band image asset into a 2D array.

Parameters:: image_asset – an osml-imagery-io image asset with block-oriented access
Return type:: ndarray
Returns:: 2D numpy array of shape (height, width)