aws.osml.image_processing

The image_processing package contains various utilities for manipulating overhead imagery.

Image Tiling: Tiling With Updated Image Metadata

Many applications break large remote sensing images into smaller chips or tiles for distributed processing or dissemination. GDAL’s Translate function provides basic capabilities, but it does not correctly update geospatial metadata to reflect the new image extent. These utilities provide those functions so tile consumers can correctly interpret the pixel information they have been provided.

Example showing creation of a NITF tile from the upper left corner of an image

# Load the image and create a sensor model
ds, sensor_model = load_gdal_dataset("./imagery/sample.nitf")
tile_factory = GDALTileFactory(ds,
                               sensor_model,
                               GDALImageFormats.NITF,
                               GDALCompressionOptions.NONE
                               )

# Bounds are [left_x, top_y, width, height]
nitf_encoded_tile_bytes = tile_factory.create_encoded_tile([0, 0, 1024, 1024])

Image Tiling: Tiles for Display

Some images, for example 11-bit panchromatic images or SAR imagery with floating point complex data, can not be displayed directly without remapping the pixels into an 8-bit per pixel grayscale or RGB color model. The TileFactory supports creation of tiles suitable for human review by setting both the output_type and range_adjustment options. Note that the output_size parameter can be used to generate lower resolution tiles. This operation will make use of GDAL generated overviews if they are available to the dataset.

Example showing creation of a PNG tile scaled down from the full resolution image

viz_tile_factory = GDALTileFactory(ds,
                                   sensor_model,
                                   GDALImageFormats.PNG,
                                   GDALCompressionOptions.NONE,
                                   output_type=gdalconst.GDT_Byte,
                                   range_adjustment=RangeAdjustmentType.DRA)

viz_tile = viz_tile_factory.create_encoded_tile([0, 0, 1024, 1024], output_size=(512, 512))

Image Tiling: Map Tiles / Orthophotos

The TileFactory supports creation of tiles suitable for use by geographic information systems (GIS) or map-based visualization tools. Given a north-east aligned bounding box in geographic coordinates the tile factory can use the sensor models to orthorectify imagery to remove the perspective and terrain effects.

Example showing creation of a map tile from the WebMercatorQuad tile set

# Look up the tile boundary for a tile in a well known tile set
tile_set = MapTileSetFactory.get_for_id("WebMercatorQuad")
tile_id = MapTileId(tile_matrix=16, tile_row=37025, tile_col=54816)
tile = tile_set.get_tile(tile_id)

# Create an orthophoto for this tile
image_bytes = viz_tile_factory.create_orthophoto_tile(geo_bbox=tile.bounds, tile_size=tile.size)

Original image with perspective effects and same area after orthorectification — Example showing original image with perspective effects and same area after orthorectification.

Orthophoto tile overlaid on Google Maps — Example showing map tile overlaid on Google Maps

Complex SAR Data Display

There are a variety of different techniques to convert complex SAR data to a simple image suitable for human display. The toolkit contains two helper functions that can convert complex image data into an 8-bit grayscle representation The equations implemented are described in Sections 3.1 and 3.2 of SAR Image Scaling, Dynamic Range, Radiometric Calibration, and Display (SAND2019-2371).

Example converting complex SAR data into a 8-bit per pixel image for display

import numpy as np
from aws.osml.image_processing import histogram_stretch, quarter_power_image

sicd_dataset, sensor_model = load_gdal_dataset("./sample-sicd.nitf")
complex_pixels = sicd_dataset.ReadAsArray()

histo_stretch_pixels = histogram_stretch(complex_pixels)
quarter_power_pixels = quarter_power_image(complex_pixels)

Histogram Stretch Applied to Sample SICD Image — Example of applying histogram_stretch to a sample SICD image.

Quarter Power Image Applied to Sample SICD Image — Example of applying quarter_power_image to a sample SICD image.

APIs

class aws.osml.image_processing.GDALTileFactory(raster_dataset: Dataset, sensor_model: SensorModel | None = None, tile_format: GDALImageFormats = GDALImageFormats.NITF, tile_compression: GDALCompressionOptions = GDALCompressionOptions.NONE, output_type: int | None = None, range_adjustment: RangeAdjustmentType = RangeAdjustmentType.NONE)[source]

Bases: object

This class creates tiles from a larger image on request. Image metadata is retained whenever possible but updated as necessary to account for the new raster bounds.

create_encoded_tile(src_window: List[int], output_size: Tuple[int, int] | None = None) → bytearray | None[source]

This method cuts a tile from the full image, updates the metadata as needed, and finally compresses/encodes the result in the output format requested.

