Roadrunner Rrhd AuthoringSAFE

The MATLAB Agentic Toolkit brings proven MATLAB capabilities to AI agents, making engineering and scientific workflows agent-ready.

The instruction file, verbatim from the audited commit — this is the text the model reads, and the surface the audit's instruction layer examines. Quoted here so you can judge it without cloning anything.

---
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](references/alignmentRules.md) | Any converter with shared/opposing boundaries |
| Center line synthesis (resample + average) | [synthesizeCenterLine.md](references/synthesizeCenterLine.md) | Any converter deriving lanes from boundary pairs |
| Junction polygon construction | [junctionPolygon.md](references/junctionPolygon.md) | Any converter inferring junctions from topology |
| Closed-loop splitting | [splitClosedGeometry.md](references/splitClosedGeometry.md), [orthogonalSplit.md](references/orthogonalSplit.md) | Any converter handling circular/oval roads |
| Left-gap topology filter | [leftGapFilter.md](references/leftGapFilter.md) | Any converter with node-matched topology |
| Endpoint snapping | [snapEndpoints.md](references/snapEndpoints.md) | Any converter with topology connections |
| Height conflict resolution | [resolveHeights.md](references/resolveHeights.md) | Any converter with overlapping lanes |
| Boundary deduplication | [deduplicateBoundaries.md](references/deduplicateBoundaries.md) | Any converter with shared/opposing boundaries from source |
| RRHD object API patterns | [apiReference.md](references/apiReference.md) | Any code constructing `roadrunner.hdmap.*` objects |
| Enforcement gate (validation) | [validateMap.md](references/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

SAFEgrade B · trust 89/100 Nothing in the source contradicts what it says it does. Grade A is reserved for packages that have also passed the behavioural sandbox.

What the source does

Filesystem

none-observed

Network

none-observed

Shell

none-observed

Dependencies

pinned

Secrets in source

none-found

Findings (0)

No findings outside the package's declared scope.

Gates applied: no_behavioural_pass.