roadrunner-import-scene

RoadRunner シーンのインポート

マップファイルを RoadRunner シーンにインポートして、可視化、検証、ビルドを行います。

使用する場合

• .rrhd ファイルを RoadRunner にインポートして視覚的に検証する場合
• OpenDRIVE の .xodr ファイルを RoadRunner にインポートする場合
• Lanelet2 から RRHD への変換やその他の変換後に、マップを検証する場合
• ビルドオプション（アスファルト路面、橋の検出、交差点の保持）を設定する場合

使用しない場合

• RoadRunner の起動やプロジェクトの管理 — roadrunner-core を使用してください
• RRHD マップコンテンツの作成 — roadrunner-rrhd-authoring を使用してください
• Lanelet2 から RRHD への変換 — roadrunner-convert-lanelet2-to-rrhd を使用してください
• アセットパスの検索 — roadrunner-asset-mapping を使用してください

重要なルール

• コードを実行する場合は、必ず .m ファイルに書き込んでください。 複数行の MATLAB コードを evaluate_matlab_code に直接記述しないでください。.m ファイルに書き込み、run_matlab_file で実行し、エラーが出た場合は編集してください。例外：ユーザーが「パターンを示して」または「実行しないで」と依頼した場合は、ファイルに書き込まず、コードをインラインで提示してください。
• roadrunner-core の rrApp が必要です。 このスキルでは RoadRunner を起動したり接続したりしないでください。rrApp が存在しない場合は、先に roadrunner-core を呼び出してください。
• ファイルは必ずプロジェクトフォルダーにコピーしてください。 すべてのインポートワークフローで status(rrApp).Project.Filename と copyfile() を明示的に使用してください。省略したり、変数の背後に隠したりしないでください。
• 必ず bridgeOpts.IsEnabled = true を明示的に設定してください。 橋の自動検出について、コンストラクターの既定値に依存しないでください。
• importScene の前に適用条件を確認してください。 ファイルの場所、拡張子、ビルドオプションのチェックは必須です。
• 既定では、ビルドの前に読み込みます。 ユーザーが完全なビルドを明示的に要求しない限り、ImportStep="Load" を使用してください。
• 変換されたマップに対して DetectAsphaltSurfaces = true をハードコードしないでください。 まず RRHD の閉ループトポロジーを必ず確認してください。閉ループネットワーク（多くの Lanelet2 変換が該当）では、アスファルト検出によってループの内側が埋められるため、必ず DetectAsphaltSurfaces = false を使用してください。
• 交差点が存在する場合は、必ず保持してください。 tempMap.Junctions が空でない場合は、必ず overlapOpts.IsEnabled = true、overlapOpts.PreserveJunctionLanes = true、および overlapOpts.PreserveJunctionShape = true を設定してください。RoadRunner の自動検出による交差点の再推定に依存しないでください。作成済みの形状が破棄されます。

前提条件

• 有効な rrApp ハンドルが存在すること（roadrunner-core スキルによって生成されます）
• RoadRunner プロジェクトが開いていること
• rrApp が存在しない場合は、起動して接続するために、先に roadrunner-core を呼び出してください

接続、起動、プロジェクトのライフサイクルは roadrunner-core が担当します。 このスキルでは、rrApp がすでに使用可能であることを前提としています。

インポートワークフロー

ステップ 1：新しいシーンを作成する

古いデータが残らないよう、インポート前に必ず新しいシーンを作成してください。

newScene(rrApp);

ステップ 2：ファイルをプロジェクトにコピーする（必須 — 必ず明示する）

RoadRunner では、インポートするファイルをプロジェクトフォルダー内に置く必要があります。生成するコードには、必ず以下のパターンをそのまま含めてください。ファイルがすでに存在すると想定したり、変数の背後に隠したりしないでください。

st = status(rrApp);
projectFolder = st.Project.Filename;
[~, fileName, ext] = fileparts(sourceFile);
destFile = fullfile(projectFolder, fileName + ext);
copyfile(sourceFile, destFile);

