aws.osml.photogrammetry¶

This package contains sensor model implementations (image-to-world and world-to-image transforms), coordinate types, elevation model abstractions, and supporting math. It does not include metadata parsing (that belongs to the metadata package) or display/pixel operations (that belongs to image_processing).

photogrammetry is the leaf dependency of the toolkit. The metadata, image_processing, and features packages all depend on it; it has no sibling-package imports.

Design abstractions¶

SensorModel ABC is the central interface. Every model implements image_to_world and world_to_image. Concrete implementations range from rational polynomial cameras (RPCSensorModel) to SAR-specific models (SICDSensorModel) and grid-based RSM models. Two structural wrappers compose models: CompositeSensorModel pairs an approximate model with a precision model, and ChippedImageSensorModel adapts a full-image model to a chip’s local pixel coordinate system.

ElevationModel ABC represents a terrain surface used to constrain the image-to-world calculation. The package provides composable decorators: MultiElevationModel merges multiple sources by priority, OffsetElevationModel applies a provider-supplied bias, ConditionalElevationModel selects a model based on a runtime condition, and NormalizedElevationModel clamps outputs to a valid range.

Coordinate value objects (ImageCoordinate, GeodeticWorldCoordinate, WorldCoordinate) are numpy-backed vectors. Angular quantities are in radians.

        classDiagram
    class SensorModel {
        <<abstract>>
        +image_to_world(ImageCoordinate) GeodeticWorldCoordinate
        +world_to_image(GeodeticWorldCoordinate) ImageCoordinate
    }
    class RPCSensorModel
    class SICDSensorModel
    class RSMPolynomialSensorModel
    class CompositeSensorModel
    class ChippedImageSensorModel

    SensorModel <|-- RPCSensorModel
    SensorModel <|-- SICDSensorModel
    SensorModel <|-- RSMPolynomialSensorModel
    SensorModel <|-- CompositeSensorModel
    SensorModel <|-- ChippedImageSensorModel
    CompositeSensorModel o-- "2" SensorModel : approximate + precision
    ChippedImageSensorModel o-- SensorModel : delegates

    SensorModel ..> ImageCoordinate
    SensorModel ..> GeodeticWorldCoordinate

    note for SensorModel "Additional implementations (Affine, Projective,\nRSMSectioned, Defaulted) omitted for clarity"

        classDiagram
    class ElevationModel {
        <<abstract>>
        +set_elevation(GeodeticWorldCoordinate) GeodeticWorldCoordinate
    }
    class DigitalElevationModel
    class MultiElevationModel
    class OffsetElevationModel
    class ConditionalElevationModel
    class ElevationOffsetProvider {
        <<abstract>>
    }
    class ElevationModelCondition {
        <<abstract>>
    }
    class DigitalElevationModelTileSet {
        <<abstract>>
    }
    class DigitalElevationModelTileFactory {
        <<abstract>>
    }

    ElevationModel <|-- DigitalElevationModel
    ElevationModel <|-- MultiElevationModel
    ElevationModel <|-- OffsetElevationModel
    ElevationModel <|-- ConditionalElevationModel
    DigitalElevationModel o-- DigitalElevationModelTileSet
    DigitalElevationModel o-- DigitalElevationModelTileFactory
    OffsetElevationModel o-- ElevationOffsetProvider
    ConditionalElevationModel o-- ElevationModelCondition
    MultiElevationModel o-- "1..*" ElevationModel

Contributor guidance¶

New sensor model types go here as a new file implementing the SensorModel ABC. The corresponding builder that constructs the model from raw metadata belongs in the metadata package. Keep models pure-math — no I/O, no format parsing.

Coordinates¶

class aws.osml.photogrammetry.WorldCoordinate(coordinate=None)¶

Bases: object

A world coordinate is a vector representing a position in 3D space. Note that this type is a simple value with 3 components that does not distinguish between geodetic or other cartesian coordinate systems (e.g. geocentric Earth-Centered Earth-Fixed or coordinates based on a local tangent plane).

property x: float¶

property y: float¶

property z: float¶

class aws.osml.photogrammetry.GeodeticWorldCoordinate(coordinate=None)¶

Bases: WorldCoordinate

A GeodeticWorldCoordinate is an WorldCoordinate where the x,y,z components can be interpreted as longitude, latitude, and elevation. It is important to note that longitude, and latitude are in radians while elevation is meters above the ellipsoid.

This class uses a custom format specification for a geodetic coordinate uses % directives similar to datetime. These custom directives can be combined as needed with literal values to produce a wide range of output formats. For example, ‘%ld%lm%ls%lH%od%om%os%oH’ will produce a ddmmssXdddmmssY formatted coordinate. The first half, ddmmssX, represents degrees, minutes, and seconds of latitude with X representing North or South (N for North, S for South). The second half, dddmmssY, represents degrees, minutes, and seconds of longitude with Y representing East or West (E for East, W for West), respectively.

Directive	Meaning	Notes
%L	latitude in decimal radians	1
%l	latitude in decimal degrees	1
%ld	latitute degrees	2
%lm	latitude minutes
%ls	latitude seconds
%lh	latitude hemisphere (n or s)
%lH	latitude hemisphere uppercase (N or S)
%O	longitude in decimal radians	1
%o	longitude in decimal degrees	1
%od	longitude degrees	2
%om	longitude minutes
%os	longitude seconds
%oh	longitude hemisphere (e or w)
%oH	longitude hemisphere uppercase (E or W)
%E	elevation in meters
%%	used to represent a literal % in the output

Notes:

Formatting in decimal degrees or radians will be signed values
Formatting for the degrees, minutes, seconds will always be unsigned assuming hemisphere will be included
Any unknown directives will be ignored

property longitude: float¶

property latitude: float¶

property elevation: float¶

to_dms_string()¶

Outputs this coordinate in a format ddmmssXdddmmssY. The first half, ddmmssX, represents degrees, minutes, and seconds of latitude with X representing North or South (N for North, S for South). The second half, dddmmssY, represents degrees, minutes, and seconds of longitude with Y representing East or West (E for East, W for West), respectively.

