`srb ephemeris` — Real Sun/Planet Geometry (Optional Feature)

The srb ephemeris command queries or downloads the real sun/planet geometry used by SRB’s optional SPICE ephemeris subsystem. It is built on NASA/JPL’s NAIF SPICE toolkit via spiceypy, which is an opt-in extra (pip install 'srb[spice]') — the parser and --help/ completion paths stay fast and Isaac-free even when the extra is not installed; only running an action imports spiceypy/numpy.

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 Products).

`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 (1849-12-26 to 2150-01-22).
`--bodies BODIES`	No (default `sun,earth`)	Comma-separated list of bodies to query in addition to the observer’s own body. `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`. Mutually exclusive with the explicit-target options below (exactly one mode).
`--out PATH`	Explicit-target mode only	Output `.npz` path.
`--crs CRS`	Explicit-target mode only	Target CRS (e.g. an `IAU_2015:*` code).
`--center-xy CX,CY`	Explicit-target mode only	Patch center in the target CRS, meters.
`--size-m SIZE`	Explicit-target mode only	Patch size, meters.
`--lat LAT` / `--lon LON`	Explicit-target mode only	Site latitude/longitude in degrees, used for the true-north azimuth and curvature-ramp elevation corrections.
`--gsd-m GSD`	Explicit-target mode only	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.

--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

Pre-fetch the kernel bundle once (subsequent info calls reuse the cache):

srb ephemeris download

Query sun and earth geometry for a Shackleton-crater-rim-like 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 only the sun for a historical Apollo 17 EVA timestamp:

srb ephemeris info --body moon --lat 20.19 --lon 30.77 \
  --utc 1972-12-11T19:54:57 --bodies sun

Query Mars geometry (Jezero crater) for a rover-relevant epoch:

srb ephemeris info --body mars --lat 18.44 --lon 77.45 \
  --utc 2021-02-18T20:55:00 --bodies sun

Sample info output (one line per queried body, plus the irradiance scale):

sun: az=279.043° el=1.512° dist=149685302 km diam=0.559°
earth: az=64.201° el=2.551° dist=384412 km diam=1.916°
irradiance_scale=1.0021

Import a baked lunar terrain patch’s illumination directly from a lunarlab spice_maps product (target grid/CRS/site inferred from the patch’s 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 target grid (no baked patch available):

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

By default, missing kernels are downloaded automatically the first time they are needed (download or info). To require an explicit pre-fetch step (e.g. air-gapped CI), disable auto-fetch and pre-populate the cache ahead of time:

export SRB_EPHEMERIS_AUTO_FETCH=0
srb ephemeris download   # run once, ahead of time, with network access

With auto-fetch disabled and kernels missing, info/programmatic queries raise KernelsMissingError naming the exact srb ephemeris download command to run.

Space Robotics Bench