◆VideoCapture()[1/6]-活动查询-元素星在线活动查询中心

2026-02-15 15:40:26
admin

用于从视频文件、图像序列或摄像头捕获视频的类。更多…

#include

cv::VideoCapture 的协作图

公共成员函数

VideoCapture ()

默认构造函数。

VideoCapture (const Ptr< IStreamReader > &source, int apiPreference, const std::vector< int > ¶ms)

使用数据流打开视频。

VideoCapture (const String &filename, int apiPreference, const std::vector< int > ¶ms)

使用 API 首选项和参数打开视频文件或捕获设备或 IP 视频流进行视频捕获。

VideoCapture (const String &filename, int apiPreference=CAP_ANY)

使用 API 首选项打开视频文件或捕获设备或 IP 视频流进行视频捕获。

VideoCapture (int index, int apiPreference, const std::vector< int > ¶ms)

使用 API 首选项和参数打开摄像头进行视频捕获。

VideoCapture (int index, int apiPreference=CAP_ANY)

打开摄像头进行视频捕获。

virtual ~VideoCapture ()

默认析构函数。

virtual double get (int propId) const

返回指定的 VideoCapture 属性。

String getBackendName () const

返回使用的后端 API 名称。

bool getExceptionMode () const

查询异常模式是否处于活动状态

virtual bool grab ()

从视频文件或捕获设备抓取下一帧。

virtual bool isOpened () const

如果视频捕获已初始化，则返回 true。

virtual bool open (const Ptr< IStreamReader > &source, int apiPreference, const std::vector< int > ¶ms)

使用数据流打开视频。

virtual bool open (const String &filename, int apiPreference, const std::vector< int > ¶ms)

使用 API 首选项和参数打开视频文件或捕获设备或 IP 视频流进行视频捕获。

virtual bool open (const String &filename, int apiPreference=CAP_ANY)

打开视频文件或捕获设备或 IP 视频流进行视频捕获。

virtual bool open (int index, int apiPreference, const std::vector< int > ¶ms)

使用 API 首选项和参数打开摄像头进行视频捕获。

virtual bool open (int index, int apiPreference=CAP_ANY)

打开摄像头进行视频捕获。

virtual VideoCapture & operator>> (Mat &image)

流运算符，用于读取下一视频帧。

virtual VideoCapture & operator>> (UMat &image)

virtual bool read (OutputArray image)

抓取、解码并返回下一视频帧。

virtual void release ()

关闭视频文件或捕获设备。

virtual bool retrieve (OutputArray image, int flag=0)

解码并返回已抓取的视频帧。

virtual bool set (int propId, double value)

设置 VideoCapture 中的属性。

void setExceptionMode (bool enable)

静态公共成员函数

static bool waitAny (const std::vector< VideoCapture > &streams, std::vector< int > &readyIndex, int64 timeoutNs=0)

等待来自 VideoCapture 的就绪帧。

受保护的属性

Ptr< CvCapture > cap

Ptr< IVideoCapture > icap

bool throwOnFail

友元

类 internal::VideoCapturePrivateAccessor

详细描述

用于从视频文件、图像序列或摄像头捕获视频的类。

此类提供 C++ API，用于从摄像头捕获视频或读取视频文件和图像序列。

以下是此类的使用方法

#include

using namespace cv;

using namespace std;

int main(int, char**)

{

Mat frame;

//--- 初始化 VIDEOCAPTURE

VideoCapture cap;

// 使用默认 API 打开默认摄像头

// cap.open(0);

// 或高级用法：选择任何 API 后端

int deviceID = 0; // 0 = 打开默认摄像头

int apiID = cv::CAP_ANY; // 0 = 自动检测默认API

// 使用选择的API打开选定的摄像头

cap.open(deviceID, apiID);

// 检查是否打开成功

if (!cap.isOpened()) {

cerr << "错误！无法打开摄像头\n";

return -1;

}

//--- 抓取和写入循环

cout << "开始抓取" << endl

<< "按任意键终止" << endl;

for (;;)

{

// 等待来自摄像头的新的帧并将其存储到'frame'中

cap.read(frame);

// 检查是否打开成功

if (frame.empty()) {

cerr << "错误！抓取到空帧\n";

break;

}

// 显示实时画面并使用足够长的超时时间等待按键以显示图像

imshow("实时画面", frame);

if (waitKey(5) >= 0)

break;

}

// 摄像头将在VideoCapture析构函数中自动解除初始化

return 0;

}

cv::Matn维密集数组类定义 mat.hpp:829

cv::Mat::emptybool empty() const如果数组没有元素，则返回true。

