1 /*M/////////////////////////////////////////////////////////////////////////////////////// 2 // 3 // IMPORTANT: READ BEFORE DOWNLOADING, COPYING, INSTALLING OR USING. 4 // 5 // By downloading, copying, installing or using the software you agree to this license. 6 // If you do not agree to this license, do not download, install, 7 // copy or use the software. 8 // 9 // 10 // License Agreement 11 // For Open Source Computer Vision Library 12 // 13 // Copyright (C) 2000-2008, Intel Corporation, all rights reserved. 14 // Copyright (C) 2009, Willow Garage Inc., all rights reserved. 15 // Third party copyrights are property of their respective owners. 16 // 17 // Redistribution and use in source and binary forms, with or without modification, 18 // are permitted provided that the following conditions are met: 19 // 20 // * Redistribution's of source code must retain the above copyright notice, 21 // this list of conditions and the following disclaimer. 22 // 23 // * Redistribution's in binary form must reproduce the above copyright notice, 24 // this list of conditions and the following disclaimer in the documentation 25 // and/or other materials provided with the distribution. 26 // 27 // * The name of the copyright holders may not be used to endorse or promote products 28 // derived from this software without specific prior written permission. 29 // 30 // This software is provided by the copyright holders and contributors "as is" and 31 // any express or implied warranties, including, but not limited to, the implied 32 // warranties of merchantability and fitness for a particular purpose are disclaimed. 33 // In no event shall the Intel Corporation or contributors be liable for any direct, 34 // indirect, incidental, special, exemplary, or consequential damages 35 // (including, but not limited to, procurement of substitute goods or services; 36 // loss of use, data, or profits; or business interruption) however caused 37 // and on any theory of liability, whether in contract, strict liability, 38 // or tort (including negligence or otherwise) arising in any way out of 39 // the use of this software, even if advised of the possibility of such damage. 40 // 41 //M*/ 42 43 #ifndef __OPENCV_VIDEOIO_HPP__ 44 #define __OPENCV_VIDEOIO_HPP__ 45 46 #include "opencv2/core.hpp" 47 48 /** 49 @defgroup videoio Media I/O 50 @{ 51 @defgroup videoio_c C API 52 @defgroup videoio_ios iOS glue 53 @defgroup videoio_winrt WinRT glue 54 @} 55 */ 56 57 ////////////////////////////////// video io ///////////////////////////////// 58 59 typedef struct CvCapture CvCapture; 60 typedef struct CvVideoWriter CvVideoWriter; 61 62 namespace cv 63 { 64 65 //! @addtogroup videoio 66 //! @{ 67 68 // Camera API 69 enum { CAP_ANY = 0, // autodetect 70 CAP_VFW = 200, // platform native 71 CAP_V4L = 200, 72 CAP_V4L2 = CAP_V4L, 73 CAP_FIREWARE = 300, // IEEE 1394 drivers 74 CAP_FIREWIRE = CAP_FIREWARE, 75 CAP_IEEE1394 = CAP_FIREWARE, 76 CAP_DC1394 = CAP_FIREWARE, 77 CAP_CMU1394 = CAP_FIREWARE, 78 CAP_QT = 500, // QuickTime 79 CAP_UNICAP = 600, // Unicap drivers 80 CAP_DSHOW = 700, // DirectShow (via videoInput) 81 CAP_PVAPI = 800, // PvAPI, Prosilica GigE SDK 82 CAP_OPENNI = 900, // OpenNI (for Kinect) 83 CAP_OPENNI_ASUS = 910, // OpenNI (for Asus Xtion) 84 CAP_ANDROID = 1000, // Android - not used 85 CAP_XIAPI = 1100, // XIMEA Camera API 86 CAP_AVFOUNDATION = 1200, // AVFoundation framework for iOS (OS X Lion will have the same API) 87 CAP_GIGANETIX = 1300, // Smartek Giganetix GigEVisionSDK 88 CAP_MSMF = 1400, // Microsoft Media Foundation (via videoInput) 89 CAP_WINRT = 1410, // Microsoft Windows Runtime using Media Foundation 90 CAP_INTELPERC = 1500, // Intel Perceptual Computing SDK 91 CAP_OPENNI2 = 1600, // OpenNI2 (for Kinect) 92 CAP_OPENNI2_ASUS = 1610, // OpenNI2 (for Asus Xtion and Occipital Structure sensors) 93 CAP_GPHOTO2 = 1700 // gPhoto2 connection 94 }; 95 96 // generic properties (based on DC1394 properties) 97 enum { CAP_PROP_POS_MSEC =0, 98 CAP_PROP_POS_FRAMES =1, 99 CAP_PROP_POS_AVI_RATIO =2, 100 CAP_PROP_FRAME_WIDTH =3, 101 CAP_PROP_FRAME_HEIGHT =4, 102 CAP_PROP_FPS =5, 103 CAP_PROP_FOURCC =6, 104 CAP_PROP_FRAME_COUNT =7, 105 CAP_PROP_FORMAT =8, 106 CAP_PROP_MODE =9, 107 CAP_PROP_BRIGHTNESS =10, 108 CAP_PROP_CONTRAST =11, 109 CAP_PROP_SATURATION =12, 110 CAP_PROP_HUE =13, 111 CAP_PROP_GAIN =14, 112 CAP_PROP_EXPOSURE =15, 113 CAP_PROP_CONVERT_RGB =16, 114 CAP_PROP_WHITE_BALANCE_BLUE_U =17, 115 CAP_PROP_RECTIFICATION =18, 116 CAP_PROP_MONOCHROME =19, 117 CAP_PROP_SHARPNESS =20, 118 CAP_PROP_AUTO_EXPOSURE =21, // DC1394: exposure control done by camera, user can adjust refernce level using this feature 119 CAP_PROP_GAMMA =22, 120 CAP_PROP_TEMPERATURE =23, 121 CAP_PROP_TRIGGER =24, 122 CAP_PROP_TRIGGER_DELAY =25, 123 CAP_PROP_WHITE_BALANCE_RED_V =26, 124 CAP_PROP_ZOOM =27, 125 CAP_PROP_FOCUS =28, 126 CAP_PROP_GUID =29, 127 CAP_PROP_ISO_SPEED =30, 128 CAP_PROP_BACKLIGHT =32, 129 CAP_PROP_PAN =33, 130 CAP_PROP_TILT =34, 131 CAP_PROP_ROLL =35, 132 CAP_PROP_IRIS =36, 133 CAP_PROP_SETTINGS =37 134 }; 135 136 137 // Generic camera output modes. 138 // Currently, these are supported through the libv4l interface only. 139 enum { CAP_MODE_BGR = 0, // BGR24 (default) 140 CAP_MODE_RGB = 1, // RGB24 141 CAP_MODE_GRAY = 2, // Y8 142 CAP_MODE_YUYV = 3 // YUYV 143 }; 144 145 146 // DC1394 only 147 // modes of the controlling registers (can be: auto, manual, auto single push, absolute Latter allowed with any other mode) 148 // every feature can have only one mode turned on at a time 149 enum { CAP_PROP_DC1394_OFF = -4, //turn the feature off (not controlled manually nor automatically) 150 CAP_PROP_DC1394_MODE_MANUAL = -3, //set automatically when a value of the feature is set by the user 151 CAP_PROP_DC1394_MODE_AUTO = -2, 152 CAP_PROP_DC1394_MODE_ONE_PUSH_AUTO = -1, 153 CAP_PROP_DC1394_MAX = 31 154 }; 155 156 157 // OpenNI map generators 158 enum { CAP_OPENNI_DEPTH_GENERATOR = 1 << 31, 159 CAP_OPENNI_IMAGE_GENERATOR = 1 << 30, 160 CAP_OPENNI_GENERATORS_MASK = CAP_OPENNI_DEPTH_GENERATOR + CAP_OPENNI_IMAGE_GENERATOR 161 }; 162 163 // Properties of cameras available through OpenNI interfaces 164 enum { CAP_PROP_OPENNI_OUTPUT_MODE = 100, 165 CAP_PROP_OPENNI_FRAME_MAX_DEPTH = 101, // in mm 166 CAP_PROP_OPENNI_BASELINE = 102, // in mm 167 CAP_PROP_OPENNI_FOCAL_LENGTH = 103, // in pixels 168 CAP_PROP_OPENNI_REGISTRATION = 104, // flag that synchronizes the remapping depth map to image map 169 // by changing depth generator's view point (if the flag is "on") or 170 // sets this view point to its normal one (if the flag is "off"). 171 CAP_PROP_OPENNI_REGISTRATION_ON = CAP_PROP_OPENNI_REGISTRATION, 172 CAP_PROP_OPENNI_APPROX_FRAME_SYNC = 105, 173 CAP_PROP_OPENNI_MAX_BUFFER_SIZE = 106, 174 CAP_PROP_OPENNI_CIRCLE_BUFFER = 107, 175 CAP_PROP_OPENNI_MAX_TIME_DURATION = 108, 176 CAP_PROP_OPENNI_GENERATOR_PRESENT = 109, 177 CAP_PROP_OPENNI2_SYNC = 110, 178 CAP_PROP_OPENNI2_MIRROR = 111 179 }; 180 181 // OpenNI shortcats 182 enum { CAP_OPENNI_IMAGE_GENERATOR_PRESENT = CAP_OPENNI_IMAGE_GENERATOR + CAP_PROP_OPENNI_GENERATOR_PRESENT, 183 CAP_OPENNI_IMAGE_GENERATOR_OUTPUT_MODE = CAP_OPENNI_IMAGE_GENERATOR + CAP_PROP_OPENNI_OUTPUT_MODE, 184 CAP_OPENNI_DEPTH_GENERATOR_BASELINE = CAP_OPENNI_DEPTH_GENERATOR + CAP_PROP_OPENNI_BASELINE, 185 CAP_OPENNI_DEPTH_GENERATOR_FOCAL_LENGTH = CAP_OPENNI_DEPTH_GENERATOR + CAP_PROP_OPENNI_FOCAL_LENGTH, 186 CAP_OPENNI_DEPTH_GENERATOR_REGISTRATION = CAP_OPENNI_DEPTH_GENERATOR + CAP_PROP_OPENNI_REGISTRATION, 187 CAP_OPENNI_DEPTH_GENERATOR_REGISTRATION_ON = CAP_OPENNI_DEPTH_GENERATOR_REGISTRATION 188 }; 189 190 // OpenNI data given from depth generator 191 enum { CAP_OPENNI_DEPTH_MAP = 0, // Depth values in mm (CV_16UC1) 192 CAP_OPENNI_POINT_CLOUD_MAP = 1, // XYZ in meters (CV_32FC3) 193 CAP_OPENNI_DISPARITY_MAP = 2, // Disparity in pixels (CV_8UC1) 194 CAP_OPENNI_DISPARITY_MAP_32F = 3, // Disparity in pixels (CV_32FC1) 195 CAP_OPENNI_VALID_DEPTH_MASK = 4, // CV_8UC1 196 197 // Data given from RGB image generator 198 CAP_OPENNI_BGR_IMAGE = 5, 199 CAP_OPENNI_GRAY_IMAGE = 6 200 }; 201 202 // Supported output modes of OpenNI image generator 203 enum { CAP_OPENNI_VGA_30HZ = 0, 204 CAP_OPENNI_SXGA_15HZ = 1, 205 CAP_OPENNI_SXGA_30HZ = 2, 206 CAP_OPENNI_QVGA_30HZ = 3, 207 CAP_OPENNI_QVGA_60HZ = 4 208 }; 209 210 211 // GStreamer 212 enum { CAP_PROP_GSTREAMER_QUEUE_LENGTH = 200 // default is 1 213 }; 214 215 216 // PVAPI 217 enum { CAP_PROP_PVAPI_MULTICASTIP = 300, // ip for anable multicast master mode. 0 for disable multicast 218 CAP_PROP_PVAPI_FRAMESTARTTRIGGERMODE = 301, // FrameStartTriggerMode: Determines how a frame is initiated 219 CAP_PROP_PVAPI_DECIMATIONHORIZONTAL = 302, // Horizontal sub-sampling of the image 220 CAP_PROP_PVAPI_DECIMATIONVERTICAL = 303, // Vertical sub-sampling of the image 221 CAP_PROP_PVAPI_BINNINGX = 304, // Horizontal binning factor 222 CAP_PROP_PVAPI_BINNINGY = 305, // Vertical binning factor 223 CAP_PROP_PVAPI_PIXELFORMAT = 306 // Pixel format 224 }; 225 226 // PVAPI: FrameStartTriggerMode 227 enum { CAP_PVAPI_FSTRIGMODE_FREERUN = 0, // Freerun 228 CAP_PVAPI_FSTRIGMODE_SYNCIN1 = 1, // SyncIn1 229 CAP_PVAPI_FSTRIGMODE_SYNCIN2 = 2, // SyncIn2 230 CAP_PVAPI_FSTRIGMODE_FIXEDRATE = 3, // FixedRate 231 CAP_PVAPI_FSTRIGMODE_SOFTWARE = 4 // Software 232 }; 233 234 // PVAPI: DecimationHorizontal, DecimationVertical 235 enum { CAP_PVAPI_DECIMATION_OFF = 1, // Off 236 CAP_PVAPI_DECIMATION_2OUTOF4 = 2, // 2 out of 4 decimation 237 CAP_PVAPI_DECIMATION_2OUTOF8 = 4, // 2 out of 8 decimation 238 CAP_PVAPI_DECIMATION_2OUTOF16 = 8 // 2 out of 16 decimation 239 }; 240 241 // PVAPI: PixelFormat 242 enum { CAP_PVAPI_PIXELFORMAT_MONO8 = 1, // Mono8 243 CAP_PVAPI_PIXELFORMAT_MONO16 = 2, // Mono16 244 CAP_PVAPI_PIXELFORMAT_BAYER8 = 3, // Bayer8 245 CAP_PVAPI_PIXELFORMAT_BAYER16 = 4, // Bayer16 246 CAP_PVAPI_PIXELFORMAT_RGB24 = 5, // Rgb24 247 CAP_PVAPI_PIXELFORMAT_BGR24 = 6, // Bgr24 248 CAP_PVAPI_PIXELFORMAT_RGBA32 = 7, // Rgba32 249 CAP_PVAPI_PIXELFORMAT_BGRA32 = 8, // Bgra32 250 }; 251 252 // Properties of cameras available through XIMEA SDK interface 253 enum { CAP_PROP_XI_DOWNSAMPLING = 400, // Change image resolution by binning or skipping. 254 CAP_PROP_XI_DATA_FORMAT = 401, // Output data format. 255 CAP_PROP_XI_OFFSET_X = 402, // Horizontal offset from the origin to the area of interest (in pixels). 256 CAP_PROP_XI_OFFSET_Y = 403, // Vertical offset from the origin to the area of interest (in pixels). 257 CAP_PROP_XI_TRG_SOURCE = 404, // Defines source of trigger. 258 CAP_PROP_XI_TRG_SOFTWARE = 405, // Generates an internal trigger. PRM_TRG_SOURCE must be set to TRG_SOFTWARE. 259 CAP_PROP_XI_GPI_SELECTOR = 406, // Selects general purpose input 260 CAP_PROP_XI_GPI_MODE = 407, // Set general purpose input mode 261 CAP_PROP_XI_GPI_LEVEL = 408, // Get general purpose level 262 CAP_PROP_XI_GPO_SELECTOR = 409, // Selects general purpose output 263 CAP_PROP_XI_GPO_MODE = 410, // Set general purpose output mode 264 CAP_PROP_XI_LED_SELECTOR = 411, // Selects camera signalling LED 265 CAP_PROP_XI_LED_MODE = 412, // Define camera signalling LED functionality 266 CAP_PROP_XI_MANUAL_WB = 413, // Calculates White Balance(must be called during acquisition) 267 CAP_PROP_XI_AUTO_WB = 414, // Automatic white balance 268 CAP_PROP_XI_AEAG = 415, // Automatic exposure/gain 269 CAP_PROP_XI_EXP_PRIORITY = 416, // Exposure priority (0.5 - exposure 50%, gain 50%). 270 CAP_PROP_XI_AE_MAX_LIMIT = 417, // Maximum limit of exposure in AEAG procedure 271 CAP_PROP_XI_AG_MAX_LIMIT = 418, // Maximum limit of gain in AEAG procedure 272 CAP_PROP_XI_AEAG_LEVEL = 419, // Average intensity of output signal AEAG should achieve(in %) 273 CAP_PROP_XI_TIMEOUT = 420 // Image capture timeout in milliseconds 274 }; 275 276 // Properties of cameras available through AVFOUNDATION interface 277 enum { CAP_PROP_IOS_DEVICE_FOCUS = 9001, 278 CAP_PROP_IOS_DEVICE_EXPOSURE = 9002, 279 CAP_PROP_IOS_DEVICE_FLASH = 9003, 280 CAP_PROP_IOS_DEVICE_WHITEBALANCE = 9004, 281 CAP_PROP_IOS_DEVICE_TORCH = 9005 282 }; 283 284 285 // Properties of cameras available through Smartek Giganetix Ethernet Vision interface 286 /* --- Vladimir Litvinenko (litvinenko.vladimir@gmail.com) --- */ 287 enum { CAP_PROP_GIGA_FRAME_OFFSET_X = 10001, 288 CAP_PROP_GIGA_FRAME_OFFSET_Y = 10002, 289 CAP_PROP_GIGA_FRAME_WIDTH_MAX = 10003, 290 CAP_PROP_GIGA_FRAME_HEIGH_MAX = 10004, 291 CAP_PROP_GIGA_FRAME_SENS_WIDTH = 10005, 292 CAP_PROP_GIGA_FRAME_SENS_HEIGH = 10006 293 }; 294 295 enum { CAP_PROP_INTELPERC_PROFILE_COUNT = 11001, 296 CAP_PROP_INTELPERC_PROFILE_IDX = 11002, 297 CAP_PROP_INTELPERC_DEPTH_LOW_CONFIDENCE_VALUE = 11003, 298 CAP_PROP_INTELPERC_DEPTH_SATURATION_VALUE = 11004, 299 CAP_PROP_INTELPERC_DEPTH_CONFIDENCE_THRESHOLD = 11005, 300 CAP_PROP_INTELPERC_DEPTH_FOCAL_LENGTH_HORZ = 11006, 301 CAP_PROP_INTELPERC_DEPTH_FOCAL_LENGTH_VERT = 11007 302 }; 303 304 // Intel PerC streams 305 enum { CAP_INTELPERC_DEPTH_GENERATOR = 1 << 29, 306 CAP_INTELPERC_IMAGE_GENERATOR = 1 << 28, 307 CAP_INTELPERC_GENERATORS_MASK = CAP_INTELPERC_DEPTH_GENERATOR + CAP_INTELPERC_IMAGE_GENERATOR 308 }; 309 310 enum { CAP_INTELPERC_DEPTH_MAP = 0, // Each pixel is a 16-bit integer. The value indicates the distance from an object to the camera's XY plane or the Cartesian depth. 311 CAP_INTELPERC_UVDEPTH_MAP = 1, // Each pixel contains two 32-bit floating point values in the range of 0-1, representing the mapping of depth coordinates to the color coordinates. 312 CAP_INTELPERC_IR_MAP = 2, // Each pixel is a 16-bit integer. The value indicates the intensity of the reflected laser beam. 313 CAP_INTELPERC_IMAGE = 3 314 }; 315 316 enum { VIDEOWRITER_PROP_QUALITY = 1, // Quality (0..100%) of the videostream encoded 317 VIDEOWRITER_PROP_FRAMEBYTES = 2, // (Read-only): Size of just encoded video frame 318 }; 319 320 // gPhoto2 properties, if propertyId is less than 0 then work on widget with that __additive inversed__ camera setting ID 321 // Get IDs by using CAP_PROP_GPHOTO2_WIDGET_ENUMERATE. 322 // @see CvCaptureCAM_GPHOTO2 for more info 323 enum { CAP_PROP_GPHOTO2_PREVIEW = 17001, // Capture only preview from liveview mode. 324 CAP_PROP_GPHOTO2_WIDGET_ENUMERATE = 17002, // Readonly, returns (const char *). 325 CAP_PROP_GPHOTO2_RELOAD_CONFIG = 17003, // Trigger, only by set. Reload camera settings. 326 CAP_PROP_GPHOTO2_RELOAD_ON_CHANGE = 17004, // Reload all settings on set. 327 CAP_PROP_GPHOTO2_COLLECT_MSGS = 17005, // Collect messages with details. 328 CAP_PROP_GPHOTO2_FLUSH_MSGS = 17006, // Readonly, returns (const char *). 329 CAP_PROP_SPEED = 17007, // Exposure speed. Can be readonly, depends on camera program. 330 CAP_PROP_APERTURE = 17008, // Aperture. Can be readonly, depends on camera program. 331 CAP_PROP_EXPOSUREPROGRAM = 17009, // Camera exposure program. 332 CAP_PROP_VIEWFINDER = 17010 // Enter liveview mode. 333 }; 334 335 //enum { 336 337 class IVideoCapture; 338 339 /** @brief Class for video capturing from video files, image sequences or cameras. The class provides C++ API 340 for capturing video from cameras or for reading video files and image sequences. Here is how the 341 class can be used: : 342 @code 343 #include "opencv2/opencv.hpp" 344 345 using namespace cv; 346 347 int main(int, char**) 348 { 349 VideoCapture cap(0); // open the default camera 350 if(!cap.isOpened()) // check if we succeeded 351 return -1; 352 353 Mat edges; 354 namedWindow("edges",1); 355 for(;;) 356 { 357 Mat frame; 358 cap >> frame; // get a new frame from camera 359 cvtColor(frame, edges, COLOR_BGR2GRAY); 360 GaussianBlur(edges, edges, Size(7,7), 1.5, 1.5); 361 Canny(edges, edges, 0, 30, 3); 362 imshow("edges", edges); 363 if(waitKey(30) >= 0) break; 364 } 365 // the camera will be deinitialized automatically in VideoCapture destructor 366 return 0; 367 } 368 @endcode 369 @note In C API the black-box structure CvCapture is used instead of VideoCapture. 370 371 @note 372 - A basic sample on using the VideoCapture interface can be found at 373 opencv_source_code/samples/cpp/starter_video.cpp 374 - Another basic video processing sample can be found at 375 opencv_source_code/samples/cpp/video_dmtx.cpp 376 - (Python) A basic sample on using the VideoCapture interface can be found at 377 opencv_source_code/samples/python2/video.py 378 - (Python) Another basic video processing sample can be found at 379 opencv_source_code/samples/python2/video_dmtx.py 380 - (Python) A multi threaded video processing sample can be found at 381 opencv_source_code/samples/python2/video_threaded.py 382 */ 383 class CV_EXPORTS_W VideoCapture 384 { 385 public: 386 /** @brief 387 @note In C API, when you finished working with video, release CvCapture structure with 388 cvReleaseCapture(), or use Ptr\<CvCapture\> that calls cvReleaseCapture() automatically in the 389 destructor. 390 */ 391 CV_WRAP VideoCapture(); 392 393 /** @overload 394 @param filename name of the opened video file (eg. video.avi) or image sequence (eg. 395 img_%02d.jpg, which will read samples like img_00.jpg, img_01.jpg, img_02.jpg, ...) 396 */ 397 CV_WRAP VideoCapture(const String& filename); 398 399 /** @overload 400 @param device id of the opened video capturing device (i.e. a camera index). If there is a single 401 camera connected, just pass 0. 402 */ 403 CV_WRAP VideoCapture(int device); 404 405 virtual ~VideoCapture(); 406 407 /** @brief Open video file or a capturing device for video capturing 408 409 @param filename name of the opened video file (eg. video.avi) or image sequence (eg. 410 img_%02d.jpg, which will read samples like img_00.jpg, img_01.jpg, img_02.jpg, ...) 411 412 The methods first call VideoCapture::release to close the already opened file or camera. 413 */ 414 CV_WRAP virtual bool open(const String& filename); 415 416 /** @overload 417 @param device id of the opened video capturing device (i.e. a camera index). 418 */ 419 CV_WRAP virtual bool open(int device); 420 421 /** @brief Returns true if video capturing has been initialized already. 422 423 If the previous call to VideoCapture constructor or VideoCapture::open succeeded, the method returns 424 true. 425 */ 426 CV_WRAP virtual bool isOpened() const; 427 428 /** @brief Closes video file or capturing device. 429 430 The methods are automatically called by subsequent VideoCapture::open and by VideoCapture 431 destructor. 432 433 The C function also deallocates memory and clears \*capture pointer. 434 */ 435 CV_WRAP virtual void release(); 436 437 /** @brief Grabs the next frame from video file or capturing device. 438 439 The methods/functions grab the next frame from video file or camera and return true (non-zero) in 440 the case of success. 441 442 The primary use of the function is in multi-camera environments, especially when the cameras do not 443 have hardware synchronization. That is, you call VideoCapture::grab() for each camera and after that 444 call the slower method VideoCapture::retrieve() to decode and get frame from each camera. This way 445 the overhead on demosaicing or motion jpeg decompression etc. is eliminated and the retrieved frames 446 from different cameras will be closer in time. 447 448 Also, when a connected camera is multi-head (for example, a stereo camera or a Kinect device), the 449 correct way of retrieving data from it is to call VideoCapture::grab first and then call 450 VideoCapture::retrieve one or more times with different values of the channel parameter. See 451 <https://github.com/Itseez/opencv/tree/master/samples/cpp/openni_capture.cpp> 452 */ 453 CV_WRAP virtual bool grab(); 454 455 /** @brief Decodes and returns the grabbed video frame. 456 457 The methods/functions decode and return the just grabbed frame. If no frames has been grabbed 458 (camera has been disconnected, or there are no more frames in video file), the methods return false 459 and the functions return NULL pointer. 460 461 @note OpenCV 1.x functions cvRetrieveFrame and cv.RetrieveFrame return image stored inside the video 462 capturing structure. It is not allowed to modify or release the image! You can copy the frame using 463 :ocvcvCloneImage and then do whatever you want with the copy. 464 */ 465 CV_WRAP virtual bool retrieve(OutputArray image, int flag = 0); 466 virtual VideoCapture& operator >> (CV_OUT Mat& image); 467 virtual VideoCapture& operator >> (CV_OUT UMat& image); 468 469 /** @brief Grabs, decodes and returns the next video frame. 470 471 The methods/functions combine VideoCapture::grab and VideoCapture::retrieve in one call. This is the 472 most convenient method for reading video files or capturing data from decode and return the just 473 grabbed frame. If no frames has been grabbed (camera has been disconnected, or there are no more 474 frames in video file), the methods return false and the functions return NULL pointer. 475 476 @note OpenCV 1.x functions cvRetrieveFrame and cv.RetrieveFrame return image stored inside the video 477 capturing structure. It is not allowed to modify or release the image! You can copy the frame using 478 :ocvcvCloneImage and then do whatever you want with the copy. 479 */ 480 CV_WRAP virtual bool read(OutputArray image); 481 482 /** @brief Sets a property in the VideoCapture. 483 484 @param propId Property identifier. It can be one of the following: 485 - **CAP_PROP_POS_MSEC** Current position of the video file in milliseconds. 486 - **CAP_PROP_POS_FRAMES** 0-based index of the frame to be decoded/captured next. 487 - **CAP_PROP_POS_AVI_RATIO** Relative position of the video file: 0 - start of the 488 film, 1 - end of the film. 489 - **CAP_PROP_FRAME_WIDTH** Width of the frames in the video stream. 490 - **CAP_PROP_FRAME_HEIGHT** Height of the frames in the video stream. 491 - **CAP_PROP_FPS** Frame rate. 492 - **CAP_PROP_FOURCC** 4-character code of codec. 493 - **CAP_PROP_FRAME_COUNT** Number of frames in the video file. 494 - **CAP_PROP_FORMAT** Format of the Mat objects returned by retrieve() . 495 - **CAP_PROP_MODE** Backend-specific value indicating the current capture mode. 496 - **CAP_PROP_BRIGHTNESS** Brightness of the image (only for cameras). 497 - **CAP_PROP_CONTRAST** Contrast of the image (only for cameras). 498 - **CAP_PROP_SATURATION** Saturation of the image (only for cameras). 499 - **CAP_PROP_HUE** Hue of the image (only for cameras). 500 - **CAP_PROP_GAIN** Gain of the image (only for cameras). 501 - **CAP_PROP_EXPOSURE** Exposure (only for cameras). 502 - **CAP_PROP_CONVERT_RGB** Boolean flags indicating whether images should be converted 503 to RGB. 504 - **CAP_PROP_WHITE_BALANCE** Currently unsupported 505 - **CAP_PROP_RECTIFICATION** Rectification flag for stereo cameras (note: only supported 506 by DC1394 v 2.x backend currently) 507 @param value Value of the property. 508 */ 509 CV_WRAP virtual bool set(int propId, double value); 510 511 /** @brief Returns the specified VideoCapture property 512 513 @param propId Property identifier. It can be one of the following: 514 - **CAP_PROP_POS_MSEC** Current position of the video file in milliseconds or video 515 capture timestamp. 516 - **CAP_PROP_POS_FRAMES** 0-based index of the frame to be decoded/captured next. 517 - **CAP_PROP_POS_AVI_RATIO** Relative position of the video file: 0 - start of the 518 film, 1 - end of the film. 519 - **CAP_PROP_FRAME_WIDTH** Width of the frames in the video stream. 520 - **CAP_PROP_FRAME_HEIGHT** Height of the frames in the video stream. 521 - **CAP_PROP_FPS** Frame rate. 522 - **CAP_PROP_FOURCC** 4-character code of codec. 523 - **CAP_PROP_FRAME_COUNT** Number of frames in the video file. 524 - **CAP_PROP_FORMAT** Format of the Mat objects returned by retrieve() . 525 - **CAP_PROP_MODE** Backend-specific value indicating the current capture mode. 526 - **CAP_PROP_BRIGHTNESS** Brightness of the image (only for cameras). 527 - **CAP_PROP_CONTRAST** Contrast of the image (only for cameras). 528 - **CAP_PROP_SATURATION** Saturation of the image (only for cameras). 529 - **CAP_PROP_HUE** Hue of the image (only for cameras). 530 - **CAP_PROP_GAIN** Gain of the image (only for cameras). 531 - **CAP_PROP_EXPOSURE** Exposure (only for cameras). 532 - **CAP_PROP_CONVERT_RGB** Boolean flags indicating whether images should be converted 533 to RGB. 534 - **CAP_PROP_WHITE_BALANCE** Currently not supported 535 - **CAP_PROP_RECTIFICATION** Rectification flag for stereo cameras (note: only supported 536 by DC1394 v 2.x backend currently) 537 538 @note When querying a property that is not supported by the backend used by the VideoCapture 539 class, value 0 is returned. 540 */ 541 CV_WRAP virtual double get(int propId) const; 542 543 protected: 544 Ptr<CvCapture> cap; 545 Ptr<IVideoCapture> icap; 546 }; 547 548 class IVideoWriter; 549 550 /** @brief Video writer class. 551 */ 552 class CV_EXPORTS_W VideoWriter 553 { 554 public: 555 /** @brief VideoWriter constructors 556 557 The constructors/functions initialize video writers. On Linux FFMPEG is used to write videos; on 558 Windows FFMPEG or VFW is used; on MacOSX QTKit is used. 559 */ 560 CV_WRAP VideoWriter(); 561 562 /** @overload 563 @param filename Name of the output video file. 564 @param fourcc 4-character code of codec used to compress the frames. For example, 565 VideoWriter::fourcc('P','I','M','1') is a MPEG-1 codec, VideoWriter::fourcc('M','J','P','G') is a 566 motion-jpeg codec etc. List of codes can be obtained at [Video Codecs by 567 FOURCC](http://www.fourcc.org/codecs.php) page. 568 @param fps Framerate of the created video stream. 569 @param frameSize Size of the video frames. 570 @param isColor If it is not zero, the encoder will expect and encode color frames, otherwise it 571 will work with grayscale frames (the flag is currently supported on Windows only). 572 */ 573 CV_WRAP VideoWriter(const String& filename, int fourcc, double fps, 574 Size frameSize, bool isColor = true); 575 576 virtual ~VideoWriter(); 577 578 /** @brief Initializes or reinitializes video writer. 579 580 The method opens video writer. Parameters are the same as in the constructor 581 VideoWriter::VideoWriter. 582 */ 583 CV_WRAP virtual bool open(const String& filename, int fourcc, double fps, 584 Size frameSize, bool isColor = true); 585 586 /** @brief Returns true if video writer has been successfully initialized. 587 */ 588 CV_WRAP virtual bool isOpened() const; 589 590 /** @brief Closes the video writer. 591 592 The methods are automatically called by subsequent VideoWriter::open and by the VideoWriter 593 destructor. 594 */ 595 CV_WRAP virtual void release(); 596 virtual VideoWriter& operator << (const Mat& image); 597 598 /** @brief Writes the next video frame 599 600 @param image The written frame 601 602 The functions/methods write the specified image to video file. It must have the same size as has 603 been specified when opening the video writer. 604 */ 605 CV_WRAP virtual void write(const Mat& image); 606 607 /** @brief Sets a property in the VideoWriter. 608 609 @param propId Property identifier. It can be one of the following: 610 - **VIDEOWRITER_PROP_QUALITY** Quality (0..100%) of the videostream encoded. Can be adjusted dynamically in some codecs. 611 @param value Value of the property. 612 */ 613 CV_WRAP virtual bool set(int propId, double value); 614 615 /** @brief Returns the specified VideoWriter property 616 617 @param propId Property identifier. It can be one of the following: 618 - **VIDEOWRITER_PROP_QUALITY** Current quality of the encoded videostream. 619 - **VIDEOWRITER_PROP_FRAMEBYTES** (Read-only) Size of just encoded video frame; note that the encoding order may be different from representation order. 620 621 @note When querying a property that is not supported by the backend used by the VideoWriter 622 class, value 0 is returned. 623 */ 624 CV_WRAP virtual double get(int propId) const; 625 626 /** @brief Concatenates 4 chars to a fourcc code 627 628 This static method constructs the fourcc code of the codec to be used in the constructor 629 VideoWriter::VideoWriter or VideoWriter::open. 630 */ 631 CV_WRAP static int fourcc(char c1, char c2, char c3, char c4); 632 633 protected: 634 Ptr<CvVideoWriter> writer; 635 Ptr<IVideoWriter> iwriter; 636 637 static Ptr<IVideoWriter> create(const String& filename, int fourcc, double fps, 638 Size frameSize, bool isColor = true); 639 }; 640 641 template<> CV_EXPORTS void DefaultDeleter<CvCapture>::operator ()(CvCapture* obj) const; 642 template<> CV_EXPORTS void DefaultDeleter<CvVideoWriter>::operator ()(CvVideoWriter* obj) const; 643 644 //! @} videoio 645 646 } // cv 647 648 #endif //__OPENCV_VIDEOIO_HPP__ 649