carla-map-asset-builder

Docker内のCARLAを使って、fbx + OpenDRIVE(.xodr) から CARLAマップパッケージ(.tar.gz)をビルドするCLIツールです。

• 必要なファイル(fbx / xodr)は引数で渡す
• CARLAが読むメタデータJSONは引数から自動生成（ユーザーはJSONを意識しない）
• まずは CARLA 0.9.16 をサポート

前提

アセットのcook(取り込み)にはUnreal Engineを含む ソースビルド済みのCARLA Dockerイメージが必要です。 公式ランタイムイメージ carlasim/carla:0.9.16 単体ではcookできません。 cook可能なイメージ名を --image で渡してください。

セットアップ

uv sync --extra dev

使い方

uv run carla-asset-builder build \
  --fbx path/to/mymap.fbx \
  --xodr path/to/mymap.xodr \
  --image <cook可能なCARLAビルドイメージ> \
  --output ./dist

主なオプション:

dry-run で中身を確認

uv run carla-asset-builder build --fbx mymap.fbx --xodr mymap.xodr \
  --image carla-build:0.9.16 --dry-run

Python APIとして使う

CLIと同じ操作をPythonから直接呼び出せます。

from carla_map_asset_builder import build_map

artifacts = build_map(
    fbx="path/to/mymap.fbx",
    xodr="path/to/mymap.xodr",   # 省略可
    name="mymap",                # 省略時はfbxのファイル名
    image="carla-build:0.9.16",  # cook可能なCARLAビルドイメージ
    output_dir="./dist",
    dry_run=False,
)
# artifacts: 生成された .tar.gz などのパス一覧 (list[pathlib.Path])

より細かく制御したい場合は BuildRequest を組み立てて build() を呼びます （複数マップを1パッケージにまとめる等）。

from pathlib import Path
from carla_map_asset_builder import BuildRequest, MapAsset, build

request = BuildRequest(
    package_name="my_pkg",
    maps=[
        MapAsset(name="town01", fbx=Path("town01.fbx"), xodr=Path("town01.xodr")),
        MapAsset(name="town02", fbx=Path("town02.fbx"), xodr=Path("town02.xodr")),
    ],
    output_dir=Path("./dist"),
    image="carla-build:0.9.16",
    carla_version="0.9.16",
)
artifacts = build(request)

公開シンボル: build_map, build, BuildRequest, MapAsset, get_ingestor, SUPPORTED_CARLA_VERSIONS, DEFAULT_CARLA_VERSION。

動作の流れ

1. 引数から Import/ レイアウト(fbx / xodr / <package>.json)を一時ディレクトリに生成
2. その一時ディレクトリをコンテナに read-only マウントし、 コンテナ内で make import → make package を実行
3. Dist/ に生成された .tar.gz を --output に回収

開発

uv run pytest

テストはDockerを必要としません（メタデータ生成・staging・docker引数組み立てを検証）。

リリース (PyPI)

GitHub Actions による自動リリースを備えています(simple_lanelet2 / tier4/splatsim 方式)。

日常的な流れ:

1. PR を作り、release:major / release:minor / release:patch のいずれか 1つ をラベル付けする
2. その PR を main にマージする
3. release.yml が自動で:
   • tools/bump_version.py で pyproject.toml と __init__.py のバージョンを上げる
   • vX.Y.Z タグを打って GitHub Release を作成
   • テスト再実行 → sdist/wheel ビルド → PyPI へ公開

その他の入口:

• v* タグを手動 push → そのタグを直接ビルド・公開(hotfix 用)
• workflow_dispatch(手動実行)→ ビルドのみ、公開はしない(リハーサル)

初回のみ必要な PyPI 側設定(Trusted Publishing):

API トークンは使いません。PyPI の Publishing 設定で pending publisher を1度だけ登録します。

この登録が済むまで publish ステップは失敗し、wheel は artifact として残ります (=リポジトリ外の明示的な設定なしには何も PyPI に届かない、という安全な向き)。

拡張

新しいCARLAバージョンをサポートする場合: src/carla_map_asset_builder/versions/ に Ingestor を継承したクラスを追加し、 versions/__init__.py の _REGISTRY に登録します。