Metadata-Version: 2.5
Name: carla-map-asset-builder
Version: 0.1.0
Summary: Docker内のCARLAでマップ/アセットをビルド(ingest/cook)するCLI
Project-URL: Homepage, https://github.com/hakuturu583/carla_map_asset_builder
Project-URL: Repository, https://github.com/hakuturu583/carla_map_asset_builder
Project-URL: Issues, https://github.com/hakuturu583/carla_map_asset_builder/issues
Author: hakuturu583
License: MIT License
        
        Copyright (c) 2026 hakuturu583
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Keywords: asset,carla,docker,map,opendrive,simulation
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering
Requires-Python: >=3.10
Requires-Dist: typer>=0.12.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Description-Content-Type: text/markdown

# 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` で渡してください。

## セットアップ

```bash
uv sync --extra dev
```

## 使い方

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

主なオプション:

| オプション | 説明 |
| --- | --- |
| `--fbx` | 取り込むマップのfbx (必須) |
| `--xodr` | 対応するOpenDRIVE(.xodr) |
| `--name` | マップ名 (省略時はfbxのファイル名) |
| `--package` | パッケージ名 (省略時はマップ名) |
| `--image` | cook可能なCARLAビルドDockerイメージ (必須) |
| `--output`, `-o` | 出力先 (デフォルト `./dist`) |
| `--carla-version` | 対象CARLAバージョン (デフォルト `0.9.16`) |
| `--carla-root` | コンテナ内のCARLAソースルート (デフォルト `/home/carla/carla`) |
| `--use-carla-materials / --no-carla-materials` | CARLA標準マテリアル適用 |
| `--docker-arg` | `docker run` への追加引数 (複数可、例 `--docker-arg=--gpus=all`) |
| `--dry-run` | dockerを実行せず生成コマンドを表示 |

### dry-run で中身を確認

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

## Python APIとして使う

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

```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パッケージにまとめる等）。

```python
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` に回収

## 開発

```bash
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度だけ登録します。

| 項目 | 値 |
| --- | --- |
| owner | `hakuturu583` |
| repository | `carla_map_asset_builder` |
| workflow | `release.yml` |
| environment | `pypi` |

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

## 拡張

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