Return type:: str
Returns:: the formatted coordinate string

normalized()¶

Return a new GeodeticWorldCoordinate that normalizes latitude between -90 / 90 and longitude between -180 / 180.

Return type:: GeodeticWorldCoordinate
Returns:: the new geodetic world coordinate

range_adjusted(min_lon, max_lon, min_lat, max_lat)¶

Return a new GeodeticWorldCoordinate that normalizes latitude and longitude between user input ranges.

Parameters:

min_lon (float) – the lower bound, in radians, of the new longitude range
max_lon (float) – the upper bound, in radians, of the new longitude range
min_lat (float) – the lower bound, in radians, of the new latitude range
max_lat (float) – the upper bound, in radians, of the new latitude range

Return type:

GeodeticWorldCoordinate

Returns:

the new geodetic world coordinate

class aws.osml.photogrammetry.ImageCoordinate(coordinate=None)¶

Bases: object

This image coordinate system convention is defined as follows. The upper left corner of the upper left pixel of the original full image has continuous image coordinates (pixel position) (r, c) = (0.0,0.0) , and the center of the upper left pixel has continuous image coordinates (r, c) = (0.5,0.5) . The first row of the original full image has discrete image row coordinate R = 0 , and corresponds to a range of continuous image row coordinates of r = [0,1) . The first column of the original full image has discrete image column coordinate C = 0 , and corresponds to a range of continuous image column coordinates of c = [0,1) . Thus, for example, continuous image coordinates (r, c) = (5.6,8.3) correspond to the sixth row and ninth column of the original full image, and discrete image coordinates (R,C) = (5,8).

property c: float¶

property r: float¶

property x: float¶

property y: float¶

aws.osml.photogrammetry.geocentric_to_geodetic(ecef_world_coordinate)¶

Converts a ECEF world coordinate (x, y, z) in meters into a (longitude, latitude, elevation) geodetic coordinate with units of radians, radians, meters.

Parameters:: ecef_world_coordinate (WorldCoordinate) – the geocentric coordinate
Return type:: GeodeticWorldCoordinate
Returns:: the geodetic coordinate

aws.osml.photogrammetry.geodetic_to_geocentric(geodetic_coordinate)¶

Converts a geodetic world coordinate (longitude, latitude, elevation) with units of radians, radians, meters into a ECEF / geocentric world coordinate (x, y, z) in meters.

Parameters:: geodetic_coordinate (GeodeticWorldCoordinate) – the geodetic coordinate
Return type:: WorldCoordinate
Returns:: the geocentric coordinate

Sensor Models¶

class aws.osml.photogrammetry.SensorModel¶

Bases: ABC

A sensor model is an abstraction that maps the information in a georeferenced image to the real world. The concrete implementations of this abstraction will either capture the physical service model characteristics or more frequently an approximation of that physical model that allow users to transform world coordinates to image coordinates.

abstract image_to_world(image_coordinate, elevation_model=None, options=None)¶

This function returns the longitude, latitude, elevation world coordinate associated with the x, y coordinate of any pixel in the image.

Parameters:

image_coordinate (ImageCoordinate) – the x, y image coordinate
elevation_model (Optional[ElevationModel]) – optional elevation model used to transform the coordinate
options (Optional[Dict[str, Any]]) – optional dictionary of hints that will be passed on to sensor models

Return type:

GeodeticWorldCoordinate

Returns:

GeodeticWorldCoordinate = the longitude, latitude, elevation world coordinate

abstract world_to_image(world_coordinate)¶

This function returns the x, y image coordinate associated with a given longitude, latitude, elevation world coordinate.

Parameters:: world_coordinate (GeodeticWorldCoordinate) – the longitude, latitude, elevation world coordinate
Return type:: ImageCoordinate
Returns:: the x, y image coordinate

class aws.osml.photogrammetry.SensorModelOptions(value)¶

Bases: str, Enum

These are common options for SensorModel operations. Not all implementations will support these, but they are included here to encourage convention.

INITIAL_GUESS = 'initial_guess'¶

INITIAL_SEARCH_DISTANCE = 'initial_search_distance'¶

IGNORE_DEFAULT_ELEVATION_MODEL = 'ignore_default_elevation_model'¶

class aws.osml.photogrammetry.RPCSensorModel(err_bias, err_rand, line_off, samp_off, lat_off, long_off, height_off, line_scale, samp_scale, lat_scale, long_scale, height_scale, line_num_poly, line_den_poly, samp_num_poly, samp_den_poly)¶

Bases: SensorModel

A Rational Polynomial Camera (RPC) sensor model is one where the world to image transform is approximated using a ratio of polynomials. The polynomials capture specific relationships between the latitude, longitude, and elevation and the image pixels.

These cameras were common approximations for many years but started to be phased out in 2014 in favor of the more general Replacement Sensor Model (RSM). It is not uncommon to find historical imagery or imagery from older sensors still operating today that contain the metadata for these sensor models.

world_to_image(geodetic_coordinate)¶

This function transforms a geodetic world coordinate (longitude, latitude, elevation) into an image coordinate (x, y).

Parameters:: geodetic_coordinate (GeodeticWorldCoordinate) – the world coordinate (longitude, latitude, elevation)
Return type:: ImageCoordinate
Returns:: the resulting image coordinate (x,y)

image_to_world(image_coordinate, elevation_model=None, options=None)¶

This function implements the image to world transform by iteratively invoking world to image within a minimization routine to find a matching image coordinate. The longitude and latitude parameters are searched independently while the elevation of the world coordinate comes from the elevation model.

Parameters:

image_coordinate (ImageCoordinate) – the image coordinate (x, y)
elevation_model (Optional[ElevationModel]) – an optional elevation model used to transform the coordinate
options (Optional[Dict[str, Any]]) – optional hints, supports initial_guess and initial_search_distance

Return type:

GeodeticWorldCoordinate

