roadrunner-build-scenario-from-osc

OpenSCENARIO から RoadRunner シナリオを構築する

OpenSCENARIO 1.x（.xosc）ファイルを解釈し、roadrunner-scenario-authoring スキルを使用して RoadRunner でシナリオを再作成します。位置を変換し、構造を対応付け、相対参照を保持し、正しいフェーズロジックを構築します。

使用する場合

• ユーザーが .xosc ファイルを持っていて、RoadRunner で再作成したい場合
• ユーザーが OpenSCENARIO からプログラムでシナリオを構築したい場合
• ユーザーが「この .xosc を RoadRunner で構築して」または「このシナリオを再作成して」と言った場合
• ユーザーがパートナーや標準化団体（Euro NCAP、ALKS など）から OpenSCENARIO ファイルを受け取った場合
• ユーザーが .xosc ファイルから MATLAB スクリプトを生成したい場合
• ユーザーが「この xosc を matlab に変換して」または「matlab スクリプトで再作成して」と言った場合

使用しない場合

• ユーザーが .xosc ファイルを「インポート」したいと言った場合 — ユーザーが求めているのはこのスキルではなく、importScenario(rrApp, xoscPath) です。API を直接呼び出してください。
• ユーザーが RoadRunner の組み込み importScenario を使いたい場合（そのまま使ってもらってください — 単純なケースでは機能します）
• ユーザーが .xosc ファイルなしでシナリオをゼロから作成したい場合（roadrunner-scenario-authoring を使用してください）
• ユーザーがシナリオを OpenSCENARIO にエクスポートしたい場合（roadrunner-export-scenario を使用してください）

重要なルール

1. ソース XOSC に含まれないアクションや条件を決して捏造しないでください。 構造を対応付けられない場合は、その構造を省略し、ユーザーに警告してください。

2. 回避策を決して提案しないでください。 DistanceToPointCondition を DurationCondition に置き換えたり、未対応のトリガーに SimulationTimeCondition を 代用したり、ソースにない構造を追加したりしないでください。

3. 軌跡の頂点を決して簡略化したり、重複させたりしないでください。 ソース XOSC に 含まれるポリラインの頂点を、過不足なく正確に抽出してください。90 個の頂点を 5 個に 減らしてはいけません。抽出時に始点や終点を重複させないでください。

4. シーンを決して推測しないでください。 <LogicFile> に記載された .xodr ファイル名 だけを報告してください。それをインポートしてください — 類似した名前のシーンを 検索しないでください。

5. 相対参照を絶対参照に決して変換しないでください。 ソースで RelativeTargetSpeed delta=-8 が使われている場合は、 SpeedReference="actor"、Direction="slower"、Speed=8 として保持してください。 7 m/s を計算してハードコードしないでください。

6. 未対応の機能を黙って省略しないでください。 必ず Scenario Description の 「Unsupported Constructs」に明示してください。

7. XOSC の構造ではなく、意図を説明してください。 プレースホルダーの Act （MW_WaitAction）は終了条件にまとめてください。意味のあるアクターアクションがない 足場となる要素のフェーズは作成しないでください。

ワークフロー

このスキルは 2 つのステップで動作します。まずステップ 1 を完了し、説明をユーザーに 提示して確認してもらってから、承認を得た後にのみステップ 2 に進んでください。

---

ステップ 1：.xosc を解析してシナリオの説明を作成する

厳密に以下の論理順序に従って、.xosc と参照先の .xodr を解析してください。

1a. 入力を検証する

.xosc XML を読み取ってください。ファイルが無効な XML である場合、必須要素が欠けている 場合、または基本的な構造チェックに失敗する場合は、処理を停止してエラーを報告して ください。欠落したデータを推測したり、あるものと仮定したりしないでください。 データが曖昧な場合は、前提を明示してください。

1b. パラメーター、式、カタログを解決する

値を解釈する前に、すべての参照を解決してください。

• ParameterDeclarations / VariableDeclarations：${...} 式を具体的な数値に評価して ください。宣言順に処理してください（後続のパラメーターは先行するパラメーターを 参照できます）。
• CatalogReferences：参照先のカタログ XML ファイル（<CatalogLocations> 内）を 読み取り、catalogName + entryName でエントリーを検索し、車両／歩行者の定義 （model3d のパス、カテゴリ、バウンディングボックス）を抽出してください。

