Main MRPT website > C++ reference
MRPT logo

CCameraSensor.h

Go to the documentation of this file.
00001 /* +---------------------------------------------------------------------------+
00002    |          The Mobile Robot Programming Toolkit (MRPT) C++ library          |
00003    |                                                                           |
00004    |                   http://mrpt.sourceforge.net/                            |
00005    |                                                                           |
00006    |   Copyright (C) 2005-2011  University of Malaga                           |
00007    |                                                                           |
00008    |    This software was written by the Machine Perception and Intelligent    |
00009    |      Robotics Lab, University of Malaga (Spain).                          |
00010    |    Contact: Jose-Luis Blanco  <jlblanco@ctima.uma.es>                     |
00011    |                                                                           |
00012    |  This file is part of the MRPT project.                                   |
00013    |                                                                           |
00014    |     MRPT is free software: you can redistribute it and/or modify          |
00015    |     it under the terms of the GNU General Public License as published by  |
00016    |     the Free Software Foundation, either version 3 of the License, or     |
00017    |     (at your option) any later version.                                   |
00018    |                                                                           |
00019    |   MRPT is distributed in the hope that it will be useful,                 |
00020    |     but WITHOUT ANY WARRANTY; without even the implied warranty of        |
00021    |     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the         |
00022    |     GNU General Public License for more details.                          |
00023    |                                                                           |
00024    |     You should have received a copy of the GNU General Public License     |
00025    |     along with MRPT.  If not, see <http://www.gnu.org/licenses/>.         |
00026    |                                                                           |
00027    +---------------------------------------------------------------------------+ */
00028 
00029 #ifndef CCameraSensor_H
00030 #define CCameraSensor_H
00031 
00032 #include <mrpt/poses/CPose3D.h>
00033 #include <mrpt/slam/CObservation.h>
00034 #include <mrpt/utils/CDebugOutputCapable.h>
00035 #include <mrpt/utils/CConfigFileBase.h>
00036 #include <mrpt/hwdrivers/CGenericSensor.h>
00037 
00038 #include <mrpt/hwdrivers/CFFMPEG_InputStream.h>
00039 #include <mrpt/hwdrivers/CImageGrabber_OpenCV.h>
00040 #include <mrpt/hwdrivers/CImageGrabber_dc1394.h>
00041 #include <mrpt/hwdrivers/CStereoGrabber_Bumblebee.h>
00042 #include <mrpt/hwdrivers/CSwissRanger3DCamera.h>
00043 #include <mrpt/hwdrivers/CKinect.h>
00044 
00045 #include <mrpt/utils/CFileGZInputStream.h>
00046 #include <mrpt/hwdrivers/CStereoGrabber_SVS.h>
00047 
00048 #include <mrpt/gui/CDisplayWindow.h>
00049 
00050 namespace mrpt
00051 {
00052         namespace hwdrivers
00053         {
00054                 /** The central class for camera grabbers in MRPT, implementing the "generic sensor" interface.
00055                   *   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,...)
00056                   *
00057                   *   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:
00058                   *
00059                   *  \code
00060                   *   CCameraSensor myCam;
00061                   *   const string str =
00062                   *      "[CONFIG]\n"
00063                   *      "grabber_type=opencv\n";
00064                   *
00065                   *   CConfigFileMemory cfg(str);
00066                   *   myCam.loadConfig(cfg,"CONFIG");
00067                   *   myCam.initialize();
00068                   *   CObservationPtr obs = myCam.getNextFrame();
00069                   *  \endcode
00070                   *
00071                   *  Images can be retrieved through the normal "doProcess()" interface, or the specific method "getNextFrame()".
00072                   *
00073                   * Some notes:
00074                   *  - "grabber_type" determines the class to use internally for image capturing (see below).
00075                   *  - For the meaning of cv_camera_type and other parameters, refer to mrpt::hwdrivers::CImageGrabber_OpenCV
00076                   *  - For the parameters of dc1394 parameters, refer to generic IEEE1394 documentation, and to mrpt::hwdrivers::TCaptureOptions_dc1394.
00077                   *  - 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.
00078                   *
00079                   *  Images can be saved in the "external storage" mode. See setPathForExternalImages and setExternalImageFormat. These methods
00080                   *   are called automatically from rawlog-grabber.
00081                   *
00082                   *  These is the list of all accepted parameters:
00083                   *
00084                   *  \code
00085                   *  PARAMETERS IN THE ".INI"-LIKE CONFIGURATION STRINGS:
00086                   * -------------------------------------------------------
00087                   *   [supplied_section_name]
00088                   *    // Select one of the grabber implementations -----------------------
00089                   *    grabber_type       = opencv | dc1394 | bumblebee | ffmpeg | rawlog | swissranger | kinect
00090                   *
00091                   *    // Options for any grabber_type ------------------------------------
00092                   *    preview_decimation = 0     // N<=0 (or not present): No preview; N>0, display 1 out of N captured frames.
00093                   *    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.
00094                   *    capture_grayscale  = 0     // 1:capture in grayscale, whenever the driver allows it. Default=0
00095                   *    // For externaly stored images, the format of image files (default=jpg)
00096                   *    //external_images_format  = jpg
00097                   *
00098                   *    // For externaly stored images: whether to spawn independent threads to save the image files.
00099                   *    //external_images_own_thread  = 1   // 0 or 1
00100                   *
00101                   *    // If external_images_own_thread=1, this changes the number of threads to launch
00102                   *    //  to save image files. The default is determined from mrpt::system::getNumberOfProcessors()
00103                   *    //  and should be OK unless you want to save processor time for other things.
00104                   *    //external_images_own_thread_count = 2    // >=1
00105                   *
00106                   *    // (Only when external_images_format=jpg): Optional parameter to set the JPEG compression quality:
00107                   *    //external_images_jpeg_quality = 95    // [1-100]. Default: 95
00108                   *
00109                   *    // Pose of the sensor on the robot:
00110                   *    pose_x=0         ; (meters)
00111                   *    pose_y=0
00112                   *    pose_z=0
00113                   *    pose_yaw=0       ; (Angles in degrees)
00114                   *    pose_pitch=0
00115                   *    pose_roll=0
00116                   *
00117                   *    // Options for grabber_type= opencv  ------------------------------------
00118                   *    cv_camera_index  = 0       // [opencv] Number of camera to open
00119                   *    cv_camera_type   = CAMERA_CV_AUTODETECT
00120                   *    cv_frame_width   = 640     // [opencv] Capture width (not present or set to 0 for default)
00121                   *    cv_frame_height  = 480     // [opencv] Capture height (not present or set to 0 for default)
00122                   *    cv_fps           = 15      // [opencv] IEEE1394 cams only: Capture FPS (not present or 0 for default)
00123                   *    cv_gain          = 0       // [opencv] Camera gain, if available (nor present or set to 0 for default).
00124                   *
00125                   *    // Options for grabber_type= dc1394 -------------------------------------
00126                   *    dc1394_camera_guid   = 0 | 0x11223344    // 0 (or not present): the first camera; A hexadecimal number: The GUID of the camera to open
00127                   *    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)
00128                   *    dc1394_frame_width       = 640
00129                   *    dc1394_frame_height      = 480
00130                   *    dc1394_framerate         = 15                                    // eg: 7.5, 15, 30, 60, etc... For posibilities see mrpt::hwdrivers::TCaptureOptions_dc1394
00131                   *    dc1394_mode7         = -1                    // -1: Ignore, i>=0, set to MODE7_i
00132                   *    dc1394_color_coding      = COLOR_CODING_YUV422   // For posibilities see mrpt::hwdrivers::TCaptureOptions_dc1394
00133                   *    dc1394_shutter           = -1    // A value, or -1 (or not present) for not to change this parameter in the camera
00134                   *    dc1394_gain                      = -1    // A value, or -1 (or not present) for not to change this parameter in the camera
00135                   *    dc1394_gamma                     = -1    // A value, or -1 (or not present) for not to change this parameter in the camera
00136                   *    dc1394_brightness        = -1    // A value, or -1 (or not present) for not to change this parameter in the camera
00137                   *    dc1394_exposure          = -1    // A value, or -1 (or not present) for not to change this parameter in the camera
00138                   *    dc1394_sharpness         = -1    // A value, or -1 (or not present) for not to change this parameter in the camera
00139                   *    dc1394_white_balance     = -1    // A value, or -1 (or not present) for not to change this parameter in the camera
00140                   *
00141                   *    // Options for grabber_type= bumblebee ----------------------------------
00142                   *    bumblebee_camera_index  = 0       // [bumblebee] Number of camera within the firewire bus to open (typically = 0)
00143                   *    bumblebee_frame_width   = 640     // [bumblebee] Capture width (not present or set to 0 for default)
00144                   *    bumblebee_frame_height  = 480     // [bumblebee] Capture height (not present or set to 0 for default)
00145                   *    bumblebee_fps           = 15      // [bumblebee] Capture FPS (not present or 0 for default)
00146                   *    bumblebee_mono          = 0|1     // [bumblebee] OPTIONAL: If this parameter is present, monocular (0:left, 1:right) images will be grabbed instead of stereo pairs.
00147                   *    bumblebee_get_rectified = 0|1     // [bumblebee] Determines if the camera should grab rectified or raw images (1 is the default)
00148                   *
00149                   *    // Options for grabber_type= ffmpeg -------------------------------------
00150                   *    ffmpeg_url             = rtsp://127.0.0.1      // [ffmpeg] The video file or IP camera to open
00151                   *
00152                   *    // Options for grabber_type= rawlog -------------------------------------
00153                   *    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.
00154                   *    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.
00155                   *
00156                   *    // Options for grabber_type= swissranger -------------------------------------
00157                   *    sr_use_usb         = true                // True: use USB, false: use ethernet
00158                   *    sr_IP              = 192.168.2.14    // If sr_use_usb=false, the camera IP
00159                   *    sr_grab_grayscale  = true            // whether to save the intensity channel
00160                   *    sr_grab_3d         = true            // whether to save the 3D points
00161                   *    sr_grab_range      = true            // whether to save the range image
00162                   *    sr_grab_confidence = true            // whether to save the confidence image
00163                   *
00164                   *    // Options for grabber_type= kinect -------------------------------------
00165                   *    kinect_grab_intensity  = true            // whether to save the intensity (RGB) channel
00166                   *    kinect_grab_3d         = true            // whether to save the 3D points
00167                   *    kinect_grab_range      = true            // whether to save the depth image
00168                   *
00169                   *  \endcode
00170                   *
00171                   *  \note The execution rate (in rawlog-grabber) should be greater than the required capture FPS.
00172                   *  \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.
00173                   *  \sa mrpt::hwdrivers::CImageGrabber_OpenCV, mrpt::hwdrivers::CImageGrabber_dc1394, CGenericSensor, prepareVideoSourceFromUserSelection
00174                   */
00175                 class HWDRIVERS_IMPEXP CCameraSensor : public utils::CDebugOutputCapable, public CGenericSensor
00176                 {
00177                         DEFINE_GENERIC_SENSOR(CCameraSensor)
00178 
00179                 public:
00180                         /** Constructor
00181                           *  The camera is not open until "initialize" is called.
00182                           */
00183                         CCameraSensor();
00184 
00185                         /** Destructor
00186                           */
00187                         virtual ~CCameraSensor();
00188 
00189                         /** This method should be called periodically (at least at 1Hz to capture ALL the real-time data)
00190                         *  It is thread safe, i.e. you can call this from one thread, then to other methods from other threads.
00191                         */
00192                         void  doProcess();
00193 
00194                         /** Retrieves the next frame from the video source, raising an exception on any error.
00195                           * Note: The returned observations can be of one of these classes (you can use IS_CLASS(obs,CObservationXXX) to determine it):
00196                           *             - mrpt::slam::CObservationImage (For normal cameras or video sources)
00197                           *             - mrpt::slam::CObservationStereoImages (For stereo cameras)
00198                           *             - mrpt::slam::CObservation3DRangeScan (For 3D cameras)
00199                           */
00200                         mrpt::slam::CObservationPtr getNextFrame();
00201 
00202                         /** Tries to open the camera, after setting all the parameters with a call to loadConfig.
00203                           *  \exception This method must throw an exception with a descriptive message if some critical error is found.
00204                           */
00205                         virtual void initialize();
00206 
00207                         /** Close the camera (if open).
00208                           *   This method is called automatically on destruction.
00209                           */
00210                         void close();
00211 
00212                         /**  Set the path where to save off-rawlog image files (this class DOES take into account this path).
00213                           *  An  empty string (the default value at construction) means to save images embedded in the rawlog, instead of on separate files.
00214                           * \exception std::exception If the directory doesn't exists and cannot be created.
00215                           */
00216                         virtual void setPathForExternalImages( const std::string &directory );
00217 
00218                         /** This must be called before initialize() */
00219                         void enableLaunchOwnThreadForSavingImages(bool enable=true) { m_external_images_own_thread = enable; };
00220 
00221                 protected:
00222                         poses::CPose3D          m_sensorPose;
00223 
00224                         std::string                                                             m_grabber_type; //!< Can be "opencv",...
00225                         bool                                                                    m_capture_grayscale;
00226                         int                                                                             m_cv_camera_index;
00227                         std::string                                                             m_cv_camera_type;
00228                         mrpt::hwdrivers::TCaptureCVOptions                      m_cv_options;
00229 
00230                         uint64_t                                                                m_dc1394_camera_guid;
00231                         int                                                                             m_dc1394_camera_unit;
00232                         mrpt::hwdrivers::TCaptureOptions_dc1394 m_dc1394_options;
00233                         int                                                                             m_preview_decimation;
00234                         int                                                                             m_preview_reduction;
00235 
00236                         int                                                                             m_bumblebee_camera_index;
00237                         mrpt::hwdrivers::TCaptureOptions_bumblebee      m_bumblebee_options;
00238                         int                                                                             m_bumblebee_monocam; // 0:Left, 1: Right, <0,>1 -> Stereo
00239 
00240                         int                                                                             m_svs_camera_index;
00241                         mrpt::hwdrivers::TCaptureOptions_SVS    m_svs_options;
00242 
00243                         std::string                                                             m_ffmpeg_url;
00244 
00245                         std::string                                                             m_rawlog_file;
00246                         std::string                                                             m_rawlog_camera_sensor_label;
00247                         std::string                                                             m_rawlog_detected_images_dir;
00248 
00249                         bool                    m_sr_open_from_usb; //!< true: USB, false: ETH
00250                         std::string     m_sr_ip_address;
00251                         bool                    m_sr_save_3d;                   //!< Save the 3D point cloud (default: true)
00252                         bool                    m_sr_save_range_img;    //!< Save the 2D range image (default: true)
00253                         bool                    m_sr_save_intensity_img; //!< Save the 2D intensity image (default: true)
00254                         bool                    m_sr_save_confidence;   //!< Save the estimated confidence 2D image (default: false)
00255 
00256                         bool                    m_kinect_save_3d;                       //!< Save the 3D point cloud (default: true)
00257                         bool                    m_kinect_save_range_img;        //!< Save the 2D range image (default: true)
00258                         bool                    m_kinect_save_intensity_img; //!< Save the 2D intensity image (default: true)
00259 
00260                         bool                            m_external_images_own_thread; //!< Whether to launch independent thread
00261 
00262                         /** 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)
00263                           *  See hwdrivers::CCameraSensor for the possible parameters
00264                           */
00265                         void  loadConfig_sensorSpecific(
00266                                 const mrpt::utils::CConfigFileBase &configSource,
00267                                 const std::string         &iniSection );
00268 
00269                 private:
00270                         // Only one of these will be !=NULL at a time ===========
00271                         CImageGrabber_OpenCV                            *m_cap_cv;              //!< The OpenCV capture object.
00272                         CImageGrabber_dc1394                            *m_cap_dc1394;  //!< The dc1394 capture object.
00273                         CStereoGrabber_Bumblebee                        *m_cap_bumblebee;       //!< The bumblebee capture object.
00274                         mrpt::hwdrivers::CStereoGrabber_SVS        *m_cap_svs;  //!< The svs capture object.
00275                         CFFMPEG_InputStream                                     *m_cap_ffmpeg;  //!< The FFMPEG capture object
00276                         mrpt::utils::CFileGZInputStream         *m_cap_rawlog;  //!< The input file for rawlogs
00277                         CSwissRanger3DCamera                            *m_cap_swissranger; //!< SR 3D camera object.
00278                         CKinect                             *m_cap_kinect;    //!< Kinect camera object.
00279                         // =========================
00280 
00281                         int                     m_camera_grab_decimator;
00282                         int                     m_camera_grab_decimator_counter;
00283 
00284                         int                                                      m_preview_counter;
00285                         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.
00286 
00287                         /** @name Stuff related to working threads to save images to disk
00288                             @{ */
00289                         unsigned int            m_external_image_saver_count; //!< Number of working threads. Default:1, set to 2 in quad cores.
00290                         std::vector<mrpt::system::TThreadHandle>  m_threadImagesSaver;
00291 
00292                         bool    m_threadImagesSaverShouldEnd;
00293                         mrpt::synch::CCriticalSection   m_csToSaveList;         //!< The critical section for m_toSaveList
00294                         std::vector<TListObservations>  m_toSaveList;           //!< The queues of objects to be returned by getObservations, one for each working thread.
00295                         void thread_save_images(unsigned int my_working_thread_index); //!< Thread to save images to files.
00296                         /**  @} */
00297 
00298                 }; // end class
00299 
00300                 typedef stlplus::smart_ptr<CCameraSensor>    CCameraSensorPtr; //!< A smart pointer to a CCameraSensor
00301 
00302                 /** Used only from MRPT apps: Use with caution since "panel" MUST be a "mrpt::gui::CPanelCameraSelection *"
00303                   */
00304                 CCameraSensorPtr HWDRIVERS_IMPEXP prepareVideoSourceFromPanel(void *panel);
00305 
00306                 /** Parse the user options in the wxWidgets "panel" and write the configuration into the given section of the given configuration file.
00307                   * Use with caution since "panel" MUST be a "mrpt::gui::CPanelCameraSelection *"
00308                   * \sa prepareVideoSourceFromUserSelection, prepareVideoSourceFromPanel, readConfigIntoVideoSourcePanel
00309                   */
00310                 void HWDRIVERS_IMPEXP writeConfigFromVideoSourcePanel(
00311                         void *panel,
00312                         const std::string &in_cfgfile_section_name,
00313                         mrpt::utils::CConfigFileBase *out_cfgfile
00314                         );
00315 
00316                 /** Parse the given section of the given configuration file and set accordingly the controls of the wxWidgets "panel".
00317                   * Use with caution since "panel" MUST be a "mrpt::gui::CPanelCameraSelection *"
00318                   * \sa prepareVideoSourceFromUserSelection, prepareVideoSourceFromPanel, writeConfigFromVideoSourcePanel
00319                   */
00320                 void HWDRIVERS_IMPEXP readConfigIntoVideoSourcePanel(
00321                         void *panel,
00322                         const std::string &in_cfgfile_section_name,
00323                         const mrpt::utils::CConfigFileBase *in_cfgfile
00324                         );
00325 
00326                 /** Show to the user a list of possible camera drivers and creates and open the selected camera.
00327                   */
00328                 CCameraSensorPtr HWDRIVERS_IMPEXP prepareVideoSourceFromUserSelection();
00329 
00330 
00331         } // end namespace
00332 } // end namespace
00333 
00334 #endif



Page generated by Doxygen 1.7.3 for MRPT 0.9.4 SVN: at Sat Mar 26 06:40:17 UTC 2011