Returns:

the corresponding world coordinate

class aws.osml.photogrammetry.RPCPolynomial(coefficients)¶

Bases: object

evaluate(normalized_world_coordinate)¶

This function evaluates the polynomial for the given world coordinate by summing up the result of applying each coefficient to the world coordinate components. Note that these polynomials are usually defined with the assumption that the world coordinate has been normalized.

Parameters:: normalized_world_coordinate (WorldCoordinate) – the world coordinate
Return type:: float
Returns:: the resulting value

class aws.osml.photogrammetry.ProjectiveSensorModel(world_coordinates, image_coordinates)¶

Bases: SensorModel

This sensor model is used when we have a set of 2D tie point correspondences (longitude, latitude) -> (x, y) for an image.

image_to_world(image_coordinate, elevation_model=None, options=None)¶

This function returns the longitude, latitude, elevation world coordinate associated with the x, y coordinate of any pixel in the image.

Parameters:

image_coordinate (ImageCoordinate) – the x, y image coordinate
elevation_model (Optional[ElevationModel]) – optional elevation model used to transform the coordinate
options (Optional[Dict[str, Any]]) – optional dictionary of hints, this camera does not support any hints

Return type:

GeodeticWorldCoordinate

Returns:

the longitude, latitude, elevation world coordinate

world_to_image(world_coordinate)¶

This function returns the x, y image coordinate associated with a given longitude, latitude, elevation world coordinate.

Parameters:: world_coordinate (GeodeticWorldCoordinate) – the longitude, latitude, elevation world coordinate
Return type:: ImageCoordinate
Returns:: the x, y image coordinate

class aws.osml.photogrammetry.AffineSensorModel(geo_transform, proj_wkt=None)¶

Bases: SensorModel

A simple affine transform used to convert XY pixel values to longitude, latitude. See https://gdal.org/tutorials/geotransforms_tut.html

transform[0] x-coordinate of the upper-left corner of the upper-left pixel. transform[1] w-e pixel resolution / pixel width. transform[2] row rotation (typically zero). transform[3] y-coordinate of the upper-left corner of the upper-left pixel. transform[4] column rotation (typically zero). transform[5] n-s pixel resolution / pixel height (negative value for a north-up image).

image_to_world(image_coordinate, elevation_model=None, options=None)¶

This function returns the longitude, latitude, elevation world coordinate associated with the x, y coordinate of any pixel in the image. The GDAL Geo Transforms do not provide any information about elevation, so it will always be 0.0 unless the optional elevation model is provided.

Parameters:

image_coordinate (ImageCoordinate) – the x, y image coordinate
elevation_model (Optional[ElevationModel]) – an optional elevation model used to transform the coordinate
options (Optional[Dict[str, Any]]) – an optional dictionary of hints, does not support any hints

Return type:

GeodeticWorldCoordinate

Returns:

the longitude, latitude, elevation world coordinate

world_to_image(world_coordinate)¶

This function returns the x, y image coordinate associated with a given longitude, latitude, elevation world coordinate.

Parameters:: world_coordinate (GeodeticWorldCoordinate) – the longitude, latitude, elevation world coordinate
Return type:: ImageCoordinate
Returns:: the x, y image coordinate

Replacement Sensor Model (RSM)¶

class aws.osml.photogrammetry.RSMPolynomialSensorModel(context, section_row, section_col, row_norm_offset, column_norm_offset, x_norm_offset, y_norm_offset, z_norm_offset, row_norm_scale, column_norm_scale, x_norm_scale, y_norm_scale, z_norm_scale, row_numerator_poly, row_denominator_poly, column_numerator_poly, column_denominator_poly)¶

Bases: RSMSensorModel

This is an implementation of a Rational Polynomial Camera as defined in section 10.3.3.1.1 of the Manual of Photogrammetry Sixth Edition.

world_to_image(geodetic_coordinate)¶

This function transforms a geodetic world coordinate (longitude, latitude, elevation) into an image coordinate (x, y).

Parameters:: geodetic_coordinate (GeodeticWorldCoordinate) – the world coordinate (longitude, latitude, elevation)
Return type:: ImageCoordinate
Returns:: the resulting image coordinate (x,y)

image_to_world(image_coordinate, elevation_model=None, options=None)¶

Parameters:

image_coordinate (ImageCoordinate) – the image coordinate (x, y)
elevation_model (Optional[ElevationModel]) – an optional elevation model used transform the coordinate
options (Optional[Dict[str, Any]]) – optional hints, supports initial_guess and initial_search_distance

Return type:

GeodeticWorldCoordinate

Returns:

the corresponding world coordinate

ground_domain_to_image(domain_coordinate)¶

This function implements the polynomial ground-to-image transform as defined by section 10.3.3.1.1 of the Manual of Photogrammetry sixth edition. The world coordinate is first normalized using the offsets and scale factors provided. Then the rational polynomial equations are run to produce an x,y image coordinate. Those components are then denormalized to find the final image coordinate.

Parameters:: domain_coordinate (WorldCoordinate) – the ground domain coordinate (x, y, z)
Return type:: ImageCoordinate
Returns:: the image coordinate (x, y)

normalize_world_coordinate(world_coordinate)¶

This is a helper function used to normalize a world coordinate for use with the polynomials in this sensor model.

Parameters:: world_coordinate (WorldCoordinate) – the world coordinate (longitude, latitude, elevation)
Return type:: WorldCoordinate
Returns:: a world coordinate where each component has been normalized

denormalize_world_coordinate(world_coordinate)¶

This is a helper function used to denormalize a world coordinate for use with the polynomials in this sensor model.

Parameters:: world_coordinate (WorldCoordinate) – the normalized world coordinate (longitude, latitude, elevation)
Return type:: WorldCoordinate
Returns:: a world coordinate

normalize_image_coordinate(image_coordinate)¶

This is a helper function used to normalize an image coordinate for use in these polynomials.

