aws.osml.features

The features package contains classes that assist with working with geospatial features derived from imagery.

---

APIs

class aws.osml.features.Geolocator(property_accessor: ImagedFeaturePropertyAccessor, sensor_model: SensorModel, elevation_model: ElevationModel | None = None, approximation_grid_size: int = 11)

Bases: object

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

geolocate_features(features: List[Feature]) → None

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

Parameters:

features – List[geojson.Feature] = the input features to refine

Returns:

None, the features are updated in place

static radians_coordinate_to_degrees(coordinate: GeodeticWorldCoordinate) → Tuple[float, float, float]

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 = the geodetic world coordinate (longitude, latitude, elevation)

Returns:

Tuple[float, float, float] = degrees(longitude), degrees(latitude), elevation

class aws.osml.features.ImagedFeaturePropertyAccessor(allow_deprecated: bool = 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: Feature) → Geometry | None

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 – a GeoJSON feature that might contain an image geometry property

Returns:

a 2D shape representing the image geometry or None

update_existing_image_geometries(feature: Feature, geometry: Geometry) → None

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 – a GeoJSON feature that might contain an image geometry property

• geometry – the geometry to set property values for.

classmethod get_image_geometry(feature: Feature) → Geometry | None

classmethod get_image_bbox(feature: Feature) → Geometry | None

classmethod set_image_geometry(feature: Feature, geometry: Geometry) → None

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 – a GeoJSON feature that will contain the property

• geometry – the geometry value

classmethod set_image_bbox(feature: Feature, geometry: Geometry) → None

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

Parameters:

• feature – a GeoJSON feature that will contain the property

• geometry – the geometry value

class aws.osml.features.Feature2DSpatialIndex

Bases: ABC

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

abstract find_intersects(geometry: Geometry) → Iterable[Feature]

Return the features intersecting the input geometry.

Parameters:

geometry – geometry to query the index

Returns:

the features

abstract find_nearest(geometry: Geometry, max_distance: float | None = None) → Iterable[Feature]

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

Parameters:

• geometry – geometry to query the index

• max_distance – maximum distance

Returns:

the nearest features

class aws.osml.features.STRFeature2DSpatialIndex(feature_collection: ~geojson.feature.FeatureCollection, use_image_geometries: bool = True, property_accessor: ~aws.osml.features.imaged_feature_property_accessor.ImagedFeaturePropertyAccessor = <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: Geometry) → Iterable[Feature]

Return the features intersecting the input geometry.

Parameters:

geometry – geometry to query the index

Returns:

the features

find_nearest(geometry: Geometry, max_distance: float | None = None) → Iterable[Feature]

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

Parameters:

• geometry – geometry to query the index

• max_distance – maximum distance

Returns:

the nearest features