Skip to content

API Reference⚓︎

These are the Python docs for cog3pio, for the Rust docs, see https://docs.rs/cog3pio.

DLPack⚓︎

cog3pio.CudaCogReader ⚓︎

Python class interface to a Cloud-optimized GeoTIFF reader (nvTIFF backend) that decodes to GPU (CUDA) memory.

Warning

This is an experimental feature only enabled on linux-x86_64 and linux-aarch64 wheel builds.

Parameters:

  • path ⚓︎

    (str) –

    The path to the file, or a url to a remote file.

  • device_id ⚓︎

    (int) –

    The CUDA GPU device number to decode the TIFF data on.

Returns:

  • reader ( CudaCogReader ) –

    A new CudaCogReader instance for decoding GeoTIFF files.

Raises:

  • ImportError –

    If nvTIFF is not installed. Please install it (e.g. via apt install nvtiff-cuda-13 or dnf install nvtiff-cuda-13) before using this class.

Examples:

Read a GeoTIFF from a HTTP url into a DLPack tensor:

>>> import cupy as cp
>>> from cog3pio import CudaCogReader
...
>>> cog = CudaCogReader(
...     path="https://github.com/rasterio/rasterio/raw/1.5.0/tests/data/RGBA.byte.tif"
...     device_id=0,
... )
>>> array: cp.ndarray = cp.from_dlpack(cog)
>>> array.shape
(2271752,)
>>> array.dtype
dtype('uint8')

Functions⚓︎

__dlpack__(stream=None, max_version=None, dl_device=None, copy=None) ⚓︎

Get image pixel data from GeoTIFF as a DLPack capsule.

Parameters:

  • stream ⚓︎
    (int | None, default: None ) –

    A Python integer representing a pointer to a stream, on devices that support streams. Device-specific values of stream for CUDA:

    • None: producer must assume the legacy default stream (default).
    • 1: the legacy default stream.
    • 2: the per-thread default stream.
    • > 2: stream number represented as a Python integer.
    • 0 is disallowed due to its ambiguity: 0 could mean either None, 1, or 2.
  • max_version ⚓︎
    (tuple[int, int] | None, default: None ) –

    The maximum DLPack version that the consumer (i.e., the caller of __dlpack__) supports, in the form of a 2-tuple (major, minor). This method may return a capsule of version max_version (recommended if it does support that), or of a different version. This means the consumer must verify the version even when max_version is passed.

  • dl_device ⚓︎
    (tuple[int, int] | None, default: None ) –

    The DLPack device type. Default is None, meaning the exported capsule should be on the same device as self is (i.e. CUDA). When specified, the format must be a 2-tuple, following that of the return value of array.__dlpack_device__(). If the device type cannot be handled by the producer, this function will raise BufferError.

  • copy ⚓︎
    (bool | None, default: None ) –

    Boolean indicating whether or not to copy the input. Currently only None is supported, meaning the function must reuse the existing memory buffer if possible and copy otherwise (copy is not actually implemented).

Returns:

  • tensor ( CapsuleType ) –

    1D tensor in row-major order containing the GeoTIFF pixel data.

Raises:

  • NotImplementedError –

    If either of these cases happen:

    • stream>2 is passed in, as only legacy default stream (1) or per-thread default stream (2) is supported for now.
    • max_version is incompatible with the DLPack major version in this library.
    • copy is set to a value other than None as Copy keyword argument behavior is not handled yet.
  • BufferError –

    If trying to decode to non-CUDA memory, i.e. when dl_device is not None, or set to a tuple other than (2, x). This error may also be raised if trying to decode to an unsupported version from the DLPack 0.x series.

__dlpack_device__() ⚓︎

Get device type and device ID in DLPack format.

Meant for use by from_dlpack().

Returns:

  • device ( (int, int) ) –

    A tuple (device_type, device_id) in DLPack format.

xy_coords() ⚓︎

Get list of x and y coordinates.

Determined based on an Affine transformation matrix built from the ModelPixelScaleTag and ModelTiepointTag TIFF tags. Note that non-zero rotation (set by ModelTransformationTag) is currently unsupported.

Returns:

  • coords ( (ndarray, ndarray) ) –

    A tuple (x_coords, y_coords) of numpy.ndarray objects representing the GeoTIFF's x- and y-coordinates.

cog3pio.CogReader ⚓︎

Python class interface to a Cloud-optimized GeoTIFF reader (image-tiff backend).

Parameters:

  • path ⚓︎

    (str) –

    The path to the file, or a url to a remote file.

Returns:

  • reader ( CogReader ) –

    A new CogReader instance for decoding GeoTIFF files.

Examples:

Read a GeoTIFF from a HTTP url into a DLPack tensor:

>>> import numpy as np
>>> from cog3pio import CogReader
...
>>> cog = CogReader(
...     path="https://github.com/rasterio/rasterio/raw/1.5.0/tests/data/RGBA.uint16.tif"
... )
>>> array: np.ndarray = np.from_dlpack(cog)
>>> array.shape
(4, 411, 634)
>>> array.dtype
dtype('uint16')
Source code in cog3pio/__init__.py 
15
__all__ = cog3pio.__all__

Functions⚓︎

__dlpack__(stream=None) ⚓︎

Get image pixel data from GeoTIFF as a DLPack capsule

Returns:

  • tensor ( CapsuleType ) –

    3D tensor of shape (band, height, width) containing the GeoTIFF pixel data.

Raises:

  • NotImplementedError –

    If stream is not None, as only decoding to the CPU is supported.

__dlpack_device__() staticmethod ⚓︎

Get device type and device ID in DLPack format.

Meant for use by from_dlpack().

Returns:

  • device ( (int, int) ) –

    A tuple (device_type, device_id) in DLPack format.

xy_coords() ⚓︎

Get list of x and y coordinates.

Determined based on an Affine transformation matrix built from the ModelPixelScaleTag and ModelTiepointTag TIFF tags. Note that non-zero rotation (set by ModelTransformationTag) is currently unsupported.

Returns:

  • coords ( (ndarray, ndarray) ) –

    A tuple (x_coords, y_coords) of numpy.ndarray objects representing the GeoTIFF's x- and y-coordinates.

NumPy⚓︎

cog3pio.read_geotiff(path) builtin ⚓︎

Read a GeoTIFF file from a path on disk or a url into an ndarray.

Parameters:

  • path ⚓︎

    (str) –

    The path to the file, or a url to a remote file.

Returns:

  • array ( ndarray ) –

    3D array of shape (band, height, width) containing the GeoTIFF pixel data.

Raises:

  • ValueError –

    If a TIFF which has a non-float32 dtype is passed in. Please use cog3pio.CogReader for reading TIFFs with other dtypes (e.g. uint16).

Examples:

Read a GeoTIFF from a HTTP url into a numpy.ndarray:

>>> from cog3pio import read_geotiff
...
>>> array = read_geotiff("https://github.com/pka/georaster/raw/v0.2.0/data/tiff/float32.tif")
>>> array.shape
(1, 20, 20)