CDUO3DCamera.h

Go to the documentation of this file.

/* +------------------------------------------------------------------------+
   |                     Mobile Robot Programming Toolkit (MRPT)            |
   |                          http://www.mrpt.org/                          |
   |                                                                        |
   | Copyright (c) 2005-2017, Individual contributors, see AUTHORS file     |
   | See: http://www.mrpt.org/Authors - All rights reserved.                |
   | Released under BSD License. See details in http://www.mrpt.org/License |
   +------------------------------------------------------------------------+ */

#ifndef CDUO3DCamera_H
#define CDUO3DCamera_H

#include <mrpt/obs/CObservationStereoImages.h>
#include <mrpt/obs/CObservationIMU.h>
#include <mrpt/vision/CStereoRectifyMap.h>

namespace mrpt
{
namespace hwdrivers
{
/** Options used when creating a camera capture object of type
 * CImageGrabber_FlyCapture2   \ingroup mrpt_hwdrivers_grp */
struct TCaptureOptions_DUO3D
{
        enum TYMLReadResult
        {
                yrr_NAME_NON_CONSISTENT,
                yrr_EMPTY,
                yrr_OK
        };

        TCaptureOptions_DUO3D();
        ~TCaptureOptions_DUO3D();

        /** @name Image settings
          * @{ */
        /** (Default = 640) Width of the captured image. */
        int m_img_width;
        /** (Default = 480) Height of the captured image. */
        int m_img_height;
        /** (Default = 30) Frames per second <= 30. */
        float m_fps;
        /** (Default = 50) Exposure value. */
        float m_exposure;
        /** (Default = 25) Led intensity (some device models). */
        float m_led;
        /** (Default = 10) Camera gain. */
        float m_gain;
        /** @} */

        /** @name Behaviour selection
          * @{ */
        /** (Default = false) Capture IMU data. */
        bool m_capture_imu;
        /** (Default = true) Rectify images. Rectification map must be provided \sa
         * m_rectify_map_filename. */
        bool m_capture_rectified;
        /** (Default = true) Get calibration information from files provided by
         * DUO3D Calibration App. */
        bool m_calibration_from_file;
        /** @} */

        /** @name Files specification
          * @{ */
        /** Rectification map file provided by DUO3D Calibration App (YML format).
         */
        std::string m_rectify_map_filename;
        /** Intrinsic parameters file provided by DUO3D Calibration App (YML
         * format). */
        std::string m_intrinsic_filename;
        /** Extrinsic parameters file provided by DUO3D Calibration App (YML
         * format). */
        std::string m_extrinsic_filename;
        /** @} */

        /** @name Others
          * @{ */
        mrpt::utils::TStereoCamera m_stereo_camera;
        /** @} */

        // clang-format off
        /** Loads all the options from a config file.
          * Expected format:
          *
          * \code
          * [sectionName]
          *             image_width                     = 640                   // [int]        x Resolution
          *             image_height                    = 480                   // [int]        y Resolution
          *             fps                                             = 30                    // [int]        Frames per second (<= *30)
          *             exposure                                = 50                    // [int]        Exposure value (1..100)
          *             led                                             = 0                             // [int]        Led intensity (only for some device models) (1..100).
          *             gain                                    = 50                    // [int]        Camera gain (1..100)
          *             capture_rectified               = false                 // [bool]       Rectify captured images
          *             capture_imu                     = true                  // [bool]       Capture IMU data from DUO3D device (if available)
          *             calibration_from_file   = true                  // [bool]       Use YML calibration files provided by calibration application supplied with DUO3D device
          *             intrinsic_filename              = ""                    // [string]     Intrinsic parameters file.  This filename should contain a substring _RWWWxHHH_ with WWW being the image width and HHH the image height, as provided by the calibration application.
          *             extrinsic_filename              = ""                    // [string]     Extrinsic parameters file.  This filename should contain a substring _RWWWxHHH_ with WWW being the image width and HHH the image height, as provided by the calibration application.
          *             rectify_map_filename    = ""                    // [string]     Rectification map file.  This filename should contain a substring _RWWWxHHH_ with WWW being the image width and HHH the image height, as provided by the calibration application.
          *
          * \endcode
          * \note All parameter names may have an optional prefix, set with the
          *"prefix" parameter.
          *  For example, if prefix="LEFT_", the expected variable name
          *"camera_index" in the config section will be "LEFT_camera_index", and so
          *on.
          */
        void loadOptionsFrom(
                const mrpt::utils::CConfigFileBase& configSource,
                const std::string& sectionName,
                const std::string& prefix = std::string());
        // clang-format on