% Parameter expression resolution example
params.HostSpeed_kph = 80;
params.LeadTime_s = 6;
params.hostSpeed_ms = params.HostSpeed_kph / 3.6;        % 22.2222
params.leadSpeed_ms = params.hostSpeed_ms * 0.5;         % 11.1111
params.initSeparation = (params.hostSpeed_ms + params.leadSpeed_ms) * params.LeadTime_s; % 200

1c. Init フェーズを説明する

<Init> 内で、各アクターの Private アクションについて説明してください。

1. TeleportAction — 位置をワールド座標 [x, y, z] に変換します：

   • WorldPosition：そのまま使用します
   • LanePosition：.xodr を使用して変換します（scripts/xoscPositionToWorld.p を参照）
   • RoadPosition：.xodr を使用して変換します（scripts/xoscPositionToWorld.p を参照）
   • 重要：xoscPositionToWorld に渡すすべてのパラメーターは数値でなければなりません。 XML 属性は常に文字列です。呼び出し前に str2double() で変換してください：

     pos = xoscPositionToWorld(xodrPath, 'LanePosition', ...
         'roadId', str2double(roadId), 'laneId', str2double(laneId), ...
         's', str2double(s), 'offset', str2double(offset));
     

     文字列を渡すと、エラーが表示されないまま誤った座標（最大 12m の誤差）が生成されます。
   • RelativeObjectPosition：エンティティの進行方向で dx/dy を回転させ、基準位置に加算します
   • RelativeRoadPosition：基準エンティティの道路座標を逆引きし、s/t にオフセットを適用します
   • RelativeLanePosition：基準レーンを逆引きし、対象レーン + s を計算します （dLane が負の ID から正の ID にまたがる場合は中央レーンをスキップします）
   • 依存関係の順序に従ってエンティティを処理します。参照エンティティを先に解決します

2. Heading — RoadRunner API はアクターの向きの設定をサポートしていません。 アクターは常にアンカー位置の道路方向に沿って配置されます。シナリオの説明に heading を含めないでください。適用できません。 注：XOSC の h 属性は、RelativeObjectPosition の変換で引き続き必要です （エンティティのローカル座標系で dx/dy を回転させるため）が、配置されたアクターには設定されません。

3. SpeedAction — 速度の値と、それが絶対値か相対値かを記録します。 相対値の場合は、<abs(delta)> m/s <方向> relative to <基準アクター> の形式で記述します。 方向は、"slower"（delta < 0）、"faster"（delta > 0）、または "same"（0）です。

4. FollowTrajectoryAction — 実質的に t=0 で開始する場合のみサポートされます。 これは、(a) Init にある場合、または (b) Story にあり、トリガーチェーンをたどると t=0 に解決される場合を指します。チェーンをたどって解決します。Event StartTrigger が StoryboardElementStateCondition(Act, runningState) の場合は、Act の StartTrigger を確認します。それが Story の runningState を参照している場合は、Story の StartTrigger を確認します。チェーンが SimulationTimeCondition >= 0 で終わる場合は、 t=0 として扱います。チェーン内のいずれかのリンクで、0 以外の時間、継続時間、 距離、またはその他の条件が使われている場合はサポート対象外です。スキップして警告します。

   サポート対象の場合は、ポリラインの頂点を正確にすべてルートの経由点として抽出します （削減したり、開始点や終了点を重複させたりしないでください）。速度参照を判定します：

   • TimeReference に <Timing> がある場合 → Speed Reference："route-time-data"。 各頂点の time 属性を説明に含めます。 SpeedAction は無視します。タイミングが速度より優先されます。
   • TimeReference に <None/> がある場合 → Speed Reference：absolute（SpeedAction の値を使用します） WorldPosition 以外の頂点は、scripts/xoscPositionToWorld.p を使用して変換します。

5. AssignRouteAction — FollowTrajectoryAction と同じ t=0 のルールを適用します（トリガーチェーンを解決します）。 サポート対象の場合は、すべての経由点（LanePosition または WorldPosition）を抽出します。SpeedAction の絶対速度を常に使用します。トリガーチェーンが t=0 に解決されない場合はサポート対象外です。スキップして警告します。