copyfile() の呼び出しや status(rrApp).Project.Filename の取得を省略しないでください。別の場所で destFile 変数を定義している場合でも、すべてのインポートワークフローでプロジェクトパスの取得とファイルのコピー処理を明示してください。

ステップ 3：マップをインポートする

RoadRunner HD Map（.rrhd）

読み込みのみ（ビルド前に RRHD ビューを確認）：

importOpts = roadrunnerHDMapImportOptions;
importOpts.ImportStep = "Load";
importScene(rrApp, destFile, "RoadRunner HD Map", importOpts);

ビルドを含む完全なインポート（条件分岐を使用 — アスファルトや交差点の設定をハードコードしないでください）：

固定テンプレートをコピーしないでください。RRHD の内容に基づいて適切な設定を決めるには、以下の「条件付きビルドオプション」セクションを必ず参照してください。適用条件のチェックにより、RRHD ファイルに対する DetectAsphaltSurfaces = true のハードコードは拒否されます。

重要： 橋の自動検出を有効にする場合は、必ず bridgeOpts.IsEnabled = true を明示的に記述してください。コンストラクターの既定値に依存しないでください。生成するコードには、この行を含める必要があります。

条件付きビルドオプション（必須 — マップの内容に応じて適用）

ビルドオプションを選ぶ前に、RRHD の内容を確認してください。次のルールに従って、特定の設定を有効または無効にします。

条件	アクション	理由
RRHD に Junctions がない（空またはゼロ）	overlapOpts.IsEnabled = false に設定します	明示的な交差点の定義がない場合、オーバーラップの検出はジオメトリのみを使用し、グループ化が不正確になります
閉ループの道路ネットワーク（レーンがリング状になっている）	buildOpts.DetectAsphaltSurfaces = false に設定します	アスファルト検出によって閉ループの内側が塗りつぶされ、不要な路面ポリゴンが作成されます
RRHD に明示的な Junctions がある	overlapOpts.PreserveJunctionLanes = true および overlapOpts.PreserveJunctionShape = true に設定します	ジオメトリから再推定するのではなく、作成済みの交差点ジオメトリとレーンの接続性を保持します

例：交差点を考慮したオプションでインポートする場合：

importOpts = roadrunnerHDMapImportOptions;
buildOpts = roadrunnerHDMapBuildOptions;
buildOpts.ClearSceneOfExistingData = true;

% Read RRHD to inspect content before build
tempMap = roadrunnerHDMap;
read(tempMap, destFile);

% Conditional: asphalt surfaces
hasClosedLoops = false;  % Detect from lane topology (any lane chain forming a cycle)
if hasClosedLoops
    buildOpts.DetectAsphaltSurfaces = false;
else
    buildOpts.DetectAsphaltSurfaces = true;
end

% Conditional: overlap groups / junctions
overlapOpts = enableOverlapGroupsOptions;
if isempty(tempMap.Junctions) || numel(tempMap.Junctions) == 0
    overlapOpts.IsEnabled = false;
else
    overlapOpts.IsEnabled = true;
    overlapOpts.PreserveJunctionLanes = true;
    overlapOpts.PreserveJunctionShape = true;
end
buildOpts.EnableOverlapGroupsOptions = overlapOpts;

bridgeOpts = autoDetectBridgesOptions;
bridgeOpts.IsEnabled = true;
buildOpts.AutoDetectBridgesOptions = bridgeOpts;

importOpts.BuildOptions = buildOpts;
importScene(rrApp, destFile, "RoadRunner HD Map", importOpts);

OpenDRIVE（.xodr）

importOpts = openDriveImportOptions;
importOpts.ImportSignals = true;
importOpts.ImportObjects = true;
importScene(rrApp, destFile, "OpenDRIVE", importOpts);

ステップ 4：シーンを保存する

[~, sceneName] = fileparts(sourceFile);
saveScene(rrApp, sceneName);

インポートオプションのリファレンス

roadrunnerHDMapImportOptions

