roadrunner-scenario-authoring

RoadRunner シナリオの作成

MATLAB から roadrunnerAPI を使って、アクター、ルート、フェーズのロジック、検証など、RoadRunner シナリオをプログラムで作成します。

使用する場面

• RoadRunner シナリオにアクター（車両、歩行者、オブジェクト）を追加する
• アクターのルートとウェイポイントを作成する
• フェーズ、条件、アクションなどのシナリオロジックを構築する
• カットイン、歩行者の横断、先行車への追従、緊急ブレーキなど、一般的なパターンを作成する
• アンカーまたは HD Map の位置情報を使って道路上にアクターを配置する
• シミュレーションの前にシナリオ構造を検証する

使用しない場面

• RoadRunner への接続や起動 → roadrunner-core を使用します
• 記録済みのセンサーデータからシナリオを構築する → matlab-use-scenario-builder を使用します
• 道路形状（車線、交差点）を作成する → roadrunner-rrhd-authoring を使用します
• マップやシーンをインポートする → roadrunner-import-scene を使用します
• シナリオをシミュレーションまたはエクスポートする → roadrunner-scenario-simulating を使用します

ワークフロー

1. セッションを確認する

rrApp が存在することを確認します。存在しない場合は、最初に RoadRunner へ接続してください（例：roadrunner-core を使用するか、手動で接続します）。

if ~exist('rrApp', 'var') || ~isvalid(rrApp)
    error("No active RoadRunner session. Use the roadrunner-core skill.");
end

パスの設定： ヘルパー関数を呼び出す前に、スクリプトのディレクトリが MATLAB のパスに含まれていることを確認します。

addpath('<path-to-skill>/scripts');

2. シナリオを初期化する

openScene(rrApp, sceneName);
newScenario(rrApp);
rrApi = roadrunnerAPI(rrApp);
rrs = rrApi.Scenario;
phaseLogic = rrs.PhaseLogic;
rrprj = rrApi.Project;

3. シーンを把握する

アクターを配置する前にシーンを調査し、有効な車線位置を確認します。自動解析には helperSceneAwareness スクリプトを使用するか、HD Map のエクスポートを通じて手動で照会します。

sceneInfo = helperSceneAwareness(rrApp, NumActors=2, ScenarioType="cut-in");

ヘルパーを利用できない場合の手動 HD Map 照会パターンについては、references/scene-awareness.md を参照してください。

4. アクターを追加する

オプション A — 一括配置（2 体以上の場合に推奨）：

actorSpecs(1) = struct(Name="Ego", AssetPath="Vehicles/Sedan.fbx", ...
    AssetType="VehicleAsset", LaneIndex=1, Fraction=0.1, Speed=15);
[actors, report] = helperPlaceActors(rrs, rrprj, phaseLogic, sceneInfo.HDMap, actorSpecs);
ego = actors{1};  % cell array — use curly braces

オプション B — 手動配置：

vehicleAsset = getAsset(rrprj, "Vehicles/Sedan.fbx", "VehicleAsset");
actor = addActor(rrs, vehicleAsset, position);
actor.Name = "Ego";
autoAnchor(actor.InitialPoint);  % Snaps to nearest road

配置後の確認： actor.InitialPoint.WorldPosition が [0 0 0] ではないことを確認します。

利用可能な車両／キャラクターのパスについては、references/asset-catalog.md を参照してください。

5. アクターを配置する（アンカリング）

オプション A — シーンアンカーを利用できる場合：

anchors = getAnchors(rrApp);
% Use remapAnchor for cross-scene portability (not findSceneAnchor)
anchorPt = findSceneAnchor(rrs, anchors(1).Name);
anchorToPoint(actor.InitialPoint, anchorPt);
actor.InitialPoint.ForwardOffset = 20;
actor.InitialPoint.LaneOffset = 1;

オプション B — シーンアンカーがない場合（autoAnchor を使用）：

actor = addActor(rrs, asset, approximatePosition);
autoAnchor(actor.InitialPoint);  % Must be within 5m of road

オプション C — 別のアクターを基準にする場合：

anchorToPoint(target.InitialPoint, ego.InitialPoint);
target.InitialPoint.ForwardOffset = 30;
target.InitialPoint.LaneOffset = 1;

6. ルートを作成する（必要な場合）

