rosbag_slam_lint

Lint rosbag2 metadata.yaml for LiDAR/IMU SLAM recording quality. (No ROS runtime required.)

rosbag2 の metadata.yaml を対象に、LiDAR/IMU SLAM向けの録画品質をチェックするCLIです。（ROS実行環境なしで動きます）

Install

PyPI:

python3 -m pip install -U rosbag-slam-lint

CLIだけ欲しい場合（隔離環境）:

pipx install rosbag-slam-lint

開発用（editable install, このmonorepoから）:

python3 -m pip install -e ./oss/rosbag_slam_lint

Quickstart

rosbag-slam-lint /path/to/bag_dir
rosbag-slam-lint /path/to/metadata.yaml
rosbag-slam-lint /path/to/bag_dir --fail-on warn

目的

録画後に以下を即判定します。

• 必須トピックがあるか
• 平均Hzが最低ラインを満たすか
• 録画時間・総メッセージ数が極端に不足していないか

使い方

rosbag-slam-lint /path/to/bag_dir

metadata.yaml を直接渡すこともできます。

rosbag-slam-lint /path/to/metadata.yaml

JSON出力:

rosbag-slam-lint /path/to/bag_dir --json

WarningでもCIを落とす:

rosbag-slam-lint /path/to/bag_dir --fail-on warn

設定ファイルで閾値を上書き:

rosbag-slam-lint /path/to/bag_dir --profile lio --config examples/config.sample.yaml

デモ（サンプル）

サンプル入力:

examples/metadata.sample.yaml

rosbag-slam-lint examples/metadata.sample.yaml

出力例:

== rosbag_slam_lint ==
source: examples/metadata.sample.yaml
duration_s: 100.000
message_count: 5200
topic_count: 3

topics:
  - /imu/data (sensor_msgs/msg/Imu): 4200 msgs, 42.000 Hz
  - /velodyne_points (sensor_msgs/msg/PointCloud2): 900 msgs, 9.000 Hz
  - /odom (nav_msgs/msg/Odometry): 100 msgs, 1.000 Hz

diagnostics:
  [WARN] LOW_TOPIC_RATE: imu average rate is 42.00Hz; recommended >= 50.0Hz. IMU topic average rate looks low (< 50Hz).
    suggestion: Check sensor frame rate, network bandwidth, and QoS reliability.
  [INFO] MISSING_RECOMMENDED_TOPICS: Recommended topic group 'tf' not found (patterns=['/tf']).
    suggestion: This is optional, but useful for downstream debug/visualization.
  [INFO] MISSING_RECOMMENDED_TOPICS: Recommended topic group 'tf_static' not found (patterns=['/tf_static']).
    suggestion: This is optional, but useful for downstream debug/visualization.

閾値調整（実bagを使う）

複数の metadata.yaml から、プロファイルに必要なトピック群の実測Hz分布を集計できます。

rosbag-slam-profile-stats /data/bags --json

/data/bags は再帰探索され、metadata.yaml が自動収集されます。
出力の required_groups[].suggested_min_hz は、既定で p10 * 0.8 で計算されます。

設定ファイル（--config）

サンプル: examples/config.sample.yaml

checks:
  short_recording_s: 120
  low_message_count: 5000

profiles:
  lio:
    required_groups:
      lidar_points:
        min_hz: 8.0
      imu:
        min_hz: 80.0

サポート項目:

• checks.short_recording_s
• checks.low_message_count
• profiles.<profile>.required_groups.<group>.min_hz

プロファイル

• lio（現在実装済み）
  • 必須: LiDAR群, IMU群
  • 推奨: /tf, /tf_static, /odom
• lio_glim（厳しめ設定）
  • 必須: LiDAR群 (>= 8Hz), IMU群 (>= 88Hz)
  • 推奨: /tf, /tf_static, /odom
• ekf
  • 必須: IMU群 (>= 50Hz), Wheel/Odometry群 (>= 10Hz)
  • 推奨: /tf, /tf_static
• vio
  • 必須: IMU群 (>= 100Hz), Camera image群 (>= 10Hz)
  • 推奨: /tf, /tf_static
• wheel_lio
  • 必須: LiDAR群 (>= 5Hz), IMU群 (>= 50Hz), Wheel/Odometry群 (>= 10Hz)
  • 推奨: /tf, /tf_static

終了コード

• 0: 失敗条件に達する問題なし
• 1: --fail-on で指定した閾値以上の問題あり
• 2: 入力不正や読み込み失敗

今後の予定

• /tf チェーン整合チェック
• GitHub Actions向けサンプル
• プロファイル自動推定（トピック構成ベース）

リリースノート

• CHANGELOG.md を参照
• RELEASE_NOTES_v0.3.2.md を参照
• RELEASE_NOTES_v0.3.1.md を参照
• RELEASE_NOTES_v0.3.0.md を参照
• RELEASE_NOTES_v0.2.0.md を参照
• RELEASE_NOTES_v0.2.1.md を参照
• ANNOUNCE_v0.3.2.md に告知テンプレを用意
• ANNOUNCE_v0.3.1.md に告知テンプレを用意
• ANNOUNCE_v0.3.0.md に告知テンプレを用意
• ANNOUNCE_v0.2.1.md に告知テンプレを用意

テスト

cd oss/rosbag_slam_lint
pytest -q

PyPI公開（メンテナ向け）

ローカルビルド検証:

cd oss/rosbag_slam_lint
python3 -m pip install build twine
python3 -m build
python3 -m twine check dist/*

GitHub Actionsでの公開:

1. リポジトリシークレット PYPI_API_TOKEN を設定
2. バージョンを更新してタグ/リリースを作成
3. Publish rosbag_slam_lint workflow が release event で実行される

Secret設定を補助するスクリプト:

cd oss/rosbag_slam_lint
./scripts/setup_pypi_secret.sh --set

設定確認だけする場合:

cd oss/rosbag_slam_lint
./scripts/setup_pypi_secret.sh --check

CIで失敗させる最小例

name: bag-quality-check
on: [push, pull_request]

jobs:
  lint-bag:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: "3.12"
      - run: python -m pip install -e ./oss/rosbag_slam_lint
      - run: |
          rosbag-slam-lint path/to/metadata.yaml \
            --profile lio \
            --config oss/rosbag_slam_lint/examples/config.sample.yaml \
            --fail-on warn

リリース手順（v0.1.0ベース）

1. pyproject.toml の version を更新
2. CHANGELOG.md に変更内容を追記
3. ローカル確認
   • python3 -m py_compile rosbag_slam_lint.py
   • rosbag-slam-lint examples/metadata.sample.yaml
   • rosbag-slam-lint examples/metadata.sample.yaml --json
4. コミットとタグ作成
   • git add oss/rosbag_slam_lint
   • git commit -m "Release rosbag_slam_lint vX.Y.Z"
   • git tag vX.Y.Z
5. push
   • git push
   • git push --tags