← LeaderboardThe Skill Leaderboard

roadrunner-build-rrhd-map

Build, convert, and import RoadRunner HD Maps (.rrhd) in MATLAB. Author lanes, lane boundaries, markings, junctions, signs, barriers, and speed limits with roadrunnerHDMap; convert Lanelet2 (.osm, Autoware) maps to RRHD; resolve RoadRunner road asset paths for markings, crosswalks, signs, signals, and barriers; and import or build .rrhd or OpenDRIVE (.xodr) files into a RoadRunner scene. Use when creating road networks for driving simulation, converting Lanelet2 or other HD map sources to RRHD, looking up road asset paths, or loading and verifying a map in RoadRunner or RoadRunner Scene Builde

Published by matlab ↗matlab/matlab-agentic-toolkit

Try your first task

A source-grounded starter task has not been verified for this skill yet.

SKILL.md

name: roadrunner-build-rrhd-mapdescription: >  Build, convert, and import RoadRunner HD Maps (.rrhd) in MATLAB. Author lanes, lane boundaries,  markings, junctions, signs, barriers, and speed limits with roadrunnerHDMap; convert Lanelet2  (.osm, Autoware) maps to RRHD; resolve RoadRunner road asset paths for markings, crosswalks,  signs, signals, and barriers; and import or build .rrhd or OpenDRIVE (.xodr) files into a  RoadRunner scene. Use when creating road networks for driving simulation, converting Lanelet2 or  other HD map sources to RRHD, looking up road asset paths, or loading and verifying a map in  RoadRunner or RoadRunner Scene Builder. Not for building scenes from recorded sensor data,  running simulations, or recreating OpenSCENARIO (.xosc) scenarios.license: https://www.mathworks.com/content/dam/mathworks/license/pmrl/license.mdmetadata:   author: MathWorks  version: "2.0"

Build RoadRunner HD Maps

Build RoadRunner HD Map (.rrhd) content with the roadrunnerHDMap API, convert Lanelet2 maps to RRHD, resolve asset paths, and import the result into a RoadRunner scene. Pick the workflow from the router below and load only the references it lists.

When to Use

  • Building RRHD maps from scratch — synthetic scenes, test roads, multi-lane segments, junctions
  • Converting a Lanelet2 .osm file (with type=lanelet relations) to .rrhd
  • Looking up RoadRunner asset paths for lane markings, crosswalks, stop lines, signs, signals, barriers, props
  • Importing or building a .rrhd or OpenDRIVE .xodr file into a RoadRunner scene
  • Debugging RRHD construction errors — wrong roadrunner.hdmap.* property names or constructor syntax, alignment (green grass), missing assets, validateRRHD or enforcement-gate failures; check Critical API Gotchas first

When NOT to Use

  • Connecting to RoadRunner or managing projects/scenes without a map — use roadrunner-manage-project
  • Authoring scenarios, actors, routes, or phase logic — use roadrunner-author-scenario
  • Running or co-simulating scenarios — use roadrunner-simulate-scenario
  • Building scenes from recorded sensor data (GPS, lidar, camera) — use matlab-use-scenario-builder
  • Recreating a scenario from an OpenSCENARIO (.xosc) file — use roadrunner-author-scenario (this skill only imports the .xodr scene it references)
  • Vehicle or character asset paths, or pedestrian-crossing actors — use roadrunner-author-scenario (this skill covers crosswalk markings)
  • SUMO networks (.net.xml, .sumocfg) or OpenDRIVE for Eclipse SUMO co-simulation — use matlab-cosimulate-sumo-simulink
  • Standard OpenStreetMap files (highway=* ways, no type=lanelet relations) — not supported; to build roads from OpenStreetMap with recorded GPS data, use matlab-use-scenario-builder
  • Lanelet2 routing-graph exports (*.rg.osm, only routing_cost ways, no relations) — no geometry to convert
  • UAV simulation environments with terrain, OSM buildings, or drone platforms and sensors — use matlab-create-uav-scenario
  • General MATLAB runtime errors not tied to the roadrunner.hdmap API (indexing, dimension mismatch in your own code) — use matlab-debug-code

Workflow Router

