Skip to main content

Asynchronous cogeotiff reader

Project description

aiocogeo CircleCIcodecov

Installation

pip install aiocogeo

# With S3 filesystem
pip install aiocogeo[s3]

Usage

COGs are opened using the COGReader asynchronous context manager:

from aiocogeo import COGReader

async with COGReader("http://cog.tif") as cog:
    ...

Several filesystems are supported:

  • HTTP/HTTPS (http://, https://)
  • S3 (s3://)
  • File (/)

Metadata

Generating a rasterio-style profile for the COG:

async with COGReader("https://async-cog-reader-test-data.s3.amazonaws.com/lzw_cog.tif") as cog:
    print(cog.profile)

>>> {'driver': 'GTiff', 'width': 10280, 'height': 12190, 'count': 3, 'dtype': 'uint8', 'transform': Affine(0.6, 0.0, 367188.0,
       0.0, -0.6, 3777102.0), 'blockxsize': 512, 'blockysize': 512, 'compress': 'lzw', 'interleave': 'pixel', 'crs': 'EPSG:26911', 'tiled': True, 'photometric': 'rgb'}

Lower Level Metadata

A COG is composed of several IFDs, each with many TIFF tags:

from aiocogeo.ifd import IFD
from aiocogeo.tag import Tag

async with COGReader("https://async-cog-reader-test-data.s3.amazonaws.com/lzw_cog.tif") as cog:
    for ifd in cog:
        assert isinstance(ifd, IFD)
        for tag in ifd:
            assert isinstance(tag, Tag)

Each IFD contains more granular metadata about the image than what is included in the profile. For example, finding the tilesize for each IFD:

async with COGReader("https://async-cog-reader-test-data.s3.amazonaws.com/lzw_cog.tif") as cog:
    for ifd in cog:
        print(ifd.TileWidth.value, ifd.TileHeight.value)

>>> 512 512
    128 128
    128 128
    128 128
    128 128
    128 128

More advanced use cases may need access to tag-level metadata:

async with COGReader("https://async-cog-reader-test-data.s3.amazonaws.com/lzw_cog.tif") as cog:
    first_ifd = cog.ifds[0]
    assert first_ifd.tag_count == 24

    for tag in first_ifd:
        print(tag)

>>> Tag(code=258, name='BitsPerSample', tag_type=TagType(format='H', size=2), count=3, length=6, value=(8, 8, 8))
    Tag(code=259, name='Compression', tag_type=TagType(format='H', size=2), count=1, length=2, value=5)
    Tag(code=257, name='ImageHeight', tag_type=TagType(format='H', size=2), count=1, length=2, value=12190)
    Tag(code=256, name='ImageWidth', tag_type=TagType(format='H', size=2), count=1, length=2, value=10280)
    ...

Image Data

The reader also has methods for reading internal image tiles and performing partial reads. Currently only jpeg, lzw, deflate, packbits, and webp compressions are supported.

Image Tiles

Reading the top left tile of an image at native resolution:

async with COGReader("https://async-cog-reader-test-data.s3.amazonaws.com/webp_cog.tif") as cog:
    x = y = z = 0
    tile = await cog.get_tile(x, y, z)

    ifd = cog.ifds[z]
    assert tile.shape == (ifd.bands, ifd.TileHeight.value, ifd.TileWidth.value)

Partial Read

You can read a portion of the image by specifying a bounding box in the native crs of the image and an output shape:

async with COGReader("https://async-cog-reader-test-data.s3.amazonaws.com/webp_cog.tif") as cog:
    assert cog.epsg == 26911
    partial_data = await cog.read(bounds=(368461,3770591,368796,3770921), shape=(512,512))

Internal Masks

If the COG has an internal mask, the returned array will be a masked array:

import numpy as np

async with COGReader("https://async-cog-reader-test-data.s3.amazonaws.com/naip_image_masked.tif") as cog:
    assert cog.is_masked

    tile = await cog.get_tile(0,0,0)
    assert np.ma.is_masked(tile)

Configuration

Configuration options are exposed through environment variables:

  • INGESTED_BYTES_AT_OPEN - defines the number of bytes in the first GET request at file opening (defaults to 16KB)
  • HEADER_CHUNK_SIZE - chunk size used to read header (defaults to 16KB)
  • ENABLE_BLOCK_CACHE - determines if image blocks are cached in memory (defaults to TRUE)
  • ENABLE_HEADER_CACHE - determines if COG headers are cached in memory (defaults to TRUE)
  • HTTP_MERGE_CONSECUTIVE_RANGES - determines if consecutive ranges are merged into a single request (defaults to FALSE)
  • BOUNDLESS_READ - determines if internal tiles outside the bounds of the IFD are read (defaults to TRUE)
  • BOUNDLESS_READ_FILL_VALUE - determines the value used to fill boundless reads (defaults to 0)
  • LOG_LEVEL - determines the log level used by the package (defaults to ERROR)
  • VERBOSE_LOGS - enables verbose logging, designed for use when LOG_LEVEL=DEBUG (defaults to FALSE)
  • AWS_REQUEST_PAYER - set to requester to enable reading from S3 RequesterPays buckets.

Refer to aiocogeo/config.py for more details about configuration options.

CLI

$ aiocogeo --help
Usage: aiocogeo [OPTIONS] COMMAND [ARGS]...

Options:
  --install-completion [bash|zsh|fish|powershell|pwsh]
                                  Install completion for the specified shell.
  --show-completion [bash|zsh|fish|powershell|pwsh]
                                  Show completion for the specified shell, to
                                  copy it or customize the installation.

  --help                          Show this message and exit.

Commands:
  create-tms  Create OGC TileMatrixSet.
  info        Read COG metadata.

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

aiocogeo-0.3.0.tar.gz (26.2 kB view details)

Uploaded Source

Built Distribution

aiocogeo-0.3.0-py3-none-any.whl (28.7 kB view details)

Uploaded Python 3

File details

Details for the file aiocogeo-0.3.0.tar.gz.

File metadata

  • Download URL: aiocogeo-0.3.0.tar.gz
  • Upload date:
  • Size: 26.2 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/3.2.0 pkginfo/1.5.0.1 requests/2.22.0 setuptools/46.0.0.post20200309 requests-toolbelt/0.9.1 tqdm/4.42.1 CPython/3.7.6

File hashes

Hashes for aiocogeo-0.3.0.tar.gz
Algorithm Hash digest
SHA256 bc327cb78f9906cb94a5fb08ab9486bbddf649e15fc4839b72a96ac76368131b
MD5 4e3b926ba1d07997fd4866938133bf57
BLAKE2b-256 d7a957bb107272c09dd275332e83076523e9d6bcf8d5d182f30affd37714af6e

See more details on using hashes here.

File details

Details for the file aiocogeo-0.3.0-py3-none-any.whl.

File metadata

  • Download URL: aiocogeo-0.3.0-py3-none-any.whl
  • Upload date:
  • Size: 28.7 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/3.2.0 pkginfo/1.5.0.1 requests/2.22.0 setuptools/46.0.0.post20200309 requests-toolbelt/0.9.1 tqdm/4.42.1 CPython/3.7.6

File hashes

Hashes for aiocogeo-0.3.0-py3-none-any.whl
Algorithm Hash digest
SHA256 744bee72304595340bf4d8a8fd399c0d0068940e0aedb1d3f57b96340be5ab6a
MD5 b538067786ce8ebab831f169cf3813da
BLAKE2b-256 96314af752f901c98f94b0c3b313acbf859732e072bc7086617fe837c6a676cc

See more details on using hashes here.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page