Explore a CARLA map

Paths. scripts/… and references/… below are relative to the directory holding this SKILL.md. Your working directory is the user's project, not that directory, so prefix them with its absolute path or the command is not found.

Query and visualise the road network of the loaded map. Three headline uses:

1. Rundown — summary turns the map into stats and a one-paragraph description ("a dense, city-like map … mostly 2-lane roads … 12 junctions").
2. Show the topology — topology --draw overlays the modelled road graph so you can confirm it matches the map you see rendered.
3. Resolve a described element — junctions lists every junction with its centre, arm count, distance-to-map-centre and bearing, so a phrase like "the 4-way junction in the middle" resolves to a specific junction id.

Plus per-point queries: waypoint (lane facts) and navigate (next/previous).

How natural language maps to elements

This skill emits structured data; the agent does the matching (like the weather skill). "The 4-way junction in the middle" → junctions --arms 4, then pick the smallest dist ... of centre. "The northern junction" → the one whose bearing is N. Draw the chosen one with junctions --arms 4 --draw (or by id) to confirm. See references/waypoints.md for the vocabulary (centre/near/far, bearings, "biggest" = size).

Instructions

Progress:
- [ ] Step 1: Check prerequisites (bash scripts/check_env.sh), clear FAILs
- [ ] Step 2: Rundown the map (summary) if asked about layout
- [ ] Step 3: For a described element, enumerate (junctions) then filter to one
- [ ] Step 4: Draw it (--draw) to confirm modelled == visible; navigate if needed

Commands need CARLA_HOST/CARLA_PORT from scripts/env.sh. Negative coordinates: pass --at with an = (e.g. --at=-24,-57,0.6) so the leading minus isn't parsed as a flag; the space form only works for all-positive coords.

Step 1: Check prerequisites

bash scripts/check_env.sh

Step 2-4: Explore

source scripts/env.sh

# a rundown of the map
python3 scripts/waypoints.py summary

# draw the whole road topology to compare with the visible map
python3 scripts/waypoints.py topology --draw --life 180

# every junction; or just the four-way ones, nearest the centre first
python3 scripts/waypoints.py junctions
python3 scripts/waypoints.py junctions --arms 4
python3 scripts/waypoints.py junctions --arms 4 --draw     # highlight + label them

# lane facts at a point, and a forward walk along the lane
python3 scripts/waypoints.py waypoint --at 30,20,0
python3 scripts/waypoints.py navigate --at 30,20,0 --dist 2 --steps 30 --draw

On CARLA 0.10.0 (the UE5 line: 5.5 and 5.8)

Landmark.waypoint is always None on 0.10.0. Measured on Town10HD_Opt: 68 landmarks, 68 of them with waypoint is None. Every other landmark field populates normally (id, name, type, road_id, s, t, distance, orientation, transform, country, unit, value, sub_type, text, h_offset, z_offset, height, width, pitch, roll, is_dynamic, get_lane_validities).

So any code shaped landmark.waypoint.transform or landmark.waypoint.lane_id raises AttributeError: 'NoneType' there. Get the road position from the landmark itself instead — map.get_waypoint_xodr( landmark.road_id, lane_id, landmark.s), or map.get_waypoint( landmark.transform.location) when you only need the nearest lane.

get_all_landmarks, get_all_landmarks_of_type, get_all_landmarks_from_id and get_landmark_group all work on both versions. The rest of the Map/Waypoint API this skill uses — get_topology, generate_waypoints, get_waypoint, get_spawn_points, get_crosswalks — is unchanged.

Examples

Example 1: describe the map

User says: "give me a rundown of the topology"

summary. Relay the RUNDOWN paragraph (extent, road/lane counts, dominant lane count, junction breakdown, density).

Example 2: confirm the model matches what's rendered

User says: "show me the topology so I can check the map"

topology --draw on a rendered server; the green arrows trace every road segment — they should sit on the visible roads.

Example 3: resolve a described junction

User says: "highlight the 4-way junction in the middle"

junctions --arms 4 → pick the row with the smallest "of centre" distance → note its id → junctions --arms 4 --draw (or read its centre and debug-draw box there). Confirm the label lands on the central crossroads.

Example 4: navigate a lane

User says: "follow the lane forward from (30,20) for 60 m"

navigate --at 30,20,0 --dist 2 --steps 30 --draw.

Troubleshooting

Problem: summary is slow on a large map Cause: Town11/12/13 have huge road networks; stats sample every 3 m. Solution: expected; it still completes. Increase STAT_STEP in the script for a faster, coarser pass.

Problem: drawn topology/junctions not visible Cause: headless -nullrhi server, or the spectator is far away. Solution: use a rendered server (see debug-draw) and move to the map centre.

Problem: a "junction" has an odd arm count Cause: arms are counted as distinct entry road ids — merges/ramps can skew it. Solution: treat arm count as approximate; confirm visually with --draw.

Problem: waypoint --at says no driving lane Cause: the point is off-road or on a non-driving lane. Solution: move the point onto a road; the query projects to the nearest driving lane within range.

Outputs

Text reports (rundown, junction list, lane facts, navigation path) and optional world.debug overlays. No file, no world change.

Detail (the Map/Waypoint/Junction API, arm counting, bearings/centre semantics, lane topology) in references/waypoints.md.