cv::VideoCapture用于从视频文件、图像序列或摄像头捕获视频的类。定义 videoio.hpp:766

cv::VideoCapture::readvirtual bool read(OutputArray image)抓取、解码并返回下一视频帧。

cv::VideoCapture::openvirtual bool open(const String &filename, int apiPreference=CAP_ANY)打开视频文件或捕获设备或 IP 视频流进行视频捕获。

cv::VideoCapture::isOpenedvirtual bool isOpened() const如果视频捕获已初始化，则返回 true。

core.hpp

cv::CAP_ANY@ CAP_ANY自动检测 == 0。定义 videoio.hpp:96

highgui.hpp

mainint main(int argc, char *argv[])定义 highgui_qt.cpp:3

cv定义 core.hpp:107

stdSTL命名空间。

videoio.hpp

注意在C API中，使用黑盒结构CvCapture代替VideoCapture。

(C++) 使用VideoCapture接口的基本示例可以在OPENCV_SOURCE_CODE/samples/cpp/videocapture_starter.cpp中找到。

(Python) 使用VideoCapture接口的基本示例可以在OPENCV_SOURCE_CODE/samples/python/video.py中找到。

(Python) 多线程视频处理示例可以在OPENCV_SOURCE_CODE/samples/python/video_threaded.py中找到。

(Python) 演示Video4Linux2后端一些特性的VideoCapture示例OPENCV_SOURCE_CODE/samples/python/video_v4l2.py

示例samples/cpp/camshiftdemo.cpp, samples/cpp/facedetect.cpp, samples/cpp/laplace.cpp, samples/cpp/lkdemo.cpp, samples/cpp/peopledetect.cpp, samples/cpp/polar_transforms.cpp, samples/cpp/segment_objects.cpp, samples/cpp/train_HOG.cpp, samples/cpp/tutorial_code/videoio/video-write/video-write.cpp, samples/cpp/videowriter_basic.cpp, samples/dnn/classification.cpp, samples/dnn/object_detection.cpp, samples/dnn/segmentation.cpp, samples/dnn/text_detection.cpp, 和 samples/tapi/hog.cpp。

构造函数和析构函数文档

◆ VideoCapture() [1/6]

cv::VideoCapture::VideoCapture

(

)

Pythoncv.VideoCapture() -> cv.VideoCapture(filename[, apiPreference]) -> cv.VideoCapture(filename, apiPreference, params) -> cv.VideoCapture(index[, apiPreference]) -> cv.VideoCapture(index, apiPreference, params) -> cv.VideoCapture(source, apiPreference, params) ->

默认构造函数。

注意在C API中，当您完成视频处理后，使用cvReleaseCapture()释放CvCapture结构，或者使用Ptr，它会在析构函数中自动调用cvReleaseCapture()。

◆ VideoCapture() [2/6]

cv::VideoCapture::VideoCapture

(

const String & filename,

int apiPreference = CAP_ANY )

explicit

使用 API 首选项打开视频文件或捕获设备或 IP 视频流进行视频捕获。

这是一个重载的成员函数，为了方便提供。它与上面的函数的区别仅仅在于它接受的参数。

参数

filename它可以是

视频文件名 (例如：video.avi)

或图像序列 (例如：img_%02d.jpg，它将读取诸如img_00.jpg, img_01.jpg, img_02.jpg, ...之类的样本)

