roadrunner-scenario-simulating

RoadRunner シナリオシミュレーション

MATLAB および Simulink から RoadRunner シナリオをシミュレーションし、シミュレーションをステップ実行し、協調シミュレーションでアクターを制御し、オブザーバーを追加し、センサーを取り付け、結果を取得します。

使用する場面

• RoadRunner シナリオシミュレーションを実行したい場合
• シミュレーションをフレームごとにステップ実行したい場合
• アクターを外部から制御したい場合（協調シミュレーション）
• シミュレーションの状態を観測したい場合（読み取り専用のモニタリング）
• センサーを追加して、ターゲットのポーズや車線境界を読み取りたい場合
• シミュレーションログをプログラムから取得したい場合
• シナリオ変数を読み書きしたい場合
• Simulink との協調シミュレーションについて質問する場合
• アクターの動作の公開について質問する場合

使用しない場面

• RoadRunner の起動または接続
• シナリオの作成（エディターでのアクター、経路、動作の追加）
• シーンの構築または編集（道路、地形、アセット）
• アクターの軌跡を CSV にエクスポート — exportActorTrajectoryToCSV を直接使用してください
• drivingScenario の操作（これは別のツールボックスである Automated Driving Toolbox の機能です）

重要：drivingScenario と混同しないでください

drivingScenario（Automated Driving Toolbox の機能）は、MATLAB ネイティブのシナリオツールです。 RoadRunner シナリオシミュレーションでは、roadrunner オブジェクトのまったく異なる API を使用します。 この 2 つを混在させないでください。関連性はありません。

---

判断フロー

User wants to simulate →
  ├── Just run to completion? → Workflow A (simulateScenario)
  ├── Need step control OR programmatic log? → Workflow B (createSimulation)
  ├── Need to read actor state during sim? → Workflow C (getAttribute)
  ├── Need external actor control? →
  │     ├── From MATLAB? → Workflow D (System object co-sim)
  │     └── From Simulink? → Workflow E (Simulink blocks)
  ├── Need read-only monitoring? → Workflow F (Observers)
  └── Need sensor data during sim? → Workflow G (SensorSimulation)

---

ワークフロー A：シンプルなシミュレーション（完了まで実行）

すでに開いているシナリオをシミュレーションするだけの場合に使用します。

openScenario(rrApp, "MyScenario");
simulateScenario(rrApp, EnableLogging=true);

オプション：Pacing、IsBlocking、IsSteppingStart、EnableLogging。

重要： simulateScenario はログオブジェクトを返しません。完了まで実行するだけでよい場合に使用してください。MATLAB でシミュレーションログにプログラムからアクセスする必要がある場合は、代わりに createSimulation（ワークフロー B）を使用してください。

---

ワークフロー B：ステップ実行シミュレーション

フレームごとの制御や、プログラムからのログアクセスが必要な場合に使用します。

呼び出し順序は厳守してください： createSimulation は simulateScenario より前に呼び出す必要があります。シミュレーションの実行中または一時停止中は、シナリオサーバーが新しい接続を拒否します。また、set(rrSim, SimulationCommand="Start") の後に "Step" を指定しないでください。"Start" はシミュレーションを中断せずに完了まで実行します。

% 1. Get the simulation handle FIRST (before anything is running)
rrSim = createSimulation(rrApp);
stepSize = 0.01;
set(rrSim, StepSize=stepSize);
set(rrSim, MaxSimulationTime=30);

% 2. THEN start simulation in stepping mode
simulateScenario(rrApp, IsSteppingStart=true, IsBlocking=false, EnableLogging=true);
pause(0.5);  % Allow sim to initialize before stepping

% 3. Step through the simulation
for i = 1:numSteps
    set(rrSim, SimulationCommand="Step");
    pause(stepSize);  % REQUIRED — Step is async, must wait for frame to complete
end
set(rrSim, SimulationCommand="Stop");

simLog = get(rrSim, "SimulationLog");

重要： "Step" は非同期です。各 Step の後に必ず pause(stepSize) を追加してください。これを行わないと、コマンドが蓄積され、通知なく破棄されます。ドットメソッド構文（rrSim.step()）は使用せず、常に set(rrSim, SimulationCommand=...) を使用してください。ステップ実行中に Logging="On" を設定しないでください。simulateScenario の呼び出しで EnableLogging=true を使用してください。

