Aria: ArMap Class Reference

- Main Page
- Classes
- Files
- Related Pages

- Alphabetical List
- Class List
- Class Hierarchy
- Class Members

# ArMap Class Reference

`#include <ArMap.h>`

Inheritance diagram for ArMap:

List of all members.

## Detailed Description

A map of a space the robot can navigate within, and which can be updated via the Aria config.

ArMap contains data that represents the operating space of the robot, and can be used for space searching, localizing, navigating etc. MobileRobots' ARNL and SONARNL localization and navigation libraries use ArMap objects. ArMap also provides methods to read and write the map from and to a file, along with a mechanism for setting the map file via the global Aria config.

Types of data stored in a map include sensable obstacles (e.g. walls and furniture in a room) that are represented either as a collection of data points or lines. The data points are similar to a raster or bit map and are useful for high resolution sensors like lasers. The lines create a vector map that is useful for low resolution sensors like sonar. For advanced applications, the sensable obstacle data can be categorized according to the type of scan or sensor; see ArMapScanInterface for more information.

In addition to the obstacle data, the Aria map may contain goals, forbidden areas, and other points and regions of interest (a.k.a. "map objects"). Advanced applications can extend the set of predefined map object types. See Map Objects for more information.

If the application needs to be aware of any changes that are made to the Aria map at runtime, then it should install "mapChanged" callbacks on the map. If the map file is re-read while the robot is running, then the callbacks are automatically invoked. If the application makes other changes to the map by calling any of the set methods, then it should call mapChanged() when it is finished.

See MapFileFormat for the exact format of the actual .map file.

## Thread issuses, and changing the map

Different threads will need to access the same map data (for example ARNL, ArForbiddenRangeDevice, networking). However, the ArMap class is not inherently thread-safe. You must call lock() and unlock() methods, before and after any access to the map data (e.g. calls to getMapObjects(), getPoints(), setMapObjects(), setPoints()).

If you are going to use setMapObjects(), setPoints(), setLines(), or setMapInfo(), then you should lock() the map beforehand, call the methods, then call mapChanged() to invoke the callbacks, and then finally unlock() the map when done. Note that mapChanged() will only invoke the callbacks if the data has actually changed.

However, there is an exception: the readFile() and writeFile() methods do automatically lock the map while they read and write.

## Map Objects

In addition to lines and points, maps may contain "map objects", points or regions in space that have special meaning.

Certain types of objects are predefined for all maps. These include Goal, GoalWithHeading, Dock, ForbiddenLine, ForbiddenArea, and RobotHome.

- Goal and GoalWithHeading are basically named ArPoses, the difference being that the "th" (heading) value is only valid for GoalWithHeading.
- Dock is an ArPose that must always have a heading.
- ForbiddenLine is a boundary line, and ForbiddenArea is a rectangular "sector". The extents of these objects are given as a pair of poses, a "from" point and a "to" point.
- RobotHome may be either an ArPose or a rectangular sector.

Rectangular objects may also have an associated angle of rotation, which is stored in the object pose theta value (ArMapObject::getPose().getTh()). The actual global coordinates of the rectangle must be calculated using this angle and its "from-to" values. You can get a list of the 4 ArLineSegment objects that comprise the rectangle's edges using ArMapObject::getFromToSegments(). If you want to do your own calculations, see ArMapObject::ArMapObject().

You can get a pointer to the current list of map objects with getMapObjects(), and directly modify the list. You can also replace the current list of map objects with a new one by calling setMapObjects(); this will destroy the old list of map objects. Call mapChanged() to notify other components that the map has changed.

In addition to the standard map object types, is also possible to define custom types of map objects using the "MapInfo" metadata section of the map file. For example, if you wished to program some special behavior that would only occur upon reaching certain goals, you could define a new "SpecialGoal" type in the map file, and check for it in your program. See MapFileFormat for the syntax for defining new object types in the map file. Custom types will appear in Mapper3 and MobilePlanner in drop-down menus, and instances of the custom types will be displayed in MobileEyes.

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