プロパティ	説明
ImportStep	"Load"（RRHD ビューのみ）または "Unspecified"（読み込みとビルドの全工程）
LoadOptions	roadrunnerHDMapLoadOptions — オフセット、投影
BuildOptions	roadrunnerHDMapBuildOptions — ビルド設定

roadrunnerHDMapBuildOptions

プロパティ	説明	デフォルト
ClearSceneOfExistingData	既存のシーンコンテンツを削除します	自動
DetectAsphaltSurfaces	路面を生成します	自動
FitCrossSections	レーンの断面をフィットさせます	自動
CurvatureBlend	曲率ブレンド係数	自動
UseLaneGroups	編集用にレーンをグループ化します（R2024a 以降）	自動
CombineTransitionLanes	遷移レーンを統合します（R2025a 以降）	自動
AutoDetectBridgesOptions	autoDetectBridgesOptions オブジェクト	自動
EnableOverlapGroupsOptions	enableOverlapGroupsOptions オブジェクト（交差点）	自動
FixUnrealisticRoadElevation	HD ソースに起因する不自然な標高の変化を修正します	自動
FixInconsistentLaneConnections	物理的に不自然なレーン接続を削除します	自動

enableOverlapGroupsOptions

プロパティ	説明	デフォルト
IsEnabled	交差点の位置情報を使用します（false の場合はジオメトリ上のオーバーラップを使用します）	自動
PreserveJunctionLanes	インポートしたマップの元の交差点レーンを保持します	自動
PreserveJunctionShape	インポートしたマップの交差点ポリゴンジオメトリを保持します	自動
GroupName	オーバーラップグループの名前	自動

openDriveImportOptions

プロパティ	説明
ImportSignals	交通信号をインポートします
ImportObjects	静的オブジェクトをインポートします
LaneOptions	レーンの変換設定
Offset	シーンの位置オフセット
Projection	地理空間投影
ImportRegion	地域フィルター（R2024a 以降）

対応形式

形式名	ファイルの種類	対応開始バージョン
"RoadRunner HD Map"	.rrhd	R2022b
"OpenDRIVE"	.xodr	R2022a
"HERE HD Map"	（カタログ）	R2024a
"TomTom HD Map"	（カタログ）	R2024b

デフォルトの動作

ユーザーが「マップをインポートする」または「RoadRunner に読み込む」と依頼した場合：

1. rrApp が存在することを確認します（存在しない場合は roadrunner-core を呼び出します）
2. 新しいシーンを作成します（既存の内容をすべてクリアします）
3. ファイルをプロジェクトの Assets フォルダーにコピーします
4. ユーザーが RRHD ビューを確認できるよう、読み込みのみ（ImportStep="Load"）でインポートします
5. ファイル名をシーン名としてシーンを保存します

ユーザーからビルドを明示的に依頼された場合、または RRHD ビューが確認済みの場合にのみ、BuildOptions を使って全工程のビルドを実行します。

ビルドを行う際は、必ず最初に RRHD の内容を確認し、上記の「条件付きビルドオプション」セクションに従ってオプションを適用してください。マップの内容を確認せずに、固定またはハードコードされたビルドオプションを使用してはいけません。

主な機能

機能	目的
newScene(rrApp)	新しいシーンを作成します（初期状態）
status(rrApp)	プロジェクト情報を取得します（.Project.Filename）
importScene(rrApp, file, format, opts)	マップファイルをシーンにインポートします
saveScene(rrApp, name)	現在のシーンを保存します
roadrunnerHDMapImportOptions	インポートオプションを作成します（ImportStep、BuildOptionsを設定）
roadrunnerHDMapBuildOptions	ビルドオプションを作成します（アスファルト、橋、交差点）
autoDetectBridgesOptions	橋の検出設定（IsEnabled）
enableOverlapGroupsOptions	交差点の維持設定（PreserveJunctionLanes、PreserveJunctionShape）
openDriveImportOptions	OpenDRIVE 固有のインポートオプション

適用必須のゲート（必須 — インポート前に実行）

importSceneを呼び出す前に、必ずこれらのチェックを実行してください。省略しないでください。

%% --- ENFORCEMENT: RoadRunner is connected ---
try
    st = status(rrApp);
    assert(~isempty(st.Project.Filename), 'No project open');
    fprintf('RoadRunner connected, project: %s\n', st.Project.Filename);
catch
    error('RoadRunner:NotConnected', ...
        'No RoadRunner instance connected. Run the Connection Strategy block first.');
end

%% --- ENFORCEMENT: File is inside project folder ---
projectFolder = st.Project.Filename;
assert(startsWith(destFile, projectFolder) || isfile(destFile), ...
    'Import file must be inside the project folder. Copy it first.');
fprintf('File location check: PASS\n');

%% --- ENFORCEMENT: File extension matches format ---
[~, ~, ext] = fileparts(destFile);
if formatName == "RoadRunner HD Map"
    assert(ext == ".rrhd", 'Expected .rrhd file for RoadRunner HD Map format');
elseif formatName == "OpenDRIVE"
    assert(ext == ".xodr", 'Expected .xodr file for OpenDRIVE format');
end
fprintf('Format check: PASS\n');

%% --- ENFORCEMENT: Build options match RRHD content (MANDATORY for .rrhd) ---
if ext == ".rrhd"
    tempMap = roadrunnerHDMap;
    read(tempMap, destFile);

    % Junction preservation check
    if ~isempty(tempMap.Junctions) && numel(tempMap.Junctions) > 0
        assert(exist('overlapOpts','var') == 1 && overlapOpts.IsEnabled == true ...
            && overlapOpts.PreserveJunctionLanes == true ...
            && overlapOpts.PreserveJunctionShape == true, ...
            'RRHD has %d junctions — you MUST enable PreserveJunctionLanes and PreserveJunctionShape.', ...
            numel(tempMap.Junctions));
        fprintf('Junction preservation check: PASS (%d junctions preserved)\n', numel(tempMap.Junctions));
    end

    % Closed-loop / asphalt check — detect topology cycles (multi-lane or self-loop)
    hasClosedLoop = false;
    lanes = tempMap.Lanes;
    nLanes = numel(lanes);
    laneIDs = cell(1, nLanes);
    for li2 = 1:nLanes, laneIDs{li2} = char(lanes(li2).ID); end
    laneIDSet = containers.Map(laneIDs, num2cell(1:nLanes));
    % BFS from each lane: if we revisit a lane, there's a cycle
    visited = false(1, numel(lanes));
    for startIdx = 1:numel(lanes)
        if visited(startIdx), continue; end
        queue = startIdx; seen = false(1, numel(lanes)); seen(startIdx) = true;
        while ~isempty(queue)
            ci = queue(1); queue(1) = [];
            visited(ci) = true;
            succs = lanes(ci).Successors;
            for si = 1:numel(succs)
                sid = char(succs(si).Reference.ID);
                if laneIDSet.isKey(sid)
                    ni = laneIDSet(sid);
                    if ni == startIdx
                        hasClosedLoop = true; break;
                    end
                    if ~seen(ni), seen(ni) = true; queue(end+1) = ni; end
                end
            end
            if hasClosedLoop, break; end
        end
        if hasClosedLoop, break; end
    end
    if hasClosedLoop
        assert(buildOpts.DetectAsphaltSurfaces == false, ...
            'DetectAsphaltSurfaces must be false for closed-loop maps (fills interior). Set it explicitly.');
        fprintf('Asphalt detection check: PASS (disabled for closed-loop)\n');
    else
        fprintf('Asphalt detection check: PASS (no closed-loop detected)\n');
    end
end

規約

• 形式名の文字列は常に正確に指定してください："RoadRunner HD Map"、"OpenDRIVE"
• IIR の安定性にはSOS形式を使用してください（BuildOptionsが内部で処理します）
• ファイルのステージングに関するコード（status、fileparts、fullfile、copyfile）はすべて明示してください
• 複数パネルの図にはsubplotではなく、tiledlayout／nexttileを使用してください
• destFileはプロジェクトフォルダーのパスに固定してください。インポートには一時パスや相対パスを使用しないでください

---

Copyright 2026 The MathWorks, Inc.