SimulationCommand の値

"Start"、"Step"、"Pause"、"Continue"、"Stop"、"Replay"

Replay では位置引数構文を使用します：set(rrSim, "SimulationCommand", "Replay", fileName)

SimulationStatus のポーリング

get(rrSim, "SimulationStatus") は次の値を返します："Inactive"、"Running"、"Paused"、"Done"

非ブロッキングシミュレーションの実行時に、待機ループ内で使用します。"Done" と "Inactive" の両方を確認してください。短いシナリオでは、ポーリングが状態を検出する前に "Done" を通過することがあります：

status = get(rrSim, "SimulationStatus");
while ~ismember(status, ["Done", "Inactive"])
    pause(0.1);
    status = get(rrSim, "SimulationStatus");
end

---

ワークフロー C：アクターの状態を読み取る

ステップ実行シミュレーション中にアクター情報を取得するには、次のようにします。

注： get(rrSim, "ActorSimulation") には、常にワールドアクター（ID 0）がインデックス 1 に含まれます。これは移動できないルートアクターであり、車両ではありません。反復処理ではスキップするか、ID で絞り込んでください。

注： アクターを照会できるのは、シミュレーションがアクティブ（Running または Paused）な間だけです。"Stop" の後では、get(rrSim, "ActorSimulation") は空を返します。

% Get all actors — returns a CELL ARRAY, use {idx} not (idx)
actors = get(rrSim, "ActorSimulation");
actorSim = actors{2};  % cell indexing required; index 1 is world actor (ID 0)

% Or find a specific actor by ID (returns a single object)
% NOTE: ActorID must be uint64 — double will fail silently or error
actorSim = Simulink.ScenarioSimulation.find("ActorSimulation", ActorID=uint64(1));

% Read runtime attributes — use getAttribute, NOT property access
pose = getAttribute(actorSim, "Pose");              % 4x4 matrix
velocity = getAttribute(actorSim, "Velocity");      % 1x3 vector
angVel = getAttribute(actorSim, "AngularVelocity"); % 1x3 vector

重要： actorSim.Pose や actorSim.Velocity は使用しないでください。これらはパブリックプロパティではありません。必ず getAttribute(actorSim, "AttrName") を使用してください。

ランタイム属性："ID"、"Pose"、"Velocity"、"AngularVelocity"、"WheelPoses"、"LaneLocation"、"Children"、"Parent"、"PhaseStatus"、"ActorType"、"TrafficSignalRuntime"、"TrafficSignalControllerRuntime"

静的属性（Name、BoundingBox など）

アクターの名前やその他の静的プロパティを取得するには、ActorModel を使用します。getAttribute(actorSim, "Name") は使用しないでください（存在しません）。

actorModel = get(actorSim, "ActorModel");
actorName = getAttribute(actorModel, "Name");
boundingBox = getAttribute(actorModel, "BoundingBox");

ActorModel の静的属性：「"ID"」、「"Name"」、「"PaintColor"」、「"BoundingBox"」、「"WheelSpec"」、「"TrafficSignalSpec"」、「"TrafficSignalControllerSpec"」

---

ワークフロー D：MATLAB System Object による協調シミュレーション

アーキテクチャ

1. アクターにビヘイビアを割り当てます（以下を参照）
2. MATLAB で：実行時にアクターを制御する System object を記述します
3. System object は Simulink.ScenarioSimulation.find を使用して自身を見つけます

ビヘイビアの割り当て

R2024a： RoadRunner Scenario Editor の UI でのみビヘイビアを割り当てます（MATLAB API はありません）。

R2025a 以降： roadrunnerAPI オーサリングインターフェイスを介して、プログラムでビヘイビアを割り当てます。

rrApi = roadrunnerAPI(rrApp);
prj = rrApi.Project;
scnro = rrApi.Scenario;

% Get or create a behavior asset
behaviorAsset = getAsset(prj, "Behaviors/MyBehavior.rrbehavior", "BehaviorAsset");

% Assign to an existing actor
car.BehaviorAsset = behaviorAsset;

重要な点：

