ToupCam Native API 手册

 


1. 版本


1.0.2774.20140217


2. 介绍


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

toupcam.h, C/C++ 头文件
toupcam.cs, 支持.Net/C#. toupcam.cs使用P/Invoke调用至toupcam.dll. 请把toupcam.cs 拷贝到你的.Net/C#工程中使用.

toupcam.lib, x86 lib 文件.
toupcam.dll, x86 动态库文件.
toupcamdemocpp.exe, x86 C++ demo执行程序.

toupcam.lib, x64 lib文件.
toupcam.dll, x64 动态库文件.
toupcamdemocpp.exe, x64 C++ demo 执行程序.

x86 文件夹包含x86的内核态驱动文件,包括toupcam.cat, toupcam.inf 和 toupcam.sys.
x64 文件夹包含x64的内核态驱动文件,包括toupcam.cat, toupcam.inf 和 toupcam.sys.

directshow 目录包含directshow SDK和demo程序
twain 目录包含twain SDK 和demo程序
labview 目录包含labview SDK 和demo程序.

包含中英文SDK使用文档.


3. 获取图像数据的模式: Pull Mode vs Push Mode


Toupcam提供了两种模式来获取图像数据: Pull Mode 和 Push Mode. 前者更有优势因为它更简单,且在多线程情况下更加稳定可靠, 尤其是使用windows消息机制的情况下.

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

TOUPCAM_EVENT_EXPOSURE 曝光时间发生改变
TOUPCAM_EVENT_TEMPTINT 白平衡参数发生改变
TOUPCAM_EVENT_IMAGE 视频图像数据到达(视频).使用Toupcam_PullImage获取数据
TOUPCAM_EVENT_STILLIMAGE 静态图片数据到达(Toupcam_Snap引发).使用Toupcam_PullStillImage获取数据
TOUPCAM_EVENT_ERROR 发生错误,数据采集不能继续

4. 函数


返回值:非负整数,枚举到的相机数目

参数:ToupcamInst缓冲区

说明:调用该函数枚举计算机上当前插上的Toupcam相机.函数返回时,ToupcamInst缓冲区包含有枚举到的每个相机实例的信息.如果不关心多个相机同时联入电脑的情况的话,调用本函数枚举相机实例是可选的.

如下面的代码片段:

ToupcamInst arr[TOUPCAM_MAX];
unsigned cnt = Toupcam_Enum(arr);
for (unsigned i = 0; i < cnt; ++i)
    ......

 

typedef struct{
 #ifdef _WIN32
   const wchar_t*  name; /* model name */
 #else
   const char*    name;
 #endif
   unsigned     flag; /* TOUPCAM_FLAG_xxx */
   unsigned     maxspeed; /* number of speed level, Toupcam_get_MaxSpeed, the speed range = [0, max], closed interval */
   unsigned     preview; /* number of preview resolution, Toupcam_get_ResolutionNumber */
   unsigned     still; /* number of still resolution, Toupcam_get_StillResolutionNumber */
   ToupcamResolution  res[TOUPCAM_MAX];
}ToupcamModel;
typedef void (*PTOUPCAM_DATA_CALLBACK)(const void* pData, const BITMAPINFOHEADER* pHeader, BOOL bSnap, void* pCallbackCtx);

如果回调时,pData参数==NULL,表示发生内部错误(如相机被突然拔出等等).
BOOL bSnap参数,TRUE表示是由Toupcam_Snap函数发起的图片抓拍,FALSE表示普通的预览图片(视频).
注意:该回调函数是从toupcam.dll的内部线程上下文中回调出来,所以,非常有必要关注多线程问题.请尽量保持回调函数代码的简洁,并且快速返回.不要在回调函数上下文调用Toupcam_Stop或Toupcam_Close函数,否则,会死锁.正式因为使用Push模式的复杂性,所以,推荐使用Pull模式(特别是使用窗口消息通知事件).

说明:开启相机实例.

