SatNav Documentation

This page is the main entry point for SatNav documentation. Choose the path that matches your goal; you do not need to read every document in filename order.

If this is your first time using SatNav, begin with Installation and run a repository example. Training and full evaluation additionally require SatNav-v0.1 episodes, GeoTIFF scenes, and model resources.

System principles

1. Run SatNav for the first time

Follow these documents in order:

  1. Installation: install SatNav Core and any optional application or classic-baseline dependencies;

  2. Examples: run a rollout with the bundled synthetic scene and two example episodes;

  3. Core API: learn the Env, observation, action, episode, and metric interfaces;

  4. Data Format: understand real episodes, GeoTIFFs, and trajectories.

The repository examples require no SatNav-v0.1 download, satellite imagery, or model checkpoint.

2. Prepare SatNav-v0.1 data

For training or full evaluation, prepare data in this order:

  1. Episode Download: download train, val_seen, val_unseen, and the scene list;

  2. Satellite Scene Download: request prepared GeoTIFFs or generate them with your own API credentials;

  3. SatSim Viewer: inspect scenes, episode starts, and reference paths;

  4. Trajectory Generation: generate RGB frames and expert actions for offline training;

  5. Data Format: verify the public episode and trajectory schemas.

Online evaluation needs episodes, GeoTIFFs, and a model checkpoint; it does not require offline trajectories. Training Seq2Seq, CMA, or a VLM baseline does.

3. Train models

Begin with Model Training for the shared workflow, required inputs, and the choice between Classic and VLM baselines.

Classic baselines

Classic Baselines covers Seq2Seq and CMA data preparation, vocabulary construction, training, checkpoint validation, and single-/multi-GPU evaluation. Use the tiny example quickstart first when validating a new environment. Random and ReferenceFollower have no trainable parameters.

VLM baselines

Each VLM uses its own Python environment and model resources:

Baseline

Training and evaluation guide

StreamVLN

StreamVLN Baseline

NaVILA

NaVILA Baseline

Uni-NaVid

Uni-NaVid Baseline

OpenFly

OpenFly Baseline

Released SatNav checkpoints are available in the SatNav Baseline Model Zoo.

Do not share PyTorch, Transformers, or FlashAttention environments across VLM baselines. Store models, datasets, upstream checkouts, and output paths in the baseline’s Git-ignored .local/env.sh.

4. Evaluate models

Evaluation documents the common online rollout, episode selection, multi-rank sharding, output format, aggregation, error handling, and resume behavior used by every Classic and VLM baseline.

Recommended evaluation sequence:

  1. run a single-GPU smoke with a few episodes and a five-step cap;

  2. repeat the same smoke on multiple GPUs to validate sharding and aggregation;

  3. run all val_seen episodes with a 500-step cap;

  4. repeat the full settings on val_unseen.

Use the baseline-specific guide for model setup, checkpoints, and launchers.

5. Integrate a new model

Read these documents in order:

  1. Core API: environment, observation, and action contract;

  2. Evaluation: evaluator ownership and result format;

  3. Model Integration: implement a PolicyAdapter, isolated environment, launcher, and local configuration;

  4. use a structurally similar VLM baseline as a complete reference.

New models must use the public Env and PolicyAdapter interfaces. The adapter owns model state, frame history, tokenization, processors, and action queues.

6. Find documentation by task

Goal

Document

Install SatNav

Installation

Run repository examples

Examples

Use the Python API

Core API

Understand data fields

Data Format

Download episodes

Episode Download

Prepare GeoTIFFs

Satellite Scene Download

Inspect scenes and episodes

SatSim Viewer

Generate offline trajectories

Trajectory Generation

Choose a training path

Model Training

Train Seq2Seq or CMA

Classic Baselines

Train or evaluate a VLM

VLM baselines

Run common online evaluation

Evaluation

Integrate a new model

Model Integration

7. Documentation conventions

  • Commands run from the SatNav repository root unless stated otherwise.

  • /path/to/... is a placeholder for a machine-local path.

  • Store datasets, models, checkouts, and output paths in .local/env.sh or another Git-ignored configuration.

  • Smoke commands validate the pipeline; they are not performance results.

  • Official benchmark runs use the full split, a 500-step cap, and a complete checkpoint for the selected baseline.

  • Each procedural guide ends with troubleshooting for that workflow.