API Reference

DLPack¶

class cog3pio.CogReader(path)

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 (cog3pio.CogReader) – A new CogReader instance for decoding GeoTIFF files.

__dlpack__()

Get image pixel data from GeoTIFF as a DLPack capsule

Returns

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

static __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 ((np.ndarray, np.ndarray)) – A tuple (x_coords, y_coords) of np.ndarray objects representing the GeoTIFF’s x- and y-coordinates.

class cog3pio.CudaCogReader(path)

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

Parameters

path (str) – The path to the file, or a url to a remote file.

Returns

reader (cog3pio.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-12 or dnf install nvtiff-cuda-12) before using this class.

__dlpack__(stream=None, max_version=None, **kwargs)

Get image pixel data from GeoTIFF as a DLPack capsule

Parameters

• stream (int | 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) – 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.

Returns

tensor (PyCapsule) – 1D tensor in row-major order containing the GeoTIFF pixel data.

__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.

Xarray¶

class cog3pio.xarray_backend.Cog3pioBackendEntrypoint

Xarray backend to read GeoTIFF files using ‘cog3pio’ engine.

NumPy¶

cog3pio.read_geotiff(path)

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 (np.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).