ArMapInterface Class Reference

#include <ArMapInterface.h>

Inheritance diagram for ArMapInterface:

List of all members.

---

Detailed Description

ArMapInterface defines the methods that are available on all Aria maps. These maps represent the operating space of a robot, and can be used for space searching, localizing, navigating etc. The types of data stored in a map include sensable obstacles (e.g. walls and furniture in a room) represented either as a collection of data points (similar to a raster or bit map, useful for high resolution sensors like a laser), or lines (a vector map, useful for low resolution sensors like the sonar), goals, and other points or regions of interest ("map objects").

The methods in ArMapInterface can be broadly categorized as follows:

• Scan Methods: These provide access the sensable obstacles that are represented as a collection of data points or lines. These are typically generated during the scanning process (i.e. the creation of the .2d file). If more than one sensor is used, then the data is organized on a per-sensor basis. The scan methods are grouped into the ArMapScanInterface.
• Object Methods: These provide access to the "high-level" objects in the environment. Such objects include goals, docks, forbidden areas, and other user-defined points of interest. They may also include special data objects that are actually part of the operating environment and are generally added automatically and are not editable by the user. The object methods are grouped into the ArMapObjectsInterface.
• Info Methods: A wide variety of supporting information is included in various "info" categories. This includes definitions for the types of map objects that can be stored in the map. It also includes various optional features such as macros and schedules. The info methods are grouped into the ArMapInfoInterface.
• Extra Data Methods: These are essentially the "leftovers" -- i.e. methods that are related directly to map data but which do not fit into any of the above categories. They are defined in the ArMapSupplementInterface.
• Callback Methods: Users of the Aria map may install callbacks onto the map in order to be notified when the map contents has changed. These methods are defined below.
• File and I/O Methods: Methods to read and write map files are also included below. In addition, the MD5 checksum of the map contents may be calculated.

TODO:

• Possibly make the calculation of checksums optional?

Public Types
enum	{ MAX_MAP_NAME_LENGTH = 512 }
Public Member Functions
virtual void	addMapChangedCB (ArFunctor *functor, ArListPos::Pos position=ArListPos::LAST)=0
	Adds a callback that is invoked when the map has been changed.
virtual void	addPostWriteFileCB (ArFunctor *functor, ArListPos::Pos position=ArListPos::LAST)=0
	Adds a callback to be invoked after the map file is written.
virtual void	addPreMapChangedCB (ArFunctor *functor, ArListPos::Pos position=ArListPos::LAST)=0
	Adds a callback called before the map changed callbacks are called.
virtual void	addPreWriteFileCB (ArFunctor *functor, ArListPos::Pos position=ArListPos::LAST)=0
	Adds a callback to be invoked before the map file is written.
	ArMapInterface ()
	Constructor.
virtual bool	calculateChecksum (unsigned char *md5DigestBuffer, size_t md5DigestBufferLen)=0
	Calculates the checksum of the map.
virtual void	clear ()=0
	Clears the map, removing all info, objects and data points and lines.
virtual ArMapInterface *	clone ()=0
	Creates a new map that is "equivalent" to this map.
virtual std::string	createRealFileName (const char *fileName)=0
	Prepends the appropriate directory information on the given filename.
virtual ArArgumentBuilder *	findMapObjectParams (const char *mapObjectName)=0
	Returns the optional parameters associated with a map object, or NULL if none.
virtual const char *	getBaseDirectory (void) const=0
	Gets the base directory.
virtual const char *	getFileName (void) const=0
	Gets the fileName that was loaded.
virtual bool	getIgnoreCase (void)=0
	Gets whether we ignore case or not.
virtual bool	getIgnoreEmptyFileName (void)=0
	Gets whether we ignore empty file names or fail if we encounter one.
virtual ArMapInfoInterface *	getInactiveInfo ()=0
	Provides direct access to the inactive map info.
virtual ArMapObjectsInterface *	getInactiveObjects ()=0
	Provides direct access to the inactive map objects.
virtual ArLog::LogLevel	getMapChangedLogLevel (void)=0
	Returns the level at which information about the map changed callbacks is logged.