6. AddEntityAction — 通常は SpeedAction と組み合わせます（位置と初期速度を設定します。TeleportAction + SpeedAction と同じです）。FollowTrajectoryAction または AssignRouteAction と組み合わせることもできます。その場合は、既存のルール（項目 4 と 5）が適用されます。ネストされた <Position> 要素から位置を抽出し、ワールド座標の [x, y, z] に変換します。Actors セクションでアクターを説明し、作成スキルが addActor で配置できるようにします。
   Actors セクションに Initial Speed を含めないでください — アクターには初期化がありません。速度は WaitAction の後の Phase Logic で定義します。addActor はすべてのアクターをシナリオ開始時に配置するため（シナリオ途中のスポーンには対応しません）、Phase Logic を使って遅延出現を再現します。

   • AddEntityAction のイベント／アクトの StartTrigger 条件を確認します
   • アクターの最初のフェーズとして、WaitAction フェーズ（SystemActionPhase）を記述します — アクターに自動作成される初期化フェーズの前に挿入します
   • 待機フェーズの終了条件を XOSC の開始条件に設定します
   • アクターに自動作成される初期化フェーズは WaitAction の後に配置します — ここで速度や動作（例：ChangeSpeedAction）を設定します
   • WaitAction の前にパススルーフェーズを追加しないでください — WaitAction が最初のフェーズです。各アクターには WaitAction → 動作 の 2 つのフェーズのみを設定します
   • AddEntityAction アクターの速度の配置： WaitAction フェーズには速度を設定しません — スポーン条件を待つだけです。速度（例：17.88 m/s の ChangeSpeedAction）は、WaitAction の後に配置される、自動作成された初期化フェーズに設定する必要があります。WaitAction 上、またはその前に速度を設定しないでください。

7. 移動モードの制約 — Story に ChangeLaneAction または ChangeLateralOffsetAction があるアクターは、レーン追従モード（ルートなし）にする必要があります。そのようなアクターにはルートのウェイポイントを含めないでください。

アクターに影響しないグローバルな初期化アクション（例：EnvironmentAction）は無視します。

1d. Story フェーズを記述する

目的は、各アクターが何を行い、何がそれをトリガーし、何によって終了するかという意図を記述することです。XOSC の構造階層（Acts、Events、ManeuverGroups）は維持しないでください。構造上の要素を簡潔なアクションの説明にまとめます。

MW_WaitAction の処理（プレースホルダーの Act）：

• 実際のアクション + MW_WaitAction がある Act： Act の StopTrigger を終了条件として、主なアクションを記述します。MW_WaitAction は無視します。
• MW_WaitAction のみがある Act（実際のアクションなし）： この Act の StopTrigger は、直列チェーンで直前にあるフェーズの終了条件です。条件をその直前のフェーズに直接設定し、別の WaitAction フェーズは作成しないでください。例外： 直前のフェーズがない場合、または直前のフェーズにすでに終了条件がある場合は、Act の StopTrigger を終了条件とする WaitAction フェーズを作成します。

実行順序の判断：

StartTrigger を確認し、直列／並列の関係を判断します。

• StoryboardElementStateCondition(X, completeState) → X の終了後に実行
• StoryboardElementStateCondition(X, runningState) → X と並行して実行
• SimulationTimeCondition >= 0 → 直ちに開始

並列グループと直列の後続処理：

Act に並列実行される複数の Event が含まれる場合、それらは ParallelPhase を構成します。後続のアクションがその Act の completeState をトリガーとする場合、そのアクションは個々の子フェーズではなく、コンテナーであるParallelPhase の後に直列で実行されます。Act はすべての Event が完了したときに完了するため、後続アクションは並列グループ全体の完了を待つ必要があります。

各アクションで記録する内容：

• アクター、アクションの種類、アクションのプロパティ
• フェーズ名：XOSC の <Action> タグの name 属性を使用します
• トリガー（開始条件）
• 終了条件（終了条件 — Act の StopTrigger または MW_WaitAction の Act から取得）
• 他のアクションとの直列／並列の関係

1e. シナリオの説明を作成する

roadrunner-scenario-authoring の用語を使って構造化された説明を記述し、 オーサリングスキルがそのまま実行できるようにします。

