cogeo-mosaic

9.1.0 verified Fri May 01 auth: no python

A Python library for creating and managing Cloud Optimized GeoTIFF (COG) mosaics using MosaicJSON format. Version 9.1.0 requires Python >=3.11 and supports rio-tiler 7+. Active development with frequent releases.

pip install cogeo-mosaic

Common errors

error ModuleNotFoundError: No module named 'cogeo_mosaic' ↓

cause Package not installed or installed in wrong environment.

fix

Run pip install cogeo-mosaic in the correct Python environment.

error AttributeError: module 'cogeo_mosaic' has no attribute 'MosaicJSON' ↓

cause Incorrect import path; MosaicJSON is in cogeo_mosaic.mosaic.

fix

Use from cogeo_mosaic.mosaic import MosaicJSON.

error TypeError: Cannot read properties of undefined (reading 'shape') / rio_tiler.errors.InvalidBandNames ↓

cause Using tile() without specifying assets or expression, or tile index out of bounds.

fix

Provide valid tile indices (x, y, z) and optionally set assets parameter.

error cogeo_mosaic.errors.InvalidMosaicError: 'mosaic' must be a valid MosaicJSON ↓

cause Passing a dictionary or invalid JSON to MosaicBackend constructor.

fix

Use MosaicJSON.from_urls() or MosaicJSON.from_features() to create a MosaicJSON object first.

Warnings

breaking Version 9.0.0 switched to rio-tiler 7.x and changed backend base class from `BaseMosaic` to `rio_tiler.mosaic.backend.BaseBackend`. Custom backends must update imports. ↓

fix Replace `from cogeo_mosaic.backends.base import BaseMosaic` with `from rio_tiler.mosaic.backend import BaseBackend`.

breaking Version 8.0.0 dropped support for Python <3.8 and rio-tiler <7.0. ↓

fix Upgrade Python to >=3.8 and rio-tiler to >=7.0.

gotcha When using S3 backends, credentials must be configured via environment variables or boto3 session. The library does not auto-configure from ~/.aws/config. ↓

fix Set AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, and AWS_SESSION_TOKEN (if needed) environment variables.

deprecated `from cogeo_mosaic.backends.base import BaseMosaic` is deprecated in 9.0.0 and removed in later versions. ↓

fix Use `from rio_tiler.mosaic.backend import BaseBackend` instead.

Imports

MosaicJSON

from cogeo_mosaic.mosaic import MosaicJSON

MosaicBackend

from cogeo_mosaic.backends import MosaicBackend

STACBackend

from cogeo_mosaic.backends.stac import STACBackend

Quickstart

Create and query a Cloud Optimized GeoTIFF mosaic using MosaicJSON.

from cogeo_mosaic.mosaic import MosaicJSON
from cogeo_mosaic.backends import MosaicBackend

# Create a simple mosaic from a list of COG URLs
cogs = [
    "https://example.com/cog1.tif",
    "https://example.com/cog2.tif",
]
mosaic = MosaicJSON.from_urls(cogs)

# Save to local file
with MosaicBackend("mosaic.json", mosaic_def=mosaic) as backend:
    backend.write()

# Open existing mosaic
with MosaicBackend("mosaic.json") as backend:
    tile = backend.tile(0, 0, 0)
    print(tile.shape)