Package: aiocogeo
aiocogeoInstallationpip install aiocogeo

# With S3 filesystem
pip install aiocogeo[s3]UsageCOGs are opened using theCOGReaderasynchronous context manager:fromaiocogeoimportCOGReaderasyncwithCOGReader("http://cog.tif")ascog:...Several filesystems are supported:HTTP/HTTPS(http://,https://)S3(s3://)File(/)MetadataGenerating arasterio-style profilefor the COG:asyncwithCOGReader("https://async-cog-reader-test-data.s3.amazonaws.com/lzw_cog.tif")ascog: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 MetadataA COG is composed of several IFDs, each with many TIFF tags:fromaiocogeo.ifdimportIFDfromaiocogeo.tagimportTagasyncwithCOGReader("https://async-cog-reader-test-data.s3.amazonaws.com/lzw_cog.tif")ascog:forifdincog:assertisinstance(ifd,IFD)fortaginifd:assertisinstance(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:asyncwithCOGReader("https://async-cog-reader-test-data.s3.amazonaws.com/lzw_cog.tif")ascog:forifdincog:print(ifd.TileWidth.value,ifd.TileHeight.value)>>>512512128128128128128128128128128128More advanced use cases may need access to tag-level metadata:asyncwithCOGReader("https://async-cog-reader-test-data.s3.amazonaws.com/lzw_cog.tif")ascog:first_ifd=cog.ifds[0]assertfirst_ifd.tag_count==24fortaginfirst_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 DataThe 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 TilesReading the top left tile of an image at native resolution:asyncwithCOGReader("https://async-cog-reader-test-data.s3.amazonaws.com/webp_cog.tif")ascog:x=y=z=0tile=awaitcog.get_tile(x,y,z)ifd=cog.ifds[z]asserttile.shape==(ifd.bands,ifd.TileHeight.value,ifd.TileWidth.value)Partial ReadYou can read a portion of the image by specifying a bounding box in the native crs of the image and an output shape:asyncwithCOGReader("https://async-cog-reader-test-data.s3.amazonaws.com/webp_cog.tif")ascog:assertcog.epsg==26911partial_data=awaitcog.read(bounds=(368461,3770591,368796,3770921),shape=(512,512))Internal MasksIf the COG has an internal mask, the returned array will be a masked array:importnumpyasnpasyncwithCOGReader("https://async-cog-reader-test-data.s3.amazonaws.com/naip_image_masked.tif")ascog:assertcog.is_maskedtile=awaitcog.get_tile(0,0,0)assertnp.ma.is_masked(tile)ConfigurationConfiguration 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 whenLOG_LEVEL=DEBUG(defaults to FALSE)AWS_REQUEST_PAYER- set torequesterto enable reading from S3 RequesterPays buckets.Refer toaiocogeo/config.pyfor 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.