• roadrunnerAPI(rrApp) を使用すると、Project オブジェクトと Scenario オブジェクトにアクセスできます
• getAsset(prj, path, "BehaviorAsset") を使用して、既存の .rrbehavior アセットを取得します
• createAsset(prj, path, "BehaviorAsset") を使用して、新しいビヘイビアアセットを作成します
• ビヘイビアアセットを作成した後、プラットフォームを設定します：setPlatform(behaviorAsset, "SimulinkPlatform")。これは MATLAB System object と Simulink モデルの両方に正しい設定です。"MATLAB"、"External"、"MATLABSystem" は登録されていないため、使用しないでください
• Vehicle／Character／MovableObject の BehaviorAsset プロパティを介して割り当てます
• setBehavior() 関数はありません。代わりにプロパティを割り当ててください

System Object パターン

classdef MyActorController < matlab.System
    properties (Access = private)
        ActorSim  % ActorSimulation handle
    end

    methods (Access = protected)
        function setupImpl(obj)
            obj.ActorSim = Simulink.ScenarioSimulation.find( ...
                "ActorSimulation", SystemObject=obj);
        end

        function stepImpl(obj)
            action = getAction(obj.ActorSim, "PathAction");
            currentPose = getAttribute(obj.ActorSim, "Pose");

            % Modify pose
            currentPose(1,4) = currentPose(1,4) + 0.5;
            setAttribute(obj.ActorSim, Pose=currentPose);

            % Signal action completion (guard: ActionID may not exist)
            if ~isempty(action) && isfield(action, "ActionID")
                sendEvent(obj.ActorSim, "ActionComplete", action.ActionID);
            end
        end
    end
end

アクター制御メソッド

setAttribute(actorSim, Pose=poseMatrix);            % 4x4
setAttribute(actorSim, Velocity=[vx vy vz]);        % 1x3
setAttribute(actorSim, AngularVelocity=[wx wy wz]); % 1x3

action = getAction(actorSim, "PathAction");
action = getAction(actorSim, "SpeedAction");
action = getAction(actorSim, "LaneChangeAction");

sendEvent(actorSim, "ActionComplete", actionID);
sendEvent(actorSim, "UserDefinedEvent", eventName, eventStruct);
eventData = receiveEvent(actorSim, "UserDefinedEvent", eventName);

---

ワークフロー E：Simulink による協調シミュレーション

アーキテクチャ

1. ルートレベルに RoadRunner Scenario ブロックを配置した Simulink モデルを作成します
2. RoadRunner Scenario Reader ブロックを使用して RoadRunner からデータを受信します
3. RoadRunner Scenario Writer ブロックを使用してデータを送り返します
4. ビヘイビアを公開します：Simulink.publish.publishActorBehavior("myModel", OutputFile="output.slprotodata")
5. アクターにビヘイビアを割り当てます（RoadRunner UI、または R2025a 以降ではプログラムで割り当てます。ワークフロー D を参照してください）
6. set_param("myModel", SimulationCommand="start") でシミュレーションを開始します。sim() は使用しないでください

主な制約

• RoadRunner Scenario ブロックはモデルのルートレベルに配置する必要があります
• set_param(..., SimulationCommand="start") を使用して開始します。sim("model") は絶対に使用しないでください
• RoadRunner Scenario ブロックのサンプル時間で協調シミュレーションのステップサイズが定義されます（既定値は 0.02s）
• MATLAB インスタンスは、一度に 1 つの RoadRunner 協調シミュレーションに接続します
• バスタイプは rrScenarioSimTypes.mat から読み込まれます

Reader トピック

アクターの姿勢、仕様、レーン位置、車両のホイール姿勢、交通信号、目標姿勢、レーン境界、アクション（経路／速度／レーン変更など）、ユーザー定義イベント

Writer トピック

アクターの姿勢、車両の姿勢、アクション完了、ユーザー定義イベント、診断情報

ブロックの設定とバスタイプについては、references/simulink-cosim-details.md を参照してください。

---

ワークフロー F：オブザーバー（読み取り専用の監視）

オブザーバーは、シミュレーション状態を変更せずに監視します。協調シミュレーションのビヘイビア（UI で割り当てる）とは異なり、オブザーバーはプログラムで追加します。

