# Artefacts ツールキットのチャートヘルパー

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

---

Artefacts ツールキットのチャートヘルパーは、テスト実行中にトピックから受信したデータを可視化するのに役立つように設計されています。
インポート方法：
```python
from artefacts_toolkit.chart import make_chart
```

## 関数
* [`make_chart`](#make_chart)

## 関数リファレンス

### `make_chart`

2つの提供されたトピックからのデータに基づいてインタラクティブなHTMLチャートを作成します。

```python
make_chart(
    filepath,
    topic_x,
    topic_y,
    axis_x_name="",
    axis_y_name="",
    field_unit=None,
    output_dir="output",
    chart_name="chart",
    file_type="rosbag",
    output_format="html"
)
```

#### Parameters

| **パラメータ** | **型**             | **説明**                                             | **デフォルト** |
| ------------- | ------------------ | ----------------------------------------------------------- | ----------- |
| `filepath`    | `str`              | データファイル（rosbag）へのパス                             | 必須    |
| `topic_x`     | `Union[str, list]` | x軸のトピック名。時間に対してプロットする場合は "Time" を使用      | 必須    |
| `topic_y`     | `Union[str, list]` | y軸のトピック名。時間に対してプロットする場合は "Time" を使用      | 必須    |
| `axis_x_name` | `str`              | x軸のラベル。単一トピックの場合は自動生成。トピックのリストを使用する場合は指定を推奨  | ""          |
| `axis_y_name` | `str`              | y軸のラベル。単一トピックの場合は自動生成。トピックのリストを使用する場合は指定を推奨 | ""          |
| `field_unit`  | `str`              | フィールドデータの測定単位（例：「m/s」、「rad」） | `None`      |
| `output_dir`  | `str`              | チャートが保存されるディレクトリ                     | `"output"`  |
| `chart_name`  | `str`              | 生成されるチャートファイルの名前                            | `"chart"`   |
| `file_type`   | `str`              | データファイルのタイプ。現在は "rosbag" をサポート              | `"rosbag"`  |
| `output_format` | `str`            | 出力ファイルタイプ。"html" または "csv" から選択してください| `"html"`    |

#### 戻り値

`None`:

##### `output_format="html"` の場合

* `output_dir` に plotly html チャート `<chart_name>.html` を作成しますが、値は返しません。
* 単一または複数のプロットチャートを作成できます（例を参照）


##### `output_format="csv"` の場合

* `output_dir` に csv ファイル `<chart_name>.csv` を作成しますが、値は返しません。ダッシュボードはアップロード時に csv ファイルを自動的にチャートに変換しようとします。ファイルサイズを小さく保ちたい場合に便利です。
* ダッシュボードは現在、単一トピックのチャートのみ自動作成できます。

> [!NOTE]
> * 現在、rosbag からのチャート作成のみをサポートしています。
> * "Time" をトピックの1つとして使用する場合、関数は可能であれば他のトピックをそのトピックのタイムスタンプに対してプロットします。トピックのメッセージ構造にタイムスタンプがない場合は、rosbag の時間が使用されます。

#### 例

##### 単一トピック
以下の例では、テストが完了し rosbag が保存された後、すなわちシャットダウン後に `make_chart` 関数を追加しています。

```python
# my_test_file.launch.py
# test code

...

@launch_testing.post_shutdown_test()
class TestProcOutputAfterShutdown(unittest.TestCase):
    def test_exit_code(self, rosbag_filepath):
        make_chart(
            rosbag_filepath,
            "/odom.pose.pose.position.x",
            "/odom.pose.pose.position.y",
            field_unit="m",
            chart_name="odometry_position",
            output_format="csv"
        )
```
以下のように、ダッシュボードでチャートとして自動的に表示される csv ファイルが生成されます：

![Example Chart](/images/toolkit/example-chart.png)

##### トピック vs 複数トピック

```python
make_chart(
    rosbag_filepath,
    "time",
    ["/critics_cost/ConstraintCritic.data", "/critics_cost/GoalAngleCritic.data", "/critics_cost/GoalCritic.data", "/critics_cost/CostCritic.data", "/critics_cost/PathAlignCritic.data", "/critics_cost/PathAngleCritic.data", "/critics_cost/PathFollowCritic.data", "/critics_cost/PreferForwardCritic.data"],
    axis_x_name="time",
    axis_y_name="critics",
    chart_name="Critics vs Time",
)
```

以下のようなチャートが生成されます：

![Example Chart, topic vs topics](/images/toolkit/topic-vs-topics-chart.png)


##### 複数トピック vs 複数トピック

```python
 make_chart(
        rosbag_filepath,
        topic_x=["/odom.pose.pose.position.x", "/gt_odom.pose.pose.position.x"],
        topic_y=["/odom.pose.pose.position.y", "/gt_odom.pose.pose.position.y"],
        axis_x_name="x (m)",
        axis_y_name="y (m)",
        chart_name="odom vs gt positions"
    )
```

以下のようなチャートが生成されます：

![Example Chart, topics vs topics](/images/toolkit/topics-vs-topics-chart.png)