roadrunner-asset-mapping

# RoadRunner Asset Mapping

Consolidated lookup tables for mapping source map format elements to RoadRunner project asset paths. All paths are relative to the project `Assets/` folder.

## When to Use

- Resolving lane marking subtypes to RoadRunner `.rrlms` asset paths
- Mapping sign codes (US MUTCD, German StVO, Japanese) to sign asset SVGs
- Looking up barrier/extrusion asset paths for fence, guard rail, jersey barrier, wall
- Finding prop/static object asset paths for placement in RRHD
- Determining region-specific sign paths based on geoReference coordinates
- Assigning lane type enums from source format lane classifications

## When NOT to Use

- Building RRHD objects from scratch — use `roadrunner-rrhd-authoring`
- Performing the full Lanelet2 conversion pipeline — use `roadrunner-convert-lanelet2-to-rrhd`
- Importing maps into RoadRunner — use `roadrunner-import-scene`

## Key Rules

- **All asset paths start with `Assets/`** — always prefix when constructing `RelativeAssetPath` objects.
- **Extension matters.** `.rrlms` = lane marking style, `.rrcws` = crosswalk style, `.rrpms` = polygon marking style, `.svg_rrx` = sign. Using wrong extension causes "Asset file is missing" on import.
- **Signs use `.svg_rrx` extension** (NOT `.svg`). The `.svg` paths in XML configs are internal references only.
- **Sign naming: descriptive English names** with region suffix (e.g., `Stop_JP_01.svg_rrx`, `MaxSpeedLimit_30_DE.svg_rrx`). The old `Sign_<code>.svg` naming is obsolete.
- **Region detection from geoReference.** Use lat/lon to determine Japan/Germany/US for sign and marking paths.
- **Runtime asset discovery is MANDATORY for signs.** Asset names vary by version — always verify file exists before assigning.

## Source Data

Asset mappings are derived from the official RoadRunner project configuration XMLs:
- `DefaultAssets.xml` — default materials and markings
- `ApolloAssetData.xml` — Apollo/Baidu HD Map format
- `OpenDriveAssetData.xml` — OpenDRIVE format
- `HEREAssetData_NA.xml` / `HEREAssetData_WE.xml` — HERE HD Map (NA/EU)
- `TomTomAssetData.xml` — TomTom HD Map format

These XML files are located in the RoadRunner project's configuration directory (typically `<RoadRunner Project>/Configuration/`).

## Lane Markings

See [references/laneMarkings.md](references/laneMarkings.md) for full mapping table.

**Key patterns:**
- All marking assets are in `Assets/Markings/` with `.rrlms` extension
- Markings are keyed by **type** (solid/dashed/double) + **color** (white/yellow)
- Default road center marking: `SolidDoubleYellow.rrlms`
- Default outer boundary: `SolidSingleWhite.rrlms`

## Signs

See [references/signs.md](references/signs.md) for full mapping table.

**CRITICAL: Asset File Extension**
- RoadRunner sign assets use **`.svg_rrx`** extension on disk (NOT `.svg`)
- The `.svg` paths in project XML configs are internal references only
- **Always use `.svg_rrx` in `RelativeAssetPath` objects** — using `.svg` causes "Could not find asset" errors

**MANDATORY: Runtime Asset Discovery**
- Sign asset names vary by RoadRunner version and installed asset libraries
- **Always verify at runtime** that the target asset exists before assigning it
- Use `dir(fullfile(projFolder, 'Assets', 'Signs', region, category, '*.svg_rrx'))` to discover available signs

**Key patterns:**
- US signs: `Assets/Signs/US/Regulatory Signs/` or `Assets/Signs/US/Warning Signs/`
- German signs: `Assets/Signs/Germany/Regulatory Signs/`
- Japan signs: `Assets/Signs/Japan/Regulatory Signs/` or `Assets/Signs/Japan/Warning Signs/`
- Sign geometry uses `GeoOrientedBoundingBox` (Center + Dimension + GeoOrientation)

**Naming convention:** Signs use **descriptive English names** with region suffix:
- Pattern: `<Description>_<Region>.svg_rrx` (e.g., `Stop_JP_01.svg_rrx`, `MaxSpeedLimit_30_JP.svg_rrx`)
- The old `Sign_<code>.svg` naming is **obsolete** — files do NOT exist on disk

**Region detection from geoReference:**
```matlab
lat = geoRef(1); lon = geoRef(2);
if lat >= 24 && lat <= 46 && lon >= 122 && lon <= 154
    region = "Japan";
elseif lat >= 35 && lat <= 72 && lon >= -10 && lon <= 25
    region = "Germany";
else
    region = "US";
end
```

**Region-specific sign paths (verified R2026a with RoadRunner_Asset_Library):**

| Sign | Japan | US | Germany |
|---|---|---|---|
| Stop | `Signs/Japan/Regulatory Signs/Stop_JP_01.svg_rrx` | `Signs/US/Stop_US.svg_rrx` | `Signs/Germany/Regulatory Signs/Stop_DE.svg_rrx` |
| Yield | — | `Signs/US/Yield_US.svg_rrx` | `Signs/Germany/Regulatory Signs/Yield_DE.svg_rrx` |
| Speed N | `Signs/Japan/Regulatory Signs/MaxSpeedLimit_<N>_JP.svg_rrx` | `Signs/US/Regulatory Signs/MaxSpeedLimit_<N>_US.svg_rrx` | `Signs/Germany/Regulatory Signs/MaxSpeedLimit_<N>_DE.svg_rrx` |
| Fallback | `Signs/Japan/Regulatory Signs/SlowDown_JP_01.svg_rrx` | `Signs/US/White_Blank_US.svg_rrx` | `Signs/Germany/Warning Signs/Danger_DE.svg_rrx` |

## Signals (Traffic Lights)

| Configuration | Asset Path |
|---|---|
| 3-light vertical (post) | `Props/Signals/Signal_3Light_Post01.fbx` |
| 3-light vertical (bare) | `Props/Signals/Signal_3Light_Bare01.fbx_rrx` |

**Authoring vs Import limitation:** You CAN author `SignalType` objects (add to `rrMap.SignalTypes`) and `Signal` instances (add to `rrMap.Signals`) in MATLAB and write the map to `.rrhd` — signal data IS written to the file and survives read/write cycles. However, RoadRunner **silently ignores** signals when importing `.rrhd` maps — signals will not appear in the RoadRunner scene after import. Show the asset paths and authoring code, but warn the user about this import limitation.

## Barriers & Extrusions

See [references/barriers.md](references/barriers.md) for full mapping table.

**Key patterns:**
- All extrusions in `Assets/Extrusions/` with `.rrext` or `.rrext.rrmeta` extension
- Barriers use `roadrunner.hdmap.BarrierType` with `ExtrusionPath`

## Props & Static Objects

See [references/staticObjects.md](references/staticObjects.md) for full mapping tab