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++ 头文件
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工程中使用.
toupcam.lib, x86 lib文件
toupcam.dll, x86 动态库文件
democpp.exe, x86 C++ demo执行程序
toupcam.lib, x64 lib文件
toupcam.dll, x64 动态库文件
democpp.exe, x64 C++ demo 执行程序
toupcam.lib, arm lib文件
toupcam.dll, arm 动态库文件
toupcam.lib, arm64 lib文件
toupcam.dll, arm64 动态库文件
适用于WinRT / UWP (Universal Windows Platform) / Windows Store App的动态库文件.
它们和Windows Runtime兼容,可以被Universal Windows Platform app引用.
如果使用C#开发UWP,可以使用toupcam.cs包装类.
请注意:1. uwp只能使用winusb驱动,不能私有私有驱动。如果已安装,请在设备管理器中卸载私有驱动,之后Windows会自动使用Winusb。demouwp.zip是一个uwp简单例子,编译运行例子之前请修改文件Package.appxmanifest中的DeviceCapability下的vid和pid.
2. uwp的DeviceCapability,参阅How to add USB device capabilities to the app manifest.(微软似乎限制了DeviceCapability下的Device条目不超过100)
x86 文件夹包含x86的内核态驱动文件,包括toupcam.cat, toupcam.inf 和 toupcam.sys
建议使用DPInst.exe来自动安装驱动,如使用NSIS制作安装文件,可以使用类似如下语句:
x64 文件夹包含x64的内核态驱动文件,包括toupcam.cat, toupcam.inf 和 toupcam.sys
ExecWait '"$INSTDIR\drivers\x64\DPInst.exe" /SA /SW /PATH "$INSTDIR\drivers\x64"'
Toupcam提供了两种模式来获取图像数据: Pull Mode 和 Push Mode. 以下所讲的几种方式中,从功能上说它们都是平等的,开发者可以任选一种使用. 推荐使用拉模式,因为它更简单,且在多线程情况下更加不容易出错, 尤其是使用windows消息机制的情况下.
a) 使用Windows消息机制: 通过调用函数 Toupcam_StartPullModeWithWndMsg启动Pull mode模式. 当事件发生时, toupcam会主动发送消息(PostMessage)到指定窗口. 参数WPARAM 是事件类型, 请参考TOUPCAM_EVENT_xxxx的定义. 参数LPARAM保留未使用. 本模式规避了多线程问题,是最简单的方式.(显然,这种方式只支持Windows系统,不支持Linux和macOS.)
b) 使用回调函数使用 Toupcam_StartPullModeWithCallback启动Pull mode模式. 当事件发生时, 会调用PTOUPCAM_EVENT_CALLBACK回调函数.
在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 恢复出厂设置
大部分的相机型号都支持所谓静态抓拍的能力,指相机在连续的视频预览过程中,临时切换到另外一个分辨率,抓取一帧静态图片之后,马上把分辨率切换回原始分辨率的过程.
举例来说,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值来查看是否支持静态抓拍能力.
Toupcam支持两种数据格式: RGB格式(默认)和RAW格式. RAW模式可以通过调用函数Toupcam_put_Option设置参数TOUPCAM_OPTION_RAW为1开启.
用户可以通过TOUPCAM_OPTION_RAW调用函数Toupcam_put_Option来切换这两种模式.请注意切换模式必须在调用相机开启函数(Toupcam_StartPullModeWithWndMsg或Toupcam_StartPullModeWithCallback或Toupcam_StartPushModeV3)之前.
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.
1. 什么是触发
Toupcam相机拥有2中工作模式: 视频模式和触发模式. 当处于触发模式时,只有触发条件满足的情况下才能获取图像. 根据触发源有2种类型的触发类型: 外部触发,软件触发.
2. 触发和Snap(静态图像抓拍)的区别
触发模式被设计用来精确控制相机当且仅当触发条件满足时才能获取图像.用户可以通过控制预设的触发条件获取图像.当进入触发模式时,直到触发条件被满足才能得到图像.图像的分辨率没有改变. Snap(静态图像抓拍)是用来在视频模式下抓取相同或者不同分辨率的图像.
3. 软件触发
相机可以被软件触发. 在软件触发模式下,通过软件来控制触发条件. 图像的张数也可以软件控制.
4. 外部触发
相机可以被外部信号触发. 当前仅支持上升沿触发模式.
5. 混合触发
外部触发+软件触发同时启用.
6. 模拟触发
对于既不支持软件触发又不支持外部触发的相机,可以使用模拟触发.当处于模拟触发模式时,相机硬件的工作模式和视频模式下的工作模式没有区别,但是上层软件不发起抓取动作,软件内部的缓冲区保持为空,直到用户设置触发条件.
7. 怎样进入触发模式
枚举相机时,可以得到相机型号的能力标志位,查看相机对于触发模式的支持能力,定义如下:可以使用函数Toupcam_put_Option(HToupcam h, unsigned iOption, int iValue)设置相机的触发模式,其中iOption参数为TOUPCAM_OPTION_TRIGGER,iValue用于设置触发模式的类型.请参阅以下内容:
#define TOUPCAM_FLAG_TRIGGER_SOFTWARE 0x00080000 /* 支持软触发 */ #define TOUPCAM_FLAG_TRIGGER_EXTERNAL 0x00100000 /* 支持外部触发 */ #define TOUPCAM_FLAG_TRIGGER_SINGLE 0x00200000 /* 仅支持单张触发: 一次触发得到一张图像 */函数Toupcam_get_Option(HToupcam h, unsigned iOption, int* piValue)可以用来获取当前相机的触发模式类型.
#define TOUPCAM_OPTION_TRIGGER 0x0b /* 0 = 视频模式, 1 = 软件或模拟触发模式, 2 = 外部触发模式, 3 = 外部触发+软件触发模式;默认值 = 0 */
8. 怎样触发相机
使用函数Toupcam_Trigger(HToupcam h, unsigned short nNumber). 不同的nNumber的含义:nNumber = 0 取消触发.如果TOUPCAM_FLAG_TRIGGER_SINGLE标志位是设置的,那么nNumber参数只能为1,意味着单次触发只能获取单张图片.
nNumber = 0xFFFF 一直触发, 类似于视频模式;
nNumber = 其他合法值代表单次触发获取的图片张数.
在调用Toupcam_Trigger函数之前,相机必须已经处于触发模式.
9. 触发超时
超时时间建议不少于(曝光时间 * 102% + 4秒).
HRESULT在Windows平台上的使用很普遍. macOS, Linux和Android平台上借用之,定义如下:
请注意,返回值>=0都表示成功(特别S_FALSE也是成功,表示内部值和用户设置的值已经一致,相当于空操作). 所以,一般情况下应该使用SUCCEEDED和FAILED宏来判断返回值是成功或者失败.
(除非有特殊需要,不要使用"==S_OK"或"==0"来判断返回值)
名称 | 说明 | 值 |
S_OK | Operation successful (成功) | 0x00000000 |
S_FALSE | Operation successful, nothing changed (成功,值没有变化) | 0x00000001 |
E_FAIL | Unspecified failure (未指定的错误) | 0x80004005 |
E_ACCESSDENIED | General access denied error (拒绝访问) | 0x80070005 |
E_INVALIDARG | One or more arguments are not valid (参数错误) | 0x80070057 |
E_NOTIMPL | Not supported or not implemented (功能不支持或未实现) | 0x80004001 |
E_POINTER | Pointer that is not valid (无效指针) | 0x80004003 |
E_UNEXPECTED | Unexpected failure (灾难性故障) | 0x8000FFFF |
E_WRONG_THREAD | Wrong thread (函数在错误的线程上下文中被调用) | 0x8001010E |
E_GEN_FAILURE | Device not functioning (设备不相应) | 0x8007001F |
#define SUCCEEDED(hr) (((HRESULT)(hr)) >= 0) #define FAILED(hr) (((HRESULT)(hr)) < 0) |
在Win平台使用__stdcall,请参阅这里
在macOS, Linux和Android使用__cdecl
这些回调函数是从toupcam.dll的内部线程上下文中回调出来,所以,非常有必要关注多线程问题. 请尽量保持回调函数代码的简洁,并且快速返回.
回调模式下,如果PTOUPCAM_EVENT_CALLBACK回调函数复杂,可以设置TOUPCAM_OPTION_CALLBACK_THREAD,使用专门的线程用于回调.
类似Toupcam_put_Roi, Toupcam_put_AEAuxRect等等这类带有坐标参数的,其坐标永远是相对原始分辨率而言的,即使视频已经执行过旋转,Flip,ROI,数字Binning或它们的任意组合.
如果视频是倒置的(参考这里),则矩形坐标也必须倒置.
返回值:非负整数,枚举到的相机数目
参数:ToupcamDeviceV2缓冲区
说明:调用该函数枚举计算机上当前插上的Toupcam相机.函数返回时,ToupcamDeviceV2缓冲区包含有枚举到的每个相机实例的信息.如果不关心多个相机同时联入电脑的情况的话,调用本函数枚举相机实例是可选的.
如下面的代码片段:
ToupcamDeviceV2 arr[TOUPCAM_MAX]; unsigned cnt = Toupcam_EnumV2(arr); for (unsigned i = 0; i < cnt; ++i) ......
typedef struct{ #ifdef _WIN32 const wchar_t* name; /* model name */ #else const char* name; #endif unsigned long long flag; /* TOUPCAM_FLAG_xxx */ unsigned maxspeed; /* maximum speed level, Toupcam_get_MaxSpeed, the speed range = [0, maxspeed], closed interval */ unsigned preview; /* number of preview resolution, Toupcam_get_ResolutionNumber */ unsigned still; /* number of still resolution, Toupcam_get_StillResolutionNumber */ unsigned maxfanspeed; /* maximum fan speed */ ToupcamResolution res[TOUPCAM_MAX]; }ToupcamModelV2;
name 型号名称 flag 位标记 (Bitwise flag) TOUPCAM_FLAG_CMOS cmos传感器 TOUPCAM_FLAG_CCD_PROGRESSIVE 逐行ccd传感器 TOUPCAM_FLAG_CCD_INTERLACED 隔行ccd传感器 TOUPCAM_FLAG_ROI_HARDWARE 支持硬件ROI.所谓硬件ROI和软件ROI,前者设置sensor的工作参数,从sensor读取的数据减少(从而提高帧率);后者不改变sensor的工作参数,从sensor读取的数据量不变,上层软件把原始图像剪切到目标ROI矩形大小. TOUPCAM_FLAG_MONO 黑白传感器 TOUPCAM_FLAG_BINSKIP_SUPPORTED 支持bin/skip模式, 请参考Toupcam_put_Mode和Toupcam_get_Mode TOUPCAM_FLAG_USB30 USB3.0 TOUPCAM_FLAG_TEC TEC制冷相机 TOUPCAM_FLAG_USB30_OVER_USB20 usb3.0 相机被插入usb2.0端口 TOUPCAM_FLAG_ST4 支持ST4端口 TOUPCAM_FLAG_GETTEMPERATURE 支持读取温度, Toupcam_get_Temperature TOUPCAM_FLAG_PUTTEMPERATURE 支持设置传感器目标温度, Toupcam_put_Temperature TOUPCAM_FLAG_RAW10 Pixel format, RAW 10 bits TOUPCAM_FLAG_RAW12 Pixel format, RAW 12 bits TOUPCAM_FLAG_RAW14 Pixel format, RAW 14 bits TOUPCAM_FLAG_RAW16 Pixel format, RAW 16 bits TOUPCAM_FLAG_FAN 支持制冷风扇 TOUPCAM_FLAG_TEC_ONOFF TEC制冷装置支持开启/关闭,TEC制冷的目标温度,见:
TOUPCAM_OPTION_TEC
TOUPCAM_OPTION_TECTARGETTOUPCAM_FLAG_ISP 支持硬件ISP (Image Signal Processing),降低CPU进行图像处理时的CPU利用率 TOUPCAM_FLAG_TRIGGER_SOFTWARE 支持软件触发模式 TOUPCAM_FLAG_TRIGGER_EXTERNAL 支持外触发模式 TOUPCAM_FLAG_TRIGGER_SINGLE 只支持单帧触发模式,单次触发只能获取一张图片. TOUPCAM_FLAG_BLACKLEVEL 支持设置和获取 TOUPCAM_FLAG_FOCUSMOTOR 支持对焦马达 TOUPCAM_FLAG_AUTO_FOCUS 支持自动对焦 TOUPCAM_FLAG_BUFFER 帧缓冲 TOUPCAM_FLAG_CG 转换增益(Conversion Gain): LCG, HCG TOUPCAM_FLAG_CGHDR 转换增益(Conversion Gain): LCG, HCG, HDR TOUPCAM_FLAG_DDR 使用超大容量DDR(Double Data Rate SDRAM)作帧缓冲 TOUPCAM_FLAG_YUV411 pixel format, yuv411 TOUPCAM_FLAG_YUV422 pixel format, yuv422 TOUPCAM_FLAG_YUV444 pixel format, yuv444 TOUPCAM_FLAG_RGB888 pixel format, RGB888 TOUPCAM_FLAG_RAW8 pixel format, RAW 8 bits TOUPCAM_FLAG_GMCY8 pixel format, GMCY, 8bits TOUPCAM_FLAG_GMCY12 pixel format, GMCY, 12 btis TOUPCAM_FLAG_GLOBALSHUTTER 全局快门 TOUPCAM_FLAG_PRECISE_FRAMERATE 支持精确帧率和带宽,参阅TOUPCAM_OPTION_PRECISE_FRAMERATE和TOUPCAM_OPTION_BANDWIDTH maxspeed 最大速度等级,和函数Toupcam_get_MaxSpeed返回值相同. 速度范围是[0, maxspeed]. 可以通过Toupcam_put_Speed设置速度等级, Toupcam_get_Speed获取当前速度等级 preview 预览分辨率的个数. 和函数Toupcam_get_ResolutionNumber返回值相同 still 静态抓拍分辨率个数, 0表示不支持静态抓拍. 和函数Toupcam_get_StillResolutionNumber返回值相同 res 分辨率宽度和高度
返回值:无
参数:
PTOUPCAM_HOTPLUG pHotPlugCallback: 回调函数
typedef void (*PTOUPCAM_HOTPLUG)(void* pCallbackCtx);void* pCallbackCtx: 回调函数上下文
说明:
本函数只存在于macOS, Linux和Android平台.
在Windows平台处理设备插入/拔出通知,请参阅MSDN(Device Management, Detecting Media Insertion or Removal).
在Linux/macOS/Android平台,如果需要处理设备插入/拔出通知,调用本函数注册回调函数. 当设备被插入/拔出时时,程序通过回调函数得到通知,然后调用Toupcam_EnumV2重新枚举设备即可.
macOS平台下也可以使用IONotificationPortCreate系列API.
建议: 当设备插入通知到达时,建议不要立即打开句柄,而是延时一小段时间(如200毫秒)之后再打开,这样稳定性更好.
返回值:HToupcam句柄.失败时返回NULL(如设备被突然拔出等等)
参数:Toupcam相机实例,由Toupcam_EnumV2枚举得到.如果id是NULL则自动打开第一个相机,所以,如果不关心多个相机实例同时连入电脑的情况,Toupcam_EnumV2不是必须的,直接传入参数NULL打开唯一的相机实例.
说明:打开相机实例.
返回值:无
参数:HToupcam句柄
说明:关闭相机实例.句柄关闭之后,请不要再使用之.
返回值:HRESULT类型表示成功失败
参数:
HToupcam h:由Toupcam_Open打开的实例句柄
HWND hWnd: 事件发生时,消息将Post到这个窗口
UINT nMsg: Windows自定义消息类型.消息的WPARAM参数是事件类型TOUPCAM_EVENT_xxxx,LPARAM参数不用(恒等于0)
PTOUPCAM_EVENT_CALLBACK pEventCallback, void* pCallbackContext:用户程序指定的回调函数和回调上下文参数.
typedef void (*PTOUPCAM_EVENT_CALLBACK)(unsigned nEvent, void* pCallbackCtx);请参阅这里.
说明:很明显,Toupcam_StartPullModeWithWndMsg只支持Windows系统
返回值:HRESULT类型表示成功失败,不存在图像可供获取时返回E_FAIL
参数:
HToupcam h:由Toupcam_Open打开的实例句柄
void* pImageData:数据缓冲区.用户应用程序必须确保改缓冲区足够大以容纳图像数据.缓冲区大小必须 >= rowPitch * nHeight
int bits:图像颜色位数,支持24, 32, 48, 8和16,分别代表RGB24, RGB32, RGB48, 8位灰度, 16位灰度图像. 本参数在RAW模式下没有意义,被忽略
int rowPitch: 行间距(Stride, 跨距),行与行之间的间距,=0表示默认使用行间距
unsigned* pnWidth, unsigned* pnHeight:输出参数,图像的宽度高度
ToupcamFrameInfoV2* pInfo:输出参数,图像Info. 一些相机支持帧序号和帧时间戳,其它不支持的相机始终为0
说明:当pImageData为NULL而pnWidth, pnHeight参数不为NULL的时候,可以获取(Peek)是否存在图像以及图像的宽度高度信息
请保证pImageData缓冲区的大小足够容纳整帧数据,请看下表:
格式 默认行间距(跨距) RGB RGB24 TDIBWIDTHBYTES(24 * Width) RGB32 Width * 4 RGB48 TDIBWIDTHBYTES(48 * Width) RGB8灰度图像 TDIBWIDTHBYTES(8 * Width) RAW 8bits模式 Width 10bits, 12bits, 14bits, 16bits模式 Width * 2
#ifndef TDIBWIDTHBYTES
#define TDIBWIDTHBYTES(bits) ((unsigned)(((bits) + 31) & (~31)) / 8)
#endif
返回值:HRESULT类型表示成功失败
参数:
HToupcam h:由Toupcam_Open打开的实例句柄
PTOUPCAM_DATA_CALLBACK_V3 pDataCallback, void* pDataCallbackCtx:用户程序指定的回调函数和回调上下文参数. toupcam.dll内部从相机得到的图像数据后,会回调该函数.
PTOUPCAM_EVENT_CALLBACK pEventCallback, void* pEventCallbackContext:
typedef void (*PTOUPCAM_DATA_CALLBACK_V3)(const void* pData, const ToupcamFrameInfoV2* pInfo, int bSnap, void* pCallbackCtx); 请参阅这里.
如果回调时,pData参数==NULL,表示发生内部错误(如相机被突然拔出等等).
数据pData的行间距(row pitch, stride, 跨距)是默认值.
int bSnap参数,TRUE表示是由Toupcam_Snap或Toupcam_SnapN函数发起的图片抓拍,FALSE表示普通的预览图片(视频).
说明:开启相机实例.
返回值:HRESULT类型表示成功失败
参数:HToupcam句柄
说明:停止相机实例. 停止之后,可以调用Toupcam_StartPushMode重新开启.比如切换视频分辨率:
步骤1:调用Toupcam_Stop停止
步骤2:调用Toupcam_put_Size或者Toupcam_put_eSize设置新分辨率
步骤3:调用Toupcam_StartPullModeWithWndMsg或Toupcam_StartPullModeWithCallback或Toupcam_StartPushModeV3重新开启
返回值:HRESULT类型表示成功失败
参数:HToupcam句柄
说明:暂停或者继续相机实例
返回值:HRESULT类型表示成功失败
参数:
HToupcam h:相机实例句柄
unsigned nResolutionIndex:想要抓拍的分辨率序号.
说明:抓拍“静态”图片,请参阅这里. 抓拍成功之后,如果是Push Mode, 则通过TOUPCAM_EVENT_STILLIMAGE通知. 如果是Push Mode则通过PTOUPCAM_DATA_CALLBACK_V3回调函数返回,其中回调函数的参数BOOL bSnap设为TRUE.
有些相机支持在预览视频的不间断的情况下,抓拍单张的不同于正在视频预览的分辨率的所谓静态图片.例如UCMOS03100KPA,正在预览的分辨率是1024*768,调用Toupcam_Snap(h, 0)抓拍单张第0号分辨率(2048*1536)的图片.预览使用小分辨率(追求更快的帧率),抓拍使用大分辨率(追求更好的图片质量).这种行为,称之为“静态抓拍”.
对于不支持静态抓拍的相机型号,则参数nResolutionIndex的值必须等于当前正在预览的分辨率,否则,函数返回E_UNEXPECTED.
某个型号是否支持静态抓拍能力,参见ToupcamModelV2的still域(大于0).Toupcam_Snap(h, index) == Toupcam_SnapN(h, index, 1)
返回值:HRESULT类型表示成功失败.
参数:
HToupcam h:相机实例句柄
unsigned short nNumber: 0xffff(一直触发),0(取消触发),其他值(触发图片的张数)
说明:触发模式下,调用本函数进行软件触发. 触发成功之后,如果是Push Mode, 则通过TOUPCAM_EVENT_IMAGE通知. 如果是Push Mode则通过PTOUPCAM_DATA_CALLBACK_V3回调函数返回,其中回调函数的参数BOOL bSnap设为FALSE.
返回值:HRESULT类型表示成功失败
参数:
HToupcam h:相机实例句柄
unsigned nResolutionIndex:当前分辨率序号
int nWidth, int nHeight:当前分辨率的宽度高度
说明:设置或者得到当前分辨率.
设置分辨率应该在Toupcam_StartPullModeWithWndMsg或Toupcam_StartPullModeWithCallback或Toupcam_StartPushModeV3之前进行.
有2种方法设置当前分辨率,一种是通过分辨率的序号,一种是通过宽度/高度.两种方法是等效的.比如UCMOS03100KPA支持以下3种分辨率:
序号0: 2048, 1536
序号1: 1024, 768
序号2: 680, 510
所以Toupcam_put_Size(h, 1024, 768) or Toupcam_put_eSize(h, 1)效果一样.
返回值:HRESULT类型表示成功失败
参数:
HToupcam h:相机实例句柄
unsigned nResolutionIndex:当前分辨率序号
int nWidth, int nHeight:当前分辨率的宽度高度
说明:设置或者得到当前分辨率.
设置分辨率应该在Toupcam_StartPullModeWithWndMsg或Toupcam_StartPullModeWithCallback或Toupcam_StartPushModeV3之前进行.
有2种方法设置当前分辨率,一种是通过分辨率的序号,一种是通过宽度/高度.两种方法是等效的.比如UCMOS03100KPA支持以下3种分辨率:
序号0: 2048, 1536
序号1: 1024, 768
序号2: 680, 510
所以Toupcam_put_Size(h, 1024, 768) or Toupcam_put_eSize(h, 1)效果一样.
返回值:HRESULT类型表示成功失败.
参数:
HToupcam h: 相机实例句柄
unsigned xOffset: x偏移,必须是偶数
unsigned yOffset: y偏移,必须是偶数
unsigned xWidth: 宽度. 最小值16,必须是偶数
unsigned yHeight: 高度. 最小值16,必须是偶数
说明: 设置/获取ROI. Toupcam_put_Roi(h, 0, 0, 0, 0)表示清除ROI恢复原始尺寸.
重要提示: 不允许在PTOUPCAM_EVENT_CALLBACK和PTOUPCAM_DATA_CALLBACK_V3的回调上下文中调用Toupcam_put_Roi,否则返回E_WRONG_THREAD.
注意:坐标永远是相对原始分辨率而言的,请参阅这里
例外: UHCCD03100KPB, UHCCD05000KPA, UHCCD05100KPA的小分辨率不支持ROI功能, 函数返回值是E_NOTIMPL。
返回值:HRESULT类型表示成功失败
参数:
HToupcam h:相机实例句柄
unsigned nResolutionIndex:分辨率序号
int* pWidth, int* pHeight:宽度、高度
说明:Toupcam_get_ResolutionNumber得到支持的分辨率个数(如UCMOS03100KPA返回3,表示支持3种分辨率).Toupcam_get_Resolution得到每种分辨率的高度/宽度.
这些参数在Toupcam_EnumV2返回相机实例的ToupcamModelV2都已经包含.
返回值:HRESULT类型表示成功失败.
参数:
HToupcam h:相机实例句柄
unsigned* nFourCC:格式类型,见下表
unsigned* bitsperpixel:Bits per Pixel,如8, 10, 12, 14, 16, 24
#ifndef MAKEFOURCC
#define MAKEFOURCC(a, b, c, d) ((unsigned)(unsigned char)(a) | ((unsigned)(unsigned char)(b) << 8) | ((unsigned)(unsigned char)(c) << 16) | ((unsigned)(unsigned char)(d) << 24))
#endif
MAKEFOURCC('G', 'B', 'R', 'G') GBGBGB...
RGRGRG...
GBGBGB...
RGRGRG...
...
请参阅这里MAKEFOURCC('R', 'G', 'G', 'B') RGRGRG...
GBGBGB...
RGRGRG...
GBGBGB...
...MAKEFOURCC('B', 'G', 'G', 'R') BGBGBG...
GRGRGR...
BGBGBG...
GRGRGR...
...MAKEFOURCC('G', 'R', 'B', 'G') GRGRGR...
BGBGBG...
GRGRGR...
BGBGBG...
...MAKEFOURCC('V', 'U', 'Y', 'Y') YUV4:2:2, 请参阅: http://www.fourcc.org MAKEFOURCC('U', 'Y', 'V', 'Y') YUV4:2:2 MAKEFOURCC('Y', 'Y', 'Y', 'Y') 黑白相机
返回值:HRESULT类型表示成功失败.
参数:
HToupcam h:相机实例句柄
unsigned iOption:选项,见下表
int iValue:值,见下表
选项 说明 默认值 是否可以在调用Toupcam_StartPullModeWithWndMsg或Toupcam_StartPullModeWithCallback或Toupcam_StartPushModeV3之后设置该值
The value can be changed on-the-fly?TOUPCAM_OPTION_RAW 0表示使用RGB模式.
1表示RAW模式,直接获取底层传感器数据.0 否
(在相机已经开启的情况下,设置本选项,函数返回E_UNEXPECTED)TOUPCAM_OPTION_BITDEPTH 一些型号的相机支持大于8Bits的位深度(Bit Depth),如10,12,14,16等.
0表示使用8Bits位深度.
1表示使用本相机支持的最高位深度NA 是
(启动相机之后不建议频繁修改,最好是在启动之前就设置好)TOUPCAM_OPTION_FAN 一些型号的相机支持制冷风扇.
0 = 关闭风扇
[1, max] = 风扇速率NA 是 TOUPCAM_OPTION_TEC 一些型号的相机支持开启关闭TEC制冷装置.
0 = 关闭TEC制冷
1 = 开启TEC制冷1 是 TOUPCAM_OPTION_WBGAIN 0 = 关闭内部白平衡增益
1 = 开启内部白平衡增益1 是 TOUPCAM_OPTION_TRIGGER 0 = 视频模式
1 = 软件或模拟触发模式
2 = 外部触发模式
3 = 外部触发和软件触发都开启0 是 TOUPCAM_OPTION_RGB 0 = 使用RGB24
1 = 在位深度>8时,启用RGB48格式
2 = 使用RGB32
3 = 8位灰度(只对黑白相机有效)
4 = 16位灰度(只对黑白相机并且位深度>8时有效)0 否
(在相机已经开启的情况下,设置本选项,函数返回E_UNEXPECTED)TOUPCAM_OPTION_BYTEORDER 字节序:
1: BGR
0: RGBWin: 1
Linux/MacOS/Android: 0是
(启动相机之后不建议频繁修改,最好是在启动之前就设置好)TOUPCAM_OPTION_UPSIDE_DOWN 倒置:
1: yes
0: no
请和Toupcam_put_VFlip区别,后者需要耗费CPU对每帧数据执行数据搬动的工作Win: 1, Windows下默认倒置
Linux/MacOS/Android: 0, 默认不倒置否 TOUPCAM_OPTION_TECTARGET 获取和设置TEC制冷的目标温度,单位0.1℃. 例如, 125表示12.5℃,-35表示-3.5℃ NA 是 TOUPCAM_OPTION_AUTOEXP_POLICY 自动曝光策略:
0: 仅曝光
1: 曝光优先
2: 仅模拟增益
3: 模拟增益优先1 是 TOUPCAM_OPTION_AUTOEXP_THRESHOLD 自动曝光阈值,范围: [2~15] 5 是 TOUPCAM_OPTION_FRAMERATE 帧率限制(每秒帧数),范围[0, 63].
触发模式下帧率控制自动禁用.0
(表示不限制)否
(在相机已经开启的情况下,设置本选项,函数返回E_UNEXPECTED)TOUPCAM_OPTION_BLACKLEVEL 暗电平(Black Level)
对于不支持暗电平的相机返回E_NOTIMPL.0 是 TOUPCAM_OPTION_MULTITHREAD 多线程图像处理 1 否
(在相机已经开启的情况下,设置本选项,函数返回E_UNEXPECTED)TOUPCAM_OPTION_BINNING 数字binning:
0x01 (无binning)
0x02 (加法, 2*2)
0x03 (加法, 3*3)
0x04 (加法, 4*4)
0x05 (加法, 5*5)
0x06 (加法, 6*6)
0x07 (加法, 7*7)
0x08 (加法, 8*8)
0x82 (平均, 2*2)
0x83 (平均, 3*3)
0x84 (平均, 4*4)
0x85 (平均, 5*5)
0x86 (平均, 6*6)
0x87 (平均, 7*7)
0x88 (平均, 8*8)
最终图像尺寸向下圆整到偶数,如640/3得到2121 是 TOUPCAM_OPTION_ROTATE 顺时针旋转: 0°, 90°, 180°, 270° 0 是 TOUPCAM_OPTION_CG 转换增益(Conversion Gain):
0: LCG
1: HCG
2: HDRNA 是 TOUPCAM_OPTION_PIXEL_FORMAT pixel format NA 是
(启动相机之后不建议频繁修改,最好是在启动之前就设置好)TOUPCAM_OPTION_DDR_DEPTH DDR最多可以缓存的帧数:
1: DDR最大缓存一帧
0: 自动,视频模式下自动曝光开启时为1,其他为全部容量
-1: DDR最多可缓存至DDR全部容量0 是 TOUPCAM_OPTION_FFC 平场校正(Flat Field Correction):
设置(set):0: 禁用1: 启用-1: 重置(0xff000000 | n): 设置平均数为n, [1~255]获取(get):(val & 0xff): 0 -> 禁用, 1 -> 启用, 2 -> 已初始化((val & 0xff00) >> 8): 序号((val & 0xff0000) >> 8): 平均数0 是 TOUPCAM_OPTION_DFC 暗场校正(Dark Field Correction):
设置(set):0: 禁用1: 启用-1: 重置(0xff000000 | n): 设置平均数为n, [1~255]获取(get):(val & 0xff): 0 ->> 禁用, 1 -> 启用, 2 -> 已初始化((val & 0xff00) >> 8): 序号((val & 0xff0000) >> 8): 平均数0 是 TOUPCAM_OPTION_SHARPENING 锐化, (threshold << 24) | (radius << 16) | strength)
强度(strength): [0, 500], default: 0 (disable)半径(radius): [1, 10]阈值(threshold): [0, 255]0 是 TOUPCAM_OPTION_FACTORY 恢复出厂设置. 请注意恢复出厂设置可能导致分辨率改变
Only put恒为0 是 TOUPCAM_OPTION_TEC_VOLTAGE 获取TEC的当前工作电压,单位0.1伏,如59代表5.9伏.
请不要过于频繁获取本值,建议间隔2秒或以上
Only getNA NA TOUPCAM_OPTION_TEC_VOLTAGE_MAX 获取TEC的最大工作电压,单位0.1伏,如59代表5.9伏.
Only getNA NA TOUPCAM_OPTION_DEVICE_RESET 重置相机的usb连接,相当于模拟一次重新插拔.
Only putNA NA TOUPCAM_OPTION_AFPOSITION 自动对焦位置 NA 是 TOUPCAM_OPTION_AFMODE 自动对焦模式:
0: 手动
1: 自动
2: 单击
3: 共轭校准NA 是 TOUPCAM_OPTION_AFZONE 自动对焦区域 NA 是 TOUPCAM_OPTION_AFFEEDBACK 自动对焦反馈信息:
0: 未知
1: 聚焦
2: 正在对焦
3: 离焦
4: 上
5: 下
Only getNA 是 TOUPCAM_OPTION_TESTPATTERN test pattern:
0: TestPattern Off
3: monochrome diagonal stripes
5: monochrome vertical stripes
7: monochrome horizontal stripes
9: chromatic diagonal stripes
Only put0 是 TOUPCAM_OPTION_NOFRAME_TIMEOUT 最大曝光时间内没有获取到任何一帧完整数据,报错.
1 = 使能本特性;
0 = 禁用0 是 TOUPCAM_OPTION_NOPACKET_TIMEOUT 设定时间没有获取到任何视频包.
0 = 禁用
正整数 = 超时毫秒数0 是 TOUPCAM_OPTION_MAX_PRECISE_FRAMERATE 获取最大精确帧率. 单位0.1帧/秒,如115表示11.5帧/秒
最大帧率和分辨率/位深度/ROI等等相关
E_NOTIMPL表示不支持该功能NA NA TOUPCAM_OPTION_MIN_PRECISE_FRAMERATE 获取最小精确帧率. 单位0.1帧/秒,如11表示1.5帧/秒
最小帧率和分辨率/位深度/ROI等等相关
E_NOTIMPL表示不支持该功能NA NA TOUPCAM_OPTION_PRECISE_FRAMERATE 单位0.1帧/秒,如115表示11.5帧/秒. 范围:[[1~最大值] 最大帧率的90% 是 TOUPCAM_OPTION_BANDWIDTH 带宽, [1-100]% 90% 是 TOUPCAM_OPTION_RELOAD 触发模式下发生帧丢失时恢复最后一帧的数据.
get返回值S_OK表示支持本功能, E_NOTIMPL表示不支持.NA 是 TOUPCAM_OPTION_CALLBACK_THREAD 单独的专门线程用于回调,只在拉(Pull)模式下Callback可用,不能用于推(Push)模式 0 否 TOUPCAM_OPTION_FRAME_DEQUE_LENGTH Pull模式下帧队列长度,范围[2~1024] 3 否 TOUPCAM_OPTION_SEQUENCER_ONOFF sequencer trigger: 开启/关闭 0 是 TOUPCAM_OPTION_SEQUENCER_NUMBER sequencer trigger: 数量, 范围[1~255] NA 是 TOUPCAM_OPTION_SEQUENCER_EXPOTIME sequencer trigger: 曝光时间
iOption = TOUPCAM_OPTION_SEQUENCER_EXPOTIME | index
iValue = 曝光时间值
如设置第3组的曝光时间50ms,则调用:
Toupcam_put_Option(h, TOUPCAM_OPTION_SEQUENCER_EXPOTIME | 3, 50000)NA 是 TOUPCAM_OPTION_SEQUENCER_EXPOGAIN sequencer trigger: 增益
iOption = TOUPCAM_OPTION_SEQUENCER_EXPOGAIN | index
iValue = 增益值NA 是 TOUPCAM_OPTION_DENOISE 去噪
强度范围[0, 100], 0表示禁用0 是 TOUPCAM_OPTION_THREAD_PRIORITY 设置内部线程的优先级.
0 = THREAD_PRIORITY_NORMAL;
1 = THREAD_PRIORITY_ABOVE_NORMAL;
2 = THREAD_PRIORITY_HIGHEST;
3 = THREAD_PRIORITY_TIME_CRITICAL;
请参阅: SetThreadPriority
本选项在Linux和macOS平台下被忽略.1 是 TOUPCAM_OPTION_PROCESSMODE 0:full模式,图像质量更好,但是更耗费CPU.
1: fast模式,图像质量差些,耗费更少的CPU.
根据具体的使用情况选择FULL模式还是FAST模式.0 是 TOUPCAM_OPTION_LINEAR 0 = 关闭内部linear tone mapping
1 = 开启内部linear tone mapping1 是 TOUPCAM_OPTION_CURVE 0 = 关闭内部curve tone mapping
1 = 开启内部多项式拟合curve tone mapping
2 = 开启内部对数拟合tone mapping2 是 TOUPCAM_OPTION_COLORMATIX 0 = 关闭内部颜色矩阵
1 = 开启内部颜色矩阵1 是 TOUPCAM_OPTION_DEMOSAIC 视频和静态图像的Demosaic算法:(请参阅https://en.wikipedia.org/wiki/Demosaicing)
0 = BILINEAR
1 = VNG(Variable Number of Gradients interpolation)(暂时不可用)
2 = PPG(Patterned Pixel Grouping interpolation)
3 = AHD(Adaptive Homogeneity-Directed interpolation)
对于黑白相机始终返回E_NOTIMPL.0 是 TOUPCAM_OPTION_DEMOSAIC_VIDEO 视频的Demosaic算法 0 是 TOUPCAM_OPTION_DEMOSAIC_STILL 静态图像的Demosaic算法 0 是 重要提示:
a. 部分设置只可以在相机没有Start的情况下修改,也即不能被changed on-the-fly.
b. 不允许在PTOUPCAM_EVENT_CALLBACK和PTOUPCAM_DATA_CALLBACK_V3的回调上下文中调用Toupcam_put_Option设置TOUPCAM_OPTION_TRIGGER, TOUPCAM_OPTION_BITDEPTH, TOUPCAM_OPTION_PIXEL_FORMAT, TOUPCAM_OPTION_BINNING, TOUPCAM_OPTION_ROTATE,否则返回E_WRONG_THREAD.
c. UHCCD03100KPB, UHCCD05000KPA, UHCCD05100KPA的小分辨率不支持RAW模式.
返回值:HRESULT类型表示成功失败
参数:
HToupcam h:相机实例句柄
int val:
0: 当帧缓冲队列满时停止抓帧,直到队列中的帧被取走从而队列非满
1: 实时
使用最小的帧缓冲. 当新帧来到时,不论帧缓冲区是否满,都把所有的老帧全部丢弃.
如果有DDR,将同时把DDR帧缓冲也设为1. 2: 软实时
当帧缓冲区满时,丢弃最老的帧再入队新帧
说明:如果设置RealTime模式为1,更短的帧延时,但是帧速率降低,流畅性受损.缺省设为0,一般不需要改动.
返回值:HRESULT类型表示成功失败
参数:
HToupcam h:相机实例句柄
int bAutoExposure:TRUE or FALSE
unsigned short Target:自动曝光目标
unsigned maxTime, unsigned short maxAGain:自动曝光的最大曝光时间和最大模拟增益.默认值分别为350ms和500.
unsigned minTime, unsigned short minAGain:自动曝光的最小曝光时间和最小模拟增益.默认值分别为0和100.
说明:如果启用自动曝光,软件将自动设置曝光时间和模拟增益使得目标矩形的平均亮度尽量接近曝光目标(见Toupcam_put_AEAuxRect, Toupcam_get_AEAuxRect).
返回值:HRESULT类型表示成功失败
参数:
HToupcam h:相机实例句柄
unsigned Time:曝光时间,单位微秒
unsigned* nMin, unsigned* nMax, unsigned* nDef:曝光时间的最小值,最大值,默认值
说明:曝光时间相关. Toupcam_get_RealExpoTime获取基于50HZ/60HZ调整过的曝光时间.
返回值:HRESULT类型表示成功失败
参数:
HToupcam h:相机实例句柄
unsigned short AGain:模拟增益,百分比,如200表示增益200%
unsigned short* nMin, unsigned short* nMax, unsigned short* nDef:模拟增益的最小值,最大值,默认值
说明:模拟增益相关.
返回值:HRESULT类型表示成功失败
参数:HToupcam h:相机实例句柄
说明:设置或者得到:色度,饱和度,亮度,对比度,Gamma
返回值:HRESULT类型表示成功失败
参数:
HToupcam h:相机实例句柄
int bChrome:TRUE or FALSE
说明:多色模式或者单色模式.
返回值:HRESULT类型表示成功失败
参数: HToupcam h:相机实例句柄
说明:垂直或者水平翻转
返回值:HRESULT类型表示成功失败
参数:
HToupcam h:相机实例句柄
unsigned short nSpeed:帧速率级别
说明:最小帧速率等级是0.最大帧速率级别可以通过Toupcam_get_MaxSpeed函数得到,和ToupcamModelV2的maxspeed是一个意思.
返回值:HRESULT类型表示成功失败
参数:
HToupcam h:相机实例句柄
int nHZ:0表示60Hz交流,1表示50Hz交流,2表示直流
说明:设置光源的电力供应频率
返回值:HRESULT类型表示成功失败, E_NOTIMPL表示不支持读取/设置温度
参数:
HToupcam h:相机实例句柄
short nTemperature:以0.1℃为单位,如32表示3.2℃,-35表示-3.5℃.
说明:读取传感器温度(TOUPCAM_FLAG_GETTEMPERATURE表示支持读取温度).
设置传感器目标温度.
返回值:HRESULT类型表示成功失败
参数:
HToupcam h:相机实例句柄
int bSkip:Bin模式或者Skip模式
说明:设置Bin模式或者Skip模式.较高分辨率的相机支持2种采样模式,一种是Bin模式(邻域平均),一种是Skip模式(抽样提取).相比较而言,前者图像效果较好,但是帧速率降低;后者帧速率较高,但是图像效果较差.
返回值:HRESULT类型表示成功失败. Temp/Tint模式下起作用,RGB Gain模式下不起作用直接返回E_NOTIMPL.
参数:
HToupcam h:相机实例句柄
int nTemp, int nTint:色温和Tint
说明:Temp/Tint模式下设置/获取白平衡的色温和Tint参数.请参阅这里.
返回值:HRESULT类型表示成功失败. Temp/Tint模式下起作用,RGB Gain模式下不起作用直接返回E_NOTIMPL.
参数:
HToupcam h:相机实例句柄
PITOUPCAM_TEMPTINT_CALLBACK fnTTProc, void* pTTCtx:自动白平衡过程完成时的回调函数以及回调上下文.
说明:Temp/Tint白平衡模式下调用本函数来触发单次自动白平衡功能. 当白平衡参数计算完成的时候, TOUPCAM_EVENT_TEMPTINT事件会通知应用程序(Pull Mode)和调用回调函数. Pull mode中, 如果不使用回调函数, 请把函数指针设为NULL.
返回值:HRESULT类型表示成功失败. RGB Gain模式下起作用,Temp/Tint模式下不起作用直接返回E_NOTIMPL.
参数:
HToupcam h:相机实例句柄
int aGain[3]:RGB增益值
说明:RGB Gain模式下设置/获取白平衡的RGB增益值.请参阅这里.
返回值:HRESULT类型表示成功失败. RGB Gain模式下起作用,Temp/Tint模式下不起作用直接返回E_NOTIMPL.
参数:
HToupcam h:相机实例句柄
PITOUPCAM_WHITEBALANCE_CALLBACK fnWBProc, void* pWBCtx:自动白平衡过程完成时的回调函数以及回调上下文.
说明:RGB Gain白平衡模式下调用本函数来触发单次自动白平衡功能. 当白平衡参数计算完成的时候, TOUPCAM_EVENT_WBGAIN事件会通知应用程序(Pull Mode)和调用回调函数. Pull mode中, 如果不使用回调函数, 请把函数指针设为NULL.
返回值:HRESULT类型表示成功失败.
参数:
HToupcam h:相机实例句柄
PITOUPCAM_BLACKBALANCE_CALLBACK fnBBProc, void* pBBCtx:自动黑平衡过程完成时的回调函数以及回调上下文.
说明:调用本函数来触发单次自动黑平衡功能. 当黑平衡参数计算完成的时候, TOUPCAM_EVENT_BLACK事件会通知应用程序(Pull Mode)和调用回调函数. Pull mode中, 如果不使用回调函数, 请把函数指针设为NULL.
返回值:HRESULT类型表示成功失败
参数:
HToupcam h:相机实例句柄
unsigned short aSub[3]:RGB偏移值
说明:设置/获取黑平衡的RGB偏移值
返回值:HRESULT类型表示成功失败
参数:HToupcam h:相机实例句柄
说明:设置/获取自动白平衡和自动曝光和黑平衡的参考矩形.默认矩形位于图像正中央,宽度等于20%图像宽度,高度等于20%图像高度.
注意:坐标永远是相对原始分辨率而言的,请参阅这里.
返回值:S_OK表示单色模式,S_FALSE表示彩色模式
参数:HToupcam h:相机实例句柄
说明:是否单色相机,对应ToupcamModelV2的flag: TOUPCAM_FLAG_MONO
返回值:相机支持的最大位深度(Bit Depth)
参数:HToupcam h:相机实例句柄
说明:有些型号的相机支持比8bits更大的位深度,如10, 12, 14, 16等.
返回值:HRESULT类型表示成功失败
参数:
HToupcam h:相机实例句柄
unsigned nResolutionIndex:分辨率序号
int* pWidth, int* pHeight:宽度、高度
说明:Toupcam_get_StillResolutionNumber得到支持的静态抓拍分辨率个数(如UCMOS03100KPA返回3,表示支持3种分辨率),如果不支持静态抓拍能力,返回0.Toupcam_get_StillResolution得到每种分辨率的高度/宽度.
返回值:HRESULT类型表示成功失败
参数:
HToupcam h:相机实例句柄
char sn[32]:存放序列号的缓冲区. 如:TP110826145730ABCD1234FEDC56787
char fwver[16]: 存放固件版本号的缓冲区. 如: 3.2.1.20140922
char hwver[16]: 存放硬件版本好的缓冲区. 如: 3.12
char pdate[10]: 存放生产日期的缓冲区. 如: 20150327
unsigned short pRevision: revision
说明:每个相机都有一个唯一的31位的序列号.
返回值:HRESULT类型表示成功失败
参数:
HToupcam h:相机实例句柄
unsigned nResolutionIndex:分辨率序号
float* x, float* y: 物理像素大小(μm)
返回值:HRESULT类型表示成功失败
参数:
HToupcam h:相机实例句柄
unsigned short iLed:LED灯的序号
unsigned short iState:LED状态,1代表常亮,2代表闪烁,其它代表熄灭
unsigned short iPeriod:闪烁周期,毫秒数. 至少需要500ms.
说明:有些相机上安装有1到n个LED灯,本函数控制这些灯的状态.
返回值:HRESULT类型表示失败或读写的字节数
参数:
HToupcam h:相机实例句柄
unsigned addr: EEPROM读写地址
const unsigned char* pBuffer: 需要写入EEPROM的数据
unsigned char* pBuffer: 读取EEPROM的缓冲区
unsigned nBufferLen: 缓冲区长度
说明:有些相机上安装有EEPROM可供读写.读写失败时返回HRESULT错误码(负数),成功时返回读取或者写入的字节数.
返回值:HRESULT类型表示失败或读写的字节数
参数:
HToupcam h:相机实例句柄
unsigned addr: EEPROM读写地址
const unsigned char* pBuffer: 需要写入EEPROM的数据
unsigned char* pBuffer: 读取EEPROM的缓冲区
unsigned nBufferLen: 缓冲区长度
说明:有些相机上安装有EEPROM可供读写.读写失败时返回HRESULT错误码(负数),成功时返回读取或者写入的字节数.
返回值:HRESULT类型表示失败或读写的字节数
参数:
HToupcam h: 相机实例句柄
const unsigned char* pBuffer: 需要写入的数据
unsigned char* pBuffer: 读取缓冲区
unsigned nBufferLen: 缓冲区长度
说明:如果读写失败,返回负数HRESULT; 如果成功,返回读写成功的字节数.
返回值:HRESULT类型表示成功或失败
参数:
HToupcam h:相机实例句柄
返回值:HRESULT类型表示成功或失败
参数:
HToupcam h:相机实例句柄
返回值:HRESULT类型表示成功或失败
参数:
HToupcam h:相机实例句柄
unsigned index: IO口序号
unsigned nType: 控制类型,见下表
int outVal: 输出控制值
int* inVal: 输入控制值
TOUPCAM_IOCONTROLTYPE_GET_SUPPORTEDMODE 支持的模式:
0x01->输入
0x02->输出
(0x01 | 0x02)->同时支持输入和输出TOUPCAM_IOCONTROLTYPE_GET_GPIODIR IO方向:0x00->>输入, 0x01->>输出 TOUPCAM_IOCONTROLTYPE_SET_GPIODIR TOUPCAM_IOCONTROLTYPE_GET_FORMAT 格式:
0x00->>未连接
0x01->三态
0x02->TTL
0x03->LVDS
0x04->>RS422
0x05->光耦隔离TOUPCAM_IOCONTROLTYPE_SET_FORMAT TOUPCAM_IOCONTROLTYPE_GET_OUTPUTINVERTER 输出反相:boolean, 只支持输出信号 TOUPCAM_IOCONTROLTYPE_SET_OUTPUTINVERTER TOUPCAM_IOCONTROLTYPE_GET_INPUTACTIVATION 输入信号触发沿:0x00->>上升沿, 0x01->>下降沿 TOUPCAM_IOCONTROLTYPE_SET_INPUTACTIVATION TOUPCAM_IOCONTROLTYPE_GET_DEBOUNCERTIME 消抖时间, [0, 20000]微秒 TOUPCAM_IOCONTROLTYPE_SET_DEBOUNCERTIME TOUPCAM_IOCONTROLTYPE_GET_TRIGGERSOURCE 触发源:0x00->>光耦隔离输入
0x01->> GPIO0
0x02->> GPIO1
0x03->> 计数器分频模式
0x04->> 脉冲模式(PWM)
0x05->> 软件TOUPCAM_IOCONTROLTYPE_SET_TRIGGERSOURCE TOUPCAM_IOCONTROLTYPE_GET_TRIGGERDELAY 触发延迟时间, [0, 5000000]微秒 TOUPCAM_IOCONTROLTYPE_SET_TRIGGERDELAY TOUPCAM_IOCONTROLTYPE_GET_BURSTCOUNTER 突发计数:1, 2, 3 ... 1023 TOUPCAM_IOCONTROLTYPE_SET_BURSTCOUNTER TOUPCAM_IOCONTROLTYPE_GET_COUNTERSOURCE 计数器模式信号源:
0x00->> 光耦隔离输入
0x01->> GPIO0
0x02->> GPIO1TOUPCAM_IOCONTROLTYPE_SET_COUNTERSOURCE TOUPCAM_IOCONTROLTYPE_GET_COUNTERVALUE 计数值:1, 2, 3 ... 1023 TOUPCAM_IOCONTROLTYPE_SET_COUNTERVALUE TOUPCAM_IOCONTROLTYPE_SET_RESETCOUNTER 计数器复位 TOUPCAM_IOCONTROLTYPE_GET_PWMSOURCE 脉冲模式信号源:
0x00->> 光耦隔离输入
0x01->> GPIO0
0x02->> GPIO1TOUPCAM_IOCONTROLTYPE_SET_PWMSOURCE TOUPCAM_IOCONTROLTYPE_GET_OUTPUTMODE 输出模式:
0x00->> 触发等待信号
0x01->> 曝光有效信号
0x02->> 闪光灯信号
0x03->> 用户输出信号TOUPCAM_IOCONTROLTYPE_SET_OUTPUTMODE TOUPCAM_IOCONTROLTYPE_GET_STROBEDELAYMODE 闪光灯信号延迟模式, 0->> 预输出, 1->> 延迟输出; compared to exposure active signal TOUPCAM_IOCONTROLTYPE_SET_STROBEDELAYMODE TOUPCAM_IOCONTROLTYPE_GET_STROBEDELAYTIME 闪光灯信号延迟时间, [0, 5000000]微秒 TOUPCAM_IOCONTROLTYPE_SET_STROBEDELAYTIME TOUPCAM_IOCONTROLTYPE_GET_STROBEDURATION 闪光灯脉冲宽度, [0, 5000000]微秒 TOUPCAM_IOCONTROLTYPE_SET_STROBEDURATION TOUPCAM_IOCONTROLTYPE_GET_USERVALUE 用户输出数值:bit0->> 光耦隔离输出
bit1->> GPIO0输出
bit2->> GPIO1输出TOUPCAM_IOCONTROLTYPE_SET_USERVALUE TOUPCAM_IOCONTROLTYPE_GET_UART_ENABLE 启用串口: 1-> on; 0-> off TOUPCAM_IOCONTROLTYPE_SET_UART_ENABLE TOUPCAM_IOCONTROLTYPE_GET_UART_BAUDRATE 波特率:
0-> 9600
1-> 19200
2-> 38400
3-> 57600
4-> 115200TOUPCAM_IOCONTROLTYPE_SET_UART_BAUDRATE TOUPCAM_IOCONTROLTYPE_GET_UART_LINEMODE 线缆选择:
0-> TX(GPIO_0)/RX(GPIO_1)
1-> TX(GPIO_1)/RX(GPIO_0)TOUPCAM_IOCONTROLTYPE_SET_UART_LINEMODE
返回值:HRESULT类型表示成功失败
参数:HToupcam h:相机实例句柄
说明:自动LevelRange
返回值:HRESULT类型表示成功失败
参数:
HToupcam h:相机实例句柄
unsigned short aLow[4], unsigned short aHigh[4]: R, G, B和灰度的Level Range. RGB只对彩色图像有效, 灰度只对灰度图像有效.
说明:LevelRange相关.
返回值:HRESULT类型表示成功失败
参数:
HToupcam h:相机实例句柄
PITOUPCAM_HISTOGRAM_CALLBACK fnHistogramProc, void* pHistogramCtx:直方图数据的回调函数以及回调上下文
说明:获取直方图数据
参数 范围 默认值 获取 设置 自动 AutoExpoTarget
(自动曝光目标亮度)16~220 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 -127~127 0 Toupcam_get_WhiteBalanceGain Toupcam_put_WhiteBalanceGain Toupcam_AwbInit Green Gain Blue Gain LevelRange 0~255 Low = 0
High = 255Toupcam_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 Black Level(暗电平) 0~31 (位深度=8)
0~31 * 4 (位深度=10)
0~31 * 16 (位深度=12)
0~31 * 64 (位深度=14)
0~31 * 256 (位深度=16)Toupcam_get_Option Toupcam_put_Option Auto Exposure
(自动曝光)Max(最大) Exposure Time
(曝光时间)350ms Toupcam_get_MaxAutoExpoTimeAGain Toupcam_put_MaxAutoExpoTimeAGain Gain
(增益)500 Min(最小) Exposure Time
(曝光时间)0 Toupcam_get_MinAutoExpoTimeAGain Toupcam_put_MinAutoExpoTimeAGain Gain
(增益)100
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#是类似的,不另说明.
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存放在同一目录.
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放在合适目录
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_PullImageWithRowPitch和Toupcam_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: 初始发布
如果在使用Toupcam SDK的过程中,碰到任何问题,请与我们联系
网站:www.touptek.com
EMAIL:support@touptek.com