返回值:HRESULT类型表示成功失败

参数:HToupCam句柄

说明:停止相机实例.如果使用推模式(Push Mode),请不要在PTOUPCAM_DATA_CALLBACK回调函数里面调用Toupcam_Stop,否则,会死锁.停止之后,可以调用Toupcam_StartPushMode重新开启.比如切换视频分辨率:

说明:抓拍图片.抓拍成功之后,通过PTOUPCAM_DATA_CALLBACK回调函数返回,这种情况下,回调函数的参数BOOL bSnap设为TRUE.

说明:设置或者得到当前分辨率.

说明:Toupcam_get_ResolutionNumber得到支持的分辨率个数(如UCMOS03100KPA返回3,表示支持3种分辨率).Toupcam_get_Resolution得到每种分辨率的高度/宽度.

说明:如果设置RealTime模式为TRUE,更短的帧延时,但是帧速率降低,流畅性受损.缺省设为FALSE,一般不需要改动.

说明:自动曝光,自动曝光的目标.

说明:曝光时间相关.

说明:模拟增益相关.

说明:多色模式或者单色模式.

说明:最小帧速率等级是0.最大帧速率级别可以通过Toupcam_get_MaxSpeed函数得到,和ToupcamModel的maxspeed是一个意思.

提醒:CCD型号不能实时改变帧速率设置,也即在调用Toupcam_Startxxxx之后就不能再改变帧速率设置.所以,针对CCD型号的帧率设置,应该在Toupcam_Open之后,Toupcam_Startxxxx之前.

说明:设置光源的电力供应频率

说明:设置Bin模式或者Skip模式.较高分辨率的相机支持2种采样模式,一种是Bin模式(邻域平均),一种是Skip模式(抽样提取).相比较而言,前者图像效果较好,但是帧速率降低;后者帧速率较高,但是图像效果较差.

说明:设置/获取白平衡的色温和Tint参数.

说明: 自动白平衡功能,业界有两种模式, 一种是连续自动白平衡,一种是触发自动白平衡(one push). 连续自动白平衡功能会一直进行白平衡参数的计算, 触发模式只是在触发的时候才会计算白平衡参数. Toupcam使用了触发式白平衡计算方法因为这种方法在显微镜等领域更加合适和精确. 连续自动白平衡在某些场景情况下会出现错误. 调用这个函数来触发单次白平衡功能. 当白平衡参数计算完成的时候, TOUPCAM_EVENT_TEMPTINT 事件会通知应用程序 (In Pull Mode) 和调用回调函数. pull mode中, 如果不使用回调函数, 请把函数指针设为NULL.

说明:Toupcam_get_StillResolutionNumber得到支持的静态抓拍分辨率个数(如UCMOS03100KPA返回3,表示支持3种分辨率),如果不支持静态抓拍能力,返回0.Toupcam_get_StillResolution得到每种分辨率的高度/宽度.

说明:每个相机都有一个唯一的31位的序列号.如:“TP110826145730ABCD1234FEDC56787”

说明:一旦设置了非NULL的回调函数,每当曝光时间变化时,回调发生.设置fnExpoProc为NULL,表示不再回调.

说明:一旦设置了非NULL的回调函数,每当单色/多色切换时(如调用Toupcam_put_Chrome),回调发生.

说明:LevelRange相关.

说明:获取直方图数据


5. C#和.Net


Toupcam支持.Net和C#开发环境.

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

ToupTek.ToupCam c#类的属性和方法等等,直接调用toupcam.dll中对应的原生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);
}

6. 其他


一些参数的范围以及默认值

参数 范围 默认值
AutoExpoTarget 10~230 120
Temp 2000~15000 6503
Tint 200~2500 1000
LevelRange 0~255 Low = 0, High = 255
Contrast -100~100 0
Hue -180~180 0
Saturation 0~255 128
Brightness -64~64 0
Gamma 20~180 100

7. 联系信息


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