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  /** Loads specific configuration for the device from a given source of
185  * configuration parameters, for example, an ".ini" file, loading from the
186  * section "[iniSection]" (see config::CConfigFileBase and derived classes)
187  * \exception This method must throw an exception with a descriptive
188  * message if some critical parameter is missing or has an invalid value.
189  */
190  virtual void loadConfig_sensorSpecific(
191  const mrpt::config::CConfigFileBase& configSource,
192  const std::string& section) = 0;
193 
194  public:
195  /** Creates a sensor by a name of the class.
196  * Typically the user may want to create a smart pointer around the
197  * returned pointer, whis is made with:
198  * \code
199  * CGenericSensor::Ptr sensor = CGenericSensor::Ptr(
200  * CGenericSensor::createSensor("XXX") );
201  * \endcode
202  * \return A pointer to a new class, or nullptr if class name is unknown.
203  */
204  static CGenericSensor* createSensor(const std::string& className);
205 
206  /** Just like createSensor, but returning a smart pointer to the newly
207  * created sensor object. */
209  const std::string& className)
210  {
211  return CGenericSensor::Ptr(createSensor(className));
212  }
213 
214  /** Constructor */
215  CGenericSensor();
216 
217  CGenericSensor(const CGenericSensor&) = delete;
218  CGenericSensor& operator=(const CGenericSensor&) = delete;
219 
220  /** Destructor */
221  virtual ~CGenericSensor();
222 
223  /** Loads the generic settings common to any sensor (See CGenericSensor),
224  * then call to "loadConfig_sensorSpecific"
225  * \exception This method throws an exception with a descriptive message
226  * if some critical parameter is missing or has an invalid value.
227  */
228  void loadConfig(
229  const mrpt::config::CConfigFileBase& configSource,
230  const std::string& section);
231 
232  /** This method can or cannot be implemented in the derived class, depending
233  * on the need for it.
234  * \exception This method must throw an exception with a descriptive
235  * message if some critical error is found.
236  */
237  virtual void initialize() {} // Default method does nothing.
238  /** This method will be invoked at a minimum rate of "process_rate" (Hz)
239  * \exception This method must throw an exception with a descriptive
240  * message if some critical error is found.
241  */
242  virtual void doProcess() = 0;
243 
244  /** Returns a list of enqueued objects, emptying it (thread-safe). The
245  * objects must be freed by the invoker.
246  */
247  void getObservations(TListObservations& lstObjects);
248 
249  /** Set the path where to save off-rawlog image files (will be ignored in
250  * those sensors where this is not applicable).
251  * An empty string (the default value at construction) means to save
252  * images embedded in the rawlog, instead of on separate files.
253  * \exception std::exception If the directory doesn't exists and cannot be
254  * created.
255  */
256  virtual void setPathForExternalImages(const std::string& directory)
257  {
258  MRPT_UNUSED_PARAM(directory);
259  // In this base class, the default is to ignore image paths.
260  }
261 
262  /** Set the extension ("jpg","gif","png",...) that determines the format of
263  * images saved externally
264  * The default is "jpg".
265  * \sa setPathForExternalImages, setExternalImageJPEGQuality
266  */
268  {
270  }
271 
272  /** The quality of JPEG compression, when external images is enabled and the
273  * format is "jpg". \sa setExternalImageFormat */
274  void setExternalImageJPEGQuality(const unsigned int quality)
275  {
277  }
278  unsigned int getExternalImageJPEGQuality() const
279  {
281  }
282 
283  public:
284 }; // end of class
285 
286 static_assert(
287  !std::is_copy_constructible_v<CGenericSensor> &&
288  !std::is_copy_assignable_v<CGenericSensor>,
289  "Copy Check");
290 
291 #define SENSOR_CLASS_ID(class_name) \
292  static_cast<const mrpt::hwdrivers::TSensorClassId*>( \
293  &mrpt::hwdrivers::class_name::class##class_name)
294 
295 #define SENSOR_IS_CLASS(ptrObj, class_name) \
296  (ptrObj->GetRuntimeClass() == SENSOR_CLASS_ID(class_name))
297 
298 /** This declaration must be inserted in all CGenericSensor classes definition,
299  * within the class declaration.
300  */
301 #define DEFINE_GENERIC_SENSOR(class_name) \
302  public: \
303  static mrpt::hwdrivers::TSensorClassId class##class_name; \
304  const mrpt::hwdrivers::TSensorClassId* GetRuntimeClass() const override; \
305  static mrpt::hwdrivers::CGenericSensor* CreateObject(); \
306  static void doRegister() \
307  { \
308  CGenericSensor::registerClass(SENSOR_CLASS_ID(class_name)); \
309  }
310 
311 /** This must be inserted in all CGenericSensor classes implementation files:
312  */
313 #define IMPLEMENTS_GENERIC_SENSOR(class_name, NameSpace) \
314  mrpt::hwdrivers::CGenericSensor* NameSpace::class_name::CreateObject() \
315  { \
316  return static_cast<hwdrivers::CGenericSensor*>( \
317  new NameSpace::class_name); \
318  } \
319  mrpt::hwdrivers::TSensorClassId NameSpace::class_name::class##class_name = \
320  {#class_name, NameSpace::class_name::CreateObject}; \
321  const mrpt::hwdrivers::TSensorClassId* \
322  NameSpace::class_name::GetRuntimeClass() const \
323  { \
324  return SENSOR_CLASS_ID(class_name); \
325  }
326 
327 } // namespace hwdrivers
328 } // 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.
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.
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: 1de0e027c Sat Sep 14 16:15:22 2019 +0200 at sáb sep 14 16:20:14 CEST 2019