C接口取图流程和取图方式

C接口取图流程和取图方式

一、设备连接接口流程

        对设备进行操作，实现图像采集、参数配置等功能，需要先连接设备（打开设备），具体流程如下图所示。

详细步骤：

1. （可选）调用 MV_CC_EnumDevices() 枚举子网内指定传输协议对应的所有设备。
   可以通过pstDevList在结构 MV_CC_DEVICE_INFO_LIST 中找到设备的信息。
2. （可选）在打开指定设备之前，调用 MV_CC_IsDeviceAccessible() 检查指定设备是否可访问。
3. 调用 MV_CC_CreateHandle() 以创建设备句柄。
4. 调用 MV_CC_OpenDevice() 打开设备。
5. （可选）执行以下一个或多个操作：

   获取设备信息	MV_CC_GetDeviceInfo()
   获得最佳包大小(仅对网口相机有效)	MV_CC_GetOptimalPacketSize()

6. （可选）其他操作，例如图像采集和显示、参数配置等。有关详细信息，请参阅后面的章节。
7. 调用 MV_CC_CloseDevice() 关闭设备。
8. 调用 MV_CC_DestroyHandle() 来销毁句柄并释放资源。

            示例：

示例代码，仅供参考。

#include "MvCameraControl.h"
void main()
{
    int nRet = -1;
    void*  m_handle = NULL;

    //枚举子网内指定的传输协议对应的所有设备
    unsigned int nTLayerType = MV_GIGE_DEVICE | MV_USB_DEVICE;
    MV_CC_DEVICE_INFO_LIST m_stDevList = {0};
    int nRet = MV_CC_EnumDevices(nTLayerType, &m_stDevList);
    if (MV_OK != nRet)
    {
        printf("error: EnumDevices fail [%x]\n", nRet);
        return;
    }

    int i = 0;
    if (m_stDevList.nDeviceNum == 0)
    {
        printf("no camera found!\n");
        return;
    }

    //选择查找到的第一台在线设备，创建设备句柄
    int nDeviceIndex = 0;

    MV_CC_DEVICE_INFO m_stDevInfo = {0};
    memcpy(&m_stDevInfo, m_stDevList.pDeviceInfo[nDeviceIndex], sizeof(MV_CC_DEVICE_INFO));

    nRet = MV_CC_CreateHandle(&m_handle, &m_stDevInfo);

    if (MV_OK != nRet)
    {
        printf("error: CreateHandle fail [%x]\n", nRet);
        return;
    }

    //连接设备
    unsigned int nAccessMode = MV_ACCESS_Exclusive;
    unsigned short nSwitchoverKey = 0;
    nRet = MV_CC_OpenDevice(m_handle, nAccessMode, nSwitchoverKey);
    if (MV_OK != nRet)
    {
        printf("error: OpenDevice fail [%x]\n", nRet);
        return;
    }

    //...其他处理

    //关闭设备，释放资源
    nRet = MV_CC_CloseDevice(m_handle);
    if (MV_OK != nRet)
    {
        printf("error: CloseDevice fail [%x]\n", nRet);
        return;
    } 
    
    //销毁句柄，释放资源
    nRet = MV_CC_DestroyHandle(m_handle);
    if (MV_OK != nRet)
    {
        printf("error: DestroyHandle fail [%x]\n", nRet);
        return;
    }
}

二、主动取流流程图

        SDK提供主动获取图像的接口，用户可以在开启取流后直接调用此接口获取图像，也可以使用异步方式（线程、定时器等）获取图像。示例代码详见 GrabImage.cpp 和 GrabImage_HighPerformance.cpp 。

• 主动获取图像有两种方式（两种方式不能同时使用）：
  方式一：调用 MV_CC_StartGrabbing() 开始采集，需要自己开启一个buffer，然后在应用层循环调用 MV_CC_GetOneFrameTimeout() 获取指定像素格式的帧数据，获取帧数据时上层应用程序需要根据帧率控制好调用该接口的频率。
  方式二：调用 MV_CC_StartGrabbing() 开始采集，然后在应用层调用 MV_CC_GetImageBuffer() 获取指定像素格式的帧数据，然后调用 MV_CC_FreeImageBuffer() 释放buffer，获取帧数据时上层应用程序需要根据帧率控制好调用该接口的频率。
  
• 主动取图方式使用的场景：
  主动取图方式需要先调用 MV_CC_StartGrabbing() 启动图像采集。上层应用程序需要根据帧率，控制好调用主动取图接口的频率。两种主动取图方式都支持设置超时时间，SDK内部等待直到有数据时返回，可以增加取流平稳性，适合用于对平稳性要求较高的场合。