Parameters:: image_coordinate (ImageCoordinate) – the image coordinate (x, y)
Return type:: ImageCoordinate
Returns:: the normalized image coordinate (x, y)

denormalize_image_coordinate(image_coordinate)¶

This is a helper function to denormalize an image coordinate after it has been processed by the polynomials.

Parameters:: image_coordinate (ImageCoordinate) – the normalized image coordinate (x, y)
Return type:: ImageCoordinate
Returns:: the image coordinate (x, y)

static normalize(value, offset, scale)¶

This function normalizes a value using an offset and scale using the equations defined in Section 7.2 of STDI-0002 Volume 1 Appendix U.

Parameters:

value (float) – the value to be normalized
offset (float) – the normalization offset
scale (float) – the normalization scale

Return type:

float

Returns:

the normalized value

static denormalize(value, offset, scale)¶

This function denormalizes a value using an offset and scale using the equations defined in Section 7.2 of STDI-0002 Volume 1 Appendix U.

Parameters:

value (float) – the normalized value
offset (float) – the normalization offset
scale (float) – the normalization scale

Return type:

float

Returns:

the denormalized value

class aws.osml.photogrammetry.RSMSectionedPolynomialSensorModel(context, row_num_image_sections, column_num_image_sections, row_section_size, column_section_size, row_polynomial, column_polynomial, section_sensor_models)¶

Bases: RSMSensorModel

This is an implementation of a sectioned sensor model that splits overall RSM domain into multiple regions each serviced by a dedicated sensor model. A low complexity sensor model covering the entire domain is used to first identify the general region of the image associated with a world coordinate then the final coordinate transform is delegated to a sensor model associated with that section.

world_to_image(geodetic_coordinate)¶

This function transforms a geodetic world coordinate (longitude, latitude, elevation) into an image coordinate (x, y).

Parameters:: geodetic_coordinate (GeodeticWorldCoordinate) – the world coordinate (longitude, latitude, elevation)
Return type:: ImageCoordinate
Returns:: the resulting image coordinate (x,y)

image_to_world(image_coordinate, elevation_model=None, options=None)¶

This function implements the image to world transform by selecting the sensor model responsible for coordinates in the image section and then delegating the image to world calculations to that sensor model.

Parameters:

image_coordinate (ImageCoordinate) – the image coordinate (x, y)
elevation_model (Optional[ElevationModel]) – optional elevation model used to transform the coordinate
options (Optional[Dict[str, Any]]) – optional dictionary of hints passed on to the section sensor models

Return type:

GeodeticWorldCoordinate

Returns:

the corresponding world coordinate (longitude, latitude, elevation)

get_section_index(image_coordinate)¶

Use the equations from STDO-0002 Volume 1 Appendix U Section 6.3 to calculate the section of this image containing the rough x, y. Note that these equations are slightly different from the documentation since those equations produce section numbers that start with 1, and we’re starting with 0 to more naturally index into the array of sensor models. Note that if the value is outside the normal sections it is clamped to use the sensor model from the closest section available.

Parameters:: image_coordinate (ImageCoordinate) – the image coordinate (x, y)
Return type:: Tuple[int, int]
Returns:: section index (x, y)

class aws.osml.photogrammetry.RSMPolynomial(max_power_x, max_power_y, max_power_z, coefficients)¶

Bases: object

This is an implementation of a general polynomial that can be applied to a world coordinate (i.e. an x,y,z vector). For additional information see Section 7.2 of STDI-0002 Volume 1 Appendix U or Section 10.3.3.1.1 of the Manual of Photogrammetry Sixth Edition.

evaluate(normalized_world_coordinate)¶

Parameters:: normalized_world_coordinate (WorldCoordinate) – the world coordinate
Return type:: float
Returns:: the resulting value

class aws.osml.photogrammetry.RSMLowOrderPolynomial(coefficients)¶

Bases: object

This is an implementation of a “low order” polynomial used when generating coarse image row and column coordinates from a world coordinate. For additional information see Section 6.2 of STDI-0002 Volume 1 Appendix U.

evaluate(world_coordinate)¶

This function evaluates the polynomial for the given world coordinate by summing up the result of applying each coefficient to the world coordinate components.

Parameters:: world_coordinate (WorldCoordinate) – the world coordinate
Returns:: the resulting value

class aws.osml.photogrammetry.RSMContext(ground_domain, image_domain)¶

Bases: object

The RSM context contains information necessary to apply and interpret results from the sensor models on an image.

This current implementation only covers the ground domain and image domains necessary for georeferencing but it can be expanded as needed to support other RSM functions.

TODO: Implement the TimeContext which can be used to identify the collection time of any x, y image coordinate TODO: Implement the IlluminationContext which can be used to predict shadow information on an image TODO: Implement the TrajectoryModel which captures the sensors 3D position in relation to the image

class aws.osml.photogrammetry.RSMGroundDomain(ground_domain_form, ground_domain_vertices, rectangular_coordinate_origin=None, rectangular_coordinate_unit_vectors=None, ground_reference_point=None)¶

Bases: object

The RSM ground domain is an approximation of the ground area where the RSM representation is valid. It is a solid in three-dimensional space bounded by a hexahedron with quadrilateral faces specified using eight three-dimensional vertices.

It is typically constructed from values in the NITF RSMID TRE. For more information see section 5.6 of STDI-0002 Volume 1 Appendix U.

geodetic_to_ground_domain_coordinate(geodetic_coordinate)¶

This function converts WGS-84 geodetic world coordinate into a world coordinate that uses the domain coordinate system for this sensor model.

Parameters:: geodetic_coordinate (GeodeticWorldCoordinate) – the WGS-84 longitude, latitude, elevation
Return type:: WorldCoordinate
Returns:: the x, y, z domain coordinate

ground_domain_coordinate_to_geodetic(ground_domain_coordinate)¶

This function converts an x, y, z coordinate defined in the ground domain of this sensor model into a WGS-84 longitude, latitude, elevation coordinate.

