Skip to content

SatMAE++ Family (satmaepp, satmaepp_s2_10b)

Quick Facts

Field satmaepp (RGB) satmaepp_s2_10b (S2-10B)
Canonical ID satmaepp satmaepp_s2_10b
Aliases satmaepp_rgb, satmae++ satmaepp_sentinel10, satmaepp_s2
Adapter type on-the-fly on-the-fly
Model config keys none variant (default: large; choices: large)
Core extraction forward_encoder(mask_ratio=0.0) forward_encoder(mask_ratio=0.0)

SatMAE++ In 30 Seconds

SatMAE++ is a multi-scale improvement over SatMAE, and in rs-embed it ships as two non-interchangeable adapter paths: a plain RGB fMoW path (satmaepp) and a Sentinel-2 10-band grouped-channel path (satmaepp_s2_10b) that partitions channels into three fixed groups ((0,1,2,6),(3,4,5,7),(8,9)) and reduces grouped tokens at output time.

In rs-embed, its most important characteristics are:

Shared Output Semantics

pooled: RGB path records patch_mean/patch_max; S2-10B path records group_tokens_mean/group_tokens_max reflecting its grouped-token runtime.

grid: satmaepp returns a standard ViT patch-token grid (D,H,W); satmaepp_s2_10b reduces grouped tokens across channel groups then reshapes to (D,H,W).

Variant A: satmaepp (RGB)

Input Contract

Field Value
Backend provider only (gee)
TemporalSpec range (single-composite window)
Default collection COPERNICUS/S2_SR_HARMONIZED
Default bands (order) B4, B3, B2
Default fetch scale_m=10, cloudy_pct=30, composite="median"
input_chw CHW, C=3 in (B4,B3,B2) order, raw SR 0..10000
Side inputs none

Architecture Concept

flowchart LR
    A1["3-band\n(B4,B3,B2)"] --> A2["uint8 → eval preprocess\n(rgb/bgr order)"]
    A2 --> A3["forward_encoder\n(mask_ratio=0.0)"]
    A3 --> A4["Standard\npatch tokens"]
    A4 --> A5P["pooled:\npatch_mean / patch_max"]
    A4 --> A5G["grid:\nViT patch-token grid (D,H,W)"]

Preprocessing Pipeline

Resize is the default — tiling is also available

The pipeline below shows the default input_prep="resize" path. For large ROIs, use input_prep="tile" to split the input into tiles and preserve spatial detail. See Choosing Settings.

flowchart LR
    INPUT["Provider fetch / input_chw"] --> RGB["RGB uint8 patch"]
    RGB --> PRE["SatMAE++ fMoW eval preprocess\n(channel_order: rgb / bgr)"]
    PRE --> FWD["forward_encoder\n(mask_ratio=0.0)"]
    FWD --> OUT{Output}
    OUT -- pooled --> POOL["Token pooling"]
    OUT -- grid --> GRID["Patch-token\nreshape (D,H,W)"]

Key Environment Variables

Env var Effect
RS_EMBED_SATMAEPP_ID HF model ID / checkpoint selector
RS_EMBED_SATMAEPP_IMG Eval image size
RS_EMBED_SATMAEPP_CHANNEL_ORDER rgb or bgr preprocessing order
RS_EMBED_SATMAEPP_BGR Legacy BGR toggle
RS_EMBED_SATMAEPP_FETCH_WORKERS Provider prefetch workers for batch APIs
RS_EMBED_SATMAEPP_BATCH_SIZE Inference batch size for batch APIs

Common Failure Modes

  • wrong input_chw shape or band order
  • checkpoint preprocessing mismatch because CHANNEL_ORDER changed
  • missing rshf / SatMAE++ wrapper dependencies
  • unexpected token shape causing grid reshape failures

Variant B: satmaepp_s2_10b (Sentinel-2 10-band)

Input Contract

Field Value
Backend provider only (gee)
TemporalSpec range (single-composite window)
Default collection COPERNICUS/S2_SR_HARMONIZED
Default bands (order) B2, B3, B4, B5, B6, B7, B8, B8A, B11, B12 — strict order, must match exactly
Default fetch scale_m=10, cloudy_pct=30, composite="median", fill_value=0.0
input_chw CHW, C=10 in the strict band order, raw SR 0..10000
Side inputs none

