Main MRPT website > C++ reference
MRPT logo
CCameraSensor.h
Go to the documentation of this file.
1 /* +---------------------------------------------------------------------------+
2  | The Mobile Robot Programming Toolkit (MRPT) C++ library |
3  | |
4  | http://www.mrpt.org/ |
5  | |
6  | Copyright (C) 2005-2012 University of Malaga |
7  | |
8  | This software was written by the Machine Perception and Intelligent |
9  | Robotics Lab, University of Malaga (Spain). |
10  | Contact: Jose-Luis Blanco <jlblanco@ctima.uma.es> |
11  | |
12  | This file is part of the MRPT project. |
13  | |
14  | MRPT is free software: you can redistribute it and/or modify |
15  | it under the terms of the GNU General Public License as published by |
16  | the Free Software Foundation, either version 3 of the License, or |
17  | (at your option) any later version. |
18  | |
19  | MRPT is distributed in the hope that it will be useful, |
20  | but WITHOUT ANY WARRANTY; without even the implied warranty of |
21  | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the |
22  | GNU General Public License for more details. |
23  | |
24  | You should have received a copy of the GNU General Public License |
25  | along with MRPT. If not, see <http://www.gnu.org/licenses/>. |
26  | |
27  +---------------------------------------------------------------------------+ */
28 
29 #ifndef CCameraSensor_H
30 #define CCameraSensor_H
31 
32 #include <mrpt/poses/CPose3D.h>
33 #include <mrpt/slam/CObservation.h>
34 #include <mrpt/utils/CDebugOutputCapable.h>
35 #include <mrpt/utils/CConfigFileBase.h>
36 #include <mrpt/hwdrivers/CGenericSensor.h>
37 
38 #include <mrpt/hwdrivers/CFFMPEG_InputStream.h>
39 #include <mrpt/hwdrivers/CImageGrabber_OpenCV.h>
40 #include <mrpt/hwdrivers/CImageGrabber_dc1394.h>
41 #include <mrpt/hwdrivers/CStereoGrabber_Bumblebee.h>
42 #include <mrpt/hwdrivers/CSwissRanger3DCamera.h>
43 #include <mrpt/hwdrivers/CKinect.h>
44 
45 #include <mrpt/utils/CFileGZInputStream.h>
46 #include <mrpt/hwdrivers/CStereoGrabber_SVS.h>
47 
48 #include <mrpt/gui/CDisplayWindow.h>
49 
50 namespace mrpt
51 {
52  namespace hwdrivers
53  {
54  /** The central class for camera grabbers in MRPT, implementing the "generic sensor" interface.
55  * This class provides the user with a uniform interface to a variety of other classes which manage only one specific camera "driver" (opencv, ffmpeg, bumblebee,...)
56  *
57  * Following the "generic sensor" interface, all the parameters must be passed int the form of a configuration file, which may be also formed on the fly (without being a real config file) as in this example:
58  *
59  * \code
60  * CCameraSensor myCam;
61  * const string str =
62  * "[CONFIG]\n"
63  * "grabber_type=opencv\n";
64  *
65  * CConfigFileMemory cfg(str);
66  * myCam.loadConfig(cfg,"CONFIG");
67  * myCam.initialize();
68  * CObservationPtr obs = myCam.getNextFrame();
69  * \endcode
70  *
71  * Images can be retrieved through the normal "doProcess()" interface, or the specific method "getNextFrame()".
72  *
73  * Some notes:
74  * - "grabber_type" determines the class to use internally for image capturing (see below).
75  * - For the meaning of cv_camera_type and other parameters, refer to mrpt::hwdrivers::CImageGrabber_OpenCV
76  * - For the parameters of dc1394 parameters, refer to generic IEEE1394 documentation, and to mrpt::hwdrivers::TCaptureOptions_dc1394.
77  * - If all the existing parameter annoy you, try the function prepareVideoSourceFromUserSelection(), which displays a GUI dialog to the user so he/she can choose the desired camera & its parameters.
78  *
79  * Images can be saved in the "external storage" mode. See setPathForExternalImages and setExternalImageFormat. These methods
80  * are called automatically from rawlog-grabber.
81  *
82  * These is the list of all accepted parameters:
83  *
84  * \code
85  * PARAMETERS IN THE ".INI"-LIKE CONFIGURATION STRINGS:
86  * -------------------------------------------------------
87  * [supplied_section_name]
88  * // Select one of the grabber implementations -----------------------
89  * grabber_type = opencv | dc1394 | bumblebee | ffmpeg | rawlog | swissranger | kinect
90  *
91  * // Options for any grabber_type ------------------------------------
92  * preview_decimation = 0 // N<=0 (or not present): No preview; N>0, display 1 out of N captured frames.
93  * preview_reduction = 0 // 0 or 1 (or not present): The preview shows the actual image. For 2,3,..., reduces the size of the image by that factor, only for the preview window.
94  * capture_grayscale = 0 // 1:capture in grayscale, whenever the driver allows it. Default=0
95  * // For externaly stored images, the format of image files (default=jpg)
96  * //external_images_format = jpg
97  *
98  * // For externaly stored images: whether to spawn independent threads to save the image files.
99  * //external_images_own_thread = 1 // 0 or 1
100  *
101  * // If external_images_own_thread=1, this changes the number of threads to launch
102  * // to save image files. The default is determined from mrpt::system::getNumberOfProcessors()
103  * // and should be OK unless you want to save processor time for other things.
104  * //external_images_own_thread_count = 2 // >=1
105  *
106  * // (Only when external_images_format=jpg): Optional parameter to set the JPEG compression quality:
107  * //external_images_jpeg_quality = 95 // [1-100]. Default: 95
108  *
109  * // Pose of the sensor on the robot:
110  * pose_x=0 ; (meters)
111  * pose_y=0
112  * pose_z=0
113  * pose_yaw=0 ; (Angles in degrees)
114  * pose_pitch=0
115  * pose_roll=0
116  *
117  * // Options for grabber_type= opencv ------------------------------------
118  * cv_camera_index = 0 // [opencv] Number of camera to open
119  * cv_camera_type = CAMERA_CV_AUTODETECT
120  * cv_frame_width = 640 // [opencv] Capture width (not present or set to 0 for default)
121  * cv_frame_height = 480 // [opencv] Capture height (not present or set to 0 for default)
122  * cv_fps = 15 // [opencv] IEEE1394 cams only: Capture FPS (not present or 0 for default)
123  * cv_gain = 0 // [opencv] Camera gain, if available (nor present or set to 0 for default).
124  *
125  * // Options for grabber_type= dc1394 -------------------------------------
126  * dc1394_camera_guid = 0 | 0x11223344 // 0 (or not present): the first camera; A hexadecimal number: The GUID of the camera to open
127  * dc1394_camera_unit = 0 // 0 (or not present): the first camera; 0,1,2,...: The unit number (within the given GUID) of the camera to open (Stereo cameras: 0 or 1)
128  * dc1394_frame_width = 640
129  * dc1394_frame_height = 480
130  * dc1394_framerate = 15 // eg: 7.5, 15, 30, 60, etc... For posibilities see mrpt::hwdrivers::TCaptureOptions_dc1394
131  * dc1394_mode7 = -1 // -1: Ignore, i>=0, set to MODE7_i
132  * dc1394_color_coding = COLOR_CODING_YUV422 // For posibilities see mrpt::hwdrivers::TCaptureOptions_dc1394
133  * dc1394_shutter = -1 // A value, or -1 (or not present) for not to change this parameter in the camera
134  * dc1394_gain = -1 // A value, or -1 (or not present) for not to change this parameter in the camera
135  * dc1394_gamma = -1 // A value, or -1 (or not present) for not to change this parameter in the camera
136  * dc1394_brightness = -1 // A value, or -1 (or not present) for not to change this parameter in the camera
137  * dc1394_exposure = -1 // A value, or -1 (or not present) for not to change this parameter in the camera
138  * dc1394_sharpness = -1 // A value, or -1 (or not present) for not to change this parameter in the camera
139  * dc1394_white_balance = -1 // A value, or -1 (or not present) for not to change this parameter in the camera
140  *
141  * // Options for grabber_type= bumblebee ----------------------------------
142  * bumblebee_camera_index = 0 // [bumblebee] Number of camera within the firewire bus to open (typically = 0)
143  * bumblebee_frame_width = 640 // [bumblebee] Capture width (not present or set to 0 for default)
144  * bumblebee_frame_height = 480 // [bumblebee] Capture height (not present or set to 0 for default)
145  * bumblebee_fps = 15 // [bumblebee] Capture FPS (not present or 0 for default)
146  * bumblebee_mono = 0|1 // [bumblebee] OPTIONAL: If this parameter is present, monocular (0:left, 1:right) images will be grabbed instead of stereo pairs.
147  * bumblebee_get_rectified = 0|1 // [bumblebee] Determines if the camera should grab rectified or raw images (1 is the default)
148  *
149  * // Options for grabber_type= ffmpeg -------------------------------------
150  * ffmpeg_url = rtsp://127.0.0.1 // [ffmpeg] The video file or IP camera to open
151  *
152  * // Options for grabber_type= rawlog -------------------------------------
153  * rawlog_file = mylog.rawlog // [rawlog] This can be used to simulate the capture of images already grabbed in the past in the form of a MRPT rawlog.
154  * rawlog_camera_sensor_label = CAMERA1 // [rawlog] If this field is not present, all images found in the rawlog will be retrieved. Otherwise, only those observations with a matching sensor label.
155  *
156  * // Options for grabber_type= swissranger -------------------------------------
157  * sr_use_usb = true // True: use USB, false: use ethernet
158  * sr_IP = 192.168.2.14 // If sr_use_usb=false, the camera IP
159  * sr_grab_grayscale = true // whether to save the intensity channel
160  * sr_grab_3d = true // whether to save the 3D points
161  * sr_grab_range = true // whether to save the range image
162  * sr_grab_confidence = true // whether to save the confidence image
163  *
164  * // Options for grabber_type= kinect -------------------------------------
165  * kinect_grab_intensity = true // whether to save the intensity (RGB) channel
166  * kinect_grab_3d = true // whether to save the 3D points
167  * kinect_grab_range = true // whether to save the depth image
168  *
169  * kinect_video_rgb = true // Optional. If set to "false", the IR intensity channel will be grabbed instead of the color RGB channel.
170  *
171  * \endcode
172  *
173  * \note The execution rate (in rawlog-grabber) should be greater than the required capture FPS.
174  * \note In Linux you may need to execute "chmod 666 /dev/video1394/ * " and "chmod 666 /dev/raw1394" for allowing any user R/W access to firewire cameras.
175  * \sa mrpt::hwdrivers::CImageGrabber_OpenCV, mrpt::hwdrivers::CImageGrabber_dc1394, CGenericSensor, prepareVideoSourceFromUserSelection
176  * \ingroup mrpt_hwdrivers_grp
177  */
178  class HWDRIVERS_IMPEXP CCameraSensor : public utils::CDebugOutputCapable, public CGenericSensor
179  {
180  DEFINE_GENERIC_SENSOR(CCameraSensor)
181 
182  public:
183  /** Constructor
184  * The camera is not open until "initialize" is called.
185  */
186  CCameraSensor();
187 
188  /** Destructor
189  */
190  virtual ~CCameraSensor();
191 
192  /** This method should be called periodically (at least at 1Hz to capture ALL the real-time data)
193  * It is thread safe, i.e. you can call this from one thread, then to other methods from other threads.
194  */
195  void doProcess();
196 
197  /** Retrieves the next frame from the video source, raising an exception on any error.
198  * Note: The returned observations can be of one of these classes (you can use IS_CLASS(obs,CObservationXXX) to determine it):
199  * - mrpt::slam::CObservationImage (For normal cameras or video sources)
200  * - mrpt::slam::CObservationStereoImages (For stereo cameras)
201  * - mrpt::slam::CObservation3DRangeScan (For 3D cameras)
202  */
203  mrpt::slam::CObservationPtr getNextFrame();
204 
205  /** Tries to open the camera, after setting all the parameters with a call to loadConfig.
206  * \exception This method must throw an exception with a descriptive message if some critical error is found.
207  */
208  virtual void initialize();
209 
210  /** Close the camera (if open).
211  * This method is called automatically on destruction.
212  */
213  void close();
214 
215  /** Set the path where to save off-rawlog image files (this class DOES take into account this path).
216  * An empty string (the default value at construction) means to save images embedded in the rawlog, instead of on separate files.
217  * \exception std::exception If the directory doesn't exists and cannot be created.
218  */
219  virtual void setPathForExternalImages( const std::string &directory );
220 
221  /** This must be called before initialize() */
222  void enableLaunchOwnThreadForSavingImages(bool enable=true) { m_external_images_own_thread = enable; };
223 
224  protected:
225  poses::CPose3D m_sensorPose;
226 
227  std::string m_grabber_type; //!< Can be "opencv",...
228  bool m_capture_grayscale;
229  int m_cv_camera_index;
230  std::string m_cv_camera_type;
231  mrpt::hwdrivers::TCaptureCVOptions m_cv_options;
232 
233  uint64_t m_dc1394_camera_guid;
234  int m_dc1394_camera_unit;
235  mrpt::hwdrivers::TCaptureOptions_dc1394 m_dc1394_options;
236  int m_preview_decimation;
237  int m_preview_reduction;
238 
239  int m_bumblebee_camera_index;
240  mrpt::hwdrivers::TCaptureOptions_bumblebee m_bumblebee_options;
241  int m_bumblebee_monocam; // 0:Left, 1: Right, <0,>1 -> Stereo
242 
243  int m_svs_camera_index;
244  mrpt::hwdrivers::TCaptureOptions_SVS m_svs_options;
245 
246  std::string m_ffmpeg_url;
247 
248  std::string m_rawlog_file;
249  std::string m_rawlog_camera_sensor_label;
250  std::string m_rawlog_detected_images_dir;
251 
252  bool m_sr_open_from_usb; //!< true: USB, false: ETH
253  std::string m_sr_ip_address;
254  bool m_sr_save_3d; //!< Save the 3D point cloud (default: true)
255  bool m_sr_save_range_img; //!< Save the 2D range image (default: true)
256  bool m_sr_save_intensity_img; //!< Save the 2D intensity image (default: true)
257  bool m_sr_save_confidence; //!< Save the estimated confidence 2D image (default: false)
258 
259  bool m_kinect_save_3d; //!< Save the 3D point cloud (default: true)
260  bool m_kinect_save_range_img; //!< Save the 2D range image (default: true)
261  bool m_kinect_save_intensity_img; //!< Save the 2D intensity image (default: true)
262  bool m_kinect_video_rgb; //!< Save RGB or IR channels (default:true)
263 
264  bool m_external_images_own_thread; //!< Whether to launch independent thread
265 
266  /** 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)
267  * See hwdrivers::CCameraSensor for the possible parameters
268  */
269  void loadConfig_sensorSpecific(
270  const mrpt::utils::CConfigFileBase &configSource,
271  const std::string &iniSection );
272 
273  private:
274  // Only one of these will be !=NULL at a time ===========
275  CImageGrabber_OpenCV *m_cap_cv; //!< The OpenCV capture object.
276  CImageGrabber_dc1394 *m_cap_dc1394; //!< The dc1394 capture object.
277  CStereoGrabber_Bumblebee *m_cap_bumblebee; //!< The bumblebee capture object.
278  mrpt::hwdrivers::CStereoGrabber_SVS *m_cap_svs; //!< The svs capture object.
279  CFFMPEG_InputStream *m_cap_ffmpeg; //!< The FFMPEG capture object
280  mrpt::utils::CFileGZInputStream *m_cap_rawlog; //!< The input file for rawlogs
281  CSwissRanger3DCamera *m_cap_swissranger; //!< SR 3D camera object.
282  CKinect *m_cap_kinect; //!< Kinect camera object.
283  // =========================
284 
285  int m_camera_grab_decimator;
286  int m_camera_grab_decimator_counter;
287 
288  int m_preview_counter;
289  mrpt::gui::CDisplayWindowPtr m_preview_win1,m_preview_win2; //!< Normally we'll use only one window, but for stereo images we'll use two of them.
290 
291  /** @name Stuff related to working threads to save images to disk
292  @{ */
293  unsigned int m_external_image_saver_count; //!< Number of working threads. Default:1, set to 2 in quad cores.
294  std::vector<mrpt::system::TThreadHandle> m_threadImagesSaver;
295 
296  bool m_threadImagesSaverShouldEnd;
297  mrpt::synch::CCriticalSection m_csToSaveList; //!< The critical section for m_toSaveList
298  std::vector<TListObservations> m_toSaveList; //!< The queues of objects to be returned by getObservations, one for each working thread.
299  void thread_save_images(unsigned int my_working_thread_index); //!< Thread to save images to files.
300  /** @} */
301 
302  }; // end class
303 
304  typedef stlplus::smart_ptr<CCameraSensor> CCameraSensorPtr; //!< A smart pointer to a CCameraSensor
305 
306  /** Used only from MRPT apps: Use with caution since "panel" MUST be a "mrpt::gui::CPanelCameraSelection *"
307  */
308  CCameraSensorPtr HWDRIVERS_IMPEXP prepareVideoSourceFromPanel(void *panel);
309 
310  /** Parse the user options in the wxWidgets "panel" and write the configuration into the given section of the given configuration file.
311  * Use with caution since "panel" MUST be a "mrpt::gui::CPanelCameraSelection *"
312  * \sa prepareVideoSourceFromUserSelection, prepareVideoSourceFromPanel, readConfigIntoVideoSourcePanel
313  */
314  void HWDRIVERS_IMPEXP writeConfigFromVideoSourcePanel(
315  void *panel,
316  const std::string &in_cfgfile_section_name,
317  mrpt::utils::CConfigFileBase *out_cfgfile
318  );
319 
320  /** Parse the given section of the given configuration file and set accordingly the controls of the wxWidgets "panel".
321  * Use with caution since "panel" MUST be a "mrpt::gui::CPanelCameraSelection *"
322  * \sa prepareVideoSourceFromUserSelection, prepareVideoSourceFromPanel, writeConfigFromVideoSourcePanel
323  */
324  void HWDRIVERS_IMPEXP readConfigIntoVideoSourcePanel(
325  void *panel,
326  const std::string &in_cfgfile_section_name,
327  const mrpt::utils::CConfigFileBase *in_cfgfile
328  );
329 
330  /** Show to the user a list of possible camera drivers and creates and open the selected camera.
331  */
332  CCameraSensorPtr HWDRIVERS_IMPEXP prepareVideoSourceFromUserSelection();
333 
334 
335  } // end namespace
336 } // end namespace
337 
338 #endif


Page generated by Doxygen 1.8.3 for MRPT 0.9.6 SVN: at Fri Feb 15 22:05:02 EST 2013