Parameters:: ground_domain_coordinate (WorldCoordinate) – the x, y, z domain coordinate
Return type:: GeodeticWorldCoordinate
Returns:: the WGS-84 longitude, latitude, elevation coordinate

class aws.osml.photogrammetry.RSMGroundDomainForm(value)¶

Bases: Enum

The RSMGroundDomainForm defines how world coordinates (x, y, z) should be interpreted in this sensor model.

If geodetic, X, Y, and Z, correspond to longitude, latitude, and height above the ellipsoid, respectively. Longitude is specified east of the prime meridian, and latitude is specified north of the equator. Units for X, Y, and Z, are radians, radians, and meters, respectively. The range for Y is (-pi/2 to pi/2). The range for X is (-pi to pi) when GEODETIC, and (0 to 2pi) when GEODETIC_2PI. The latter is specified when the RSM ground domain contains a longitude value near pi radians.

If RECTANGULAR, X, Y, and Z correspond to a coordinate system that is defined as an offset from and rotation about the WGS 84 Rectangular coordinate system.

For more information see the GRNDD TRE field definition in section 5.9 of STDI-0002 Volume 1 Appendix U.

GEODETIC = 'G'¶

GEODETIC_2PI = 'H'¶

RECTANGULAR = 'R'¶

class aws.osml.photogrammetry.RSMImageDomain(min_row, max_row, min_column, max_column)¶

Bases: object

This RSM image domain is a rectangle defined by the minimum and maximum discrete row coordinate values, and the minimum and maximum discrete column coordinate values. It is typically constructed from values in the NITF RSMID TRE. For more information see section 5.5 of STDI-0002 Volume 1 Appendix U.

SICD Sensor Model¶

class aws.osml.photogrammetry.SICDSensorModel(coord_converter, coa_projection_set, u_spn, side_of_track='L', u_gpn=None)¶

Bases: SensorModel

This is an implementation of the SICD sensor model as described by SICD Volume 3 Image Projections Description NGA.STND.0024-3_1.3.0 (2021-11-30)

static compute_side_of_track(scp_ecf, scp_arp, scp_varp)¶

This helper function computes side of track through partially calculating squint angle. For squint angle reference, see Volume 1 of the SIDD Specification.

Parameters:

scp_ecf (WorldCoordinate) – Scene Center Point position in ECF coordinates
scp_arp (ndarray) – aperture reference point position
scp_varp (ndarray) – aperture reference point velocity

Return type:

str

Returns:

either ‘R’ for right or ‘L’ for left

static compute_u_spn(scp_ecf, scp_arp, scp_varp, side_of_track)¶

This helper function computes the slant plane normal.

Parameters:

scp_ecf (WorldCoordinate) – Scene Center Point position in ECF coordinates
scp_arp (ndarray) – aperture reference point position
scp_varp (ndarray) – aperture reference point velocity
side_of_track (str) – side of track imaged

Return type:

ndarray

Returns:

unit vector for the slant plane normal

static compute_u_gpn(scp_ecf, u_row, u_col)¶

Return type:: ndarray

image_to_world(image_coordinate, elevation_model=None, options=None)¶

This is an implementation of an Image Grid to Scene point projection that first projects the image location to the R/RDot contour and then intersects the R/RDot contour with the elevation model. If an elevation model is provided then this routine intersects the R/Rdot contour with the DEM surface which may result in multiple solutions. In that case the solution with the lowest HAE is returned.

Parameters:

image_coordinate (ImageCoordinate) – the x,y image coordinate
elevation_model (Optional[ElevationModel]) – the optional elevation model, if none supplied a plane tangent to SCP is assumed
options (Optional[Dict[str, Any]]) – no additional options are supported at this time

Return type:

GeodeticWorldCoordinate

Returns:

the lon, lat, elev geodetic coordinate of the surface matching the image coordinate

world_to_image(world_coordinate)¶

This is an implementation of Section 6.1 Scene To Image Grid Projection for a single point.

Parameters:: world_coordinate (GeodeticWorldCoordinate) – lon, lat, elevation coordinate of the scene point
Return type:: ImageCoordinate
Returns:: the x,y pixel location in this image

class aws.osml.photogrammetry.SARImageCoordConverter(scp_pixel, scp_ecf, u_row, u_col, row_ss, col_ss, first_pixel=ImageCoordinate(coordinate=array([0., 0.])))¶

Bases: object

This class contains image grid and image plane coordinate conversions for a provided set of SICD parameters. The equations are mostly defined in Section 2 of the SICD Standard Volume 3.

rowcol_to_xrowycol(row_col)¶

This function converts the row and column indexes (row, col) in the global image grid to SCP centered image coordinates (xrow, ycol) using equations (2) (3) in Section 2.2 of the SICD Specification Volume 3.

Parameters:: row_col (ndarray) – the [row, col] location as an array
Return type:: ndarray
Returns:: the [xrow, ycol] location as an array

xrowycol_to_rowcol(xrow_ycol)¶

This function converts the SCP centered image coordinates (xrow, ycol) to row and column indexes (row, col) in the global image grid using equations (2) (3) in Section 2.2 of the SICD Specification Volume 3.

Parameters:: xrow_ycol (ndarray) – the [xrow, ycol] location as an array
Return type:: ndarray
Returns:: the [row, col] location as an array

xrowycol_to_ipp(xrow_ycol)¶

This function converts SCP centered image coordinates (xrow, ycol) to a ECF coordinate, image plane point (IPP), on the image plane using equations in Section 2.4 of the SICD Specification Volume 3.

Parameters:: xrow_ycol (ndarray) – the [xrow, ycol] location as an array
Return type:: ndarray
Returns:: the image plane point [x, y, z] ECF location on the image plane

ipp_to_xrowycol(ipp)¶

This function converts an ECF location on the image plane into SCP centered image coordinates (xrow, ycol) using equations in Section 2.4 of the SICD Specification volume 3.

Parameters:: ipp (ndarray) – the image plane point [x, y, z] ECF location on the image plane
Return type:: ndarray
Returns:: the [xrow, ycol] location as an array

