---

name: roadrunner-rrhd-authoring description: > Build RoadRunner HD Map entities in MATLAB — lanes, boundaries, markings, junctions, signs, signals, barriers, parking. Use when creating driving scenes from scratch, authoring road networks for simulation and testing automated driving systems, or assembling RRHD maps from Lanelet2 or other HD map sources. license: https://www.mathworks.com/content/dam/mathworks/license/pmrl/license.md metadata: author: MathWorks version: "1.1"

RRHD Authoring Skill

Build RoadRunner HD Map (.rrhd) entities directly using the roadrunnerHDMap API in MATLAB. Provides the generic building blocks for constructing RRHD from any source — synthetic scenes, converted map data, or custom formats.

When to Use

• Building RRHD maps from scratch (synthetic scenes, test roads)
• Assembling RRHD entities from converted map data (Lanelet2, HERE, NDS, OpenDRIVE, custom formats)
• Need reusable geometry algorithms: alignment detection, center line synthesis, junction polygons, endpoint snapping, closed-loop splitting
• Adding lanes, boundaries, markings, junctions, signs, barriers, or parking to an HD Map
• Need verified roadrunner.hdmap.* class/property reference and construction patterns
• Debugging RRHD construction errors (wrong property names, alignment issues)

Role in Map Conversion Pipelines

This skill provides format-agnostic RRHD construction patterns that any converter skill invokes:

| Reusable Building Block | Reference | Used By | |---|---|---| | Alignment detection (Forward/Backward) | alignmentRules.md | Any converter with shared/opposing boundaries | | Center line synthesis (resample + average) | synthesizeCenterLine.md | Any converter deriving lanes from boundary pairs | | Junction polygon construction | junctionPolygon.md | Any converter inferring junctions from topology | | Closed-loop splitting | splitClosedGeometry.md, orthogonalSplit.md | Any converter handling circular/oval roads | | Left-gap topology filter | leftGapFilter.md | Any converter with node-matched topology | | Endpoint snapping | snapEndpoints.md | Any converter with topology connections | | Height conflict resolution | resolveHeights.md | Any converter with overlapping lanes | | Boundary deduplication | deduplicateBoundaries.md | Any converter with shared/opposing boundaries from source | | RRHD object API patterns | apiReference.md | Any code constructing roadrunner.hdmap.* objects | | Enforcement gate (validation) | validateMap.md | Any converter before write() |

Skill Boundaries

This skill owns (format-agnostic RRHD construction):

| Responsibility | Description | |---|---| | roadrunner.hdmap.* API | Class/property reference, constructor patterns, type rules | | Geometry algorithms | Alignment, center line, resampling, orthogonal split, snapping | | Junction polygon | Outer boundary tracing, boundary(), convhull techniques | | Validation/enforcement | Spatial checks, alignment verification, geometry dimensions | | Entity construction | Lanes, boundaries, markings, junctions, barriers, signs, signals, parking | | Import options | roadrunnerHDMapImportOptions, build options, bridge detection |

Converter skills own (source-format-specific):

| Responsibility | Description | |---|---| | Source parsing | XML/protobuf/JSON reading, node/way/relation extraction | | Coordinate projection | lat/lon → ENU, map_projector_info.yaml, local_x/local_y | | Topology extraction | Node matching, opposing-direction filter, left-gap filter | | Junction detection | BFS clustering from tags, fallback fan-in/fan-out, lane additions | | Semantic mapping | Source subtypes → RRHD LaneType, marking assets, sign codes | | Discovery & completeness | Scan all elements, report unmapped, enforce nothing is dropped |

Decision rule:

• "How do I build this RRHD object?" → RRHD authoring skill
• "How do I extract this from my source format?" → Converter skill

When NOT to Use