## Scene
- OpenDRIVE file: <filename from LogicFile>
- Import required: yes (use `roadrunner-import-scene` with format "OpenDRIVE")

## Parameters (if any)
- <name> = <resolved value> (original expression: <expr>)

## Actors
For each actor:
- Name: <XOSC entity name>
- Type: Vehicle / Pedestrian
- Asset: <model3d path> (AssetType: "VehicleAsset" or "CharacterAsset")
- Initial Position: [x, y, z] (translated from <original position type>)
- Anchoring:
  - Lane-following (no route): autoAnchor (actor must be anchored to road for lane following)
    - **Exception:** If the actor's translated position is on a junction connector road,
      do NOT autoAnchor — anchoring on junctions shifts the position to an
      unpredictable anchor point. Place the actor at the exact world coordinates instead.
  - Path-following (has route): do NOT autoAnchor (positions are precise world coordinates)
- Movement Mode: path-following (has route) or lane-following (no route)
- **Anchoring and Movement Mode are REQUIRED fields.** Every actor description
  must explicitly state the anchoring decision (autoAnchor or NOT autoAnchor)
  and movement mode. Do not omit these even when the choice seems obvious from
  context — the downstream authoring skill needs them stated explicitly.
- Initial Speed: <value> m/s (absolute)
  OR: <delta> m/s <direction> relative to <reference actor>
- Route (if path-following):
  - Waypoints: [x, y, z] per row (ALL vertices — never simplify)
  - Timestamps: [t0, t1, t2, ...] (if timed trajectory — sets Point.Time)
  - Speed Reference: "route-time-data" (timed) or absolute value (untimed)
  - Freeform: true (route follows exact waypoint positions, not road geometry)
  - Do NOT autoAnchor route waypoints

## Phase Logic
Use RoadRunner action/condition type names (see references/openscenario-mapping.md):
For each meaningful action (skip MW_WaitAction placeholders):
- Actor: <who>
- Phase Name: <from XOSC Action name attribute>
- Action: <RoadRunner action type> (e.g., ChangeSpeedAction, ChangeLaneAction)
  - Properties: Speed=X, DynamicsShape="step", Direction="left", etc.
- Trigger: <RoadRunner condition type> (e.g., SimulationTimeCondition, DurationCondition)
  - Properties: Time=X, Duration=X, Distance=X, Rule="ge", etc.
- End Condition: <RoadRunner condition type> with properties
- Topology: serial after <previous> / parallel with <sibling>

## Scenario End Conditions
- End: <condition type> on RootPhase (e.g., SimulationTimeCondition, Time=60)
- Fail: <condition type> on RootPhase (e.g., CollisionCondition)

## Unsupported Constructs
- <construct>: <why it cannot be mapped>

1f. レビュー用に提示する

シナリオの説明をユーザーに見せ、次のように尋ねます。 「抽出したシナリオの説明はこちらです。アクター、位置、フェーズロジック、相対参照を確認してください。MATLAB スクリプトを生成する前に、何か調整しますか？」

ステップ 2 に進む前に、ユーザーの承認を待ちます。

---

ステップ 2：依存スキルを使ってシナリオを構築する

ユーザーがシナリオの説明を承認した後、依存スキルに実行を委任します。このスキルは MATLAB コードを生成しません。 .xosc を解釈し、説明を作成するだけです。

2a. シーンをインポートする

新しいシーンにインポートして、新しいシナリオを作成します。

1. newScene(rrApp) を呼び出して、クリーンなシーン（残存する道路のないシーン）を取得します。
2. ProjectionMode = "noprojection" を指定してインポートし、.xodr のネイティブ座標系を保持します。

   importOpts = openDriveImportOptions;
   importOpts.ProjectionMode = "noprojection";
   importScene(rrApp, xodrPath, "OpenDRIVE", importOpts);
   

3. newScenario(rrApp) を呼び出して、インポートしたシーンに新しいシナリオを作成します。

2b. シナリオを構築する

重要：シナリオを構築するには、必ず /roadrunner-scenario-authoring を呼び出してください。MATLAB コードを直接記述しないでください。MCP MATLAB ツール（mcp__matlab__evaluate_matlab_code、mcp__matlab__run_matlab_file）を自分で呼び出さないでください。すべてのコード生成と実行は、オーサリングスキルが処理します。

