Metadata-Version: 2.4
Name: grib2cog
Version: 0.1.0
Summary: Convert GRIB2 files to Cloud-Optimized GeoTIFF (COG)
Author: Sam Chen
License-Expression: MIT
Project-URL: Homepage, https://github.com/cyberpsyche/grib2cog
Project-URL: Repository, https://github.com/cyberpsyche/grib2cog
Keywords: grib2,grib,cog,geotiff,gdal,geospatial
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
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
Dynamic: license-file

# grib2cog - GRIB2 to Cloud-Optimized GeoTIFF Converter

Convert GRIB2 files to Cloud-Optimized GeoTIFF (COG) format.

## Features

- **Format conversion**: GRIB2 → Cloud-Optimized GeoTIFF (COG) in a single GDAL pass
- **Smart message grouping**: one COG per (variable, level), forecast times as bands
- **Message filtering**: select by variable short name, level, forecast step, or raw band index
- **Advanced compression**: deflate / lzw / jpeg with a configurable deflate level
- **Performance tuning**: configurable tile size, overview levels, resampling, and output dtype
- **Reprojection**: transform to any EPSG coordinate system during conversion
- **Batch processing**: convert directories (one subdirectory per input file), parallel across files
- **Rich metadata**: 18 metadata fields written to every output COG
- **Config file**: YAML defaults merged with CLI overrides

## Requirements

- Python 3.9+
- GDAL ≥ 3.8 with Python bindings

## Installation

Install GDAL first:

- **macOS**: `brew install gdal`
- **Ubuntu/Debian**: `sudo apt-get install gdal-bin libgdal-dev`
- **Windows**: use the OSGeo4W installer

Then install grib2cog:

```bash
pip install grib2cog
```

### From source

```bash
git clone <repository-url>
cd grib2cog
pip install .
```

## Quick Start

```bash
# Convert a file: one COG per (variable, level), forecast times as bands
grib2cog input.grib2 output/

# Convert only one variable
grib2cog input.grib2 output/ --short-name UGRD

# Filter by level and forecast step
grib2cog input.grib2 output/ --level 0-MSL --step 0,3

# Convert to a specific file (requires exactly one group)
grib2cog input.grib2 output/ugrd.tif --short-name UGRD --level 10-HTGL

# Whole file as one multi-band COG
grib2cog input.grib2 output/ --whole-file

# Batch convert a directory (one subdirectory per input file), 4 files in parallel
grib2cog input_dir/ output/ --threads 4
```

## Command Line Options

| Option | Description | Default |
|---|---|---|
| `INPUT_PATH` | GRIB2 file or directory | (required) |
| `OUTPUT_PATH` | Output directory, or a file ending in `.tif` | (required) |
| `--config`, `-c` | Path to a YAML config file | — |
| `--compression` | `deflate` / `lzw` / `jpeg` | `deflate` |
| `--zlevel` | DEFLATE compression level 1–9 | `6` |
| `--tile-size` | COG tile size in pixels | `512` |
| `--resampling` | Overview resampling (`nearest`/`average`/`gauss`/`cubic`/`cubicspline`/`lanczos`/`mode`/`rms`) | `nearest` |
| `--overview-levels` | Number of overview levels (e.g. `2,4,8,16` → 4 levels) | `2,4,8,16` |
| `--output-type` | Output dtype (`Byte`/`UInt16`/`Int16`/`UInt32`/`Int32`/`Float32`/`Float64`) | source dtype |
| `--short-name` | Filter by variable short name, comma-separated (e.g. `UGRD,HTSGW`) | all |
| `--level` | Filter by level descriptor, comma-separated (e.g. `0-MSL,10-HTGL`) | all |
| `--step` | Filter by forecast step in hours, comma-separated (e.g. `0,3`) | all |
| `--band` | Filter by raw 1-based band indices (comma/ranges, e.g. `1,3-5`); disables grouping | — |
| `--whole-file` | Convert the whole file as one multi-band COG (no grouping) | off |
| `--src-proj` | Source projection, e.g. `EPSG:4326` | auto-detected |
| `--dst-proj` | Target projection, e.g. `EPSG:3857` | — |
| `--metadata-source` | Override the `Source` metadata field | auto (GRIB) |
| `--overwrite` | Overwrite existing output files | off |
| `--dry-run` | Show what would be processed without doing it | off |
| `--verbose`, `-v` | Verbose (debug) logging | off |
| `--threads` | Process multiple files in parallel | `1` |
| `--version`, `-V` | Show version and exit | — |

Filters are case-insensitive; different filters AND together, comma-separated values within one filter OR together.

## Output Path Rules

| `OUTPUT_PATH` | Behavior |
|---|---|
| directory | one COG per (variable, level), named `{element}_{level}.tif` |
| directory (directory input) | one subdirectory per input file: `{output}/{input_stem}/...` |
| ends with `.tif` | write that exact file (requires exactly one group) |

## Configuration File

```yaml
compression: "deflate"
zlevel: 6
tile_size: 512
output_type: null        # null = preserve source dtype

overviews:
  resampling: "nearest"
  levels: [2, 4, 8, 16]

projection:              # optional
  source: "EPSG:4326"
  target: "EPSG:3857"
  resampling_method: "nearest"

overwrite: false
skip_errors: true

metadata:
  source: ""             # override Source (auto-detected from GRIB if empty)
  offset: 0.0
  scale: 1.0
  unit: ""               # fallback unit (auto-detected from GRIB if empty)
```

Use with: `grib2cog --config config.yaml input.grib2 output/`

CLI options override config-file values.

## COG Metadata

Each output COG carries 18 metadata fields:

| Field | Description |
|---|---|
| `Coordinate System` | CRS of the output |
| `Band Count` | Number of bands (forecast times) |
| `Data Type` | Pixel data type |
| `Resolution` | Pixel resolution |
| `Extent` | `minLon, minLat, maxLon, maxLat` |
| `Creation Time` | UTC timestamp of conversion |
| `Source` | Data source (from `--metadata-source` or GRIB) |
| `Compression` | Compression algorithm |
| `startX` / `startY` | Upper-left corner coordinates |
| `endX` / `endY` | Lower-right corner coordinates |
| `min` / `max` | Global data value range |
| `offset` / `scale` | Linear transformation parameters |
| `unit` | Data unit (from GRIB) |
| `NoData` | No-data value (from the source band) |

## License

MIT — see [LICENSE](LICENSE).
