Platform Guide

Customize the ocean-environment dataset, export portable variants, and run marine-robotics tasks across quantitative and scene-backed backends.

Quickstart Pipeline Backends Publish

Tip: you can either download the released dataset (recommended for starting) or generate a custom dataset with the pipeline below.

Quickstart

This is the shortest path from a dataset file to a first benchmark run. All commands are run from the repository root.

Start from the released dataset

Download a prebuilt combined_environment.nc from Zenodo or Hugging Face and place it under: Data_pipeline/Data/Combined/.

Zenodo · Hugging Face

Run a first core-backend task

Export a drift cache from the dataset, then run a canonical navigation task. 

python -m benchmark_core.cli.export_drift_cache \\
  --nc Data_pipeline/Data/Combined/combined_environment.nc \\
  --u-var utotal --v-var vtotal --time-index 0 --depth-index 0 \\
  --out runs/benchmark_core/_cache/drift_t0_d0.npz

python -m benchmark_core.cli.run \\
  --drift-npz runs/benchmark_core/_cache/drift_t0_d0.npz \\
  --task go_to_goal_current \\
  --controller go_to_goal \\
  --difficulty medium \\
  --n-agents 1 \\
  --episodes 10 \\
  --seed 0 \\
  --out-dir runs/benchmark_core/quickstart

If your dataset does not include tides, replace utotal/vtotal with uo/vo in the drift-cache export command.

Where do the dataset files live? The pipeline writes to Data_pipeline/Data/. The released dataset mirrors that layout so you can run without refetching upstream data.

Pipeline

The OneOcean pipeline produces a canonical combined_environment.nc (terrain + currents + masks), then exports portable variants for debugging, scene grounding, and public release.

CMEMS ocean fields
so, thetao, uo, vo, zos (+ optional tides)
→
GEBCO GeoTIFF
bathymetry / terrain crop
Data_pipeline/run_pipeline.py
align · interpolate · merge · compress
→
combined_environment.nc
time × depth × lat × lon
generate_variants.py
tiny · scene · public
→
Tasks + backends
benchmark_core + OceanGym scenes

Customize region, time, depth

Use --lat-min/--lat-max/--lon-min/--lon-max and --start/--end to define the spatiotemporal slice. Depth can be specified as a range or a concrete list. 

python Data_pipeline/run_pipeline.py --overwrite \\
  --lat-min 32.0 --lat-max 33.0 --lon-min -66.5 --lon-max -65.5 \\
  --start 2024-06-01T00:00:00 --end 2024-06-30T00:00:00 \\
  --depths \"0,10,20,50,100,200\" \\
  --include-tides

If tides are surface-only, the pipeline applies a configurable depth profile (default: exponential decay). This is an engineering approximation.

Export dataset variants

Variants are written under Data_pipeline/Data/Combined/variants/. Each variant includes a small variant.json manifest for auditability. 

python Data_pipeline/generate_variants.py \\
  --which tiny,scene,public \\
  --overwrite
tiny
fast iteration + web assets
scene
main scene/task grounding tier
public
broader coverage, lighter resolution

Credentials: CMEMS access uses COPERNICUSMARINE_USERNAME and COPERNICUSMARINE_PASSWORD. GEBCO GeoTIFF tiles must be available under Data_pipeline/Data/.

Backends: quantitative + scene-backed

OneOcean supports a fast quantitative backend for scalable benchmarking and a packaged scene-backed backend for underwater deployment and media generation.

Core benchmark backend (benchmark_core)

Export a drift cache (.npz) from combined_environment.nc, then run tasks with shared metrics and reproducible manifests. 

python -m benchmark_core.cli.export_drift_cache \\
  --nc Data_pipeline/Data/Combined/variants/scene/combined/combined_environment.nc \\
  --u-var utotal --v-var vtotal --time-index 0 --depth-index 0 \\
  --out runs/benchmark_core/_cache/drift_scene_t0_d0.npz

python -m benchmark_core.cli.run_matrix \\
  --drift-npz runs/benchmark_core/_cache/drift_scene_t0_d0.npz \\
  --preset paper_v1 \\
  --dynamics-model 6dof \\
  --constraint-mode hard \\
  --bathy-mode hard \\
  --validate

OceanGym scene backend (tracks/oceangym_benchmark)

Export a time series of data-grounded currents (.npz) and run the scene task suite (e.g., plume localization/containment, multi-agent formation). 

python tracks/oceangym_benchmark/export_current_series_npz.py \\
  --dataset Data_pipeline/Data/Combined/combined_environment.nc \\
  --out_npz runs/_cache/data_grounding/currents/cmems_center_uovo.npz

python tracks/oceangym_benchmark/run_task_suite.py \\
  --preset ocean_worlds_camera \\
  --episodes 3 \\
  --current_npz runs/_cache/data_grounding/currents/cmems_center_uovo.npz

This backend assumes you have a working HoloOcean client and packaged worlds installed locally.

Choosing a backend: use benchmark_core for scalable comparisons and paper tables; use oceangym_benchmark when you need scene semantics, screenshots, GIFs, and MP4s.

Publish & reuse

The safest way to help others reproduce your results is to share (1) dataset artifacts, (2) the run manifests produced by the backends, and (3) the exact commands you used.

Recommended artifact bundle

  • combined_environment.nc (or the relevant variant)
  • variants/<tier>/variant.json manifest
  • runs/benchmark_core/**/results_manifest.json
  • runs/oceangym_benchmark/**/media/ screenshots, GIFs, MP4s

Deploy this page on GitHub Pages

This repository serves the website from docs/. Updating docs/index.html and docs/platform/index.html is enough to publish changes.

If the page looks stale after pushing, wait a few minutes for Pages to rebuild, then hard-refresh the browser cache.

Back to project page