aws.osml.features¶

Working with geospatial features (detections, annotations) derived from imagery. This package covers converting image-coordinate features to geographic coordinates (geolocation), the inverse projection (geographic to image), spatial indexing for efficient region queries, and a property accessor facade for the imaged-feature GeoJSON convention. It does not include the sensor model mathematics themselves (photogrammetry) or pixel extraction and display logic (image_processing).

Dependencies: Imports from photogrammetry (SensorModel, ElevationModel, GeodeticWorldCoordinate, ImageCoordinate). Uses geojson, shapely, and scipy (for bilinear interpolation). Does not import image_processing or metadata.

Design abstractions¶

The package is organized around a small set of collaborating abstractions:

Imaged-feature GeoJSON convention — Features carry image-coordinate geometry in properties.imageGeometry and properties.imageBBox. The Geolocator populates the standard GeoJSON geometry field by projecting these through a sensor model and elevation model. The Projector performs the inverse operation (geographic to image).

ImagedFeaturePropertyAccessor — A facade that encapsulates how image coordinates are encoded in feature properties, isolating the rest of the package from the specific JSON schema.

LocationGridInterpolator — Pre-computes a bilinear interpolation grid of sensor model results over a tile extent, amortizing the cost of sensor model evaluation and providing O(1) per-feature geolocation within that tile.

Feature2DSpatialIndex (ABC) and STRFeature2DSpatialIndex — A query-only spatial index backed by Shapely’s STR-tree. Operates in either image-pixel or geographic coordinate space, enabling efficient region-based feature retrieval without scanning the full collection.

Geolocation pipeline¶

        flowchart LR
    A[pixel detections<br/>imageGeometry] --> B[Geolocator<br/>sensor model + elevation]
    B --> C[GeoJSON features<br/>geometry]
    C --> D[SpatialIndex]
    D --> E[query results]

Contributor rules¶

New query or filter operations belong on the spatial index or in a new class — not inlined at call sites.
Coordinate transforms must go through Geolocator or Projector, not raw sensor model calls.
No pixel-reading or display logic belongs in this package.

Geolocation¶

class aws.osml.features.Geolocator(property_accessor, sensor_model, elevation_model=None, approximation_grid_size=11, force=False)¶

Bases: object

A Geolocator is a class that assign geographic coordinates for the features that are currently defined in image coordinates.

geolocate_features(features)¶

Update the features to contain additional information from the context provided.

When force=False (default), features that already have a non-None geometry property are skipped. When force=True, all features are re-geolocated regardless of existing geometry.

Parameters:: features (List[Feature]) – List[geojson.Feature] = the input features to refine
Return type:: None
Returns:: None, the features are updated in place

static radians_coordinate_to_degrees(coordinate)¶

GeoJSON coordinate order is a decimal longitude, latitude with an optional height as a 3rd value (i.e. [lon, lat, ht]). The WorldCoordinate uses the same ordering but the longitude and latitude are expressed in radians rather than degrees.

Parameters:: coordinate (GeodeticWorldCoordinate) – GeodeticWorldCoordinate = the geodetic world coordinate (longitude, latitude, elevation)
Return type:: Tuple[float, float, float]
Returns:: Tuple[float, float, float] = degrees(longitude), degrees(latitude), elevation

Spatial Indexing¶

class aws.osml.features.Feature2DSpatialIndex¶

Bases: ABC

A query-only spatial index allowing clients to lookup features using 2D geometries

abstract find_intersects(geometry)¶

Return the features intersecting the input geometry.

Parameters:: geometry (Geometry) – geometry to query the index
Return type:: Iterable[Feature]
Returns:: the features

abstract find_nearest(geometry, max_distance=None)¶

Return the nearest feature for the input geometry based on distance within two-dimensional Cartesian space.

Parameters:

geometry (Geometry) – geometry to query the index
max_distance (Optional[float]) – maximum distance

Return type:

Iterable[Feature]

Returns:

the nearest features

class aws.osml.features.STRFeature2DSpatialIndex(feature_collection, use_image_geometries=True, property_accessor=<aws.osml.features.imaged_feature_property_accessor.ImagedFeaturePropertyAccessor object>)¶

Bases: Feature2DSpatialIndex

Implementation of the 2D spatial index for GeoJSON features using Shapely’s Sort-Tile-Recursive (STR) tree datastructure.

find_intersects(geometry)¶

Return the features intersecting the input geometry.

Parameters:: geometry (Geometry) – geometry to query the index
Return type:: Iterable[Feature]
Returns:: the features

find_nearest(geometry, max_distance=None)¶

Return the nearest feature for the input geometry based on distance within two-dimensional Cartesian space.

Parameters:

geometry (Geometry) – geometry to query the index
max_distance (Optional[float]) – maximum distance

Return type:

Iterable[Feature]

Returns:

the nearest features

Property Accessors¶

class aws.osml.features.ImagedFeaturePropertyAccessor(allow_deprecated=True)¶

Bases: object

This class contains utility functions that ensure the property names / values for features derived from imagery are consistently implemented. These specifications are still evolving so the intent is to encapsulate all of the names in this one class so that changes do not ripple through the rest of the software baseline.

IMAGE_GEOMETRY = 'imageGeometry'¶

IMAGE_BBOX = 'imageBBox'¶

BOUNDS_IMCORDS = 'bounds_imcoords'¶

GEOM_IMCOORDS = 'geom_imcoords'¶

DETECTION = 'detection'¶

TYPE = 'type'¶

COORDINATES = 'coordinates'¶

PIXEL_COORDINATES = 'pixelCoordinates'¶

find_image_geometry(feature)¶

This function searches through the properties of a GeoJSON feature that are known to contain the geometry of the feature in image coordinates. If found an appropriate 2D shape is constructed and returned. Note that this search is conducted in priority order giving preference to the current preferred “imageGeometry” and “bboxGeometry” properties. If neither of those is available and the accessor has been configured to search deprecated properties then the “geom_imcoords”, “detection”, and “bounds_imcoords” properties are searched in that order.

Parameters:: feature (Feature) – a GeoJSON feature that might contain an image geometry property
Return type:: Optional[Geometry]
Returns:: a 2D shape representing the image geometry or None

update_existing_image_geometries(feature, geometry)¶

This function searches through the properties of a GeoJSON feature that are known to contain the geometry of the feature in image coordinates. If found each property is overwritten with information from the geometry provided. Note that for bounding box properties the bounds of the input geometry are used.

Parameters:

feature (Feature) – a GeoJSON feature that might contain an image geometry property
geometry (Geometry) – the geometry to set property values for.

Return type:

None

classmethod get_image_geometry(feature)¶

Return type:: Optional[Geometry]

classmethod get_image_bbox(feature)¶

Return type:: Optional[Geometry]

classmethod set_image_geometry(feature, geometry)¶

Add or set the “imageGeometry” property for a feature. This is a 2D geometry that supports a variety of types (points, lines, polygons, etc.)

Parameters:

feature (Feature) – a GeoJSON feature that will contain the property
geometry (Geometry) – the geometry value

Return type:

None

classmethod set_image_bbox(feature, geometry)¶

Add or set the “imageBBox” property for a feature. this is a [minx, miny, maxx, maxy] bounds for this object.

Parameters:

feature (Feature) – a GeoJSON feature that will contain the property
geometry (Geometry) – the geometry value

Return type:

None