Skip to content

matlab/matlab-agentic-toolkit / skills-catalog/automotive/roadrunner-build-rrhd-map

roadrunner-build-rrhd-map

Verified

Build, 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.

FileKindSize
SKILL.mdskill md15.5 KB
manifest.yamlconfig557 B
references/assets/assetCatalog.mdmarkdown7.4 KB
references/assets/barriers.mdmarkdown3.6 KB
references/assets/laneMarkings.mdmarkdown5.8 KB
references/assets/laneTypes.mdmarkdown2.2 KB
references/assets/signs.mdmarkdown5.0 KB
references/assets/staticObjects.mdmarkdown5.1 KB
references/authoring/alignmentRules.mdmarkdown10.3 KB
references/authoring/apiReference.mdmarkdown9.0 KB
references/authoring/authoringWorkflow.mdmarkdown20.4 KB
references/authoring/deduplicateBoundaries.mdmarkdown4.9 KB
references/authoring/junctionPolygon.mdmarkdown6.8 KB
references/authoring/leftGapFilter.mdmarkdown6.5 KB
references/authoring/orthogonalSplit.mdmarkdown7.7 KB
references/authoring/resolveHeights.mdmarkdown2.4 KB
references/authoring/snapEndpoints.mdmarkdown4.0 KB
references/authoring/splitClosedGeometry.mdmarkdown3.8 KB
references/authoring/synthesizeCenterLine.mdmarkdown4.6 KB
references/authoring/validateMap.mdmarkdown1.1 KB
references/import/buildOptions.mdmarkdown4.0 KB
references/import/importScene.mdmarkdown12.9 KB
references/lanelet2/buildRRHD.mdmarkdown14.2 KB
references/lanelet2/conversionPipeline.mdmarkdown13.3 KB
references/lanelet2/coordinates.mdmarkdown4.9 KB
references/lanelet2/discoverRelations.mdmarkdown2.4 KB
references/lanelet2/enforcementGate.mdmarkdown3.3 KB
references/lanelet2/extractGeometry.mdmarkdown3.4 KB
references/lanelet2/extractJunctions.mdmarkdown5.0 KB
references/lanelet2/extractLanelets.mdmarkdown2.6 KB
references/lanelet2/extractNonLaneElements.mdmarkdown14.4 KB
references/lanelet2/extractSemantics.mdmarkdown4.4 KB
references/lanelet2/extractTopology.mdmarkdown5.4 KB
references/lanelet2/placedObjects.mdmarkdown4.4 KB
references/lanelet2/readOSM.mdmarkdown4.0 KB
references/lanelet2/splitClosedRoads.mdmarkdown3.0 KB
scripts/detectAlignment.mother3.3 KB
scripts/detectClosedLoop.mother5.8 KB
scripts/detectJunctions.mother12.4 KB
scripts/discoverWayTypes.mother4.8 KB
scripts/parseOSM.mother4.0 KB
scripts/resolveHeightConflicts.mother6.8 KB
scripts/resolveSignAsset.mother7.2 KB
scripts/snapConnectedEndpoints.mother4.0 KB
scripts/validateRRHD.mother6.3 KB

references/authoring/alignmentRules.md

View on GitHub
# Alignment Rules — Lanes, Boundaries, and Travel Direction

**Reference implementation:** `scripts/detectAlignment.m`

Defines the geometry alignment conventions that prevent **green surface (grass/terrain)** rendering bugs in RoadRunner.

## Core Concept: Digitization Direction

Every geometric object has a direction defined by point order:
- **First point** = START
- **Last point** = END

All alignment is relative to this direction.

## Alignment Enum

| Value | Meaning |
|-------|---------|
| `Forward` | Referenced object runs **same direction** as the referring object |
| `Backward` | Referenced object runs **opposite direction** |

## Lane Boundary Alignment

`LeftLaneBoundary.Alignment` and `RightLaneBoundary.Alignment` describe how boundary geometry relates to **lane** geometry:

```
Forward:  lane start──────►lane end
          bnd start───────►bnd end    (same direction)

Backward: lane start──────►lane end
          bnd end◄─────────bnd start  (opposite direction)
```

### Detection Algorithm (Proximity + Multi-Sample Spatial Verification)

A simple dot product or overall direction vector is NOT sufficient — it fails on highly curved lanes (split half-ovals, U-turns, tight curves) where the chord direction (start→end) doesn't represent travel direction.

**Use this two-step algorithm:**

#### Step 1: Proximity-Based Direction

Compare boundary start/end distance to the lane center start point:

```matlab
% For each boundary independently:
dStartToLaneStart = norm(bndGeom(1,1:2) - centerGeom(1,1:2));
dEndToLaneStart   = norm(bndGeom(end,1:2) - centerGeom(1,1:2));
if dStartToLaneStart <= dEndToLaneStart
    alignment = "Forward";
else
    alignment = "Backward";
end
```

#### Step 2: Multi-Sample Spatial Verification

Sample multiple points along the center line, use LOCAL tangent at each to verify which side boundaries are on:

```matlab
nSamples = min(5, size(centerGeom,1)-1);
sampleIdx = round(linspace(2, size(centerGeom,1)-1, nSamples));
leftOnLeft = 0;
for si = 1:numel(sampleIdx)
    idx = sampleIdx(si);
    % Local tangent (NOT overall direction)
    localTan = centerGeom(min(idx+1,end),1:2) - centerGeom(max(idx-1,1),1:2);
    localTan = localTan / norm(localTan);
    localLeftN = [-localTan(2), localTan(1)];  % 90 deg CCW = left normal
    % Find closest point on left boundary to this center point
    distsL = vecnorm(leftBndGeom(:,1:2) - centerGeom(idx,1:2), 2, 2);
    [~, closestL] = min(distsL);
    toBndL = leftBndGeom(closestL,1:2) - centerGeom(idx,1:2);
    if dot(toBndL, localLeftN) > 0
        leftOnLeft = leftOnLeft + 1;
    end
end
% If left boundary is NOT on the left at majority of samples → swap left/right
if leftOnLeft < numel(sampleIdx)/2
    % Swap boundary assignments and recompute proximity alignment
end
```

**Why multi-sample?** The overall direction vector `geom(end,:) - geom(1,:)` fails catastrophically on half-oval segments where the chord cuts across the curve interior. Local tangent at each sample point always correctly identifies the geometric left/right regardless of overall curvature.

#### Simplified Algorithm for Map Conversion (Lanelet2-proven)

For converting maps where left/right boundary assignment is already known (e.g., Lanelet2 lanelets define which way is left vs right), a simpler approach works reliably:

```matlab
lDir = leftPts(end,:) - leftPts(1,:);
rDir = rightPts(end,:) - rightPts(1,:);
dp = dot(lDir(1:2)/(norm(lDir(1:2))+1e-10), rDir(1:2)/(norm(rDir(1:2))+1e-10));

if dp >= -0.3
    % Same digitization direction. Verify the left way is on the LEFT of travel —
    % if not, the lanelet is driven against its ways (inverted lanelet).
    travel = lDir(1:2)/(norm(lDir(1:2))+1e-10) + rDir(1:2)/(norm(rDir(1:2))+1e-10);
    if dot(mean(leftPts(:,1:2),1) - mean(rightPts(:,1:2),1), [-travel(2), travel(1)]) >= 0
        rightAlign = "Forward";  leftAlign = "Forward";
    else
        rightAlign = "Backward"; leftAlign = "Backward";
    end
else
    % Opposing boundaries: use proximity to determine which is backward
    d_ls_re = norm(leftPts(1,1:2) - rightPts(end,1:2));  % left start to right end
    d_ls_rs = norm(leftPts(1,1:2) - rightPts(1,1:2));    % left start to right start
    if d_ls_re < d_ls_rs
        % left_start near right_end → right is Backward
        rightAlign = "Backward";
        leftAlign = "Forward";
    else
        rightAlign = "Forward";
        leftAlign = "Backward";
    end
end
```

**Key insight:** The -0.3 threshold (not 0) handles lanes with slight boundary curvature that produce small negative dot products but are NOT truly opposing. True opposing boundaries (shared center lines between lanes going opposite directions) typically have dp < -0.7.

Source data does **not** always draw ways in the travel direction: a real highway map has 489 of 4549 lanelets whose ways run against travel (left way geometrically on the right). The inverted-lanelet check above handles them; without it the spatial enforcement gate fails. Validated on 184-lane Japanese urban maps (46 backward-right boundaries) and a 4549-lane real highway map.

#### Legacy Algorithm (d_starts/d_cross)

The `d_starts` vs `d_cross` approach below works for straight/mildly curved lanes but **MUST NOT be used as the sole spatial verification for highly curved geometry**. It is acceptable as a quick first-pass for typical road networks, but always validate with the multi-sample check above:

```matlab
d_starts = norm(leftGeom(1,1:2) - rightGeom(1,1:2));
d_cross  = norm(leftGeom(1,1:2) - rightGeom(end,1:2));

if d_starts <= d_cross
    % Both boundaries go same direction
    laneDir = (leftGeom(end,1:2)+rightGeom(end,1:2))/2 ...
            - (leftGeom(1,1:2)+rightGeom(1,1:2))/2;
    laneDir = laneDir / norm(laneDir);
    leftNormal = [-laneDir(2), laneDir(1)];
    toLeft = mean(leftGeom(:,1:2)) - mean(rightGeom(:,1:2));
    if dot(toLeft, leftNormal) >= 0
        leftAlign = "Forward"; rightAlign = "Forward";
    else
        leftAlign = "Backward"; rightAlign = "Backward";
    end
else
    % Boundaries go opposite directions
    laneDirA = leftGeom(end,1:2) - leftGeom(1,1:2);
    laneDirA = laneDirA / norm(laneDirA);
    leftNormalA = [-laneDirA(2), laneDirA(1)];
    toLB = mean(leftGeom(:,1:2)) - mean(rightGeom(:,1:2));
    if dot(toLB, leftNormalA) >= 0
        leftAlign = "Forward"; rightAlign = "Backward";
    else
        leftAlign = "Backward"; rightAlign = "Forward";
    end
end
```

**Why proximity first?** The d_starts vs d_cross comparison tells you whether the two boundary geometries were digitized in the same direction or opposing directions. This determines whether their alignments should match or be opposite.

**Why spatial verification?** The leftNormal check ensures the boundary assigned as "left" is actually on the geometric left side when looking in the lane's travel direction. Without this, you can get alignment values that are technically consistent (dot product passes) but physically wrong (boundaries swapped).

**Critical:** Use **overall direction** `(end - start)`, NOT first-segment direction `(2,:) - (1,:)`. First-segment fails for wide turn lanes where initial tangent is nearly perpendicular to overall direction.

## Left vs Right Boundary Determination

Standing at lane START, facing lane END:
- **Left boundary** = on your left-hand side
- **Right boundary** = on your right-hand side

### Verification Algorithm

```matlab
laneDir2D = laneGeom(end,1:2) - laneGeom(1,1:2);
laneDir2D = laneDir2D / norm(laneDir2D);
leftNormal = [-laneDir2D(2), laneDir2D(1)];  % 90 deg CCW rotation

centerToBnd = mean(bndGeom(:,1:2)) - mean(laneGeom(:,1:2));
if dot(centerToBnd, leftNormal) > 0
    % Boundary IS on the left → assign as LeftLaneBoundary
else
    % Boundary is on the right → assign as RightLaneBoundary
end
```

## Green Surface Bug — Root Causes

RoadRunner constructs road mesh by walking left boundary then right boundary (respecting alignment) and filling between them.

| Symptom | Root Cause | Fix |
|---------|-----------|-----|
| Green grass on road | Left/Right boundaries swapped | Verify with cross product; swap assignment |
| Green patches at curves | Alignment Forward/Backward incorrect | Recompute dot product using overall direction |
| Half-lane green | Shared boundary has wrong alignment for one lane | Each lane computes alignment independently |
| Green at intersections | First-segment direction used | Use `geom(end,:) - geom(1,:)` |

## Travel Direction

Describes traffic flow relative to lane digitization direction:

| Value | Traffic flows... | Use case |
|-------|-----------------|----------|
| `Forward` | START → END (same as digitization) | Standard one-way lanes |
| `Backward` | END → START (opposite) | Opposing lane sharing geometry |
| `Bidirectional` | Both directions | Two-way undivided roads |
| `Undirected` | No dominant direction | Sidewalks, curbs, parking |

**TravelDirection does NOT affect surface rendering.** It only affects:
- Routing/navigation logic
- Lane arrow visualization in scenario editing
- Which end is entry/exit for actors

## Predecessor/Successor Alignment

| Alignment | Connection |
|-----------|-----------|
| `Forward` | Connected lane flows same direction (predecessor END → current START) |
| `Backward` | Connected lane flows opposite (predecessor START → current START) |

```
Forward predecessor:   [pred]────►  ────►[current]
                         end      start

Backward predecessor:  ◄────[pred]  ────►[current]
                       start        start
```

## Lane Group Alignment

`LaneGroup.Lanes[i].Alignment`:
- `Forward`: lane geometry same direction as LaneGroup geometry
- `Backward`: lane geometry opposite (allows opposing lanes in one group)

## Shared Boundary Between Adjacent Lanes

Each lane computes alignment **independently** against the same boundary:

```
Lane A (W→E):          ────────────►
Shared boundary (W→E): ────────────►  (Right of A → Forward, Left of B → Forward)
Lane B (W→E):          ────────────►

Lane A (W→E):          ────────────►
Shared boundary (E→W): ◄────────────  (Right of A → Backward, Left of B → Backward)
Lane B (W→E):          ────────────►
```

----

Copyright 2026 The MathWorks, Inc.

----
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: 198kUpdated Claude CodeCodexVerifiedInstall
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: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
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: 194kUpdated Claude CodeCodexVerifiedInstall