ルートを設定すると、アクターは経路追従モードになります。ルートのないアクターは、アンカーが設定された車線に沿って車線追従モードで走行します。

route = actor.InitialPoint.Route;
fwdPt = addPoint(route, actor.InitialPoint.WorldPosition + [20 0 0]);
autoAnchor(fwdPt);
% For vehicles: disable freeform so route follows road surface
% (Do NOT do this for pedestrians — they need freeform to cross roads)
for i = 1:numel(route.Segments)
    route.Segments(i).Freeform = false;
end

ルートを追加する場面：

• キャラクター／歩行者のアクター — 必ず必要です（ルートがないと検証に失敗します）
• 特定の経路をたどる車両（例：直進する自車）
• ChangeLaneAction を必要としない車両

ルートを追加しない場面：

• ChangeLaneAction が必要な車両 — 車線追従モードでなければなりません（ルートなし）
• ChangeLateralOffsetAction が必要な車両 — 同様の要件があります

ルートポイントのルール：

• ルートポイントには必ず autoAnchor を使用します — 位置は道路から 5m 以内でなければなりません
• ルートポイントに anchorToPoint と ForwardOffset を使用しないでください — 検証に失敗します
• 道路上にとどまるよう、ルートのオフセットは小さく（20m）保ちます
• 交差点で曲がる場合：滑らかな経路になるよう、複数のウェイポイント（交差点の手前、通過後、出口）を使用します
• ルートポイントを追加した後、各セグメントで seg.Freeform = false を設定し、道路形状に沿わせます（フリーフォームルートは道路面を無視するため、道路の上または下に浮くことがあります）

7. フェーズロジックを構築する

カタログ全体については、references/actions-and-conditions.md を参照してください。

% Get actor's initial phase (auto-created with addActor)
initPhase = initialPhaseForActor(phaseLogic, actor);

% Modify default speed (initial phase already has ChangeSpeedAction)
initPhase.Actions(1).Speed = 20;

% Add sequential phase
nextPhase = addPhaseInSerial(phaseLogic, initPhase, "ActorActionPhase");
nextPhase.Actor = actor;  % REQUIRED — never omit

% Set trigger condition on initial phase
cond = setEndCondition(initPhase, "LongitudinalDistanceToActorCondition");
cond.Actor = actor;           % REQUIRED
cond.ReferenceActor = otherActor;
cond.Distance = 10;

% Add action to next phase
action = addAction(nextPhase, "ChangeLaneAction");
action.Direction = "left";

複数アクターのフェーズロジック： 各アクターのフェーズチェーンは独立しています。後続フェーズがあるフェーズには、必ず終了条件を設定する必要があります。終了条件がないと、フェーズは無期限に実行され、後続フェーズは実行されません。複数アクターのシナリオでは、後続フェーズがあるすべてのフェーズに、setEndCondition を使って適切な終了条件を設定してください。

8. 検証して報告する

validate(rrs);

検証に合格したら、作成した内容の概要を提示します。明示的に依頼されない限り、シミュレーションは実行しないでください。

シナリオの分解

必須：コードを1行でも書く前に、以下のステップ0～1を完了し、計画をユーザーに提示して確認を得てください。 これを省略しないでください。事前分析なしで作成したシナリオは、タイミングの誤り、衝突の見落とし、または実現不可能なトリガー条件が原因で失敗することがよくあります。

ステップ0 — 意図の確認： ユーザーのプロンプトで、以下のいずれかが不明確な場合は、先に確認してください。

• アクターの数と種類
• 望ましい結果（衝突、ニアミス、安全な完了？）
• 指定されていない速度、距離、またはタイミング
• どのアクターが「エゴ」で、どのアクターが「ターゲット」か
• 使用するシーン（指定がない場合）

ステップ1 — 物理を優先した設計（時間指定の相互作用では必須）： 衝突、ニアミス、割り込み、歩行者の横断、および特定の時刻にアクターが同じ地点に到達する必要があるシナリオでは、コードを書く前に運動学的パラメーターを導出する必要があります。references/physics-first-design.md に記載された5段階のプロセスに従ってください。

1. 意図をタイムラインに変換する
2. 空間パラメーターを計測する（HD Map を照会）
3. パラメーター導出表を作成する（計算過程を示す）
4. 条件がトリガーされることを検証する
5. 導出した値を使ってコードを書く