class aws.osml.photogrammetry.COAProjectionSet(coa_time_poly, arp_poly, delta_arp=array([0., 0., 0.]), delta_varp=array([0., 0., 0.]), range_bias=0.0)¶

Bases: object

This is an abstract base class for R/Rdot projection contour computations described in Section 4 of the SICD Standard Volume 3.

precise_rrdot_computation(xrow_ycol)¶

This executes the precise image pixel grid location to R/Rdot projection. This function invokes the _grid_specific_projection() function implemented by subclasses which should handle the portions of the calculation that are dependent on the image grid and image formation algorithm.

Parameters:: xrow_ycol (ndarray) – the [xrow, ycol] location as an array
Return type:: Tuple[ndarray, ndarray, ndarray, ndarray, ndarray]
Returns:: the COA projection set { Rcoa, Rdotcoa, tcoa, arpcoa, varpcoa }

class aws.osml.photogrammetry.PFAProjectionSet(scp_ecf, polar_ang_poly, spatial_freq_sf_poly, coa_time_poly, arp_poly, delta_arp=array([0., 0., 0.]), delta_varp=array([0., 0., 0.]), range_bias=0.0)¶

Bases: COAProjectionSet

This Center Of Aperture (COA) Projection set is to be used with a range azimuth image grid (RGAZIM) and polar formatted (PFA) phase history data. See section 4.1 of the SICD Specification Volume 3.

class aws.osml.photogrammetry.INCAProjectionSet(r_ca_scp, inca_time_coa_poly, drate_sf_poly, coa_time_poly, arp_poly, delta_arp=array([0., 0., 0.]), delta_varp=array([0., 0., 0.]), range_bias=0.0)¶: Bases: COAProjectionSet

class aws.osml.photogrammetry.RGAZCOMPProjectionSet(scp_ecf, az_scale_factor, coa_time_poly, arp_poly, delta_arp=array([0., 0., 0.]), delta_varp=array([0., 0., 0.]), range_bias=0.0)¶: Bases: COAProjectionSet

class aws.osml.photogrammetry.PlaneProjectionSet(scp_ecf, image_plane_urow, image_plane_ucol, coa_time_poly, arp_poly, delta_arp=array([0., 0., 0.]), delta_varp=array([0., 0., 0.]), range_bias=0.0)¶: Bases: COAProjectionSet

class aws.osml.photogrammetry.Polynomial2D(coef)¶

Bases: object

This class contains coefficients for a two-dimensional polynomial.

class aws.osml.photogrammetry.PolynomialXYZ(x_polynomial, y_polynomial, z_polynomial)¶

Bases: object

This class is an aggregation 3 one-dimensional polynomials all with the same input variable. The result of evaluating this class on the input variable is an [x, y, z] vector.

deriv(m=1)¶

Create a new PolynomialXYZ that is the derivative of the current PolynomialXYZ.

Parameters:: m (int) – find the derivative of order m
Returns:: the new polynomial derivative

Composite and Chipped Models¶

class aws.osml.photogrammetry.CompositeSensorModel(approximate_sensor_model, precision_sensor_model)¶

Bases: SensorModel

A CompositeSensorModel is a SensorModel that combines an approximate but fast model with an accurate but slower model.

image_to_world(image_coordinate, elevation_model=None, options=None)¶

This function first calls the approximate model’s image_to_world function to get an initial guess and then passes that information to the more accurate model through the options parameter’s ‘initial_guess’ and ‘initial_search_distance’ options.

Parameters:

image_coordinate (ImageCoordinate) – the x, y image coordinate
elevation_model (Optional[ElevationModel]) – an optional elevation model used to transform the coordinate
options (Optional[Dict[str, Any]]) – the options that will be augmented and then passed along

Return type:

GeodeticWorldCoordinate

Returns:

the longitude, latitude, elevation world coordinate

world_to_image(world_coordinate)¶

This is just a pass through to the more accurate sensor model’s world_to_image. These calculations tend to be quicker so there is no need to involve the approximate model.

Parameters:: world_coordinate (GeodeticWorldCoordinate) – the longitude, latitude, elevation world coordinate
Return type:: ImageCoordinate
Returns:: the x, y image coordinate

class aws.osml.photogrammetry.ChippedImageSensorModel(original_image_coordinates, chipped_image_coordinates, full_image_sensor_model)¶

Bases: SensorModel

This sensor model should be used when we have pixels for only a portion of the image, but we have a sensor model that describes the full image. In this case the image coordinates need to be converted to those of the full image before being used by the full sensor model.

image_to_world(image_coordinate, elevation_model=None, options=None)¶

This function returns the longitude, latitude, elevation world coordinate associated with the x, y coordinate of any pixel in the image.

Parameters:

image_coordinate (ImageCoordinate) – the x, y image coordinate
elevation_model (Optional[ElevationModel]) – an elevation model used to transform the coordinate
options (Optional[Dict[str, Any]]) – a dictionary of options that will be passed on to the full image sensor model

Return type:

GeodeticWorldCoordinate

Returns:

the longitude, latitude, elevation world coordinate

world_to_image(world_coordinate)¶

This function returns the x, y image coordinate associated with a given longitude, latitude, elevation world coordinate.

Parameters:: world_coordinate (GeodeticWorldCoordinate) – the longitude, latitude, elevation world coordinate
Return type:: ImageCoordinate
Returns:: the x, y image coordinate

class aws.osml.photogrammetry.DefaultedSensorModel(inner_sensor_model, elevation_model=None, options=None)¶

Bases: SensorModel

Sensor model wrapper that adds default options for image_to_world.

image_to_world(image_coordinate, elevation_model=None, options=None)¶

This function returns the longitude, latitude, elevation world coordinate associated with the x, y coordinate of any pixel in the full image.

Parameters:

image_coordinate (ImageCoordinate) – the x, y full image coordinate
elevation_model (Optional[ElevationModel]) – optional elevation model used to transform the coordinate
options (Optional[Dict[str, Any]]) – optional dictionary of hints, passed to nested sensor models

