507 lines
19 KiB
C++
507 lines
19 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
|
|
*/
|
|
#ifndef ARCAMERACOLLECTION_H
|
|
#define ARCAMERACOLLECTION_H
|
|
|
|
#include <list>
|
|
#include <map>
|
|
#include <string>
|
|
|
|
#include "ArConfigArg.h"
|
|
#include "ArFunctor.h"
|
|
#include "ArMutex.h"
|
|
|
|
class ArCameraCollectionItem;
|
|
class ArCameraParameterSource;
|
|
|
|
/// Maintains information about all of the robot's cameras.
|
|
/**
|
|
* ArCameraCollection is a repository for information about each of the
|
|
* cameras that are installed on the robot. It enables clients to adjust
|
|
* to robots with varying camera configurations.
|
|
* <p>
|
|
* Three main types of information are maintained for each camera:
|
|
* <ul>
|
|
* <li> Overview Information: This includes the name and type of the camera,
|
|
* along with text strings suitable for display. Note that each camera
|
|
* must be assigned a unique name. Furthermore, the overview information
|
|
* must be added to the collection before any of the other types of
|
|
* information are added.</li>
|
|
*
|
|
* <li> Command Information: Each camera may respond to any number
|
|
* of generic commands (such as pan/tilt/zoom, or get camera picture).
|
|
* The command information defines which commands are supported for
|
|
* each camera, and also defines a unique "camera command name" for
|
|
* each generic command. (The "camera command name", for example,
|
|
* may be used as a network packet name. It must be unique across
|
|
* <em>all</em> of the robot's cameras.) Commands which are commonly
|
|
* supported are defined in ArCameraCommands, but additional ones may
|
|
* be added.</li>
|
|
*
|
|
* <li> Parameter Information: Parameters, or settings, may be defined
|
|
* for each camera. A framework has been built into the collection to
|
|
* allow clients to view/edit the parameters. Changes are relayed to
|
|
* the originator (source) of the parameter, which is responsible for
|
|
* actually adjusting the camera hardware. </li>
|
|
* </ul>
|
|
* <p>
|
|
* Callbacks may be installed on the collection to be notified whenever
|
|
* the collection is modified. This notification only occurs when
|
|
* cameras, commands, or parameters are added or removed. (The editing
|
|
* of parameters is merely passed to the parameter source.)
|
|
* <p>
|
|
* ArCameraCollection is thread-safe.
|
|
|
|
@ingroup OptionalClasses
|
|
**/
|
|
class ArCameraCollection
|
|
{
|
|
public:
|
|
|
|
/// Constructor
|
|
AREXPORT ArCameraCollection();
|
|
|
|
/// Destructor
|
|
AREXPORT virtual ~ArCameraCollection();
|
|
|
|
// ---------------------------------------------------------------------------
|
|
|
|
/// Adds a new camera to the collection.
|
|
/**
|
|
* @param cameraName the char * name of the camera; must be unique
|
|
* and non-NULL
|
|
* @param cameraType the char * type of the camera (e.g. VCC4 or Omni)
|
|
* @param displayName the char * string to be displayed for the
|
|
* camera name; if NULL, then the cameraName is used instead
|
|
* @param displayType the char * string to be displayed for the
|
|
* camera type; if NULL, then the cameraType is used instead
|
|
* @return bool true if the camera was successfully added; false,
|
|
* otherwise.
|
|
**/
|
|
AREXPORT virtual bool addCamera(const char *cameraName,
|
|
const char *cameraType,
|
|
const char *displayName,
|
|
const char *displayType);
|
|
|
|
/// Removes the specified camera from the collection.
|
|
/**
|
|
* @param cameraName the char * name of the camera to be removed
|
|
* @return bool true if the camera was successfully removed; false,
|
|
* otherwise.
|
|
**/
|
|
AREXPORT virtual bool removeCamera(const char *cameraName);
|
|
|
|
/// Adds the specified command to the camera.
|
|
/**
|
|
* @param cameraName the char * name of the camera to which the
|
|
* command is to be added. The camera must have already been
|
|
* installed in the collection via the addCamera() method.
|
|
* @param command the char * identifier of the command that is being
|
|
* added. Common commands (currently recognized by MobileEyes)
|
|
* are defined in ArCameraCommands.
|
|
* @param cameraCommandName the corresponding char * command
|
|
* (i.e. network packet) name that is actually handled by the
|
|
* camera. The cameraCommandName must be non-NULL and unique
|
|
* across all robot cameras.
|
|
* @param requestInterval the int number of milliseconds between
|
|
* client requests for repeating commands; if -1, then the
|
|
* command is not repeating.
|
|
* @return bool true if the command was successfully added;
|
|
* false if an error occurred.
|
|
**/
|
|
AREXPORT virtual bool addCameraCommand(const char *cameraName,
|
|
const char *command,
|
|
const char *cameraCommandName,
|
|
int requestInterval = -1);
|
|
|
|
|
|
/// Removes the specified command from the camera.
|
|
/**
|
|
* @param cameraName the char * name of the camera from which the
|
|
* command is to be removed.
|
|
* @param command the char * identifier of the command that is being
|
|
* removed.
|
|
* @return bool true if the command was successfully removed;
|
|
* false if an error occurred.
|
|
**/
|
|
AREXPORT virtual bool removeCameraCommand(const char *cameraName,
|
|
const char *command);
|
|
|
|
|
|
/// Adds the specified parameter to the camera.
|
|
/**
|
|
* @param cameraName the char * name of the camera to which the
|
|
* parameter is to be added. The camera must have already been
|
|
* installed in the collection via the addCamera() method.
|
|
* @param source the ArCameraParameterSource * that is to be notified
|
|
* when the parameter value is changed; if NULL, then no notification
|
|
* @param param the ArConfigArg parameter to be added; the parameter
|
|
* name must be unique for this camera. (Parameter names may be
|
|
* reused across different cameras though.)
|
|
* @return bool true if the parameter was successfully added to the
|
|
* camera; false if an error occurred
|
|
**/
|
|
AREXPORT virtual bool addParameter(const char *cameraName,
|
|
ArCameraParameterSource *source,
|
|
const ArConfigArg ¶m);
|
|
|
|
|
|
/// Removes the specified parameter from the camera.
|
|
/**
|
|
* @param cameraName the char * name of the camera from which the
|
|
* parameter is to be removed.
|
|
* @param paramName the char * name of the parameter to be removed
|
|
* @return bool true if the parameter was successfully removed from the
|
|
* camera; false if an error occurred
|
|
**/
|
|
AREXPORT virtual bool removeParameter(const char *cameraName,
|
|
const char *paramName);
|
|
|
|
// ---------------------------------------------------------------------------
|
|
|
|
/// Returns the names of the cameras that are in the collection.
|
|
/**
|
|
* @param outList the std::list<std::string> into which the names are output;
|
|
* any previous contents of the outList are cleared.
|
|
**/
|
|
AREXPORT virtual void getCameraNames(std::list<std::string> &outList);
|
|
|
|
|
|
/// Returns the type of the specified camera.
|
|
/**
|
|
* @param cameraName the unique char * name of the camera
|
|
* @return char * the type of the specified camera; NULL if the camera was
|
|
* not found in the collection
|
|
**/
|
|
AREXPORT virtual const char *getCameraType(const char *cameraName);
|
|
|
|
/// Returns the display name of the specified camera.
|
|
/**
|
|
* @param cameraName the unique char * name of the camera
|
|
* @return char * the string to be displayed as the name of the specified camera;
|
|
* NULL if the camera was not found in the collection
|
|
**/
|
|
AREXPORT virtual const char *getDisplayName(const char *cameraName);
|
|
|
|
/// Returns the display type of the specified camera.
|
|
/**
|
|
* @param cameraName the unique char * name of the camera
|
|
* @return char * the string to be displayed as the type of the specified camera;
|
|
* NULL if the camera was not found in the collection
|
|
**/
|
|
AREXPORT virtual const char *getDisplayType(const char *cameraName);
|
|
|
|
// ---------------------------------------------------------------------------
|
|
|
|
/// Returns the generic commands that are supported by the specified camera.
|
|
/**
|
|
* @param cameraName the unique char * name of the camera
|
|
* @param outList the std::list<std::string> into which the commands are output;
|
|
* any previous contents of the outList are cleared.
|
|
**/
|
|
AREXPORT virtual void getCameraCommands(const char *cameraName,
|
|
std::list<std::string> &outList);
|
|
|
|
/// Returns the specific camera command (/ network packet) name for the generic command.
|
|
/**
|
|
* @param cameraName the unique char * name of the camera
|
|
* @param command the char * name of the generic command to be retrieved
|
|
* @return char * the unique command (or network packet) name for the generic
|
|
* command on the specified camera; NULL, if the camera does not support the
|
|
* generic command
|
|
**/
|
|
AREXPORT virtual const char *getCommandName(const char *cameraName,
|
|
const char *command);
|
|
|
|
/// Returns the default request interval for the specified camera command.
|
|
/**
|
|
* @param cameraName the unique char * name of the camera
|
|
* @param command the char * name of the generic command
|
|
* @return int the default number of milliseconds between command requests;
|
|
* if -1, then the command is not for refreshing data
|
|
**/
|
|
AREXPORT virtual int getRequestInterval(const char *cameraName,
|
|
const char *command);
|
|
|
|
// ---------------------------------------------------------------------------
|
|
|
|
/// Returns the names of the parameters for the specified camera.
|
|
/**
|
|
* @param cameraName the unique char * name of the camera
|
|
* @param outList the std::list<std::string> into which the parameter names are
|
|
* output; any previous contents of the outList are cleared.
|
|
**/
|
|
AREXPORT virtual void getParameterNames(const char *cameraName,
|
|
std::list<std::string> &outList);
|
|
|
|
/// Returns the specified camera parameter.
|
|
/**
|
|
* @param cameraName the unique char * name of the camera
|
|
* @param parameterName the unique char * name of the parameter to be retrieved
|
|
* @param paramOut the ArConfigArg into which the parameter is copied
|
|
* @return bool true if the parameter was successfully found; false, otherwise.
|
|
**/
|
|
AREXPORT virtual bool getParameter(const char *cameraName,
|
|
const char *parameterName,
|
|
ArConfigArg ¶mOut);
|
|
|
|
/// Updates the specified camera parameter.
|
|
/**
|
|
* @param cameraName the unique char * name of the camera
|
|
* @param param the ArConfigArg to be set; the parameter must have been
|
|
* previously added to the camera with the addParameter() method
|
|
* @return bool true if the parameter was found and set; false, otherwise.
|
|
**/
|
|
AREXPORT virtual bool setParameter(const char *cameraName,
|
|
const ArConfigArg ¶m);
|
|
|
|
// ---------------------------------------------------------------------------
|
|
|
|
/// Returns whether the specified camera is contained in the collection.
|
|
AREXPORT virtual bool exists(const char *cameraName);
|
|
|
|
/// Returns whether the specified command is defined for a particular camera.
|
|
AREXPORT virtual bool exists(const char *cameraName,
|
|
const char *command);
|
|
|
|
/// Returns whether the specified parameter has been defined for a particular camera.
|
|
AREXPORT virtual bool parameterExists(const char *cameraName,
|
|
const char *paramName);
|
|
|
|
// ---------------------------------------------------------------------------
|
|
|
|
/// Adds a callback to be invoked when the camera collection has been modified.
|
|
/**
|
|
* @param functor the ArFunctor * to be invoked when the collection has been
|
|
* modified; must be non-NULL
|
|
* @param position the ArListPos::Pos at which to put the callback
|
|
* (beginning or end)
|
|
* @return bool true if the callback was succesfully added; false, otherwise.
|
|
**/
|
|
AREXPORT virtual bool addModifiedCB(ArFunctor *functor,
|
|
ArListPos::Pos position = ArListPos::LAST);
|
|
|
|
/// Removes a callback from the modified notification list.
|
|
/**
|
|
* @param functor the ArFunctor * to be removed from the notification list
|
|
* @return bool true if the callback was succesfully removed; false, otherwise.
|
|
**/
|
|
AREXPORT virtual bool removeModifiedCB(ArFunctor *functor);
|
|
|
|
|
|
/// Starts an update to the collection.
|
|
/**
|
|
* This method may be used when multiple changes are being made to the collection.
|
|
* While an update is in progress, the modified callbacks will not be invoked.
|
|
* The endUpdate() method should be called after all of the changes are complete
|
|
* (and then the modified callbacks <em>will</em> be invoked).
|
|
**/
|
|
AREXPORT virtual void startUpdate();
|
|
|
|
/// Ends an update to the collection.
|
|
/**
|
|
* A call to startUpdate() must eventually be followed by a call to endUpdate().
|
|
**/
|
|
AREXPORT virtual void endUpdate();
|
|
|
|
|
|
// ---------------------------------------------------------------------------
|
|
|
|
/// Lock the collection
|
|
int lock() {
|
|
return (myMutex.lock());
|
|
}
|
|
|
|
/// Try to lock the collection without blocking
|
|
int tryLock() {
|
|
return(myMutex.tryLock());
|
|
}
|
|
|
|
/// Unlock the collection
|
|
int unlock() {
|
|
return(myMutex.unlock());
|
|
}
|
|
|
|
|
|
// -----------------------------------------------------------------------------
|
|
protected:
|
|
|
|
/// Information regarding a particular camera command.
|
|
struct CommandInfo {
|
|
|
|
/// Generic name of the command.
|
|
std::string myCommand;
|
|
/// Unique name of the corresponding command (or packet) for this camera.
|
|
std::string myCameraCommandName;
|
|
/// Default number of milliseconds between command requests.
|
|
int myRequestInterval;
|
|
|
|
/// Constructor
|
|
CommandInfo();
|
|
/// Destructor
|
|
~CommandInfo();
|
|
|
|
}; // end struct CommandInfo
|
|
|
|
|
|
/// Information regarding a particular camera parameter.
|
|
struct ParamInfo {
|
|
|
|
/// Source of the parameter (to be notified when the parameter changes)
|
|
ArCameraParameterSource *mySource;
|
|
/// The parameter
|
|
ArConfigArg myParam;
|
|
|
|
/// Constructor
|
|
ParamInfo();
|
|
/// Destructor
|
|
~ParamInfo();
|
|
|
|
}; // end struct ParamInfo
|
|
|
|
|
|
/// Information regarding a single camera.
|
|
struct CameraInfo {
|
|
|
|
/// Unique name of the camera
|
|
std::string myCameraName;
|
|
/// Type of the camera
|
|
std::string myCameraType;
|
|
/// String displayed for the name of the camera
|
|
std::string myDisplayName;
|
|
/// String displayed for the type of the camera
|
|
std::string myDisplayType;
|
|
/// Map of generic command names to the specific camera command info
|
|
std::map<std::string, CommandInfo*> myCommandToInfoMap;
|
|
/// Map of parameter names to the related info (including the actual parameter value)
|
|
std::map<std::string, ParamInfo*> myParamToInfoMap;
|
|
|
|
/// Constructor
|
|
CameraInfo();
|
|
/// Destructor
|
|
~CameraInfo();
|
|
|
|
}; // end struct CameraInfo
|
|
|
|
|
|
/// Returns a pointer to the CameraInfo for the specified camera.
|
|
CameraInfo *findCameraInfo(const char *cameraName);
|
|
|
|
/// Returns a pointer to the CommandInfo for the specified generic command.
|
|
CommandInfo *findCommandInfo(const char *cameraName,
|
|
const char *commandName);
|
|
|
|
/// Returns a pointer to the ParamInfo for the specified parameter.
|
|
ParamInfo *findParamInfo(const char *cameraName,
|
|
const char *paramName);
|
|
|
|
/// Sets an indication that the collection has been modified.
|
|
void setModified();
|
|
|
|
/// Invokes each of the callbacks when the collection has been modified.
|
|
void notifyModifiedListeners();
|
|
|
|
private:
|
|
/// Disabled copy ctor
|
|
ArCameraCollection(const ArCameraCollection &);
|
|
/// Disabled assignment operator
|
|
ArCameraCollection &operator=(const ArCameraCollection &);
|
|
|
|
protected:
|
|
|
|
/// Mutex for multi-threaded access
|
|
ArMutex myMutex;
|
|
/// Map of camera names to the associated camera information
|
|
std::map<std::string, CameraInfo*> myCameraToInfoMap;
|
|
/// Whether updates are currently enabled
|
|
bool myIsUpdatesEnabled;
|
|
/// Whether the collection has been modified (since the last notification)
|
|
bool myIsModified;
|
|
/// List of callbacks to be notified when the collection is modified
|
|
std::list<ArFunctor *> myModifiedCBList;
|
|
|
|
}; // end class ArCameraCollection
|
|
|
|
// -----------------------------------------------------------------------------
|
|
|
|
/// Interface for items that add information to the camera collection.
|
|
/**
|
|
* ArCameraCollectionItem is a simple interface whose primary purpose is to
|
|
* identify classes that support some aspect of a camera's functionality.
|
|
* It defines two methods: one to identify the associated camera, and one
|
|
* that adds the information about the supported functionality to the collection.
|
|
* (Note that the addToCameraCollection() method is not automatically invoked.
|
|
* Its only purpose in life is to suggest consistency between different items.)
|
|
**/
|
|
class ArCameraCollectionItem
|
|
{
|
|
public:
|
|
|
|
/// Constructor
|
|
ArCameraCollectionItem() {};
|
|
/// Destructor
|
|
virtual ~ArCameraCollectionItem() {};
|
|
|
|
/// Returns the name of the camera handled by this item.
|
|
virtual const char *getCameraName() = 0;
|
|
|
|
/// Adds this item to the given camera collection.
|
|
virtual void addToCameraCollection(ArCameraCollection &collection) = 0;
|
|
|
|
}; // end class ArCameraCollectionItem
|
|
|
|
// -----------------------------------------------------------------------------
|
|
|
|
/// Interface for collection items that also access the camera's parameters.
|
|
/**
|
|
* ArCameraParameterSource is a special collection item that provides the ability
|
|
* to read and modify some of the camera's parameters. In general, the
|
|
* addToCameraCollection() method should add the parameters to the collection.
|
|
* The collection will then invoke the getParameter() and setParameter() methods as
|
|
* callers make changes to the parameters; the ArCameraParameterSource is reponsible
|
|
* for propagating the changes to the camera hardware.
|
|
**/
|
|
class ArCameraParameterSource : public ArCameraCollectionItem
|
|
{
|
|
public:
|
|
|
|
/// Constructor
|
|
ArCameraParameterSource() {};
|
|
/// Destructor
|
|
~ArCameraParameterSource() {};
|
|
|
|
/// Gets the specified camera parameter.
|
|
virtual bool getParameter(const char *paramName,
|
|
ArConfigArg ¶mOut) = 0;
|
|
|
|
/// Sets the given camera parameter.
|
|
virtual bool setParameter(const ArConfigArg ¶m) = 0;
|
|
|
|
}; // end class ArCameraParameterSource
|
|
|
|
|
|
#endif // ARCAMERACOLLECTION_H
|