或视频流的URL (例如：protocol://host:port/script_name?script_params|auth)

或者如果使用GStreamer作为后端，则为gst-launch工具格式中的GStreamer管道字符串。请注意，每个视频流或IP摄像机馈送都有其自己的URL方案。请参考源流的文档以了解正确的URL。

apiPreference首选的捕获API后端。如果有多个可用，则可用于强制使用特定的读取器实现：例如 cv::CAP_FFMPEG 或 cv::CAP_IMAGES 或 cv::CAP_DSHOW。

另请参见cv::VideoCaptureAPIs

◆ VideoCapture() [3/6]

cv::VideoCapture::VideoCapture

(

const String & filename,

int apiPreference,

const std::vector< int > & params )

explicit

使用 API 首选项和参数打开视频文件或捕获设备或 IP 视频流进行视频捕获。

这是一个重载的成员函数，为了方便提供。它与上面的函数的区别仅仅在于它接受的参数。

params参数允许指定编码为(paramId_1, paramValue_1, paramId_2, paramValue_2, ...)对的额外参数。参见 cv::VideoCaptureProperties

◆ VideoCapture() [4/6]

cv::VideoCapture::VideoCapture

(

int index,

int apiPreference = CAP_ANY )

explicit

打开摄像头进行视频捕获。

这是一个重载的成员函数，为了方便提供。它与上面的函数的区别仅仅在于它接受的参数。

参数

index要打开的视频采集设备的ID。要使用默认后端打开默认摄像头，只需传入0。（为了向后兼容，当apiPreference为CAP_ANY时，可以使用camera_id + domain_offset (CAP_*)）

apiPreference首选的捕获API后端。如果有多个可用，则可以使用它来强制使用特定的读取器实现：例如 cv::CAP_DSHOW 或 cv::CAP_MSMF 或 cv::CAP_V4L。

另请参见cv::VideoCaptureAPIs

◆ VideoCapture() [5/6]

cv::VideoCapture::VideoCapture

(

int index,

int apiPreference,

const std::vector< int > & params )

explicit

使用 API 首选项和参数打开摄像头进行视频捕获。

这是一个重载的成员函数，为了方便提供。它与上面的函数的区别仅仅在于它接受的参数。

params参数允许指定编码为(paramId_1, paramValue_1, paramId_2, paramValue_2, ...)对的额外参数。参见 cv::VideoCaptureProperties

◆ VideoCapture() [6/6]

cv::VideoCapture::VideoCapture

(

const Ptr< IStreamReader > & 数据源,

int apiPreference,

const std::vector< int > & params )

使用数据流打开视频。

这是一个重载的成员函数，为了方便提供。它与上面的函数的区别仅仅在于它接受的参数。

params参数允许指定编码为(paramId_1, paramValue_1, paramId_2, paramValue_2, ...)对的额外参数。参见 cv::VideoCaptureProperties

◆ ~VideoCapture()

virtual cv::VideoCapture::~VideoCapture

(

)

虚函数

默认析构函数。

该方法首先调用 VideoCapture::release 关闭已打开的文件或摄像头。

成员函数文档

◆ get()

virtual double cv::VideoCapture::get

(

int 属性ID)

const

虚函数

Pythoncv.VideoCapture.get(属性ID) -> 返回值

返回指定的 VideoCapture 属性。

参数

属性ID来自 cv::VideoCaptureProperties 的属性标识符（例如 cv::CAP_PROP_POS_MSEC，cv::CAP_PROP_POS_FRAMES，…）或来自 Additional flags for video I/O API backends 的属性标识符

返回指定属性的值。当查询VideoCapture实例使用的后端不支持的属性时，返回的值为0。

注意读取/写入属性涉及许多层。在这个过程中可能会发生一些意想不到的结果。VideoCapture -> API后端 -> 操作系统 -> 设备驱动程序 -> 设备硬件

返回值可能与设备实际使用的值不同，或者它可能使用设备相关的规则（例如，步长或百分比）进行编码。实际行为取决于设备驱动程序和API后端。

示例samples/cpp/laplace.cpp.

◆ getBackendName()

String cv::VideoCapture::getBackendName

(

)

const

Pythoncv.VideoCapture.getBackendName() -> 返回值

返回使用的后端 API 名称。

注意流应该已经打开。

◆ getExceptionMode()

bool cv::VideoCapture::getExceptionMode

(

)

const

内联函数

Pythoncv.VideoCapture.getExceptionMode() -> 返回值

查询异常模式是否处于活动状态

◆ grab()

virtual bool cv::VideoCapture::grab

(

)

虚函数

Pythoncv.VideoCapture.grab() -> 返回值

从视频文件或捕获设备抓取下一帧。

返回成功时返回true（非零）。

该方法/函数从视频文件或摄像头抓取下一帧，并在成功时返回true（非零）。

该函数的主要用途是在多摄像机环境中，尤其是在摄像机没有硬件同步的情况下。也就是说，您为每个摄像机调用 VideoCapture::grab()，然后调用较慢的方法 VideoCapture::retrieve() 来解码并从每个摄像机获取帧。这样可以消除去马赛克或运动JPEG解压缩等的开销，并且从不同摄像机检索的帧在时间上会更接近。

此外，当连接的摄像头是多头的（例如，立体摄像头或Kinect设备）时，从其检索数据的正确方法是首先调用 VideoCapture::grab()，然后使用通道参数的不同值调用 VideoCapture::retrieve() 一次或多次。

使用Kinect和其他兼容OpenNI的深度传感器

◆ isOpened()

virtual bool cv::VideoCapture::isOpened

(

)

const

虚函数

Pythoncv.VideoCapture.isOpened() -> 返回值

如果视频捕获已初始化，则返回 true。

如果之前对 VideoCapture 构造函数或 VideoCapture::open() 的调用成功，则该方法返回true。

示例samples/cpp/camshiftdemo.cpp，samples/cpp/facedetect.cpp，samples/cpp/laplace.cpp，samples/cpp/lkdemo.cpp，samples/cpp/peopledetect.cpp，samples/cpp/polar_transforms.cpp，samples/cpp/segment_objects.cpp，samples/cpp/train_HOG.cpp，samples/cpp/videowriter_basic.cpp 和 samples/tapi/hog.cpp。

◆ open() [1/5]

virtual bool cv::VideoCapture::open

(

const Ptr< IStreamReader > & 数据源,

int apiPreference,

const std::vector< int > & params )

虚函数

Pythoncv.VideoCapture.open(filename[, apiPreference]) -> 返回值cv.VideoCapture.open(filename, apiPreference, params) -> 返回值cv.VideoCapture.open(index[, apiPreference]) -> 返回值cv.VideoCapture.open(index, apiPreference, params) -> 返回值cv.VideoCapture.open(source, apiPreference, params) -> 返回值

使用数据流打开视频。

这是一个重载的成员函数，为了方便提供。它与上面的函数的区别仅仅在于它接受的参数。

params参数允许指定编码为(paramId_1, paramValue_1, paramId_2, paramValue_2, ...)对的额外参数。参见 cv::VideoCaptureProperties

返回如果文件已成功打开，则返回true

该方法首先调用 VideoCapture::release 关闭已打开的文件或摄像头。

◆ open() [2/5]

virtual bool cv::VideoCapture::open

(

const String & filename,

int apiPreference,

const std::vector< int > & params )

虚函数

使用 API 首选项和参数打开视频文件或捕获设备或 IP 视频流进行视频捕获。

这是一个重载的成员函数，为了方便提供。它与上面的函数的区别仅仅在于它接受的参数。

params参数允许指定编码为(paramId_1, paramValue_1, paramId_2, paramValue_2, ...)对的额外参数。参见 cv::VideoCaptureProperties

返回如果文件已成功打开，则返回true

该方法首先调用 VideoCapture::release 关闭已打开的文件或摄像头。

◆ open() [3/5]

virtual bool cv::VideoCapture::open

(

const String & filename,

int apiPreference = CAP_ANY )

虚函数

打开视频文件或捕获设备或 IP 视频流进行视频捕获。

这是一个重载的成员函数，为了方便提供。它与上面的函数的区别仅仅在于它接受的参数。

参数与构造函数 VideoCapture(const String& filename, int apiPreference = CAP_ANY) 相同

返回如果文件已成功打开，则返回true

该方法首先调用 VideoCapture::release 关闭已打开的文件或摄像头。

示例samples/cpp/camshiftdemo.cpp，samples/cpp/facedetect.cpp，samples/cpp/laplace.cpp，samples/cpp/lkdemo.cpp，samples/cpp/peopledetect.cpp，samples/cpp/polar_transforms.cpp，samples/cpp/segment_objects.cpp，samples/cpp/train_HOG.cpp，samples/dnn/classification.cpp，samples/dnn/object_detection.cpp，samples/dnn/segmentation.cpp，samples/dnn/text_detection.cpp 和 samples/tapi/hog.cpp。

◆ open() [4/5]

virtual bool cv::VideoCapture::open

(

int index,

int apiPreference,

const std::vector< int > & params )

虚函数

使用 API 首选项和参数打开摄像头进行视频捕获。

这是一个重载的成员函数，为了方便提供。它与上面的函数的区别仅仅在于它接受的参数。

params参数允许指定编码为(paramId_1, paramValue_1, paramId_2, paramValue_2, ...)对的额外参数。参见 cv::VideoCaptureProperties

返回如果摄像头成功打开，则返回true。

该方法首先调用 VideoCapture::release 关闭已打开的文件或摄像头。

◆ open() [5/5]

virtual bool cv::VideoCapture::open

(

int index,

int apiPreference = CAP_ANY )

虚函数

打开摄像头进行视频捕获。

这是一个重载的成员函数，为了方便提供。它与上面的函数的区别仅仅在于它接受的参数。

参数与构造函数VideoCapture(int index, int apiPreference = CAP_ANY)相同。

返回如果摄像头成功打开，则返回true。

该方法首先调用 VideoCapture::release 关闭已打开的文件或摄像头。

◆ operator>>() [1/2]

virtual VideoCapture & cv::VideoCapture::operator>>

(

Mat & image)

虚函数

流运算符，用于读取下一视频帧。

另请参见read()

◆ operator>>() [2/2]

virtual VideoCapture & cv::VideoCapture::operator>>

(

UMat & image)

虚函数

这是一个重载的成员函数，为了方便提供。它与上面的函数的区别仅仅在于它接受的参数。

另请参见read()

◆ read()

virtual bool cv::VideoCapture::read

(

OutputArray image)

虚函数

Pythoncv.VideoCapture.read([, image]) -> retval, image

抓取、解码并返回下一视频帧。

参数

[out]image视频帧将返回此处。如果未抓取任何帧，则图像将为空。

返回如果未抓取任何帧，则返回false

此方法/函数将VideoCapture::grab() 和 VideoCapture::retrieve() 组合在一个调用中。这是读取视频文件或从解码中捕获数据的便捷方法，并返回刚刚抓取的帧。如果未抓取任何帧（摄像头已断开连接，或者视频文件中没有更多帧），则该方法返回false，函数返回空图像（使用cv::Mat，用Mat::empty()测试）。

注意在C API中，函数cvRetrieveFrame()和cv.RetrieveFrame()返回存储在视频捕获结构中的图像。不允许修改或释放图像！可以使用cvCloneImage复制帧，然后对副本执行任何操作。

示例samples/cpp/videowriter_basic.cpp.

◆ release()

virtual void cv::VideoCapture::release

(

)

虚函数

Pythoncv.VideoCapture.release() -> 无

关闭视频文件或捕获设备。

此方法会由后续的VideoCapture::open和VideoCapture析构函数自动调用。

C函数还释放内存并清除*capture指针。

◆ retrieve()

virtual bool cv::VideoCapture::retrieve

(

OutputArray image,

int flag = 0 )

虚函数

Pythoncv.VideoCapture.retrieve([, image[, flag]]) -> retval, image

解码并返回已抓取的视频帧。

参数

[out]image视频帧将返回此处。如果未抓取任何帧，则图像将为空。

flag它可以是帧索引或驱动程序特定的标志

返回如果未抓取任何帧，则返回false

此方法解码并返回刚刚抓取的帧。如果未抓取任何帧（摄像头已断开连接，或者视频文件中没有更多帧），则该方法返回false，函数返回空图像（使用cv::Mat，用Mat::empty()测试）。

另请参见read()

◆ set()

virtual bool cv::VideoCapture::set

(

int 属性ID,

double value )

虚函数

Pythoncv.VideoCapture.set(propId, value) -> 返回值

设置 VideoCapture 中的属性。

参数

属性ID来自 cv::VideoCaptureProperties 的属性标识符（例如 cv::CAP_PROP_POS_MSEC，cv::CAP_PROP_POS_FRAMES，…）或来自 Additional flags for video I/O API backends 的属性标识符

value属性的值。

返回如果VideoCapture实例使用的后端支持该属性，则返回true。

注意即使它返回true，也不能保证捕获设备已接受属性值。请参见VideoCapture::get()中的说明

示例samples/cpp/laplace.cpp.

◆ setExceptionMode()

void cv::VideoCapture::setExceptionMode

(

bool enable)

内联函数

Pythoncv.VideoCapture.setExceptionMode(enable) -> 无

切换异常模式

如果方法不成功，则引发异常，而不是返回错误代码。

◆ waitAny()

static bool cv::VideoCapture::waitAny

(

const std::vector< VideoCapture > & streams,

std::vector< int > & readyIndex,

int64 timeoutNs = 0 )

static

Pythoncv.VideoCapture.waitAny(streams[, timeoutNs]) -> retval, readyIndexcv.VideoCapture_waitAny(streams[, timeoutNs]) -> retval, readyIndex

等待来自 VideoCapture 的就绪帧。

参数

streams输入视频流

readyIndex具有已抓取帧的流索引（准备使用。retrieve()获取实际帧）

timeoutNs纳秒数（0 - 无限）

返回如果streamReady不为空，则返回true

异常

异常流错误时的异常（使用。isOpened()过滤掉格式错误的流）或不支持VideoCapture类型

此函数的主要用途在于多摄像头环境。如果摄像头已准备好，则该方法填充就绪状态向量，抓取视频帧。

此调用之后，使用VideoCapture::retrieve()解码并获取帧数据。

友元和相关符号文档

◆ internal::VideoCapturePrivateAccessor

friend class internal::VideoCapturePrivateAccessor

friend

成员数据文档

◆ cap

Ptr cv::VideoCapture::cap

protected

◆ icap

Ptr cv::VideoCapture::icap

protected

◆ throwOnFail

bool cv::VideoCapture::throwOnFail

protected

此类的文档是从以下文件生成的：

opencv2/videoio.hpp

◆VideoCapture()[1/6]

福卡怎么用，详细的使用教程