zarr2cog - Zarr to Cloud-Optimized GeoTIFF Converter
Convert Zarr arrays to Cloud-Optimized GeoTIFF (COG) format with advanced compression and performance settings. A companion to nc2cog with the same command-line interface, for Zarr instead of netCDF.
🚀 Features
- Format Conversion: Convert Zarr arrays to Cloud-Optimized GeoTIFF (COG)
- Batch Processing: Process entire directories of zarr stores
- Multi-array Stores: Convert each array of a zarr group to a separate COG
- Multidimensional Arrays: Leading dimensions (e.g. time) become bands
- Advanced Compression: deflate, lzw, and jpeg with configurable levels
- Pyramid Structure: Customizable overview (pyramid) levels
- Projection Transformation: Reproject via
--src-proj/--dst-proj - Resume Capability: Resume interrupted conversions
- Rich Metadata: 18 metadata fields written to each output COG
📋 Requirements
- Python 3.9+
- GDAL 3.8+ with Python bindings
🛠️ Installation
pip install zarr2cog
System GDAL is required:
- macOS:
brew install gdal - Ubuntu:
sudo apt-get install gdal-bin libgdal-dev - Windows: Use OSGeo4W installer
🚀 Quick Start
Convert a single 2D zarr array:
zarr2cog input.zarr output/
Convert a multi-array zarr group (one COG per array):
zarr2cog dataset.zarr output/
# Produces: output/PRE.tif, output/REF.tif
Convert only specific arrays:
zarr2cog --variables PRE,REF dataset.zarr output/
Convert a single array to a specific output file:
zarr2cog --variables PRE dataset.zarr output/PRE.tif
Batch-convert a directory of zarr stores:
zarr2cog input_dir/ output/
⚙️ Command Line Options
| Option | Default | Description |
|---|---|---|
--config / -c |
— | Path to YAML configuration file |
--compression |
deflate | deflate / lzw / jpeg |
--zlevel |
6 | deflate compression level (1-9) |
--block-size |
— | Deprecated alias for --tile-size |
--resampling |
nearest | Overview resampling method |
--tile-size |
512 | COG tile size |
--overview-levels |
2,4,8,16 | Overview levels (comma-separated) |
--overwrite |
— | Overwrite existing outputs |
--dry-run |
— | Show what would be processed |
--verbose / -v |
— | Verbose logging |
--resume |
— | Resume from last processed store |
--threads |
1 | Parallel processing threads |
--src-proj |
— | Source projection (EPSG:XXXX) |
--dst-proj |
— | Target projection (EPSG:XXXX) |
--variables |
— | Arrays to convert (comma-separated) |
--metadata-source |
— | Custom source name for metadata |
--version / -V |
— | Show version and exit |
📁 Output Path Rules
| Output path ends with | Behavior |
|---|---|
.tif |
Output to the specified file directly (single array) |
/ or no extension |
Output to a directory (one file per array) |
🔧 Configuration File
compression: "deflate"
zlevel: 6
tile_size: [512, 512]
overviews:
resampling: "nearest"
levels: [2, 4, 8, 16]
metadata:
source: ""
offset: 0.0
scale: 1.0
unit: ""
overwrite: false
skip_errors: true
Use with: zarr2cog --config config.yaml input.zarr output/
📋 COG Metadata
Each output COG contains metadata fields including Coordinate System,
Band Count, Data Type, Resolution, Extent, Creation Time, Source,
Compression, startX/startY/endX/endY, min/max, offset/scale,
unit, and NoData. The Source and unit fields are auto-detected from the
zarr .zattrs (source/platform/institution and units/unit) with
config/CLI overrides available.
📄 License
MIT License
1 maintainer
Release files for zarr2cog 0.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| zarr2cog-0.1.0.tar.gz | 21.1 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| zarr2cog-0.1.0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 40.8 kB
Release files / zarr2cog-0.1.0.tar.gz
| Download URL | zarr2cog-0.1.0.tar.gz |
|---|---|
| Size | 21.1 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
318c4466037108ca57fb067fc15bff0eb1505ab98c5e0fa72e319a548152b1e6
|
|
BLAKE2b-256 checksum How to use checksums |
b53241e7d386c8b1dacc322fbdc5f53475c9e9f6a9da8919224a9ee67078b0cc
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.11.19 {"installer":{"name":"uv","version":"0.11.19","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Release files / zarr2cog-0.1.0-py3-none-any.whl
| Download URL | zarr2cog-0.1.0-py3-none-any.whl |
|---|---|
| Size | 19.7 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
0c4339b5ee4a998c507f7489a495b931766b6e1020fef4ddca71ac4499e05dc6
|
|
BLAKE2b-256 checksum How to use checksums |
f59ffb62c36d6ccb4c23d346c6ed9c83ee45161b5755de754615b8db3601e4fa
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.11.19 {"installer":{"name":"uv","version":"0.11.19","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
