---
license: apache-2.0
paper: https://arxiv.org/abs/2510.12670
homepage: https://github.com/IBM/TerraCodec
datasets:
- embed2scale/SSL4EO-S12-v1.1
library_name: terratorch
tags:
- Compression
- Neutral Codecs
- Earth Observation
---

# TerraCodec

**Neural Compression for Earth Observation**

[![arXiv](https://img.shields.io/badge/arXiv-2510.12670-b31b1b)](https://arxiv.org/abs/2510.12670)
[![GitHub](https://img.shields.io/badge/GitHub-IBM%2FTerraCodec-black?logo=github)](https://github.com/IBM/TerraCodec)
[![PyPI](https://img.shields.io/badge/PyPI-terracodec-blue?logo=pypi)](https://pypi.org/project/terracodec/)

TerraCodec (TEC) is a family of pretrained neural compression codecs for **multispectral Sentinel-2 satellite imagery**. The models compress optical Earth observation data using learned latent representations and entropy coding.

Compared to classical codecs such as JPEG2000 or WebP, TerraCodec achieves **3–10× higher compression at comparable reconstruction quality** on multispectral satellite imagery. Temporal models further improve compression by exploiting redundancy across seasonal image sequences of satellite imagery.

![Reconstructions](https://raw.githubusercontent.com/IBM/TerraCodec/main/assets/reconstructions.jpg)

---

# Model Family

| Model | Available Checkpoints | Description |
|---|---|---|
| [`terracodec_v1_fp_s2l2a`](https://huggingface.co/embed2scale/TerraCodec-1.0-ELIC-S2L2A) | λ = 0.5, 2, 10, 40, 200 | Factorized-prior image codec. Smallest model and strong baseline for multispectral image compression. |
| [`terracodec_v1_elic_s2l2a`](https://huggingface.co/embed2scale/TerraCodec-1.0-FP-S2L2A) | λ = 0.5, 2, 10, 40, 200 | Enhanced entropy model with spatial and channel context for improved rate–distortion performance. |
| [`terracodec_v1_tt_s2l2a`](https://huggingface.co/embed2scale/TerraCodec-1.0-TT-S2L2A) | λ = 0.4, 1, 5, 20, 100, 200, 700 | Temporal Transformer codec modeling redundancy across seasonal image sequences. |
| [`flextec_v1_s2l2a`](https://huggingface.co/embed2scale/TerraCodec-1.0-FlexTEC-S2L2A) | **Single checkpoint** (quality = 1–16) | Flexible-rate temporal codec. One model supports multiple compression levels via token-based quality settings. |

Lower λ / quality → **higher compression**  
Higher λ / quality → **higher reconstruction quality**

---

# Model Architecture

This repository contains the **TEC-ELIC** variants of TerraCodec.

![assets/TEC_ELIC_architecture.png](https://raw.githubusercontent.com/IBM/TerraCodec/main/assets/TEC_image_architecture.png)

TEC-ELIC is a convolutional encoder–decoder neural compression model based on the Efficient Learned Image Compression (ELIC) architecture. The model predicts the mean and scale of latent variables using spatial and channel context together with a hyperprior. 
This richer entropy model improves rate–distortion performance compared to the factorized prior model, at the cost of higher computational complexity. TEC-ELIC is optimized for 12-band Sentinel-2 imagery.

See the [paper](https://arxiv.org/abs/2510.12670) for additional architectural and training details.

---

# Input Format

| Codec type      | Expected shape      | Example                |
|-----------------|---------------------|-------------------------|
| Image codecs    | `[B, C, H, W]`      | `[1, 12, 256, 256]`     |
| Temporal codecs | `[B, T, C, H, W]`   | `[1, 4, 12, 256, 256]`  |

- Inputs use **12 Sentinel‑2 L2A spectral bands**.  
- Recommended spatial size: **256×256**.
- Temporal codecs were pretrained on four seasonal frames, but can process any number of timesteps during inference (higher T increases compute).  

---

# Normalization

Models were trained on **[SSL4EO-S12 v1.1](https://huggingface.co/datasets/embed2scale/SSL4EO-S12-v1.1)**.

Inputs should be standardized per spectral band using dataset statistics. For S2L2A:

```python
mean = torch.tensor([793.243, 924.863, 1184.553, 1340.936, 1671.402, 2240.082, 2468.412, 2563.243, 2627.704, 2711.071, 2416.714, 1849.625])
std = torch.tensor([1160.144, 1201.092, 1219.943, 1397.225, 1400.035, 1373.136, 1429.170, 1485.025, 1447.836, 1652.703, 1471.002, 1365.307])
```

# Usage

Install TerraCodec:

```
pip install terracodec
```

Load pretrained models:
```python
from terracodec import terracodec_v1_elic_s2l2a

model = terracodec_v1_elic_s2l2a(
    pretrained=True,
    compression=10
)

# Fast reconstruction (no bitstream)
reconstruction = model(inputs)

# True compression
compressed = model.compress(inputs)
reconstruction = model.decompress(**compressed)
```

# Feedback
If you have questions, encounter issues or want to discuss improvements:
- open an issue or discussion on GitHub
- or contribute directly to the repository

GitHub repository: https://github.com/IBM/TerraCodec

# Citation
If you use TerraCodec in your research, please cite:
```
@article{terracodec2025,
  title   = {TerraCodec: Compressing Optical Earth Observation Data},
  author  = {Costa Watanabe, Julen and Wittmann, Isabelle and Blumenstiel, Benedikt and Schindler, Konrad},
  journal = {arXiv preprint arXiv:2510.12670},
  year    = {2025}
}
```