Toupcam API 手册

 


1. 版本和平台



2. 简介


Toupcam系列相机支持多种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压缩包包含了所有需要用到的的资源和信息, 目录如下:

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


3. 概念和术语


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

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

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

TOUPCAM_EVENT_EXPOSURE 曝光时间发生改变
TOUPCAM_EVENT_TEMPTINT 白平衡参数发生改变,Temp/Tint模式, 请参阅这里.
TOUPCAM_EVENT_WBGAIN 白平衡参数发生改变,RGB Gain模式, 请参阅这里.
TOUPCAM_EVENT_IMAGE 视频图像数据到达(视频).使用Toupcam_PullImage(V2)“拉”图像数据
TOUPCAM_EVENT_STILLIMAGE 静态图片数据到达(Toupcam_Snap或Toupcam_SnapN引发).使用Toupcam_PullStillImage(V2)“拉”图像数据
TOUPCAM_EVENT_ERROR 一般性错误,数据采集不能继续
TOUPCAM_EVENT_DISCONNECTED 相机断开连接,如被拔出
TOUPCAM_EVENT_NOFRAMETIMEOUT 抓取视频帧超时错误,数据采集不能继续
TOUPCAM_EVENT_NOFRAMETIMEOUT 抓取视频包超时
TOUPCAM_EVENT_TRIGGERFAIL 触发失败(如帧数据错误或超时)
TOUPCAM_EVENT_BLACK 黑平衡参数发生改变
TOUPCAM_EVENT_FFC 平场校正(flat field correction)状态发生改变
TOUPCAM_EVENT_DFC 暗场校正(dark field correction)状态发生改变
TOUPCAM_EVENT_ROI ROI发生改变
TOUPCAM_EVENT_FACTORY 恢复出厂设置

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

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

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

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

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

c. 数据格式: RGB vs RAW

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

用户可以通过TOUPCAM_OPTION_RAW调用函数Toupcam_put_Option来切换这两种模式.请注意切换模式必须在调用相机开启函数(Toupcam_StartPullModeWithWndMsg或Toupcam_StartPullModeWithCallback或Toupcam_StartPushModeV3)之前.

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

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

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

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

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

a) Temp/Tint模式下,必须使用Toupcam_get_TempTint和Toupcam_put_TempTint和Toupcam_AwbOnePush. 而Toupcam_get_WhiteBalanceGain和Toupcam_put_WhiteBalanceGain和Toupcam_AwbInit不能使用,永远返回E_NOTIMPL.
b) RGB Gain模式下,必须使用Toupcam_get_WhiteBalanceGain和Toupcam_put_WhiteBalanceGain和Toupcam_AwbInit. 而Toupcam_get_TempTint和Toupcam_put_TempTint和Toupcam_AwbOnePush不能使用,永远返回E_NOTIMPL

Toupcam_Open的id参数之前加'@'字符表示使用RGB Gain模式的白平衡.如果想使用RGB Gain模式白平衡,假设id参数是"abcdef",则传入参数"@abcdef".

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

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

e. 触发模式

1. 什么是触发

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

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

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

3. 软件触发

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

4. 外部触发

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

5. 混合触发

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

6. 模拟触发

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

7. 怎样进入触发模式

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

8. 怎样触发相机

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

9. 触发超时

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

4. 函数



5. .NET, C#和VB.NET


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

toupcam.cs使用P/Invoke调用至toupcam.dll. 把toupcam.cs拷贝到你的C#工程中使用,请参考例子代码demowinformcs1, demowinformcs2和demowinformcs3.

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

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

[DllImport("toupcam.dll", ExactSpelling = true, CallingConvention = CallingConvention.StdCall)]
private static extern int Toupcam_Snap(SafeHToupcamHandle h, uint nResolutionIndex);

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

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


6. Python


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

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

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

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

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


7. Java


Toupcam支持Java开发. toupcam.java使用JNA (https://github.com/java-native-access/jna)调用至toupcam.dll/so/dylib. 把toupcam.java拷贝到你的JAVA工程中使用,请参考例子代码simplest.java(控制台程序), javafx.java, swing.java.

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

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

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

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


8. 更新历史


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

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

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

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

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

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

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

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

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

v37: 增加Android支持
       增加Toupcam_StartPushModeV3 (Toupcam_StartPushModeV2和Toupcam_StartPushMode过时)

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

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

v34: 自动对焦和对焦马达

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

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

v31: 增加Toupcam_deBayerV2,支持RGB48和RGB64

v30: 增加TOUPCAM_FLAG_CGHDR

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

v28: 增加Toupcam_read_Pipe/Toupcam_write_Pipe/Toupcam_feed_Pipe

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

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

v25: 增加锐化, TOUPCAM_OPTION_SHARPENING

v24: 增加50/60HZ约束下的自动曝光

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

v22: 增加TOUPCAM_OPTION_DDR_DEPTH, 请参阅这里

v21: 增加Toupcam_IoControl

v20: 增加Toupcam_EnumV2, ToupcamModelV2, ToupcamDeviceV2; (Toupcam_Enum, ToupcamModel和ToupcamInst过时)
       增加Pixel Format,见TOUPCAM_OPTION_PIXEL_FORMAT; (TOUPCAM_OPTION_BITDEPTH的超集)
       增加平场校正(Flat Field Correction)

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

v18: 增加Toupcam_get_Revision

v17: 增加TOUPCAM_OPTION_ROTATE

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

v15: 增加TOUPCAM_OPTION_BINNING

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

v13: 支持行间隔(Row Pitch, Stride), 请参阅Toupcam_PullImageWithRowPitchToupcam_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: 支持更多的位深度(bit depth): 10bits, 12bits, 14bits, 16bits

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

v1: 初始发布


9. 联系信息


如果在使用Toupcam SDK的过程中,碰到任何问题,请与我们联系
网站:www.touptek.com
EMAIL:support@touptek.com