## Public Member Functions
virtual void | addMapChangedCB (ArFunctor *functor, ArListPos::Pos position=ArListPos::LAST)
virtual void | addPostWriteFileCB (ArFunctor *functor, ArListPos::Pos position=ArListPos::LAST)
virtual void | addPreMapChangedCB (ArFunctor *functor, ArListPos::Pos position=ArListPos::LAST)
virtual void | addPreWriteFileCB (ArFunctor *functor, ArListPos::Pos position=ArListPos::LAST)
virtual bool | addToFileParser (ArFileParser *fileParser)
| ArMap (const ArMap &other)
| Copy constructor.
| ArMap (const char *baseDirectory="./", bool addToGlobalConfig=true, const char *configSection="Files", const char *configParam="Map", const char *configDesc="Map of the environment that the robot uses for navigation", bool ignoreEmptyFileName=true, ArPriority::Priority priority=ArPriority::IMPORTANT, const char *tempDirectory=NULL)
| Constructor.
virtual bool | calculateChecksum (unsigned char *md5DigestBuffer, size_t md5DigestBufferLen)
void | changeConfigMapName (const char *fileName)
| Changes the config map name.
virtual void | clear ()
virtual ArMapInterface * | clone ()
virtual std::string | createRealFileName (const char *fileName)
virtual ArMapObject * | findFirstMapObject (const char *name, const char *type, bool isIncludeWithHeading=false)
virtual ArMapObject * | findMapObject (const char *name, const char *type=NULL, bool isIncludeWithHeading=false)
virtual ArArgumentBuilder * | findMapObjectParams (const char *mapObjectName)
virtual std::list< ArMapObject * > | findMapObjectsOfType (const char *type, bool isIncludeWithHeading=false)
virtual const char * | getBaseDirectory (void) const
virtual const char * | getDisplayString (const char *scanType=ARMAP_DEFAULT_SCAN_TYPE)
virtual const char * | getFileName (void) const
virtual bool | getIgnoreCase (void)
virtual bool | getIgnoreEmptyFileName (void)
virtual ArMapInfoInterface * | getInactiveInfo ()
virtual ArMapObjectsInterface * | getInactiveObjects ()
virtual std::list< ArArgumentBuilder * > * | getInfo (int infoType)
virtual std::list< ArArgumentBuilder * > * | getInfo (const char *infoName)
virtual int | getInfoCount () const
virtual const char * | getInfoName (int infoType)
virtual std::list< std::string > | getInfoNames () const
virtual ArPose | getLineMaxPose (const char *scanType=ARMAP_DEFAULT_SCAN_TYPE)
virtual ArPose | getLineMinPose (const char *scanType=ARMAP_DEFAULT_SCAN_TYPE)
virtual std::vector< ArLineSegment > * | getLines (const char *scanType=ARMAP_DEFAULT_SCAN_TYPE)
virtual ArLog::LogLevel | getMapChangedLogLevel (void)
virtual bool | getMapId (ArMapId *mapIdOut, bool isInternalCall=false)
virtual std::list< ArArgumentBuilder * > * | getMapInfo (void)
virtual std::list< ArMapObject * > * | getMapObjects (void)
virtual ArPose | getMaxPose (const char *scanType=ARMAP_DEFAULT_SCAN_TYPE)
virtual ArPose | getMinPose (const char *scanType=ARMAP_DEFAULT_SCAN_TYPE)
virtual int | getNumLines (const char *scanType=ARMAP_DEFAULT_SCAN_TYPE)
virtual int | getNumPoints (const char *scanType=ARMAP_DEFAULT_SCAN_TYPE)
virtual double | getOriginAltitude ()
virtual ArPose | getOriginLatLong ()
virtual std::vector< ArPose > * | getPoints (const char *scanType=ARMAP_DEFAULT_SCAN_TYPE)
virtual struct stat | getReadFileStat () const
virtual std::list< ArArgumentBuilder * > * | getRemainder ()
virtual int | getResolution (const char *scanType=ARMAP_DEFAULT_SCAN_TYPE)
virtual std::list< std::string > | getScanTypes () const
virtual const char * | getTempDirectory (void) const
virtual bool | hasOriginLatLongAlt ()
virtual bool | isLoadingDataStarted ()
virtual bool | isLoadingLinesAndDataStarted ()
virtual bool | isSortedLines (const char *scanType=ARMAP_DEFAULT_SCAN_TYPE) const
virtual bool | isSortedPoints (const char *scanType=ARMAP_DEFAULT_SCAN_TYPE) const
virtual void | loadDataPoint (double x, double y)
virtual void | loadLineSegment (double x1, double y1, double x2, double y2)
virtual int | lock ()
virtual void | mapChanged (void)
ArMap & | operator= (const ArMap &other)
| Assignment operator.
virtual bool | parseLine (char *line)
virtual void | parsingComplete (void)
virtual bool | readDataPoint (char *line)
bool | readFile (const char *fileName)
bool | readFile (const char *fileName, char *errorBuffer, size_t errorBufferLen)
virtual bool | readFile (const char *fileName, char *errorBuffer, size_t errorBufferLen, unsigned char *md5DigestBuffer, size_t md5DigestBufferLen)
bool | readFileAndChangeConfig (const char *fileName)
| Reads a map and changes the config map name to that file.
virtual bool | readLineSegment (char *line)
virtual bool | refresh ()
virtual bool | remFromFileParser (ArFileParser *fileParser)
virtual void | remMapChangedCB (ArFunctor *functor)
virtual void | remPostWriteFileCB (ArFunctor *functor)
virtual void | remPreMapChangedCB (ArFunctor *functor)
virtual void | remPreWriteFileCB (ArFunctor *functor)
virtual bool | set (ArMapInterface *other)
virtual void | setBaseDirectory (const char *baseDirectory)
virtual void | setIgnoreCase (bool ignoreCase=false)
virtual void | setIgnoreEmptyFileName (bool ignore)
virtual bool | setInfo (int infoType, const std::list< ArArgumentBuilder * > *infoList, ArMapChangeDetails *changeDetails=NULL)
virtual bool | setInfo (const char *infoName, const std::list< ArArgumentBuilder * > *infoList, ArMapChangeDetails *changeDetails=NULL)
virtual void | setLines (const std::vector< ArLineSegment > *lines, const char *scanType=ARMAP_DEFAULT_SCAN_TYPE, bool isSortedLines=false, ArMapChangeDetails *changeDetails=NULL)
virtual void | setMapChangedLogLevel (ArLog::LogLevel level)
virtual bool | setMapInfo (const std::list< ArArgumentBuilder * > *mapInfo, ArMapChangeDetails *changeDetails=NULL)
virtual bool | setMapObjectParams (const char *mapObjectName, ArArgumentBuilder *params, ArMapChangeDetails *changeDetails=NULL)
virtual void | setMapObjects (const std::list< ArMapObject * > *mapObjects, bool isSortedObjects=false, ArMapChangeDetails *changeDetails=NULL)
virtual void | setOriginLatLongAlt (bool hasOriginLatLong, const ArPose &originLatLong, double altitude, ArMapChangeDetails *changeDetails=NULL)
virtual void | setPoints (const std::vector< ArPose > *points, const char *scanType=ARMAP_DEFAULT_SCAN_TYPE, bool isSortedPoints=false, ArMapChangeDetails *changeDetails=NULL)
virtual void | setQuiet (bool isQuiet)
virtual void | setResolution (int resolution, const char *scanType=ARMAP_DEFAULT_SCAN_TYPE, ArMapChangeDetails *changeDetails=NULL)
virtual bool | setScanTypes (const std::list< std::string > &scanTypeList)
virtual void | setSourceFileName (const char *sourceName, const char *fileName, bool isInternalCall=false)
virtual void | setTempDirectory (const char *tempDirectory)
virtual int | tryLock ()
virtual int | unlock ()
virtual bool | writeFile (const char *fileName)
virtual bool | writeFile (const char *fileName, bool internalCall, unsigned char *md5DigestBuffer=NULL, size_t md5DigestBufferLen=0, time_t fileTimestamp=-1)
virtual void | writeInfoToFunctor (ArFunctor1< const char * > *functor, const char *endOfLineChars)
virtual void | writeLinesToFunctor (ArFunctor2< int, std::vector< ArLineSegment > * > *functor, const char *scanType=ARMAP_DEFAULT_SCAN_TYPE, ArFunctor1< const char * > *keywordFunctor=NULL)
virtual void | writeObjectListToFunctor (ArFunctor1< const char * > *functor, const char *endOfLineChars)
virtual void | writeObjectsToFunctor (ArFunctor1< const char * > *functor, const char *endOfLineChars, bool isOverrideAsSingleScan=false, const char *maxCategory=NULL)
virtual void | writePointsToFunctor (ArFunctor2< int, std::vector< ArPose > * > *functor, const char *scanType=ARMAP_DEFAULT_SCAN_TYPE, ArFunctor1< const char * > *keywordFunctor=NULL)
virtual void | writeScanToFunctor (ArFunctor1< const char * > *functor, const char *endOfLineChars, const char *scanType=ARMAP_DEFAULT_SCAN_TYPE)
virtual void | writeSupplementToFunctor (ArFunctor1< const char * > *functor, const char *endOfLineChars)
virtual void | writeToFunctor (ArFunctor1< const char * > *functor, const char *endOfLineChars)
virtual | ~ArMap (void)
| Destructor.
## Protected Member Functions
bool | processFile (char *errorBuffer, size_t errorBufferLen)
| Processes changes to the Aria configuration; loads a new map file if necessary.
## Protected Attributes
std::string | myBaseDirectory
| File path in which to find the map file name.
char | myConfigMapName [MAX_MAP_NAME_LENGTH]
| The name of the map file specified in the Aria config parameter.
std::string | myConfigParam
| Name of the Aria config parameter that specifies the map file name.
bool | myConfigProcessedBefore
| Whether the Aria config has already been processed at least once.
ArMapSimple *const | myCurrentMap
| The current map used by the robot.
std::string | myFileName
| Name of the map file.
bool | myIgnoreCase
| Whether to ignore case when comparing map file names.
bool | myIgnoreEmptyFileName
| Whether to ignore (not process) an empty Aria config parameter.
bool | myIsQuiet
| Whether to run in "quiet mode", i.e. logging less information.
ArMapSimple * | myLoadingMap
| The map that is being loaded, i.e. read from a file; will be copied to the current map if successful.
ArMutex | myMutex
ArRetFunctor2C< bool, ArMap, char *, size_t > | myProcessFileCB
| Callback that processes changes to the Aria config.
stat | myReadFileStat
| File statistics for the map file.