• 两种主动取图方式的区别：
  a、 MV_CC_GetImageBuffer() 需要与 MV_CC_FreeImageBuffer() 配套使用，当处理完取到的数据后，需要用 MV_CC_FreeImageBuffer() 接口将pstFrame内的数据指针权限进行释放。
  b、 MV_CC_GetImageBuffer() 与 MV_CC_GetOneFrameTimeout() 相比，有着更高的效率。且其取流缓存的分配是由sdk内部自动分配的，而 MV_CC_GetOneFrameTimeout() 接口是需要客户自行分配。
• 注意事项：
  a、两种主动取图方式不能同时使用，且不能与后面的回调取图方式同时使用，三种取图方式只能使用其中一种。
  b、Pdata返回的是一个地址指针，建议将Pdata里面的数据copy出来另建线程使用。

详细步骤：

1. (可选)调用 MV_CC_EnumDevices() 枚举子网内指定传输协议对应的所有设备。
   可以通过pstDevList在结构 MV_CC_DEVICE_INFO_LIST 中找到设备的信息。
2. (可选)在打开指定设备之前，调用 MV_CC_IsDeviceAccessible() 检查指定设备是否可访问。
3. 调用 MV_CC_CreateHandle() 以创建设备句柄。
4. (可选)执行以下一个或多个操作以获取/设置相机不同类型的参数。

   获取/设置 Bool 类型节点值	MV_CC_GetBoolValue() / MV_CC_SetBoolValue()
   获取/设置 Enum 类型节点值	MV_CC_GetEnumValue() / MV_CC_SetEnumValue()
   获取/设置 Float 类型节点值	MV_CC_GetFloatValue() / MV_CC_SetFloatValue()
   获取/设置 Int 类型节点值	MV_CC_GetIntValueEx() / MV_CC_SetIntValueEx()
   获取/设置 String 类型节点值	MV_CC_GetStringValue() / MV_CC_SetStringValue()
   设置 Command 类型节点值	MV_CC_SetCommandValue()

   
   说明：
   1. 相机所有开放的属性值都可参考相机参数节点表 进行查询，此节点表对每个节点的名称、数据类型、数值范围定义、访问模式和节点描述进行了详细说明。
   例如：
   1. 单帧、多帧和持续采集模式的设置获取如下：
      MV_CC_SetEnumValue (handle, "AcquisitionMode", value)//设置采集模式，类型为Enumeration。
      MV_CC_GetEnumValue(handle, "AcquisitionMode", &stEnumValue)//获取采集模式。
      
   2. 触发参数配置：
      1) 通过MV_CC_SetEnumValue(handle, " TriggerMode", value)来设置触发模式。
      2) 如果开启了触发模式，则需要配置触发源MV_CC_SetEnumValue(handle, " TriggerSource", value)，相机触发源包括硬件触发和软触发。
      3) 对应的相机触发延时时间通过MV_CC_GetFloatValue(handle, " TriggerDelay", &stFloatValue)、MV_CC_SetFloatValue(handle, " TriggerDelay", value)可以获取和设置。
      4) 相机触发源设置为软触发模式之后需要调用MV_CC_SetCommandValue(handle, "TriggerSoftware ")触发抓拍，而硬件触发模式时由设备本地硬件输入进行触发。
      
   3. 图像参数配置：
      包括图像宽高、像素格式、帧率、AIO偏移量、增益、曝光模式、曝光值、亮度、锐度、饱和度、灰度、白平衡、Gamma值等参数，都可用万能接口进行配置包括图像宽高、像素格式、帧率、AIO偏移量、增益、曝光模式、曝光值、亮度、锐度、饱和度、灰度、白平衡、Gamma值等参数，都可用万能接口进行配置 MV_CC_SetIntValueEx 、 MV_CC_SetEnumValue、 MV_CC_SetEnumValue、 MV_CC_SetBoolValue、 MV_CC_SetStringValue、 MV_CC_SetCommandValue；通用配置接口详见“模块”中“相机参数设置”节点下的”通用配置接口 ”。
5. 图像采集：
   1. 调用 MV_CC_StartGrabbing() 开始获取流。
      • 在开始采集之前，可以调用 MV_CC_SetImageNodeNum() 设置SDK内部图像缓存节点个数。设置该节点个数，当SDK内部已获取的图像数超过这个值后，自动丢弃最早的图像数据。
      • 采集到原始图像数据可以调用 MV_CC_ConvertPixelType() 转换图像的像素格式，也可以调用 MV_CC_SaveImageEx2() 转成JPEG或者BMP等格式的图片数据然后保存成图片文件。
   2. 在应用程序层中重复调用 MV_CC_GetOneFrameTimeout() 或 MV_CC_GetImageBuffer() 来获取图像数据。
      • 该接口为主动式获取帧数据，上层应用程序需要根据帧率，控制好调用该接口的频率。
6. 调用 MV_CC_DisplayOneFrame() 输入窗口句柄并开始显示。
7. 调用 MV_CC_StopGrabbing() 停止采集。
8. 调用 MV_CC_CloseDevice() 关闭设备。
9. 调用 MV_CC_DestroyHandle() 来销毁句柄并释放资源。

