Map Annotation

SVL Simulator supports creating, editing, and exporting of HD maps of existing 3D environments (Unity scenes) in Developer Mode. The maps can be saved in the currently supported Apollo, Autoware or Lanelet2 formats.

Map annotation objects contain a combination of data for all export formats and internal NPC navigation. The classes are organized in a specific way to better support NPC navigation. Not all data contained in an HD map import is kept in the annotation objects.

To better understand map annotation objects and how they are organized, please review existing open-source maps before attempting to create complex map annotation scenes.

Table of Contents

Creating a New Map top#

  • Make sure your roads belong to the layer of Default since waypoints will be only created on this layer.
  • Turn on Gizmos in Unity Editor Scene panel so annotation will be visible.

  • Make sure your environment has Mesh Collider Unity components added.
  • Open HD Map Annotation in Unity: Simulator -> Annotate HD Map

  • By default, map annotation is not shown. Click View All under View Modes to show all existing map annotations. Or you can click Lock View Selected to only show the annotations you are selecting. NOTE Large maps with heavy annotation will slow the Unity Editor; be sure to only enable what you need to work with. You can also use the Unity Editor features to hide objects that are not needed in the Hierarchy panel.
  • Before annotating, drag in the correct Parent Object, for example TrafficLanes. Then every new object you create will be under TrafficLanes object.
  • The expected object hierarchy is as follows:
    • Map - This prefab which will be the object containing all the HD Annotations. The MapHolder script should be added to this prefab
    • TrafficLanes - This object will hold all of the MapLaneSection and MapLane which cannot be grouped under MapLaneSection
      • MapLaneSection - This will hold all of the lanes in a section of road
      • MapLane - A single annotated lane
    • Intersections - This object will hold all of the MapIntersection
      • MapIntersection - This object will hold all of the annotations for an intersection
      • MapLane - A single annotated lane
      • MapLine - A single annotated line (e.g. a stop line)
      • MapSignal - A single annotated traffic signal
      • MapSign - A single annotated traffic sign (e.g. a stop sign)
    • BoundaryLines - This object will hold all of boundary lines
  • More notes on HD Map Annotation window:
    • Under Utilities, there are three Utility buttons
      • Snap all which will snap all your annotations to ground layer. NOTE Colliders above the annotation will catch the raycast; be sure to turn off before using this tool.
      • Remove lines which will remove all extra boundary lines in the map annotations. If two boundary lines' end points are both overlapping, one of the lines will be removed and the other will be shared.
      • Create lines which will create fake boundary lines for all lanes which miss boundary lines using fixed width. To quick annotate a map, you can first annotate lanes, click this button to create boundary lines, and then adjust them.
    • Under Create Intersection / Lane Section Holder, there are two buttons Intersection and Lane Section to create these two objects quickly and attach the corresponding scripts.

  • To make Map a prefab, drag it from the scene Hierarchy into the Project folder

  • After annotation is done, remember to save: select the Map prefab, in the Inspector click Overrides -> Apply All

Annotate Lanes top#

