Omegonprocam API 手册

 


1. 版本和平台



2. 简介


Omegonprocam系列相机支持多种API, 包括:Native C/C++, .NET(C#和VB.NET), Python, Java, DirectShow, Twain, LabView, MatLab等等. Native C/C++ API作为底层(Low Level) API相比较其他API的特点是使用纯C/C++开发, 不依赖其他的运行时库, 接口简洁, 控制灵活. 本SDK压缩包包含了所有需要用到的的资源和信息, 目录如下:

omegonprocam.h, C/C++头文件


3. 概念和术语


a. 获取图像数据的模式: “Pull” Mode vs “Push” Mode (“拉”模式 vs “推”模式)

Omegonprocam提供了两种模式来获取图像数据: Pull Mode 和 Push Mode. 以下所讲的几种方式中, 从功能上说它们都是平等的, 开发者可以任选一种使用. 推荐使用拉模式, 因为它更简单,且在多线程情况下更加不容易出错, 尤其是使用windows消息机制的情况下.

在Pull Mode 情况下, omegonprocam不但可以通知应用程序图像数据或者静态图片到达, 还可以通知其他事件类型, 如下所示:

事件 来源 描述
OMEGONPROCAM_EVENT_EXPOSURE 软件 曝光时间发生改变
OMEGONPROCAM_EVENT_TEMPTINT 白平衡参数发生改变,Temp/Tint模式, 请参阅这里.
OMEGONPROCAM_EVENT_WBGAIN 白平衡参数发生改变,RGB Gain模式, 请参阅这里.
OMEGONPROCAM_EVENT_IMAGE 视频图像数据到达(视频). 使用Omegonprocam_PullImageXXXX“拉”图像数据
OMEGONPROCAM_EVENT_STILLIMAGE 静态图片数据到达(Omegonprocam_Snap或Omegonprocam_SnapN引发). 使用Omegonprocam_PullImageXXXX“拉”图像数据
OMEGONPROCAM_EVENT_ERROR 一般性错误, 数据采集不能继续
OMEGONPROCAM_EVENT_DISCONNECTED 相机断开连接, 如被拔出
OMEGONPROCAM_EVENT_NOFRAMETIMEOUT 规定时间内没有抓取到视频帧. 见OMEGONPROCAM_OPTION_NOFRAME_TIMEOUT
OMEGONPROCAM_EVENT_NOPACKETTIMEOUT 规定时间内没有抓取到视频包. 见OMEGONPROCAM_OPTION_NOPACKET_TIMEOUT
OMEGONPROCAM_EVENT_TRIGGERFAIL 触发失败(如帧数据错误或超时)
OMEGONPROCAM_EVENT_BLACK 黑平衡参数发生改变
OMEGONPROCAM_EVENT_FFC 平场校正(flat field correction)状态发生改变
OMEGONPROCAM_EVENT_DFC 暗场校正(dark field correction)状态发生改变
OMEGONPROCAM_EVENT_FPNC 固定模式噪声校正(fixed pattern noise correction)状态发生改变
OMEGONPROCAM_EVENT_ROI ROI发生改变
OMEGONPROCAM_EVENT_LEVELRANGE Level range 发生改变
OMEGONPROCAM_EVENT_AUTOEXPO_CONV 自动曝光收敛
OMEGONPROCAM_EVENT_AUTOEXPO_CONVFAIL 单次模式自动曝光收敛失败
OMEGONPROCAM_EVENT_FACTORY 恢复出厂设置
OMEGONPROCAM_EVENT_EXPO_START 硬件 硬件事件:曝光开始
OMEGONPROCAM_EVENT_EXPO_STOP 硬件事件:曝光结束
OMEGONPROCAM_EVENT_TRIGGER_ALLOW 硬件事件:触发允许
OMEGONPROCAM_EVENT_TRIGGER_IN 硬件事件:触发进入
OMEGONPROCAM_EVENT_HEARTBEAT 硬件事件:心跳, 可以用于监视相机是否存活. 参见OMEGONPROCAM_OPTION_HEARTBEAT

b. 静态抓拍(静态图片, Still Image, Snap)

大部分的相机型号都支持所谓静态抓拍的能力, 指相机在连续的视频预览过程中, 临时切换到另外一个分辨率, 抓取一帧静态图片之后, 马上把分辨率切换回原始分辨率的过程.

举例来说, UCMOS05100KPA支持3种分辨率, 假设当前视频预览分辨率为1280 * 960, 调用函数Omegonprocam_Snap(h, 0)静态抓拍分辨率2592 * 1944的静态图片, 这时相机临时切换到2592 * 1944的分辨率, 抓取一帧数据之后, 又把分辨率切换成原来的1280 * 960.

a) 拉模式下, 抓拍到静态图片之后, 通知外层应用OMEGONPROCAM_EVENT_STILLIMAGE事件, 然后外层应用调用Omegonprocam_PullStillImage(V2)获取静态图片的数据.
b) 推模式下, 抓拍到静态图片之后, 回调函数POMEGONPROCAM_DATA_CALLBACK_V4/V3, 参数bSnap设置为TRUE, 图片的分辨率等信息在参数pHeader中.

