rio-cogeo Documentation

rio-cogeo is a plugin for Rasterio designed to facilitate the creation and validation of Cloud Optimized GeoTIFF (COG or COGEO) files.

While it adheres to the official COG specifications, it enforces specific features by default:

• Internal overviews: Can be removed using the --overview-level 0 option.
• Internal tiles: Default profiles use 512x512 internal tiles.

The rio-cogeo module extends the rasterio (rio) CLI by adding a cogeo sub-command. This sub-command provides three primary operations for working with Cloud Optimized GeoTIFFs (COGs):

1. create: Generate a COG from an input raster.
2. info: Inspect metadata and properties of a raster dataset.
3. validate: Check if a COG file adheres to Cloud Optimized GeoTIFF standards.

$ rio cogeo --help

Use the --web-optimized option to create a Cloud Optimized GeoTIFF (COG) that is friendly to web-tiling services. This option aligns the dataset bounds and internal tiles with the Web Mercator grid (or a specified TMS grid) and ensures that raw data and overview resolutions match TMS zoom level resolutions.

Important: Because this process creates a larger file due to padding tiles on the sides, ensure your input dataset contains a nodata value, an alpha band, or an internal mask. If none are present, the original data will be surrounded by black (0) data in the output.

rio cogeo input.tif output_web_optimized.tif --web-optimized

Use rio cogeo validate to check if a GeoTIFF conforms to the COG specification. The tool will report warnings (e.g., missing overviews) or errors (e.g., not tiled, incorrect IFD offsets) and explicitly state if the file is or is not a valid COG.

$ rio cogeo validate <input_file.tif>

For specific data types (like RGB/Uint8), you can use more efficient compression algorithms via the -p (profile) flag to significantly reduce file size.

• JPEG: Use -p jpeg for lossy compression. This is ideal for visual-only COGs and provides massive size reductions.
• DEFLATE: The default compression used by rio-cogeo.

$ rio cogeo create HYP_50M_SR.tif HYP_50M_SR_COG_jpeg.tif -p jpeg

By default, rio-cogeo creates datasets with a 512x512 internal tile size. You can customize this by passing --co BLOCKXSIZE and --co BLOCKYSIZE options.

When creating a Web-Optimized COG, proper alignment of tiles and bounds with the mercator grid reduces the number of GET requests a dynamic tiling service must perform to generate map tiles.

rio cogeo input.tif output.tif --co BLOCKXSIZE=64 --co BLOCKYSIZE=64

You can install rio-cogeo using pip. It is recommended to upgrade pip first to ensure a smooth installation.

$ pip install -U pip
$ pip install rio-cogeo

For Byte or Uint16 datasets, you can use the --add-mask option to replace a nodata value or an Alpha band with an internal bit mask. This is supported by most GDAL-based backends.

Note: If your input dataset has an alpha band and you are adding a mask, you must use the bidx option to remove the alpha band from the output.

Warning: Do not use internal nodata values with lossy compression formats like webp or jpeg. Instead, use internal masking or an alpha band (if using webp).

# Replace the alpha band by an internal mask
rio cogeo mydataset_withalpha.tif mydataset_withmask.tif --cog-profile raw --add-mask --bidx 1,2,3

Use the rio cogeo info command to inspect a GeoTIFF's properties. To identify if a file is a valid Cloud Optimized GeoTIFF (COG), check the following in the output:

• Tiled: Must be True.
• BlockSize: Should represent internal tiles (e.g., 512x512) rather than full row dimensions (e.g., 10800x1).
• IFD (Image File Directory): A COG should have multiple IFDs representing different overview levels (decimation).

$ rio cogeo info <input_file.tif>

To use the rio cogeo CLI tools, install the package via pip. Requires Python 3.7+.

$ pip install rio-cogeo

Convert a standard GeoTIFF into a Cloud Optimized GeoTIFF using rio cogeo create.

By default, this command:

• Creates internal tiles with a 512x512 blocksize.
• Adds internal overviews.
• Uses DEFLATE compression.

Syntax: rio cogeo create <input_file.tif> <output_file.tif>

$ rio cogeo create HYP_50M_SR.tif HYP_50M_SR_COG.tif