roadrunner-convert-lanelet2-to-rrhd

# Lanelet2 to RRHD Converter

Converts Lanelet2 `.osm` files to RoadRunner HD Map `.rrhd` format.

## When to Use

- Converting a Lanelet2 `.osm` file to RoadRunner HD Map `.rrhd` format
- Importing Lanelet2 maps into RoadRunner via MATLAB
- Building RRHD from `.osm` sources that contain `type=lanelet` relations
- Need full pipeline: parse, geometry, topology, semantics, junctions, barriers, signs, markings

## When NOT to Use

- Input is a standard OpenStreetMap file (highway=* ways without `type=lanelet` relations)
- Input is OpenDRIVE `.xodr` — import directly via `roadrunner-import-scene`
- Building RRHD from scratch without a source file — use `roadrunner-rrhd-authoring`
- Only need asset path lookups — use `roadrunner-asset-mapping`

## 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.
- **ALL pipeline steps are mandatory.** Do NOT stop after writing lanes/boundaries — junctions, curve markings, barriers, signs, and speed limits must all be built.
- **Boundary geometry is IMMUTABLE.** Never flip, resample, project, or modify boundary points.
- **One boundary object per way.** Deduplicate via `wayToBndID` map.
- **Detect alignment for EVERY lane.** Never hardcode `"Forward"` for all boundaries.
- **Center line density: 1 point per meter minimum.** Use `max(10, round(avgLen), nLeft, nRight)`.
- **Run enforcement gate before `write()`.** Alignment, spatial, extension, and completeness checks are mandatory.
- **No nested function definitions.** Code runs in script context — all logic inline or anonymous functions.

## Behavior

Generate MATLAB code that performs the conversion pipeline described below. Run it via `mcp__matlab__evaluate_matlab_code`. No pre-built scripts or `addpath` calls are needed — Claude generates all code at runtime from these instructions.

**MANDATORY: ALL steps must be executed.** Do NOT stop after writing lanes/boundaries. The pipeline is incomplete without: junctions, curve markings (stop lines + crosswalks), barriers, signs, and speed limits. Every element found in the OSM MUST appear in the output RRHD.

**MANDATORY: Steps 3b and 3c (discovery) must execute IN THE SAME code block as Step 3a.** These are not optional post-processing — they are part of parsing. The discovery loop code is inlined below in Step 3. If you skip 3b/3c, the completeness gate in Step 9 will fail with assertion errors.

**Scope:** This skill supports **Lanelet2 OSM only**. If the input is a standard OpenStreetMap file (highway=* ways without `type=lanelet` relations), do NOT attempt conversion. Instead inform the user: "This file appears to be a standard OpenStreetMap road network, not a Lanelet2 map. This skill only supports Lanelet2 OSM → RRHD conversion."

**Companion skills (invoke automatically during conversion):**

| Skill | When to invoke | Purpose |
|-------|----------------|---------|
| `roadrunner-rrhd-authoring` | Step 9 (Build RRHD Objects) | Provides `roadrunner.hdmap.*` class/property reference and construction patterns |
| `roadrunner-asset-mapping` | Step 8 (Extract Semantics) | Resolves marking subtypes, sign codes, and barrier types to RoadRunner asset paths |

These skills are loaded on demand — read their references when generating RRHD construction code or resolving asset paths.

**Skill boundary:** This skill owns everything Lanelet2-specific (OSM parsing, node-ref topology, turn_direction clustering, opposing-boundary detection). For RRHD object construction patterns (alignment algorithm, center line synthesis, junction polygon, API reference), defer to `roadrunner-rrhd-authoring`.

## Coordinate System

Lanelet2 OSM nodes may use either:
- **`local_x`/`local_y` tags** — already in local meters, use directly as geometry X/Y
- **`lat`/`lon` attributes only** — geographic coordinates that MUST be projected to local meters

### Step 1: Check for `map_projector_info.yaml`

Lanelet2 datasets typically include a `map_projector_info.yaml` file in the same directory as the `.osm` file. This file specifies the projection and map origin:

```yaml
ProjectorType: TransverseMercator
VerticalDatum: WGS84
MapOrigin:
  Latitude: 42.300945
  Longitude: -83.698205
  Altitude: 0
```

**Always look for this file first.** Parse it to get `ProjectorType` and `MapOrigin`:

```matlab
projFile = fullfile(fileparts(osmFile), "map_projector_info.yaml");
if isfile(projFile)
    txt = fileread(projFile);
    latMatch = regexp(txt, 'Latitude:\s*([-\d.]+)', 'tokens');
    lonMatch = regexp(txt, 'Longitude:\s*([-\d.]+)', 'tokens');
    if ~isempty(latMatch) && ~isempty(lonMatch)
        originLat = str2double(latMatch{1}{1});
        originLon = str2double(lonMatch{1}{1});
    end
end
```

If `MapOrigin` is `[0, 0]`, the origin is implicit — use the centroid of all nodes instead.

### Step 2: Determine coordinate mode

1. **Nodes have `local_x`/`local_y`** → use directly, set `geoRef` from `map_projector_info.yaml` MapOrigin (or from node lat/lon if yaml missing)
2. **Nodes have only `lat`/`lon`** → project to local ENU meters using the origin from yaml (or node centroid as fallback)

### Step 3: Project lat/lon to local meters (when needed)

```matlab
% Origin from map_projector_info.yaml or centroid fallback
geoRef = [originLat, originLon];

% For each node, convert to local meters:
dLat = node.lat - originLat;
dLon = node.lon - originLon;
metersPerDegLat = 111132.92;
metersPerDegLon = 111132.92 * cosd(originLat);
x = dLon * metersPerDegLon;   % East
y = dLat * metersPerDegLat;   % North
z = node.ele;                  % Up (elevation)
```

Set `rrMap.GeoReference = [originLat, originLon]` so RoadRunner knows the map's geographic position.

**IMPORTANT:** This projection happens ONCE during node parsing. All downstream geometry (bo