可以通过函数Omegonprocam_get_StillResolutionNumber的返回值或者结构OmegonprocamModelV2的still值来查看是否支持静态抓拍能力.

c. 数据格式: RGB vs RAW

Omegonprocam支持两种数据格式: RGB格式(默认)和RAW格式. RAW模式可以通过调用函数Omegonprocam_put_Option设置参数OMEGONPROCAM_OPTION_RAW为1开启.

用户可以通过OMEGONPROCAM_OPTION_RAW调用函数Omegonprocam_put_Option来切换这两种模式. 请注意相机必须处于非运行状态才能修改此设置.

用户可以通过OMEGONPROCAM_OPTION_RGB调用函数Omegonprocam_put_Option来设置RGB的bits数. 请注意相机必须处于非运行状态才能修改此设置.

d. 白平衡和自动白平衡: Temp/Tint模式 vs RGB Gain模式

1. Omegonprocam支持互相独立的两种模式描述白平衡: a) Temp/Tint模式; b) RGB Gain模式

a) 默认是Temp/Tint模式, 在本模式下, 使用Temp, Tint这2个参数来控制白平衡. Omegonprocam_get_TempTint获取值, Omegonprocam_put_TempTint设置值. Omegonprocam_AwbOnce执行自动白平衡. 当白平衡参数改变时, 发送OMEGONPROCAM_EVENT_TEMPTINT通知消息.

b) 在RGB Gain模式下, 使用3个通道的Gain值来控制白平衡. Omegonprocam_get_WhiteBalanceGain获取值, Omegonprocam_put_WhiteBalanceGain设置值. Omegonprocam_AwbInit执行自动白平衡. 当白平衡参数改变时, 发送OMEGONPROCAM_EVENT_WBGAIN通知消息.

两种模式下使用的函数不能混淆:

a) Temp/Tint模式下, 必须使用Omegonprocam_get_TempTint和Omegonprocam_put_TempTint和Omegonprocam_AwbOnce. 而Omegonprocam_get_WhiteBalanceGain和Omegonprocam_put_WhiteBalanceGain和Omegonprocam_AwbInit不能使用, 永远返回E_NOTIMPL.
b) RGB Gain模式下, 必须使用Omegonprocam_get_WhiteBalanceGain和Omegonprocam_put_WhiteBalanceGain和Omegonprocam_AwbInit. 而Omegonprocam_get_TempTint和Omegonprocam_put_TempTint和Omegonprocam_AwbOnce不能使用, 永远返回E_NOTIMPL

两种模式在相机打开的时候指定, 除非关闭相机重新打开, 一旦指定就不能更改. 参阅这里.

2. 自动白平衡功能, 业界有两种模式, 一种是连续自动白平衡,一种是触发式自动白平衡(once). 连续自动白平衡功能会一直进行白平衡参数的计算, 触发模式只是在触发的时候才会计算白平衡参数. Omegonprocam使用触发式白平衡计算方法, 因为这种方法在显微镜等领域更加合适和精确. 连续自动白平衡在某些场景情况下会出现错误.

3. 黑白相机不支持白平衡. 以上提到的函数一直返回E_NOTIMPL.

e. 触发模式

1. 什么是触发

Omegonprocam相机拥有2中工作模式: 视频模式和触发模式. 当处于触发模式时, 只有触发条件满足的情况下才能获取图像. 根据触发源有2种类型的触发类型: 外部触发, 软件触发.

2. 触发和Snap(静态图像抓拍)的区别

触发模式被设计用来精确控制相机当且仅当触发条件满足时才能获取图像. 用户可以通过控制预设的触发条件获取图像. 当进入触发模式时, 直到触发条件被满足才能得到图像. 图像的分辨率没有改变. Snap(静态图像抓拍)是用来在视频模式下抓取相同或者不同分辨率的图像.

3. 软件触发

相机可以被软件触发. 在软件触发模式下, 通过软件来控制触发条件. 图像的张数也可以软件控制.

4. 外部触发

相机可以被外部信号触发. 当前仅支持上升沿触发模式.

5. 混合触发

外部触发+软件触发同时启用.

6. 模拟触发

对于既不支持软件触发又不支持外部触发的相机, 可以使用模拟触发. 当处于模拟触发模式时, 相机硬件的工作模式和视频模式下的工作模式没有区别, 但是上层软件不发起抓取动作, 软件内部的缓冲区保持为空, 直到用户设置触发条件.

7. 怎样进入触发模式

枚举相机时, 可以得到相机型号的能力标志位, 查看相机对于触发模式的支持能力, 定义如下:
#define OMEGONPROCAM_FLAG_TRIGGER_SOFTWARE   0x00080000  /* 支持软触发 */
#define OMEGONPROCAM_FLAG_TRIGGER_EXTERNAL   0x00100000  /* 支持外部触发 */
#define OMEGONPROCAM_FLAG_TRIGGER_SINGLE     0x00200000  /* 仅支持单张触发: 一次触发得到一张图像 */
可以使用函数Omegonprocam_put_Option(HOmegonprocam h, unsigned iOption, int iValue)设置相机的触发模式, 其中iOption参数为OMEGONPROCAM_OPTION_TRIGGER, iValue用于设置触发模式的类型. 请参阅以下内容:
#define OMEGONPROCAM_OPTION_TRIGGER   0x0b    /* 0 = 视频模式, 1 = 软件或模拟触发模式, 2 = 外部触发模式, 3 = 外部触发+软件触发模式;默认值 = 0 */
函数Omegonprocam_get_Option(HOmegonprocam h, unsigned iOption, int* piValue)可以用来获取当前相机的触发模式类型.

8. 怎样触发相机

使用函数Omegonprocam_Trigger(HOmegonprocam h, unsigned short nNumber). 不同的nNumber的含义:
nNumber = 0 取消触发.
nNumber = 0xFFFF 一直触发, 类似于视频模式;
nNumber = 其他合法值代表单次触发获取的图片张数.
如果OMEGONPROCAM_FLAG_TRIGGER_SINGLE标志位是设置的, 那么nNumber参数只能为1, 意味着单次触发只能获取单张图片.
在调用Omegonprocam_Trigger函数之前, 相机必须已经处于触发模式.

9. 触发超时

超时时间建议不少于(曝光时间 * 102% + 4秒).

4. 函数