Parameters:

src_window – the [left_x, top_y, width, height] bounds of this tile
output_size – an optional size of the output tile (width, height)

Returns:

the encoded image tile or None if one could not be produced

create_orthophoto_tile(geo_bbox: Tuple[float, float, float, float], tile_size: Tuple[int, int]) → bytearray | None[source]

This method creates an orthorectified tile from an image assuming there is overlap in the coverage.

IMPORTANT: This is an experimental API that may change in future minor releases of the toolkit. This early release is subject to the following limitations: - All tiles are returned in PNG format - An 8-bit conversion and dynamic range mapping is automatically applied using the statistics of the tile

Parameters:

geo_bbox – the geographic bounding box of the tile in the form (min_lon, min_lat, max_lon, max_lat)
tile_size – the shape of the output tile (width, height)

Returns:

the encoded image tile or None if one could not be produced

class aws.osml.image_processing.MapTile(id: TildId, size: MapTileSize, bounds: MapTileBounds)[source]

Bases: object

This dataclass provides a description of a map tile that is part of a well known tile set.

id: TildId

size: MapTileSize

bounds: MapTileBounds

aws.osml.image_processing.MapTileId: alias of TildId

class aws.osml.image_processing.MapTileSet[source]

Bases: ABC

This class provides an abstract interface to a well known set of map tiles.

abstract property tile_matrix_set_id: str

Get the identifier for this map tile set. This is the tile matrix set ID in the OGC definitions.

Returns:: the tile matrix set ID

abstract get_tile(tile_id: TildId) → MapTile[source]

Get a description of the tile identified by a specific map tile ID.

Parameters:: tile_id – the tile ID
Returns:: the tile description

abstract get_tile_for_location(world_coordinate: GeodeticWorldCoordinate, tile_matrix: int) → MapTile[source]

Get a description of the tile containing a specific world location.

Parameters:

world_coordinate – the location in the world
tile_matrix – the tile_matrix or zoom level of interest

Returns:

the tile description

get_tile_matrix_limits_for_area(boundary_coordinates: list[GeodeticWorldCoordinate], tile_matrix: int) → tuple[int, int, int, int][source]

Get a list of all tiles that intersect a specific area.

Parameters:

boundary_coordinates – the boundary of the area
tile_matrix – the tile_matrix or zoom level of interest

Returns:

the (min_col, min_row, max_col, max_row) limits of tiles containing all points

class aws.osml.image_processing.MapTileSetFactory[source]

Bases: object

This class provides a means to construct / access the implementation of well known tile sets using their name. It allows clients to easily work with the TileSet abstraction independent of any implementation details associated with specific tile sets.

static get_for_id(tile_matrix_set_id: str) → MapTileSet | None[source]

Constructs a tile set matching the requested id.

Parameters:: tile_matrix_set_id – the tile set id
Returns:: the TileSet or None if not available

class aws.osml.image_processing.WellKnownMapTileSet(value)[source]

Bases: str, Enum

A partial list of well known tile sets used by this library.

WEB_MERCATOR_QUAD = 'WebMercatorQuad'

WEB_MERCATOR_QUAD_X2 = 'WebMercatorQuadx2'

This function converts SAR image pixels to an 8-bit grayscale image by scaling the pixels and cropping to the desired range [0:255]. This is histogram stretching without any gamma correction. The equations are described in Section 3.1 of SAR Image Scaling, Dynamic Range, Radiometric Calibration, and Display (SAND2019-2371).

Parameters:

image_pixels – the SAR image pixels
pixel_type – “AMP8I_PHS8I”, “RE32F_IM32F”, or “RE16I_IM16I”
amplitude_table – optional lookup table of amplitude values for AMP8I_PHS8I image pixels
scale_factor – a scale factor, default = 8.0

Returns:

the quantized grayscale image clipped to the range of [0:255]

This function converts SAR image pixels to an 8-bit grayscale image pixel magnitudes to a Quarter-Power Image using equations found in Section 3.2 of SAR Image Scaling, Dynamic Range, Radiometric Calibration, and Display (SAND2019-2371).

Parameters:

image_pixels – the SAR image pixels
pixel_type – “AMP8I_PHS8I”, “RE32F_IM32F”, or “RE16I_IM16I”
amplitude_table – optional lookup table of amplitude values for AMP8I_PHS8I image pixels
scale_factor – a brightness factor that is typically between 5 and 3
precomputed_mean – a precomputed mean of magnitude usually taken from a larger set of pixels

Returns:

the quantized grayscale image clipped to the range of [0:255]