ToupCam API 手册

 


1. 版本


1.6.5660.20150520


2. 简介


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

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

toupcam.cs, 支持C#. toupcam.cs使用P/Invoke调用至toupcam.dll. 请把toupcam.cs 拷贝到你的C#工程中使用.
toupcam.vb, 支持VB.NET. toupcam.vb使用P/Invoke调用至toupcam.dll. 请把toupcam.vb 拷贝到你的VB.NET工程中使用.

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“拉”图像数据
TOUPCAM_EVENT_STILLIMAGE 静态图片数据到达(Toupcam_Snap引发).使用Toupcam_PullStillImage“拉”图像数据
TOUPCAM_EVENT_ERROR 发生错误,数据采集不能继续
TOUPCAM_EVENT_DISCONNECTED 相机断开连接,如被拔出

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

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

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

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

可以通过函数Toupcam_get_StillResolutionNumber的返回值或者结构ToupcamModel的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_StartPushMode)之前.

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. 连续(Continuous)模式 vs 触发(Trigger)模式

除了连续采集模式以外,一些相机还支持触发采集模式. 在触发模式下,每调用Toupcam_Trigger函数一次采集一帧.


4. 函数



5. .NET, C#和VB.NET


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

inc目录下toupcam.cs使用P/Invoke调用至toupcam.dll. 把toupcam.cs 拷贝到你的C#工程中使用,请参考例子代码samples\toupcamdemowinformcs1和toupcamdemowinformcs2.

ToupTek.ToupCam C#包装类的属性和方法等等,直接调用toupcam.dll中对应的原生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. 其他


参数 范围 默认值 获取 设置 自动
AutoExpoTarget
(自动曝光目标亮度)
16~235 120 Toupcam_get_AutoExpoTarget Toupcam_put_AutoExpoTarget  
白平衡 Temp/Tint模式 Temp(色温) 2000~15000 6503 Toupcam_get_TempTint Toupcam_put_TempTint Toupcam_AwbOnePush
Tint 200~2500 1000
RGB Gain模式 Red Gain -128~128 0 Toupcam_get_WhiteBalanceGain Toupcam_put_WhiteBalanceGain Toupcam_AwbInit
Green Gain
Blue Gain
LevelRange 0~255 Low = 0
High = 255
Toupcam_get_LevelRange Toupcam_put_LevelRange Toupcam_LevelRangeAuto
Contrast(对比度) -100~100 0 Toupcam_get_Contrast Toupcam_put_Contrast  
Hue(色度) -180~180 0 Toupcam_get_Hue Toupcam_put_Hue  
Saturation(饱和度) 0~255 128 Toupcam_get_Saturation; Toupcam_put_Saturation  
Brightness(亮度) -64~64 0 Toupcam_get_Brightness Toupcam_put_Brightness  
Gamma 20~180 100 Toupcam_get_Gamma Toupcam_put_Gamma  

7. 更新历史


v1.6: 位深度>8时支持RGB48格式输出, 请参阅这里

v1.5: 支持触发(Trigger)模式

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

v1.3: 支持ROI (Region Of Interest), 请参阅这里

v1.2: 支持更多的位深度(bit depth): 10bits, 12bits, 14bits, 16bits

v1.1: 支持RAW模式,请参阅这里和请参阅这里;增加对Linux和OSX的支持

v1.0: 初始发布


8. 联系信息


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