分解した内容をユーザーに提示してください — アクター、配置、速度、トリガーのタイミング、予想される結果を示します。コードを実行する前に確認を得てください。

1. アクター — 数、種類（車両／歩行者／物体）、役割（エゴ、ターゲット、背景、停止中）
2. 配置の形状 — 使用する helperSceneAwareness の種類を決定します。
   • 同じ車線（ScenarioType="following"）— 先行／追従、追い越し開始、緊急ブレーキ
   • 隣接車線（ScenarioType="cut-in"）— 車線変更、合流、並走
   • 交差する進路 — 歩行者の横断、交差点での競合
3. 相互作用の意図 — 速度／車間距離／トリガーのデフォルト値を決定します。
   • 競合／ニアミス： 近接、速度差、反応のテスト（短い車間距離、距離トリガー）
   • 協調： 安全な完了が想定され、衝突なし（広い車間距離 ≥ 30m、時間または継続時間トリガー）
   • 独立： アクター同士が直接相互作用しない（背景交通、停止物体）
4. マヌーバーの順序 — それぞれ異なる動作の変化をフェーズとして特定します：走行 → 車線変更 → ブレーキ → 再開。遷移ごとにトリガー条件が必要です。
5. トリガーの選択：
   • 距離ベース（LongitudinalDistanceToActorCondition）— アクター間に速度差が必要です
   • 時間ベース（DurationCondition）— 速度に関係なく機能し、よりシンプルです
   • シミュレーション時間（SimulationTimeCondition）— 絶対時間であり、演出されたシーケンスに適しています
6. 安全性の検証 — 実行前に、車線変更シナリオで衝突が起きないことを検証します：required_gap = lane_change_distance + closing_rate × (lane_change_distance / actor_speed) + 5m

シナリオのデフォルト設定（RoadRunner により自動作成）

newScenario() が呼び出されると、RoadRunner は次を自動的に作成します。

• ルートフェーズの失敗条件としての CollisionCondition（アクター同士の衝突が発生するとシナリオは失敗します）
• ルートフェーズの終了条件としての SimulationTimeCondition（60s）

これらを重複して追加しないでください。デフォルトの衝突条件を変更するには：

rootPhase = phaseLogic.RootPhase;
% The fail condition already exists — access it directly
% To change the end time:
rootEndCond = setEndCondition(rootPhase, "SimulationTimeCondition");
rootEndCond.Time = 30;  % Override default 60s

厳守事項

