roadrunner-rrhd-authoring

# 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. See [references/orthogonalSplit.md](references/orthogonalSplit.md).

## Critical API Rules

**You MUST create a `roadrunnerHDMap` object before using any `roadrunner.hdmap.*` classes** (lazy namespace loading):
```matlab
rrMap = roadrunnerHDMap;  % REQUIRED — loads the namespace
```

**Create-then-assign pattern** — never pass constructor args (except Name=Value for two classes):
```matlab
ref = roadrunner.hdmap.Reference;
ref.ID = "myID";  % assign after creation
```

**Name=Value constructo