# Lite3 Nav2 ルートテスト

> Newton 上の DeepRobotics Lite3 四足歩行ロボットで、記録したルートを Nav2 で走行させるテスト

---

Site [llms.txt](/ja/llms.txt)

---

> [!NOTE]
> このページは機械翻訳です。正確な内容は[英語版](/example-projects/lite3/)を参照してください。

[デモはこちら](https://app.artefacts.com/artefacts-demos/lite3-navigation-demo)。注：登録が必要です。
[コードはこちら](https://github.com/art-e-fact/lite3-navigation-demo)

## 概要

[Lite3](https://www.deeprobotics.us/products/lite-3/) は DeepRobotics 製の四足歩行ロボットです。SDK は[こちら](https://github.com/DeepRoboticsLab/sdk_deploy)で公開されていますが、このデモでは独自の[フォーク](https://github.com/art-e-fact/sdk_deploy/tree/core-only)を使用します。このフォークは、`/cmd_vel` を関節指令に変換する歩行コントローラを提供します。

このデモでは、rviz 上で `artefacts-route` レコーダーを使って記録したルートに沿って、[Nav2](https://docs.nav2.org/) が Lite3 を走行させます。シミュレーション世界は、ルートの地図を押し出して生成します。テストはロボットがすべてのウェイポイントに到達することを検証し、歩行速度でパラメータ化して、Lite3 がどれだけ速くルートを追従できるかを確認します。

![](/images/example-projects/lite3/lite3-follow.gif)

このプロジェクトは以下を使用して実行されます：

* [Newton](https://github.com/newton-physics/newton)（シミュレータ）、Lite3 と 2D LiDAR 付き
* [ROS 2](https://docs.ros.org/en/jazzy/) Jazzy と [Nav2](https://docs.nav2.org/)（ナビゲーション）、経路追従コントローラは Regulated Pure Pursuit
* [pytest](https://docs.pytest.org/en/stable/)（テストの記述）
* [artefacts-toolkit-navigation](/artefacts-toolkit/navigation)（ルートの記録、世界の生成、ルートの走行）
* [Artefacts](https://www.artefacts.com/)（テストの自動化と結果のレビュー）

## ルートの記録

ルートとは、地図上の開始姿勢と順序付きのウェイポイントのリストです。RViz 上で手動で一度だけ記録します：

```
artefacts-route record --map src/nav2_demo/maps/depot.yaml
```

地図を表示した RViz が開きます。**2D Pose Estimate** でロボットのスポーン（開始）位置を設定し、**Publish Point** でウェイポイントを順に追加します。ターミナルで Enter を押すと、ルートが `routes/` 以下に保存されます（`--name` でファイル名を指定できます）。テストは常に最後に記録されたルート（`.latest` として保存）を走行します。

![](/images/example-projects/lite3/lite3-recorded-route.png)

このデモで使用するルートは Nav2 の `depot` 地図上のもので、ウェイポイントは 3 つ、歩行距離は約 9 m、最初の 2 つのウェイポイントで 90 度の旋回があります。

```yaml
format_version: 1
name: 2026-10-20_09-57-23
recorded_at: '2026-10-20T00:58:12+00:00'
ros_distro: jazzy
frame_id: map
map:
  file: src/nav2_demo/maps/depot.yaml
  sha256: 8cd5c8d2cbeaf406d6d5312958cd70b64764726e4acd08ec57b9b5348f2a4544
initial_pose: {x: 9.7662, y: -6.3585, yaw: 0.0}
waypoints:
  - {x: 12.4948, y: -6.4473, yaw: 1.5278}
  - {x: 12.6235, y: -3.4588, yaw: -3.1244}
  - {x: 9.8225, y: -3.507, yaw: -3.1244}
```

## テストの記述

テストファイル [`test_route.py`](https://github.com/art-e-fact/lite3-navigation-demo/blob/main/src/nav2_demo/test/test_route.py) は、モジュールスコープの pytest フィクスチャの中でルートを一度だけ走行させます。このフィクスチャは：

1. **ルートを読み込む**：`load_route()` で最後に記録されたルートを読み込みます。
2. **世界を生成する**：`map_to_world()` でルートの地図から 2D 地図を 3D シーンに押し出します。世界は実行のたびに新しく生成され、実行結果と一緒にアップロードされます。
3. **シミュレータを起動する**：`route_launch_args()` で開始姿勢をシミュレータの `--set` オーバーライドに変換し、Lite3 をルートの開始姿勢にスポーンします。追従カメラと俯瞰ビューの 2 台のカメラが動画を記録します。
4. **歩行コントローラと Nav2 を起動する**：シミュレータの時計が進み始めたら、ルートの地図上で起動します。Nav2 はロボットが立ち上がってから起動します。
5. **ルートを走行する**：`follow_route()` でウェイポイントを Nav2 に送り、各ウェイポイントに到達したか、どれだけ近づいたか、リカバリーが（あれば）何回必要だったかを報告します。
6. **アップロード用のデータを作成する**：成否にかかわらず、オドメトリの軌跡を CSV で、3 つのチャート、`metrics.json` を出力します。

5 つのテストが、[ナビゲーションツールキットのアサーションヘルパー](/artefacts-toolkit/navigation/#assert_route_completed)を使って `RouteResult` を検証します：

```python
def test_route_completed(run):
    try:
        assert_route_completed(run.result)
    except AssertionError as error:
        pytest.fail(f'{error}\n--- nav log ---\n{run.harness.control_log_tail(40)}')


def test_each_waypoint_reached(run):
    assert_each_waypoint_reached(run.result, tolerance_m=WAYPOINT_TOLERANCE_M)  # 0.5 m


def test_final_pose(run):
    assert_final_pose(run.result, max_pos_error_m=MAX_FINAL_ERROR_M)  # 0.5 m


def test_min_clearance(run):
    assert_min_clearance(run.result, MIN_CLEARANCE_M)  # 0.2 m from the lidar, roughly the body's half width


def test_max_recoveries(run):
    assert_max_recoveries(run.result, MAX_RECOVERIES)  # 2
```

## artefacts.yaml ファイル

```yaml
project: artefacts-demos/lite3-navigation-demo
version: 0.1.0

jobs:
  test-nav2-route:
    type: test
    timeout: 15 # minutes
    runtime:
      framework: other
      simulator: newton

    scenarios:
      defaults:
        metrics: metrics.json
        params:
          headless: false  # false shows the Newton viewer
          rviz: true  # true also opens Nav2's RViz view
          linear_vel: [0.2, 0.3, 0.4]  # m/s, one run per value (velocity_smoother caps at 0.4)
      settings:
        - name: nav2_route
          pytest_file: src/nav2_demo/test/test_route.py
```

上記のポイント：

* テストは `linear_vel` の値ごとに 1 回、計 3 回実行されます。この値は Nav2 の `FollowPath` コントローラが要求する速度を設定します。
* `metrics.json` はアップロードされ、Artefacts ダッシュボードに表示されます。
* `pytest_file` は Artefacts にテストファイルの場所を指定します。

詳細は[シナリオ設定](/configuration/artefacts-yaml/#scenario)を参照してください。

## 結果

ジョブはシナリオを `linear_vel` ごとに 1 回、計 3 回実行します。以下のスクリーンショットではすべて成功しています。上部のチャートは各実行の `duration_s` をプロットしたもので、Lite3 は 0.2 m/s で約 52 秒、0.3 m/s で約 40 秒、0.4 m/s で約 32 秒でルートを歩行しています。

![](/images/example-projects/lite3/dashboard-summary.png)

実行を展開すると、メトリクスと 5 つのテスト結果が並んで表示されます。**Compare Runs** では 3 つの速度を横に並べて比較できます。0.2 m/s では、Lite3 は 3 つのウェイポイントすべてに到達し、最終ウェイポイントから 0.23 m の位置で停止し、最も近い壁からは常に 0.35 m 以上離れていました：

![](/images/example-projects/lite3/lite3-dashboard-metrics-andassertions.png)

### ルートの完走

ウェイポイントごとのチャートは、各ウェイポイントにどれだけ近づいたかと、そこに至るまでの壁との最小クリアランスを示します：

![](/images/example-projects/lite3/lite3-waypoints-chart.png)

### 地図上の経路

経路チャートは、ロボットのオドメトリ軌跡と Nav2 の計画経路を地図に重ねて表示し、ルートと実際に走行した経路を比較できます：

![](/images/example-projects/lite3/lite3-path-chart.png)

### 動画

シミュレータは各実行について、追従カメラと俯瞰ビューの 2 本の動画を記録します：

| 追従カメラ | 俯瞰ビュー |
|--------|----------|
| ![](/images/example-projects/lite3/lite3-follow.gif) | ![](/images/example-projects/lite3/lite3-overhead.gif) |

## テスト後に利用できるデータ

テストが実行のアップロードディレクトリ（`ARTEFACTS_SCENARIO_UPLOAD_DIR`）に書き込んだものはすべて Artefacts ダッシュボードにアップロードされます。

![](/images/example-projects/lite3/lite3-dashboard-uploads.png)

* 地図から押し出した世界（MJCF）とシミュレータの設定
* ルート結果（YAML）
* 2 本の動画：追従カメラと俯瞰ビュー
* オドメトリの軌跡（CSV）
* HTML のチャート：地図上の経路、速度の時間変化、ウェイポイントごとの数値
* メトリクス（`json` 形式）
* シミュレータと Nav2 起動のログ

## Artefacts Toolkit ヘルパー

このプロジェクトでは、[Artefacts Toolkit](/artefacts-toolkit) から以下のヘルパーを使用しました：

* [`get_artefacts_params`](/artefacts-toolkit/config/#get_artefacts_params)：このシナリオの `headless`、`rviz`、`linear_vel` の読み取り
* [`artefacts-route record`](/artefacts-toolkit/navigation/#recording-a-route)：RViz でのルートの記録
* [`load_route`](/artefacts-toolkit/navigation/#load_route)：最後に記録したルートの読み込み
* [`map_to_world`](/artefacts-toolkit/navigation/#map_to_world)：ルートの地図からシミュレータ世界を押し出して生成
* [`route_launch_args`](/artefacts-toolkit/navigation/#route_launch_args)：ルートの開始姿勢へのロボットのスポーン
* [`follow_route`](/artefacts-toolkit/navigation/#follow_route)：Nav2 へのルートの送信と結果の収集
* [`assert_route_completed`](/artefacts-toolkit/navigation/#assert_route_completed) などの `assert_*` ヘルパー：ルート結果に対するすぐに使える検証