        TYMLReadResult m_camera_int_params_from_yml(
                const std::string& _file_name = std::string());
        TYMLReadResult m_camera_ext_params_from_yml(
                const std::string& _file_name = std::string());
        TYMLReadResult m_rectify_map_from_yml(
                const std::string& _file_name = std::string());

};  // end-TCaptureOptions_DUO3D

// clang-format off
/** This "software driver" implements the communication protocol for interfacing
  *a DUO3D Stereo Camera
  *
  *   See also the example configuration file for rawlog-grabber in
  *"share/mrpt/config_files/rawlog-grabber".
  *
  *  \code
  *  PARAMETERS IN THE ".INI"-LIKE CONFIGURATION STRINGS:
  * -------------------------------------------------------
  *   [supplied_section_name]
  *             image_width                     = 640                   // [int]        x Resolution
  *             image_height                    = 480                   // [int]        y Resolution
  *             fps                                             = 30                    // [int]        Frames per second (<=30)
  *             exposure                                = 50                    // [int]        Exposure value (1..100)
  *             led                                             = 0                             // [int]        Led intensity (only for some device models) (1..100).
  *             gain                                    = 50                    // [int]        Camera gain (1..100)
  *             capture_rectified               = false                 // [bool]       Rectify captured images
  *             capture_imu                     = true                  // [bool]       Capture IMU data from DUO3D device (if available)
  *             calibration_from_file   = true                  // [bool]       Use YML calibration files provided by calibration application supplied with DUO3D device
  *             intrinsic_filename              = ""                    // [string]     Intrinsic parameters file.  This filename should contain a substring _RWWWxHHH_ with WWW being the image width and HHH the image height, as provided by the calibration application.
  *             extrinsic_filename              = ""                    // [string]     Extrinsic parameters file. This filename should contain a substring _RWWWxHHH_ with WWW being the image width and HHH the image height, as provided by the calibration application.
  *             rectify_map_filename    = ""                    // [string]     Rectification map file.  This filename should contain a substring _RWWWxHHH_ with WWW being the image width and HHH the image height, as provided by the calibration application.
  *
  *   pose_x=0.21       // camera 3D position in the robot (meters)
  *   pose_y=0
  *   pose_z=0.34
  *   pose_yaw=0        // Angles in degrees
  *   pose_pitch=0
  *   pose_roll=0
  *  \endcode
  *
  * \ingroup mrpt_hwdrivers_grp
  */  // clang-format on
class CDUO3DCamera
{
   protected:
        // members
        // [USER-DEFINED]
        TCaptureOptions_DUO3D m_options;

        // [INTERNAL]
        mrpt::vision::CStereoRectifyMap m_rectify_map;

        /** Opaque pointer to DUO's DUOInstance */
        void* m_duo;
        /** Pointer, to be reinterpreted as "PDUOFrame" */
        void* m_pframe_data;
        /** DUO's HANDLE */
        void* m_evFrame;

   public:
        /** Default Constructor (does not open the camera) */
        CDUO3DCamera();

        /** Constructor: tries to open the camera with the given options. Raises an
         * exception on error. \sa open() */
        CDUO3DCamera(const TCaptureOptions_DUO3D& options);

        CDUO3DCamera(const CDUO3DCamera&) = delete;
        CDUO3DCamera& operator=(const CDUO3DCamera&) = delete;

        /** Destructor  */
        virtual ~CDUO3DCamera();

        /** Returns the current settings of the camera */
        const TCaptureOptions_DUO3D& getCameraOptions() const { return m_options; }
        /** Tries to open the camera with the given options, and starts capturing.
         * Raises an exception on error.
          * \param[in] startCapture If set to false, the camera is only opened and
         * configured, but a posterior call to startCapture() is required to start
         * grabbing data.
          * \sa close(), startCapture()
          */
        void open(
                const TCaptureOptions_DUO3D& options, const bool startCapture = true);

        /** Start the actual data capture of the camera. Must be called after
         * open(), only when "startCapture" was set to false.
          */
        void startCapture();

        /** Stop capture. */
        void stopCapture();

        /** Stop capture and closes the opened camera, if any. Called automatically
         * on object destruction. */
        void close();

        /** Specific laser scanner "software drivers" must process here new data
         * from the I/O stream, and, if a whole scan has arrived, return it.
          *  This method will be typically called in a different thread than other
         * methods, and will be called in a timely fashion.
          */
        void getObservations(
                mrpt::obs::CObservationStereoImages& outObservation_img,
                mrpt::obs::CObservationIMU& outObservation_imu, bool& there_is_img,
                bool& there_is_imu);

        /** Indicates if the camera is grabbing IMU data */
        inline bool captureIMUIsSet() { return m_options.m_capture_imu; }
        /** Returned pointer to be reinterpreted as DUO3D's "HANDLE" */
        inline void* getEvent() { return this->m_evFrame; }
        /** frame is a reinterpreted PDUOFrame */
        inline void setDataFrame(void* frame) { this->m_pframe_data = frame; }
   protected:
        /** Queries the DUO3D Camera firmware version */
        bool queryVersion(std::string version, bool printOutVersion = false);

        /** Gets a stereo frame from the DUO3D Camera (void* to be reinterpreted as
         * PDUOFrame) */
        void* m_get_duo_frame();

        /** Opens DUO3D camera */
        bool m_open_duo_camera(int width, int height, float fps);

        /** Closes DUO3D camera */
        void m_close_duo_camera();

        /** Sets DUO3D camera Exposure setting */
        void m_set_exposure(float value);

        /** Sets DUO3D camera Gain setting  */
        void m_set_gain(float value);

        /** Sets DUO3D camera LED setting  */
        void m_set_led(float value);

   public:
        MRPT_MAKE_ALIGNED_OPERATOR_NEW

};  // End of class

static_assert(!std::is_copy_constructible<CDUO3DCamera>::value, "Copy Check");
static_assert(!std::is_copy_assignable<CDUO3DCamera>::value, "Assign Check");
}  // End of namespace
}  // End of namespace
#endif