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
17#include <mrpt/system/threads.h>
18#include <map>
19
21#include <map>
22
23
24namespace 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:
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
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 {
157 CGenericSensor::registerClass(pNewClass);
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 */
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 */
186
187 /** Destructor */
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 */
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 */
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
A generic interface for a wide-variety of sensors designed to be used in the application RawLogGrabbe...
void appendObservation(const mrpt::utils::CSerializablePtr &obj)
Like appendObservations() but for just one observation.
void setSensorLabel(const std::string &sensorLabel)
std::string m_path_for_external_images
The path where to save off-rawlog images: empty means save images embedded in the rawlog.
void getObservations(TListObservations &lstObjects)
Returns a list of enqueued objects, emptying it (thread-safe).
TSensorState
The current state of the sensor.
TListObservations m_objList
The queue of objects to be returned by getObservations.
virtual void doProcess()=0
This method will be invoked at a minimum rate of "process_rate" (Hz)
size_t m_grab_decimation_counter
Used when "m_grab_decimation" is enabled.
size_t m_grab_decimation
If set to N>=2, only 1 out of N observations will be saved to m_objList.
static void registerClass(const TSensorClassId *pNewClass)
Register a class into the internal list of "CGenericSensor" descendents.
void loadConfig(const mrpt::utils::CConfigFileBase &configSource, const std::string &section)
Loads the generic settings common to any sensor (See CGenericSensor), then call to "loadConfig_sensor...
size_t m_max_queue_len
See CGenericSensor.
TSensorState getState() const
The current state of the sensor
virtual const mrpt::hwdrivers::TSensorClassId * GetRuntimeClass() const =0
double m_process_rate
See CGenericSensor.
virtual void initialize()
This method can or cannot be implemented in the derived class, depending on the need for it.
std::pair< mrpt::system::TTimeStamp, mrpt::utils::CSerializablePtr > TListObsPair
static CGenericSensor * createSensor(const std::string &className)
Creates a sensor by a name of the class.
std::string m_external_images_format
The extension ("jpg","gif","png",...) that determines the format of images saved externally.
virtual ~CGenericSensor()
Destructor.
synch::CCriticalSection m_csObjList
The critical section for m_objList.
std::string getSensorLabel() const
static std::map< std::string, const TSensorClassId * > m_knownClasses
Used in registerClass.
virtual void loadConfig_sensorSpecific(const mrpt::utils::CConfigFileBase &configSource, const std::string &section)=0
Loads specific configuration for the device from a given source of configuration parameters,...
void setExternalImageJPEGQuality(const unsigned int quality)
The quality of JPEG compression, when external images is enabled and the format is "jpg".
std::string m_sensorLabel
See CGenericSensor.
void appendObservations(const std::vector< mrpt::utils::CSerializablePtr > &obj)
This method must be called by derived classes to enqueue a new observation in the list to be returned...
void enableVerbose(bool enabled=true)
Enable or disable extra debug info dumped to std::cout during sensor operation.
unsigned int getExternalImageJPEGQuality() const
unsigned int m_external_images_jpeg_quality
For JPEG images, the quality (default=95%).
std::multimap< mrpt::system::TTimeStamp, mrpt::utils::CSerializablePtr > TListObservations
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...
void setExternalImageFormat(const std::string &ext)
Set the extension ("jpg","gif","png",...) that determines the format of images saved externally The d...
static CGenericSensorPtr createSensorPtr(const std::string &className)
Just like createSensor, but returning a smart pointer to the newly created sensor object.
This class provides simple critical sections functionality.
This class allows loading and storing values and vectors of different types from a configuration text...
The base class of classes that cannot be copied: compile-time errors will be issued on any copy opera...
Definition: CUncopiable.h:31
#define HWDRIVERS_IMPEXP
#define MRPT_MAKE_ALIGNED_OPERATOR_NEW
Definition: memory.h:112
#define MRPT_UNUSED_PARAM(a)
Can be used to avoid "not used parameters" warnings from the compiler.
Definition: mrpt_macros.h:290
stlplus::smart_ptr< CGenericSensor > CGenericSensorPtr
This is the global namespace for all Mobile Robot Programming Toolkit (MRPT) libraries.
Auxiliary structure used for CSerializable runtime class ID support.
CLASSINIT_GENERIC_SENSOR(const TSensorClassId *pNewClass)
A structure for runtime ID class type information in the context of hwdrivers::CGenericSensor.
const char * className
Class name.



Page generated by Doxygen 1.9.6 for MRPT 1.4.0 SVN: at Tue Jan 17 22:40:29 UTC 2023