srb ephemeris — Real Sun/Planet Geometry (Optional Feature)
Query sun/planet geometry, download SPICE kernels and import illumination
products. Install the optional spiceypy extra (pip install 'srb[spice]');
parsing, --help and completion need neither it nor Isaac Sim.
Usage
srb ephemeris <action> [options]
Actions
| Action | Purpose |
|---|---|
download | Fetch the pinned ~43 MB kernel bundle (see kernel bundle table) into the local cache. Idempotent — already-cached, hash-verified kernels are not re-downloaded. |
info | Print azimuth, elevation, distance, and angular diameter for one or more bodies as seen from a given site and epoch, plus the solar-irradiance scale. |
import | Import an external precomputed illumination product (lunarlab or PGDA) onto a terrain-patch grid as an srb_illum/2 sidecar (see illumination-product details). |
info Options
| Option | Required | Description |
|---|---|---|
--body {moon,mars,earth} | Yes | Observer’s home body (the surface site sits on this body). |
--lat LAT | Yes | Site latitude in degrees, [-90, 90]. |
--lon LON | Yes | Site longitude in degrees. |
--alt ALT | No (default 0.0) | Site altitude in meters above the mean body radius. |
--utc UTC | Yes | ISO-8601 epoch, e.g. 2026-11-01T12:00:00. Must fall within the de440s kernel coverage window (1850-01-01 through 2149-12-31). |
--bodies BODIES | No (default sun,earth) | Comma-separated list from sun, earth, moon, mars, and venus; duplicate or unknown names fail validation. sun is always included regardless of this list. |
import Options
| Option | Required | Description |
|---|---|---|
--source {lunarlab-zarr,lunarlab-npz,pgda-lpsr} | Yes | External illumination-product format to import. |
--input PATH | Yes | Path to the source product (a directory for lunarlab-zarr, a file otherwise). |
--baked-dir PATH | No | A baked Real-Terrain-v2 patch directory; the target grid, CRS, and site lat/lon are inferred from its meta.json, and the output defaults to <baked-dir>/illumination.npz. --out and --gsd-m may also be used; --lat/--lon are rejected. |
--out PATH | Required without --baked-dir | Output .npz path; in baked-directory mode defaults to <baked-dir>/illumination.npz. |
--crs CRS | Required without --baked-dir | Target CRS (e.g. an IAU_2015:* code). |
--center-xy CX,CY | Required without --baked-dir | Patch center in the target CRS, meters. |
--size-m SIZE | Required without --baked-dir | Patch size, meters. |
--lat LAT / --lon LON | Required without --baked-dir | Site latitude/longitude in degrees, used for the true-north azimuth and curvature-ramp elevation corrections. |
--gsd-m GSD | Required without --baked-dir | Target ground sample distance, meters. --size-m must be an integer multiple of --gsd-m, or the command exits with status 2. |
--epoch-range T0,T1 | No | Keep only source epochs within this inclusive ISO-8601 UTC range. Rejected (exit status 2) together with --source pgda-lpsr, which carries no epoch tier. |
--epoch-stride N | No (default 1) | Keep every Nth epoch after range filtering. Rejected (exit status 2) together with --source pgda-lpsr. |
--body {moon,mars,earth} | No (default moon) | Body the target terrain patch sits on. PGDA-LPSR imports support Moon only. |
--baked-dir and --lat/--lon are mutually exclusive — the baked patch’s
meta.json is the sole georef authority in --baked-dir mode, so passing
--lat/--lon alongside it exits with status 2.
Examples
Fetch the kernel bundle once; later info calls reuse the cache:
srb ephemeris download
Query sun and earth geometry at a lunar south-pole site:
srb ephemeris info --body moon --lat -89.66 --lon 0.0 \
--utc 2026-11-01T12:00:00 --bodies sun,earth
Query Mars geometry at Jezero crater:
srb ephemeris info --body mars --lat 18.44 --lon 77.45 \
--utc 2021-02-18T20:55:00 --bodies sun
Import illumination from a lunarlab spice_maps product using the baked
patch’s grid, CRS and site from meta.json:
srb ephemeris import --source lunarlab-zarr \
--input /data/lunarlab/shackleton_240m/epochs.zarr \
--baked-dir .cache/terrain/moon/shackleton_rim/<patch-key>
Import a PGDA product-69 LPSR GeoTIFF onto an explicit grid:
srb ephemeris import --source pgda-lpsr \
--input /data/pgda/lpsr_shackleton.tif \
--crs "IAU_2015:30135" --center-xy 0.0,10309.969398639505 \
--size-m 4096 --gsd-m 5.0 --lat -89.66 --lon 0.0 \
--out /tmp/shackleton_illumination.npz
Disabling Auto-Fetch
download fetches explicitly; info and programmatic queries auto-fetch
missing kernels by default. For explicit pre-fetch (e.g. air-gapped CI),
disable auto-fetch and populate the cache first:
export SRB_EPHEMERIS_AUTO_FETCH=0
srb ephemeris download # run once, ahead of time, with network access
With auto-fetch disabled, missing kernels raise KernelsMissingError with the
required srb ephemeris download command.
See Also
- Ephemeris Configuration — kernel bundle details,
environment variables, attribution, and the programmatic
query()API.