Main MRPT website > C++ reference for MRPT 1.4.0
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-2016, 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.
146  void appendObservation( const mrpt::utils::CSerializablePtr &obj)
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
mrpt::hwdrivers::CGenericSensor::setExternalImageJPEGQuality
void setExternalImageJPEGQuality(const unsigned int quality)
The quality of JPEG compression, when external images is enabled and the format is "jpg".
Definition: CGenericSensor.h:230
mrpt::hwdrivers::CGenericSensor::m_knownClasses
static std::map< std::string, const TSensorClassId * > m_knownClasses
Used in registerClass.
Definition: CGenericSensor.h:108
mrpt::hwdrivers::TSensorClassId::className
const char * className
Class name.
Definition: CGenericSensor.h:37
mrpt::hwdrivers::CGenericSensor::TListObsPair
std::pair< mrpt::system::TTimeStamp, mrpt::utils::CSerializablePtr > TListObsPair
Definition: CGenericSensor.h:69
mrpt::hwdrivers::CGenericSensor::getState
TSensorState getState() const
The current state of the sensor
Definition: CGenericSensor.h:82
mrpt::hwdrivers::CGenericSensor::TListObservations
std::multimap< mrpt::system::TTimeStamp, mrpt::utils::CSerializablePtr > TListObservations
Definition: CGenericSensor.h:68
mrpt::hwdrivers::CGenericSensor::CLASSINIT_GENERIC_SENSOR
Auxiliary structure used for CSerializable runtime class ID support.
Definition: CGenericSensor.h:153
mrpt::hwdrivers::CGenericSensor::createSensorPtr
static CGenericSensorPtr createSensorPtr(const std::string &className)
Just like createSensor, but returning a smart pointer to the newly created sensor object.
Definition: CGenericSensor.h:179
threads.h
CObservation.h
mrpt::hwdrivers::CGenericSensor::m_path_for_external_images
std::string m_path_for_external_images
The path where to save off-rawlog images: empty means save images embedded in the rawlog.
Definition: CGenericSensor.h:129
MRPT_UNUSED_PARAM
#define MRPT_UNUSED_PARAM(a)
Can be used to avoid "not used parameters" warnings from the compiler.
Definition: mrpt_macros.h:290
mrpt::hwdrivers::CGenericSensor::ssWorking
Definition: CGenericSensor.h:77
mrpt::hwdrivers::CGenericSensor::enableVerbose
void enableVerbose(bool enabled=true)
Enable or disable extra debug info dumped to std::cout during sensor operation.
Definition: CGenericSensor.h:92
mrpt::hwdrivers::CGenericSensor::m_max_queue_len
size_t m_max_queue_len
See CGenericSensor.
Definition: CGenericSensor.h:116
mrpt
This is the global namespace for all Mobile Robot Programming Toolkit (MRPT) libraries.
Definition: CParticleFilter.h:16
mrpt::hwdrivers::CGenericSensor::m_process_rate
double m_process_rate
See CGenericSensor.
Definition: CGenericSensor.h:115
mrpt::hwdrivers::CGenericSensor::TSensorState
TSensorState
The current state of the sensor.
Definition: CGenericSensor.h:74
mrpt::hwdrivers::CGenericSensor::m_state
TSensorState m_state
Definition: CGenericSensor.h:124
stlplus::smart_ptr
Definition: smart_ptr.hpp:228
mrpt::hwdrivers::CGenericSensor::m_grab_decimation_counter
size_t m_grab_decimation_counter
Used when "m_grab_decimation" is enabled.
Definition: CGenericSensor.h:122
mrpt::hwdrivers::CGenericSensor::getExternalImageJPEGQuality
unsigned int getExternalImageJPEGQuality() const
Definition: CGenericSensor.h:233
mrpt::hwdrivers::CGenericSensor::setPathForExternalImages
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...
Definition: CGenericSensor.h:216
mrpt::hwdrivers::CGenericSensor::m_external_images_format
std::string m_external_images_format
The extension ("jpg","gif","png",...) that determines the format of images saved externally.
Definition: CGenericSensor.h:130
mrpt::hwdrivers::CGenericSensor::m_verbose
bool m_verbose
Definition: CGenericSensor.h:125
MRPT_MAKE_ALIGNED_OPERATOR_NEW
#define MRPT_MAKE_ALIGNED_OPERATOR_NEW
Definition: memory.h:112
mrpt::hwdrivers::CGenericSensor::setExternalImageFormat
void setExternalImageFormat(const std::string &ext)
Set the extension ("jpg","gif","png",...) that determines the format of images saved externally The d...
Definition: CGenericSensor.h:225
mrpt::hwdrivers::CGenericSensor::getProcessRate
double getProcessRate() const
Definition: CGenericSensor.h:84
mrpt::hwdrivers::CGenericSensor::CLASSINIT_GENERIC_SENSOR::CLASSINIT_GENERIC_SENSOR
CLASSINIT_GENERIC_SENSOR(const TSensorClassId *pNewClass)
Definition: CGenericSensor.h:155
mrpt::synch::CCriticalSection
This class provides simple critical sections functionality.
Definition: CCriticalSection.h:31
mrpt::utils::CConfigFileBase
This class allows loading and storing values and vectors of different types from a configuration text...
Definition: CConfigFileBase.h:30
mrpt::hwdrivers::CGenericSensor::setSensorLabel
void setSensorLabel(const std::string &sensorLabel)
Definition: CGenericSensor.h:87
mrpt::utils::CUncopiable
The base class of classes that cannot be copied: compile-time errors will be issued on any copy opera...
Definition: CUncopiable.h:30
mrpt::hwdrivers::CGenericSensor::m_sensorLabel
std::string m_sensorLabel
See CGenericSensor.
Definition: CGenericSensor.h:118
mrpt::hwdrivers::CGenericSensor
A generic interface for a wide-variety of sensors designed to be used in the application RawLogGrabbe...
Definition: CGenericSensor.h:63
mrpt::hwdrivers::CGenericSensor::appendObservation
void appendObservation(const mrpt::utils::CSerializablePtr &obj)
Like appendObservations() but for just one observation.
Definition: CGenericSensor.h:146
CConfigFileBase.h
mrpt::hwdrivers::TSensorClassId
A structure for runtime ID class type information in the context of hwdrivers::CGenericSensor.
Definition: CGenericSensor.h:35
mrpt::hwdrivers::CGenericSensor::m_objList
TListObservations m_objList
The queue of objects to be returned by getObservations.
Definition: CGenericSensor.h:105
mrpt::hwdrivers::CGenericSensor::m_external_images_jpeg_quality
unsigned int m_external_images_jpeg_quality
For JPEG images, the quality (default=95%).
Definition: CGenericSensor.h:131
mrpt::hwdrivers::CGenericSensor::registerClass
static void registerClass(const TSensorClassId *pNewClass)
Register a class into the internal list of "CGenericSensor" descendents.
mrpt::hwdrivers::CGenericSensor::isVerboseEnabled
bool isVerboseEnabled() const
Definition: CGenericSensor.h:93
mrpt::utils::registerClass
void BASE_IMPEXP registerClass(const mrpt::utils::TRuntimeClassId *pNewClass)
Register a class into the MRPT internal list of "CSerializable" descendents.
mrpt::hwdrivers::CGenericSensor
class HWDRIVERS_IMPEXP CGenericSensor
Definition: CGenericSensor.h:31
mrpt::hwdrivers::CGenericSensorPtr
stlplus::smart_ptr< CGenericSensor > CGenericSensorPtr
Definition: CGenericSensor.h:41
CCriticalSection.h
CUncopiable.h
mrpt::hwdrivers::CGenericSensor::m_csObjList
synch::CCriticalSection m_csObjList
The critical section for m_objList.
Definition: CGenericSensor.h:104
HWDRIVERS_IMPEXP
#define HWDRIVERS_IMPEXP
Definition: hwdrivers_impexp.h:82
mrpt::hwdrivers::CGenericSensor::getSensorLabel
std::string getSensorLabel() const
Definition: CGenericSensor.h:86
mrpt::hwdrivers::CGenericSensor::initialize
virtual void initialize()
This method can or cannot be implemented in the derived class, depending on the need for it.
Definition: CGenericSensor.h:200
mrpt::hwdrivers::CGenericSensor::m_grab_decimation
size_t m_grab_decimation
If set to N>=2, only 1 out of N observations will be saved to m_objList.
Definition: CGenericSensor.h:117



Page generated by Doxygen 1.8.16 for MRPT 1.4.0 SVN: at Mon Oct 14 22:32:58 UTC 2019