Convenience Functions¶
High-level functions for common image read, write, inspect, and tiling
operations. These are thin wrappers over the low-level API — see
DatasetReader, DatasetWriter,
and ImageAssetProvider for full control.
imread¶
- aws.osml.io.imread(path, *, window=None, asset=None, bands=None, resolution_level=0, fill_value=0, format=None)¶
Read an image file (or a windowed region) as a NumPy array.
Returns a CHW array with shape
(bands, height, width).Note
When reading from a stream, the entire content is loaded into memory via
.read(). For large files (multi-GB NITF), this is significantly more expensive than the memory-mapped file path. Consider downloading large files to the local filesystem, or using the VirtualiZarr-based tile index for cloud-native range-read access.- Parameters:
path (
str|BinaryIO) – Path to the image file, or a file-like object containing image bytes.window (
tuple[int,int,int,int] |None) – Optional pixel region to read as(x, y, width, height)where x and y are column and row offsets of the top-left corner. IfNone, the entire image is read.asset (
str|None) – Explicit asset key to read. IfNone, the first image asset with role"data"is used (falling back to the first image asset of any role).bands (
list[int] |None) – Zero-based band indices to decode. IfNone, all bands are returned.resolution_level (
int) – Resolution level for block decoding.0is full resolution; higher levels produce progressively smaller arrays (each level halves dimensions).fill_value (
int|float) – Value used to fill regions wherehas_block()returns False. Defaults to0.format (
str|None) – Explicit format string (e.g."png","nitf"). Required when reading from a stream. IfNoneand path is a string, the format is inferred from the file extension.
- Returns:
Pixel data in CHW layout
(bands, height, width).- Return type:
ndarray[tuple[Any,...],dtype[TypeVar(_ScalarT, bound=generic)]]- Raises:
IOError – If the file does not exist or cannot be opened.
ValueError – If the specified asset key does not exist, if the dataset contains no image assets, if the window has zero or negative dimensions after clamping, or if path is a stream and format is not provided.
imsave¶
- aws.osml.io.imsave(path, data, *, compression=None, block_size=None, corners=None, crs=None, quality=None, format=None)¶
Save a NumPy array to an image file.
The array should be in CHW layout
(bands, height, width). 2-D arrays(height, width)are treated as single-band images by reshaping to(1, height, width)before writing.The output format is inferred from the file extension when path is a string and format is not provided. When path is a file-like object, format must be specified explicitly.
- Parameters:
path (
str|BinaryIO) – Output file path or a writable file-like object. When a string, the extension determines the format (e.g..ntf→ NITF,.tif→ GeoTIFF,.png→ PNG,.j2k→ JPEG 2000,.jpg→ JPEG).data (
ndarray) – Pixel data in CHW layout(bands, height, width)or a 2-D array(height, width)for single-band images.compression (
str|None) – Compression algorithm override. IfNone, a sensible default is chosen for the format (e.g. Deflate for GeoTIFF, JPEG 2000 lossless for NITF).block_size (
tuple[int,int] |None) – Block dimensions as(width, height)override. IfNone, a format-appropriate default is used (e.g. 256×256 for GeoTIFF, 1024×1024 for NITF, full image for PNG/JPEG).corners (
list[tuple[float,float]] |None) – Four geographic corner coordinates as[(lon, lat), ...]in order UL, UR, LR, LL. Used for georeferencing (NITF IGEOLO, GeoTIFF tiepoints). Silently ignored for formats that do not support georeferencing.crs (
str|None) – Coordinate reference system identifier (e.g."EPSG:4326"). Used together with corners for georeferencing.quality (
float|None) – Quality parameter for lossy formats (e.g. JPEG quality 0–100, JPEG 2000 compression ratio).format (
str|None) – Explicit format string (e.g."png","nitf"). Required when writing to a stream. IfNoneand path is a string, the format is inferred from the file extension.
- Raises:
ValueError – If the file extension is not recognized, the array dtype is unsupported for the target format, the array has invalid dimensions (0-D, 1-D, or >3-D), the array is empty, or path is a stream and format is not provided.
- Return type:
iminfo¶
- aws.osml.io.iminfo(path, *, asset=None, format=None)¶
Get image metadata without reading pixel data.
Returns an
ImageInfoobject with image dimensions, band count, pixel type, block layout, resolution level count, and the full format-specific metadata dictionary for the image segment.- Parameters:
path (
str|BinaryIO) – Path to the image file, or a file-like object containing image bytes.asset (
str|None) – Explicit asset key to inspect. IfNone, the first image asset with role"data"is used (falling back to the first image asset of any role).format (
str|None) – Explicit format string (e.g."png","nitf"). Required when reading from a stream. IfNoneand path is a string, the format is inferred from the file extension.
- Returns:
Read-only metadata for the resolved image asset. The
metadataattribute contains the full format-specific metadata dictionary (NITF subheader fields and TREs, or TIFF IFD tags).- Return type:
- Raises:
IOError – If the file does not exist or cannot be opened.
ValueError – If the specified asset key does not exist, if the dataset contains no image assets, or if path is a stream and format is not provided.
tiles¶
- aws.osml.io.tiles(path, tile_size, *, overlap=(0, 0), asset=None, bands=None, resolution_level=0, fill_value=0, format=None)¶
Iterate over fixed-size tiles of an image.
Yields
Tileobjects in row-major order (left-to-right, top-to-bottom). Edge tiles may be smaller than tile_size.The dataset is kept open for the lifetime of the generator. The caller should consume or close the generator to release the underlying file handle.
- Parameters:
path (
str|BinaryIO) – Path to the image file, or a file-like object containing image bytes.tile_size (
tuple[int,int]) – Tile dimensions as(width, height).overlap (
tuple[int,int]) – Horizontal and vertical overlap in pixels as(overlap_width, overlap_height). Defaults to(0, 0).asset (
str|None) – Explicit asset key to read. IfNone, the first image asset with role"data"is used (falling back to the first image asset of any role).bands (
list[int] |None) – Zero-based band indices to decode. IfNone, all bands are returned.resolution_level (
int) – Resolution level for block decoding.0is full resolution.fill_value (
int|float) – Value used to fill regions wherehas_block()returns False. Defaults to0.format (
str|None) – Explicit format string (e.g."png","nitf"). Required when reading from a stream. IfNoneand path is a string, the format is inferred from the file extension.
- Yields:
Tile – A tile of pixel data with position and grid coordinates.
- Raises:
IOError – If the file does not exist or cannot be opened.
ValueError – If tile_size has non-positive dimensions, if overlap is greater than or equal to tile_size in either dimension, if the specified asset key does not exist, or if path is a stream and format is not provided.
ImageInfo¶
- class aws.osml.io.ImageInfo(width, height, bands, dtype, block_size, num_resolution_levels, asset_key, metadata)¶
Read-only image metadata returned by
iminfo().- metadata¶
Format-specific metadata dictionary for the image segment. For NITF files this contains subheader fields (
IC,IGEOLO, etc.) and parsed TREs as nested dicts. For TIFF files this contains IFD tags keyed by numeric tag ID strings. The dictionary is a snapshot taken wheniminfo()is called — it is not a live reference.- Type: