Artefacts ツールキットの設定ヘルパー

Tags:

Toolkit, Configuration

Artefacts ツールキットの設定ヘルパーは、 artefacts.yaml Artefacts ツールキットの設定ヘルパーは、

インポート方法：

from artefacts_toolkit.config import get_artefacts_param

関数

関数リファレンス

`get_artefacts_param`

artefacts.yaml ファイルで設定されたパラメータを返します。 param_type が launchに設定されている場合、ROS の起動引数として使用できるように string 型で返されます。

この関数はパラメトリックテストに特に役立ちます。 artefacts.yaml ファイルでパラメータ値のリストを定義すると（例：launch/world: ["empty.sdf", "bookstore.sdf", "restaurant.sdf"])、 artefacts run コマンドはリスト内の各値に対して1回ずつ、テストを複数回実行します。各テスト実行中、 get_artefacts_param("launch", "world") は自動的にその特定のテスト実行に対する現在のパラメータ値を返します。

これはグリッドベースのテストに特に強力です！それぞれ3つの可能な値を持つ3つのパラメータがある場合、Artefacts は自動的にテストを27回（3 × 3 × 3）実行しますが、起動ファイルのコードは変更されません。

get_artefacts_param(
    param_type,
    param_name,
    default=None,
    is_ros=True
)

パラメータ

パラメータ	型	説明	デフォルト
`param_type`	`str`	パラメータの名前空間/カテゴリ（例：「launch/world」の「launch」）	必須
`param_name`	`str`	T特定のパラメータ名（例：「launch/world」の「world」）	必須
`default`	`any`	artefacts.yamlでパラメータが見つからない場合に返す値	`None`
`is_ros`	`bool`	パラメータをROS パラメータ形式に変換するかどうか	`True`

戻り値

この関数は次の動作でパラメータ値を返します：

param_type が "launch" で is_ros が Trueの場合: artefacts.yaml ファイルの元の型に関係なく、値を strとして返します。これはROS起動引数として使用できるようにするためです。
default がNone 以外に設定されている場合、artefacts が要求されたパラメータを見つけられない場合に値が返されます。これは（例えば） artefacts run の代わりに launch_test を使用しているがコード変更を行いたくない場合に便利です。また、 KeyError 例外を防ぎます。
その他のすべての場合：YAMLファイルの元の型（例： list、 dict、 int、 float、 strなど)で値を返します。

Note

現在はROS パラメータ / ROS起動引数のみをサポートしています。
パラメトリックテストは、artefactsをローカルで実行する場合、順次実行されます。プラットフォーム上で実行する場合、並行して実行されます（同時実行テストの最大数はサブスクリプションプランによって決まります）。

例

以下の設定が設定された artefacts.yaml ファイルがある場合：

scenarios:
  defaults:
    output_dirs: ["output"]
    metrics:
        - /odometry_error
    params:
      launch/world: ["bookstore.sdf", "empty.sdf"]

テスト起動ファイルでパラメータを次のように取得します：

def generate_test_description():
    try:
        world = get_artefacts_param("launch", "world")
    except FileNotFoundError:
        world = "empty.world"

    run_headless = LaunchConfiguration("run_headless")
    launch_navigation_stack = IncludeLaunchDescription(
        PythonLaunchDescriptionSource(
            [
                os.path.join(
                    get_package_share_directory("sam_bot_nav2_gz"),
                    "launch",
                    "complete_navigation.launch.py"
                ),
            ]
        ),
        launch_arguments=[("run_headless", run_headless), ("world_file", world)],
    )

...# Rest of launch test file

これにより、同じテストが2回実行されます - 1回は空のワールドで、1回は書店のワールドで - 実行間で起動ファイルのコードを変更することなく実行されます。

`get_artefacts_params`

指定された実行に対して artefacts.yaml で設定されたすべてのパラメータを読み込み、それらを dict として提供します。.get() などの通常の辞書メソッドと組み合わせて使用できます。

get_artefacts_params()

パラメータ

なし

戻り値

この関数は、指定された実行のすべてのパラメータを dict 型として返します。

Note

返される内容は、artefacts.yaml ファイルでテストファイルを指すために launch_test_file または run のどちらを使用しているかによって異なります。launch_test_file を使用している場合、パラメータは「ROS化」されますが、run を使用している場合はされません。例として：

scenarios:
  defaults:
    output_dirs: ["output"]
    metrics:
        - /odometry_error
    params:
      my_test_node/parameter_1: [0.1, 0.2]
      my_test_node/parameter_2: ["a", "b"]

launch_test_file を使用している場合、以下を返します：

# Run 1
{
    'my_test_node': {
        'ros__parameters': {
            'parameter_1': 0.1,
            'parameter_2': 'a'
        }
    }
}

# Run 2
{
    'my_test_node': {
        'ros__parameters': {
            'parameter_1': 0.2,
            'parameter_2': 'b'
        }
    }
}

run を使用している場合、以下を返します：

# Run 1
{
    'my_test_node/parameter_1': 0.1,
    'my_test_node/parameter_2': 'a'

}

# Run 2
{
    'my_test_node/parameter_1': 0.2,
    'my_test_node/parameter_2': 'b'

}

例

以下の設定が設定された artefacts.yaml ファイルがある場合：

scenarios:
    defaults:
        params:
            headless: "True"

ヘッドレスシミュレーション用の launch_description にフラグを次のように設定できます：

@launch_pytest.fixture(scope="module")
def launch_description(rosbag_recording):
    pkg_path = Path(get_package_share_directory("my_package"))
    try:
        headless = get_artefacts_params().get("headless", "False")
    except RuntimeError:
        # artefacts パラメータが利用できない場合、デフォルトで False に設定
        headless = "False"

    start_launch = IncludeLaunchDescription(
        PythonLaunchDescriptionSource(
            str(pkg_path / "launch" / "mytestfile.launch.py")
        ),
        launch_arguments={
            "headless": headless,
        }.items(),
    )

`merge_ros_params_files`

2つの ROS2 yaml パラメータファイルを1つにマージし、最初のファイル（source）の値を override の値で上書きします。

merge_ros_params_files(
    source,
    override,
    destination,
    rosify=False
)

パラメータ

パラメータ	型	説明	デフォルト
`source`	`str`	上書きされる元のパラメータファイルへのパス	必須
`override`	`str`	上書きするパラメータを含むパラメータファイルへのパス	必須
`destination`	`str`	新しいパラメータファイルを保存する場所へのパス	必須
`rosify`	`bool`	`True` の場合、パラメータを ros2 パラメータファイルのネスト形式に変換	`False`

戻り値

None: 新しく作成されたマージ済みパラメータファイルは destination で指定されたパスで利用可能になります。

例

以下の source と override yaml ファイルがある場合：

# source
outer:
    inner1: 1
    inner2: 
        leaf: keep
flat: src

# override
outer:
    inner2:
        leaf: replaced
        new_leaf: 321
    inner3: added
flat: override

以下のような新しい yaml ファイルが destination に保存されます：

# rosify=False (デフォルト)
outer:
    inner1: 1
    inner2:
        leaf: replaced
        new_leaf: 321
    inner3: added
flat: override

rosify=True の場合、パラメータは適切なノードの ros__parameters の下にネストされます：

#source
controller_server:
    ros__parameters:
        enable_stamped_cmd_vel: true
        controller_frequency: 20.0
        min_x_velocity_threshold: 0.001

#override
controller_server/controller_frequency: 30
controller_server/min_x_velocity_threshold: 0.005
controller_server/min_y_velocity_threshold: 0.5   
    
#destination
controller_server:
    ros__parameters:
        enable_stamped_cmd_vel: true
        controller_frequency: 30
        min_x_velocity_threshold: 0.005
        min_y_velocity_threshold: 0.5

最終更新 09.10.2025: Toolkit config updates (#50) (3138ef8)