Return type:

GeodeticWorldCoordinate

Returns:

the longitude, latitude, elevation world coordinate

world_to_image(world_coordinate)¶

This function returns the x, y full image coordinate associated with a given longitude, latitude, elevation world coordinate. If elevation is NaN, it will be set by the default elevation model if it exists.

Parameters:: world_coordinate (GeodeticWorldCoordinate) – the longitude, latitude, elevation world coordinate
Return type:: ImageCoordinate
Returns:: the x, y full image coordinate

Elevation Models¶

class aws.osml.photogrammetry.ElevationModel¶

Bases: ABC

An elevation model associates a height z for a given x, y of a world coordinate. It typically provides information about the terrain associated with longitude, latitude locations of an ellipsoid, but it can also be used to model surfaces for other ground domains.

abstract set_elevation(world_coordinate)¶

This method updates the elevation component of a world coordinate to match the surface elevation at longitude, latitude.

Parameters:: world_coordinate (GeodeticWorldCoordinate) – the coordinate to update
Return type:: bool
Returns:: True if the elevation was updated, else False

abstract describe_region(world_coordinate)¶

Get a summary of the region near the provided world coordinate

Parameters:: world_coordinate (GeodeticWorldCoordinate) – the coordinate at the center of the region of interest
Return type:: Optional[ElevationRegionSummary]
Returns:: the summary information

class aws.osml.photogrammetry.ConstantElevationModel(constant_elevation)¶

Bases: ElevationModel

A constant elevation model with a single value for all longitude, latitude.

set_elevation(world_coordinate)¶

Updates world coordinate’s elevation to match the constant elevation.

Parameters:: world_coordinate (GeodeticWorldCoordinate) – the coordinate to update
Return type:: bool
Returns:: True if the elevation was updated, else False

describe_region(world_coordinate)¶

Get a summary of the region near the provided world coordinate

Parameters:: world_coordinate (GeodeticWorldCoordinate) – the coordinate at the center of the region of interest
Return type:: Optional[ElevationRegionSummary]
Returns:: [min elevation value, max elevation value, no elevation data value, post spacing]

class aws.osml.photogrammetry.DigitalElevationModel(tile_set, tile_factory, raster_cache_size=10, propagate_nans=True)¶

Bases: ElevationModel

A Digital Elevation Model (DEM) is a representation of the topographic surface of the Earth. Theoretically these representations exclude trees, buildings, and any other surface objects but in practice elevations from those objects are likely captured by the sensors use to capture the elevation data.

These datasets are normally stored as a pre-tiled collection of images with a well established resolution and coverage.

set_elevation(geodetic_world_coordinate)¶

This method updates the elevation component of a geodetic world coordinate to match the surface elevation at the provided latitude and longitude. Note that if the DEM does not have elevation values for this region or if there is an error loading the associated image the elevation will be unchanged.

Parameters:: geodetic_world_coordinate (GeodeticWorldCoordinate) – the coordinate to update
Return type:: bool
Returns:: True if the elevation was updated, else False

describe_region(geodetic_world_coordinate)¶

Get a summary of the region near the provided world coordinate

Parameters:: geodetic_world_coordinate (GeodeticWorldCoordinate) – the coordinate at the center of the region of interest
Return type:: Optional[ElevationRegionSummary]
Returns:: a summary of the elevation data in this tile

get_interpolation_grid(self, tile_path) = <cachetools._cachedmethod._unlocked.<locals>.Descriptor.Wrapper object>¶

class aws.osml.photogrammetry.DigitalElevationModelTileFactory¶

Bases: ABC

This class defines an abstraction that is able to load a tile and convert it to a Numpy array of elevation data along with a SensorModel that can be used to identify the grid locations associated with a latitude, longitude.

Returns:: None

abstract get_tile(tile_path)¶

Retrieve a numpy array of elevation values and a sensor model.

TODO: Replace Any with numpy.typing.ArrayLike once we move to numpy >1.20

Parameters:: tile_path (str) – the location of the tile to load
Return type:: Tuple[Optional[Any], Optional[SensorModel], Optional[ElevationRegionSummary]]
Returns:: an array of elevation values, a sensor model, and a summary

class aws.osml.photogrammetry.DigitalElevationModelTileSet¶

Bases: ABC

This class defines an abstraction that is capable of identifying which elevation tile in a DEM contains the elevations for a given world coordinate. It is common to split a DEM with global coverage up into a collection of files with well understood coverage areas. Those files may follow a simple naming convention but could be cataloged in an external spatial index. This class abstracts those details away from the DigitalElevationModel allowing us to easily extend this design to various tile sets.

Returns:: None

abstract find_tile_id(geodetic_world_coordinate)¶

Converts the latitude, longitude of the world coordinate into a tile path.

Parameters:: geodetic_world_coordinate (GeodeticWorldCoordinate) – GeodeticWorldCoordinate = the world coordinate of interest
Return type:: Optional[str]
Returns:: the tile path or None if the DEM does not have coverage for this location

class aws.osml.photogrammetry.MultiElevationModel(elevation_models)¶

Bases: ElevationModel

Call multiple elevation models in order, using the result of the first to successfully update the elevation value.

set_elevation(world_coordinate)¶

Set elevation by using multiple inner models.

Parameters:: geodetic_world_coordinate – the coordinate to update
Return type:: bool
Returns:: True if the elevation was updated, else False

describe_region(geodetic_world_coordinate)¶

Return the first non-None region summary from the ordered elevation models.

Parameters:: geodetic_world_coordinate (GeodeticWorldCoordinate) – the coordinate at the center of the region of interest
Return type:: Optional[ElevationRegionSummary]
Returns:: the summary from the first model that provides one, or None

class aws.osml.photogrammetry.NormalizedElevationModel(inner_elevation_model)¶

Bases: ElevationModel

An elevation model that auto normalizes input.

set_elevation(world_coordinate)¶