• Converting Lanelet2 .osm files — use roadrunner-convert-lanelet2-to-rrhd (which invokes this skill)
• Looking up asset paths for markings/signs/barriers — use roadrunner-asset-mapping
• Importing finished .rrhd into RoadRunner — use roadrunner-import-scene
• Editing an existing RoadRunner scene interactively (this skill writes .rrhd files, not scene edits)

Key Rules

• Always write to .m files when executing code. Never put multi-line MATLAB code directly in evaluate_matlab_code. Write to a .m file, run with run_matlab_file, edit on error. Exception: if the user asks to "show the pattern" or says "do not execute", show code inline without writing files.
• Read only the specific reference needed for the task — do not read all references upfront. Use apiReference.md for property lookups, other references only when directly relevant.
• Only build what the user asked for. Do not add extra lanes, junctions, or objects unless explicitly requested.
• rrMap = roadrunnerHDMap; must come first — loads the namespace before any roadrunner.hdmap.* usage.
• Create-then-assign pattern — never pass constructor args (except RelativeAssetPath and AlignedReference).
• Empty typed arrays — use ClassName.empty not [].
• All geometry must be Nx3 — always include Z column (default 0 if flat).
• Run enforcement gate before write() — alignment, spatial, and geometry checks are mandatory.
• Track maps (closed-loop ovals/circuits): OMIT topology (no Predecessors/Successors), OMIT marking attributes (no ParametricAttribution), OMIT Z bumps. Use natural elevation only. See references/orthogonalSplit.md.

Critical API Rules

You MUST create a roadrunnerHDMap object before using any roadrunner.hdmap.* classes (lazy namespace loading):

rrMap = roadrunnerHDMap;  % REQUIRED — loads the namespace

Create-then-assign pattern — never pass constructor args (except Name=Value for two classes):

ref = roadrunner.hdmap.Reference;
ref.ID = "myID";  % assign after creation

Name=Value constructors — ONLY RelativeAssetPath and AlignedReference accept Name=Value:

rap = roadrunner.hdmap.RelativeAssetPath(AssetPath="Assets/Markings/StopLine.rrlms");
ar = roadrunner.hdmap.AlignedReference(Reference=ref, Alignment="Forward");
% WRONG: positional args error with "A name is expected"

Empty typed arrays — never use [] for typed properties:

lane.Predecessors = roadrunner.hdmap.AlignedReference.empty;  % CORRECT
lane.Predecessors = [];  % WRONG: "Value must be of type AlignedReference"

Verified Property Names (R2025a+)

See references/apiReference.md for the complete verified class/property table. Key gotchas:

| Common Mistake | Correct | |---|---| | LeftBoundary | LeftLaneBoundary | | RightBoundary | RightLaneBoundary | | Speed | Value (int32) | | Unit = "KPH" | VelocityUnit = "Kph" | | ParametricAttrib | ParametricAttribution | | pa.Value = mr | pa.MarkingReference = mr | | pa.StartFraction/EndFraction | pa.Span = [0 1] (double array) | | JunctionPhase / Phase (direct) | Configurations (JunctionConfiguration array with nested .Phases) | | roadrunnerHDMap("file.rrhd") | rrMap = roadrunnerHDMap; read(rrMap, "file.rrhd") | | Nx2 geometry | Nx3 geometry (always include Z column) | | cm.CurveMarkingTypeID | cm.MarkingTypeReference | | b.BarrierTypeID | b.BarrierTypeReference | | s.SignTypeID | s.SignTypeReference | | s.BoundingBox | s.Geometry (takes GeoOrientedBoundingBox) | | bb.Position | bb.Center (1x3 double) | | bb.Orientation | bb.GeoOrientation ([h,p,r] double array) | | pg.OuterRing | pg.ExteriorRing (Nx3 double) | | bt.AssetPath | bt.ExtrusionPath (for BarrierType only) | | roadrunner.hdmap.GeoOrientation | NOT a class — use [h,p,r] double array directly | | Lane.Predecessors = [] | Lane.Predecessors = roadrunner.hdmap.AlignedReference.empty | | lb.ParametricAttributes = [] | Cannot clear — skip assignment for no markings | | RelativeAssetPath("path") | RelativeAssetPath(AssetPath="path") — Name=Value required | | AlignedReference(ref, "Fwd") | AlignedReference(Reference=ref, Alignment="Forward") | | Junction.Geometry = polygon | Junction.Geometry = multiPolygon (wrap in MultiPolygon) | | MarkingReference.MarkingID = 5 | MarkingReference.MarkingID = ref (Reference object, NOT numeric) | | SpeedLimit.Velocity | SpeedLimit.Value (int32) + .VelocityUnit = "Kph" |