User intentWorkflowLoad
Build RRHD from scratchAuthorauthoring/* + assets/*
Convert Lanelet2 .osm → .rrhdConvertlanelet2/* → authoring/* → assets/*
Resolve an asset path onlyAssetsassets/*
Import / build .rrhd or .xodr in RoadRunnerImportimport/*
End-to-end Lanelet2 → RoadRunner sceneConvert, then Importlanelet2/* → authoring/* → assets/* → import/*

Key Rules

  • Always write multi-line MATLAB code to .m files and run with run_matlab_file; edit on error. Exception: the user asks to "show the pattern" or "do not execute".
  • Read only the references the workflow needs — do not load everything upfront.
  • Only build what the user asked for — no extra lanes, junctions, or objects.
  • rrMap = roadrunnerHDMap; first — loads the roadrunner.hdmap.* namespace.
  • Never pass positional constructor arguments to roadrunner.hdmap.* classes — use Name=Value (RelativeAssetPath(AssetPath=...), AlignedReference(Reference=..., Alignment=...)) or create-then-assign.
  • Empty typed arrays — ClassName.empty, never [].
  • All geometry is Nx3 — include Z (default 0).
  • Boundary geometry is immutable in conversions — never flip, resample, or project source boundaries; use Alignment="Backward". Keep source elevation (never flatten Z).
  • One boundary object per source way; detect alignment for every lane — never hardcode "Forward".
  • Run the enforcement gate before write() and before importScene.
  • Asset paths start with Assets/; extension selects the style (.rrlms, .rrcws, .rrpms, .rrext, signs .svg_rrx or .svg). Resolve signs with resolveSignAsset and pass ProjectFolder to verify assets exist.
  • Import requires rrApp from roadrunner-manage-project; copy the file into the project folder, use ImportStep="Load" by default, never hardcode asphalt detection, and preserve junctions when the map has them (OSM-derived maps from matlab-use-scenario-builder follow that skill's overlap-group default instead).

Critical API Gotchas

WrongCorrect
LeftBoundary / RightBoundaryLeftLaneBoundary / RightLaneBoundary (AlignedReference)
RelativeAssetPath("path")RelativeAssetPath(AssetPath="path")
AlignedReference(ref, "Forward")AlignedReference(Reference=ref, Alignment="Forward")
lane.Predecessors = []lane.Predecessors = roadrunner.hdmap.AlignedReference.empty
Junction.Geometry = polygonwrap in MultiPolygon; ring property is ExteriorRing
MarkingReference.MarkingID = 5MarkingID takes a Reference object
pa.StartFraction / EndFractionpa.Span = [0 1]
cm.CurveMarkingTypeID, b.BarrierTypeIDMarkingTypeReference, BarrierTypeReference
Sign.BoundingBox, bb.PositionSign.Geometry = GeoOrientedBoundingBox with Center, Dimension, GeoOrientation
GeoOrientation = [headingDeg 0 0], full-size DimensionGeoOrientation = [roll pitch heading] in radians; Dimension = half-lengths
SpeedLimit.Speed, Unit="KPH"Value (int32), VelocityUnit="Kph"
b = a; b.ID = "x" to copy an objectroadrunner.hdmap.* classes are handles — assignment shares the object; construct a new one to copy

Full class/property table: references/authoring/apiReference.md. For classes or options not covered there, check help <class>, then matlab-read-documentation — do not guess property names.

Author RRHD from Scratch

  1. Follow authoringWorkflow.md — shared boundaries (N lanes → N+1 boundaries), multi-lane recipe, complete 2-lane example, enforcement gate.
  2. Compute alignment with alignmentRules.md; derive center lines with synthesizeCenterLine.md.
  3. Junctions: detectJunctions for overlapping lanes, or junctionPolygon.md for hand-authored polygons. Closed loops / tracks: splitClosedGeometry.md, orthogonalSplit.md.
  4. Markings, signs, barriers: resolve paths via Resolve Asset Paths.
  5. Validate with validateMap.md (or validateRRHD), then write(rrMap, file).

Convert Lanelet2 to RRHD

Run every step — the map is incomplete without junctions, curve markings, barriers, signs, and speed limits. Full step-by-step instructions, code constraints, and invariants: conversionPipeline.md.

StepReference
1. Parse OSM (parseOSM)readOSM.md
2. Validate format (type=lanelet present; reject standard OSM and routing graphs)conversionPipeline.md
3. Extract lanelets; discover ALL way and relation typesextractLanelets.md, discoverRelations.md
4. Origin, projection, way geometry (geomMap); alignment and center linescoordinates.md, extractGeometry.md
5. Split closed roadssplitClosedRoads.md
6. Topology (node matching, opposing filter, left-gap filter)extractTopology.md, leftGapFilter.md
7. Junctions — geometric, from overlapping lane footprints (detectJunctions, run in Step 9)extractJunctions.md
8. Semantics (markings, lane types, speed limits; crosswalks → CurveMarkings)extractSemantics.md
9. Build RRHD objects + non-lane elementsbuildRRHD.md, extractNonLaneElements.md, placedObjects.md; signs via resolveSignAsset (signs.md)
10. Post-process: snap, heights, dedupsnapEndpoints.md, resolveHeights.md, deduplicateBoundaries.md
11. Enforcement gate, then write()enforcementGate.md

After writing, print unmapped element counts, then continue with Import into RoadRunner if the user wants to view the map.

Resolve Asset Paths

Start with assetCatalog.md — extension rules, curve markings and crosswalks, signals, stencils, materials, default assets, region detection. Detailed tables:

ElementReference
Lane markings (incl. Japan/Germany variants)laneMarkings.md
Signs (US MUTCD, German StVO, Japanese)signs.md
Barriers and extrusionsbarriers.md
Props and static objectsstaticObjects.md
Lane typeslaneTypes.md

Import into RoadRunner

Requires a connected rrApp (from roadrunner-manage-project). Follow importScene.md: new scene → copy file into the project folder → enforcement gate → importScene with ImportStep="Load" → build only when asked. Choose build options (asphalt detection, junction preservation, bridges) from map content with buildOptions.md.

Scripts

For one-off calls, use evaluate_matlab_code with project_path set to this skill's scripts/ folder. Generated .m files run with run_matlab_file execute in their own folder, so add the folder explicitly at the top and remove it at the end:

skillScripts = "<absolute path to this skill>/scripts";
addpath(skillScripts);
% ... generated pipeline ...
rmpath(skillScripts);
ScriptInputsOutputExample
parseOSMosmFile (string, Lanelet2 .osm)ll2 struct: .nodes, .ways, .relations (containers.Map), .sourceFilell2 = parseOSM("map.osm");
discoverWayTypesways (containers.Map from parseOSM)discovery struct of way buckets (stop lines, markings, barriers, signs, lights, unmapped); each way carries .wayIDd = discoverWayTypes(ll2.ways);
detectAlignmentcenterGeom, leftBndGeom, rightBndGeom (Nx3)[leftAlignment, rightAlignment] ("Forward"/"Backward")[la, ra] = detectAlignment(c, L, R);
snapConnectedEndpointslanes, laneBoundaries, optional threshold (m, default 1.0)[lanes, laneBoundaries, snapCount][ln, lb, n] = snapConnectedEndpoints(ln, lb);
resolveHeightConflictslanes, laneBoundaries, optional zStep (m, default 0.15), MinSeparation= (m, default 2.0), JunctionLaneIDs= (skip crossings inside junctions)[lanes, laneBoundaries, info] — info.nComponents, .nConflicts, .nZLevels, .maxZ, .lanesAdjusted; offsets are added to source Z[ln, lb, info] = resolveHeightConflicts(ln, lb);
resolveSignAssetrawCode (string), region ("Japan"/"Germany"/"US"), optional ProjectFolder=[assetPath, objectType, code, isFallback] — objectType "sign"/"signal"; unrecognized codes → blank sign[p, t] = resolveSignAsset("jp_330-A", "Japan");
detectClosedLooprrMap (roadrunnerHDMap), optional MinLoopLength= (m, default 100), MinRingLength= (m, default 30)[hasClosedLoop, info] — info.reason, .loopLanes, .loopLength, .nRings (roundabouts)[tf, info] = detectClosedLoop(m);
detectJunctionslanes, laneBoundaries, optional MinOverlapArea= (0.01), MinOverlapFraction= (0), MinJunctionArea= (15), DropDivergeMerge= (false), MergeGap= (1 m), SideBySideLength= (4 m)[junctions, info] — Junction array (union of member lane footprints); info.laneCounts, .areas, .centers, .junctionLaneIDs[J, info] = detectJunctions(lanes, laneBoundaries);
validateRRHDrrMap (roadrunnerHDMap)report struct: .errors, .warnings, .isValidr = validateRRHD(rrMap);

Key Functions

FunctionPurpose
roadrunnerHDMap, read, writeCreate, read, and write HD Map objects
roadrunner.hdmap.Lane, LaneBoundary, LaneMarking, JunctionCore road entities
roadrunner.hdmap.AlignedReference, RelativeAssetPath, ParametricAttributionReferences, asset paths, marking/speed spans
xmlreadParse Lanelet2 OSM XML
importScene, roadrunnerHDMapImportOptions, roadrunnerHDMapBuildOptionsImport and build a map in RoadRunner
enableOverlapGroupsOptions, autoDetectBridgesOptionsJunction preservation and bridge detection

Known Limitations

  • RoadRunner silently ignores SignalTypes/Signals on .rrhd import — signals survive MATLAB write/read but do not appear in the scene.
  • RoadRunner cannot render self-closing lanes — split closed loops (see orthogonalSplit.md).
  • Track maps (closed-loop ovals): omit topology, marking attributes, and Z bumps; use natural elevation.
  • The RoadRunner Asset Library has no curb extrusion — Lanelet2 curbstone ways are reported, not built.
  • Unrecognized sign codes become a blank sign (isFallback); report their count so the user can map them.

Conventions

  • roadrunner.hdmap.* constructors: Name=Value or create-then-assign — never positional
  • ClassName.empty for empty typed arrays; Nx3 geometry everywhere
  • Shared boundaries: one object per source way, referenced by multiple lanes with independent alignment
  • containers.Map for indexed lookups in conversions; print a discovery summary — never silently drop elements
  • Copy files into the RoadRunner project folder before importScene; ImportStep="Load" unless a build is requested
  • tiledlayout/nexttile for multi-panel figures

Copyright 2026 The MathWorks, Inc.