5. .NET(C#和VB.NET)


Omegonprocam支持.NET开发环境(C#和VB.NET).

omegonprocam.cs使用P/Invoke调用至omegonprocam.dll. 把omegonprocam.cs拷贝到你的C#工程中使用, 请参考示例代码.

请主意Omegonprocam C#包装类的实例通过静态方法Open或者OpenByIndex得到, 而不是通常的obj = new Omegonprocam(构造函数特意是私有的).

绝大多数Omegonprocam类的方法和属性都P/Invoke调用至omegonprocam.dll/so中对应的原生C/C++ Omegonprocam_xxx函数. 所以, 关于Omegonprocam_xxx的文档说明都适用于C#中对应的属性或方法, 比如, C#中的Snap方法调用Omegonprocam_Snap函数, 关于Omegonprocam_Snap函数的说明同样适用于C# Omegonprocam类的Snap方法:

[DllImport("omegonprocam.dll", ExactSpelling = true, CallingConvention = CallingConvention.StdCall)]
private static extern int Omegonprocam_Snap(SafeHOmegonprocamHandle h, uint nResolutionIndex);

public bool Snap(uint nResolutionIndex)
{
    if (_handle == null || _handle.IsInvalid || _handle.IsClosed)
        return false;
    return (Omegonprocam_Snap(_handle, nResolutionIndex) >= 0);
}

VB.NET和C#是类似的, 不另说明.


6. Python


Omegonprocam支持Python(版本3.0及以上)开发, 请import omegonprocam导入omegonprocam.py, 参考示例代码simplest.py和qt.py.

请注意omegonprocam.Omegonprocam python包装类的实例通过类方法(classmethod)Open或者OpenByIndex得到, 而不是通常的obj = omegonprocam.Omegonprocam().

绝大多数Omegonprocam类的方法都通过ctypes调用至omegonprocam.dll/so/dylib中对应的原生C/C++ Omegonprocam_xxx函数. 所以, 关于Omegonprocam_xxx的文档说明都适用于python中的对应方法.

参见omegonprocam.py中的__errcheck, 原始的HRESULT返回值被映射成HRESULTException异常(win32平台从OSError继承).

omegonprocam dll/so/dylib库文件请和omegonprocam.py存放在同一目录.


7. Java


Omegonprocam支持Java开发. omegonprocam.java使用JNA调用至omegonprocam.dll/so/dylib. 把omegonprocam.java拷贝到你的JAVA工程中使用, 请参考示例代码simplest.java(控制台程序), javafx.java, swing.java.

请注意omegonprocam java包装类的实例通过静态方法Open或者OpenByIndex得到, 而不是通常的obj = new omegonprocam()(构造函数特意是私有的).

绝大多数omegonprocam类的方法都通过JNA调用至omegonprocam.dll/so/dylib中对应的原生C/C++ Omegonprocam_xxx函数. 所以, 关于Omegonprocam_xxx的文档说明都适用于java中的对应方法.

参见omegonprocam.java中的errcheck, 原始的HRESULT返回值被映射成HRESULTException异常.

提醒: (1)从github下载jna-*.jar并加入依赖库; (2)omegonprocam.dll/so/dylib放在合适目录


8. 示例


名称 平台 语言 依赖 界面 描述
demosimplest Win32
Linux
macOS
Android
C++   console 最简单的示例, 大约70行代码. 截图.
demowait 不使用回调函数, 使用Omegonprocam_WaitImageV3获取图像, 大约60行代码.
demomulti 打开所有枚举到的相机(可能多台)并获取图像, 大约90行代码.
demostill 最简单的静态图像抓拍, 大约120行代码.
demosofttrigger 最简单的软触发示例, 大约80行代码.
demotriggersync 同步软触发(TriggerSync)示例, 大约80行代码.
demoexternaltrigger 最简单的外部触发示例, 大约130行代码.
demotriggerout 最简单的输出信号示例, 大约150行代码.
demoraw RAW数据, 静态抓拍以及保存RAW数据到*.raw文件, 大约140行代码. 截图.
demostillraw 静态RAW抓拍并保存到*.raw文件, 大约140行代码.
demoqt Win32
Linux
macOS
Qt GUI Qt示例, 截图.
枚举设备, 打开设备, 预览视频, 抓拍(静态)图像, 设置分辨率, 保存图像到文件, 设置自动曝光和白平衡, 帧率(fps)计算, 等等. 这个示例使用Pull Mode机制, StartPullModeWithCallback
demotwoqt Qt示例, 截图.
同时打开2台相机
democpp Win32 ATL/WTL 截图. 枚举设备(响应设备插入/拔出通知), 初始化支持GigE, 打开设备, 预览视频, 抓拍图像, 设置分辨率, 触发, 多种图片格式(.bmp, .jpg, .png等)保存图像到文件, wmv格式录像, 触发模式, IO控制, 读写EEPROM/FLASH等等. 这个示例使用Pull Mode机制. 为了保持代码整洁, 示例使用的WTL库可以从这个链接下载http://sourceforge.net/projects/wtl
democallback 截图. 使用Pull Mode模式, StartPullModeWithCallback
demopush 截图. 使用Push Mode机制, StartPushModeV4
demomono 演示黑白相机的8和16bits
democns 截图. 一致性测试: 图像平均划分成m*n个区域, 每个区域取中心的小块区域计算平均值, 把平均值连成线条, 查看线条上下波动幅度.
triggertest 截图. 软触发测试, 使用后台线程保存图像文件到磁盘(推荐SSD, 否则当磁盘速度不足时, 会导致存盘速度跟不上, 队列中的图像越攒越多, 消耗内存也越来越大).
demomfc MFC 截图. 打开设备, 预览视频, 抓拍图像, 设置分辨率, 多种图片格式(.bmp, .jpg, .png等)保存图像到文件, 等等. 这个示例使用Pull Mode机制
autotest 截图. 自动测试工具(用于自动测试开关相机, 分辨率切换, 抓拍, ROI, 位深度切换等等)
demowpf .NET C# WPF winwpf示例, 截图.
支持枚举设备, 打开设备, 预览视频, 抓拍(静态)图像, 保存图片到文件, 设置自动曝光和白平衡, 帧率(fps)计算, 等等. 这个示例使用Pull Mode机制, StartPullModeWithCallback
demowinformcs WinForm winform示例, 截图.
支持枚举设备, 打开设备, 预览视频, 抓拍(静态)图像, 保存图片到文件, 设置自动曝光和白平衡, 帧率(fps)计算, 等等. 这个示例使用Pull Mode机制, StartPullModeWithCallback
demotwocs winform示例, 截图.
同时打开2台相机, 使用Pull Mode机制, StartPullModeWithCallback
demowinformvb VB.NET winform示例, 截图.
支持枚举设备, 打开设备, 预览视频, 抓拍(静态)图像, 保存图片到文件, 设置自动曝光和白平衡, 帧率(fps)计算, 等等. 这个示例使用Pull Mode机制, StartPullModeWithCallback
demouwp WinRT C#   UWP(Universal Windows Platform)简单示例, 截图
编译运行示例之前请注意文件Package.appxmanifest中的DeviceCapability下的vid
demoandroid Android C++, Java Android示例
demojava simplest Win32
Linux
macOS
Java jna console 最简单java示例. IntelliJ工程
javafx GUI javafx示例. IntelliJ工程
swing swing示例. IntelliJ工程
demopython simplest Python console 最简单python示例
qt PyQt GUI PyQt示例, 截图.
demodshow DirectShow C++ MFC DirectShow示例
amcap 微软directshow示例, https://github.com/microsoft/Windows-classic-samples/tree/main/Samples/Win7Samples/multimedia/directshow/capture/amcap
LVDemo1 LabView     Labview示例单台相机
LVDemo2 Labview示例同时打开两台相机
imagepro liveedf Win32 C++ Qt Qt示例, snapshot.
C# WinForm C#示例, snapshot.
livestack C++ Qt Qt示例, snapshot.
C# WinForm C#示例, snapshot.

9. 更新历史


v55: 增加支持HDR Pixel Format

v54: 增加支持GigE. 请参阅这里

v53: 增加OmegonprocamFrameInfoV3, Omegonprocam_PullImageV3, Omegonprocam_StartPushModeV4

v52: 安卓Java侧传递文件描述符给Omegonprocam_Open打开相机. 请参阅这里

v51: 支持自动曝光“单次”模式. 请参阅这里

v50: Windows(x86/x64), Linux(x64), Android(x64)平台上SIMD加速
       前端和后端队列长度: OMEGONPROCAM_OPTION_FRONTEND_DEQUE_LENGTHOMEGONPROCAM_OPTION_BACKEND_DEQUE_LENGTH

v49: 增加支持相机配置的保存和加载. 请参阅这里

v48: 硬件事件. 请参阅这里这里这里

v47: 硬件Level Range. 请参阅这里这里

v46: 增加Denose支持, 请参阅这里

v45: 增加支持sequencer trigger, UART, 混合触发(外触发同时启用软件触发)

v44: 扩充了实时realtime模式, 请参阅这里
       增加OMEGONPROCAM_OPTION_CALLBACK_THREAD和OMEGONPROCAM_OPTION_FRAME_DEQUE_LENGTH

v43: 触发模式下发生错误时, 可以用OMEGONPROCAM_OPTION_RELOAD恢复最后一帧的数据

v42: 帧率精确控制和带宽, 请参阅这里和OMEGONPROCAM_FLAG_PRECISE_FRAMERATE

v41: 增加包超时, 请参阅这里

v40: 增加自动测试工具, 见samples\autotest

v39: 更新C#/VB.NET/Java/Python

v38: 增加运行时修改字节序, BGR/RGB, 请参阅这里

v37: 增加Android支持
       增加Omegonprocam_StartPushModeV3 (Omegonprocam_StartPushModeV2和Omegonprocam_StartPushMode过时)

v36: 增加Java支持. 请参阅这里

v35: 增加Python支持. 请参阅这里

v34: 自动对焦和对焦马达

v33: 扩充OMEGONPROCAM_OPTION_AGAIN至OMEGONPROCAM_OPTION_AUTOEXP_POLICY, 支持更多选项. 请参阅这里

v32: 增加支持Windows 10 on ARM和ARM64, 包括Desktop和WinRT

v31: 增加Omegonprocam_deBayerV2, 支持RGB48和RGB64

v30: 增加OMEGONPROCAM_FLAG_CGHDR

v29: 增加OmegonprocamFrameInfoV2以及PullImageV2和StartPushModeV2一组函数, 一些相机支持帧序号和帧时间戳. 请参阅这里

v28: 增加Omegonprocam_read_Pipe/Omegonprocam_write_Pipe/Omegonprocam_feed_Pipe

v27: 增加Omegonprocam_SnapN, 静态抓拍支持多张图片, 请参阅这里和decmpcpp

v26: 增加恢复出厂设置, OMEGONPROCAM_OPTION_FACTORY

v25: 增加锐化, OMEGONPROCAM_OPTION_SHARPENING

v24: 增加曝光时间的50/60HZ约束

v23: 增加Linux armhf、armel和arm64的支持
       增加FFC和DFC, 请参阅这里这里

v22: 增加OMEGONPROCAM_OPTION_DDR_DEPTH, 请参阅这里

v21: 增加Omegonprocam_IoControl

v20: 增加Omegonprocam_EnumV2, OmegonprocamModelV2, OmegonprocamDeviceV2; (Omegonprocam_Enum, OmegonprocamModel和OmegonprocamInst过时)
       增加Pixel Format, 见OMEGONPROCAM_OPTION_PIXEL_FORMAT; (OMEGONPROCAM_OPTION_BITDEPTH的超集)
       增加平场校正(Flat Field Correction)

v19: 增加黑平衡: 请参阅这里

v18: 增加Omegonprocam_get_Revision

v17: 增加OMEGONPROCAM_OPTION_ROTATE

v16: 增加OMEGONPROCAM_FLAG_DDR, 使用超大容量DDR(Double Data Rate SDRAM)作帧缓冲

v15: 增加OMEGONPROCAM_OPTION_BINNING

v14: 增加对WinRT / UWP (Universal Windows Platform) / Windows Store App的支持

v13: 支持行间隔(Row Pitch, Stride), 请参阅Omegonprocam_PullImageWithRowPitchOmegonprocam_PullStillImageWithRowPitch

v12: 支持RGB32, 8位灰度, 16位灰度, 请参阅这里

v11: 暗电平(Black Level), 请参阅这里

v10: Demosaic算法, 请参阅这里

v9: 直方图数据类型从double改成float

v8: 支持模拟触发模式, 请参阅这里

v7: 位深度>8时支持RGB48输出, 请参阅这里

v6: 支持触发(Trigger)模式, 请参阅这里

v5: 白平衡的两种模式: Temp/Tint模式 vs RGB Gain模式, 请参阅这里

v4: 支持ROI (Region Of Interest), 请参阅这里

v3: 支持更多的位深度(bitdepth): 10bits, 12bits, 14bits, 16bits

v2: 支持RAW模式, 请参阅这里这里;增加对Linux和macOS的支持

v1: 初始发布