rrSim = createSimulation(rrApp);
addObserver(rrSim, "VelocityMonitor", "MyVelocityObserver");
simulateScenario(rrApp, IsBlocking=false);
% Observer's stepImpl is called each step automatically

注： オブザーバーの .m ファイルは MATLAB パス上に置く必要があります。必要に応じて addpath を使用してください。シミュレーションを開始する前に addObserver を呼び出してください。

オブザーバーの System Object パターン

classdef MyVelocityObserver < matlab.System
    properties (Access = private)
        ScenarioSim
    end

    methods (Access = protected)
        function setupImpl(obj)
            obj.ScenarioSim = Simulink.ScenarioSimulation.find( ...
                "ScenarioSimulation");
        end

        function stepImpl(obj)
            actors = get(obj.ScenarioSim, "ActorSimulation");
            for idx = 1:numel(actors)
                vel = getAttribute(actors{idx}, "Velocity");
                % Read-only analysis — logging, visualization, etc.
            end
        end
    end
end

重要： オブザーバーは読み取り専用です。getAttribute は呼び出せますが、setAttribute は呼び出してはいけません。setupImpl では ActorSimulation ではなく ScenarioSimulation を見つけます。

管理：

• addObserver(rrSim, name, fileName) — 追加します（論理値の成功結果を返します）
• removeObserver(rrSim, name) — 削除します
• get(rrSim, "Observers") — 登録済みオブザーバーを照会します

R2024b 以降では、オブザーバーとして Simulink モデル（.slx）を使用することもできます。

ワークフロー G：センサーシミュレーション

アクターに運転センサーを取り付け、シミュレーション中にグラウンドトゥルースデータを読み取ります。

rrSim = createSimulation(rrApp);
sensorSim = get(rrSim, "SensorSimulation");

% Create and attach sensors to ego vehicle (actor ID 1)
visionSensor = visionDetectionGenerator(SensorIndex=1, ...
    SensorLocation=[2.4 0], MaxRange=50);
radarSensor = drivingRadarDataGenerator(SensorIndex=2, ...
    MountingLocation=[1.8 0 0.2]);
addSensors(sensorSim, {visionSensor, radarSensor}, 1);

% During step loop
set(rrSim, SimulationCommand="Start");
for i = 1:numSteps
    set(rrSim, SimulationCommand="Step");
    targets = targetPoses(sensorSim, 1);       % struct array in ego frame
    lanes = laneBoundaries(sensorSim, 1);      % lane boundary data
end
set(rrSim, SimulationCommand="Stop");

重要なポイント：

• SensorSimulation は get(rrSim, "SensorSimulation") で取得します。直接構築してはいけません
• 各センサーには一意の SensorIndex を指定する必要があります
• targetPoses(sensorSim, actorID) の第 2 引数は、自車両（addSensors でセンサーを取り付けた車両）の actorID です。SensorIndex ではありません
• targetPoses は、ホスト車両を基準とした位置と速度を返します
• laneBoundaries は OutputOption に対応しています："EgoLane"、"EgoAdjacentLanes"、"AllLanes"

対応するセンサー：visionDetectionGenerator、drivingRadarDataGenerator、ultrasonicDetectionGenerator、lidarPointCloudGenerator、lidarSensor

---

シナリオ変数

% Get a variable
value = getScenarioVariable(rrApp, "EgoSpeed");

% Set a variable (value MUST be a string)
setScenarioVariable(rrApp, "EgoSpeed", "30");

% Get all variables — returns struct ARRAY with Name/Value fields
allVars = getAllScenarioVariables(rrApp);
for i = 1:numel(allVars)
    fprintf("%s = %s\n", allVars(i).Name, allVars(i).Value);
end

fieldnames(allVars) は使用しないでください。構造体のフィールド名（Name、Value）が返され、変数名は返されません。

---

シミュレーションログ

プログラムからログにアクセスするには、ステップモードまたはシミュレーションの完了が必要です。

% After simulation completes (or during stepping)
simLog = get(rrSim, "SimulationLog");

% Query actor pose history — returns struct array with .Time and .Pose fields
poseLog = get(simLog, "Pose", "ActorID", 1);
% poseLog(i).Time  — scalar timestamp
% poseLog(i).Pose  — 4x4 transform matrix

