Real Terrain Assets

Use srb.assets.scenery.RealTerrain to add survey terrain to an Isaac Lab scene. For DEM sources and baking, see Adding Terrain Sites.

Basic usage

from srb.assets.scenery import RealTerrain
from srb.assets.scenery.real_terrain_sites import (
    LunarSiteApollo17, MartianSiteJezero, MartianSiteJezeroV2,
)

terrain = RealTerrain(body="moon", site="apollo17")  # manifest site
terrain = LunarSiteApollo17()                         # shortcut class
terrain = MartianSiteJezero()                         # another shortcut
terrain = MartianSiteJezeroV2()                       # declared v2 source stack
terrain = RealTerrain(body="moon", lat_deg=-89.66, lon_deg=0.0, size_m=2000.0)  # arbitrary region
env_cfg.scene.terrain = terrain.asset_cfg

Companion assets

RealTerrain provides optional manifest-configured sky, lighting, and rock companions. Override them per instance or attach them explicitly:

terrain = LunarSiteApollo17(sky="apollo17_pan", lighting="auto", rocks=None)
terrain.attach_companions(env_cfg)

Environment configs attach companions by default when env.scenery resolves to RealTerrain. Selection is arbitrated against env.ephemeris; unavailable products warn and degrade according to the precedence table. Set attach_companions_enabled=False to disable attachment. See Ephemeris-driven terrain lighting for setup and fallback behavior.

SimForge augmentation

Pass augment="simforge" to generate per-environment rock variation; simforge_foundry must be importable or SimforgeMissingError is raised.

terrain = RealTerrain(body="moon", site="apollo17", augment="simforge")

User-supplied DEMs

Skip the manifest and bake a local DEM. attribution is required for license compliance.

terrain = RealTerrain(
    body="moon", dem_path="/data/my_lunar_dem.tif", site_name="my_polar_crater",  # cache key
    attribution="Acme Surveying, 2026", patch_size_m=300, use_ortho=False,
)

Set exactly one of site, dem_path, or the complete region triplet (lat_deg/lon_deg/size_m). Shortcut classes default to site, so use RealTerrain(body=..., dem_path=...) for a local DEM.

CLI workflow

srb asset list terrain
srb asset list terrain --body moon
srb asset info terrain apollo17
srb asset download terrain apollo17  # pre-bake; otherwise created on first use
srb asset download terrain --lat -89.66 --lon 0.0 --size-m 2000 --body moon --deshade
srb asset bake terrain --dem /data/my.tif --body moon --site-name my_local --attribution "Me, 2026"
srb asset cache-stats
srb asset clean terrain apollo17 --baked

Real-terrain v2: source catalog and stack resolution

The v2 catalog resolves regions to prioritized DEM and colour sources. Preview layers and estimated downloads without network access:

srb asset stack --body moon --lat -89.46 --lon 137.3 --size 2000
srb asset stack --body moon --lat -89.46 --lon 137.3 --size 2000 --json

See catalog coverage, source requirements, and declared stacks. Named sites and arbitrary regions use the same interfaces as v1; Terrain Stacks documents resolution, cache, deshade, and companion rules, including large-download consent.

Real-terrain v2: the fusion engine

A v2 site’s dem_stack has one gap-free role: base layer and optional finer, partial role: inset layers; an optional color_stack has the same structure. Baking aligns and blends sources, drops insets that fail alignment checks, and records source provenance and per-layer attribution.

Ambient occlusion is computed at up to 2048 px then upsampled. Collision skirts and shells may put final face count slightly over the cap. Shipped jezero_v2 uses this path; offline fixtures exercise fusion but do not validate upstream source data.

Caching and reproducibility

Bakes are content-addressed by (body, site, patch, lod, seed, materials_version, dem_sha256, ...): identical inputs produce identical bytes, and changing an input invalidates the bake. See cache roots and behavior.

Disabling auto-fetch

Missing bakes are produced on first use by default after source fetches pass large-download consent checks. To require explicit pre-baking (for example, in air-gapped CI):

export SRB_TERRAIN_AUTO_FETCH=0

Then RealTerrain(...) raises TerrainNotBakedError with the exact srb asset download command.

Troubleshooting