完全に承認済みのシナリオ説明を引数として、/roadrunner-scenario-authoring を呼び出します。次の文を先頭に付けます。

RoadRunner で次のシナリオを構築してください。シーンはすでに インポートされ、新しいシナリオも作成されています。

その後、完全なシナリオ説明（アクター、フェーズロジック、終了条件など）を貼り付け、オーサリングスキルがそのまま実行できるようにします。

オーサリングスキルが正しく適用できるよう、指示に次の対応関係の詳細を含めます。

アンカーのルール：

• 車線追従アクター（ルート／軌道なし）： autoAnchor を必ず適用します。車線を正しく追従するには、アクターを道路にアンカーする必要があります。
• 経路追従アクター（ルートあり）： アクターやルートのウェイポイントに autoAnchor を適用しないでください。位置は正確なワールド座標であり、autoAnchor を適用すると意図した位置からずれて、軌道が不整合になります。

CollisionCondition のパターン（終了条件に含めます）：

XOSC パターン	指定する内容
<EntityRef entityRef="ActorB"/>（特定のペア）	「[Actor] と [ActorB] の衝突」
<ByType type="vehicle"/>（任意の車両）	「[Actor] と任意の車両との衝突」

複数の <ConditionGroup> 要素（StopTrigger の OR ロジック）：それぞれを RootPhase の個別の終了条件／失敗条件として記述します。

---

参考資料

ステップ 1 では、XOSC の構成要素を RoadRunner の用語に対応付けるため、次の資料を参照します。

• references/openscenario-mapping.md — XOSC のアクション／条件タイプから RoadRunner API のタイプ名への対応付け、状態の対応付け、ルールの対応付け、プロパティの対応付け
• scripts/xoscPositionToWorld.p — MATLAB 関数。.xodr ファイルを使って、任意の XOSC 位置タイプをワールド座標 [x, y, z] に変換するために呼び出します。

よくある間違い

間違い	間違っている理由	正しい方法
ルートがないレーン追従アクターで autoAnchor を省略する	道路にアンカーされていないと、アクターはレーンを適切に追従できません	レーン追従アクター（ルート／軌跡なし）には autoAnchored が必須です。ただし、アンカリングによって位置がずれるため、ジャンクションのコネクター道路では適用しないでください
ジャンクションのコネクター道路で autoAnchor を使用する	ジャンクションでアンカリングすると、アクターが予測できないアンカーポイントに移動し、位置がずれます	変換後の位置がジャンクション上にある場合は、autoAnchor を使用せず、正確なワールド座標に配置してください
ルートがある経路追従アクターで autoAnchor を使用する	位置がずれ、軌跡が整合しなくなります	経路追従アクターとそのルートのウェイポイントには autoAnchored を使用しないでください。位置はすでに正確なワールド座標です
xoscPositionToWorld に文字列パラメーターを渡す	関数は誤った座標を（最大 12m の誤差で）返しますが、エラーは表示されません	呼び出す前に、XML 属性値に必ず str2double() を使用してください：'roadId', str2double(id), 'laneId', str2double(lane), 's', str2double(s), 'offset', str2double(off)
AddEntityAction アクターの WaitAction の前にパススルーの初期化フェーズを追加する	不要なフェーズが追加されます。アクターはスポーン時刻まで何も行わないはずです	WaitAction が最初のフェーズです。フェーズは WaitAction → 動作の 2 つだけです
AddEntityAction アクターの Actors セクションに初期速度を含める	待機前にアクターは初期化されません	速度は Actors セクションではなく、WaitAction の後の Phase Logic で設定します
WaitAction に ActorActionPhase を使用する	WaitAction はアクターアクションではありません	WaitAction は SystemActionPhase に含める必要があります

規約

• このスキルが生成するのはシナリオの説明 のみ です。MATLAB コードは生成しません
• シーンのインポートは roadrunner-import-scene に、構築は roadrunner-scenario-authoring に委任してください
• 位置を変換する前に、パラメーターや式は必ず具体的な値に解決してください
• アクターを説明する前に、CatalogReferences は必ずアセットパスに解決してください
• アセットパスにはプロジェクトの拡張子を使用します：車両には .fbx、キャラクターには .rrchar

---

Copyright 2026 The MathWorks, Inc.

---