feat(models): integrate OLMoEarth embedding model

[go-bananas-wwj]

feat(models): integrate OLMoEarth embedding model

Overview

This PR adds OLMoEarth (Allen AI's Earth-system foundation model) as the 6th embedding model to Eart
hEmbeddingExplorer, alongside SigLIP, FarSLIP, SatCLIP, DINOv2, and Clay.

OLMoEarth is a multimodal, spatio-temporal foundation model trained on Sentinel-2 L2A and 6 derived geos
patial maps (OpenStreetMap, WorldCover, SRTM DEM, etc.). It excels at capturing spectral and spatial pat
terns from 12-band multispectral imagery, making it a strong candidate for pure visual similarity search
in remote-sensing applications.

Paper: Herzog et al., 2025 — OlmoEarth: Stable Latent Image Modeling for Multimodal Earth Observati
on

---

What Changed

Commit	Scope	Description
feat(models)	models/olmoearth_model.py, core/model_manager.py, generate_embeddings.py, `requ
irements.txt, configs/config.yaml, app.py`	Add OLMoEarth model wrapper with MEAN pooling, L2-norma
lized cosine search, and MajorTOM band reordering
fix(majortom)	MajorTOM/embedder/MajorTOM_Embedder.py	Use INTER_CUBIC instead of `INTER_NEARE
ST` for 12-band image quality
chore(gitignore)	.gitignore	Exclude generated embedding artifacts (embeddings_*/, *.pkl, `
*.npy`)
docs(readme, doc, contributing)	README.md, doc.md, CONTRIBUTING.md	Document OLMoEarth as t
he 6th model; add dataset link and torch compatibility notes

---

Key Technical Details

1. Band Reordering
MajorTOM stores bands as [B01, B02, B03, B04, B05, B06, B07, B08, B8A, B09, B11, B12], but OLMoEarth e
xpects [B02, B03, B04, B08, B05, B06, B07, B8A, B11, B12, B01, B09]. The wrapper handles this transpar
ently in _prepare_input().

2. Pooling Strategy
We use PoolingType.MEAN (matching the official allenai/olmoearth_ml4rs_tutorial) rather than MAX poo
ling. Raw embeddings have L2 norm ~10.3 and are not normalized during storage/encoding to stay consi
stent with the official tutorial.

3. Retrieval Normalization
To avoid polar clustering (polar embeddings have systematically higher norms ~10.5 vs ~10.2), we apply F.normalize() only inside search(), converting dot products to cosine similarity in [-1, 1].

4. Complete Metadata
The OLMoEarth embedding GeoParquet now includes parquet_url and parquet_row columns copied from the
reference DINOv2/SatCLIP dataset (all 6 models share identical 248,719 samples in the same order). This
means no fallback code is needed — the normal _fetch_top_k_images path works out of the box.

---

Dataset

• ModelScope: WeijieWu/olmoearth_embdding (824 MB, 248,719 rows, 768-dim float32)
• Dataset README: Included in the ModelScope repository, following Major-TOM embedding dataset conve
  ntions
• Source images: Major-TOM/Core-S2L2A-249k (same as other 5 models)

Note: configs/config.yaml contains a placeholder ms://Major-TOM/Core-S2RGB-249k-OLMoEarth/...
path consistent with the other 5 models. Users should create configs/config_local.yaml with the actual
local path or the WeijieWu/olmoearth_embdding ModelScope URL.

---

Environment Compatibility

olmoearth-pretrain-minimal requires torch >= 2.8, < 2.9. For users with older PyTorch versions, we r
ecommend a dedicated conda environment:

conda create -n eee python=3.12
conda activate eee
conda install pytorch==2.8.0 torchvision==0.23.0 pytorch-cuda=12.4 -c pytorch -c nvidia
pip install -r requirements.txt
────────────────────────────────────────────────────────────────────────────────────────────────────────
Verification
• ✅ Based on latest upstream/main from OpenGeoScope
• ✅ Clean commit history — no merge commits, no fallback-related commits
• ✅ ruff check . — all checks passed on modified Python files
• ✅ ruff format . --check — all formatted
• ✅ OLMoEarth parquet has 15 columns including parquet_url and parquet_row
• ✅ Dataset README.md follows Major-TOM conventions
────────────────────────────────────────────────────────────────────────────────────────────────────────
Checklist
• [x] Model wrapper follows the unified interface (encode_image, search)
• [x] Registered in core/model_manager.py and generate_embeddings.py
• [x] Added to requirements.txt
• [x] Updated README.md, doc.md, and CONTRIBUTING.md
• [x] Ruff linting and formatting passed
• [x] Embedding files kept outside the repository (/workspace/EEE/embeddings/)
• [x] Dataset README.md uploaded alongside parquet

---