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>
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  */
257  virtual void setPathForExternalImages(const std::string& directory)
258  {
259  MRPT_UNUSED_PARAM(directory);
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.
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.
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"...
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.
#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: d1962bc6a Wed Jan 15 17:38:30 2020 +0100 at miƩ ene 15 17:45:11 CET 2020