% Extract positions for plotting
positions = arrayfun(@(s) s.Pose(1:3,4)', poseLog, UniformOutput=false);
positions = vertcat(positions{:});  % Nx3 matrix

% Save/load logs
save(rrSim, "SimulationLog", "myLog.mat");
log = load(rrSim, "SimulationLog", "myLog.mat");

ログの戻り値形式： get(simLog, "Pose", "ActorID", id) は数値配列ではなく、構造体配列を返します。各要素には .Time（スカラー）と .Pose（4x4 行列）が含まれます。プロット用の位置を抽出するには arrayfun を使用します。

---

主な関数

関数	目的	対応バージョン
simulateScenario(rrApp)	シミュレーションを最後まで実行	R2024a
createSimulation(rrApp)	ステップ制御用の ScenarioSimulation を作成	R2022a
prepareSimulation(rrApp)	協調シミュレーションクライアントの接続前にシミュレーションデータを送信	R2024a
set(rrSim, SimulationCommand=cmd)	シミュレーションを制御	R2022a
get(rrSim, param)	シミュレーションの状態を照会	R2022a
addObserver(rrSim, name, file)	読み取り専用オブザーバーを追加	R2022a
getAttribute(actorSim, attr)	アクターの実行時状態を読み取り	R2022a
setAttribute(actorSim, NV)	アクターの状態を設定（協調シミュレーションのみ）	R2022a
getAction(actorSim, name)	割り当てられたアクションを取得	R2022a
sendEvent(actorSim, event, ...)	シナリオにイベントを送信	R2022b
receiveEvent(actorSim, event, name)	シナリオからイベントを受信	R2023a
addSensors(sensorSim, sensors, actorID)	センサーを取り付け	R2023a
targetPoses(sensorSim, sensorID)	自車両座標系で対象の位置を取得	R2023a
laneBoundaries(sensorSim, sensorID)	車線境界データを取得	R2023a
Simulink.ScenarioSimulation.find(...)	アクティブなシミュレーション／アクターを検索	R2022a
Simulink.publish.publishActorBehavior(model)	Simulink の動作を公開	R2022a
roadrunnerAPI(rrApp)	オーサリング API（Project、Scenario）を取得	R2025a
getAsset(prj, path, type)	アセット（BehaviorAsset、VehicleAsset など）を取得	R2025a
createAsset(prj, path, type)	プロジェクトに新しいアセットを作成	R2025a
addActor(scnro, asset, position)	プログラムからシナリオにアクターを追加	R2025a

関数のシグネチャ、名前と値のペア、戻り値の型については、references/simulation-api-reference.md を参照してください。

---

アーキテクチャ：アクターの動作タイプ

R2024a： 動作は RoadRunner Scenario Editor の UI でのみ割り当てられます。 R2025a 以降： car.BehaviorAsset = behaviorAsset を使用して、プログラムから動作を割り当てることもできます（ワークフロー D を参照）。

動作タイプ	意味	MATLAB での役割
すぐに実行可能	アクターが組み込みの経路／ロジックに従う	コードは不要。観察するだけです
MATLAB System	アクターが System オブジェクトによって制御される	System オブジェクトを作成します（ワークフロー D）
Simulink Model	アクターが Simulink モデルによって制御される	RR ブロックを使ってモデルを構築します（ワークフロー E）

---

よくある間違い

間違い	間違っている理由	正しい方法
rrSim.start() / .step() / .stop()	ドットメソッド構文は存在しません	set(rrSim, SimulationCommand="Start"|"Step"|"Stop")
actorSim.Pose または actorSim.Velocity	パブリックプロパティではありません	getAttribute(actorSim, "Pose")
get(rrSim, "Actors")	パラメーター名が間違っています	get(rrSim, "ActorSimulation")
set(rrSim, Logging=true)	値は文字列である必要があります	set(rrSim, Logging="On")
RoadRunner に drivingScenario を使用する	まったく別のツールボックスです	simulateScenario／createSimulation を使用します
roadrunnerScenario(name)	このクラスは存在しません	openScenario(rrApp, name) を呼び出してからシミュレーションします
協調シミュレーションに sim("model") を使用する	協調シミュレーション用のコマンドではありません	set_param("model", SimulationCommand="start")
setBehavior(actor, ...)	この関数は存在しません	car.BehaviorAsset = behaviorAsset を使用するか（R2025a 以降）、RoadRunner の UI で割り当てます
fieldnames(getAllScenarioVariables(rrApp))	構造体のフィールドを取得します。変数名ではありません	allVars(i).Name
log = simulateScenario(rrApp, ...)	戻り値はありません	createSimulation と get(rrSim, "SimulationLog") を使用します
オブザーバー内で setAttribute を使用する	オブザーバーは読み取り専用です	getAttribute のみを使用します
addSensors(rrSim, ...)	対象のオブジェクトが間違っています	SensorSimulation 上で addSensors(sensorSim, ...) を使用します
getAttribute(actorSim, "Name")	Name は静的であり、実行時の値ではありません	get(actorSim, "ActorModel") を呼び出してから、getAttribute(actorModel, "Name") を使用します
get(rrSim, "ActorSimulation") の後に actors(idx) を使用する	オブジェクト配列ではなく、セル配列が返されます	actors{idx}（セル配列のインデックス指定）を使用します
set(rrSim, SimulationCommand="Start") の後に "Step" を指定する	"Start" はそのまま実行され、ステップ実行する前にシミュレーションが完了します	先に simulateScenario(rrApp, IsSteppingStart=true, IsBlocking=false) を使用します
pause(stepSize) を入れずにステップループを実行する	"Step" は非同期であるため、コマンドが蓄積し、通知なく破棄されます	各 set(rrSim, SimulationCommand="Step") の後に pause(stepSize) を追加します
ステップ実行中に set(rrSim, Logging="On") を使用する	「シミュレーション実行中はログを有効化または無効化できません」というエラーが発生します	createSimulation の前に simulateScenario(rrApp, ..., EnableLogging=true) を使用します
actors{1} を自車両として扱う	インデックス 1 は常にワールドアクター（ID 0）であり、車両ではありません	actors{2} を使用するか、Simulink.ScenarioSimulation.find("ActorSimulation", ActorID=uint64(id)) で ID を指定して検索します
Simulink.ScenarioSimulation.find(..., ActorID=1)	ActorID は double ではなく uint64 である必要があります	ActorID=uint64(1) を使用します
ステップ実行モードで simulateScenario の後に createSimulation を呼び出す	シミュレーションが一時停止している間、サーバーは接続を拒否します	simulateScenario(rrApp, IsSteppingStart=true, ...) の前に createSimulation(rrApp) を呼び出します
targetPoses(sensorSim, sensorIndex)	2 番目の引数は sensorIndex ではなく actorID です	自車両の ID を actorID として、targetPoses(sensorSim, actorID) を使用します
setPlatform(behaviorAsset, "MATLAB")	登録済みの型文字列ではありません	MATLAB と Simulink の両方のビヘイビアに setPlatform(behaviorAsset, "SimulinkPlatform") を使用します

規則

• ScenarioSimulation では必ず set／get を使用してください。ドットメソッドは使用しないでください。
• アクターのランタイム状態には必ず getAttribute／setAttribute を使用してください。
• シンプルな実行完了までのシミュレーションには simulateScenario を使用してください。createSimulation で過剰に複雑化しないでください。
• ステップ制御、アクターのイントロスペクション、またはログへのアクセスが必要な場合は createSimulation を使用してください。
• ビヘイビアの割り当て： R2024a では RoadRunner UI を使用してください。R2025a 以降では car.BehaviorAsset = getAsset(prj, path, "BehaviorAsset") を使用してください。
• 協調シミュレーションの System オブジェクトでは、setupImpl 内で Simulink.ScenarioSimulation.find("ActorSimulation", SystemObject=obj) を使用する必要があります。
• オブザーバーは "ScenarioSimulation"（"ActorSimulation" ではありません）を検索し、読み取り専用です。
• ライフサイクル： 新しいシナリオを開く（openScenario）と、既存の rrSim は無効になります。再度 createSimulation を呼び出してください。

---

著作権 2026 The MathWorks, Inc.