Architecture Concept

flowchart LR
    B1["10-band input"] --> B2["Grouped-channel\nconstruction"]
    B2 --> BG["G0=(0,1,2,6)\nG1=(3,4,5,7)\nG2=(8,9)"]
    BG --> B3["forward_encoder\n(mask_ratio=0.0)"]
    B3 --> B4["Grouped tokens\nper group"]
    B4 --> B5["GRID_REDUCE\ncollapses across groups"]
    B5 --> B6P["pooled:\ngroup_tokens_mean / max"]
    B5 --> B6G["grid:\nreduced → (D,H,W)"]

Preprocessing + Runtime Loading

flowchart LR
    INPUT["10-band CHW"] --> PREP["Sentinel stats → uint8\n→ eval transforms"]
    PREP --> GRP["Grouped-channel model\nG0=(0,1,2,6) G1=(3,4,5,7) G2=(8,9)"]
    GRP --> FWD["forward_encoder\n(mask_ratio=0.0)"]
    FWD --> POOL["pooled: reduce → vector"]
    FWD --> GRID["grid: reduce → (D,H,W)"]

Key Environment Variables

Env var Effect
RS_EMBED_SATMAEPP_S2_CKPT_REPO Checkpoint repo/source
RS_EMBED_SATMAEPP_S2_CKPT_FILE Checkpoint filename
RS_EMBED_SATMAEPP_S2_MODEL_FN Model constructor name
RS_EMBED_SATMAEPP_S2_IMG Eval image size
RS_EMBED_SATMAEPP_S2_PATCH Patch size
RS_EMBED_SATMAEPP_S2_GRID_REDUCE Group reduction mode for grid output
RS_EMBED_SATMAEPP_S2_WEIGHTS_ONLY Weights-only checkpoint loading toggle
RS_EMBED_SATMAEPP_S2_FETCH_WORKERS Provider prefetch workers for batch APIs
RS_EMBED_SATMAEPP_S2_BATCH_SIZE Inference batch size for batch APIs

Common Failure Modes

  • sensor.bands order differs from the strict expected 10-band layout
  • vendored runtime import fails or checkpoint download is unavailable
  • grouped-token reshape assumptions do not match the loaded checkpoint/config
  • GRID_REDUCE changes representation semantics across experiments

Examples

Minimal pooled examples

from rs_embed import get_embedding, PointBuffer, TemporalSpec, OutputSpec

spatial = PointBuffer(lon=121.5, lat=31.2, buffer_m=2048)
temporal = TemporalSpec.range("2022-06-01", "2022-09-01")

emb_rgb = get_embedding(
    "satmaepp",
    spatial=spatial,
    temporal=temporal,
    output=OutputSpec.pooled(),
    backend="gee",
)

emb_s2 = get_embedding(
    "satmaepp_s2_10b",
    spatial=spatial,
    temporal=temporal,
    output=OutputSpec.pooled(),
    backend="gee",
)

Example tuning knobs (env-controlled)

# RGB variant:
export RS_EMBED_SATMAEPP_ID=...
export RS_EMBED_SATMAEPP_CHANNEL_ORDER=rgb
#
# S2-10B variant:
export RS_EMBED_SATMAEPP_S2_IMG=224
export RS_EMBED_SATMAEPP_S2_GRID_REDUCE=mean

Example with variant selection

from rs_embed import get_embedding, PointBuffer, TemporalSpec, OutputSpec

spatial = PointBuffer(lon=121.5, lat=31.2, buffer_m=2048)
temporal = TemporalSpec.range("2022-06-01", "2022-09-01")

emb_s2 = get_embedding(
    "satmaepp_s2_10b",
    spatial=spatial,
    temporal=temporal,
    output=OutputSpec.grid(),
    backend="gee",
    variant="large",
)

For export jobs, the same setting goes through ExportModelRequest.configure("satmaepp_s2_10b", variant="large").

Reference

  • RGB variant is sensitive to CHANNEL_ORDER (rgb/bgr) — the original eval preprocessing was BGR-based.
  • S2-10B variant's GRID_REDUCE changes the output semantics; mean and max are not interchangeable.
  • The two variants (satmaepp and satmaepp_s2_10b) are separate model IDs with different preprocessing, not a config switch on the same model.