Create Parent Object top#

  • In the Map prefab (if you don't have one, you can create an empty game object, attaching MapHolder script and make it a prefab), create a new object and name it "TrafficLanes"
  • In the Inspector of the Map, drag the new TrafficLanes object into the Traffic Lanes holder
  • In TrafficLanes, create a new object
    • Add the MapLaneSection script to the object and position it close the section of road that will be annotated
    • You can also create a MapLaneSection object using the Lane Section button in HD Map Annotation window.
    • MapLaneSection script is needed for sections that contain more than 1 lane. For sections with only 1 lane, they can be left as a child object of the TrafficLanes object or grouped with the boundary lines under a different parent object without the MapLaneSection script.
  • Each MapLaneSection will contain parallel lanes with similar lengths
    • 1 MapLane per lane of road as well as 1 MapLine per boundary line (optional, you can use the utility button Create lines to generate fake boundary lines)
    • If the annotations will be broken up into multiple MapLane (e.g. a straight section and a curved section), multiple MapLaneSection are required
    • A MapLane cannot begin or end in the middle of another MapLane (e.g. a lane splits or merges). This situation would require a 2nd MapLaneSection to be created where the split/merge begins.
    • The other lanes on the road will also need to be broken up into multiple MapLane to be included in the multiple MapLaneSection
    • MapLaneSection is used to automate the computation of relation of neighboring lanes. Please make sure every lane under MapLaneSection has at least 3 waypoints.

Example of single lane splitting into a right-turn only lane and a straight lane

Make Lanes top#

  • Select the Lane/Line option under Create Mode
  • A large yellow TARGET_WAYPOINT will appear in the center of the scene. This is where the TEMP_WAYPOINT objects will be placed. The TARGET_WAYPOINT will not appear if your roads had no mesh collider attached.
  • Drag in the appropriate MapLaneSection to be the Parent Object
  • Click Waypoint button to create a new TEMP_WAYPOINT. This is where the lane will begin.

  • Move the scene so that the TARGET_WAYPOINT is in the desired location of the next TEMP_WAYPOINT
    • With 2 waypoints, the Create Straight function will connect the waypoints and use the number in Waypoint Count to determine how many waypoints to add in between
    • More than 2 waypoints can be used with the Create Straight function and they will be connected in the order they were created, and the Waypoint Count value will not be used
    • With 3 waypoints, the Create Curve function can be used to create a Bezier curve between the 1st and 3rd waypoints and the Waypoint Count value will be used to determine how many waypoints to add in between.

  • Verify Lane is the selected Map Object Type
  • Verify the selected Lane Turn Type is correct
  • Select the appropriate lane boundry types
  • Enter the speed limit of the lane (in m/s)
  • Enter the desired number of waypoints in the lane (minimum 2 for a straight lane and 3 for a curved lane)
  • Click the appropriate Connect button to create the lane

  • To adjust the positions of the waypoints, with the MapLane selected, in the Inspector check Display Handles. Individual waypoints can now have their position adjusted
    • You can also show each waypoint's handle by clicking Toggle Handles button in HD Map Annotation window. NOTE Be sure to toggle off when finished editing.
    • Below you can also find a group of helper buttons to manipulate the lane's waypoints.
    • Append - Adds a waypoint after the last index
    • Prepend - Adds a waypoint before the first index
    • Remove First - Removes the first waypoint
    • Remove Last - Remove the the last waypoint
    • Reverse - Reverses the waypoint order
    • Clear - Removes all waypoints
    • Double - Doubles the waypoint count
    • Half - Reduces the waypoint count be approximately half

Make Boundary Lines top#

  • Drag in the appropriate MapLaneSection to be the Parent Object
  • The same process as for lanes can be used to create boundary lines, but the Map Object Type will be BoundaryLine
  • It is better to have the direction of a boundary line match the direction of the lane if possible
  • For every boundary line, you also need to drag it into the corresponding field in the lane object.
  • Boundary lines can be combined for adjacent lanes - no need to make duplicates for the same line.
  • It is best to name boundary lines left and right so it is easier to tell which line goes into the public references on the map lane data.

Annotate Intersections top#

Create Parent Object top#

  • In the Map prefab, create a new object and name it "Intersections"
  • In the Inspector of the Map, drag the new Intersections object into the Intersections holder
  • In Intersections, create a new object
    • Add the MapIntersection script to the new object and position it in the center of the intersection that will be annotated
    • You can also create an MapIntersection object using the Intersection button in HD Map Annotation window
    • You need to adjust the Trigger Bounds of the MapIntersection so that the box covers the space of the intersection
  • The MapIntersection will contain all lanes, traffic signals, stop lines, and traffic signs in the intersection

Create Intersection Lanes top#

  • Select the Lane/Line option under Create Mode
  • Drag in the MapIntersection as the Parent Object
  • Place the intersection object in the center of the intersection.
  • The same process for creating normal MapLane is used here
  • If the Lane involves changing directions, verify the correct Lane Turn Type is selected
  • If you are annotating boundary lines for each lane, remember to set VIRTUAL as the Line Type for the line objects
  • If there is a stop line in the intersection, the start of the intersection lanes should be after the stop line
  • Be sure the trigger bounds size covers most of the intersection, in X,Y, and Z axes, but does not overlap with any stop lines. This trigger volume counts NPCs that enter the intersection and will cause errors if an NPC is counted before it reaches the intersection itself.
  • For NPCs to properly navigate an intersection, the Yield To Lanes list of a lane (usually a turning lane) must be manually filled in. With View Selected toggled in the HD Map Annotation window, the lanes in the Yield To Lanes list will be highlighted in yellow to make it easier to verify that the correct lanes are in the list. Before an NPC enters an intersection lane, it will check that there are no NPCs on the lanes in the Yield To Lanes before continuing.
    • Enter the number of lanes that the current lanes yields to as the size of Yield To Lanes
    • For each element in the list, drag in a lane that takes priority over the selected lane
      • For example, generally when turning left the NPC will yield to the oncoming traffic going straight so the straight lanes should be in the left turn lane's Yield To Lanes list

Create Traffic Signals top#

  • Select the Signal option under Create Mode
  • Drag in the MapIntersection as the Parent Object
  • Select the correct Signal Type
  • Traffic Signals are created on top of existing meshes. The signal annotation directions will be the same as the directions of the mesh. Please make sure the directions of the mesh is correct.

  • Select the mesh that is going to be annotated
  • Select the Forward Vector and Up Vector so that it matches the selected mesh

  • Click Create Signal to annotate the traffic signal
  • Make sure the bounds of the map signal match the mesh object bounds

Create Traffic Signs top#

  • Select the Sign option under Create Mode
  • Drag in the MapIntersection as the Parent Object
  • Select the Sign mesh that is going to be annotated
  • Select the Forward Vector and Up Vector so that it matches the selected mesh
  • Change the Sign Type to the desired type
  • Click Create Sign to create the annotation
  • Find the stop line MapLine that is associated with the created MapSign
  • Select the MapSign and drag the MapLine into the Stop Line box
  • Verify the annotation is created in the correct orientation. The Z-axis (blue) should be facing the same way the sign faces.
  • Move the Bounding Box so that is matches the sign
    • Bound Offsets adjusts the location of the box
    • Bound Scale adjusts the size of the box

Create Stop Lines top#

  • Select the Lane/Line option under Create Mode
  • Drag in the MapIntersection as the Parent Object
  • A similar process to boundary lines and traffic lanes is used for stop lines
  • Change the Map Object Type to StopLine
  • Forward Right vs Forward Left depend on the direction of the lane related to this stop line and the order that the waypoints were created in. The "Forward" direction should match the direction of the lane
    • Example: In a right-hand drive map (cars are on the right side of the road), if the waypoints are created from the outside of the road inwards, then Forward Right should be selected. To verify if the correct direction was selected, Toggle Tool Handle Rotation so that the tool handles are in the active object's rotation. The Z-axis of the selected Stop Line should point to the intersection.
  • A StopLine needs to be with the lanes that approach it.
  • The last waypoint of approaching lanes should be perpendicular and intersect with the stop line
  • Stop lines should be checked IsStopSign for stop sign intersections and left false for signal light intersections
  • For intersections that do not have signals, stop lines are not needed.

Create Pole top#

Poles are required for Autoware Vector maps. In an intersection with traffic lights, there is 1 MapPole on each corner, next to a stop line. The MapPole holds references to all traffic lights that signal the closest stop line.

  • Select the Pole option under Create Mode
  • Drag in the MapIntersection as the Parent Object
  • A TARGET_WAYPOINT will appear in the center of the scene. This is where the pole annotation will be created.
  • Position the TARGET_WAYPOINT on the corner of the intersection near the stop line
  • Click Create Pole to create the annotation
  • Find the traffic light MapSignal that are associated with the closest stop line
  • Select the MapPole
  • In the Inspector, change the Signal Lights size to be the number of MapSignal that signal the stop line
  • Drag 1 MapSignal into each element of Signal Lights

Annotate Self-Reversing Lanes top#

These types of lanes are only supported on Apollo 5.0

Annotation Information top#

There are TrafficLanes and Intersections objects. TrafficLanes object is for straight lane without any branch. Intersections object is for branching lanes, which has same predecessor lane.

Annotate Self-Reversing Lanes under Traffic Lanes top#

  • Add MapLaneSection game object under TrafficLanes. MapLaneSection has one pair of lanes, which are forward and reverse lanes.
  • Annotate lane given name to MapLane_forward and move it under MapLaneSection.
    • Use straight line connect menu with way point count and move each point to shape lane.
    • Use Display Lane option to show width of lane. In order for parking to work, there should have some space between parking space and lane.
  • Duplicate the MapLane_forward and rename it to MapLane_reverse.
  • Choose MapLane_reverse and click Reverse Lane.
    • Reverse Lane will have way points in reverse order and make tweak to each way point.
    • Routing module doesn't work right when forward and reverse lane have same way point coordinates.
  • Choose both lanes (MapLane_forward, MapLane_reverse) and change properties like the following:
    • Is Self Reverse Lane: True
    • Lane Turn Type: NO_TURN
    • Left Bound Type: SOLID_WHITE
    • Right Bound Type: SOLID_WHITE
    • Speed Limit: 4.444444 (This value is indicated in sunnyvale_with_two_offices map)
  • Set Self Reverse Lane for each lane
    • As for forward lane, you can drag reverse lane game object to Self Reverse Lane of forward lane.
    • As for reverse lane, you can do the same way.

Annotate Self-Reversing Lanes under Intersections top#

  • Add MapIntersection game object under Intersections. MapIntersection has several pair of lanes.
  • Annotate lane given name to MapLane_forward move it under MapIntersection.
    • Use curve connect menu with way point count, 5.
  • Duplicate the MapLane_forward and rename it to MapLane1_reverse.
  • Choose MapLane_reverse and click Reverse Lane.
    • Reverse Lane will have way points in reverse order and make tweak to each way point.
    • Routing module doesn't work right when forward and reverse lane have same way point coordinates.
  • Choose both lanes (MapLane_forward, MapLane_reverse) and change properties like the following:
    • Is Self Reverse Lane: True
    • Left Bound Type: DOTTED_WHITE
    • Right Bound Type: DOTTED_WHITE
    • Speed Limit: 4.444444 (This value is indicated in sunnyvale_with_two_offices map).
  • Choose each lane and decide its turn type considering its direction.
    • Lane Turn Type: NO_TURN or LEFT_TURN or RIGHT_TURN
  • Set Self Reverse Lane for each lane
    • As for forward lane, you can drag reverse lane game object to Self Reverse Lane of forward lane.
    • As for reverse lane, you can do the same way.

Annotate Other Features top#

Other annotation features may be included in the TrafficLanes or Intersections objects or they may be sorted into other parent objects.

Create Pedestrian NavMesh top#

To support pedestrians, the map must include a NavMesh created with the the Unity Editor.

  1. Be sure map scene is saved in the correct folder in Assets/External/Environments/YourMap
  2. Mark all walkable ground meshes as Navigation Static in the Inspector panel
  3. Open Window -> AI -> Navigation
  4. Select meshes and mark Navigation Area in the Object menu of the Navigation panel
  5. Road and Sidewalk MUST be separate meshes and layered for Pedestrian crosswalk to work (see second image below)
  6. Click Bake button in the Bake menu of the Navigation panel. NavMesh will be created in a folder named from the scene file.

Create Pedestrian Path Sidewalk top#

This annotation controls where pedestrians will pass on sidewalks. Pedestrians can walk anywhere but will stay on annotated areas if possible.

  1. Select the Pedestrian option under Create Mode
  2. Drag in the desired Parent Object
  3. A TARGET_WAYPOINT will appear in the center for the scene. This is where the TEMP_WAYPOINT will be created.
  4. Position the TARGET_WAYPOINT on the desired path
  5. Click Waypoint to create a TEMP_WAYPOINT
  6. Repeat to create a trail of TEMP_WAYPOINT along the desired path
  7. Click Connect to create the MapPedestrian object

Create Pedestrian Path Crosswalk top#

This annotation controls where pedestrians will walk on crosswalks. Pedestrians can walk anywhere but will stay on annotated areas if possible. When annotated correctly, pedestrians will only walk when signal lights are red.

  1. Select the Pedestrian option under Create Mode
  2. Drag in the MapIntersection Parent Object . This MUST be the MapIntersection object for the pedestrian to know what signal states are.
  3. Again, MapIntersection holder MUST be the parent for crosswalk map pedestrian annotation.
  4. A TARGET_WAYPOINT will appear in the center for the scene. This is where the TEMP_WAYPOINT will be created.
  5. Position the TARGET_WAYPOINT on the desired path
  6. Click Waypoint to create a TEMP_WAYPOINT start
  7. Click Waypoint to create a TEMP_WAYPOINT end
  8. Select Crosswalk type and select Z forward orientation. MapPedestrian object MUST be Z-forward INTO intersection.
  9. Click Connect to create the MapPedestrian object

Create Junction top#

Junction annotations need to be annotated for Apollo 5.0 for Map Exporter to work correctly. It converts the boundary of the intersection.

  • Select the Junction option under Create Mode
  • Drag in the desired Parent Object
  • A TARGET_WAYPOINT will appear in the center fo the scene. This is where the TEMP_WAYPOINT will be created.
  • Position the TARGET_WAYPOINT to one vertex of the junction
  • Click Waypoint to create a TEMP_WAYPOINT
  • Create the desired number of TEMP_WAYPOINTS
  • Click Connect to create the MapJunction

Create Crosswalk top#

  • Select the CrossWalk option under Create Mode
  • Drag in the desired Parent Object
  • A TARGET_WAYPOINT will appear in the center fo the scene. This is where the TEMP_WAYPOINT will be created.
  • Position the TARGET_WAYPOINT to one corner of the crosswalk
  • Click Waypoint to create a TEMP_WAYPOINT
  • Create 4 TEMP_WAYPOINT in the order shown below
  • Click Connect to create the MapCrossWalk

Create Clear Area top#

  • Select the ClearArea option under Create Mode
  • Drag in the desired Parent Object
  • A TARGET_WAYPOINT will appear in the center fo the scene. This is where the TEMP_WAYPOINT will be created.
  • Position the TARGET_WAYPOINT to one corner of the clear area
  • Click Waypoint to create a TEMP_WAYPOINT
  • Create 4 TEMP_WAYPOINT in the order shown below
  • Click Connect to create the MapClearArea

Create Parking Space top#

  • Select the ParkingSpace option under Create Mode
  • Drag in the desired Parent Object
  • A TARGET_WAYPOINT will appear in the center fo the scene. This is where the TEMP_WAYPOINT will be created.
  • Position the TARGET_WAYPOINT to the corner of the parking space closest to an approaching vehicle
  • Click Waypoint to create a TEMP_WAYPOINT
  • Create 4 TEMP_WAYPOINT in the order shown below
  • Click Connect to create the MapParkingSpace

NOTE: Apollo 5.0 requires some space between the edge of a lane and the parking space. To verify that there is space, select the MapLane that goes past the MapParkingSpace and click Display Lane. This will show the width of the lane facilitate adjustment of the lane to have a gap between the lane and parking space.

Create Speed Bump top#

  • Select the SpeedBump option under Create Mode
  • Drag in the desired Parent Object
  • A TARGET_WAYPOINT will appear in the center fo the scene. This is where the TEMP_WAYPOINT will be created.
  • Position the TARGET_WAYPOINT to one end of the speed bump
  • Click Waypoint to create a TEMP_WAYPOINT
  • Create 2 TEMP_WAYPOINT in the order shown below
  • The TEMP_WAYPOINT should be wide enough to be outside the lane
  • Click Connect to create the MapSpeedBump
  • To verify that the MapSpeedBump is wide enough, select the MapLane that the MapSpeedBump crosses. Enable Display Lane to visualize the width of the lane. If necesary, select the MapSpeedBump and enable Display Handles to adjust the positions of the individual waypoints.

Export Map Annotations top#

HD Map Annotations may be exported in a variety of formats. Current supported formats are:

  • Apollo 5.0 HD Map
  • Apollo 3.0 HD Map
  • Autoware Vector Map
  • Lanelet2 Map
  • OpenDrive Map

To export a map:

  • Open the HD Map Export tool in Unity: Simulator -> Export HD Map
  • Select the desired format from the dropdown Export Format
  • Enter the desired save location of the exported map
  • Click Export to create the exported map
  • Note the exporter will fail if any lane has no boundary lines annotated - you need to either manually annotate them or use the Create lines button in HD Map Annotation window to create fake boundary lines.

Import Map Annotations top#

The simulator can import a variety of formats of annotated map. NOTE After importing an HD map, you will be required to check each annotation to make sure import is correct. Simulator will provide logs if there are issues that need resolved. If the importer cannot parse a HD map, it will make holder objects that will need manually edited.

Current supported formats are:

  • Lanelet2 Map
  • Apollo 5.0 HD Map
  • OpenDRIVE Map

To import a map:

  • Open the HD Map Export tool in Unity: Simulator -> Import HD Map
  • Select the format of the input map from the dropdown Import Format
  • Select the file or folder that will be imported
  • Click Import to import the map annotations into the simulator
  • Distance Threshold is used to down-sample straight lines/lanes and Delta Threshold is used to down-sample curved lines/lanes. Changing both of them to 0 will keep all points, but for large maps displaying all annotations may lead to Unity crash.

Lanelet2 map importer Notes:

  • Lanes will be automatically imported and grouped as MapLaneSection if possible
  • Intersections with four-way traffic lights / stop signs or two-way stop signs can be imported and grouped under MapIntersection
  • Left-turn lanes are automatically found and their corresponding lanes to yield are also obtained automatically to get NPCs working correctly
  • For each MapIntersection, you need to manually adjust X and Z for the Trigger Bounds as explained in annotate intersection part.
  • Remember to check objects under Intersections are grouped correctly.

Map Formats top#

For more information on the map formats, please see the links below: