Skip to content

Autoware Quickstart

This is the shortest supported path from lidarslam_ros2 to an Autoware pointcloud map shown in rviz2.

If you want the product-level overview first, see Autoware-Compatible Map Authoring. For the optional browser-based viewer path, see Autoware Foxglove.

Before choosing a workflow for an arbitrary bag, run:

python3 scripts/preflight_autoware_map_bag.py /path/to/rosbag2

If you want the shortest beginner-facing entrypoint, run:

bash scripts/run_autoware_map_beginner.sh /path/to/rosbag2

If you want the repository to pick and run the shortest supported path from the same preflight result, use:

python3 scripts/run_autoware_map_from_bag.py /path/to/rosbag2

For Livox/MID360-style bags, this runner automatically switches to the tracked MID360 preset and writes verify_autoware_map.log plus a diagnosis report into the output directory.

The fixed public entrypoint for this flow is:

bash scripts/run_autoware_quickstart.sh

Scope

This quickstart covers pointcloud maps only.

  • lanelet2_map.osm is out of scope.
  • Without GNSS the generated map_projector_info.yaml uses projector_type: Local.
  • With GNSS enabled and a stable origin, the same file uses projector_type: LocalCartesian plus map_origin.

Prerequisites

  • ROS 2 workspace builds successfully.
  • Host has docker, ros2, rviz2, and a working X11 DISPLAY.
  • For the Docker viewer flow, an autoware_core checkout is available.
  • For the bundled NTU VIRAL dogfood path, prepare the sample bag once with bash scripts/download_ntu_viral_tnp01.sh.

Recommended build check:

colcon build --symlink-install --cmake-args -DCMAKE_BUILD_TYPE=Release
bash scripts/run_default_ci_checks.sh

Fastest Paths

1. Run the fixed public quickstart

If you want the shortest end-to-end supported path:

bash scripts/download_ntu_viral_tnp01.sh
bash scripts/run_autoware_quickstart.sh

This runs the bundled NTU VIRAL dogfood path with a bounded viewer lifetime. Under the hood it forwards to run_rko_lio_graph_autoware_dogfood.sh.

2. Open an existing graph_based_slam output in Autoware

If you already have a saved graph_based_slam run under output/...:

bash scripts/run_autoware_quickstart.sh \
  output/bench_rko_lio_ntu_viral_loopgate_20260324

This stages the bundle under /tmp/autoware_maps/<run_name>, verifies it, and opens the pointcloud map through Autoware's Dockerized map loaders. The wrapper for this path is run_graph_slam_pointcloud_map_in_autoware.sh.

3. Use the explicit dogfood subcommand

If you want to stay on the public wrapper but pass dogfood-specific options:

bash scripts/run_autoware_quickstart.sh dogfood \
  --wait-for-offline-completion \
  --auto-exit-secs 20

4. Stage a run manually and smoke-test the map loaders

If you want to inspect the staged bundle before opening rviz2:

bash scripts/prepare_autoware_map_from_graph_slam.sh \
  output/bench_rko_lio_ntu_viral_loopgate_20260324 \
  /tmp/autoware_maps/ntu_viral_loopgate \
  --smoke \
  --autoware-core-dir /tmp/autoware_core \
  --work-dir /tmp/autoware_map_runtime_ws

Then open the viewer:

bash scripts/run_autoware_pointcloud_map_viewer_docker.sh \
  /tmp/autoware_maps/ntu_viral_loopgate \
  /tmp/autoware_core \
  /tmp/autoware_map_runtime_ws

What Success Looks Like

You should see all of the following:

  • python3 scripts/verify_autoware_map.py <map_dir> reports RESULT: PASS
  • Docker-side Autoware map loaders start without early exit
  • host-side rviz2 subscribes to /map/pointcloud_map
  • frame_id is map

Useful outputs:

  • staged map bundle: /tmp/autoware_maps/<name>
  • saved SLAM run: output/dogfood_rko_lio_autoware_<timestamp>/
  • Autoware smoke logs: inside the chosen runtime work directory

Troubleshooting

RViz opens but no pointcloud appears

  • Confirm DISPLAY works on the host.
  • Confirm Docker can reach the host X server.
  • Re-run with --viewer-rebuild if the local runtime image is stale.

Map bundle fails verification

Run:

python3 scripts/verify_autoware_map.py /path/to/pointcloud_map

Common causes:

  • float tile coordinates in pointcloud_map_metadata.yaml
  • missing map_projector_info.yaml
  • orphan or missing PCD tiles

GNSS map origin does not appear

This is expected when GNSS is disabled. The map stays valid for Autoware with:

projector_type: Local

A run finished but the result still looks suspicious

Write a short diagnosis report from the saved output directory:

python3 scripts/diagnose_autoware_map_run.py output/<run_dir> --write

This summarizes launch status, verify results, projector metadata, and common failure hints such as TF issues or missing GNSS edges.

  • bag preflight: python3 scripts/preflight_autoware_map_bag.py /path/to/rosbag2
  • beginner wrapper: bash scripts/run_autoware_map_beginner.sh /path/to/rosbag2
  • one-shot runner: python3 scripts/run_autoware_map_from_bag.py /path/to/rosbag2
  • public Autoware entrypoint: bash scripts/run_autoware_quickstart.sh
  • benchmark path: bash scripts/run_rko_lio_graph_benchmark.sh
  • release gate: bash scripts/run_release_readiness_checks.sh --ape-threshold 0.10
  • map-only verify: python3 scripts/verify_autoware_map.py <pointcloud_map_dir>
  • run diagnosis: python3 scripts/diagnose_autoware_map_run.py <output_dir>