これは、このセクションの複数ページの印刷可能なビューです。 印刷するには、ここをクリックしてください.
Artefactsユーザーガイドへようこそ。このセクションでは、ロボティクスアプリケーションのテストにArtefactsを使用する方法を学ぶことができます。
多くの一般的なユースケースでは、有効な artefacts.yaml 設定ファイルがあれば、Artefactsは自動的に実行されます。これはArtefactsインフラストラクチャ上で実行する場合 (run-remote) と artefacts run --in-containerを使用する場合の両方に適用されます。Artefactsインフラストラクチャ上でのジョブ実行の詳細については、 cloud-simulation を参照してください。
ArtefactsはカスタムのDockerファイル設定もサポートしています。このガイドではArtefactsでスムーズに実行するための条件について説明します。
Artefactsクラウドシミュレーション (run-remote)上で実行する場合、または artefacts run --in-containerを使用する場合、現在、以下の状況ではカスタム Dockerfile またはイメージを指定する必要があります：
my-job:
type: test
package:
docker:
build: # Sample with a custom Dockerfile. Another option is to specify an image.
dockerfile: ./Dockerfile
Dockerfileの例は nav2サンプルプロジェクト で確認できます。
ROS2プロジェクトのベースレイヤーとして自由に使用できる多くのイメージを用意しています。これらのベースイメージには以下が含まれています：
humble-fortress には ros-humble-ros-core パッケージが含まれています)ros-humble-ros-ign-bridge など)catkin / colcon)rosdep の初期化と更新公開されているベースイメージの完全なリストは ECRパブリックレジストリで確認できます。以下の命名規則に従っています：
public.ecr.aws/artefacts/<framework>:<framework_version>-<simulator>-gpu
# -gpu is optional
# Examples:
public.ecr.aws/artefacts/ros2:humble-fortress
public.ecr.aws/artefacts/ros2:humble-fortress-gpu
gpu 対応イメージはartefactsインフラストラクチャ上で、NVIDIAのGPUで実行するように特別に設計されています。そのため、artefactsクラウドシミュレーション上で実行する際に追加の環境変数を設定する必要はありません。これらはamd64でのみ利用可能です（armでは利用できません）。
ローカルで実行している場合は、NVIDIA Container Toolkitをインストールし、いくつかの環境変数（‘ENV’）を設定する必要があるかもしれません。詳細については、NVIDIAの インストールガイド と ユーザガイド を参照してください。
これらのベースイメージを使用することで、プロジェクトのDockerfileは（最低限）以下の手順を実行する必要があります：
例として、ROS2 Humble / Ignition Fortressプロジェクトのartefactsで動作するDockerfileは以下のようになります：
# Use the artefacts ROS2 humble base image
FROM public.ecr.aws/artefacts/ros2:humble-fortress
# Set the working directory and copy our project
WORKDIR /ws
COPY . /ws/src
# ROS dependencies
RUN rosdep install --from-paths src --ignore-src -r -y
# Source ROS version and build
RUN . /opt/ros/galactic/setup.sh && colcon build --symlink-install
WORKDIR /ws/src
# Source colcon workspace and run the artefacts client
CMD . /ws/install/setup.sh && artefacts run $ARTEFACTS_JOB_NAME
現在、Dockerfileは2つの要件を満たす必要があります：
RUN pip install artefacts-cli
CMD artefacts run $ARTEFACTS_JOB_NAME
これは artefacts run <job_name> --in-container (ローカル) または artefacts run-remote <job_name> (クラウドシミュレーション)で実行できます。
artefacts run [jobname] を使用すると、テストはローカルで実行されます。しかし、テストに時間がかかる場合、例えば複数のパラメータ化されたシナリオがある場合は、Artefacts クラウドシミュレーション上で実行したいと思うかもしれません。
その場合は artefacts run-remote [jobname]を使用できます。ローカルコードがアーカイブファイルに圧縮され、実行のために当社のサーバーに送信されます。
以下は実行モデルの概要です。
graph TD
subgraph artefacts
ac(cloud simulation) --> dashboard(dashboard)
end
subgraph LocalMachine
lc(local code) -.-CLI
CLI --run_local-->dashboard
CLI --run_remote-->ac
end
lc --push--> github
github --pushEvent/pullCode--> ac
Artefacts クラウドシミュレーションでの実行時間は、使用量クォータに計上されます。
プロジェクト内にテスト実行に必要のないファイル（例：rosbags、一部のアセットなど）がある場合、アップロードするアーカイブファイルのサイズを小さく保つために、プロジェクトのルートに .artefactsignore ファイルを追加することができます。これは .gitignore ファイルと同じ方法で使用できます。例えば：
rosbags/
venv/
.DS_Store
これにより、 rosbags と venv フォルダ、および隠しファイル .DS_Store はバンドルされません。
Artefacts はいくつかのシミュレーターとフレームワークをすぐに使用できるよう対応しています。その場合、必要なのはテスト起動ファイルを提供するだけです ( Running and Tracking Tests を参照)
現在サポートされているのは：
runtime:
simulator: gazebo:fortress
framework: ros2:humble
runtime:
simulator: gazebo:harmonic
framework: ros2:humble
設定ファイルの runtime セクションでこれらが適切に指定されていることを確認してください ( 設定構文 を参照)。
また、（プロジェクトが ROS を使用していない場合など）Artefacts クラウドシミュレーション上で実行するための Docker パッケージを準備する 必要があるかもしれません。
ほとんどの場合、ランタイムブロックで使用するフレームワークとシミュレーターを指定するだけで十分です：
runtime:
simulator: gazebo:fortress
framework: ros2:humble
そしてテスト起動ファイルを提供するだけで、Artefacts は他の入力なしであなたのプロジェクトを構築してテストすることができます。しかし、一部のプロジェクトでは、いくつかのカスタマイズや微調整が必要な場合があることも理解しています。
これらのケースに対応するため、 artefacts.yaml ファイルの package['custom'] セクションで以下のキーを使用できます：
package:
custom:
os: # string
include: # List
commands: # List
os: 文字列 ベースイメージを入力します (例： ubuntu:22.04)。 これは framework と simulator の選択に基づいてArtefactsが使用するベースイメージをオーバーライドします。例：
package:
custom:
os: ubuntu:22.04
include: リスト デフォルトでは、Artefacts はGitHubリポジトリ（継続的インテグレーション）または現在の作業ディレクトリ（‘run-remote’）を再帰的にサーバー上で実行されているコンテナにコピーします。 include を使用して、コンテナで利用可能にしたいディレクトリ/ファイルを指定します。例：
package:
custom:
include:
- ./path/to/my_necessary_files
- ./makefile
commands: リスト プロジェクトのビルド段階の前に実行する追加のbashコマンドが必要な場合は、ここに入力します。一般的な使用例は、ros/gazeboプロジェクトを構築する際に、通常のros source に加えてカスタム source が必要な場合です。例：
package:
custom:
commands:
- source simulator/my_workspace/install/setup.bash
runtime:
framework: ros2:humble
simulator: gazebo:fortress
Artefacts クラウドシミュレーションは、新しいコードがリポジトリにプッシュされたときにテストジョブを実行できます。そのためには、お好みの CI ツールで run-remote をトリガーするだけです。
結果は他のジョブと同様にダッシュボードに表示されます。GitHub によってトリガーされたジョブには、コミット ID などの追加メタデータが含まれています。
継続的インテグレーションジョブの実行に問題がある場合は、まず ローカルでテストを実行 し、次に the tests can run on artefacts cloud を確認して、テストとパッケージが正しく動作していることを確認してください。
GitHub CI ワークフローの一部として Artefacts クラウドシミュレーションを統合したい方は、GitHub ワークフローに art-e-fact/action-artefacts-ci@main アクションを追加できます。このアクションには Python が必要であり、実行するためには（ダッシュボードから作成できる）Artefacts API キーも必要です。
基本的な例を以下に示します：
name: test
on: push
jobs:
test:
runs-on: ubuntu-latest
strategy:
matrix:
python-version: [3.11]
steps:
- uses: actions/checkout@v3
- name: Set Up Python ${{ matrix.python-version }}
uses: actions/setup-python@v4
with:
python-version: ${{ matrix.python-version }}
- uses: art-e-fact/action-artefacts-ci@main
with:
artefacts-api-key: ${{ secrets.ARTEFACTS_API_KEY }}
job-name: test_job
artefacts-api-key: 特定のプロジェクト用にダッシュボードで作成されます。job-name: artefacts.yaml ファイルで実行したいジョブと一致する必要があります。GitHub アクションは、プロジェクトの実行に必要な追加リポジトリがある場合に特に便利です。以下のアクションを使用して、Artefacts クラウドシミュレーションを実行する前にそのリポジトリをプロジェクトにクローンできます：
- name: Clone My Repo
uses: actions/checkout@v3
with:
repository: my-org/my-repo
token: ${{ secrets.MYREPO_PAT }} # if cloning a private repository
path: my-repo
ref: main
ROS2とTurtlesimシミュレーターを使用した例については、 example-turtlesim ご参照してください。 ROS1 noeticとTurtlesimシミュレーターを使用した例については、 demo-ros1-turtlesim を参照してください：Artefactプラットフォームを使用したシンプルなロボットのオドメトリ/位置推定アプリケーションの開発例です。
Artefactsクライアントは、 artefacts.yaml 設定ファイルのoutput_dirsで指定されたパスにあるすべてのファイルをアップロードします ( 設定構文を参照)。
ロボットシステムの開発中、開発者は新機能の開発やコンポーネントの統合のために多数のテストを実行します。このチュートリアルでは、Artefactsプラットフォームが具体的な例を用いて、以下の3つの一般的なユースケースによりロボット開発をより効率的にする方法を紹介します：
ロボティクスのユースケースに関連しながらも、最小限のコードで設定不要なチュートリアルを提供するため、ROS1とそのシンプルなturtlesimシミュレータを用いた参照実装を構築しました。
ここで紹介するArtefactsの概念はすべて、ROS1やturtlesimの例を超えて一般的に適用できます。これらはあなた自身のユースケースの参考やレシピとして機能することを意図しています。
以下の各例には、テストの根拠 + テスト説明 + テスト結果が含まれており、Artefactsを活用する方法について明確なガイダンスを提供しています。このチュートリアルでは実装の詳細を最小限に抑えていますが、すべてのユースケースをサポートするデモコードは[demo-ros1-turtlesim]で確認できます。
チュートリアルの例は概念の複雑さに応じて段階的に進むよう選ばれているため、順番に従うことをお勧めします。ROS1とturtlesimの事前知識があることを前提としています。
根拠： 複雑なシステムにおけるベストプラクティス：既に実装された機能が後続の実装によって劣化しないことを保証するテストを定義すること：回帰テスト。
テスト説明: 主な特徴は、テストが自動的に最初から最後まで実行され、合格/不合格をArtefactsダッシュボードに報告できることです。
この例では、以下のように回帰テストを定義します：
テストのセットアップ:
rostestとArtefactsのセットアップは簡単です:
rostest テストクラスを作成する。
unittest.TestCase を継承する。setUp() メソッドを提供する。例えば、ロボットを開始位置に配置し、テストに必要なリソースを準備する。test_mytest() メソッドを提供する。tearDown() メソッドを提供する。.launch ファイルのartefacts.yaml ファイルを作成する。 参照例を参照。以下のようにシンプルにできます：project: demo-ros1-turtlesim
jobs:
turtle_regression:
type: test
runtime:
simulator: turtlesim
framework: ros1:noetic
scenarios:
settings:
- name: simple_regression_test
ros_testpackage: turtle_simple
ros_testfile: turtle_simple.launch
このテストの実行は、以下の3つの方法のいずれかで行えます：
artefacts run rover_trajectoryartefacts run-remote rover_trajectoryまとめ：
回帰テストについては：これらのテストを継続的インテグレーションパイプラインに含めることで、新しい開発が以前に機能していた機能を壊した場合にアラートが発生することを保証できます。
より一般的には、このシンプルなセットアップは実際に、Artefactsの使用と任意の種類のテストの作成に関する基本的な内容をすべてカバーしています：
rostest と unittestを使用しました。 ArtefactsはROS2と launch_test （およびその他のフレームワーク）もサポートしています。Artefactsの重要な機能は、多数（本当に多数！）のテストを簡単に調整できることです：この例では、YAML設定ファイルに1つの追加概念（パラメータのリスト）を加えるだけで、50のテストを自動的に実行します。
また、 rosbag_postprocess スクリプトを使用して各テストの終了時にテスト指標を自動的に計算する方法も紹介します。
根拠： 50のテストを実行することで、シミュレーションやテスト設定の非決定的な側面を特定し定量化することができます。これは再現性テストと呼ばれます。同一のパラメータでテストを実行した際の指標のばらつきを定量化することで、将来の実装が実際に計算された指標の改善/劣化につながるのか（あるいは単に統計的なばらつきの影響なのか）を適切な確信度で結論付けることができます。
テスト説明：
この例は前述のturtlesimの正方形軌道の上に構築しています。
この再現性テストをより現実的にするため、シミュレートされたホイールオドメトリセンサーを作成し、そこから亀の位置を計算するノードを追加します (see turtle_odom.py参照)。これは、IMUとモーターエンコーダデータをカルマンフィルターに融合したり、SLAMを実装したり、その他の位置推定フレームワークを使用したりする可能性のあるロボティクスアプリケーションに関連するスタンドインです。
各テスト実行について、以下のようなさまざまな指標を計算し、実行ごとにどのように変化するかを確認します：
cumulative distance_final: テスト中に亀が移動した総距離（グラウンドトゥルース）error horizontal final: 軌道の終了時における、推定された亀のx位置とy位置とグラウンドトゥルースとの間の誤差（ユークリッド距離、メートル単位）error orientation final: 軌道の終了時における、推定された亀のヨー（向き）方向とグラウンドトゥルースとの間の誤差（絶対値、度単位）time delta max: 各推定メッセージとグラウンドトゥルースメッセージ間の最大タイムスタンプ不一致。低い値は誤差指標が一貫して計算されることを保証します。テストのセットアップ：
Artefactsを使用すると、わずかな追加手順だけで済みます：
artefacts.yamlを以下のように設定します：
rosbag_record キーを追加rosbag_postprocessキーを追加params キーの下に、X個のダミー値のリストを持つダミーパラメータを追加artefacts.yaml ファイルの参照例 を参照してください。以下のようにシンプルにできます：
project: demo-ros1-turtlesim
jobs:
turtle_repeat:
type: test
runtime:
simulator: turtlesim
framework: ros1:noetic
scenarios:
settings:
- name: turtle_repeatability
ros_testpackage: turtle_odometry
ros_testfile: test_odometry.launch
rosbag_record: all
rosbag_postprocess: turtle_post_process.py
params:
dummy: [0, 0, 0, 0, 0, 0, 0, 0, 0, 0] # Artefacts will run 10 scenarios, each with the value from this parameter list
このテストはローカル (artefacts run turtle_repeatability) またはArtefactsインフラで実行できます。どちらの場合も、Artefactsは10のテストを順番に自動的に実行します。その後、各テストの結果はArtefactsダッシュボードのクラウドにログ記録されます。
Artefactダッシュボードはテスト中に作成されたすべてのファイルを、豊富な視覚化をサポートして表示します。特に、HTML形式のグラフ (例 plotly製)が表示されます。
Artefactsダッシュボードから、灰色の矢印ボタンをクリックすると、すべてのシナリオの結果をCSVでエクスポートしてさらに分析することができます。
テスト結果：
シンプルな分析 ( jupyter notebookの例を参照)では、各指標の統計を計算しグラフを作成します：
シミュレーションの非決定的な性質により、まったく同じ条件で実行されたテストの指標でも変動が生じます。
これらの変動は、後続のテストで誤った結論に達しないように定量化することが重要です：
まとめ
YAML設定ファイルにXパラメータをリストとして指定するだけで、Artefactsは自動的にXテストを実行し、すべての結果をArtefactsダッシュボードに保存します。
後処理スクリプトを指定するだけで、Artefactsは各テストの終了時にそれを実行し、結果の指標を各テストのArtefactダッシュボードにアップロードできます。
テスト中に作成されたすべてのファイルは、豊富な視覚化サポートとともにアップロードされます。これにより、より深い洞察を得るためのテスト結果のインタラクティブな探索が可能になります。
根拠：
従来、ロボティクスにおけるパラメータ調整は時間がかかり、エラーが発生しやすい理由は以下の通りです：
Artefactsは、テストの各側面を指定し、パラメータ化し、パラメータセット間で自動的にグリッド検索を実行しながら、すべての結果をログに記録し、中央ダッシュボードに表示するフレームワークを提供します。
テスト説明： この例は前述のturtlesimの再現性テストの上に構築しています。
今回の目標は、実際に亀の位置推定精度を向上させることです。具体的には、 horizontal error final と orientation error final の2つの指標を最小化することです。
この例では、調整可能なパラメータは odom_tuning_theta と odom_tuning_forwardの2つだけで、これらは亀のモックセンサーを使用したオドメトリ計算に影響します
これら2つのパラメータそれぞれに10個の値をテストすると、すでに100の組み合わせになります。これは従来の/手動テスト設定では扱いにくいでしょう！しかし、Artefactsを使えば簡単に設定でき、昼食時にテストを実行させ、その後Artefactsダッシュボードで結果を確認できます。
テストのセットアップ：
上記の2つのテスト設定を基に、さらに2つの要素を実装するだけです：
artefacts.yaml に渡された各パラメータはArtefactsによってROS rosparam サーバーで利用可能になります。そのため、起動時に rosparam サーバーをチェックするための数行をオドメトリノードに追加するだけです(rospy.get_param('test/odom_tuning_theta')).artefacts.yaml に追加します。これらはArtefactsによって実装された自動グリッドカバレッジの基礎として機能します：パラメータの組み合わせごとにテストシナリオがトリガーされます (完全な例)。 例えば、以下の.yamlでは102=10010^2 = 100
102=100のテストシナリオが作成されます！project: demo-ros1-turtlesim
jobs:
turtle_grid:
type: test
runtime:
simulator: turtlesim
framework: ros1:noetic
scenarios:
settings:
- name: turtle_gridsearch
ros_testpackage: turtle_odometry
ros_testfile: turtle_odometry.launch
rosbag_record: all
rosbag_postprocess: turtle_post_process.py --skip_figures
params:
test/odom_tuning_theta: [0.001, 0.0025, 0.005, 0.01, 0.025, 0.05, 0.075, 0.1, 0.25, 0.5]
test/odom_tuning_forward: [0.001, 0.0025, 0.005, 0.01, 0.025, 0.05, 0.075, 0.1, 0.25, 0.5]
テスト結果:
Artefactsダッシュボードからジョブ結果をCSVとしてダウンロードした後、各シナリオの関心のある2つの指標をプロットできます (jupyterノートブック参照)：
ここでは値が低いほど良く、目標は両方の指標を共同で最小化することです。 両方の指標にわたって結果を比較することをより実用的にするために、性能指標（figure of merit）を定義するのが一般的です：
$FoM = \displaystyle\sum_i w_i * m_i$ ここで各 $w_i$ は各指標 $m_i$ に割り当てられた重みです
これらはプロジェクトの目標に従って選択すべきです（例えば、方向誤差を最小化することと水平誤差を最小化することのどちらが重要か？）。ここでは、方向誤差1度が水平誤差10cmに相当すると選択します。 次に、100のシナリオそれぞれの性能指標をプロットします：
パラメータの関数として性能指標をプロットすることで、検索内でのトレンドを見つけることができます。ここでは、両方のパラメータの値が低いほど性能指標が低くなり、以下の図に示されています：
最高の位置推定精度につながるパラメータは次のとおりです：
まとめ
この例では、一度だけの設定後、Artefactsに単一のコマンドで100のテストを実行するよう指示しました。その後、計算されたすべての指標をCSVとしてエクスポートし、これを使用して亀の位置推定アルゴリズムを調整するための最適なパラメータセットを特定しました。この方法論は、多くの異なるパラメータ値を試す必要のあるあらゆる種類のアルゴリズムの調整に適用できます。
このチュートリアルでは、一般的なロボティクス開発のユースケースでArtefactsを使用する方法を説明しました：
rostest でテストを記述し、ローカルとArtefactsインフラのクラウドの両方で自動的に実行する方法。