/**
* @file videocapture_starter.cpp
* @brief 一个使用OpenCV的VideoCapture与捕获设备，视频文件或图像序列的入门示例
* 就像CV_PI一样简单，对吧？
*
*  创建于: 2010年11月23日
*      作者: Ethan Rublee
*
*  修改于: 2013年4月17日
*      作者: Kevin Hughes
*/


#include <opencv2/imgcodecs.hpp>  // 包含处理图像编解码的功能
#include <opencv2/videoio.hpp>    // 包含处理视频读写的功能
#include <opencv2/highgui.hpp>    // 包含GUI函数以及视频读写功能


#include <iostream>   // 包含基本输入输出功能
#include <stdio.h>    // 包含C语言标准输入输出库


using namespace cv;  // 使用命名空间cv，避免每次调用OpenCV功能时都要加cv::前缀
using namespace std; // 使用标准命名空间std，避免每次都要加std::前缀


// 在匿名命名空间中隐藏局部函数
namespace {
    void help(char** av) {  // help函数提供了使用说明
        cout << "The program captures frames from a video file, image sequence (01.jpg, 02.jpg ... 10.jpg) or camera connected to your computer." << endl
             << "Usage:\n" << av[0] << " <video file, image sequence or device number>" << endl
             << "q,Q,esc -- quit" << endl  // 按q、Q或esc键退出程序
             << "space   -- save frame" << endl << endl  // 按空格键保存帧（图片）
             << "\tTo capture from a camera pass the device number. To find the device number, try ls /dev/video*" << endl
             << "\texample: " << av[0] << " 0" << endl  // 提供了如何使用摄像头设备进行捕获的示例
             << "\tYou may also pass a video file instead of a device number" << endl
             << "\texample: " << av[0] << " video.avi" << endl  // 提供了如何打开视频文件的示例
             << "\tYou can also pass the path to an image sequence and OpenCV will treat the sequence just like a video." << endl
             << "\texample: " << av[0] << " right%%02d.jpg" << endl;  // 提供了如何打开图像序列的示例
    }


    int process(VideoCapture& capture) {  // process函数用于处理视频捕获的过程
        int n = 0;
        char filename[200];  // 用于存储文件名的字符数组
        string window_name = "video | q or esc to quit";  // 显示窗口的名称
        cout << "press space to save a picture. q or esc to quit" << endl; // 提示用户按空格保存图片，按q或esc退出
        namedWindow(window_name, WINDOW_KEEPRATIO); // 创建一个可调整大小的窗口
        Mat frame; // 创建一个Mat对象，用于存储每一帧图像数据


        for (;;) {
            capture >> frame; // 从VideoCapture对象中获取一帧图像到frame中
            if (frame.empty()) // 如果帧为空，则退出循环
                break;


            imshow(window_name, frame); // 显示当前帧
            char key = (char)waitKey(30); // 等待30毫秒，如果有按键则返回按键值


            switch (key) {
            case 'q':
            case 'Q':
            case 27: // 按esc键
                return 0;  // 退出程序
            case ' ': // 按空格键，保存一幅图像
                snprintf(filename,sizeof(filename),"filename%.3d.jpg",n++);
                imwrite(filename,frame);  // 将当前帧保存为文件
                cout << "Saved " << filename << endl;
                break;
            default:
                break;
            }
        }
        return 0;
    }
}


int main(int ac, char** av) {
    CommandLineParser parser(ac, av, "{help h||}{@input||}"); // 命令行解析器，用于解析命令行参数
    if (parser.has("help"))  // 如果指定了help参数，则显示帮助信息
    {
        help(av);  // 调用help函数
        return 0;
    }
    string arg = parser.get<string>("@input"); // 获取输入参数，可能是视频文件名、图像序列或设备号
    if (arg.empty()) {  // 如果没有输入参数，则显示帮助信息并退出
        help(av);
        return 1;
    }
    VideoCapture capture(arg); // 尝试以视频文件名或图像序列的形式打开输入
    if (!capture.isOpened()) // 如果打开失败，则尝试将输入当作视频设备号来打开
        capture.open(atoi(arg.c_str()));
    if (!capture.isOpened()) { // 如果还是打开失败，显示错误信息并显示帮助信息后退出
        cerr << "Failed to open the video device, video file or image sequence!\n" << endl;
        help(av);
        return 1;
    }
    return process(capture); // 调用process函数处理视频捕获过程
}

这段代码是一个使用OpenCV库进行视频捕获的C++程序例子。程序可以从视频文件、图像序列（如01.jpg, 02.jpg等）或连接到计算机的摄像头中捕获帧。用户可以通过命令行参数指定输入源，并且通过按键操作来保存帧或退出程序。程序首先定义了两个函数：help函数用于显示使用方法，process函数用于捕获视频并处理按键操作。在main函数中，程序会根据命令行参数尝试打开视频拍摄设备、视频文件或图像序列文件，并在成功打开后调用process函数来捕获和处理视频帧。如果无法打开指定的输入源，则会提示错误信息并显示帮助信息。