Set elevation using a normalized coordinate for the inner model.

Parameters:: world_coordinate (GeodeticWorldCoordinate) – the coordinate to update
Return type:: bool
Returns:: True if the elevation was updated, else False

describe_region(world_coordinate)¶

Get a summary of the region near the provided world coordinate

Parameters:: world_coordinate (GeodeticWorldCoordinate) – the coordinate at the center of the region of interest
Return type:: Optional[ElevationRegionSummary]
Returns:: the summary information

class aws.osml.photogrammetry.OffsetElevationModel(inner_elevation_model, offset_provider)¶

Bases: ElevationModel

An elevation model that adds an offset to the result of an inner elevation model when the elevation is set.

set_elevation(world_coordinate)¶

Set elevation using the inner model + offset.

Parameters:: world_coordinate (GeodeticWorldCoordinate) – the coordinate to update
Return type:: bool
Returns:: True if the elevation was updated, else False

describe_region(world_coordinate)¶

Delegate to the inner model and adjust min/max elevation by the offset at this coordinate.

Parameters:: world_coordinate (GeodeticWorldCoordinate) – the coordinate at the center of the region of interest
Return type:: Optional[ElevationRegionSummary]
Returns:: the adjusted summary, or None if the inner model returns None

class aws.osml.photogrammetry.ConditionalElevationModel(inner_elevation_model, em_condition)¶

Bases: ElevationModel

An elevation model that sets elevation using an inner elevation model only if it first passes a condition on the given coordinate.

set_elevation(world_coordinate)¶

Set elevation conditionally using the inner model.

Parameters:: world_coordinate (GeodeticWorldCoordinate) – the coordinate to update
Return type:: bool
Returns:: True if the elevation was updated, else False

describe_region(world_coordinate)¶

Check the condition and delegate to the inner model if true.

Parameters:: world_coordinate (GeodeticWorldCoordinate) – the coordinate at the center of the region of interest
Return type:: Optional[ElevationRegionSummary]
Returns:: the inner model’s summary if condition is true, else None

class aws.osml.photogrammetry.ElevationRegionSummary(min_elevation, max_elevation, no_data_value, post_spacing)¶

Bases: object

This class contains a general summary of an elevation tile.

min_elevation: float¶

max_elevation: float¶

no_data_value: int¶

post_spacing: float¶

DEM Tile Sets¶

class aws.osml.photogrammetry.GenericDEMTileSet(format_spec='%od%oh/%ld%lh.dt2', min_latitude_degrees=-90.0, max_latitude_degrees=90.0, min_longitude_degrees=-180.0, max_longitude_degrees=180.0)¶

Bases: DigitalElevationModelTileSet

A generalizable tile set with a naming convention that can be described as a format string.

find_tile_id(geodetic_world_coordinate)¶

This method creates tile IDs that based on the format string provided.

Parameters:: geodetic_world_coordinate (GeodeticWorldCoordinate) – the world coordinate of interest
Return type:: Optional[str]
Returns:: the tile path or None if the DEM does not have coverage for this location

class aws.osml.photogrammetry.SRTMTileSet(prefix='', version='1arc_v3', format_extension='.tif')¶

Bases: DigitalElevationModelTileSet

A tile set for SRTM content downloaded from the USGS website.

find_tile_id(geodetic_world_coordinate)¶

This method creates tile IDs that match the file names for grid tiles downloaded using the USGS Earth Eplorer. It appears they are following a <latitude degrees>_<longitude degrees>_<resolution>_<version><format> convention. Examples:

n47_e034_3arc_v2.tif: 3 arc second resolution
n47_e034_1arc_v3.tif: 1 arc second resolution

Parameters:: geodetic_world_coordinate (GeodeticWorldCoordinate) – the world coordinate of interest
Return type:: Optional[str]
Returns:: the tile path or None if the DEM does not have coverage for this location

Elevation Conditions and Offsets¶

class aws.osml.photogrammetry.ElevationModelCondition¶

Bases: ABC

A base class functor for determining a True / False condition based on a given coordinate.

abstract 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.photogrammetry.EMConditionTrue¶

Bases: ElevationModelCondition

An always True ElevationModel condition.

is_true(world_coordinate)¶

Always returns True.

Parameters:: world_coordinate (GeodeticWorldCoordinate) – the coordinate to evaluate
Return type:: bool
Returns:: True

class aws.osml.photogrammetry.EMConditionFalse¶

Bases: ElevationModelCondition

An always False ElevationModel condition.

is_true(world_coordinate)¶

Always returns False.

Parameters:: world_coordinate (GeodeticWorldCoordinate) – the coordinate to evaluate
Return type:: bool
Returns:: False

class aws.osml.photogrammetry.ElevationOffsetProvider¶

Bases: ABC

A base class functor for calculating a WGS84 height offset, in meters, given a coordinate. It is common for elevation data sources to reference a 0-level that does not match WGS84.

abstract get_offset(geodetic_world_coordinate)¶

Provide a WGS84 height offset, in meters, given a coordinate.

Parameters:: geodetic_world_coordinate (GeodeticWorldCoordinate) – the world coordinate of interest
Return type:: float
Returns:: meters above WGS84 ellipsoid

class aws.osml.photogrammetry.ConstantOffsetProvider(constant_offset)¶

Bases: ElevationOffsetProvider

Provide a constant WGS84 height offset.

get_offset(geodetic_world_coordinate)¶

Provide a WGS84 height offset, in meters, given a coordinate.

Parameters:: geodetic_world_coordinate (GeodeticWorldCoordinate) – the world coordinate of interest
Return type:: float
Returns:: meters above WGS84 ellipsoid

Geometry Utilities¶

class aws.osml.photogrammetry.GeometryQuery¶

Bases: ABC

Define an abstraction for a query returning a geometry.

abstract get_geometry(world_coordinate)¶

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

Parameters:: world_coordinate (GeodeticWorldCoordinate) – the point of interest
Return type:: Optional[Geometry]
Returns:: the geometry