1. ActorActionPhase と条件オブジェクトには必ず .Actor を設定してください — 省略しないでください
2. 1 つのフェーズに重複するアクションタイプを追加しないでください — 代わりに phase.Actions(1) を変更してください
3. キャラクターアクターにはルートが必要です — ルートがないと検証に失敗します
4. autoAnchor には近接が必要です — ポイントは道路面から 5m 以内になければなりません
5. 距離条件のルール — 有効なのは "le" と "ge" のみです（"lt"、"gt" は無効）
6. 速度条件のルール — 使用可能な値は "eq"、"gt"、"lt"、"ge"、"le"、"ne" です
7. SerialPhase の中に SerialPhase をネストできません — 中間に ParallelPhase を使用してください
8. 距離トリガーには速度差が必要です — アクターが同じ速度で移動すると、間隔は変化しません
9. ユーザーから明示的に依頼されない限り、シミュレーションを実行しないでください — シナリオの作成とシミュレーションは別々のワークフローです。数式だけを根拠にシナリオの結果（衝突、ニアミス）を主張しないでください。正解となる結果が得られるのはシミュレーションのみです
10. 決めつけず、曖昧なプロンプトは必ず確認してください — 速度、距離、タイミング、アクター数、望ましい結果（衝突、ニアミス、安全）、またはシーンが指定されていない場合は、コードを書く前に質問してください。実行前に、シナリオの分解と物理解析をユーザーに提示し、確認を得てください。推測すると、検証には通っても意図した結果にならないシナリオにつながります
11. addEndCondition ではなく setEndCondition を使用してください — フェーズごとに設定できる終了条件は 1 つだけです
12. ChangeLaneAction にはレーン追従モードが必要です — 車線変更が必要なアクターにはルートを追加しないでください
13. ルートポイントに anchorToPoint と ForwardOffset を使用しないでください — 検証に失敗します。autoAnchor のみを使用してください
14. LaneOffset によって交差点のコネクターに配置される場合があります — 車線変更シナリオでは、LaneOffset の代わりに HD Map の位置と autoAnchor を使い、検証済みの平行な車線にアクターを配置してください
15. 車線変更の方向を推測しないでください — 別のアクターの車線を目標にする場合は LaneChangeReference="actor" と Direction="same-lane" を使用するか、外積で方向を計算してください（references/scenario-templates.md を参照）
16. 並列グループの終了条件 は子フェーズではなく .ParentPhase に設定してください
17. 配置後に WorldPosition を確認してください — [0 0 0] はアンカー設定が失敗していることを示します
18. アクターを削除する API はありません — removeActor は存在せず、アンカー設定後の WorldPosition は読み取り専用です。配置を間違えた場合は newScenario() を使って再構築する必要があります。実行前に配置を慎重に計画してください。
19. 車線境界では autoAnchor の信頼性が低くなります — HD Map の位置を問い合わせる際は、分数を 0.2 以上 0.8 以下にしてください。車線の始点・終点では複数の車線が合流するため、autoAnchor が誤った車線にスナップする場合があります。
20. 車線変更時の安全マージン — 車線変更では、縦方向の間隔が次の値を超えるようにしてください：lane_change_distance + (closing_rate × maneuver_time) + vehicle_length。5 m/s の接近率で 20m の車線変更を行う場合、初期間隔は 30m 以上必要です。
21. 車両のルートセグメントはデフォルトでフリーフォームです — 車両のウェイポイントを追加した後、各セグメントで seg.Freeform = false を設定し、ルートが道路の形状に沿うようにしてください。歩行者は道路を横断するため、フリーフォームの経路が必要です。歩行者のルートではフリーフォームを無効にしないでください。
22. 経路追従アクターには衝突物理がありません — 経路を持つ経路追従モードの車両は、互いをすり抜けます。バンパー間の距離が 50mm 以下になると RoadRunner が衝突を検出し、シナリオを終了します。衝突のタイミングは、中心間距離ではなくバンパー間距離を使って設計してください。
23. 衝突間隔の計算式 — 中心間距離ではなく、バンパー間の距離を使います：bumper_gap = center_distance - (vehicle1_length/2 + vehicle2_length/2)。タイミング：t_collision = bumper_gap / closing_rate。停止状態からの加速には約 1 秒かかることを考慮してください（車両は目標速度に瞬時には達しません）。
24. 正面衝突はサポートされていません — LaneOffset は正の値でなければならず、プログラム API を介して同じ道路セグメント上に向かい合わせで 2 台の車両を配置することはできません。代わりに追突または交差経路での衝突を設計してください。
25. 初期間隔はトリガー距離より大きくなければなりません — アクター同士の初期間隔がトリガー条件の距離しきい値より小さい場合、条件が即座に発動し、意図したタイミングより前にフェーズが進みます。
26. setEndCondition の戻り値にプロパティ代入を連結しないでください — setEndCondition(phase,"Type").Property = N は ActorActionPhase では失敗します（InitialPhase でのみ動作します）。必ず戻り値を先に格納してください：c = setEndCondition(phase, "Type"); c.Property = N;。この 2 行のパターンはすべてのフェーズタイプで動作します。
27. ActorActionPhase ごとにアクションは 1 つだけです — フェーズごとに addAction を呼び出すのは 1 回だけにしてください。例外は initialPhaseForActor によって自動作成される初期フェーズのみです。アクションを同時に実行するには、アクションごとに 1 つの ActorActionPhase 子要素を持つ ParallelPhase を使用してください。
28. アクターの配置にワールド座標系のオフセットを使用しないでください — egoPos + [X, Y, 0] が動作するのは、道路がワールド軸に平行な場合のみです。歩行者や横断するアクターには、必ず helperGetPositionFromHDMap を使って位置と方位を取得し、垂直な横断方向を計算してください：hdg2D = hdg(1:2)/norm(hdg(1:2)); perpDir = [-hdg2D(2), hdg2D(1), 0];
29. 交差点のシーンでは、交差点の別の腕を横切るルートを設定しないでください — FourWaySignal、FourWayStop、T_Intersection では、ルーティング API を介して進入車線を反対側の退出車線に接続できません。単一の腕のルート（進入車線 → 同じコリドー内の接続された退出車線）を使うか、車線追従モードのみを使用してください。交差する腕を横断するルートは validate に失敗します。
30. 車線の長さを過度に絞り込まないでください — helperSceneAwareness のパラメーターは MinLaneLength（デフォルトは 30）です。helperSurveyLanes／helperGetPositionFromHDMap では MinLength を使用してください。交差点のシーンでは進入車線が短いため、30 を使用してください。必要な長さは max_speed × scenario_duration + 20m で計算します。小規模なシーンで 80 以上を使用すると、想定より少ない車線しか残りません。