## Constructor & Destructor Documentation

ArMap::ArMap | ( | const char * | baseDirectory = `"./"`,
|  | bool | addToGlobalConfig = `true`,
|  | const char * | configSection = `"Files"`,
|  | const char * | configParam = `"Map"`,
|  | const char * | configDesc = `"Map of the environment that the robot uses for navigation"`,
|  | bool | ignoreEmptyFileName = `true`,
|  | ArPriority::Priority | priority = `ArPriority::IMPORTANT`,
|  | const char * | tempDirectory = `NULL` |
| ) |  |  |

Constructor.

Parameters:

  | baseDirectory | the name of the directory in which to search for map files that are not fully qualified
  | addToGlobalConfig | a bool set to true if the map file name parameter should be added to the global config, Aria::getConfig(); false, otherwise
  | configSection | the char * name of the config section to which to add the map file name parameter name; applicable only if addToGlobalConfig is true
  | configParam | the char * name of the parameter to be added to the specified configSection; applicable only if addToGlobalConfig is true
  | configDesc | the char * description of the configParam; applicable only if addToGlobalConfig is true
  | ignoreEmptyFileName | a bool set to true if an empty file name is a valid config parameter value; set to false if a failure should be reported when the file name is empty; applicable only if addToGlobalConfig is true
  | priority | the ArPriority::Priority of the config parameter; applicable only if addToGlobalConfig is true
  | tempDirectory | the name of the directory in which to write temporary files when saving a map; if NULL, then the map file is written directly. Note that using a temp file reduces the risk that the map will be corrupted if the application crashes.

## Member Function Documentation

virtual struct stat ArMap::getReadFileStat | ( |  | ) | const`[virtual]`

Java and Python Wrappers: Not available in Java or Python wrapper libraries.

Implements ArMapInterface.

virtual void ArMap::loadDataPoint | ( | double | x,
|  | double | y |
| ) |  |  | `[virtual]`

Public for ArQClientMapProducer

Implements ArMapScanInterface.

virtual bool ArMap::readFile | ( | const char * | fileName,
|  | char * | errorBuffer,
|  | size_t | errorBufferLen,
|  | unsigned char * | md5DigestBuffer,
|  | size_t | md5DigestBufferLen |
| ) |  |  | `[virtual]`

Java and Python Wrappers: Not available in Java or Python wrapper libraries. (can't write to arguments yet)

Implements ArMapInterface.

virtual bool ArMap::writeFile | ( | const char * | fileName,
|  | bool | internalCall,
|  | unsigned char * | md5DigestBuffer = `NULL`,
|  | size_t | md5DigestBufferLen = `0`,
|  | time_t | fileTimestamp = `-1` |
| ) |  |  | `[virtual]`

Java and Python Wrappers: Not available in Java or Python wrapper libraries. (can't write to arguments yet)

Implements ArMapInterface.

The documentation for this class was generated from the following file:

- ArMap.h