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 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)
void	forceMapLoadOnConfigProcessFile (void)
	Forces the map to reload if the config is changed/reloaded.
virtual const char *	getBaseDirectory (void) const
virtual ArMapObjectsInterface *	getChildObjects ()
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 (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)
ArMap &	operator= (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)
	Destructor.
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 ()
	Constructor.
virtual	~ArMapInterface (void)
	Destructor.
Public Member Functions inherited from ArHasFileName
	ArHasFileName ()
	Constructor.
	ArHasFileName (ArHasFileName const &)
	Copy constructor.
ArHasFileName &	operator= (ArHasFileName const &)
	Assignment operator.
virtual	~ArHasFileName ()
	Destructor.
Public Member Functions inherited from ArMapInfoInterface
	ArMapInfoInterface ()
	Constructor.
virtual	~ArMapInfoInterface ()
	Destructor.
Public Member Functions inherited from ArMapObjectsInterface
	ArMapObjectsInterface ()
	Constructor.
virtual	~ArMapObjectsInterface ()
	Destructor.
Public Member Functions inherited from ArMapScanInterface
	ArMapScanInterface ()
	Default constructor.
virtual	~ArMapScanInterface ()
	Destructor.
Public Member Functions inherited from ArMapSupplementInterface
	ArMapSupplementInterface ()
	Default constructor.
virtual	~ArMapSupplementInterface ()
	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	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.
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.
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 {   MAP_INFO, FIRST_INFO = MAP_INFO, META_INFO, TASK_INFO,   ROUTE_INFO, SCHED_TASK_INFO, SCHED_INFO, CAIRN_INFO,   CUSTOM_INFO, LAST_INFO = CUSTOM_INFO }
	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
	)

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.
configProcessFilePriority	priority at which ArMap's configuration parameters should be processed by ArConfig.

Member Function Documentation

getReadFileStat()

struct stat ArMap::getReadFileStat ( ) const

virtual

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),

myMapChangedHelper(NULL),

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

myIsQuiet(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  )

virtual

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  )

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

• ArMap.h
• ArMap.cpp