Skip to content

GeoTIFF

async_geotiff.GeoTIFF dataclass

A class representing a GeoTIFF image.

block_shapes property 

block_shapes: tuple[tuple[int, int], ...]

Block shapes for each band. Each shape is (height, width).

bounds property 

bounds: BoundingBox

Return the bounds of the dataset in the units of its CRS.

Returns:

  • BoundingBox ( BoundingBox ) –

    The bounding box of the dataset.

colorinterp property 

colorinterp: tuple[ColorInterp, ...]

The color interpretation of each band in index order.

colormap property 

colormap: Colormap | None

Return the Colormap stored in the file, if any.

Returns:

  • Colormap | None –

    A Colormap instance if the dataset has a colormap, else None.

compression property 

compression: Compression | None

The compression algorithm used for the dataset.

Returns None if the compression is not recognized.

count property 

count: int

The number of raster bands in the full image.

crs property 

crs: CRS

The dataset's coordinate reference system.

dtype property 

dtype: dtype | None

The NumPy data type of the image.

Returns None if the data type is unknown/not supported.

height property 

height: int

The height (number of rows) of the full image.

ifd property 

ifd: ImageFileDirectory

Access to the underlying ImageFileDirectory of the full-resolution image.

Warning

This is for advanced users who need access to the underlying TIFF object. Most users should only need to use async-geotiff's higher-level APIs.

interleaving property 

interleaving: Interleaving

The interleaving scheme of the dataset.

mask_ifd class-attribute instance-attribute 

mask_ifd: ImageFileDirectory | None = None

Access to the underlying ImageFileDirectory for the mask associated with the full-resolution image, if any.

Warning

This is for advanced users who need access to the underlying TIFF object. Most users should only need to use async-geotiff's higher-level APIs.

nodata property 

nodata: float | None

The dataset's single nodata value.

offsets property 

offsets: tuple[float, ...]

The offset for each band, if any.

overviews property 

overviews: list[Overview]

A list of overview levels for the dataset.

Overviews are reduced-resolution versions of the main image used for faster rendering at lower zoom levels.

This list of overviews is ordered from finest to coarsest resolution. The first element of the list is the highest-resolution after the base image.

photometric property 

photometric: PhotometricInterpretation | None

The photometric interpretation of the dataset.

Returns None if the photometric interpretation is not recognized.

res property 

res: tuple[float, float]

Return the (width, height) of pixels in the units of its CRS.

scales property 

scales: tuple[float, ...]

The scale for each band, if any.

The keys of the mapping are 1-based band indices to match GDAL's convention.

shape property 

shape: tuple[int, int]

Get the shape (height, width) of the full image.

stored_stats property 

stored_stats: Mapping[int, BandStatistics] | None

The pre-existing statistics for each GeoTIFF band, if available.

These statistics are extracted from the GDALMetadata TIFF tag and are never computed on demand here.

The keys of the mapping are 1-based band indices to match GDAL's convention.

tiff instance-attribute 

tiff: TIFF

The underlying async-tiff TIFF instance that we wrap.

Warning

This is for advanced users who need access to the underlying TIFF object. Most users should only need to use async-geotiff's higher-level APIs.

tile_count property 

tile_count: tuple[int, int]

The number of tiles in the x and y directions.

tile_height property 

tile_height: int

The height in pixels per tile of the image.

tile_width property 

tile_width: int

The width in pixels per tile of the image.

transform property 

transform: Affine

Return the dataset's georeferencing transformation matrix.

This transform maps pixel row/column coordinates to coordinates in the dataset's CRS.

width property 

width: int

The width (number of columns) of the full image.

__init__ 

__init__(tiff: TIFF) -> None

Create a GeoTIFF from an existing TIFF instance.

fetch_tile async 

fetch_tile(x: int, y: int, *, boundless: bool = True) -> Tile

Fetch a single tile from the GeoTIFF.

Parameters:

  • x (int) –

    The x-coordinate of the tile.

  • y (int) –

    The y-coordinate of the tile.

Other Parameters:

  • boundless (bool) –

    If False, clip edge tiles to the image bounds. Defaults to True.

Returns:

  • Tile –

    A Tile object containing the fetched tile data.

fetch_tiles async 

fetch_tiles(
    xy: Sequence[tuple[int, int]], *, boundless: bool = True
) -> list[Tile]

Fetch multiple tiles from this overview.

The benefit of using this method over multiple calls to fetch_tile is that fetch_tiles will coalesce requests for tiles that are stored contiguously on disk. The exact behavior depends on how the underlying store passed to GeoTIFF.open implements get_ranges_async.

Parameters:

Other Parameters:

  • boundless (bool) –

    If False, clip edge tiles to the image bounds.

index 

index(
    x: float, y: float, op: Callable[[float], int] = floor
) -> tuple[int, int]

Get the (row, col) index of the pixel containing (x, y).

Parameters:

  • x (float) –

    x value in coordinate reference system.

  • y (float) –

    y value in coordinate reference system.

  • op (Callable[[float], int], default: floor ) –

    Function to convert fractional pixels to whole numbers (floor, ceiling, round). Defaults to math.floor.

Returns:

open async classmethod 

open(
    path: str, *, store: Store, prefetch: int = 32768, multiplier: float = 2.0
) -> Self

Open a new GeoTIFF.

Parameters:

  • path (str) –

    The path within the store to read from.

  • store (Store) –

    The backend to use for data fetching. Most of the time, you'll want to use a store from obstore, such as its S3Store, GCSStore, or AzureStore. However, this can be any object that implements the interface required by Store.

  • prefetch (int, default: 32768 ) –

    The number of initial bytes to read up front.

  • multiplier (float, default: 2.0 ) –

    The multiplier to use for readahead size growth. Must be greater than 1.0. For example, for a value of 2.0, the first metadata read will be of size prefetch, and then the next read will be of size prefetch * 2.

Returns:

  • Self –

    A GeoTIFF instance.

read async 

read(*, window: Window | None = None) -> RasterArray

Read pixel data for a window region.

This method fetches all tiles that intersect the given window and stitches them together, returning only the pixels within the window.

Parameters:

  • window (Window | None, default: None ) –

    A Window object defining the pixel region to read. If None, the entire image is read.

Returns:

  • RasterArray –

    A RasterArray containing the pixel data for the requested window.

Raises:

  • WindowError –

    If the window extends outside the image bounds.

xy 

xy(
    row: int,
    col: int,
    offset: Literal["center", "ul", "ur", "ll", "lr"] = "center",
) -> tuple[float, float]

Get the coordinates (x, y) of a pixel at (row, col).

The pixel's center is returned by default, but a corner can be returned by setting offset to one of "ul", "ur", "ll", "lr".

Parameters:

  • row (int) –

    Pixel row.

  • col (int) –

    Pixel column.

  • offset (Literal['center', 'ul', 'ur', 'll', 'lr'], default: 'center' ) –

    Determines if the returned coordinates are for the center of the pixel or for a corner.

Returns:

async_geotiff.Store

Bases: GetRangeAsync, GetRangesAsync, Protocol

Supported input to store param of GeoTIFF.open.

Anything that implements GetRangeAsync and GetRangesAsync can be used as an input to the TIFF reader.