File size: 5,198 Bytes
0c4abd5 e9d5f4d 0c4abd5 e9d5f4d 0c4abd5 e9d5f4d 0c4abd5 9b49836 0c4abd5 e9d5f4d 0c4abd5 e9d5f4d 0c4abd5 e9d5f4d 0c4abd5 | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 | ---
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**
[](https://arxiv.org/abs/2510.12670)
[](https://github.com/IBM/TerraCodec)
[](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.
---
# 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-TT (Temporal Transformer)** variants of TerraCodec.
TEC-TT extends the TerraCodec image codecs by modeling temporal dependencies across satellite image sequences. Each frame is first encoded using an ELIC-style CNN encoder–decoder to obtain latent representations. A temporal transformer then predicts the probability distribution of the current frame’s latents conditioned on previously encoded frames.
By exploiting redundancy across seasonal observations, TEC-TT achieves improved compression efficiency for multi-temporal 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_tt_s2l2a
model = terracodec_v1_tt_s2l2a(
pretrained=True,
compression=5
)
# 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}
}
``` |