Main MRPT website > C++ reference for MRPT 1.3.2
CGenericSensor.h
Go to the documentation of this file.
1 /* +---------------------------------------------------------------------------+
2  | Mobile Robot Programming Toolkit (MRPT) |
3  | http://www.mrpt.org/ |
4  | |
5  | Copyright (c) 2005-2015, Individual contributors, see AUTHORS file |
6  | See: http://www.mrpt.org/Authors - All rights reserved. |
7  | Released under BSD License. See details in http://www.mrpt.org/License |
8  +---------------------------------------------------------------------------+ */
9 
10 #ifndef CGenericSensor_H
11 #define CGenericSensor_H
12 
14 #include <mrpt/utils/CUncopiable.h>
15 #include <mrpt/obs/CObservation.h>
17 #include <mrpt/system/threads.h>
18 #include <map>
19 
21 #include <map>
22 
23 
24 namespace mrpt
25 {
26  /** Contains classes for various device interfaces.
27  * \ingroup mrpt_hwdrivers_grp
28  */
29  namespace hwdrivers
30  {
32 
33  /** A structure for runtime ID class type information in the context of hwdrivers::CGenericSensor.
34  */
36  {
37  const char* className; //!< Class name
38  CGenericSensor* (*ptrCreateObject)(); //!< Pointer to class constructor
39  };
40 
42 
43  /** A generic interface for a wide-variety of sensors designed to be used in the application RawLogGrabber.
44  * Derived classes should be designed with the following execution flow in mind:
45  * - Object constructor
46  * - CGenericSensor::loadConfig: The following parameters are common to all sensors in rawlog-grabber (they are automatically loaded by rawlog-grabber) - see each class documentation for additional parameters:
47  * - "process_rate": (Mandatory) The rate in Hertz (Hz) at which the sensor thread should invoke "doProcess".
48  * - "max_queue_len": (Optional) The maximum number of objects in the observations queue (default is 200). If overflow occurs, an error message will be issued at run-time.
49  * - "grab_decimation": (Optional) Grab only 1 out of N observations captured by the sensor (default is 1, i.e. do not decimate).
50  * - CGenericSensor::initialize
51  * - CGenericSensor::doProcess
52  * - CGenericSensor::getObservations
53  *
54  * Notice that there are helper methods for managing the internal list of objects (see CGenericSensor::appendObservation).
55  *
56  * <b>Class Factory:</b> This is also a factory of derived classes, through the static method CGenericSensor::createSensor
57  *
58  *
59  * For more details on RawLogGrabber refer to the wiki page:
60  * http://www.mrpt.org/Application:RawLogGrabber
61  * \ingroup mrpt_hwdrivers_grp
62  */
64  {
65  public:
66  virtual const mrpt::hwdrivers::TSensorClassId* GetRuntimeClass() const = 0;
67 
68  typedef std::multimap< mrpt::system::TTimeStamp, mrpt::utils::CSerializablePtr > TListObservations;
69  typedef std::pair< mrpt::system::TTimeStamp, mrpt::utils::CSerializablePtr > TListObsPair;
70 
71  /** The current state of the sensor
72  * \sa CGenericSensor::getState
73  */
75  {
76  ssInitializing = 0,
78  ssError
79  };
80 
81  /** The current state of the sensor */
82  inline TSensorState getState() const { return m_state; }
83 
84  inline double getProcessRate() const { return m_process_rate; }
85 
86  inline std::string getSensorLabel() const { return m_sensorLabel; }
87  inline void setSensorLabel(const std::string& sensorLabel) { m_sensorLabel=sensorLabel; }
88 
89  /** Enable or disable extra debug info dumped to std::cout during sensor operation.
90  * Default: disabled unless the environment variable "MRPT_HWDRIVERS_VERBOSE" is set to "1" during object creation.
91  */
92  inline void enableVerbose(bool enabled=true) { m_verbose=enabled; }
93  inline bool isVerboseEnabled() const { return m_verbose; }
94 
95  /** Register a class into the internal list of "CGenericSensor" descendents.
96  * Used internally in the macros DEFINE_GENERIC_SENSOR, etc...
97  *
98  * Can be used as "CGenericSensor::registerClass( SENSOR_CLASS_ID(CMySensor) );" if
99  * building custom sensors outside mrpt libraries in user code.
100  */
101  static void registerClass(const TSensorClassId* pNewClass);
102 
103  private:
104  synch::CCriticalSection m_csObjList; //!< The critical section for m_objList
105  TListObservations m_objList; //!< The queue of objects to be returned by getObservations
106 
107  /** Used in registerClass */
108  static std::map< std::string , const TSensorClassId *> m_knownClasses;
109 
110 
111  protected:
112  /** @name Common settings to any sensor, loaded in "loadConfig"
113  @{ */
114 
115  double m_process_rate; //!< See CGenericSensor
116  size_t m_max_queue_len; //!< See CGenericSensor
117  size_t m_grab_decimation; //!< If set to N>=2, only 1 out of N observations will be saved to m_objList.
118  std::string m_sensorLabel; //!< See CGenericSensor
119 
120  /** @} */
121 
122  size_t m_grab_decimation_counter; //!< Used when "m_grab_decimation" is enabled
123 
125  bool m_verbose;
126 
127  // === Data for off-rawlog file external image directory ====
128  // Only used by a few sensor classes.
129  std::string m_path_for_external_images; //!< The path where to save off-rawlog images: empty means save images embedded in the rawlog.
130  std::string m_external_images_format; //!< The extension ("jpg","gif","png",...) that determines the format of images saved externally \sa setPathForExternalImages
131  unsigned int m_external_images_jpeg_quality; //!< For JPEG images, the quality (default=95%).
132  // ======================================
133 
134  /** This method must be called by derived classes to enqueue a new observation in the list to be returned by getObservations.
135  * Passed objects must be created in dynamic memory and a smart pointer passed. Example of creation:
136  \code
137  mrpt::obs::CObservationGPSPtr o = CObservationGPSPtr( new CObservationGPS() );
138  o-> .... // Set data
139  appendObservation(o);
140  \endcode
141  * If several observations are passed at once in the vector, they'll be considered as a block regarding the grabbing decimation factor.
142  */
143  void appendObservations( const std::vector<mrpt::utils::CSerializablePtr> &obj);
144 
145  //! Like appendObservations() but for just one observation.
147  {
148  appendObservations(std::vector<mrpt::utils::CSerializablePtr>(1, obj));
149  }
150 
151  /** Auxiliary structure used for CSerializable runtime class ID support.
152  */
154  {
156  {
158  }
159  };
160 
161  /** Loads specific configuration for the device from a given source of configuration parameters, for example, an ".ini" file, loading from the section "[iniSection]" (see utils::CConfigFileBase and derived classes)
162  * \exception This method must throw an exception with a descriptive message if some critical parameter is missing or has an invalid value.
163  */
164  virtual void loadConfig_sensorSpecific(
165  const mrpt::utils::CConfigFileBase &configSource,
166  const std::string &section ) = 0;
167 
168  public:
169  /** Creates a sensor by a name of the class.
170  * Typically the user may want to create a smart pointer around the returned pointer, whis is made with:
171  * \code
172  * CGenericSensorPtr sensor = CGenericSensorPtr( CGenericSensor::createSensor("XXX") );
173  * \endcode
174  * \return A pointer to a new class, or NULL if class name is unknown.
175  */
176  static CGenericSensor* createSensor(const std::string &className);
177 
178  /** Just like createSensor, but returning a smart pointer to the newly created sensor object. */
179  static inline CGenericSensorPtr createSensorPtr(const std::string &className)
180  {
181  return CGenericSensorPtr(createSensor(className));
182  }
183 
184  /** Constructor */
185  CGenericSensor( );
186 
187  /** Destructor */
188  virtual ~CGenericSensor();
189 
190  /** Loads the generic settings common to any sensor (See CGenericSensor), then call to "loadConfig_sensorSpecific"
191  * \exception This method throws an exception with a descriptive message if some critical parameter is missing or has an invalid value.
192  */
193  void loadConfig(
194  const mrpt::utils::CConfigFileBase &configSource,
195  const std::string &section );
196 
197  /** This method can or cannot be implemented in the derived class, depending on the need for it.
198  * \exception This method must throw an exception with a descriptive message if some critical error is found.
199  */
200  virtual void initialize()
201  { } // Default method does nothing.
202 
203  /** This method will be invoked at a minimum rate of "process_rate" (Hz)
204  * \exception This method must throw an exception with a descriptive message if some critical error is found.
205  */
206  virtual void doProcess() = 0;
207 
208  /** Returns a list of enqueued objects, emptying it (thread-safe). The objects must be freed by the invoker.
209  */
210  void getObservations( TListObservations &lstObjects );
211 
212  /** Set the path where to save off-rawlog image files (will be ignored in those sensors where this is not applicable).
213  * An empty string (the default value at construction) means to save images embedded in the rawlog, instead of on separate files.
214  * \exception std::exception If the directory doesn't exists and cannot be created.
215  */
216  virtual void setPathForExternalImages( const std::string &directory ) {
217  MRPT_UNUSED_PARAM(directory);
218  // In this base class, the default is to ignore image paths.
219  }
220 
221  /** Set the extension ("jpg","gif","png",...) that determines the format of images saved externally
222  * The default is "jpg".
223  * \sa setPathForExternalImages, setExternalImageJPEGQuality
224  */
225  void setExternalImageFormat( const std::string &ext ) {
226  m_external_images_format = ext;
227  }
228 
229  /** The quality of JPEG compression, when external images is enabled and the format is "jpg". \sa setExternalImageFormat */
230  void setExternalImageJPEGQuality(const unsigned int quality) {
231  m_external_images_jpeg_quality = quality;
232  }
233  unsigned int getExternalImageJPEGQuality()const {
234  return m_external_images_jpeg_quality;
235  }
236 
237  public:
239 
240  }; // end of class
241 
242 
243  #define SENSOR_CLASS_ID(class_name) \
244  static_cast<const mrpt::hwdrivers::TSensorClassId*>(& mrpt::hwdrivers::class_name::class##class_name)
245 
246  #define SENSOR_IS_CLASS( ptrObj, class_name ) (ptrObj->GetRuntimeClass()==SENSOR_CLASS_ID(class_name))
247 
248 
249  /** This declaration must be inserted in all CGenericSensor classes definition, within the class declaration.
250  */
251  #define DEFINE_GENERIC_SENSOR(class_name) \
252  protected: \
253  static mrpt::hwdrivers::CGenericSensor::CLASSINIT_GENERIC_SENSOR _init_##class_name;\
254  public: \
255  static mrpt::hwdrivers::TSensorClassId class##class_name; \
256  virtual const mrpt::hwdrivers::TSensorClassId* GetRuntimeClass() const; \
257  static mrpt::hwdrivers::CGenericSensor* CreateObject(); \
258  static void doRegister() \
259  { CGenericSensor::registerClass( SENSOR_CLASS_ID( class_name ) ); }
260 
261  /** This must be inserted in all CGenericSensor classes implementation files:
262  */
263  #define IMPLEMENTS_GENERIC_SENSOR(class_name, NameSpace) \
264  mrpt::hwdrivers::CGenericSensor* NameSpace::class_name::CreateObject() \
265  { return static_cast<hwdrivers::CGenericSensor*>( new NameSpace::class_name ); } \
266  mrpt::hwdrivers::TSensorClassId NameSpace::class_name::class##class_name = { \
267  #class_name, NameSpace::class_name::CreateObject }; \
268  const mrpt::hwdrivers::TSensorClassId* NameSpace::class_name::GetRuntimeClass() const \
269  { return SENSOR_CLASS_ID(class_name); }
270 
271 
272  } // end of namespace
273 } // end of namespace
274 
275 #endif
TListObservations m_objList
The queue of objects to be returned by getObservations.
A generic interface for a wide-variety of sensors designed to be used in the application RawLogGrabbe...
size_t m_grab_decimation_counter
Used when "m_grab_decimation" is enabled.
This class provides simple critical sections functionality.
double m_process_rate
See CGenericSensor.
synch::CCriticalSection m_csObjList
The critical section for m_objList.
std::multimap< mrpt::system::TTimeStamp, mrpt::utils::CSerializablePtr > TListObservations
virtual void setPathForExternalImages(const std::string &directory)
Set the path where to save off-rawlog image files (will be ignored in those sensors where this is not...
#define MRPT_MAKE_ALIGNED_OPERATOR_NEW
Definition: memory.h:112
void BASE_IMPEXP registerClass(const mrpt::utils::TRuntimeClassId *pNewClass)
Register a class into the MRPT internal list of "CSerializable" descendents.
std::string m_sensorLabel
See CGenericSensor.
static void registerClass(const TSensorClassId *pNewClass)
Register a class into the internal list of "CGenericSensor" descendents.
void enableVerbose(bool enabled=true)
Enable or disable extra debug info dumped to std::cout during sensor operation.
static std::map< std::string, const TSensorClassId * > m_knownClasses
Used in registerClass.
unsigned int getExternalImageJPEGQuality() const
This class allows loading and storing values and vectors of different types from a configuration text...
const char * className
Class name.
#define MRPT_UNUSED_PARAM(a)
Can be used to avoid "not used parameters" warnings from the compiler.
CLASSINIT_GENERIC_SENSOR(const TSensorClassId *pNewClass)
TSensorState getState() const
The current state of the sensor.
The base class of classes that cannot be copied: compile-time errors will be issued on any copy opera...
Definition: CUncopiable.h:30
void setExternalImageFormat(const std::string &ext)
Set the extension ("jpg","gif","png",...) that determines the format of images saved externally The d...
size_t m_max_queue_len
See CGenericSensor.
stlplus::smart_ptr< CGenericSensor > CGenericSensorPtr
void setExternalImageJPEGQuality(const unsigned int quality)
The quality of JPEG compression, when external images is enabled and the format is "jpg"...
struct BASE_IMPEXP CSerializablePtr
Definition: CStream.h:24
This is the global namespace for all Mobile Robot Programming Toolkit (MRPT) libraries.
size_t m_grab_decimation
If set to N>=2, only 1 out of N observations will be saved to m_objList.
std::pair< mrpt::system::TTimeStamp, mrpt::utils::CSerializablePtr > TListObsPair
std::string getSensorLabel() const
unsigned int m_external_images_jpeg_quality
For JPEG images, the quality (default=95%).
class HWDRIVERS_IMPEXP CGenericSensor
void setSensorLabel(const std::string &sensorLabel)
TSensorState
The current state of the sensor.
static CGenericSensorPtr createSensorPtr(const std::string &className)
Just like createSensor, but returning a smart pointer to the newly created sensor object...
virtual void initialize()
This method can or cannot be implemented in the derived class, depending on the need for it...
void appendObservation(const mrpt::utils::CSerializablePtr &obj)
Like appendObservations() but for just one observation.
std::string m_external_images_format
The extension ("jpg","gif","png",...) that determines the format of images saved externally.
#define HWDRIVERS_IMPEXP
Auxiliary structure used for CSerializable runtime class ID support.
std::string m_path_for_external_images
The path where to save off-rawlog images: empty means save images embedded in the rawlog...
A structure for runtime ID class type information in the context of hwdrivers::CGenericSensor.



Page generated by Doxygen 1.8.12 for MRPT 1.3.2 SVN: at Thu Nov 10 13:46:27 UTC 2016