Synthetic Scene Construction

Lane Width and Geometry

Standard lane width: 3.7m (US highway). Compute boundary positions by offsetting perpendicular to the lane center line direction.

Shared Boundaries Between Adjacent Lanes

Adjacent lanes MUST share boundary geometry. The right boundary of lane N is the same object as the left boundary of lane N+1. For N lanes, create N+1 boundaries.

  LB_0 (left edge)
  ───────────────────
  │    Lane_1        │  left=LB_0(Fwd), right=LB_1(Fwd)
  ───────────────────
  LB_1 (shared)
  ───────────────────
  │    Lane_2        │  left=LB_1(Fwd), right=LB_2(Fwd)
  ───────────────────
  LB_2 (right edge)

Alignment Rules

See references/alignmentRules.md for complete rules, diagrams, and green-surface debugging.

Alignment specifies how boundary geometry direction relates to lane geometry direction:

• Same direction → "Forward"
• Opposite direction → "Backward"

Which algorithm to use:

• Map conversion (left/right known from source, e.g., Lanelet2 roles) → dp-based approach below
• Synthetic scenes (left/right must be determined from geometry) → Multi-sample spatial verification in references/alignmentRules.md

Dp-based algorithm (for conversion — left/right already known):

lDir = leftPts(end,:) - leftPts(1,:);
rDir = rightPts(end,:) - rightPts(1,:);
dp = dot(lDir(1:2)/(norm(lDir(1:2))+1e-10), rDir(1:2)/(norm(rDir(1:2))+1e-10));

if dp >= -0.3
    % Normal: both boundaries go same direction
    leftAlign = "Forward"; rightAlign = "Forward";
else
    % Opposing boundaries: use proximity to determine which is backward
    d_ls_re = norm(leftPts(1,1:2) - rightPts(end,1:2));
    d_ls_rs = norm(leftPts(1,1:2) - rightPts(1,1:2));
    if d_ls_re < d_ls_rs
        leftAlign = "Forward"; rightAlign = "Backward";
    else
        leftAlign = "Backward"; rightAlign = "Forward";
    end
end

The -0.3 threshold (not 0) handles lanes with slight boundary curvature that produce small negative dot products but are NOT truly opposing.

Left/Right spatial verification (for synthetic scenes where left/right must be verified):

nSamples = min(5, size(centerGeom,1)-1);
sampleIdx = round(linspace(2, size(centerGeom,1)-1, nSamples));
leftOnLeft = 0;
for si = 1:numel(sampleIdx)
    idx = sampleIdx(si);
    localTan = centerGeom(min(idx+1,end),1:2) - centerGeom(max(idx-1,1),1:2);
    localTan = localTan / norm(localTan);
    localLeftN = [-localTan(2), localTan(1)];
    distsL = vecnorm(leftBndGeom(:,1:2) - centerGeom(idx,1:2), 2, 2);
    [~, closestL] = min(distsL);
    toBndL = leftBndGeom(closestL,1:2) - centerGeom(idx,1:2);
    if dot(toBndL, localLeftN) > 0, leftOnLeft = leftOnLeft + 1; end
end
assert(leftOnLeft >= numel(sampleIdx)/2, ...
    'Left boundary is spatially on the RIGHT — swap boundaries or fix assignment');

Wrong alignment or swapped left/right causes **green grass instead of r