Installation Guide¶

This page describes the installation and configuration of the NavArena embodied navigation infrastructure. NavArena uses a uv workspace to manage four sub-projects: Core Library (navarena-core), Asset Preprocessing (navarena-forge), Data Generator (navarena-gen), and Evaluation Framework (navarena-bench).

System Requirements¶

Before starting, ensure your system meets the following requirements:

Choosing an Installation Method¶

flowchart TD
    Start[Choose installation method] --> Q1{Need exact reproduction?}
    Q1 -->|Yes| Lock[Section 1: Quick Install\nUse environment.yml or requirements-lock.txt]
    Q1 -->|No| Q2{Have uv installed?}
    Q2 -->|Yes| UV[Section 2: uv workspace\nNote: Install PyTorch first]
    Q2 -->|No| Lock

Version Strategy¶

NavArena provides two primary installation paths for different needs:

1. Quick Install (Exact Reproduction)¶

Install from lock files to guarantee exact match with the verified environment:

# Create environment with Python 3.9 + Node.js + all pip packages
conda env create -f environment.yml
conda activate navarena

# Install core library in editable mode
pip install -e "navarena-core[rendering,export]"

# Optional: install CLIP (for semantic detection, requires GitHub access)
pip install git+https://github.com/ultralytics/CLIP.git

conda create -n navarena python=3.9 nodejs -c conda-forge -y
conda activate navarena
pip install -r requirements-lock.txt

# Install core library in editable mode
pip install -e "navarena-core[rendering,export]"

# Optional: install CLIP (for semantic detection, requires GitHub access)
pip install git+https://github.com/ultralytics/CLIP.git

2. Install via uv Workspace¶

If you have uv installed, use workspace mode to install all sub-projects at once:

# Tested: torch==2.8.0+cu128, torchvision==0.23.0
pip install "torch>=2.8.0,<3.0" "torchvision>=0.23.0,<1.0" \
    --index-url https://download.pytorch.org/whl/cu128

cd NavArena

# Install uv (if not installed)
curl -LsSf https://astral.sh/uv/install.sh | sh

uv sync --all-packages

# Or use Makefile
make install

3. Data and Environment Variables¶

3.1 Set NAVARENA_DATA_DIR¶

NavArena uses NAVARENA_DATA_DIR as the unified data root directory:

# Copy environment template
cp .env.example .env

# Edit .env to set data directory
# NAVARENA_DATA_DIR=/path/to/your/navarena-data-root

Or set the environment variable directly:

export NAVARENA_DATA_DIR=/path/to/your/navarena-data-root

3.2 Data Directory Structure¶

NAVARENA_DATA_DIR should contain the following subdirectories (symlinks are fine):

$NAVARENA_DATA_DIR/
├── assets/       # 3DGS scene assets (PLY files, occupancy grids, etc.)
│   ├── x2robot/
│   │   └── 17dc3367/
│   └── sage-3d/
│       └── 00666b7a/
├── datasets/     # Generated datasets (Parquet format)
└── shared/       # Shared resources
    ├── camera.yaml                    # Camera configuration
    └── visualnav-transformer/         # ViNT model weights (optional)

3.3 CUDA Setup¶

Ensure CUDA environment variables are correctly set:

export CUDA_HOME=/usr/local/cuda
export PATH=$CUDA_HOME/bin:$PATH
export LD_LIBRARY_PATH=$CUDA_HOME/lib64:$LD_LIBRARY_PATH

4. Verify Installation¶

4.1 Python Package Import Test¶

python -c "
import torch
print(f'PyTorch: {torch.__version__}')
print(f'CUDA available: {torch.cuda.is_available()}')
print(f'CUDA version: {torch.version.cuda}')

import navarena_core
print(f'navarena-core: OK')

import gsplat
print(f'gsplat: OK')

import open3d
print(f'open3d: {open3d.__version__}')

import duckdb
print(f'duckdb: {duckdb.__version__}')
"

Expected output (versions may vary slightly depending on installation method):

PyTorch: 2.8.0+cu128
CUDA available: True
CUDA version: 12.8
navarena-core: OK
gsplat: OK
open3d: 0.19.0
duckdb: 1.4.4

4.2 Run Examples¶

Run the following from the NavArena repository root with NAVARENA_DATA_DIR set:

# Data generator help
python navarena-gen/scripts/generate_data.py --help

# Generate PointNav data (example)
python navarena-gen/scripts/generate_data.py --config navarena-gen/configs/examples/pointnav_example.yaml

# Launch Web Viewer (data dir from env or via --data-dir)
python navarena-gen/scripts/run_viewer.py --data-dir $NAVARENA_DATA_DIR
# Open http://localhost:5173 in your browser

5. FAQ¶