371 lines
14 KiB
C++
371 lines
14 KiB
C++
/*
|
|
Adept MobileRobots Robotics Interface for Applications (ARIA)
|
|
Copyright (C) 2004, 2005 ActivMedia Robotics LLC
|
|
Copyright (C) 2006, 2007, 2008, 2009, 2010 MobileRobots Inc.
|
|
Copyright (C) 2011, 2012, 2013 Adept Technology
|
|
|
|
This program is free software; you can redistribute it and/or modify
|
|
it under the terms of the GNU General Public License as published by
|
|
the Free Software Foundation; either version 2 of the License, or
|
|
(at your option) any later version.
|
|
|
|
This program is distributed in the hope that it will be useful,
|
|
but WITHOUT ANY WARRANTY; without even the implied warranty of
|
|
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
|
|
GNU General Public License for more details.
|
|
|
|
You should have received a copy of the GNU General Public License
|
|
along with this program; if not, write to the Free Software
|
|
Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
|
|
|
|
If you wish to redistribute ARIA under different terms, contact
|
|
Adept MobileRobots for information about a commercial version of ARIA at
|
|
robots@mobilerobots.com or
|
|
Adept MobileRobots, 10 Columbia Drive, Amherst, NH 03031; +1-603-881-7960
|
|
*/
|
|
/* \file ArMapObject.h
|
|
* \brief Contains the definition of the ArMapObject class.
|
|
* \date 06/27/08
|
|
* \author K. Cunningham
|
|
*/
|
|
#ifndef ARMAPOBJECT_H
|
|
#define ARMAPOBJECT_H
|
|
|
|
#include "ariaTypedefs.h"
|
|
#include "ariaUtil.h"
|
|
|
|
/// A point or region of interest in an Aria map.
|
|
/**
|
|
* ArMapObject contains the data related to an Aria map object, i.e a point or
|
|
* region of interest in an Aria map that is not part of the sensed obstacle
|
|
* data. Examples of map objects include goals, docks, forbidden lines, and
|
|
* forbidden areas. Applications may define their own custom ArMapObject types
|
|
* using the ArMap MapInfo mechanism. See @ref ArMap for more information.
|
|
*
|
|
* The basic attributes of an ArMapObject include the type of the map object,
|
|
* an optional name of the object, and its position information. As mentioned
|
|
* above, there are two basic categories of ArMapObjects:
|
|
*
|
|
* - Points: A single ArPose in the map. By convention, if a map object
|
|
* can have an optional heading, then "WithHeading" appears at the end of
|
|
* the object type when the heading is specified. For example, "Goal"
|
|
* designates an (x,y) location in the map (any heading or theta value should
|
|
* be ignored) and "GoalWithHeading" designates
|
|
* an (x,y,th) location.
|
|
*
|
|
* - Regions: A set of two ArPoses ("from" and "to") which define a rectangle
|
|
* or a line. Rectangles may have an associated rotation value. It is the
|
|
* rotation to be applied to the "from" and "to" poses <em> around
|
|
* the global origin </em>. To retrieve the list of line segments that
|
|
* comprise the rotated rectangle's perimeter, use the getFromToSegments()
|
|
* method.
|
|
*
|
|
* Note that the ArMapObject is generally immutable. If an object needs to be
|
|
* changed, then the original version should simply be replaced with a new one.
|
|
* See ArMap::getMapObjects(), ArMap::setMapObjects(), and ArMap::mapChanged().
|
|
*
|
|
**/
|
|
class ArMapObject
|
|
{
|
|
public:
|
|
|
|
/// Creates a new ArMapObject whose attributes are as specified in the given arguments
|
|
/**
|
|
* @param arg the ArArgumentBuilder * from which to create the ArMapObject; this
|
|
* should correspond to a parsed line in the ArMap file
|
|
* @return ArMapObject * the newly created map object, or NULL if an error
|
|
* occurred
|
|
**/
|
|
AREXPORT static ArMapObject *createMapObject(ArArgumentBuilder *arg);
|
|
|
|
|
|
/// ArArgumentBuilder indices for the various map object attributes
|
|
enum ArgIndex {
|
|
TYPE_ARG_INDEX = 0,
|
|
POSE_X_ARG_INDEX = 1,
|
|
POSE_Y_ARG_INDEX = 2,
|
|
TH_ARG_INDEX = 3,
|
|
DESC_ARG_INDEX = 4,
|
|
ICON_ARG_INDEX = 5,
|
|
NAME_ARG_INDEX = 6,
|
|
LAST_POSE_ARG_INDEX = NAME_ARG_INDEX,
|
|
FROM_X_ARG_INDEX = 7,
|
|
FROM_Y_ARG_INDEX = 8,
|
|
TO_X_ARG_INDEX = 9,
|
|
TO_Y_ARG_INDEX = 10,
|
|
LAST_ARG_INDEX = TO_Y_ARG_INDEX
|
|
};
|
|
|
|
enum {
|
|
ARG_INDEX_COUNT = LAST_ARG_INDEX + 1
|
|
};
|
|
|
|
// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
|
|
// Instance Methods
|
|
// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
|
|
|
|
/// Constructor
|
|
/**
|
|
* @param type the char * type of the map object (e.g. "Goal", "ForbiddenLine");
|
|
* must be non-empty
|
|
* @param pose the primary ArPose of the map object; for points, this is its
|
|
* location; for rectangles, this specifies the rotation of the rectangle (in
|
|
* pose.getTh())
|
|
* @param description an optional char * description of the object.
|
|
* @param iconName char * currently unused: use "ICON" or NULL as a dummy value. Must
|
|
* be a non-empty, non-whitespace string.
|
|
* @param name the char * name of the map object; depending on the object type,
|
|
* this may be optional or required
|
|
* @param hasFromTo a bool set to true if the object is a region (i.e. line or
|
|
* rectangle); false if the object is a point
|
|
* @param fromPose the ArPose that defines the start point of the region object;
|
|
* applicable only when hasFromTo is true
|
|
* @param toPose the ArPose that defines the end point of the region object;
|
|
* applicable only when hasFromTo is true
|
|
**/
|
|
AREXPORT ArMapObject(const char *type,
|
|
ArPose pose,
|
|
const char *description,
|
|
const char *iconName,
|
|
const char *name,
|
|
bool hasFromTo,
|
|
ArPose fromPose,
|
|
ArPose toPose);
|
|
|
|
/// Copy constructor
|
|
AREXPORT ArMapObject(const ArMapObject &mapObject);
|
|
|
|
/// Assignment operator
|
|
AREXPORT ArMapObject &operator=(const ArMapObject &mapObject);
|
|
|
|
/// Destructor
|
|
AREXPORT virtual ~ArMapObject();
|
|
|
|
// --------------------------------------------------------------------------
|
|
// Text Attributes:
|
|
// --------------------------------------------------------------------------
|
|
|
|
/// Returns the type of the map object
|
|
AREXPORT const char *getType(void) const;
|
|
|
|
/// Returns the "base" (or root) type of the map object
|
|
/**
|
|
* If the map object type ends with "WithHeading", then the base is the
|
|
* corresponding heading-less type. For example, "GoalWithHeading" has a
|
|
* base type of "Goal".
|
|
*
|
|
* If the map object type does not end with "WithHeading", then the base
|
|
* is the same as the type.
|
|
**/
|
|
AREXPORT const char *getBaseType(void) const;
|
|
|
|
/// Returns the name of the map object (if any)
|
|
AREXPORT const char *getName(void) const;
|
|
|
|
/// Returns the optional description of the map object
|
|
AREXPORT const char *getDescription() const ;
|
|
|
|
/// Returns the icon string of the object
|
|
/**
|
|
* The use of the ICON field is application-dependent. It currently contains
|
|
* either the string "ICON" or "ID=<n>". The ID is used only when auto-numbering
|
|
* has been turned on in the MapInfo.
|
|
**/
|
|
AREXPORT const char *getIconName(void) const;
|
|
|
|
/// Returns the numerical identifier of the object, when auto-numbering is on.
|
|
/**
|
|
* This method returns 0 when auto-numbering is off.
|
|
**/
|
|
AREXPORT int getId() const;
|
|
|
|
/// Sets the description of the map object
|
|
/**
|
|
* This method really should only be called immediately after the object
|
|
* is created, and before it is added to the map. (Since the map object
|
|
* isn't intended to be mutable.) It exists for backwards compatibility.
|
|
**/
|
|
AREXPORT void setDescription(const char *description);
|
|
|
|
|
|
// --------------------------------------------------------------------------
|
|
// Position Attributes:
|
|
// --------------------------------------------------------------------------
|
|
|
|
/// Returns the primary pose of the object
|
|
/**
|
|
* For points, this is the map object's location; for rectangles, this
|
|
* specifies the rotation of the rectangle (in getPose().getTh())
|
|
**/
|
|
AREXPORT ArPose getPose(void) const;
|
|
|
|
/// Returns true if the map object has valid "from/to" poses (i.e. is a line or rectangle)
|
|
AREXPORT bool hasFromTo(void) const;
|
|
|
|
/// Returns the "from" pose for lines and rectangles; valid only if hasFromTo()
|
|
AREXPORT ArPose getFromPose(void) const;
|
|
/// Returns the "to" pose for lines and rectangles; valid only if hasFromTo()
|
|
AREXPORT ArPose getToPose(void) const;
|
|
|
|
/// Returns the optional rotation of a rectangle; or 0 if none
|
|
/**
|
|
* Note that this function doesn't know whether it actually makes sense
|
|
* for this map object to have the rotation. (For example, it makes sense
|
|
* on a ForbiddenArea but not a ForbiddenLine.)
|
|
*
|
|
**/
|
|
AREXPORT double getFromToRotation(void) const;
|
|
|
|
/// Gets a list of fromTo line segments that have been rotated
|
|
/**
|
|
* Note that this function doesn't know whether it actually makes sense
|
|
* for this map object to have the rotation. (For example, it makes sense
|
|
* on a ForbiddenArea but not a ForbiddenLine.) This is just here so
|
|
* that everyone doesn't have to do the same calculation. Note that
|
|
* this might be a little more CPU/Memory intensive transfering
|
|
* these around, so you may want to keep a copy of them if you're
|
|
* using them a lot (but make sure you clear the copy if the map
|
|
* changes). It may not make much difference on a modern processor
|
|
* though (its set up this way for safety).
|
|
**/
|
|
AREXPORT std::list<ArLineSegment> getFromToSegments(void);
|
|
|
|
/// Gets a line segment that goes from the from to the to
|
|
/**
|
|
* Note that this function doesn't know whether this is supposed to
|
|
* be a rectangle or a line. (For example, it makes sense on a
|
|
* ForbiddenLine but not a ForbiddenAra.) This is just here to
|
|
* store it. Note that this might be a little more CPU/Memory
|
|
* intensive transfering these around, so you may want to keep a
|
|
* copy of them if you're using them a lot (but make sure you clear
|
|
* the copy if the map changes). It may not make much difference on
|
|
* a modern processor though (its set up this way for safety).
|
|
**/
|
|
AREXPORT ArLineSegment getFromToSegment(void);
|
|
|
|
/// Computes the center pose of the map object.
|
|
/**
|
|
* This method determines the center of map objects that have a "from" and a
|
|
* "to" pose (i.e. lines and rectangles). For map objects that are poses,
|
|
* this method simply returns the pose.
|
|
**/
|
|
AREXPORT ArPose findCenter(void) const;
|
|
|
|
// --------------------------------------------------------------------------
|
|
// I/O Methods
|
|
// --------------------------------------------------------------------------
|
|
|
|
/// Returns the text representation of the map object
|
|
/**
|
|
* The returned string is suitable for writing to the ArMap file. Note that
|
|
* the string does NOT include the map object's optional parameters.
|
|
**/
|
|
AREXPORT const char *toString() const;
|
|
|
|
/// Returns the text representation of the map object
|
|
/**
|
|
* This method is equivalent to toString();
|
|
**/
|
|
const char *getStringRepresentation() const {
|
|
return toString();
|
|
}
|
|
|
|
/// Writes the map object to the ArLog.
|
|
/**
|
|
* @param intro an optional string that should appear before the object
|
|
**/
|
|
AREXPORT void log(const char *intro = NULL) const;
|
|
|
|
|
|
// --------------------------------------------------------------------------
|
|
// Miscellaneous Methods
|
|
// --------------------------------------------------------------------------
|
|
|
|
/// Less than operator (for sets), orders by position
|
|
AREXPORT bool operator<(const ArMapObject& other) const;
|
|
|
|
|
|
/// Gets the fileName of the object (probably never used for maps)
|
|
/**
|
|
* This method is maintained solely for backwards compatibility.
|
|
* It now returns the same value as getDescription (i.e. any file names
|
|
* that may have been associated with an object can now be found in the
|
|
* description attribute).
|
|
* @deprecated
|
|
**/
|
|
AREXPORT const char *getFileName(void) const;
|
|
|
|
private:
|
|
|
|
/// Parses the given arguments and sets the description of the given ArMapObject
|
|
static bool setObjectDescription(ArMapObject *object,
|
|
ArArgumentBuilder *arg);
|
|
|
|
protected:
|
|
|
|
/// The type of the map object
|
|
std::string myType;
|
|
/// If non-empty, then myType ends with "WithHeading" and this is the "root"
|
|
std::string myBaseType;
|
|
|
|
/// The name of the map object, if any
|
|
std::string myName;
|
|
/// The description of the map object
|
|
std::string myDescription;
|
|
|
|
/// For pose objects, THE pose; For rectangle objects, contains the optional rotation
|
|
ArPose myPose;
|
|
|
|
/// Reserved for future use
|
|
std::string myIconName;
|
|
|
|
/// Whether the map object is a region (line or rect) with "from/to" poses
|
|
bool myHasFromTo;
|
|
/// The "from" pose of a region map object; valid only if myHasFromTo is true
|
|
ArPose myFromPose;
|
|
/// The "to" pose of a region map object; valid only if myHasFromTo is true
|
|
ArPose myToPose;
|
|
|
|
/// For rectangle objects, the line segments that comprise the perimeter (even if rotated)
|
|
std::list<ArLineSegment> myFromToSegments;
|
|
/// For line objects, the line
|
|
ArLineSegment myFromToSegment;
|
|
|
|
/// Text representation written to the map file
|
|
mutable std::string myStringRepresentation;
|
|
|
|
}; // end class ArMapObject
|
|
|
|
|
|
// =============================================================================
|
|
|
|
#ifndef SWIG
|
|
/// Comparator for two pointers to map objects
|
|
/** @swigomit */
|
|
struct ArMapObjectCompare :
|
|
public std::binary_function<const ArMapObject *,
|
|
const ArMapObject *,
|
|
bool>
|
|
{
|
|
/// Returns true if obj1 is less than obj2; NULL pointers are greater than non-NULL
|
|
bool operator()(const ArMapObject *obj1,
|
|
const ArMapObject *obj2)
|
|
{
|
|
if ((obj1 != NULL) && (obj2 != NULL)) {
|
|
return *obj1 < *obj2;
|
|
}
|
|
else if ((obj1 == NULL) && (obj2 == NULL)) {
|
|
return false;
|
|
}
|
|
else {
|
|
return (obj1 == NULL);
|
|
}
|
|
} // end operator()
|
|
|
|
}; // end struct ArMapObjectCompare
|
|
|
|
#endif //ifndef SWIG
|
|
|
|
#endif // ARMAPOBJECT_H
|
|
|