よくある誤ったプロパティ名

誤り（幻覚によるもの）	正しい名前
RelativeLaneOffset	NumLanesOffset
SimulationTime	SimulationTimeCondition
addEndCondition	setEndCondition
listAssets / getAssets	getAsset(proj, path, type)
getActors / listActors	rrs.Actors
actor.Speed	initPhase.Actions(1).Speed
route.addWaypoint	addPoint(route, position)
removeActor / deleteActor	存在しません — newScenario() を使用してください
actor.WorldPosition = ...	読み取り専用です — newScenario() を使って再配置してください
cond.Comparison	SimulationTimeCondition には存在しません（.Time を設定するだけです）
rrApp.ProjectFolder	パブリックプロパティではありません — status(rrApp) を使用してください
DistanceType = "gap"	"space"（空間）または "time"（時間間隔）を使用してください
ConstraintType = "acceleration"	"asset"、"custom"、または "none" を使用してください
PhaseState = "completed"	"end" を使用してください（有効な値："idle"、"start"、"run"、"end"）
MeasureDistance = "euclidean"	"lane" または "actor" を使用してください
"MovableObjects/..."	"MovableObjectAsset" タイプとともに "Props/TrafficControl/..." を使用してください
syncAction.TargetPoint = actor.InitialPoint	共有参照の落とし穴です — 独立した Point としてルートのウェイポイントを使用してください
LateralOffsetAction	ChangeLateralOffsetAction（完全な名前が必要です）
.Offset（ChangeLateralOffsetAction の場合）	.LateralOffset
laneTable.LaneIndex	laneTable.Index（helperSurveyLanes の列名）
action.Rate	.DynamicsDimension = "rate"; .DynamicsValue = N; を使用してください
setEndCondition(...).Property = N	c = setEndCondition(...); c.Property = N;（2 行のパターン）
MinLength（helperSceneAwareness の場合）	MinLaneLength — 下位レベルのヘルパーのみ MinLength を使用します
"text" + status(rrApp)	status(rrApp) は構造体を返します — s = status(rrApp); s.Scene.Filename を使用してください
helperPlaceActors の actors(i)	actors{i} — セル配列を返すため、中括弧でインデックス指定してください

主な関数

関数	用途	対応バージョン
roadrunnerAPI(rrApp)	オーサリング API ハンドルを作成	R2025a
addActor(rrs, asset, pos)	シナリオにアクターを追加	R2025a
getAsset(proj, path, type)	パスでアセットを読み込み	R2025a
autoAnchor(point)	点を最寄りの道路にスナップ	R2025a
anchorToPoint(pt, anchor)	点を参照点にアンカー	R2025a
addPoint(route, pos)	ルートにウェイポイントを追加	R2025a
initialPhaseForActor(logic, actor)	アクターの初期フェーズを取得	R2025a
addPhaseInSerial(logic, phase, type)	逐次フェーズを追加	R2025a
addPhaseInParallel(logic, phase, type)	並列フェーズを追加	R2025a
setEndCondition(phase, type)	フェーズのトリガーを設定	R2025a
addAction(phase, type)	動作アクションを追加	R2025a
validate(rrs)	シナリオの有効性を確認	R2025a
validate(rrs, ObjectRoot=obj)	特定のオブジェクト（フェーズ、アクター、ルート）を検証	R2025a
findActions(phase, type)	フェーズ内で指定したタイプのアクションを検索	R2025a
createAsset(proj, path, type)	新しいアセット（車両、キャラクター、動作）を作成	R2025a
getAnchors(rrApp)	シーンのアンカーを一覧表示	R2024a
"CharacterAsset" を指定した getAsset	歩行者アセットを読み込み	R2025a

アクターの移動モード

モード	トリガー	動作	互換性のあるアクション
車線追従	ルートのウェイポイントがない	設定速度でアンカーされた車線に沿って移動	ChangeLaneAction、ChangeLateralOffsetAction
経路追従	ルートのウェイポイントがある	ウェイポイントの経路に沿って移動	ChangeSpeedAction、ChangeLongitudinalDistanceAction

• 速度を設定した車両は、ルートがなくても車線に沿って自動的に走行します
• ChangeLaneAction は車線追従モード（ルートなし）でのみ動作します
• キャラクター／歩行者のアクターには必ずルートが必要です（ルートがないと検証に失敗します）

規約

• 座標系： Z-up。ワールド空間の位置は [X Y Z] で指定します
• アセットパス： プロジェクトの Assets フォルダーからの正確な相対パスを使用します（例："Vehicles/Sedan.fbx"）
• ファイルの拡張子： ディスク上では .fbx_rrx、API では .fbx を使用します。ディスク上では .rrchar_rrx、API では .rrchar を使用します
• 速度の単位： 常にメートル毎秒（m/s）を使用します
• アクターの命名： 内容がわかる名前を使用します（"Ego"、"TargetVehicle"、"Pedestrian1"）
• デフォルトシーン： ScenarioBasic.rrscene（前方車線 310 本、ScenarioStart アンカー）
• 交差点シーン： FourWaySignal、FourWayStop、T_Intersection
• ユーザーへの確認（必須）： コードを書く前に、シナリオ計画（アクター、配置、速度、タイミング、想定される結果）を提示し、ユーザーの確認を得てください。パラメーターに少しでも曖昧な点があれば、推測せずに質問してください。手戻りを防ぐうえで、これが最も重要な規約です。

スクリプト

シーンの自動解析とバッチ配置のために、これらのヘルパーをユーザーの MATLAB パスに配置します。これらは相互に依存します。helperSceneAwareness は helperSurveyLanes と helperGetPositionFromHDMap を呼び出します。

スクリプト	目的	使用するタイミング
scripts/helperSceneAwareness.m	HD Map のエクスポート、車線の調査、道路の特徴の分類、配置の推奨	アクター配置の前に最初に実行します。位置、車線の状況、特徴の分類を取得できます
scripts/helperSurveyLanes.m	種類、方向、長さによる車線のフィルタリングと並べ替え	シーン全体の解析をせずに車線の形状データが必要なとき
scripts/helperGetPositionFromHDMap.m	車線に沿った弧長補間、最近傍点の検索	車線上の特定の割合の位置を正確に取得したいとき
scripts/helperPlaceActors.m	複数のアクターの一括配置、アンカー設定、速度設定、検証	2 人以上のアクターを配置するとき。手動での追加、アンカー設定、検証の繰り返しを自動化します
scripts/helperClassifyRoadFeatures.m	高さに基づく道路特徴の分類（橋、地上、ランプ）	内部で helperSceneAwareness によって使用されます。カスタムの特徴を検索する場合は直接呼び出します

使用パターン：

% 1. Run scene awareness to get lane data and recommended positions
sceneInfo = helperSceneAwareness(rrApp, NumActors=2, ScenarioType="cut-in");

% 2. Define actor specs (do NOT pre-initialize with actorSpecs=[])
actorSpecs(1) = struct(Name="Ego", AssetPath="Vehicles/Sedan.fbx", ...
    AssetType="VehicleAsset", LaneIndex=1, Fraction=0.1, Speed=15);
actorSpecs(2) = struct(Name="Target", AssetPath="Vehicles/Sedan.fbx", ...
    AssetType="VehicleAsset", LaneIndex=2, Fraction=0.2, Speed=20);

% 3. Batch place and verify (actors is a cell array)
[actors, report] = helperPlaceActors(rrs, rrprj, phaseLogic, sceneInfo.HDMap, actorSpecs);
assert(report.AllValid, "Placement failed: " + report.Summary);
ego = actors{1}; target = actors{2};  % curly braces required

シーンの特徴の把握

複数の高さの道路があるシーン（橋、高架道路、アンダーパス）では、RoadFeature パラメーターを使って特定の道路構造を指定します。

% Place actors specifically on the bridge deck
sceneInfo = helperSceneAwareness(rrApp, NumActors=2, ScenarioType="following", ...
    RoadFeature="bridge");

