{"id":7677,"library":"rio-cogeo","title":"Cloud Optimized GeoTIFF (COG) Creation Plugin for Rasterio","description":"rio-cogeo is a Rasterio plugin that streamlines the creation and validation of Cloud Optimized GeoTIFF (COG) files. It intelligently handles critical COG specifications, including internal tiling, overview generation, and metadata ordering, ensuring geospatial data is optimized for efficient cloud storage and rapid web-based access. The library is actively maintained with consistent releases, serving as a vital tool in modern geospatial data pipelines.","status":"active","version":"7.0.2","language":"en","source_language":"en","source_url":"https://github.com/cogeotiff/rio-cogeo","tags":["geospatial","gis","geotiff","cog","raster","cloud-native","rasterio-plugin"],"install":[{"cmd":"pip install rio-cogeo","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"rio-cogeo is a plugin for Rasterio, extending its command-line interface and API for COG functionalities.","package":"rasterio","optional":false},{"reason":"Underpins Rasterio and rio-cogeo for all geospatial data operations. GDAL >= 2.3 is recommended.","package":"GDAL","optional":false},{"reason":"Used for tile matrix set operations and web-optimized COG creation.","package":"morecantile","optional":false}],"imports":[{"note":"Primary function for programmatic COG creation.","symbol":"cog_translate","correct":"from rio_cogeo.cogeo import cog_translate"},{"note":"Used to access predefined COG profiles for compression and tiling options.","symbol":"cog_profiles","correct":"from rio_cogeo.profiles import cog_profiles"},{"note":"For programmatic validation of COG files.","symbol":"cog_validate","correct":"from rio_cogeo.cogeo import cog_validate"}],"quickstart":{"code":"# Create a dummy GeoTIFF for demonstration\nimport rasterio\nimport numpy as np\nfrom rasterio.transform import from_bounds\n\nwidth, height = 1000, 1000\ntransform = from_bounds(-10, 40, 10, 60, width, height)\n\nwith rasterio.open(\n    'input.tif',\n    'w',\n    driver='GTiff',\n    height=height,\n    width=width,\n    count=1,\n    dtype=np.uint8,\n    crs='EPSG:4326',\n    transform=transform,\n) as dst:\n    dst.write(np.zeros((height, width), dtype=np.uint8), 1)\n\nprint(\"Created input.tif\")\n\n# --- Using rio-cogeo CLI ---\n# Create a COG with DEFLATE compression (default profile)\n# This command is run from the shell, not directly in Python\n# import os\n# os.system(\"rio cogeo create input.tif output_deflate.tif\")\n# print(\"Created output_deflate.tif\")\n\n# Create a COG with JPEG profile, add internal mask, and select first 3 bands\n# os.system(\"rio cogeo create input.tif output_jpeg.tif -b 1 --add-mask --cog-profile jpeg\")\n# print(\"Created output_jpeg.tif\")\n\n# Validate a COG\n# os.system(\"rio cogeo validate output_deflate.tif\")\n# print(\"Validated output_deflate.tif\")\n\n# Example of programmatic COG creation\nfrom rasterio.io import MemoryFile\nfrom rio_cogeo.cogeo import cog_translate\nfrom rio_cogeo.profiles import cog_profiles\n\n# Use a local file path for input\nsrc_path = 'input.tif'\noutput_path_programmatic = 'output_programmatic.tif'\n\ndst_profile = cog_profiles.get(\"deflate\")\n\nwith rasterio.open(src_path) as src_dataset:\n    cog_translate(\n        src_path,\n        output_path_programmatic,\n        dst_profile,\n        config=dict(GDAL_NUM_THREADS='ALL_CPUS', GDAL_TIFF_OVR_BLOCKSIZE='128'),\n        overview_resampling='nearest',\n        web_optimized=False,\n        in_memory=False,\n        quiet=True,\n        # For real usage, consider `dst_kwargs` for profile overrides or `resampling` for overviews\n    )\nprint(f\"Created {output_path_programmatic} programmatically.\")\n\n# Clean up dummy files\nimport os\nos.remove('input.tif')\nos.remove('output_programmatic.tif')\n# os.remove('output_deflate.tif') # Uncomment if running CLI examples\n# os.remove('output_jpeg.tif')   # Uncomment if running CLI examples\n","lang":"python","description":"rio-cogeo can be used via its command-line interface (CLI) or directly through its Python API. The CLI (prefixed with `rio cogeo`) is often the simplest for common tasks like creating or validating COGs. The Python API offers more granular control for integration into custom scripts. This example demonstrates both a dummy file creation for testing and a programmatic COG translation, showing how to leverage `cog_translate` and `cog_profiles`."},"warnings":[{"fix":"Upgrade Python to version 3.11 or later. (e.g., `conda install python=3.11` or rebuild virtual environment).","message":"Python 3.10 support was removed in rio-cogeo version 7.0.0. Users on Python 3.10 must upgrade their Python environment to 3.11 or newer.","severity":"breaking","affected_versions":">=7.0.0"},{"fix":"For lossy compressed COGs, prefer using the `--add-mask` option to create an internal bitmask, or ensure your input has an alpha band. Avoid `nodata` for such profiles where possible, or use lossless compression like `deflate`.","message":"Using internal nodata values with lossy compression profiles (e.g., `jpeg`, `webp`) is generally not recommended as it can lead to unexpected visual artifacts or data loss around nodata regions. Internal masking or using an alpha band is often a more robust approach for lossy formats.","severity":"gotcha","affected_versions":"All"},{"fix":"Ensure your input dataset has a proper nodata value, an alpha band, or use the `--add-mask` option when creating web-optimized COGs to prevent unintended padding with zero values.","message":"When using the `--web-optimized` option without a nodata value, an alpha band, or an internal mask in the input dataset, the output COG may contain padded areas filled with black (0) data. This can lead to larger file sizes than expected.","severity":"gotcha","affected_versions":"All"},{"fix":"Verify `ColorInterp` metadata in your source TIFFs (e.g., using `gdalinfo`). If using lossy compression, compare pixel values at the native resolution. For exact value preservation, use lossless compression profiles like `deflate` or `zstd`.","message":"The `rio_cogeo.cog_translate` function or `rio cogeo create` CLI command might produce output raster pixel values that differ from the input if `ColorInterp` metadata is incorrectly defined or if lossy compression is applied and comparisons are made at overview resolutions (which are resampled).","severity":"gotcha","affected_versions":"All"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"For such small rasters, consider using `rasterio.shutil.copy` directly without `rio-cogeo`, or if using `rio-cogeo` via the API, manually set a smaller `blocksize` in `dst_profile['blockxsize']` and `dst_profile['blockysize']` (e.g., 256 or 128) for the output.","cause":"This error typically occurs with very small input GeoTIFFs (e.g., some JPEG2000 preview files) where the internal block size defined in the source raster is larger than the actual band dimensions (width or height).","error":"ERROR 1: blocksize exceeds raster width (or height)"},{"fix":"Ensure both `rasterio` and `rio-cogeo` are installed in your active Python environment: `pip install rasterio rio-cogeo`. If in a virtual environment, ensure it is activated.","cause":"The `rio` command-line interface is part of `rasterio`, and `cogeo` is a subcommand added by `rio-cogeo`. This error indicates that either `rasterio` or `rio-cogeo` is not installed, or the environment's `PATH` does not include the location of the `rio` executable.","error":"Command 'rio cogeo' not found (or similar CLI execution error)"},{"fix":"If working with large files, ensure you have ample free disk space in the output directory. If using `in_memory=True` (programmatically), you may be running out of RAM. Try setting `in_memory=False` or reducing the number of overview levels.","cause":"This error occurs when `rio-cogeo` attempts to create internal overviews or otherwise reorganize the GeoTIFF structure, but the output file system (or memory if processing in-memory) does not have sufficient contiguous space for the operation.","error":"ERROR 1: Freezing Dataset, not enough space for overviews."}]}