Aria  2.8.0
ArMap Class Reference

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

#include <ArMap.h>

Inherits ArMapInterface.

Public Member Functions

virtual void addMapChangedCB (ArFunctor *functor, int position=50)
virtual void addPostWriteFileCB (ArFunctor *functor, ArListPos::Pos position=ArListPos::LAST)
virtual void addPreMapChangedCB (ArFunctor *functor, int position=50)
virtual void addPreWriteFileCB (ArFunctor *functor, ArListPos::Pos position=ArListPos::LAST)
virtual bool addToFileParser (ArFileParser *fileParser)
 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, int configProcessFilePriority=100)
 Constructor. More...
 ArMap (const ArMap &other)
 Copy constructor.
virtual bool calculateChecksum (unsigned char *md5DigestBuffer, size_t md5DigestBufferLen)
void changeConfigMapName (const char *fileName)
 Changes the config map name.
virtual void clear ()
virtual ArMapInterfaceclone ()
virtual std::string createRealFileName (const char *fileName)
virtual ArMapObjectfindFirstMapObject (const char *name, const char *type, bool isIncludeWithHeading=false)
virtual ArMapObjectfindMapObject (const char *name, const char *type=NULL, bool isIncludeWithHeading=false)
virtual ArArgumentBuilderfindMapObjectParams (const char *mapObjectName)
virtual std::list< ArMapObject * > findMapObjectsOfType (const char *type, bool isIncludeWithHeading=false)
void forceMapLoadOnConfigProcessFile (void)
 Forces the map to reload if the config is changed/reloaded.
virtual const char * getBaseDirectory (void) const
virtual ArMapObjectsInterfacegetChildObjects ()
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 ArMapInfoInterfacegetInactiveInfo ()
virtual ArMapObjectsInterfacegetInactiveObjects ()
virtual std::list< ArArgumentBuilder * > * getInfo (const char *infoName)
virtual std::list< ArArgumentBuilder * > * getInfo (int infoType)
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)
 Public for ArQClientMapProducer.
virtual void loadLineSegment (double x1, double y1, double x2, double y2)
virtual int lock ()
virtual void mapChanged (void)
ArMapoperator= (const ArMap &other)
 Assignment operator. More...
virtual bool parseLine (char *line)
virtual void parsingComplete (void)
virtual bool readDataPoint (char *line)
virtual bool readFile (const char *fileName, char *errorBuffer, size_t errorBufferLen, unsigned char *md5DigestBuffer, size_t md5DigestBufferLen)
bool readFile (const char *fileName, char *errorBuffer, size_t errorBufferLen)
bool readFile (const char *fileName)
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 (const char *infoName, const std::list< ArArgumentBuilder *> *infoList, ArMapChangeDetails *changeDetails=NULL)
virtual bool setInfo (int infoType, 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, bool internalCall, unsigned char *md5DigestBuffer=NULL, size_t md5DigestBufferLen=0, time_t fileTimestamp=-1)
virtual bool writeFile (const char *fileName)
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)
- Public Member Functions inherited from ArMapInterface
virtual void addMapChangedCB (ArFunctor *functor, ArListPos::Pos position)
 Adds a callback that is invoked when the map has been changed. More...
virtual void addPreMapChangedCB (ArFunctor *functor, ArListPos::Pos position)
 Adds a callback called before the map changed callbacks are called. More...
 ArMapInterface ()
virtual ~ArMapInterface (void)
- Public Member Functions inherited from ArHasFileName
 ArHasFileName ()
 ArHasFileName (ArHasFileName const &)
 Copy constructor.
ArHasFileNameoperator= (ArHasFileName const &)
 Assignment operator.
virtual ~ArHasFileName ()
- Public Member Functions inherited from ArMapInfoInterface
 ArMapInfoInterface ()
virtual ~ArMapInfoInterface ()
- Public Member Functions inherited from ArMapObjectsInterface
 ArMapObjectsInterface ()
virtual ~ArMapObjectsInterface ()
- Public Member Functions inherited from ArMapScanInterface
 ArMapScanInterface ()
 Default constructor.
virtual ~ArMapScanInterface ()
- Public Member Functions inherited from ArMapSupplementInterface
 ArMapSupplementInterface ()
 Default constructor.
virtual ~ArMapSupplementInterface ()

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 myForceMapLoad
 Whether we want to force loading the map for some reasing.
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.
 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.
struct stat myReadFileStat
 File statistics for the map file.

Additional Inherited Members

- Public Types inherited from ArMapInterface
enum  { MAX_MAP_NAME_LENGTH = 512 }
- Public Types inherited from ArMapInfoInterface
enum  { INFO_COUNT = LAST_INFO + 1 }
enum  InfoType {
 List of the standard Info categories defined for Aria maps. More...
- Static Public Member Functions inherited from ArMapInterface
static std::string createRealFileName (const char *baseDirectory, const char *fileName, bool isIgnoreCase)
 Helper method creates a full file path name from the given components. More...
- Static Public Member Functions inherited from ArMapScanInterface
static bool isDefaultScanType (const char *scanType)
 Determines whether the given scan type is the default (i.e. no prefix on the map tags)
static bool isSummaryScanType (const char *scanType)
 Determines whether the given scan type represents the summary of all other scan types.
- Static Public Attributes inherited from ArMapInterface
static const char * MAP_CATEGORY_2D = "2D-Map"
static const char * MAP_CATEGORY_2D_COMPOSITE = "2D-Map-Ex3"
 Superset of extended; includes group objects and parent maps.
static const char * MAP_CATEGORY_2D_EXTENDED = "2D-Map-Ex2"
 Superset of multi-sources; includes advanced Info types, CairnInfo and CustomInfo.
static const char * MAP_CATEGORY_2D_MULTI_SOURCES = "2D-Map-Ex"
- Static Public Attributes inherited from ArMapInfoInterface
static const char * CAIRN_INFO_NAME = "CairnInfo:"
static const char * CUSTOM_INFO_NAME = "CustomInfo:"
static const char * MAP_INFO_NAME = "MapInfo:"
static const char * META_INFO_NAME = "MetaInfo:"
static const char * ROUTE_INFO_NAME = "RouteInfo:"
static const char * SCHED_INFO_NAME = "SchedInfo:"
static const char * SCHED_TASK_INFO_NAME = "SchedTaskInfo:"
static const char * TASK_INFO_NAME = "TaskInfo:"

Detailed Description

A map of a two-dimensional 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 Map File Format 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 Map File Format 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.

Constructor & Destructor Documentation

◆ ArMap()

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,
int  configProcessFilePriority = 100 


baseDirectorythe name of the directory in which to search for map files that are not fully qualified
addToGlobalConfiga bool set to true if the map file name parameter should be added to the global config, Aria::getConfig(); false, otherwise
configSectionthe char * name of the config section to which to add the map file name parameter name; applicable only if addToGlobalConfig is true
configParamthe char * name of the parameter to be added to the specified configSection; applicable only if addToGlobalConfig is true
configDescthe char * description of the configParam; applicable only if addToGlobalConfig is true
ignoreEmptyFileNamea 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
prioritythe ArPriority::Priority of the config parameter; applicable only if addToGlobalConfig is true
tempDirectorythe 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.
configProcessFilePrioritypriority at which ArMap's configuration parameters should be processed by ArConfig.

Member Function Documentation

◆ getReadFileStat()

struct stat ArMap::getReadFileStat ( ) const

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

Implements ArMapInterface.

◆ operator=()

ArMap & ArMap::operator= ( const ArMap other)

Assignment operator.

myConfigParam myIgnoreEmptyFileName(false), myIgnoreCase(false),


myConfigProcessedBefore(false), // TODO This is not always init in ArMap myConfigMapName(), myForceMapLoad(false),


myCurrentMapChangedCB(this, &ArMap::handleCurrentMapChanged), myProcessFileCB(this, &ArMap::processFile)

◆ readFile()

bool ArMap::readFile ( const char *  fileName,
char *  errorBuffer,
size_t  errorBufferLen,
unsigned char *  md5DigestBuffer,
size_t  md5DigestBufferLen 

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

Implements ArMapInterface.

◆ writeFile()

bool ArMap::writeFile ( const char *  fileName,
bool  internalCall,
unsigned char *  md5DigestBuffer = NULL,
size_t  md5DigestBufferLen = 0,
time_t  fileTimestamp = -1 

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 files: