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



Page generated by Doxygen 1.8.14 for MRPT 2.0.2 Git: 9efc2a654 Mon Apr 6 11:24:47 2020 +0200 at lun abr 6 11:30:12 CEST 2020