ArMapInterface defines the methods that are available on all Aria maps. More...

#include <ArMapInterface.h>

Inherits ArHasFileName, ArMapInfoInterface, ArMapObjectsInterface, ArMapScanInterface, and ArMapSupplementInterface.

Public Types
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...

Public Member Functions
virtual void	addMapChangedCB (ArFunctor *functor, ArListPos::Pos position)
	Adds a callback that is invoked when the map has been changed. More...

virtual void	addMapChangedCB (ArFunctor *functor, int position=50)=0
	Adds a callback that is invoked when the map has been changed. More...

virtual void	addPostWriteFileCB (ArFunctor *functor, ArListPos::Pos position=ArListPos::LAST)=0
	Adds a callback to be invoked after the map file is written. More...

virtual void	addPreMapChangedCB (ArFunctor *functor, ArListPos::Pos position)
	Adds a callback called before the map changed callbacks are called. More...

virtual void	addPreMapChangedCB (ArFunctor *functor, int position=50)=0
	Adds a callback called before the map changed callbacks are called. More...

virtual void	addPreWriteFileCB (ArFunctor *functor, ArListPos::Pos position=ArListPos::LAST)=0
	Adds a callback to be invoked before the map file is written. More...

	ArMapInterface ()
	Constructor.

virtual bool	calculateChecksum (unsigned char *md5DigestBuffer, size_t md5DigestBufferLen)=0
	Calculates the checksum of the map. More...

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. More...

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. More...

virtual const char *	getBaseDirectory (void) const =0
	Gets the base directory.

virtual ArMapObjectsInterface *	getChildObjects ()=0
	Provides direct access to the child map objects which are used to define group templates.

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. More...

virtual bool	getIgnoreEmptyFileName (void)=0
	Gets whether we ignore empty file names or fail if we encounter one. More...

virtual ArMapInfoInterface *	getInactiveInfo ()=0
	Provides direct access to the inactive map info. More...

virtual ArMapObjectsInterface *	getInactiveObjects ()=0
	Provides direct access to the inactive map objects. More...

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. More...

virtual struct stat	getReadFileStat () const =0
	Returns information about the map file that was read. More...

virtual std::list< ArArgumentBuilder * > *	getRemainder ()=0
	Returns a list of the map file lines that were not recognized. More...

virtual std::list< std::string >	getScanTypes () const =0
	Returns a list of the scan types that are defined for this map. More...

virtual const char *	getTempDirectory (void) const =0
	Gets the temp directory.

virtual bool	isLoadingDataStarted ()=0
	This value returns true once the first DATA tag has been reached. More...

virtual bool	isLoadingLinesAndDataStarted ()=0
	This value returns true once the first LINES tag has been reached. More...

virtual int	lock ()=0
	Lock the map instance.

virtual void	mapChanged (void)=0
	Function that will call the map changed CBs if needed. More...

virtual bool	parseLine (char *line)=0
	Public for ArQMapProducer. More...

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. More...

virtual bool	refresh ()=0
	Determines whether the map file needs to be re-read. More...

virtual void	remMapChangedCB (ArFunctor *functor)=0
	Removes a callback called when the map has been changed. More...

virtual void	remPostWriteFileCB (ArFunctor *functor)=0
	Removes the given callback from the list of post-write callbacks. More...

virtual void	remPreMapChangedCB (ArFunctor *functor)=0
	Removes the specified "pre-map-changed callback". More...

virtual void	remPreWriteFileCB (ArFunctor *functor)=0
	Removes the given callback from the list of pre-write callbacks. More...

virtual bool	set (ArMapInterface *other)=0
	Sets this map to be "equivalent" to the given other map. More...

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. More...

virtual void	setIgnoreEmptyFileName (bool ignore)=0
	Sets whether we ignore empty file names or fail if we encounter one. More...

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. More...

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. More...

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. More...

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. More...

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. More...

virtual void	writeToFunctor (ArFunctor1< const char > functor, const char *endOfLineChars)=0
	Writes all of the map to the given text-based functor. More...

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 std::list< ArArgumentBuilder * > *	getInfo (const char *infoName)=0
	Returns the arguments for the specified info category; or NULL if none found. More...

virtual std::list< ArArgumentBuilder * > *	getInfo (int infoType)=0
	Gets the strings for the specified Info category. More...

virtual int	getInfoCount () const =0
	Returns the number of info categories that are contained in this collection.

virtual const char *	getInfoName (int infoType)=0
	Returns the name of the specified Info type. More...

virtual std::list< std::string >	getInfoNames () const =0
	Returns a list of the info category names that are contained in this collection. More...

virtual std::list< ArArgumentBuilder * > *	getMapInfo (void)=0
	Gets the map info strings. More...

virtual bool	setInfo (const char infoName, const std::list< ArArgumentBuilder > infoList, ArMapChangeDetails changeDetails=NULL)=0
	Sets the contents of the specified Info category (copies those passed in) More...

virtual bool	setInfo (int infoType, const std::list< ArArgumentBuilder > infoList, ArMapChangeDetails *changeDetails=NULL)=0
	Sets the contents of the specified Info category (copies those passed in) More...

virtual bool	setMapInfo (const std::list< ArArgumentBuilder > mapInfo, ArMapChangeDetails *changeDetails=NULL)=0
	Sets the map info (copies those passed in) More...

virtual void	writeInfoToFunctor (ArFunctor1< const char > functor, const char *endOfLineChars)=0
	Writes the info collection to a text-based functor. More...

virtual	~ArMapInfoInterface ()
	Destructor.

Public Member Functions inherited from ArMapObjectsInterface
	ArMapObjectsInterface ()
	Constructor.

virtual ArMapObject *	findFirstMapObject (const char name, const char type, bool isIncludeWithHeading=false)=0
	Returns the first map object of given name and type, or NULL if none is found. More...

virtual ArMapObject *	findMapObject (const char name, const char type=NULL, bool isIncludeWithHeading=false)=0
	Returns the map object of given name and type, or NULL if none is found. More...

virtual std::list< ArMapObject * >	findMapObjectsOfType (const char *type, bool isIncludeWithHeading=false)=0
	Returns a list of all map objects of the specified type. More...

virtual std::list< ArMapObject * > *	getMapObjects (void)=0
	Returns a pointer to the internal list of map objects. More...

virtual void	setMapObjects (const std::list< ArMapObject > mapObjects, bool isSortedObjects=false, ArMapChangeDetails *changeDetails=NULL)=0
	Sets the map objects (copies those passed in) More...

virtual void	writeObjectListToFunctor (ArFunctor1< const char > functor, const char *endOfLineChars)=0
	Writes the list of map objects to a text-based functor. More...

virtual	~ArMapObjectsInterface ()
	Destructor.

Public Member Functions inherited from ArMapScanInterface
virtual bool	addToFileParser (ArFileParser *fileParser)=0
	Adds handlers for this scan data's header information to the given file parser. More...

	ArMapScanInterface ()
	Default constructor.

virtual const char *	getDisplayString (const char *scanType=ARMAP_DEFAULT_SCAN_TYPE)=0

virtual ArPose	getLineMaxPose (const char *scanType=ARMAP_DEFAULT_SCAN_TYPE)=0
	Returns the upper right point (maximum x and y) of the scan's line segments. More...

virtual ArPose	getLineMinPose (const char *scanType=ARMAP_DEFAULT_SCAN_TYPE)=0
	Returns the lower left point (minimum x and y) of the scan's line segments. More...

virtual std::vector< ArLineSegment > *	getLines (const char *scanType=ARMAP_DEFAULT_SCAN_TYPE)=0
	Returns a pointer to the line segments for the specified scan. More...

virtual ArPose	getMaxPose (const char *scanType=ARMAP_DEFAULT_SCAN_TYPE)=0
	Returns the upper right point (maximum x and y) of the scan's points. More...

virtual ArPose	getMinPose (const char *scanType=ARMAP_DEFAULT_SCAN_TYPE)=0
	Returns the lower left point (minimum x and y) of the scan's points. More...

virtual int	getNumLines (const char *scanType=ARMAP_DEFAULT_SCAN_TYPE)=0
	Returns the number of line segments in the specified scan. More...

virtual int	getNumPoints (const char *scanType=ARMAP_DEFAULT_SCAN_TYPE)=0
	Returns the number of points in the specified scan. More...

virtual std::vector< ArPose > *	getPoints (const char *scanType=ARMAP_DEFAULT_SCAN_TYPE)=0
	Returns a pointer to the map points for the specified scan. More...

virtual int	getResolution (const char *scanType=ARMAP_DEFAULT_SCAN_TYPE)=0
	Gets the resolution (-1 if none specified) More...

virtual bool	isSortedLines (const char *scanType=ARMAP_DEFAULT_SCAN_TYPE) const =0
	Returns whether the line segment vector for the specified scan is sorted. More...

virtual bool	isSortedPoints (const char *scanType=ARMAP_DEFAULT_SCAN_TYPE) const =0
	Returns whether the point vector for the specified scan is sorted. More...

virtual void	loadDataPoint (double x, double y)=0
	Adds the specified data point to the scan data.

virtual void	loadLineSegment (double x1, double y1, double x2, double y2)=0
	Adds the specified line segment to the scan data.

virtual bool	readDataPoint (char *line)=0
	Reads a data point from the given line and adds it to this scan data. More...

virtual bool	readLineSegment (char *line)=0
	Reads a line segment from the given line and adds it to this scan data. More...

virtual bool	remFromFileParser (ArFileParser *fileParser)=0
	Removes the handlers for this scan data's header information from the given file parser. More...

virtual void	setLines (const std::vector< ArLineSegment > lines, const char scanType=ARMAP_DEFAULT_SCAN_TYPE, bool isSortedLines=false, ArMapChangeDetails *changeDetails=NULL)=0
	Sets the lines (copies those passed in) More...

virtual void	setPoints (const std::vector< ArPose > points, const char scanType=ARMAP_DEFAULT_SCAN_TYPE, bool isSortedPoints=false, ArMapChangeDetails *changeDetails=NULL)=0
	Sets the points (copies those passed in) More...

virtual void	setResolution (int resolution, const char scanType=ARMAP_DEFAULT_SCAN_TYPE, ArMapChangeDetails changeDetails=NULL)=0
	Sets the resolution (-1 if none specified) More...

virtual void	writeLinesToFunctor (ArFunctor2< int, std::vector< ArLineSegment > > functor, const char scanType=ARMAP_DEFAULT_SCAN_TYPE, ArFunctor1< const char > *keywordFunctor=NULL)=0
	Writes the map line segments to a functor. More...

virtual void	writePointsToFunctor (ArFunctor2< int, std::vector< ArPose > > functor, const char scanType=ARMAP_DEFAULT_SCAN_TYPE, ArFunctor1< const char > *keywordFunctor=NULL)=0
	Writes the scan data points to a functor. More...

virtual void	writeScanToFunctor (ArFunctor1< const char > functor, const char endOfLineChars, const char scanType=ARMAP_DEFAULT_SCAN_TYPE)=0
	This method writes a text line for each of the scan header attributes (such as MinPose, MaxPose, NumPoints). More...

virtual	~ArMapScanInterface ()
	Destructor.

Public Member Functions inherited from ArMapSupplementInterface
	ArMapSupplementInterface ()
	Default constructor.

virtual double	getOriginAltitude ()=0
	Gets the altitude of the origin; valid only if hasOriginLatLongAlt returns true. More...

virtual ArPose	getOriginLatLong ()=0
	Returns the latitude/longitude origin; valid only if hasOriginLatLongAlt returns true.

virtual bool	hasOriginLatLongAlt ()=0
	Returns whether this map has an origin specified in latitude/longitude (and altitude)

virtual void	setOriginLatLongAlt (bool hasOriginLatLong, const ArPose &originLatLong, double altitude, ArMapChangeDetails *changeDetails=NULL)=0
	Sets the latitude/longitude and altitude of the origin. More...

virtual void	writeSupplementToFunctor (ArFunctor1< const char > functor, const char *endOfLineChars)=0
	Writes the supplemental data to the given functor. More...

virtual	~ArMapSupplementInterface ()
	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. 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
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

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?

Member Enumeration Documentation

◆ anonymous enum

anonymous enum

Enumerator
MAX_MAP_NAME_LENGTH	Maximum length of the map file's name.

Member Function Documentation

◆ addMapChangedCB() [1/2]

void ArMapInterface::addMapChangedCB	(	ArFunctor *	functor,
		ArListPos::Pos	position
	)

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.

This method is just a wrapper for compatibility, the one that takes position as an integer is the main one that should be used now.

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)

◆ addMapChangedCB() [2/2]

virtual void ArMapInterface::addMapChangedCB	(	ArFunctor *	functor,
		int	position = `50`
	)

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	this indicates the order in which the functors will be called, the nominal range is 0 to 100, highest is called first

◆ addPostWriteFileCB()

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

◆ addPreMapChangedCB() [1/2]

void ArMapInterface::addPreMapChangedCB	(	ArFunctor *	functor,
		ArListPos::Pos	position
	)

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.

This method is just a wrapper for compatibility, the one that takes position as an integer is the main one that should be used now.

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)

Java and Python Wrappers: call as addPreMapChangedCBPos() if passing an ArListPos.Pos object for position rather than an int

◆ addPreMapChangedCB() [2/2]

virtual void ArMapInterface::addPreMapChangedCB	(	ArFunctor *	functor,
		int	position = `50`
	)

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	this indicates the order in which the functors will be called, the nominal range is 0 to 100, highest is called first

◆ addPreWriteFileCB()

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

◆ calculateChecksum()

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

◆ clone()

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

◆ createRealFileName()

std::string ArMapInterface::createRealFileName	(	const char *	baseDirectory,
		const char *	fileName,
		bool	isIgnoreCase
	)

static

Helper method creates a full file path name from the given components.

Determines what system file path to use based on the contents of baseDirectory, fileName and isIgnoreCase.

If fileName is not an absolute path and baseDirectory is not null and not empty, then it is combined with baseDirectory to form a full path. An absolute path starts with the '/' or '\' character, or on Windows, with "X:\" where X is any upper or lower case alphabetic character A-Z or a-z.

◆ findMapObjectParams()

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;

◆ getIgnoreCase()

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.

◆ getIgnoreEmptyFileName()

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.

◆ getInactiveInfo()

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

◆ getInactiveObjects()

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

◆ getMapId()

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

◆ getReadFileStat()

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 ArMapSimple, and ArMap.

◆ getRemainder()

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.

◆ getScanTypes()

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

◆ isLoadingDataStarted()

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.

◆ isLoadingLinesAndDataStarted()

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.

◆ mapChanged()

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

◆ parseLine()

virtual bool ArMapInterface::parseLine ( char * line )

pure virtual

Public for ArQMapProducer.

Parses a map line

◆ readFile()

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.

◆ refresh()

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.

◆ remMapChangedCB()

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

◆ remPostWriteFileCB()

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

◆ remPreMapChangedCB()

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

◆ remPreWriteFileCB()

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

◆ set()

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

◆ setIgnoreCase()

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.

◆ setIgnoreEmptyFileName()

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.

◆ setMapObjectParams()

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

Implemented in ArMapSimple.

◆ setScanTypes()

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

◆ setSourceFileName()

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

◆ writeFile()

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.

◆ writeObjectsToFunctor()

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.
maxCategory	if given, limit map category

◆ writeToFunctor()

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

ArMapInterface.h
ArMapInterface.cpp

Public Types

Public Member Functions

Static Public Member Functions

Static Public Attributes

Detailed Description

Member Enumeration Documentation

◆ anonymous enum

Member Function Documentation

◆ addMapChangedCB() [1/2]

◆ addMapChangedCB() [2/2]

◆ addPostWriteFileCB()

◆ addPreMapChangedCB() [1/2]

◆ addPreMapChangedCB() [2/2]

◆ addPreWriteFileCB()

◆ calculateChecksum()

◆ clone()

◆ createRealFileName()

◆ findMapObjectParams()

◆ getIgnoreCase()

◆ getIgnoreEmptyFileName()

◆ getInactiveInfo()

◆ getInactiveObjects()

◆ getMapId()

◆ getReadFileStat()

◆ getRemainder()

◆ getScanTypes()

◆ isLoadingDataStarted()

◆ isLoadingLinesAndDataStarted()

◆ mapChanged()

◆ parseLine()

◆ readFile()

◆ refresh()

◆ remMapChangedCB()

◆ remPostWriteFileCB()

◆ remPreMapChangedCB()

◆ remPreWriteFileCB()

◆ set()

◆ setIgnoreCase()

◆ setIgnoreEmptyFileName()

◆ setMapObjectParams()

◆ setScanTypes()

◆ setSourceFileName()

◆ writeFile()

◆ writeObjectsToFunctor()

◆ writeToFunctor()