virtual bool	getMapId (ArMapId *mapIdOut, bool isInternalCall=false)=0
	Retrieves the map ID.
virtual struct stat	getReadFileStat () const=0
	Returns information about the map file that was read.
virtual std::list< ArArgumentBuilder * > *	getRemainder ()=0
	Returns a list of the map file lines that were not recognized.
virtual std::list< std::string >	getScanTypes () const=0
	Returns a list of the scan types that are defined for this map.
virtual const char *	getTempDirectory (void) const=0
	Gets the temp directory.
virtual bool	isLoadingDataStarted ()=0
virtual bool	isLoadingLinesAndDataStarted ()=0
virtual int	lock ()=0
	Lock the map instance.
virtual void	mapChanged (void)=0
	Function that will call the map changed CBs if needed.
virtual bool	parseLine (char *line)=0
	Parses a map line.
virtual void	parsingComplete (void)=0
	Says that the parsing by lines is done and to use the parsed data.
virtual bool	readFile (const char *fileName, char *errorBuffer=NULL, size_t errorBufferLen=0, unsigned char *md5DigestBuffer=NULL, size_t md5DigestBufferLen=0)=0
	Reads the map from the specified file.
virtual bool	refresh ()=0
	Determines whether the map file needs to be re-read.
virtual void	remMapChangedCB (ArFunctor *functor)=0
	Removes a callback called when the map has been changed.
virtual void	remPostWriteFileCB (ArFunctor *functor)=0
	Removes the given callback from the list of post-write callbacks.
virtual void	remPreMapChangedCB (ArFunctor *functor)=0
	Removes the specified "pre-map-changed callback".
virtual void	remPreWriteFileCB (ArFunctor *functor)=0
	Removes the given callback from the list of pre-write callbacks.
virtual bool	set (ArMapInterface *other)=0
	Sets this map to be "equivalent" to the given other map.
virtual void	setBaseDirectory (const char *baseDirectory)=0
	Sets the base directory.
virtual void	setIgnoreCase (bool ignoreCase=false)=0
	Sets whether we ignore case or not.
virtual void	setIgnoreEmptyFileName (bool ignore)=0
	Sets whether we ignore empty file names or fail if we encounter one.
virtual void	setMapChangedLogLevel (ArLog::LogLevel level)=0
	Sets the level at which to log information about the map changed callbacks.
virtual bool	setMapObjectParams (const char *mapObjectName, ArArgumentBuilder *params, ArMapChangeDetails *changeDetails=NULL)=0
	Sets the optional parameters associated with a map object.
virtual void	setQuiet (bool isQuiet)=0
	Turn on this flag to reduce the number of verbose log messages.
virtual bool	setScanTypes (const std::list< std::string > &scanTypeList)=0
	Sets the scan types that are defined for this map.
virtual void	setSourceFileName (const char *sourceName, const char *fileName, bool isInternalCall=false)=0
	Sets the name of the source and the file from which the map was loaded.
virtual void	setTempDirectory (const char *tempDirectory)=0
	Sets the temp directory.
virtual int	tryLock ()=0
	Try to lock the map instance without blocking.
virtual int	unlock ()=0
	Unlock the map instance.
virtual bool	writeFile (const char *fileName, bool internalCall=false, unsigned char *md5DigestBuffer=NULL, size_t md5DigestBufferLen=0, time_t fileTimestamp=-1)=0
	Writes the map to the specified file.
virtual void	writeObjectsToFunctor (ArFunctor1< const char * > *functor, const char *endOfLineChars, bool isOverrideAsSingleScan=false, const char *maxCategory=NULL)=0
	Writes the map header information and objects to a text-based functor.
virtual void	writeToFunctor (ArFunctor1< const char * > *functor, const char *endOfLineChars)=0
	Writes all of the map to the given text-based functor.
virtual	~ArMapInterface (void)
	Destructor.
Static Public Member Functions
static std::string	createRealFileName (const char *baseDirectory, const char *fileName, bool isIgnoreCase)
	Helper method creates a full file path name from the given components.
Static Public Attributes
static const char *	MAP_CATEGORY_2D
static const char *	MAP_CATEGORY_2D_EXTENDED
	Superset of multi-sources; includes advanced Info types.
static const char *	MAP_CATEGORY_2D_MULTI_SOURCES

---

Member Enumeration Documentation

anonymous enum

Enumerator:

MAX_MAP_NAME_LENGTH

Maximum length of the map file's name.

---

Member Function Documentation

virtual void ArMapInterface::addMapChangedCB	(	ArFunctor *	functor,
		ArListPos::Pos	position = ArListPos::LAST
	)			[pure virtual]

Adds a callback that is invoked when the map has been changed.

The given functor should assume that the map has been lock()-ed when it is invoked. It should also not attempt to make changes to the mapChanged() callback list during the invoke method. This method is not thread-safe.

Parameters:

	functor	a pointer to the ArFunctor to be invoked; must be non-NULL
	position	the ArListPos::Pos indication at which to add the functor (i.e. at the beginning or at the end of the callback list)

virtual void ArMapInterface::addPostWriteFileCB	(	ArFunctor *	functor,
		ArListPos::Pos	position = ArListPos::LAST
	)			[pure virtual]

Adds a callback to be invoked after the map file is written.

Parameters:

	functor	the ArFunctor * callback to be added
	position	the ArListPos::Pos that specifies whether the callback should be added at the front or the back of the list

virtual void ArMapInterface::addPreMapChangedCB	(	ArFunctor *	functor,
		ArListPos::Pos	position = ArListPos::LAST
	)			[pure virtual]

Adds a callback called before the map changed callbacks are called.

The "pre-map-changed callbacks" are invoked *after* the map has been changed, but before the other "map-changed callbacks" are invoked. This method is not thread-safe.

Parameters:

	functor	a pointer to the ArFunctor to be invoked; must be non-NULL
	position	the ArListPos::Pos indication at which to add the functor (i.e. at the beginning or at the end of the callback list)

virtual void ArMapInterface::addPreWriteFileCB	(	ArFunctor *	functor,
		ArListPos::Pos	position = ArListPos::LAST
	)			[pure virtual]

Adds a callback to be invoked before the map file is written.

Parameters:

	functor	the ArFunctor * callback to be added
	position	the ArListPos::Pos that specifies whether the callback should be added at the front or the back of the list

virtual bool ArMapInterface::calculateChecksum	(	unsigned char *	md5DigestBuffer,
		size_t	md5DigestBufferLen
	)			[pure virtual]

Calculates the checksum of the map.

Parameters:

	md5DigestBuffer	the unsigned char buffer in which to store the calculated checksum
	md5DigestBufferLen	the length of the md5DigestBuffer; should be ArMD5Calculator::DIGEST_LENGTH

Returns:

bool true if the checksum was successfully calculated; false if an error occurrred

See also:

ArMD5Calculator

virtual ArMapInterface* ArMapInterface::clone

(

)

[pure virtual]

Creates a new map that is "equivalent" to this map.

Creates a new map that is effectively a copy of this map. Note, however, that the returned map may not be of exactly the same class (so the term "clone" is being used somewhat loosely). In particular, if the active ArMap that is associated with the robot configuration is cloned, then the resulting map will be simpler and not associated with the robot configuration.

Returns:

ArMapInterface * a new copy of this map

Java Wrapper Library: Use cloneMap() instead

virtual ArArgumentBuilder* ArMapInterface::findMapObjectParams

(

const char *

mapObjectName

)

[pure virtual]

Returns the optional parameters associated with a map object, or NULL if none.

The Aria map provides an advanced feature that allows a parameter list to be defined for custom map object types. (Refer to the ArMap MapFileFormat for more information.)

This convenience method provides access to the parameter values for a specified map object. It is basically a shortcut for searching and parsing the CairnInfo argument list. Unlike the CairnInfo arguments (which also include an introduction and map object name), the argument builder returned by this method only contains the parameter values. Also note that if the argument builder contains string parameters, then they may be surrounded by quotes.

The returned pointer should not be stored, modified, or deleted.

See setMapObjectParams for important information about changing the parameter values or the associated map object.

This method is not thread-safe. (The call and use of the returned ArArgumentBuilder should be surrounded by calls to lock()/unlock().)

Parameters:

mapObjectName

the unique char * name of the map object whose parameters are to be retrieved

Returns:

ArArgumentBuilder * a pointer to the map object's parameter values;

virtual bool ArMapInterface::getIgnoreCase

(

void

)

[pure virtual]

Gets whether we ignore case or not.

This method is primarily applicable to the active Aria map that is associated with the robot configuration.

virtual bool ArMapInterface::getIgnoreEmptyFileName

(

void

)

[pure virtual]

Gets whether we ignore empty file names or fail if we encounter one.

This method is primarily applicable to the active Aria map that is associated with the robot configuration.

virtual ArMapInfoInterface* ArMapInterface::getInactiveInfo

(

)

[pure virtual]

Provides direct access to the inactive map info.

The "inactive" info is a section of the Aria map that applications may use to store "_XInfo:" lines that are not currently active or applicable. The inactive info will be written to the map file, but it will not be included in any of the inherited ArMapInfoInterface calls (e.g. getInfo(type)). This is primarily intended for advanced specialized use where something needs to be removed from the map file, but it may be necessary to restore it later. This method is not thread-safe.

Returns:

ArMapInfoInterface * a pointer to the inactive map info section

virtual ArMapObjectsInterface* ArMapInterface::getInactiveObjects

(

)

[pure virtual]

Provides direct access to the inactive map objects.

The "inactive" objects is a section of the Aria map that applications may use to store "_Cairn" lines that are not currently active or applicable. The inactive objects will be written to the map file, but they will not be included in any of the inherited ArMapObjectsInterface calls (e.g. getMapObjects()). This is primarily intended for advanced specialized use where an object needs to be removed from the map file, but it may be necessary to restore it later. This method is not thread-safe.

Returns:

ArMapObjectsInterface * a pointer to the inactive map objects section

virtual bool ArMapInterface::getMapId	(	ArMapId *	mapIdOut,
		bool	isInternalCall = false
	)			[pure virtual]

Retrieves the map ID.

The map ID is a unique identifier based on the map file name and the checksum data. (Perhaps more accurately, it is highly likely to be unique during normal usage.)

Parameters:

	mapIdOut	a pointer to the ArMapId to be set
	isInternalCall	a bool set to true only when getMapId is called within the context of a method that has already locked the map; if false, then the map is locked by this method

Returns:

bool true if the map ID was successfully set; false, otherwise

virtual struct stat ArMapInterface::getReadFileStat

(

)

const [pure virtual]

Returns information about the map file that was read.

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

Implemented in ArMap, and ArMapSimple.

virtual std::list<ArArgumentBuilder *>* ArMapInterface::getRemainder

(

)

[pure virtual]

Returns a list of the map file lines that were not recognized.

Ideally, the returned list should be empty. The remainder list is primarily used to determine whether the editor is up-to-date for the current map version and to try to minimize lost data.

Note that this method returns a pointer to the actual list that is stored in the map object. It is not safe to store this pointer.

This method is not thread-safe.

virtual std::list<std::string> ArMapInterface::getScanTypes

(

)

const [pure virtual]

Returns a list of the scan types that are defined for this map.

This method is not thread-safe.

Returns:

std::list<std::string> a list of the scan types that are defined for this map

virtual bool ArMapInterface::isLoadingDataStarted

(

)

[pure virtual]

This value returns true once the first DATA tag has been reached. The rest of the map contains data points.

virtual bool ArMapInterface::isLoadingLinesAndDataStarted

(

)

[pure virtual]

This value returns true once the first LINES tag has been reached. The rest of the map contains data lines and points.

virtual void ArMapInterface::mapChanged

(

void

)

[pure virtual]

Function that will call the map changed CBs if needed.

Users of Aria maps should invoke this method after making any changes to the map. It causes the installed map changed handlers to be invoked.

This method is not thread-safe. It should be surrounded by calls to lock() and unlock(). For example:

std::list<ArMapObject*> newMapObjects; // Add some objects... myMap->lock(); myMap->setMapObjects(&newMapObjects); myMap->mapChanged(); myMap->unlock();

Note that this method is automatically invoked under some circumstances (such as when the map file is re-read following a change to the robot configuration). Also note that this method will not invoke any callbacks if the map has not been modified via an explicit call to a set method.

See also:

addMapChangedCB

addPreMapChangedCB

virtual bool ArMapInterface::parseLine

(

char *

line

)

[pure virtual]

Parses a map line.

Public for ArQMapProducer

virtual bool ArMapInterface::readFile	(	const char *	fileName,
		char *	errorBuffer = NULL,
		size_t	errorBufferLen = 0,
		unsigned char *	md5DigestBuffer = NULL,
		size_t	md5DigestBufferLen = 0
	)			[pure virtual]

Reads the map from the specified file.

If the file is successfully read into the map, then this method calls mapChanged() afterwards to invoke the installed callbacks.

This method automatically calls lock() and unlock() during operation. Do not call this method if the map is already locked.

Parameters:

	fileName	the name of the file to read; Unless an absolute path to a file is given (starting with "/" or "\" or, on Windows, a drive letter root such as "C:\", "D:\", etc.), it is combined with this map's base directory (see getBaseDirectory()) to form the complete file path name; must be non-NULL
	errorBuffer	a pointer to a char buffer in which specific read errors can be recorded; if NULL, then the return value is the only success indication
	errorBufferLen	the size_t of the error buffer
	md5DigestBuffer	an optional pointer to a buffer in which to store the calculated checksum of the map; if NULL, then the checksum is not output
	md5DigestBufferLen	the size_t of the checksum buffer

Returns:

bool true if the file was successfully read and the map was populated; false if an error occurred

See also:

ArMD5Calculator

Implemented in ArMap.

virtual bool ArMapInterface::refresh

(

)

[pure virtual]

Determines whether the map file needs to be re-read.

This method is primarily applicable to the active Aria map that is associated with the robot configuration. It checks to see if the map file has been modified since it was read, and re-reads it if necessary. The method may do nothing for "simpler" maps.

virtual void ArMapInterface::remMapChangedCB

(

ArFunctor *

functor

)

[pure virtual]

Removes a callback called when the map has been changed.

This method is not thread-safe.

Parameters:

functor

a pointer to the ArFunctor to be removed; must be non-NULL

virtual void ArMapInterface::remPostWriteFileCB

(

ArFunctor *

functor

)

[pure virtual]

Removes the given callback from the list of post-write callbacks.

Parameters:

functor

the ArFunctor * callback to be removed

virtual void ArMapInterface::remPreMapChangedCB

(

ArFunctor *

functor

)

[pure virtual]

Removes the specified "pre-map-changed callback".

This method is not thread-safe.

Parameters:

functor

a pointer to the ArFunctor to be removed; must be non-NULL

virtual void ArMapInterface::remPreWriteFileCB

(

ArFunctor *

functor

)

[pure virtual]

Removes the given callback from the list of pre-write callbacks.

Parameters:

functor

the ArFunctor * callback to be removed

virtual bool ArMapInterface::set

(

ArMapInterface *

other

)

[pure virtual]

Sets this map to be "equivalent" to the given other map.

Modifies this map so that is effectively a copy of the given map. All info, objects, and data points and lines in the other map are copied and stored in this map.

Parameters:

other

a pointer to the ArMapInterface to be copied; must not be NULL

Returns:

bool true if the map was successfully copied to this one; false if an error occurred

virtual void ArMapInterface::setIgnoreCase

(

bool

ignoreCase = false

)

[pure virtual]

Sets whether we ignore case or not.

This method is primarily applicable to the active Aria map that is associated with the robot configuration.

virtual void ArMapInterface::setIgnoreEmptyFileName

(

bool

ignore

)

[pure virtual]

Sets whether we ignore empty file names or fail if we encounter one.

This method is primarily applicable to the active Aria map that is associated with the robot configuration.

virtual bool ArMapInterface::setMapObjectParams	(	const char *	mapObjectName,
		ArArgumentBuilder *	params,
		ArMapChangeDetails *	changeDetails = NULL
	)			[pure virtual]

Sets the optional parameters associated with a map object.

This method sets the parameter values for the specified map object. It should be used only for custom map object types that have a parameter list defined in the MapInfo. (Refer to the ArMap MapFileFormat for more information.)

Like findMapObjectParams(), this is basically a convenience method that simplifies access to the data stored in the CairnInfo argument list.

If the given params is non-NULL, then it is copied and stored in the map. (Note that this deletes the pointer previously returned by findMapObjectParams(mapObjectName). Do not store that pointer.) It is entirely the caller's responsibility to ensure that the params arg count and types are correct.

If the given params is NULL, then the parameter information for the map object is cleared. If a mapObjectWithParams is to be deleted, then setMapObjectParams(mapObjectWithParams->getName(), NULL) must be called first.

Parameters:

	mapObjectName	the unique char * name of the map object whose parameters are to be updated
	params	the ArArgumentBuiler * containing the new parameter values; if NULL, then the parameter information for the map object is deleted
	changeDetails	an optional pointer to the ArMapChangeDetails in which to accumulate a description of the changes to the map; if NULL, then changes are not tracked

See also:

ArMapChangeDetails

virtual bool ArMapInterface::setScanTypes

(

const std::list< std::string > &

scanTypeList

)

[pure virtual]

Sets the scan types that are defined for this map.

This method clears all of the exisiting scans (i.e. point and line data). This method is not thread-safe.

Parameters:

scanTypeList

the list of scan type string identifiers to be set; the list must not contain any duplicate entries

Returns:

bool true if the scan types were successfully set; false otherwise

virtual void ArMapInterface::setSourceFileName	(	const char *	sourceName,
		const char *	fileName,
		bool	isInternalCall = false
	)			[pure virtual]

Sets the name of the source and the file from which the map was loaded.

This method is primarily used to track when a map has been received from the central server or another robot. The source and file name can be retrieved from the map ID.

Parameters:

	sourceName	the const char * name of the central server or robot from which the map was obtained
	fileName	the const char * name of the map file on the source
	isInternalCall	a bool set to true if this method is being called while the map is locked; if false, then this method will lock the map

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

Writes the map to the specified file.

By default, this method automatically calls lock() and unlock() during its operation. If the map is already locked when the file needs to be written, then set the internalCall parameter to true to override the default locking behavior

Parameters:

	fileName	the const char * name of the file to written; it is combined with the getBaseDirectory() to form the complete file path name; must be non-NULL
	internalCall	a bool set to true if writeFile is being called while the map is already locked; set to false to indicate that the map should lock itself during the method
	md5DigestBuffer	an optional pointer to a buffer in which to store the calculated checksum of the map; if NULL, then the checksum is not output
	md5DigestBufferLen	the size_t of the checksum buffer
	fileTimestamp	the time_t to which to set the file write time; in general, this should be left as -1 to indicate that the actual write time is desired; a real time value can be used to synchronize the map across many robots

Returns:

bool true if the file was successfully written; false if an error occurred

See also:

ArMD5Calculator

Implemented in ArMap.

virtual void ArMapInterface::writeObjectsToFunctor	(	ArFunctor1< const char * > *	functor,
		const char *	endOfLineChars,
		bool	isOverrideAsSingleScan = false,
		const char *	maxCategory = NULL
	)			[pure virtual]

Writes the map header information and objects to a text-based functor.

This method writes all of the map scan headers, the info arguments, and the Cairn map objects to the given functor. It does not write the actual scan point or line segment data (nor the header lines that introduce the data). This method is not thread-safe.

Parameters:

	functor	a pointer to the ArFunctor1 to which to write the map header as text lines
	endOfLineChars	the const char * string to use as an end-of-line indicator
	isOverrideAsSingleScan	a bool set to true if only a single scan header should be written; this is generally the "summary scan" and is used to maintain backwards compatibility with client applications that do not expect multiple scan types in a single map.

virtual void ArMapInterface::writeToFunctor	(	ArFunctor1< const char * > *	functor,
		const char *	endOfLineChars
	)			[pure virtual]

Writes all of the map to the given text-based functor.

This method is not thread-safe

Parameters:

	functor	a pointer to the ArFunctor1 to which to write the map header as text lines
	endOfLineChars	the const char * string to use as an end-of-line indicator

---

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

• ArMapInterface.h

---