SatNav Training Data

SwiftVLN is trained using offline expert trajectories generated by SatNav. The data preparation process is:

Episode + GeoTIFF
        │
        ▼
SatNav Trajectory Generation
        │
        ├── annotations.json
        ├── summary.json
        └── images/<episode>/rgb/*.jpg
                    │
                    ▼
             SwiftVLN Training

1. Prepare SatNav

After completing environment installation, initialize the SatNav submodule and install the data generation component:

cd "${SWIFTVLN_ROOT}"
git submodule update --init third_party/SatNav

conda activate swiftvln-train
cd third_party/SatNav
python -m pip install -e '.[applications]'

2. Download episodes

Follow SatNav’s Episode data download Download SatNav-Episodes-v0.1 and save the decompressed directory as:

/path/to/satnav_datasets/SatNav-v0.1

Verify downloaded files:

cd /path/to/satnav_datasets/SatNav-v0.1
sha256sum -c SHA256SUMS

Each data division includes:

Split	Episodes
train	105,164
val_seen	4,574
val_unseen	8,756

3. Prepare GeoTIFF scenes

Both options place the 59 GeoTIFFs in /path/to/satnav_datasets/scenes.

Option 1: Request and download prepared scenes

Open SatNav-Scenes-v0.1, sign in, complete the access form, and accept the terms. Once your request passes the system checks, download with the same Hugging Face account:

pip install -U huggingface_hub
hf auth login
hf download Eku127/SatNav-Scenes-v0.1 --repo-type dataset \
  --include "scenes/*.tif" --include SHA256SUMS \
  --local-dir /path/to/satnav_datasets

Verify the downloaded scene files:

(cd /path/to/satnav_datasets && sha256sum -c SHA256SUMS)

Continue with “Validate scenes” below, then generate offline trajectories.

Option 2: Generate scenes with your own API credentials

Register for an imagery service and configure your API credentials using SatNav’s Satellite Scene Download guide.

The following command uses the Google Map Tiles API to batch generate 59 scenes. Run dry run first:

cd "${SWIFTVLN_ROOT}/third_party/SatNav"
mkdir -p /path/to/satnav_datasets/scenes
export GOOGLE_MAPS_API_KEY=your-api-key

python -m applications.map_downloader google \
  --scene-config /path/to/satnav_datasets/SatNav-v0.1/scenes_list.yaml \
  --output-dir /path/to/satnav_datasets/scenes \
  --dry-run

Start downloading after confirming the scene range and output path:

python -m applications.map_downloader google \
  --scene-config /path/to/satnav_datasets/SatNav-v0.1/scenes_list.yaml \
  --output-dir /path/to/satnav_datasets/scenes

Validate scenes

After either option, validate the episodes and GeoTIFFs from the SatNav directory:

cd "${SWIFTVLN_ROOT}/third_party/SatNav"

SATNAV_DATA_ROOT=/path/to/satnav_datasets/SatNav-v0.1 \
SATNAV_SCENES_DIR=/path/to/satnav_datasets/scenes \
bash scripts/validation/data_validation.sh

Output after verification:

GeoTIFF scenes: 59/59
SatNav data configuration is complete.

4. Generate offline trajectories

First use SatNav’s two built-in example Episode test generation processes:

cd "${SWIFTVLN_ROOT}/third_party/SatNav"

python -m applications.trajectory_generation.generate \
  --config applications/resources/satnav_example_task.yaml \
  --output_dir output/trajectory_generation_test

Complete train split using SatNav’s production configuration and parallel entry:

SATNAV_TRAIN_EPISODES_PATH=/path/to/satnav_datasets/SatNav-v0.1/episodes/train/all_episodes.json \
SATNAV_SCENES_DIR=/path/to/satnav_datasets/scenes \
python -m applications.trajectory_generation.generate_parallel \
  --config applications/episode_processing/configs/trajectory_generation.yaml \
  --output_dir /path/to/satnav_datasets/SatNav-v0.1/trajectory_data

The complete data takes up approximately 233 GB. By default, the generator selects workers based on the number of scenes and the number of CPU cores; it can also be --num_workers N specifies the number of parallelism. After the task is interrupted, re-execute the command using the same output directory to continue.

For detailed parameters, see SatNav Trajectory data generation.

5. Trajectory format

The build directory contains:

trajectory_data/
├── annotations.json
├── summary.json
└── images/
    └── <scene_id>_satnav_<episode-index>/
        ├── .done
        ├── .annotation.json
        └── rgb/
            ├── 001.jpg
            ├── 002.jpg
            └── ...

annotations.json is the training entry point of SwiftVLN. A single record is as follows:

{
  "id": 0,
  "trajectory_id": "0",
  "steps": 3,
  "video": "images/Amsterdam-1_satnav_000000",
  "instructions": ["Continue along the road and stop at the junction."],
  "actions": [-1, 1, 1, 0]
}

Field	Description
`id`	Episode index in the source JSON list
`trajectory_id`	Source Episode route identifier
`steps`	The number of executable actions, equal to `len(actions) - 1`
`video`	Path to RGB frame directory relative to `trajectory_data/`
`instructions`	Navigation command list corresponding to this trajectory
`actions`	Discrete action sequence aligned with RGB observation

The action is coded as follows:

ID	Action
-1	`INIT`
0	`STOP`
1	`MOVE_FORWARD`
2	`TURN_LEFT`
3	`TURN_RIGHT`

Each trajectory satisfies:

JPEG count = len(actions) = steps + 1

For complete field definitions, see SatNav’s Data format.

6. Validate the complete dataset

Use the SatNav validator to check annotations, episodes, build configurations, scenes and all JPEGs:

cd "${SWIFTVLN_ROOT}/third_party/SatNav"
mkdir -p /path/to/satnav_datasets/validation

python scripts/validation/validate_trajectory_output.py \
  --annotations /path/to/satnav_datasets/SatNav-v0.1/trajectory_data/annotations.json \
  --output-root /path/to/satnav_datasets/SatNav-v0.1/trajectory_data \
  --source-episodes /path/to/satnav_datasets/SatNav-v0.1/episodes/train/all_episodes.json \
  --generation-config applications/episode_processing/configs/trajectory_generation.yaml \
  --scenes-dir /path/to/satnav_datasets/scenes \
  --expected-count 105164 \
  --decode-images \
  --report /path/to/satnav_datasets/validation/trajectory_data.json

The generated statistics for the complete train split should be:

Success (incl. cached): 105164
Discarded (max steps): 0
Failed: 0
Generated annotations: 105164 / 105164 episodes

7. Organize directories and configure SwiftVLN

After completing Episode, GeoTIFF and offline trajectory preparation, confirm that the directory structure is as follows:

satnav_datasets/
├── SatNav-v0.1/
│   ├── episodes/
│   │   ├── train/all_episodes.json
│   │   └── eval/
│   │       ├── val_seen/all_episodes.json
│   │       └── val_unseen/all_episodes.json
│   ├── scenes_list.yaml
│   ├── SHA256SUMS
│   └── trajectory_data/
│       ├── annotations.json
│       ├── summary.json
│       └── images/
└── scenes/
    ├── Amsterdam-1.tif
    └── ...

Set the data path in ${SWIFTVLN_ROOT}/.local/env.sh:

export SWIFTVLN_SATNAV_REPO="${SWIFTVLN_ROOT}/third_party/SatNav"
export SWIFTVLN_SATNAV_DATA_ROOT="/path/to/satnav_datasets"
export SWIFTVLN_SATNAV_DATASET="SatNav-v0.1"
export SWIFTVLN_SATNAV_TRAIN_DATA_PATH="${SWIFTVLN_SATNAV_DATA_ROOT}/${SWIFTVLN_SATNAV_DATASET}/trajectory_data"
export SWIFTVLN_SATNAV_TRAIN_EPISODES_PATH="${SWIFTVLN_SATNAV_DATA_ROOT}/${SWIFTVLN_SATNAV_DATASET}/episodes/train/all_episodes.json"
export SWIFTVLN_SATNAV_SCENES_DIR="${SWIFTVLN_SATNAV_DATA_ROOT}/scenes"

The data used in different training modes are as follows:

Training Mode	Required Data
`MEMORY_METHOD=history`	`annotations.json`, `images/`
`MEMORY_METHOD=map`	`annotations.json`, `images/`, `summary.json`, train Episode, `scenes/`

MEMORY_METHOD=map parses Episode and GeoTIFF according to the full directory structure above. After data configuration is completed, enter SwiftVLN training.