matlab/matlab-agentic-toolkit / skills-catalog/automotive/roadrunner-build-rrhd-map
roadrunner-build-rrhd-map
VerifiedBuild, 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.
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
.osmfile (withtype=laneletrelations) to.rrhd - Looking up RoadRunner asset paths for lane markings, crosswalks, stop lines, signs, signals, barriers, props
- Importing or building a
.rrhdor OpenDRIVE.xodrfile into a RoadRunner scene - Debugging RRHD construction errors — wrong
roadrunner.hdmap.*property names or constructor syntax, alignment (green grass), missing assets,validateRRHDor 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 — useroadrunner-author-scenario(this skill only imports the.xodrscene 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 — usematlab-cosimulate-sumo-simulink - Standard OpenStreetMap files (
highway=*ways, notype=laneletrelations) — not supported; to build roads from OpenStreetMap with recorded GPS data, usematlab-use-scenario-builder - Lanelet2 routing-graph exports (
*.rg.osm, onlyrouting_costways, 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.hdmapAPI (indexing, dimension mismatch in your own code) — usematlab-debug-code
Workflow Router
| User intent | Workflow | Load |
|---|---|---|
| Build RRHD from scratch | Author | authoring/* + assets/* |
Convert Lanelet2 .osm → .rrhd | Convert | lanelet2/* → authoring/* → assets/* |
| Resolve an asset path only | Assets | assets/* |
Import / build .rrhd or .xodr in RoadRunner | Import | import/* |
| End-to-end Lanelet2 → RoadRunner scene | Convert, then Import | lanelet2/* → authoring/* → assets/* → import/* |
Key Rules
- Always write multi-line MATLAB code to
.mfiles and run withrun_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 theroadrunner.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 beforeimportScene. - Asset paths start with
Assets/; extension selects the style (.rrlms,.rrcws,.rrpms,.rrext, signs.svg_rrxor.svg). Resolve signs withresolveSignAssetand passProjectFolderto verify assets exist. - Import requires
rrAppfromroadrunner-manage-project; copy the file into the project folder, useImportStep="Load"by default, never hardcode asphalt detection, and preserve junctions when the map has them (OSM-derived maps frommatlab-use-scenario-builderfollow that skill's overlap-group default instead).
Critical API Gotchas
| Wrong | Correct |
|---|---|
LeftBoundary / RightBoundary | LeftLaneBoundary / 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 = polygon | wrap in MultiPolygon; ring property is ExteriorRing |
MarkingReference.MarkingID = 5 | MarkingID takes a Reference object |
pa.StartFraction / EndFraction | pa.Span = [0 1] |
cm.CurveMarkingTypeID, b.BarrierTypeID | MarkingTypeReference, BarrierTypeReference |
Sign.BoundingBox, bb.Position | Sign.Geometry = GeoOrientedBoundingBox with Center, Dimension, GeoOrientation |
GeoOrientation = [headingDeg 0 0], full-size Dimension | GeoOrientation = [roll pitch heading] in radians; Dimension = half-lengths |
SpeedLimit.Speed, Unit="KPH" | Value (int32), VelocityUnit="Kph" |
b = a; b.ID = "x" to copy an object | roadrunner.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
- Follow authoringWorkflow.md — shared boundaries (N lanes → N+1 boundaries), multi-lane recipe, complete 2-lane example, enforcement gate.
- Compute alignment with alignmentRules.md; derive center lines with synthesizeCenterLine.md.
- Junctions:
detectJunctionsfor overlapping lanes, or junctionPolygon.md for hand-authored polygons. Closed loops / tracks: splitClosedGeometry.md, orthogonalSplit.md. - Markings, signs, barriers: resolve paths via Resolve Asset Paths.
- Validate with validateMap.md (or
validateRRHD), thenwrite(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.
| Step | Reference |
|---|---|
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 types | extractLanelets.md, discoverRelations.md |
4. Origin, projection, way geometry (geomMap); alignment and center lines | coordinates.md, extractGeometry.md |
| 5. Split closed roads | splitClosedRoads.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 elements | buildRRHD.md, extractNonLaneElements.md, placedObjects.md; signs via resolveSignAsset (signs.md) |
| 10. Post-process: snap, heights, dedup | snapEndpoints.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:
| Element | Reference |
|---|---|
| Lane markings (incl. Japan/Germany variants) | laneMarkings.md |
| Signs (US MUTCD, German StVO, Japanese) | signs.md |
| Barriers and extrusions | barriers.md |
| Props and static objects | staticObjects.md |
| Lane types | laneTypes.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);
| Script | Inputs | Output | Example |
|---|---|---|---|
parseOSM | osmFile (string, Lanelet2 .osm) | ll2 struct: .nodes, .ways, .relations (containers.Map), .sourceFile | ll2 = parseOSM("map.osm"); |
discoverWayTypes | ways (containers.Map from parseOSM) | discovery struct of way buckets (stop lines, markings, barriers, signs, lights, unmapped); each way carries .wayID | d = discoverWayTypes(ll2.ways); |
detectAlignment | centerGeom, leftBndGeom, rightBndGeom (Nx3) | [leftAlignment, rightAlignment] ("Forward"/"Backward") | [la, ra] = detectAlignment(c, L, R); |
snapConnectedEndpoints | lanes, laneBoundaries, optional threshold (m, default 1.0) | [lanes, laneBoundaries, snapCount] | [ln, lb, n] = snapConnectedEndpoints(ln, lb); |
resolveHeightConflicts | lanes, 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); |
resolveSignAsset | rawCode (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"); |
detectClosedLoop | rrMap (roadrunnerHDMap), optional MinLoopLength= (m, default 100), MinRingLength= (m, default 30) | [hasClosedLoop, info] — info.reason, .loopLanes, .loopLength, .nRings (roundabouts) | [tf, info] = detectClosedLoop(m); |
detectJunctions | lanes, 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); |
validateRRHD | rrMap (roadrunnerHDMap) | report struct: .errors, .warnings, .isValid | r = validateRRHD(rrMap); |
Key Functions
| Function | Purpose |
|---|---|
roadrunnerHDMap, read, write | Create, read, and write HD Map objects |
roadrunner.hdmap.Lane, LaneBoundary, LaneMarking, Junction | Core road entities |
roadrunner.hdmap.AlignedReference, RelativeAssetPath, ParametricAttribution | References, asset paths, marking/speed spans |
xmlread | Parse Lanelet2 OSM XML |
importScene, roadrunnerHDMapImportOptions, roadrunnerHDMapBuildOptions | Import and build a map in RoadRunner |
enableOverlapGroupsOptions, autoDetectBridgesOptions | Junction preservation and bridge detection |
Known Limitations
- RoadRunner silently ignores
SignalTypes/Signalson.rrhdimport — 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
curbstoneways 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 positionalClassName.emptyfor empty typed arrays; Nx3 geometry everywhere- Shared boundaries: one object per source way, referenced by multiple lanes with independent alignment
containers.Mapfor 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/nexttilefor multi-panel figures
Copyright 2026 The MathWorks, Inc.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack." | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |