Metadata-Version: 2.4
Name: zarr2cog
Version: 0.1.0
Summary: Convert Zarr arrays to Cloud-Optimized GeoTIFF format with advanced compression
Author: Sam Chen
License: MIT
Project-URL: Homepage, https://github.com/cyberpsyche/zarr2cog
Project-URL: Repository, https://github.com/cyberpsyche/zarr2cog
Keywords: zarr,cog,geotiff,gdal,geospatial
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: GIS
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: GDAL>=3.8.0
Requires-Dist: click>=8.1.0
Requires-Dist: PyYAML>=6.0
Requires-Dist: numpy>=1.21.0
Dynamic: license-file

# zarr2cog - Zarr to Cloud-Optimized GeoTIFF Converter

[中文](README_zh.md)

Convert Zarr arrays to Cloud-Optimized GeoTIFF (COG) format with advanced
compression and performance settings. A companion to
[nc2cog](https://github.com/cyberpsyche/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

```bash
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:

```bash
zarr2cog input.zarr output/
```

Convert a multi-array zarr group (one COG per array):

```bash
zarr2cog dataset.zarr output/
# Produces: output/PRE.tif, output/REF.tif
```

Convert only specific arrays:

```bash
zarr2cog --variables PRE,REF dataset.zarr output/
```

Convert a single array to a specific output file:

```bash
zarr2cog --variables PRE dataset.zarr output/PRE.tif
```

Batch-convert a directory of zarr stores:

```bash
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

```yaml
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
