Map File Format

ARIA's map file format is used to store data that defines a map of a space in which the robot can operate. A map file can be loaded, accessed, and saved using an ArMap object.

The robot map file is in ASCII text, and may be viewed or edited in any text editor. Map file names conventionally end in the suffix ".map".

A map file contains several types of information, including:

• Header information which includes the boundaries of the map, various data counts, and the resolution (in mm) at which the map was made.
• Optional metadata that can be used to define custom object types. (This is explained in greater detail below.)
• Map objects, such as goals and forbidden lines.
• Map data: lines and points (in mm).

A formal description of the map syntax follows in augmented Backus-Naur Format (ABNF). All blank lines in the map file should be ignored. As an exception to ABNF, literal strings given below are case-sensitive.

A map is an introductory line (e.g. "2D-Map") followed by the metadata section, followed by some number of data sections:

ARMAP                = (MapIntro NEWLINE) (MetadataSection) (*DataSection)
MapIntro             = "2D-Map" / "2D-Map-Ex" / "2D-Map-Ex2"

Most of the features described below apply to all of the MapIntro values. Exceptions are noted in the feature descriptions.

The MetadataSection section provides information about the map data, adds objects (Cairns) and also provides storage of application-specific/custom information.

MetadataSection      = *MetadataLine
MetadataLine         = MDKey ":" *(WS MDVal) NEWLINE
MDKey                = StringID
MDVal                = Integer / Float / StringID / KeyValPair 

Most metadata lines fall into one of two categories: a simple list of numeric tokens, or a StringID followed by a list of either numeric tokens or a set of KeyValuePair tokens.

The DataSections contain data that was recorded with sensors (e.g. a Laser Rangefinder for the "DATA" section) and which represent more or less permanent, solid objects detectable by a robot's range sensors. (This data can be used for localization and path planning, for instance.) The DATA section is a collection of points detected by a high-resolution sensor like the LRF. LINES abstracts the world into a set of flat surfaces.

DataSection          = (LineIntro NEWLINE *LineLine) / (PointIntro NEWLINE *PointLine)
LineLine             = XPos WS YPos WS XPos WS YPos NEWLINE
PointLine            = XPos WS YPos NEWLINE
; If MapIntro is "2D-Map":
  LineIntro            = "LINES" 
  PointIntro           = "DATA"
; If MapIntro is "2D-Map-Ex" or "2D-Map-Ex2":
  LineIntro            = "LINES" / SensorName "_LINES"
  PointIntro           = "DATA" / SensorName "_DATA"
  SensorName           = StringID

MetadataSection Details

"Cairn" is a common instance of MDKey. A "Cairn" metadata entry looks like this:

MetaDataLine         =/ Cairn  NEWLINE
Cairn                = "Cairn:" WS CairnType WS XPos WS YPos WS Theta WS InternalName WS IconName WS Label [WS TypeSpecificData]
CairnType            = StringID
XPos                 = Integer
YPos                 = Integer
Theta                = Integer
InternalName         = QuotedString
IconName             = QuotedString
Label                = QuotedString
TypeSpecificData     = *(WS MDKey)

"MapInfo" is another common instance of MDKey. A "MapInfo" entry can describe custom map object types for your application beyond the usual Cairn types (see above).

MetaDataLine         =/ MapInfo NEWLINE
MapInfo              = "MapInfo:" WS MapInfoClass WS *(KeyValuePair)
MapInfoClass         = StringID

Data types:

KeyValPair           = (StringID "=" MDVal) /  QUOTE ALNUM "=" Text QUOTE
Integer              = ["-"] *1(DIGIT)
Float                = ["-"] *1(DIGIT | ".")
StringID             = *1 ALNUM     ; One or more alphanumeric characters (no whitespace)
QuotedText           = QUOTE Text QUOTE
Text                 = *(ALNUM / WS / PUNCTUATION)
DIGIT                = ("0"-"9")
ALPHA                = ("a"-"z" / "A"-"Z")
ALNUM                = ALPHA / DIGIT
WS                   = *(" ")       ; Any number of ASCII space characters (incl. 0)
QUOTE                = d34         ; ASCII double quote mark (")
NEWLINE              = d10         ; ASCII newline (

)
PUNCTUATION          = d32-d47 / d58-d64 / d92-d96 / d123-d126
ANY                  = d32-d126   ; Any ASCII text

In addition to Cairn and MapInfo, other Common IDs for MDKey are:

Sources

If multiple sensors were used to compile the points and lines in the DataSection, they are listed here. The first sensor is the default sensor; the data for it are not prefixed (i.e. plain MinPos, MaxPos, DATA, and LINES). The data for any additional sensors are prefixed by the sensor name (i.e. SensorNameMinPos, SensorNameMaxPos, SensorName_DATA, SensorName_LINES). (2D-Map-Ex and 2D-Map-Ex2 feature.)

MinPos or SensorNameMinPos

"Minimum" value in DATA (defines opposite corner to MaxPos of a bounding box)

MaxPos or SensorNameMaxPos

"Maximum" value in DATA (defines opposite corner to MinPos of a bounding box)

NumPoints or SensorNumPoints

Number of entries in the DATA section. (Note, it is recommended that you do not rely on this value if possible; instead simply count the number of lines in the DATA section)

LineMinPos or SensorNameLineMinPos

"Minimum" value in LINES (defines opposite corner to LineMaxPos of a bounding box)

LineMaxPos or SensorNameLineMaxPos

"Maximum" value in LINES (defines opposite corner to LineMinPos of a bounding box)

NumLines or SensorNameNumLines

Number of entries in the LINES section. (Note, it is recommended that you do not rely on this value if possible; instead simply count the number of lines in the LINES section)

Resolution or SensorNameResolution

Grid resolution of the DATA points and the LINE endpoint positions.

PointsAreSorted or SensorNamePointsAreSorted

true if the points DATA are sorted, false if not.

LinesAreSorted or SensorNamePointsAreSorted

true if the LINES data are sorted, false if not.

Display or SensorNameDisplay

Text to display in user interface etc. when referring to this sensor data source.

OriginLatLonAlt

Latitude, longitude and altitude of the map's center (0, 0) point in the WGS84 datum. (Only present in "outdoor" maps made for use with MOGS.)

Cairn

Defines a special object in the map with semantic meaning. See below.

MapInfo

Describes custom cairn types. See below.

CustomInfo

Placeholder for custom application data which will be maintained if the map is edited by Mapper3 or MobilePlanner. (2D-Map-Ex2 feature.)

New values may be added in the future, or used only by some applications.

Common CairnType values are:

Goal

A named goal. Theta should be ignored. The name of the goal is provided in Label.

GoalWithHeading

A named goal. Theta indicates a final heading. The name of the goal is provided in Label.

RobotHome

A possible starting position of a robot.

Dock

A position and heading at which a docking maneuver may be initiated

ForbiddenLine

Specifies a line that any automatic navigation procedure should avoid crossing. This Cairn type has the following TypeSpecificData, which defines the endpoints of the line:

TypeSpecificData     =/ ForbiddenLineData
ForbiddenLineData    =  XPos WS YPos WS XPos WS YPos

The normal Cairn pose is not used for ForbiddenLine.

ForbiddenArea

Specifies a rectangular area that any automatic navigation procedure should avoid entering. This Cairn type has the following TypeSpecificData, which defines the upper-left and lower-right opposing corners of the rectangle:

TypeSpecificData     =/ ForbiddenAreaData
ForbiddenAreaData    =  XPos WS YPos WS XPos WS YPos

The normal Cairn pose for ForbiddenArea defines an offset of the geometric center of the area, plus a rotation of the area. (Typically, XPos and YPos will always be 0 for ForbiddenArea, but Theta may be used to provide the rotation of the rectangular area).

The InternalName and IconName tokens in Cairn data are not currently used. Typically, InternalName is simply an empty quoted string ("") and IconName is the placeholder value "ICON". You should preserve them when reading and writing map files though, as they may be used in the future.

Note, It is be better to calculate maximum, minimum, and number of points or lines based on the data in the map, if possible, rather than relying on the metadata header.

So what the heck is a "cairn"? The word is from the Scottish Gaelic, Old Irish and Welsh "carn" and Middle English "carne". A cairn is a pile of stones, placed in the landscape as a memorial, navigation aid, or other marker. So we use it to indicate a semantically meaningful object placed at some point by the human mapmaker (rather than something detectable by the robot).

Currently used MapInfoClass keywords include:

GoalType

define a custom goal subtype

DockType

define a custom dock subtype

LocationType

define a custom other generic poses on the map

BoundaryType

define a custom line on the map

SectorType

defines a custom rectangular area (which may be rotated)

The following ParamNames are valid for all MapInfoClass keywords:

Name=Text

Name of the type that is being defined.

Label=Text

Label that is displayed for the type in a GUI, etc.

Desc=Text

Longer description of the type that is displayed in a GUI, etc.

For more information about the use of MapInfo metadata, see the discussion above.

Defining Custom Map Objects

In addition to the standard map object types, is also possible to define additional types of objects in a map file using the "MapInfo" metadata section. For example, if you wished to program some special behavior that would only occur upon reaching certain goals, you could define a new goal type as follows:

    MapInfo: GoalType Name=SpecialGoal "Label=Special" "Desc=Doing special stuff" Heading=Required Shape=VBars "Color0=0xff0000"
 

The new goal type will appear be available in Mapper3 and MobilePlanner in a drop-down menu. Instances in the map will also be displayed by MobileEyes.

Please read the following information carefully if you plan to use this feature.

Each MapInfo line is of the format:

       MapInfo: Keyword ([ParamName=ParamValue] )*  ; A keyword followed by a space-separated list of Key=Value or "Key=Value" tokens.
 

The following values for Keyword are currently supported:

• GoalType : defines a goal subtype
• DockType : defines a dock subtype
• LocationType : defines another kind of point in the map
• BoundaryType : defines a line object in the map
• SectorType : defines a rectangular area of some kind in the map (which may be rotated)
• ArgDesc: defines a parameter for the preceding type (2D-Map-Ex2 feature)

The available parameters depend on the Keyword. Unless otherwise specified, parameters are optional.

If a parameter value contains a space, then both the parameter name and value must be enclosed within quotes. For example:

      "Label=Normal Goal"
 

Neither the name nor the value can contain the special characters #, %, or ".

The following ParamNames are valid for all keywords except ArgDesc:

• Name=String : Text name of the type that is being defined. (Required.)
• Label=String : Label that is displayed for the type in popup menus, etc.
• Desc=String : Description of the type that is displayed in tool tips, etc.
• Vis=[AlwaysOn|DefaultOn|DefaultOff|AlwaysOff] : Specifies the visibility of the associated item type. The default is DefaultOn. (This parameter is currently primarily supported for IsData=1 items only. See BoundaryType. In particular, if DefaultOff is specified for a non-data-item, there currently is no way in Mapper3, MobilePlanner or MobileEyes to subsequently show it.)

For GoalType, DockType, and LocationType, the following ParamNames are also supported:

• Shape=[Plain|Cross|HBars|Triangle|T|U|VBars] : Shape of the icon used to draw the pose. (The default is Plain.)
  • Plain: The default shape, a filled square
  • Cross: A cross shape
  • HBars: A square shape containing horizontal bars or stripes
  • Label: A location that simply marks a text label expected to be used with LocationType and a fixed size font (FtFix, see below)
  • Triangle: A Triangle
  • T: A "T" shape
  • U: A "U" shape
  • VBars: A square shape containing vertical bars or stripes
• Size=Integer : Width/height of the displayed icon in mm.
• Color0|1|2=ColorVal : Colors with which to draw the icon. (In general, Color0 is the primary icon color, Color1 is the heading color, and Color2 is the background/outline color.) * ColorVal is a hexadecimal number starting with 0x, and followed by two digits for the red component, two digits for green, and two digits for blue. For example, 0xff00ff.
• FtFix=Integer : A boolean. Set to 0 if the label font should be scaled when the map is zoomed (the default) set to 1 if the label should remain a fixed size. Note that the label font will only be scaled if the platform supports it. Also note that if this is set to 1, then the FtSize must also be specified.
• FtSize=Integer : Point size of the displayed font. This will vary greatly depending on the value of FtFix. If the font is scaled, then the point size is expressed in mm and must be a multiple of 100. If the font is fixed, then the point size is in pixels. (If the font should be scaled, but the platform does not support it, then a best guess is made as to the desired size.)

In addition, the following ParamName is supported only for GoalTypes:

• Heading=[Required|Optional|Never] : Whether a heading is required to be given with this goal, is optional, or is irrelevant.

For BoundaryType, the following ParamNames are also supported:

• NameRequired=0|1 : Whether the item must be named (1=true, 0=false)
• Color0|1|2=ColorVal: Color with which to draw the line.
• IsData=0|1 : Set to 1 to indicate that the item is inherently part of the map data. The default is 0 to indicate user-created items.
• FtFix=Integer : A boolean. Set to 0 if the label font should be scaled when the map is zoomed (the default) set to 1 if the label should remain a fixed size. Note that the label font will only be scaled if the platform supports it. Also note that if this is set to 1, then the FtSize must also be specified.
• FtSize=Integer : Point size of the displayed font. This will vary greatly depending on the value of FtFix. If the font is scaled, then the point size is expressed in mm and must be a multiple of 100. If the font is fixed, then the point size is in pixels. (If the font should be scaled, but the platform does not support it, then a best guess is made as to the desired size.)

For SectorType, the following ParamNames are also supported:

• NameRequired=0|1 : Whether the item must be named
• Shape=Plain|Arrow : Shape of the icon used to draw the rectangle. (The default is Plain.)
• Color0|1=ColorVal: Colors with which to draw the rectangle. (In general, Color0 is the primary rectangle color, Color1 is the shape/icon color.)

Important Note: if a map defines special GoalType or DockType items, then it must define all possible Cairn types, including the default "Goal", "GoalWithHeading", and "Dock" types if you want those types to remain available.

The MapInfo ArgDesc lines may be used to define one or more configurable parameters for a custom map object type. (2D-Map-Ex2 feature.) The ArgDesc must appear after its parent type definition and can contain the following parameters:

• Name=String : The text name of the parameter being defined. This must be the first item in the line (after ArgDesc) and must be unique for the given parent. (Required)
• Parent=String : The text name of the parent map object type (e.g. SpecialGoal, RobotHome, ...). This must be the second item in the line, immediately following the Name. (Required)
• Priority=Important|Normal|Detailed : The priority of the parameter (Required)
• Type=int|double|string|bool : The type of the parameter's value (Required)
• Value=String : An optional initial value for the parameter (as appropriate for the type)
• Min=Number : An optional minimum value for the parameter; valid only if Type=int or Type=double
• Max=Number : An optional maximum value for the parameter; valid only if Type=int or Type=double
• Display=String : An optional display hint that may be used by the client to improve display of the parameter. See ArConfigArg::setDisplayHint() for a list of the currently supported display hints.

If a cairn instance with parameters is defined in the map file, then the parameter values are stored in a special CairnInfo Metadatasection line. (2D-Map-Ex2 feature.)

---