MRPT  1.9.9
CGenericSensor.h
Go to the documentation of this file.
1 /* +------------------------------------------------------------------------+
2  | Mobile Robot Programming Toolkit (MRPT) |
3  | https://www.mrpt.org/ |
4  | |
5  | Copyright (c) 2005-2019, Individual contributors, see AUTHORS file |
6  | See: https://www.mrpt.org/Authors - All rights reserved. |
7  | Released under BSD License. See: https://www.mrpt.org/License |
8  +------------------------------------------------------------------------+ */
9 
10 #pragma once
11 
13 #include <mrpt/obs/CObservation.h>
14 #include <map>
15 #include <mutex>
16 
17 namespace mrpt
18 {
19 /** Contains classes for various device interfaces.
20  * \ingroup mrpt_hwdrivers_grp
21  */
22 namespace hwdrivers
23 {
24 class CGenericSensor;
25 
26 /** A structure for runtime ID class type information in the context of
27  * hwdrivers::CGenericSensor.
28  */
30 {
31  /** Class name */
32  const char* className;
33  /** Pointer to class constructor */
34  CGenericSensor* (*ptrCreateObject)();
35 };
36 
37 /** A generic interface for a wide-variety of sensors designed to be used in the
38  *application RawLogGrabber.
39  * Derived classes should be designed with the following execution flow in
40  *mind:
41  * - Object constructor
42  * - CGenericSensor::loadConfig: The following parameters are common to all
43  *sensors in rawlog-grabber (they are automatically loaded by rawlog-grabber) -
44  *see each class documentation for additional parameters:
45  * - "process_rate": (Mandatory) The rate in Hertz (Hz) at which the
46  *sensor
47  *thread should invoke "doProcess".
48  * - "max_queue_len": (Optional) The maximum number of objects in the
49  *observations queue (default is 200). If overflow occurs, an error message
50  *will be issued at run-time.
51  * - "grab_decimation": (Optional) Grab only 1 out of N observations
52  *captured
53  *by the sensor (default is 1, i.e. do not decimate).
54  * - CGenericSensor::initialize
55  * - CGenericSensor::doProcess
56  * - CGenericSensor::getObservations
57  *
58  * Notice that there are helper methods for managing the internal list of
59  *objects (see CGenericSensor::appendObservation).
60  *
61  * <b>Class Factory:</b> This is also a factory of derived classes, through
62  *the static method CGenericSensor::createSensor
63  *
64  *
65  * For more details on RawLogGrabber refer to the wiki page:
66  * https://www.mrpt.org/Application:RawLogGrabber
67  * \ingroup mrpt_hwdrivers_grp
68  */
70 {
71  public:
73  virtual const mrpt::hwdrivers::TSensorClassId* GetRuntimeClass() const = 0;
74 
75  using TListObservations = std::multimap<
77  using TListObsPair = std::pair<
79 
80  /** The current state of the sensor
81  * \sa CGenericSensor::getState
82  */
84  {
88  };
89 
90  /** The current state of the sensor */
91  inline TSensorState getState() const { return m_state; }
92  inline double getProcessRate() const { return m_process_rate; }
93  inline std::string getSensorLabel() const { return m_sensorLabel; }
94  inline void setSensorLabel(const std::string& sensorLabel)
95  {
96  m_sensorLabel = sensorLabel;
97  }
98 
99  /** Enable or disable extra debug info dumped to std::cout during sensor
100  * operation.
101  * Default: disabled unless the environment variable
102  * "MRPT_HWDRIVERS_VERBOSE" is set to "1" during object creation.
103  */
104  inline void enableVerbose(bool enabled = true) { m_verbose = enabled; }
105  inline bool isVerboseEnabled() const { return m_verbose; }
106  /** Register a class into the internal list of "CGenericSensor" descendents.
107  * Used internally in the macros DEFINE_GENERIC_SENSOR, etc...
108  *
109  * Can be used as "CGenericSensor::registerClass(
110  * SENSOR_CLASS_ID(CMySensor) );" if
111  * building custom sensors outside mrpt libraries in user code.
112  */
113  static void registerClass(const TSensorClassId* pNewClass);
114 
115  private:
116  /** The critical section for m_objList */
117  std::mutex m_csObjList;
118  /** The queue of objects to be returned by getObservations */
120 
121  /** Used in registerClass */
123  std::map<std::string, const TSensorClassId*>;
124  /** Access to singleton */
126 
127  protected:
128  /** @name Common settings to any sensor, loaded in "loadConfig"
129  @{ */
130 
131  /** See CGenericSensor */
132  double m_process_rate{0};
133  /** See CGenericSensor */
134  size_t m_max_queue_len{200};
135  /** If set to N>=2, only 1 out of N observations will be saved to m_objList.
136  */
137  size_t m_grab_decimation{0};
138  /** See CGenericSensor */
140 
141  /** @} */
142 
143  /** Used when "m_grab_decimation" is enabled */
145 
147  bool m_verbose{false};
148 
149  // === Data for off-rawlog file external image directory ====
150  // Only used by a few sensor classes.
151  /** The path where to save off-rawlog images: empty means save images
152  * embedded in the rawlog. */
154  /** The extension ("jpg","gif","png",...) that determines the format of
155  * images saved externally \sa setPathForExternalImages */
157  /** For JPEG images, the quality (default=95%). */
159  // ======================================
160 
161  /** This method must be called by derived classes to enqueue a new
162  observation in the list to be returned by getObservations.
163  * Passed objects must be created in dynamic memory and a smart pointer
164  passed. Example of creation:
165  \code
166  mrpt::obs::CObservationGPS::Ptr o = CObservationGPS::Ptr( new
167  CObservationGPS() );
168  o-> .... // Set data
169  appendObservation(o);
170  \endcode
171  * If several observations are passed at once in the vector, they'll be
172  considered as a block regarding the grabbing decimation factor.
173  */
174  void appendObservations(
175  const std::vector<mrpt::serialization::CSerializable::Ptr>& obj);
176 
177  //! Like appendObservations() but for just one observation.
179  {
181  std::vector<mrpt::serialization::CSerializable::Ptr>(1, obj));
182  }
183 
184  /** Auxiliary structure used for CSerializable runtime class ID support.
185  */
187  {
189  {
191  }
192  };
193 
194  /** Loads specific configuration for the device from a given source of
195  * configuration parameters, for example, an ".ini" file, loading from the
196  * section "[iniSection]" (see config::CConfigFileBase and derived classes)
197  * \exception This method must throw an exception with a descriptive
198  * message if some critical parameter is missing or has an invalid value.
199  */
200  virtual void loadConfig_sensorSpecific(
201  const mrpt::config::CConfigFileBase& configSource,
202  const std::string& section) = 0;
203 
204  public:
205  /** Creates a sensor by a name of the class.
206  * Typically the user may want to create a smart pointer around the
207  * returned pointer, whis is made with:
208  * \code
209  * CGenericSensor::Ptr sensor = CGenericSensor::Ptr(
210  * CGenericSensor::createSensor("XXX") );
211  * \endcode
212  * \return A pointer to a new class, or nullptr if class name is unknown.
213  */
214  static CGenericSensor* createSensor(const std::string& className);
215 
216  /** Just like createSensor, but returning a smart pointer to the newly
217  * created sensor object. */
219  const std::string& className)
220  {
221  return CGenericSensor::Ptr(createSensor(className));
222  }
223 
224  /** Constructor */
225  CGenericSensor();
226 
227  CGenericSensor(const CGenericSensor&) = delete;
228  CGenericSensor& operator=(const CGenericSensor&) = delete;
229 
230  /** Destructor */
231  virtual ~CGenericSensor();
232 
233  /** Loads the generic settings common to any sensor (See CGenericSensor),
234  * then call to "loadConfig_sensorSpecific"
235  * \exception This method throws an exception with a descriptive message
236  * if some critical parameter is missing or has an invalid value.
237  */
238  void loadConfig(
239  const mrpt::config::CConfigFileBase& configSource,
240  const std::string& section);
241 
242  /** This method can or cannot be implemented in the derived class, depending
243  * on the need for it.
244  * \exception This method must throw an exception with a descriptive
245  * message if some critical error is found.
246  */
247  virtual void initialize() {} // Default method does nothing.
248  /** This method will be invoked at a minimum rate of "process_rate" (Hz)
249  * \exception This method must throw an exception with a descriptive
250  * message if some critical error is found.
251  */
252  virtual void doProcess() = 0;
253 
254  /** Returns a list of enqueued objects, emptying it (thread-safe). The
255  * objects must be freed by the invoker.
256  */
257  void getObservations(TListObservations& lstObjects);
258 
259  /** Set the path where to save off-rawlog image files (will be ignored in
260  * those sensors where this is not applicable).
261  * An empty string (the default value at construction) means to save
262  * images embedded in the rawlog, instead of on separate files.
263  * \exception std::exception If the directory doesn't exists and cannot be
264  * created.
265  */
266  virtual void setPathForExternalImages(const std::string& directory)
267  {
268  MRPT_UNUSED_PARAM(directory);
269  // In this base class, the default is to ignore image paths.
270  }
271 
272  /** Set the extension ("jpg","gif","png",...) that determines the format of
273  * images saved externally
274  * The default is "jpg".
275  * \sa setPathForExternalImages, setExternalImageJPEGQuality
276  */
278  {
280  }
281 
282  /** The quality of JPEG compression, when external images is enabled and the
283  * format is "jpg". \sa setExternalImageFormat */
284  void setExternalImageJPEGQuality(const unsigned int quality)
285  {
287  }
288  unsigned int getExternalImageJPEGQuality() const
289  {
291  }
292 
293  public:
294 }; // end of class
295 
296 static_assert(
297  !std::is_copy_constructible_v<CGenericSensor> &&
298  !std::is_copy_assignable_v<CGenericSensor>,
299  "Copy Check");
300 
301 #define SENSOR_CLASS_ID(class_name) \
302  static_cast<const mrpt::hwdrivers::TSensorClassId*>( \
303  &mrpt::hwdrivers::class_name::class##class_name)
304 
305 #define SENSOR_IS_CLASS(ptrObj, class_name) \
306  (ptrObj->GetRuntimeClass() == SENSOR_CLASS_ID(class_name))
307 
308 /** This declaration must be inserted in all CGenericSensor classes definition,
309  * within the class declaration.
310  */
311 #define DEFINE_GENERIC_SENSOR(class_name) \
312  protected: \
313  static mrpt::hwdrivers::CGenericSensor::CLASSINIT_GENERIC_SENSOR \
314  _init_##class_name; \
315  \
316  public: \
317  static mrpt::hwdrivers::TSensorClassId class##class_name; \
318  const mrpt::hwdrivers::TSensorClassId* GetRuntimeClass() const override; \
319  static mrpt::hwdrivers::CGenericSensor* CreateObject(); \
320  static void doRegister() \
321  { \
322  CGenericSensor::registerClass(SENSOR_CLASS_ID(class_name)); \
323  }
324 
325 /** This must be inserted in all CGenericSensor classes implementation files:
326  */
327 #define IMPLEMENTS_GENERIC_SENSOR(class_name, NameSpace) \
328  mrpt::hwdrivers::CGenericSensor* NameSpace::class_name::CreateObject() \
329  { \
330  return static_cast<hwdrivers::CGenericSensor*>( \
331  new NameSpace::class_name); \
332  } \
333  mrpt::hwdrivers::TSensorClassId NameSpace::class_name::class##class_name = \
334  {#class_name, NameSpace::class_name::CreateObject}; \
335  const mrpt::hwdrivers::TSensorClassId* \
336  NameSpace::class_name::GetRuntimeClass() const \
337  { \
338  return SENSOR_CLASS_ID(class_name); \
339  }
340 
341 } // namespace hwdrivers
342 } // namespace mrpt
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.
double m_process_rate
See CGenericSensor.
std::map< std::string, const TSensorClassId * > registered_sensor_classes_t
Used in registerClass.
void appendObservation(const mrpt::serialization::CSerializable::Ptr &obj)
Like appendObservations() but for just one observation.
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...
std::pair< mrpt::system::TTimeStamp, mrpt::serialization::CSerializable::Ptr > TListObsPair
std::string m_sensorLabel
See CGenericSensor.
virtual void doProcess()=0
This method will be invoked at a minimum rate of "process_rate" (Hz)
void enableVerbose(bool enabled=true)
Enable or disable extra debug info dumped to std::cout during sensor operation.
void getObservations(TListObservations &lstObjects)
Returns a list of enqueued objects, emptying it (thread-safe).
std::shared_ptr< CGenericSensor > Ptr
static CGenericSensor * createSensor(const std::string &className)
Creates a sensor by a name of the class.
GLsizei GLsizei GLuint * obj
Definition: glext.h:4085
unsigned int getExternalImageJPEGQuality() const
static CGenericSensor::Ptr createSensorPtr(const std::string &className)
Just like createSensor, but returning a smart pointer to the newly created sensor object...
CGenericSensor & operator=(const CGenericSensor &)=delete
void appendObservations(const std::vector< mrpt::serialization::CSerializable::Ptr > &obj)
This method must be called by derived classes to enqueue a new observation in the list to be returned...
mrpt::Clock::time_point TTimeStamp
A system independent time type, it holds the the number of 100-nanosecond intervals since January 1...
Definition: datetime.h:40
This class allows loading and storing values and vectors of different types from a configuration text...
virtual ~CGenericSensor()
Destructor.
const char * className
Class name.
static void registerClass(const TSensorClassId *pNewClass)
Register a class into the internal list of "CGenericSensor" descendents.
static registered_sensor_classes_t & get_registered_sensor_classes()
Access to singleton.
CLASSINIT_GENERIC_SENSOR(const TSensorClassId *pNewClass)
TSensorState getState() const
The current state of the sensor.
void loadConfig(const mrpt::config::CConfigFileBase &configSource, const std::string &section)
Loads the generic settings common to any sensor (See CGenericSensor), then call to "loadConfig_sensor...
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.
GLsizei const GLchar ** string
Definition: glext.h:4116
void setExternalImageJPEGQuality(const unsigned int quality)
The quality of JPEG compression, when external images is enabled and the format is "jpg"...
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.
virtual void loadConfig_sensorSpecific(const mrpt::config::CConfigFileBase &configSource, const std::string &section)=0
Loads specific configuration for the device from a given source of configuration parameters, for example, an ".ini" file, loading from the section "[iniSection]" (see config::CConfigFileBase and derived classes)
std::string getSensorLabel() const
std::multimap< mrpt::system::TTimeStamp, mrpt::serialization::CSerializable::Ptr > TListObservations
unsigned int m_external_images_jpeg_quality
For JPEG images, the quality (default=95%).
std::mutex m_csObjList
The critical section for m_objList.
void setSensorLabel(const std::string &sensorLabel)
TSensorState
The current state of the sensor.
virtual void initialize()
This method can or cannot be implemented in the derived class, depending on the need for it...
virtual const mrpt::hwdrivers::TSensorClassId * GetRuntimeClass() const =0
std::string m_external_images_format
The extension ("jpg","gif","png",...) that determines the format of images saved externally.
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.
#define MRPT_UNUSED_PARAM(a)
Determines whether this is an X86 or AMD64 platform.
Definition: common.h:186



Page generated by Doxygen 1.8.14 for MRPT 1.9.9 Git: 8fe78517f Sun Jul 14 19:43:28 2019 +0200 at dom jul 14 20:00:11 CEST 2019