% LaneIndex=1 now refers to the longest BRIDGE lane, not the longest overall lane
actorSpecs(1) = struct(Name="Leader", AssetPath="Vehicles/Sedan.fbx", ...
    AssetType="VehicleAsset", LaneIndex=1, Fraction=0.3, Speed=15, ...
    FilterLaneIDs=sceneInfo.FilteredLaneIDs);

利用可能な特徴ラベル： "bridge"、"ground"、"ramp"、"overpass"

RoadFeature を使用するタイミング：

• ユーザーが「橋の上で」「橋の下で」「ランプ上で」「高架道路上で」と指定した場合
• シーンに複数の高さの道路がある場合（橋、高速道路のインターチェンジ）
• デフォルトの配置で別の高さの道路が選ばれた場合（アクターが予想外の高さに配置される）

RoadFeature="" の場合（デフォルト）： サマリーに検出された特徴がすべて表示されるため、ユーザーにどれを指しているのか確認できます。

Road features detected:
  bridge: 10 lanes, total 700m, connected path 192m, elevation 7.9-8.6m
  ground: 3 lanes, total 490m, connected path 165m, elevation 2.4-2.8m

特徴を考慮した配置の出力フィールド：

• sceneInfo.RoadFeatures — 特徴分類の構造体全体
• sceneInfo.FilteredLaneIDs — 指定した特徴に一致する車線 ID（actorSpecs.FilterLaneIDs に渡します）
• sceneInfo.LaneNetwork — helperAnalyzeHDMapLanes から取得した車線の接続情報全体

RoadRunner 組み込みヘルパー

RoadRunner には <RoadRunner-Install>/Tools/MATLAB/api/scenario/common にサンプルヘルパー（例：helperAddCutInAndSlowCar、helperAddPedestrian）が付属しています。これらはアクターの配置に anchorToPoint と LaneOffset を使用します。

組み込みヘルパーが適している場合： 車線が明確に分かれている単純なシーン（直線道路、既知のレイアウト）。

このスキルの方法を優先する場合： 交差点があるシーン、複雑なレイアウト、または形状が不明なシーン。LaneOffset では、車線変更に対応していない交差点の接続路にアクターが配置されることがあります。HD Map の位置と autoAnchor の組み合わせなら、どのようなシーンでも安定して動作します。

組み込みヘルパーの重要なパターン： ChangeLaneAction は LaneChangeReference="actor" と Direction="same-lane" をサポートしています。これにより、アクターは参照アクターと同じ車線へ自動的に移動し、外積による方向計算が不要になります。使用方法については、references/scenario-templates.md の Cut-In セクションを参照してください。

リファレンス

• references/actions-and-conditions.md — すべてのアクションタイプと条件タイプ、およびそのプロパティと有効な値を網羅したカタログです。フェーズロジックを構築する際に参照してください。
• references/routes-and-points.md — Point の全プロパティ、RouteSegment の設定、時間ベースの軌道、ルートの読み取り専用プロパティを記載しています。正確な位置指定、軌道のタイミング、曲線の設定を行う際に参照してください。
• references/collision-utility.md — 特定のアクターのペア間で衝突を分析するための CollisionUtility の設定を記載しています。衝突監視を設定する際に参照してください。
• references/asset-catalog.md — 車両およびキャラクターの利用可能なアセットパスと命名規則を記載しています。アクターを追加する際に参照してください。
• references/scene-awareness.md — helperSceneAwareness が利用できない場合に、HD Map をエクスポートしてレーン形状を照会するパターンを記載しています。未知のシーンにアクターを配置する際に参照してください。
• references/lane-connectivity.md — レーンネットワークのトポロジー、道路フィーチャの分類、接続経路の照会について記載しています。特定の道路フィーチャ（橋、ランプ）にアクターを配置する場合や、レーンの接続情報が必要な場合に参照してください。
• references/scenario-templates.md — 割り込み、歩行者横断、先行車追従、緊急ブレーキのテスト済みコードパターンを記載しています。特定のシナリオタイプを構築する際に参照してください。
• references/physics-first-design.md — 作成前の運動学的解析について記載しています。コードを記述する前に速度、車間距離、タイミングを導き出します。衝突、ニアミス、またはタイミングを伴うインタラクションのシナリオで参照してください。

---

Copyright 2026 The MathWorks, Inc.

---