三、回调出流流程图

        SDK提供注册回调函数的接口，用户可以将自己定义的回调函数注册在SDK内部，SDK获取到相机图像会主动回调到应用程序供用户处理，此方式可以简化用户程序逻辑。示例代码详见 Grab_ImageCallback.cpp 。

• 回调取图方式：
  您可以使用 MV_CC_RegisterImageCallBackEx() 接口注册回调函数。回调函数可以自定义，用于自动回调获取的图像。此方法可以简化应用程序逻辑。如果你想设置获取RGB24或BGR24格式的图像数据，也可以使用 MV_CC_RegisterImageCallBackForRGB() 或 MV_CC_RegisterImageCallBackForBGR() 来注册回调函数。
• 注意事项：
  a、回调函数中不建议有耗时操作、线程锁等，容易造成回调阻塞。
  b、Pdata返回的是一个地址指针，建议将Pdata里面的数据copy出来另建线程使用。

详细步骤：

1. (可选)调用 MV_CC_EnumDevices() 枚举子网内指定传输协议对应的所有设备。
   可以通过pstDevList在结构 MV_CC_DEVICE_INFO_LIST 中找到设备的信息。
2. (可选)在打开指定设备之前，调用 MV_CC_IsDeviceAccessible() 检查指定设备是否可访问。
3. 调用 MV_CC_CreateHandle() 以创建设备句柄。
4. (可选)执行以下一个或多个操作以获取/设置相机不同类型的参数。

   获取/设置 Bool 类型节点值	MV_CC_GetBoolValue() / MV_CC_SetBoolValue()
   获取/设置 Enum 类型节点值	MV_CC_GetEnumValue() / MV_CC_SetEnumValue()
   获取/设置 Float 类型节点值	MV_CC_GetFloatValue() / MV_CC_SetFloatValue()
   获取/设置 Int 类型节点值	MV_CC_GetIntValueEx() / MV_CC_SetIntValueEx()
   获取/设置 String 类型节点值	MV_CC_GetStringValue() / MV_CC_SetStringValue()
   设置 Command 类型节点值	MV_CC_SetCommandValue()

   
   说明：
   1. 相机所有开放的属性值都可参相机参数节点表 进行查询，此节点表对每个节点的名称、数据类型、数值范围定义、访问模式和节点描述进行了详细说明。
   例如：
   1. 单帧、多帧和持续采集模式的设置获取如下：
      MV_CC_SetEnumValue (handle, "AcquisitionMode", value)//设置采集模式，类型为Enumeration。
      MV_CC_GetEnumValue(handle, "AcquisitionMode", &stEnumValue)//获取采集模式。
      
   2. 触发参数配置：
      1) 通过MV_CC_SetEnumValue(handle, " TriggerMode", value)来设置触发模式。
      2) 如果开启了触发模式，则需要配置触发源MV_CC_SetEnumValue(handle, " TriggerSource", value)，相机触发源包括硬件触发和软触发。
      3) 对应的相机触发延时时间通过MV_CC_GetFloatValue(handle, " TriggerDelay", &stFloatValue)、MV_CC_SetFloatValue(handle, " TriggerDelay", value)可以获取和设置。
      4) 相机触发源设置为软触发模式之后需要调用MV_CC_SetCommandValue(handle, "TriggerSoftware ")触发抓拍，而硬件触发模式时由设备本地硬件输入进行触发。
      
   3. 图像参数配置：
      包括图像宽高、像素格式、帧率、AIO偏移量、增益、曝光模式、曝光值、亮度、锐度、饱和度、灰度、白平衡、Gamma值等参数，都可用万能接口进行配置包括图像宽高、像素格式、帧率、AIO偏移量、增益、曝光模式、曝光值、亮度、锐度、饱和度、灰度、白平衡、Gamma值等参数，都可用万能接口进行配置 MV_CC_SetIntValueEx 、 MV_CC_SetEnumValue、 MV_CC_SetEnumValue、 MV_CC_SetBoolValue、 MV_CC_SetStringValue、 MV_CC_SetCommandValue；通用配置接口详见“模块”中“相机参数设置”节点下的”通用配置接口 ”。
5. 图像采集：
   1. 调用 MV_CC_RegisterImageCallBackEx() 来设置数据回调函数。
   2. 调用 MV_CC_StartGrabbing() 开始采集。
      • 对于原始图像数据，可以调用 MV_CC_ConvertPixelType() 来转换图像像素格式，也可以调用 MV_CC_SaveImageEx2() 将图像转换为JPEG或BMP格式并保存为文件。(建议另建线程处理，不要影响取图线程)
6. 调用 MV_CC_DisplayOneFrame() 输入窗口句柄并开始显示。
7. 调用 MV_CC_StopGrabbing() 停止采集。
8. 调用 MV_CC_CloseDevice() 关闭设备。
9. 调用 MV_CC_DestroyHandle() 来销毁句柄并释放资源。