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工程中使用.
适用于WinRT / UWP (Universal Windows Platform) / Windows Store App的动态库文件.
它们和Windows Runtime兼容, 可以被Universal Windows Platform app引用.
如果使用C#开发UWP, 可以使用toupcam.cs包装类.
请注意:1. uwp只能使用WinUSB驱动, 不能使用私有私有驱动. 如果已安装, 请在设备管理器中卸载私有驱动, 之后Windows会自动使用Winusb.
2. uwp的DeviceCapability, 参阅How to add USB device capabilities to the app manifest.
USB(2017.1.1之后生产的相机内建支持WinUSB, 在Windows8及以上版本上不需要安装任何驱动.)除非想阻止设备出现在"安全删除硬件"列表中, 否则建议不要在Windows8及以上版本安装驱动.
如果仍然决定安装驱动, 建议使用DPInst.exe来自动安装驱动, 如使用NSIS制作安装文件, 可以使用类似如下语句:
GigE: GigE Performance Driver(Win7及以上版本)
不重启重新加载规则:
***Linux区分平台的简便方法, 在目标平台执行file /bin/ls. 以下为某树莓派下的结果, 可以看出属于armhf:另外一个示例, 可以看出属于x64:
请区分相机ID(camId)和相机SN:
(a) SN唯一并且是持久化的, 固化在相机内部一直保持不变, 不随连接和系统重启而变化.
(b) 相机ID(camId)因为连接或者系统重启可能变化, 枚举相机得到相机ID, 然后调用Open函数传入camId参数打开相机.
1. ImagePtr模式
应用程序直接从sdk得到帧缓冲区的指针, 节省了帧数据的拷贝过程, 性能更高. 调用函数Toupcam_PullImagePtr得到帧缓冲区, 调用函数Toupcam_PushImagePtr归还帧缓冲区.
typedef struct { unsigned id; /* 每个帧缓冲区都被赋予唯一ID, 0被保留为非法ID */ unsigned char pixelFormat; /* TOUPCAM_PIXELFORMAT_xxxx */ unsigned char ergb; /* see TOUPCAM_OPTION_RGB */ unsigned char snapR; /* see Toupcam_SnapR */ unsigned char infoVer; /* ToupcamFrameInfo版本, >= 4 */ unsigned reserved; unsigned strideRaw; /* RAW数据跨步(stride), 0表示没有无填充 */ ToupcamFrameInfoV4* ptrInfo; void* snapCtx; void* ptrRaw; /* RAW数据, see TOUPCAM_OPTION_IMAGEPTRRAW */ unsigned char* ptr8; /* 8bits, RGB24, RGB32, Grey8 */ unsigned short* ptr16; /* 16bits, RGB48, RGB64, Grey16 */ } ToupcamImagePtr; |
2. 帧内存拷贝(memcpy)模式
帧数据从sdk内部缓冲区memcpy至用户提供的缓冲区, 比ImagePtr模式多了拷贝过程, 性能损失.
“拉”模式和“推”模式从功能上说它们都是平等的, 开发者可以任选一种使用. 推荐使用拉模式, 因为它更简单, 且在多线程情况下更加不容易出错, 尤其是使用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回调函数.
| 事件 | 来源 | 描述 |
| TOUPCAM_EVENT_EXPOSURE | 软件 | 曝光时间发生改变 |
| TOUPCAM_EVENT_TEMPTINT | 白平衡参数发生改变, Temp/Tint模式, 请参阅这里. | |
| TOUPCAM_EVENT_WBGAIN | 白平衡参数发生改变, RGB Gain模式, 请参阅这里. | |
| TOUPCAM_EVENT_IMAGE | 视频图像数据到达(视频). 使用Toupcam_PullImageXXXX“拉”图像数据 | |
| TOUPCAM_EVENT_STILLIMAGE | 静态图片数据到达(Toupcam_Snap或Toupcam_SnapN引发). 使用Toupcam_PullImageXXXX“拉”图像数据 | |
| TOUPCAM_EVENT_ERROR | 一般性错误, 数据采集不能继续 | |
| TOUPCAM_EVENT_DISCONNECTED | 相机断开连接, 如被拔出 | |
| TOUPCAM_EVENT_NOFRAMETIMEOUT | 规定时间内没有抓取到视频帧. 见TOUPCAM_OPTION_NOFRAME_TIMEOUT | |
| TOUPCAM_EVENT_NOPACKETTIMEOUT | 规定时间内没有抓取到视频包. 见TOUPCAM_OPTION_NOPACKET_TIMEOUT | |
| TOUPCAM_EVENT_TRIGGERFAIL | 触发失败(如帧数据错误或超时) | |
| TOUPCAM_EVENT_BLACK | 黑平衡参数发生改变 | |
| TOUPCAM_EVENT_FFC | 平场校正(flat field correction)状态发生改变 | |
| TOUPCAM_EVENT_DFC | 暗场校正(dark field correction)状态发生改变 | |
| TOUPCAM_EVENT_FPNC | 固定模式噪声校正(fixed pattern noise correction)状态发生改变 | |
| TOUPCAM_EVENT_FRONT_OVERFLOW | 前端队列溢出 | |
| TOUPCAM_EVENT_BACK_OVERFLOW | 后端队列溢出 | |
| TOUPCAM_EVENT_ROI | ROI发生改变 | |
| TOUPCAM_EVENT_LEVELRANGE | Level range 发生改变 | |
| TOUPCAM_EVENT_AUTOEXPO_CONV | 自动曝光收敛 | |
| TOUPCAM_EVENT_AUTOEXPO_CONVFAIL | 单次模式自动曝光收敛失败 | |
| TOUPCAM_EVENT_FACTORY | 恢复出厂设置 | |
| TOUPCAM_EVENT_EXPO_START | 硬件 | 硬件事件：曝光开始 |
| TOUPCAM_EVENT_EXPO_STOP | 硬件事件：曝光结束 | |
| TOUPCAM_EVENT_TRIGGER_ALLOW | 硬件事件：触发允许 | |
| TOUPCAM_EVENT_TRIGGER_IN | 硬件事件：触发进入 | |
| TOUPCAM_EVENT_TRIGGER_FAIL | 硬件事件：触发失败 | |
| TOUPCAM_EVENT_HEARTBEAT | 硬件事件：心跳, 可以用于监视相机是否存活. 参见TOUPCAM_OPTION_HEARTBEAT |
大部分的相机型号都支持所谓静态抓拍的能力, 指相机在连续的视频预览过程中, 临时切换到另外一个分辨率, 抓取一帧静态图片之后, 马上把分辨率切换回原始分辨率的过程.
举例来说, 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_V4/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_OPTION_RGB调用函数Toupcam_put_Option来设置RGB的bits数. 请注意相机必须处于非运行状态才能修改此设置.
1. Toupcam支持互相独立的两种模式描述白平衡: a) Temp/Tint模式; b) RGB Gain模式
a) 默认是Temp/Tint模式, 在本模式下, 使用Temp, Tint这2个参数来控制白平衡. Toupcam_get_TempTint获取值, Toupcam_put_TempTint设置值. Toupcam_AwbOnce执行自动白平衡. 当白平衡参数改变时, 发送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_AwbOnce. 而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_AwbOnce不能使用, 永远返回E_NOTIMPL
两种模式在相机打开的时候指定, 除非关闭相机重新打开, 一旦指定就不能更改. 参阅这里.
2. 自动白平衡功能, 业界有两种模式, 一种是连续自动白平衡, 一种是触发式自动白平衡(once). 连续自动白平衡功能会一直进行白平衡参数的计算, 触发模式只是在触发的时候才会计算白平衡参数. 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用于设置触发模式的类型. 请参阅以下内容:
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秒).
采用一种中性自然的线程安全策略(类似C++标准库), 意味着:
a) 从多个线程读取单个相机对象是线程安全的. 例如, 给定一个相机对象A, 同时从线程1和线程2读取A是安全的.
b) 如果一个线程正在写入一个相机对象, 则同一线程或其他线程上对该对象的所有读取和写入都必须受到保护. 例如, 给定一个相机对象A, 如果线程1正在写A, 则必须阻止线程2读取或写入A.
c) 即使某线程正在读取或写入某相机对象, 其它线程读取和写入另外一个不同的相机对象是安全的. 例如, 给定相机对象A和B, 当线程1写入A, 线程2读取或写入B, 这是安全的. A和B完全独立.
d) 多线程Pull Image是安全的
SDK默认不输出日志. 如果SDK库文件所在目录存在并且具有写权限, 日志即被使能并记录在此文件中:
a) 日志文件名和库文件完全相同, 扩展名修改为*.log (如toupcam.dll对应log文件为toupcam.log; xyz.dll对应为xyz.log; libxyz.so对应libxyz.log)
b) 日志文件的时间默认使用相对时间, 把SDK启动时刻记为[00:00:00.000]. 如果想使用本地时间 (如[0923 17:11:01.491]), 在*.log扩展名中增加字母"l" (即*.llog)
c) 默认每次开启程序自动清空log文件的内容, 从零开始写日志. *.log增加字母"a", 表示使用append模式, 重启程序时不清空log文件内容 (即*.alog)
d) 默认使用同步方式写日志文件. 如果怀疑记录日志阻塞正常操作, 可以在*.log增加字母"s", 表示使用异步方式 (即*.slog)
e) 请确保程序对log文件有写权限(比如程序安装在Program Files目录下, 经常发生日志文件非管理员模式下不可写, 建议管理员模式运行程序或者修改日志文件的权限配置)
HRESULT在Windows平台上的使用很普遍. macOS, Linux和Android平台上借用之, 定义如下:
请注意, 返回值>=0都表示成功(特别地S_FALSE也是成功, 但和S_OK有区别, 比如内部值和用户设置的值已经一致, 相当于空操作). 所以, 一般情况下应该使用SUCCEEDED和FAILED宏来判断返回值是成功或者失败.
(除非有特殊需要, 不要使用"==S_OK"或"==0"来判断返回值)
| 名称 | 说明 | 备注 | 值 |
| S_OK | Success (成功) | 成功 | 0x00000000 |
| S_FALSE | Yet another success | 成功, 但和S_OK有所区别. 比如内部值和用户设置的值已经一致, 相当于空操作 | 0x00000001 |
| E_ACCESSDENIED | Permission denied (权限被拒绝) | 权限不足. 这可能是被系统安全策略阻止; 在Linux系统下, USB设备往往需要额外配置权限, 可通过设置udev规则文件, 或直接以root权限运行来解决 | 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 (无效指针) | 指针为NULL | 0x80004003 |
| E_UNEXPECTED | Catastrophic failure (灾难性故障) | 一般表示条件不符合, 如相机运行状态时调用put_Option设置某些不支持运行时修改的选项等等 | 0x8000ffff |
| E_WRONG_THREAD | Call function in the wrong thread (在错误的线程上下文中调用函数) | 请参阅这里, 这里, 这里 | 0x8001010e |
| E_GEN_FAILURE | Device not functioning (设备不响应) | 一般由硬件错误引起, 如线缆问题, USB口问题, 接触不良, 供电不足, 相机硬件损坏等等 | 0x8007001f |
| E_BUSY | The requested resource is in use (请求的资源在使用中) | 相机已经被占用, 如重复打开/启动相机, 或被其它程序使用中等等 | 0x800700aa |
| E_PENDING | The data necessary to complete this operation is not yet available (没有数据) | 暂时没有数据可供获取 | 0x8000000a |
| E_TIMEOUT | This operation returned because the timeout period expired (操作超时) | 0x8001011f | |
| E_UNREACH | Network is unreachable (网络不可达) | 请检查相机和电脑的IP设置, 或防火墙的设置 | 0x80072743 |
| E_CANCELLED | The operation was canceled by the user (操作被取消) | 0x800704c7 | |
| E_FAIL | Unspecified failure (未指定的错误) | 0x80004005 |
#define SUCCEEDED(hr) (((HRESULT)(hr)) >= 0) #define FAILED(hr) (((HRESULT)(hr)) < 0) |
在windows平台上, 这些HRESULT常量已经在系统头文件中定义过. 在其它平台上, 如果需要使用这些常量, 可以在#include "toupcam.h"之前#define TOUPCAM_HRESULT_ERRORCODE_NEEDED. 如下所示:
#define TOUPCAM_HRESULT_ERRORCODE_NEEDED #include "toupcam.h" |
在Win平台使用__stdcall, 请参阅这里
在macOS, Linux和Android使用__cdecl
这些回调函数是从toupcam.dll的内部线程上下文中回调出来, 所以, 非常有必要关注多线程问题. 请尽量保持回调函数代码的简洁, 并且快速返回.
回调模式下, 如果PTOUPCAM_EVENT_CALLBACK回调函数复杂, 可以设置TOUPCAM_OPTION_CALLBACK_THREAD, 使用专门的线程用于回调.
类似Toupcam_put_Roi, Toupcam_put_AEAuxRect等等这类带有坐标参数的, 其坐标永远是相对原始分辨率而言的, 即使图像已经执行过旋转, Flip, ROI, 数字Binning或它们的任意组合.
例外:
(a) 如果图像是倒置的(参考这里), 则坐标也必须倒置.
(b) 硬件Binning.
返回值：非负整数, 枚举到的相机数目
参数：ToupcamDeviceV2数组缓冲区
说明：调用该函数枚举计算机上当前插上的Toupcam相机. 函数返回时, ToupcamDeviceV2缓冲区包含有枚举到的每个相机实例的信息. 如果不关心多个相机同时联入电脑的情况的话, 调用本函数枚举相机实例是可选的.
(1). 如下面的代码片段：
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 */
unsigned ioctrol; /* number of input/output control */
float xpixsz; /* physical pixel size in micrometer, 像元尺寸 */
float ypixsz; /* physical pixel size in micrometer, 像元尺寸 */
ToupcamResolution res[TOUPCAM_MAX];
}ToupcamModelV2; /* device model v2 */
typedef struct {
#if defined(_WIN32)
wchar_t displayname[64]; /* 显示名称: 型号名称或用户指定的自定义名称(如果有并且使用Toupcam_EnumWithName, 使用Toupcam_EnumV2返回型号名称) */
wchar_t id[64]; /* camId */
#else
char displayname[64]; /* 显示名称: 型号名称或用户指定的自定义名称(如果有并且使用Toupcam_EnumWithName, 使用Toupcam_EnumV2返回型号名称) */
char id[64]; /* camId */
#endif
const ToupcamModelV2* model; /* Functionally equivalent to a global constant, remaining valid and unchanged throughout the lifetime of the process.
等价于全局常量, 在进程生命周期中一直有效且保持不变
*/
} ToupcamDeviceV2; /* device instance for enumerating */
|
| 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_USB32 | USB 3.2 Gen 2 | |
| TOUPCAM_FLAG_USB30 | USB3.0 | |
| TOUPCAM_FLAG_USB32_OVER_USB30 | USB 3.2 Gen 2相机被插入usb3.0端口 | |
| TOUPCAM_FLAG_USB30_OVER_USB20 | usb3.0相机被插入usb2.0端口 | |
| TOUPCAM_FLAG_ST4 | 支持ST4端口 | |
| TOUPCAM_FLAG_TEC | TEC制冷相机 | |
| TOUPCAM_FLAG_GETTEMPERATURE | 支持读取温度, Toupcam_get_Temperature | |
| TOUPCAM_FLAG_HIGH_FULLWELL | 支持高满阱模式 | |
| TOUPCAM_FLAG_RAW10 | TOUPCAM_PIXELFORMAT_RAW10 Pixel format, RAW 10 bits | |
| TOUPCAM_FLAG_RAW10PACK | TOUPCAM_PIXELFORMAT_RAW10PACK Pixel format, RAW 10 bits, packed | |
| TOUPCAM_FLAG_RAW11 | TOUPCAM_PIXELFORMAT_RAW11 Pixel format, RAW 11 bits | |
| TOUPCAM_FLAG_RAW12 | TOUPCAM_PIXELFORMAT_RAW12 Pixel format, RAW 12 bits | |
| TOUPCAM_FLAG_RAW12PACK | TOUPCAM_PIXELFORMAT_RAW12PACK Pixel format, RAW 12 bits, packed | |
| TOUPCAM_FLAG_RAW14 | TOUPCAM_PIXELFORMAT_RAW14 Pixel format, RAW 14 bits | |
| TOUPCAM_FLAG_RAW14PACK | TOUPCAM_PIXELFORMAT_RAW14PACK Pixel format, RAW 14 bits, packed | |
| TOUPCAM_FLAG_RAW16 | TOUPCAM_PIXELFORMAT_RAW16 Pixel format, RAW 16 bits | |
| TOUPCAM_FLAG_FAN | 支持制冷风扇 | |
| TOUPCAM_FLAG_TEC_ONOFF | TEC制冷装置支持开启/关闭, TEC制冷的目标温度, 见： TOUPCAM_OPTION_TEC TOUPCAM_OPTION_TECTARGET |
|
| TOUPCAM_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_EVENT_HARDWARE | 硬件事件(如曝光开始、停止等等). 参阅这里和这里 | |
| TOUPCAM_FLAG_YUV411 | TOUPCAM_PIXELFORMAT_YUV411 Pixel format | |
| TOUPCAM_FLAG_YUV422 | TOUPCAM_PIXELFORMAT_YUV422 Pixel format | |
| TOUPCAM_FLAG_YUV444 | TOUPCAM_PIXELFORMAT_YUV444 Pixel format | |
| TOUPCAM_FLAG_RGB888 | TOUPCAM_PIXELFORMAT_RGB888 Pixel format | |
| TOUPCAM_FLAG_RAW8 | TOUPCAM_PIXELFORMAT_RAW8 Pixel format, RAW 8 bits | |
| TOUPCAM_FLAG_GMCY8 | TOUPCAM_PIXELFORMAT_GMCY8 Pixel format, GMCY 8 bits | |
| TOUPCAM_FLAG_GMCY12 | TOUPCAM_PIXELFORMAT_GMCY12 Pixel format, GMCY 12 btis | |
| TOUPCAM_FLAG_GLOBALSHUTTER | 全局快门 | |
| TOUPCAM_FLAG_PRECISE_FRAMERATE | 支持精确帧率和带宽, 参阅TOUPCAM_OPTION_PRECISE_FRAMERATE和TOUPCAM_OPTION_BANDWIDTH | |
| TOUPCAM_FLAG_HEAT | 支持加热去雾, 参阅TOUPCAM_OPTION_HEAT和TOUPCAM_OPTION_HEAT_MAX | |
| TOUPCAM_FLAG_LOW_NOISE | 支持低噪声模式(更高的信噪比,更低的帧率). 参阅TOUPCAM_OPTION_LOW_NOISE | |
| TOUPCAM_FLAG_LEVELRANGE_HARDWARE | 支持硬件Level range | |
| TOUPCAM_FLAG_GIGE | 1 Gigabit GigE | |
| TOUPCAM_FLAG_25GIGE | 2.5 Gigabit GigE | |
| TOUPCAM_FLAG_5GIGE | 5 Gigabit GigE | |
| TOUPCAM_FLAG_10GIGE | 10 Gigabit GigE | |
| TOUPCAM_FLAG_40GIGE | 40 Gigabit GigE | |
| TOUPCAM_FLAG_CAMERALINK | camera link | |
| TOUPCAM_FLAG_CXP | CXP: CoaXPress | |
| TOUPCAM_FLAG_LINESCAN | 线阵相机 | |
| TOUPCAM_FLAG_FILTERWHEEL | 天文滤镜轮 | |
| TOUPCAM_FLAG_AUTOFOCUSER | 天文电调焦 | |
| TOUPCAM_FLAG_LIGHTSOURCE | 嵌入式光源控制 | |
| TOUPCAM_FLAG_LIGHT_SOURCE | 独立式光源 | |
| TOUPCAM_FLAG_GHOPTO | ghopto sensor(不支持增益, 转换增益支持高/中/低三种) | |
| maxspeed | 最大速度等级, 和函数Toupcam_get_MaxSpeed返回值相同. 速度范围是[0, maxspeed]. 可以通过Toupcam_put_Speed设置速度等级, Toupcam_get_Speed获取当前速度等级 | |
| preview | 预览分辨率的个数. 和函数Toupcam_get_ResolutionNumber返回值相同 | |
| still | 静态抓拍分辨率个数, 0表示不支持静态抓拍. 和函数Toupcam_get_StillResolutionNumber返回值相同 | |
| ioctrol | IO控制的数目 | |
| xpixsz ypixsz |
物理像元大小(微米), 见Toupcam_get_PixelSize | |
| res | 分辨率宽度和高度 | |
(2) 安卓平台上, 如果枚举不到相机, 有可能是NDK被限制了枚举USB设备的权限. 请参与这里.
返回值：无
参数：
PTOUPCAM_HOTPLUG funHotPlug: 回调函数
void* ctxHotPlug: 回调函数上下文
说明：
本函数只存在于macOS, Linux平台. 处理设备插入/拔出通知:
返回值：HRESULT类型表示成功或失败
参数：
PTOUPCAM_HOTPLUG funHotPlug：回调函数, 用于通知GigE相机上线/下线. 如果不需要相机上下线通知, 回调函数可以设为NULL.
void* ctxHotPlug: 回调函数上下文
说明：初始化对GigE相机的支持, 只需要在进程启动时调用一次即可.
返回值：相机句柄. 失败时返回NULL(如设备被突然拔出等等)
参数：
camId: Toupcam相机ID, 由Toupcam_EnumV2枚举得到. 如果camId是NULL则自动打开第一个相机, 所以, 如果不关心多个相机实例同时连入电脑的情况, Toupcam_EnumV2不是必须的, 直接传入参数NULL打开唯一的相机实例.
对于USB, GigE, CameraLink或CXP相机, camId也可以直接指定为(区分大小写, 没有空格):
(a) "sn:xxxxxxxxxxxx" (使用SN, 例如sn:d05f64ffff23)
(b) "name:xxxxxxxxxxxx" (使用用户设置的名称, 例如name:Camera1)另外, 对于GigE相机, camId也可以直接指定为(区分大小写, 没有空格):
(a) "ip:xxx.xxx.xxx.xxx" (使用IP地址, 例如ip:192.168.1.100)
(b) "mac:xxxxxxxxxxxx" (使用MAC地址, 例如mac:d05f64ffff23)
说明：打开相机实例.
(1) 在camId后面支持附着一些额外参数(用分号;分割, 区分大小写), 如:
见下表:
| 相机配置 (示例这里) |
不添加额外参数, 表示不需要相机配置的保存和加载功能. 添加参数, 相机打开时自动加载指定参数, 相机停止时自动保存参数. |
||||
| 位置 | ;registry=xxxx\yyyy | 注册表(Windows only) | 指定使用注册表HKEY_CURRENT_USER下的相对路径. 如果等号后面为空, 则使用注册表的默认位置: Software\XXX(公司名称)\capi\YYY(相机型号名称) |
||
| ;ini=x:\yyyy\zzzz.ini | .ini文件 | 使用文件x:\yyyy\zzzz.ini. 必须使用完整路径, 等号后面不能为空. 请确保目标目录存在并可读可写 | |||
| ;json=x:\yyyy\zzzz.json | .json文件 | 使用文件x:\yyyy\zzzz.json. 必须使用完整路径, 等号后面不能为空. 请确保目标目录存在并可读可写 | |||
| ;eeprom=xxxx | EEPROM | 使用EEPROM, 开始地址xxxx. 如果等号后面为空, 表示开始地址为0 | |||
| 预设 | ;preset=xxxx | 使用某个预设 | |||
| 白平衡模式 | ;wb=temptint or rgb | Temp/Tint模式或RGB Gain模式, 见这里 默认Temp/Tint |
|||
| USB块大小 | ;usbblocksize=xxx | 百分数, 范围:10~1000, 表示10%~1000% | |||
| linux平台上的零拷贝 | ;zerocopy=1或0 | 有利于减少内存拷贝, 提高效率. 要求Kernel版本>=4.6并且硬件平台支持. 如果图像出错, 表示该硬件平台不支持本特性, 请禁用之. 默认在安卓或ARM上禁用, 在非安卓的x86/x64平台上启用. | |||
2. Android
(a) 对于开放NDK枚举usb设备权限的安卓平台, 和普通流程一样, 没有任何区别.
(b) 对于没有开放NDK枚举usb设备权限的安卓平台, 只有通过Java侧获取设备权限, 得到文件描述符传递给Toupcam_Open, 得到HToupcam相机句柄之后的流程则没有区别. 如下:
usbManager = (UsbManager)getApplicationContext().getSystemService(Context.USB_SERVICE);
HashMap<String, UsbDevice> deviceList = usbManager.getDeviceList();
for (UsbDevice usbDevice : deviceList.values()) {
ModelV2 model = toupcam.get_Model((short)usbDevice.getVendorId(), (short)usbDevice.getProductId()); //通过VID/PID获取相机型号, 返回null表示非支持的设备
if (model != null) {
usbManager.requestPermission(usbDevice, mPermissionIntent); //获取权限
UsbDeviceConnection usbDeviceConnection = usbManager.openDevice(camDevice);
if (usbDeviceConnection != null) {
int fileDescriptor = usbDeviceConnection.getFileDescriptor(); //得到文件描述符
toupcam cam = toupcam.Open(String.format("fd-%d-%04x-%04x", fileDescriptor, usbDevice.getVendorId(), usbDevice.getProductId())); //打开相机
usbDeviceConnection.close(); //Java侧的usb连接不再需要, 强烈建议马上明确地关闭
if (cam != null) {
... //得到toupcam对象之后的流程没有区别, 正常使用即可
}
}
}
} |
3. Toupcam_Open/Close, Start/Stop是相对繁重的调用, 除非必要, 不推荐频繁操作.
返回值：无
参数：
HToupcam h：相机句柄
说明：关闭相机实例. 句柄关闭之后, 请不要再使用之.
返回值：HRESULT类型表示成功或失败
参数：
HToupcam h：相机句柄
strPara: 字符串参数
说明：加载配置:
(1) strPara为null或者空字符串: 从EEPROM的0地址加载
(2) strPara="eeprom=???": 从EEPROM的指定地址0x???加载
(3) strPara="path\to\file.ini": 从int文件加载
(4) strPara="path\to\file.json": 从json文件加载
返回值：HRESULT类型表示成功或失败
参数：
HToupcam h：相机句柄
HWND hWnd: 事件发生时, 消息将Post到这个窗口
unsigned nMsg: Windows自定义消息类型. 消息的WPARAM参数是事件类型TOUPCAM_EVENT_xxxx, LPARAM参数不用(恒等于0)
PTOUPCAM_EVENT_CALLBACK funEvent, void* ctxEvent：用户程序指定的回调函数和回调上下文参数.
请参阅这里.
说明：很明显, Toupcam_StartPullModeWithWndMsg只支持Windows系统
返回值：HRESULT类型表示成功或失败
参数：
HToupcam h：相机句柄
int bStill: 静态图片填1, 其它填0
unsigned waitMS: 超时值(毫秒). 如果指定非零值, 则该函数或者成功获取图像或者等待超时. 如果waitMS为零, 则没有图像可供获取时, 函数不会等待; 它总是立即返回; 相当于Toupcam_PullImagePtr
ToupcamImagePtr* ptrImage: 帧缓冲区
说明：使用ImagePtr模式获取帧缓冲区
返回值：HRESULT类型表示成功或失败
参数：
HToupcam h：相机句柄
unsigned ptrId: 帧缓冲区ID
说明：帧缓冲区使用完毕之后归还SDK以便重用. 请注意以下几点:
(a) 必须在使用完毕之后才归还. 一旦归还, 就不得再使用该帧缓冲. 如果归还之后还继续使用, 该缓冲区可能已经(正在)被SDK重用, 内存区域被写入新数据
(b) 如果帧缓冲区被遗漏归还, 可供使用的缓冲区越来越少
(c) Pull得到某ID帧缓冲区后, 只能归还一次, 不得重复归还
(d) 归还的顺序和Pull得到的顺序不需要一致, 也就是说可以乱序归还
(e) 未归还的帧缓冲区在Toupcam_Stop之后继续保持有效. 未归还的帧缓冲区在Toupcam_Close之后立即无效
返回值：HRESULT类型表示成功或失败, 不存在图像可供获取时返回E_PENDING
参数：
HToupcam h：相机句柄
waitMS: 超时值(毫秒). 如果指定非零值, 则该函数或者成功获取图像或者等待超时. 如果waitMS为零, 则没有图像可供获取时, 函数不会等待; 它总是立即返回; 相当于Toupcam_PullImageV4(V3).
void* pImageData：数据缓冲区. 用户应用程序必须确保改缓冲区足够大以容纳图像数据. 缓冲区大小必须 >= rowPitch * nHeight
int bStill: 静态图像填1, 其它填0
int bits：图像颜色位数, 支持24, 32, 48, 8, 16和64, 分别代表RGB24, RGB32, RGB48, 8位灰度, 16位灰度, RGB64图像. bits = 0表示使用基于TOUPCAM_OPTION_RGB的默认值. 本参数在RAW模式下没有意义, 被忽略
int rowPitch: 行间距(Stride, 跨距), 行与行之间的间距, =0表示默认使用行间距, =-1表示最小行间距(零填充)
unsigned* pnWidth, unsigned* pnHeight：输出参数, 图像的宽度高度
ToupcamFrameInfoV4/V3/V2* pInfo：输出参数, 本帧图像Info:
#define TOUPCAM_FRAMEINFO_FLAG_SEQ 0x00000001 /* 帧序号, frame sequence number */ #define TOUPCAM_FRAMEINFO_FLAG_TIMESTAMP 0x00000002 /* 时间戳, timestamp */ #define TOUPCAM_FRAMEINFO_FLAG_EXPOTIME 0x00000004 /* 曝光时间, exposure time */ #define TOUPCAM_FRAMEINFO_FLAG_EXPOGAIN 0x00000008 /* 曝光增益, exposure gain */ #define TOUPCAM_FRAMEINFO_FLAG_BLACKLEVEL 0x00000010 /* 暗电平, black level */ #define TOUPCAM_FRAMEINFO_FLAG_SHUTTERSEQ 0x00000020 /* 触发序号, sequence shutter counter */ #define TOUPCAM_FRAMEINFO_FLAG_GPS 0x00000040 /* GPS */ #define TOUPCAM_FRAMEINFO_FLAG_AUTOFOCUS 0x00000080 /* 自动对焦相关: uLum & uFV */ #define TOUPCAM_FRAMEINFO_FLAG_COUNT 0x00000100 /* 计数: timecount, framecount, tricount */ #define TOUPCAM_FRAMEINFO_FLAG_MECHANICALSHUTTER 0x00000200 /* 机械快门: 关闭 */ #define TOUPCAM_FRAMEINFO_FLAG_STILL 0x00008000 /* 静态图片, still image */ #define TOUPCAM_FRAMEINFO_FLAG_CG 0x00010000 /* 转换增益: 高 */ typedef struct { unsigned width; /* 图像宽度, 一直有效 */ unsigned height; /* 图像高度, 一直有效 */ unsigned flag; /* TOUPCAM_FRAMEINFO_FLAG_xxxx, flag置bit位, 代表对应的值有效, 取决于相机型号 */ unsigned seq; /* 帧序列号, frame sequence number */ unsigned long long timestamp; /* 帧时间戳, 单位微秒 */ unsigned shutterseq; /* 触发序号, sequence shutter counter */ unsigned expotime; /* 曝光时间 */ unsigned short expogain; /* 曝光增益 */ unsigned short blacklevel; /* 暗电平, black level */ } ToupcamFrameInfoV3; typedef struct { unsigned long long utcstart; /* 曝光开始时间: 纳秒数(00:00:00 UTC on Thursday, 1 January 1970, see https://en.wikipedia.org/wiki/Unix_time) */ unsigned long long utcend; /* 曝光结束时间 */ int longitude; /* 百万分之一度, 0.000001 degree */ int latitude; int altitude; /* 毫米 */ unsigned short satellite; /* 卫星数量 */ unsigned short reserved; /* 保留, 未使用 */ } ToupcamGps; typedef struct { ToupcamFrameInfoV3 v3; unsigned reserved; /* 保留, 未使用 */ unsigned uLum; unsigned long long uFV; unsigned long long timecount; unsigned framecount, tricount; ToupcamGps gps; } ToupcamFrameInfoV4;注: 除了图像宽度高度总是有效以外, 其它都取决于相机型号底层硬件是否支持. 通过判断相应的flag bit位是否设置来判断对应值是否有效.
说明：当pImageData为NULL而pInfo, pnWidth, pnHeight参数不为NULL的时候, 可以获取(Peek)是否存在图像以及图像的宽度高度等元信息.
(a) 当bits和TOUPCAM_OPTION_RGB不一致时, 将不得不进行格式转换, 造成损失效率. 见以下bits和TOUPCAM_OPTION_RGB对应表:
TOUPCAM_OPTION_RGB 0 (RGB24) 1 (RGB48) 2 (RGB32) 3 (Grey8) 4 (Grey16) 5 (RGB64) bits = 0 24 48 32 8 16 64 bits = 24 24 NA 转换至24 转换至24 NA NA bits = 32 转换至32 NA 32 转换至32 NA NA bits = 48 NA 48 NA NA 转换至48 转换至48 bits = 8 转换至8 NA 转换至8 8 NA NA bits = 16 NA 转换至16 NA NA 16 转换至16 bits = 64 NA 转换至64 NA NA 转换至64 64 (b) 请保证pImageData缓冲区的大小足够容纳整帧数据, 请看下表:
格式 0表示默认行间距(跨距) -1表示最小行间距(零填充) RGB RGB24 TDIBWIDTHBYTES(24 * Width) Width * 3 RGB32 Width * 4 Width * 4 RGB48 TDIBWIDTHBYTES(48 * Width) Width * 6 GREY8灰度图像 TDIBWIDTHBYTES(8 * Width) Width GREY16灰度图像 TDIBWIDTHBYTES(16 * Width) Width * 2 RGB64 Width * 8 Width * 8 RAW 8bits模式 Width Width 10bits, 12bits, 14bits, 16bits模式 Width * 2 Width * 2
#ifndef TDIBWIDTHBYTES
#define TDIBWIDTHBYTES(bits) ((unsigned)(((bits) + 31) & (~31)) / 8)
#endif
返回值：HRESULT类型表示成功或失败
参数：
HToupcam h：相机句柄
funData, ctxData：用户程序指定的回调函数和回调上下文参数. toupcam.dll内部从相机得到的图像数据后, 会回调该函数.
funEvent, ctxEvent: 事件回调函数和回调上下文参数.
typedef void (*PTOUPCAM_DATA_CALLBACK_V4)(const void* pData, const ToupcamFrameInfoV3* pInfo, int bSnap, void* ctxData); typedef void (*PTOUPCAM_DATA_CALLBACK_V3)(const void* pData, const ToupcamFrameInfoV2* pInfo, int bSnap, void* ctxData); 请参阅这里.
如果回调时, pData参数==NULL, 表示发生内部错误(如相机被突然拔出等等).
数据pData的行间距(row pitch, stride, 跨距)是默认值.
int bSnap参数, TRUE表示是由Toupcam_Snap或Toupcam_SnapN函数发起的图片抓拍, FALSE表示普通的预览图片(视频).
说明：开启相机实例.
返回值：HRESULT类型表示成功或失败
参数：相机句柄
说明：停止相机实例. 停止之后, 可以调用Toupcam_StartPushModeV4/V3重新开启. 比如切换视频分辨率：
步骤1：调用Toupcam_Stop停止
步骤2：调用Toupcam_put_Size或者Toupcam_put_eSize设置新分辨率
步骤3：调用Toupcam_StartXXXX(如Toupcam_StartPullModeWithWndMsg, Toupcam_StartPullModeWithCallback, Toupcam_StartPushModeV4/V3等等)重新开启
返回值：HRESULT类型表示成功或失败
参数：
HToupcam h: 相机句柄
int bPause: 1 => 暂停, 0 => 继续
说明：暂停或者继续视频流
返回值：HRESULT类型表示成功或失败
参数：
HToupcam h：相机句柄
unsigned nResolutionIndex：想要抓拍的分辨率序号. 0xffffffff表示使用当前预览分辨率.
说明：抓拍“静态”图片, 请参阅这里. 抓拍成功之后, 如果是Push Mode, 则通过TOUPCAM_EVENT_STILLIMAGE通知. 如果是Push Mode则通过PTOUPCAM_DATA_CALLBACK_V4/V3回调函数返回, 其中回调函数的参数BOOL bSnap设为TRUE.
有些相机支持在预览视频的不间断的情况下, 抓拍单张的不同于正在视频预览的分辨率的所谓静态图片. 例如UCMOS03100KPA, 正在预览的分辨率是1024*768, 调用Toupcam_Snap(h, 0)抓拍单张第0号分辨率(2048*1536)的图片.预览使用小分辨率(追求更快的帧率), 抓拍使用大分辨率(追求更好的图片质量). 这种行为, 称之为“静态抓拍”.
对于不支持静态抓拍的相机型号, 则参数nResolutionIndex的值必须等于当前正在预览的分辨率, 否则, 函数返回E_UNEXPECTED.
某个型号是否支持静态抓拍能力, 参见ToupcamModelV2的still域(大于0).Toupcam_SnapR用于抓拍"RAW"图像, 对于支持硬件ISP的相机, 跳过ISP的影响.
Toupcam_Snap(h, index) == Toupcam_SnapN(h, index, 1)
返回值：HRESULT类型表示成功或失败.
参数：
HToupcam h：相机句柄
unsigned short nNumber: 0xffff(一直触发), 0(取消触发), 其他值(触发图片的张数)
说明：触发模式下, 调用本函数进行软件触发. 触发成功之后, 如果是Pull Mode, 则通过TOUPCAM_EVENT_IMAGE通知. 如果是Push Mode则通过PTOUPCAM_DATA_CALLBACK_V4/V3回调函数返回, 其中回调函数的参数BOOL bSnap设为FALSE.
返回值：HRESULT类型表示成功或失败.
参数：
HToupcam h：相机句柄
unsigned waitMS: 超时值(毫秒). 如果waitMS为零, 表示使用默认值(曝光时间 * 102% + 4000毫秒), 0xffffffff表示永久等待, 其它值表示具体毫秒数
void* pImageData：数据缓冲区. 用户应用程序必须确保改缓冲区足够大以容纳图像数据. 缓冲区大小必须 >= rowPitch * nHeight
int bits：图像颜色位数, 支持24, 32, 48, 8, 16和64, 分别代表RGB24, RGB32, RGB48, 8位灰度, 16位灰度, RGB64图像. bits = 0表示使用基于TOUPCAM_OPTION_RGB的默认值. 本参数在RAW模式下没有意义, 被忽略
int rowPitch: 行间距(Stride, 跨距), 行与行之间的间距, =0表示默认使用行间距, =-1表示最小行间距(零填充)
ToupcamFrameInfoV4/V3* pInfo：输出参数, 本帧图像Info
说明：触发模式下, 调用本函数进行单次软件触发, 并等待图像到达.
返回值：HRESULT类型表示成功或失败
参数：
HToupcam h：相机句柄
unsigned nResolutionIndex：当前分辨率序号
int nWidth, int nHeight：当前分辨率的宽度高度
说明：设置或者得到当前分辨率.
设置分辨率应该在相机处于非运行状态下.
有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：当前分辨率的宽度高度
说明：设置或者得到当前分辨率.
设置分辨率应该在在相机处于非运行状态下.
有2种方法设置当前分辨率, 一种是通过分辨率的序号, 一种是通过宽度/高度. 两种方法是等效的. 比如UCMOS03100KPA支持以下3种分辨率:
序号0: 2048, 1536
序号1: 1024, 768
序号2: 680, 510
所以Toupcam_put_Size(h, 1024, 768) or Toupcam_put_eSize(h, 1)效果一样.Toupcam_get_FinalSize获取(经过ROI, Binning, 旋转, 等等之后)图像的最终宽度高度.
返回值：HRESULT类型表示成功或失败.
参数：
HToupcam h: 相机句柄
unsigned xOffset: x偏移, 必须是偶数, 否则返回E_INVALIDARG
unsigned yOffset: y偏移, 必须是偶数, 否则返回E_INVALIDARG
unsigned xWidth: 宽度. 最小值8, 必须是偶数, 否则返回E_INVALIDARG
unsigned yHeight: 高度. 最小值8, 必须是偶数, 否则返回E_INVALIDARG
说明: 设置/获取ROI. Toupcam_put_Roi(h, 0, 0, 0, 0)表示清除ROI恢复至原始尺寸.
重要提示: 不允许在PTOUPCAM_EVENT_CALLBACK和PTOUPCAM_DATA_CALLBACK_V4/V3的回调上下文中调用Toupcam_put_Roi, 否则返回E_WRONG_THREAD.
注意：坐标永远是相对原始分辨率而言的, 请参阅这里
返回值：HRESULT类型表示成功或失败
参数：
HToupcam h：相机句柄
unsigned nResolutionIndex：分辨率序号
int* pWidth, int* pHeight：宽度、高度
说明：Toupcam_get_ResolutionNumber得到支持的分辨率个数(如UCMOS03100KPA返回3, 表示支持3种分辨率). Toupcam_get_Resolution得到每种分辨率的高度/宽度.
这些参数在Toupcam_EnumV2返回相机实例的ToupcamModelV2都已经包含.
Toupcam_get_ResolutionRatio获取分辨率的Binning数, 用分数表示, 如1/1, 1/2, 1/3等等.
返回值：HRESULT类型表示成功或失败.
参数:
HToupcam h：相机句柄
unsigned* pFourCC：4种Bayer像素排列(MAKEFOURCC('G', 'B', 'R', 'G'), MAKEFOURCC('R', 'G', 'G', 'B'), MAKEFOURCC('B', 'G', 'G', 'R'), MAKEFOURCC('G', 'R', 'B', 'G'), 请参阅这里). 请注意, 不同软件定义Bayer时使用的坐标系Y轴方向可能不同(Y轴向上或向下), 所以互操作时有可能需要做一点映射. 如同一种像素排列, Y轴向下时Bayer是GRBG, Y轴向上则是BGGR.
unsigned* pBitsPerPixel：bitdepth, 如8, 10, 12, 14, 16
#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
返回值: HRESULT类型表示成功或失败
参数:
HToupcam h: 相机句柄
char cmd:
-1: 查询支持的Pixel Format数量
0~number: 查询第n条支持的Pixel Format的值int* pixelFormat: 输出, TOUPCAM_PIXELFORMAT_xxxx, 参阅这里
返回值: Pixel Format名称, 如"RAW10", "HDR12HL"等等
参数：
int pixelFormat: TOUPCAM_PIXELFORMAT_xxxx, 参阅这里
返回值：HRESULT类型表示成功或失败.
参数:
HToupcam h：相机句柄; 为NULL时查询预定义的枚举列表, 使用有效相机句柄时查询该相机支持的枚举列表
const char* strName: 枚举选项名(不区分大小写), 见下表
int* pNumber: 输出, 枚举项数量, 不能为NULL. *pNumber不用于指定数组容量
int arrValue[]: 输出, 枚举项的整数值数组, 可为NULL表示不获取整数值
const char* arrString[]: 输出, 枚举项的字符串名指针数组, 可为NULL表示不获取字符串名. 返回的字符串由SDK管理, 不应修改或释放
arrValue[i]与arrString[i]对应同一个枚举项, i的范围为0至*pNumber - 1. 整数值不一定等于数组索引.
用法：先将arrValue和arrString均设为NULL, 调用本函数获取数量; 再分配至少该数量的数组元素, 调用本函数获取列表. 两次调用之间应保持相机状态及影响枚举列表的设置不变, 确保数组容量足够.
例如ToneMapping的整数值0, 1, 2分别对应字符串名"Off", "Polynomial", "Logarithmic".
返回值：HRESULT类型表示成功或失败.
参数：
HToupcam h：相机句柄
unsigned iOption：旧接口的选项, 未来不再更新, 见下表
const char* strName: 选项(不区分大小写), 见下表
int iValue：值, 见下表
const char* strValue: 输入值(不区分大小写)
char strValue[]: 输出值(128字节长度肯定足够)
说明：
取值方式：
Int: 整数值, 使用Toupcam_put_Int / Toupcam_get_Int按strName设置或读取.
Str: 字符串值, 使用Toupcam_put_Str / Toupcam_get_Str按strName设置或读取.
Enum: 枚举值, 各离散取值代表特定的模式、状态、算法或开关含义, 见“说明”列. 使用Int接口传入或读取对应的整数值; 支持字符串形式的选项也可使用Str接口传入或读取对应的字符串名(不区分大小写), 支持枚举查询的选项可使用Toupcam_get_Enum查询取值及对应关系.
选项(iOption)：iOption及对应的Toupcam_put_Option / Toupcam_get_Option属于旧接口, 未来不再更新. 对于表中提供iOption的选项, 可使用这两个接口按iOption设置或读取整数值. 建议使用按strName访问的Toupcam_put_Int / Toupcam_get_Int或Toupcam_put_Str / Toupcam_get_Str.
分类：以下按所属功能分为多个表. 图像格式放在最前, 其余分类及主要项目顺序参考VisionLite的功能分组; 同类扩展项目放在对应分类中.
名称与范围查询：strName不区分大小写. 对于支持范围查询的选项, 在名称后添加Min、Max或Def, 分别使用Toupcam_get_Int查询最小值、最大值或默认值, 如GainMin、GainMax、GainDef. 这些查询为只读, 不在表中单独列出; 单位与原选项相同. 并非每个选项都支持全部三种查询, 不支持时以接口返回的HRESULT为准.
对于带序号的选项, 序号放在查询后缀之后, 如SequencerExposureTimeMin1、DebouncerTimeMax2. BlackLevel还提供BlackLevel8Max、BlackLevel10Max、BlackLevel11Max、BlackLevel12Max、BlackLevel14Max、BlackLevel16Max, 分别查询对应位深度的最大值. ResolutionMax、BinningMax和BinningModeMax返回可用项目数量, 不能直接作为最大索引或最大枚举值.
默认值查询的特殊行为: LightsourceDef返回本型号的最大光源亮度, HdrBDef在所提供的实现中返回默认HdrK值. 表中AETimeMin/Max、AEGainMin/Max等实际设置上下限的项目仍独立列出.
带序号的名称：名称末尾的N表示十进制序号占位符, 如LineMode2、SequencerExposureTime1, 调用时应替换为实际序号. 不带序号的I/O属性使用LineSelector选中的线路, 序列和定时触发属性使用对应的Selector. 型号相关的取值和设置限制以接口返回结果为准.
字符串形式：Enum选项只有在支持字符串映射时才能使用Str接口; 普通Int数值和Min/Max/Def查询应使用Int接口, 不能直接将数字字符串传给Str接口. 开关的字符串输入支持On/Off、Enable/Disable、Yes/No、True/False(不区分大小写), 字符串输出通常为On或Off. Str文件操作的输入是文件路径, 而非枚举值.
读写：RW = Read/Write(可读可写); RO = Read Only(只读); WO = Write Only(只写). 实际可用的读写操作以“读写”列为准.
运行状态限制：部分设置只可以在相机不在运行时才可以修改(下表“是否可以在相机处于运行状态设置该值”列为“否”).
图像格式 (ImageFormatControl)
分辨率、输出格式、位深度、Binning和ROI.
字符串名(strName) 取值方式 读写 说明 默认值 是否可以在相机处于运行状态设置该值
(调用Toupcam_StartXXXX之前或Toupcam_Stop之后)选项(旧接口)
(TOUPCAM_OPTION_XXXX)SensorWidth Int RO 传感器的有效宽度 NA NA SensorHeight Int RO 传感器的有效高度 NA NA FrameLineCount Int RW 每帧行数, 适用于支持可变帧行数的相机. 范围和默认值由FrameLineCountMin/Max/Def查询. 型号特定 否 PreviewResolution Int RW 相机视频模式的分辨率 NA 否 Resolution Enum RW 视频分辨率索引. 使用Toupcam_get_Enum查询整数索引及分辨率名称; ResolutionMax返回可用分辨率数量, 索引范围为[0, ResolutionMax - 1]. 对应Toupcam_put_eSize/get_eSize. 型号特定 否 StillResolution Int RW 相机静态捕获时的分辨率, 静态抓拍指相机在连续的视频预览过程中, 临时切换到另外一个分辨率, 抓取一帧静态图片之后, 马上把分辨率切换回原始分辨率的过程
对应函数: Toupcam_get_StillResolution0 是 WidthMax Int RO 经过水平合并、抽取或其他改变图像水平尺寸的处理后, 图像的最大宽度(像素), 不考虑当前 ROI 的 Width 和 OffsetX NA NA HeightMax Int RO 经过垂直合并、抽取或其他改变图像垂直尺寸的处理后, 图像的最大高度(像素), 不考虑当前 ROI 的 Height 和 OffsetY NA NA OutputFormat Enum RW 输出图像格式, 将Raw模式和RGB格式合并为一个枚举选项.
取值及含义:
0: "RGB24", Raw = 0, RGB = 0, 24位RGB
1: "RGB48", Raw = 0, RGB = 1, 48位RGB(位深度大于8时可用)
2: "RGB32", Raw = 0, RGB = 2, 32位RGB
3: "Grey8", Raw = 0, RGB = 3, 8位灰度(仅黑白相机)
4: "Grey16", Raw = 0, RGB = 4, 16位灰度(仅黑白相机且位深度大于8)
5: "RGB64", Raw = 0, RGB = 5, 64位RGB(位深度大于8时可用)
254 (0xfe): "Raw", Raw = 1, 直接输出传感器数据
253 (0xfd): "Raw2", Raw = -1, 输出RAW数据并执行FFC、DFC、FPNC、黑平衡和白平衡
设置:选择RGB或灰度格式时, 先设置Raw = 0, 再设置对应的RGB值; 选择Raw或Raw2时, 只设置Raw = 1或-1, 不改变已保存的RGB值. 例如Toupcam_put_Str(h, "OutputFormat", "RGB24")相当于先设置Raw = 0, 再设置RGB = 0; 设置"Raw2"相当于设置Raw = -1.
读取:Raw = 1时返回254 / "Raw", Raw = -1时返回253 / "Raw2"; Raw = 0时返回当前RGB对应的整数值或字符串名. OutputFormat使用独立的枚举编码, Raw选项的1和-1不能直接作为OutputFormat的RAW取值.
使用Toupcam_get_Enum(h, "OutputFormat", ...)查询当前相机支持的格式, RGB48、RGB64和Grey16的可用性取决于当前PixelFormat的位深度, Grey8和Grey16只适用于黑白相机. PixelFormat控制传感器数据格式和位深度, OutputFormat控制交给应用的输出格式. 设置时的运行状态限制与对应的Raw、RGB选项相同.NA 否 OutputFormatStill Enum RW 静态图像输出格式, 使用OutputFormat对应的整数编码. 仅支持静态图像的相机可用; 当前未使用RGB静态输出时get_Int返回E_UNEXPECTED. 型号特定 是 Raw Enum RW 0: RGB模式
1: RAW模式, 直接获取传感器(相机)数据
-1: RAW模式, 和1的区别是执行FFC, DFC, FPNC, 黑平衡, 白平衡0 否
(在相机处于运行状态时, 设置RAW和非RAW之间变化返回E_UNEXPECTED)
是(1和-1之间变化)RAW RGB Enum RW 0: 使用RGB24
1: 在位深度>8时, 启用RGB48格式
2: 使用RGB32
3: 8位灰度(只对黑白相机有效)
4: 16位灰度(只对黑白相机并且位深度>8时有效)
5: 在位深度>8时, 启用RGB64格式0 否
(在相机处于运行状态时, 设置本选项, 函数返回E_UNEXPECTED)RGB ImagePtrRaw Enum RW 0: 不包含RAW数据(默认)
1: 即使当前不是RAW格式, Toupcam_PullImagePtr/WaitImagePtr 返回的 ToupcamImagePtr 中 ptrRaw 也会包含RAW数据0 否 IMAGEPTRRAW ImagePtrBoth Enum RW 图像指针双位深输出:
0: 关闭
1: 开启. 当输出格式为8 bit且传感器实际输出位深度大于8 bit时, 返回的ToupcamImagePtr结构体同时提供ptr8和ptr16指针
必须在相机停止时设置0 否 IMAGEPTRBOTH PixelFormat Enum RW TOUPCAM_PIXELFORMAT_RAW8
TOUPCAM_PIXELFORMAT_RAW10
TOUPCAM_PIXELFORMAT_RAW12
TOUPCAM_PIXELFORMAT_RAW14
TOUPCAM_PIXELFORMAT_RAW16
TOUPCAM_PIXELFORMAT_YUV411
TOUPCAM_PIXELFORMAT_VUYY
TOUPCAM_PIXELFORMAT_YUV444
TOUPCAM_PIXELFORMAT_RGB888
TOUPCAM_PIXELFORMAT_GMCY8 (map to RGGB 8 bits)
TOUPCAM_PIXELFORMAT_GMCY12 (map to RGGB 12 bits)
TOUPCAM_PIXELFORMAT_UYVY
TOUPCAM_PIXELFORMAT_RAW12PACK
TOUPCAM_PIXELFORMAT_RAW11
TOUPCAM_PIXELFORMAT_HDR8HL(HDR, 位深度: 8, 转换增益: 高 + 低)
TOUPCAM_PIXELFORMAT_HDR10HL(HDR, 位深度: 10, 转换增益: 高 + 低)
TOUPCAM_PIXELFORMAT_HDR11HL(HDR, 位深度: 11, 转换增益: 高 + 低)
TOUPCAM_PIXELFORMAT_HDR12HL(HDR, 位深度: 12, 转换增益: 高 + 低)
TOUPCAM_PIXELFORMAT_HDR14HL(HDR, 位深度: 14, 转换增益: 高 + 低)
TOUPCAM_PIXELFORMAT_RAW10PACK型号特定 是
(相对比较“重型”的操作, 不建议在相机处于运行状态时太频繁修改)PIXEL_FORMAT PixelSize Enum RO 像素位数查询. NA NA BitDepth Enum RW 一些型号的相机支持大于8Bits的位深度(bitdepth), 如10,12,14,16等.
0: 使用8Bits位深度.
1: 使用本相机支持的最高位深度型号特定 是
(相对比较“重型”的操作, 不建议在相机处于运行状态时太频繁修改)BITDEPTH BitRange Int RW Bit范围: [0, 8], 参阅: 截图 0 是 BITRANGE ByteOrder Enum RW 字节序:
1: BGR
0: RGBWin: 1
Linux/MacOS/Android: 0是
(相对比较“重型”的操作, 不建议在相机处于运行状态时太频繁修改)BYTEORDER ZeroPadding Enum RW 当Bitdepth大于8小于16时补零方法:
0: 高位补零
1: 低位补零0 是 ZERO_PADDING BinningMode Enum RW 硬件Binning的模式:
1: 平均
2: 叠加
3: 跳过NA 否 Binning Int RW 控制硬件Binning合并因子, 通过合并相邻感光像素降低图像分辨率, 具体合并方式由BinningMode控制
对应函数: Toupcam_get/put_BinningNA 否 DigitalBinning Int RW 数字binning:
0x01 (无binning)
n: (饱和加法, n*n), 0x02(2*2), 0x03(3*3), 0x04(4*4), 0x05(5*5), 0x06(6*6), 0x07(7*7), 0x08(8*8). 数据的Bitdepth保持不变.
0x40 | n: (非饱和加法, n*n, 只在RAW模式下支持), 0x42(2*2), 0x43(3*3), 0x44(4*4), 0x45(5*5), 0x46(6*6), 0x47(7*7), 0x48(8*8). 数据的Bitdepth增加, 如Bitdepth为12的原始数据2*2 Binning之后Bitdepth增加2位变成14.
0x80 | n: (平均, n*n), 0x82(2*2), 0x83(3*3), 0x84(4*4), 0x85(5*5), 0x86(6*6), 0x87(7*7), 0x88(8*8). 数据的Bitdepth保持不变.
最终图像尺寸向下圆整到偶数, 如640/3得到2121 是 BINNING Width Int RW 设备输出图像的宽度(像素), 该值反映当前感兴趣区域(ROI), 范围[8, WidthMax-OffsetX], 步进2, 默认值WidthMax WidthMax 否 Height Int RW 设备输出图像的高度(像素), 该值反映当前感兴趣区域(ROI), 范围[8, HeightMax-OffsetY], 步进2, 默认值HeightMax HeightMax 否 FinalWidth Int RO 经过ROI、Binning、旋转等处理后的图像最终宽度, 单位像素.
对应函数: Toupcam_get_FinalSize的宽度输出NA NA FinalHeight Int RO 经过ROI、Binning、旋转等处理后的图像最终高度, 单位像素.
对应函数: Toupcam_get_FinalSize的高度输出NA NA OffsetX Int RW 从图像原点到感兴趣区域(ROI)的水平偏移(像素), 范围[0, WidthMax-Width], 步进2, 默认值0 0 否 OffsetY Int RW 从图像原点到感兴趣区域(ROI)的垂直偏移(像素), 范围[0, HeightMax-Height], 步进2, 默认值0 0 否 PayloadSize Int RO 当前图像的有效载荷大小, 单位字节. NA NA 设备控制 (DeviceControl)
设备信息、温控、网络、外围设备和配置管理.
字符串名(strName) 取值方式 读写 说明 默认值 是否可以在相机处于运行状态设置该值
(调用Toupcam_StartXXXX之前或Toupcam_Stop之后)选项(旧接口)
(TOUPCAM_OPTION_XXXX)DeviceScanType Enum RW 扫描类型:
0: 面阵扫描
1: 线阵扫描linescan型号特定 是 SCANTYPE DeviceModelName Str RO 制造商为区分产品用于唯一识别该相机型号
等于 Toupcam_query_Model 返回的 ToupcamModelV2::nameNA NA ClsName Str RO 相机内部类别名称. NA NA Hid Enum RO 是否为HID设备:
0: 否
1: 是.NA NA Revision Int RO 相机硬件修订号, 对应Toupcam_get_Revision. NA NA DeviceID Str RO 用于表示设备唯一标识符(序列号)
对应函数: Toupcam_get_SerialNumberNA NA DeviceUserID Str RW 用户可编程的设备标识符, 该值可写并持久保存, 出厂默认值为空字符串
对应函数: Toupcam_query_Name/set_NameNA 是 FPGAVersion Str RO 相机FPGA固件的版本号
对应函数: Toupcam_get_FpgaVersionNA NA FirmwareVersion Str RO 相机固件的版本号
对应函数: Toupcam_get_FwVersionNA NA HardwareVersion Str RO 相机物理电路板及元器件组合的特定设计修订标识号
对应函数: Toupcam_get_HwVersionNA NA ProductionDate Str RO 相机出厂的具体日期
对应函数: Toupcam_get_ProductionDateNA NA MCUVersion Str RO 相机微控制器单元所烧录固件的版本标识号 NA NA CameraIP Str RW GigE相机在网络中的逻辑地址
支持GigE的构建中可使用Toupcam_put_Str设置IP地址.NA 型号相关 CameraMAC Str RO GigE相机网络接口的物理地址, 用于局域网中的设备唯一标识与链路层通信 NA NA HostAdapter Str RO 主机端用于连接网络相机的网卡 NA NA AdapterSpeed Int RO 网卡链接速度(接收/传输) NA NA HostIP Str RO GigE相机连接的网卡IP地址 NA NA HostMAC Str RO GigE相机连接的网卡MAC地址 NA NA PacketSize Int RO GigE相机在单次网络数据包中所包含的图像有效负载数据的字节数 NA NA GvcpTimeout Int RW GVCP Timeout, 毫秒, 范围: [5, 150]
除非非常特殊情况, 一般而言不需要修改, 保持默认值即可15(有线)
30(无线)是 GVCP_TIMEOUT GvcpRetry Int RW GVCP Retry, 次数, 范围: [2, 16]
除非非常特殊情况, 一般而言不需要修改, 保持默认值即可4(有线)
8(无线)是 GVCP_RETRY GvspWaitPercent Int RW GVSP wait 百分比: 范围: [0, 100] 触发模式: 100
实时: 0
其它: 1是 GVSP_WAIT_PERCENT GigeTimeout Enum RW 对于 GigE 相机，应用程序会定期向相机发送心跳信号，以保持与相机的连接处于活动状态。如果相机在心跳超时计数器指定的时间内未收到心跳信号，相机将重置连接。当应用程序被调试器暂停时，应用程序将无法生成心跳信号。
0: 自动: 当相机被打开时, 如存在调试器则禁用, 如不存在调试器则启用
1: 启用
2: 禁用0 是 GIGETIMEOUT Heartbeat Int RW 心跳间隔, 单位毫秒
范围: [TOUPCAM_HEARTBEAT_MIN, TOUPCAM_HEARTBEAT_MAX]
0: 禁用禁用 是 HEARTBEAT NoPacketTimeout Int RW 没有抓取到视频包的超时时间. 当设定时间内没有获取到任何视频包时, 触发事件TOUPCAM_EVENT_NOPACKETTIMEOUT
0: 禁用
正整数(>=TOUPCAM_NOPACKET_TIMEOUT_MIN) => 超时毫秒数0 是 NOPACKET_TIMEOUT SensorType Enum RO 图像传感器芯片的类别 NA NA PhysicalPixelWidth Int RO 感光像素在X方向的物理间距, 单位0.001微米; get_Int返回xpixsz乘以1000后的整数. NA NA PhysicalPixelHeight Int RO 感光像素在Y方向的物理间距, 单位0.001微米; get_Int返回ypixsz乘以1000后的整数. NA NA Uptime Int RO 设备上电行时间(毫秒) NA NA UPTIME GPS Enum RO GPS状态
0: 不支持
-1: GPS设备不在线
1: GPS设备在线NA NA GPS TECEnable Enum RW 一些型号的相机支持开启关闭TEC制冷装置.
0: 关闭TEC制冷
1: 开启TEC制冷1 是 TEC TECTarget Int RW 获取和设置TEC制冷的目标温度, 单位0.1℃. 例如, 125表示12.5℃, -35表示-3.5℃.
设置目标温度为"-2730"或以下表示使用本型号的默认值.型号特定 是 TECTARGET TECTargetRange Int RO 获取TEC制冷的目标温度的范围, 单位0.1℃. 例如, 125表示12.5℃, -35表示-3.5℃.
最小值(low 16 bits) = (short)(val & 0xffff)
最大值(high 16 bits) = (short)((val >> 16) & 0xffff).型号特定 是 TECTARGET_RANGE TECVoltageMax Int RW TEC的最大工作电压, 单位0.1伏, 如59代表5.9伏 NA NA TEC_VOLTAGE_MAX TECVoltageMaxRange Int RO 获取TEC的最大工作电压范围, 单位0.1伏, 如59代表5.9伏
高16位: 最大值
低16位: 最小值NA NA TEC_VOLTAGE_MAX_RANGE TECVoltage Int RO 获取TEC的当前工作电压, 单位0.1伏, 如59代表5.9伏.
请不要过于频繁获取本值, 建议间隔2秒或以上NA NA TEC_VOLTAGE Fan Int RW 一些型号的相机支持制冷风扇.
0: 关闭风扇
[1, max]: 风扇速率
设置为"-1"表示使用本型号的默认值型号特定 是 FAN FanSpeed Int RO 读取风扇实际转速, 单位由相机型号定义; 不同于Fan的设定挡位. NA NA Heat Int RW 加热去雾级别 型号特定 是 HEAT HeatMax Int RO 获取最大加热去雾级别
[0, max], 0: 关闭NA NA HEAT_MAX SensorTemperature Int RO 图像传感器当前实测的工作温度值
对应函数: Toupcam_get_TemperatureNA NA ChamberTemperature Int RO 密封舱温度, 单位0.1℃, 如32表示3.2℃. 按strName读取时返回温度值; 对应TOUPCAM_OPTION_CHAMBER_HT的低16位. NA NA ChamberHumidity Int RO 密封舱湿度, 单位0.1%, 如325表示32.5%. 按strName读取时返回湿度值; 对应TOUPCAM_OPTION_CHAMBER_HT的高16位. NA NA Int RO 密封舱湿度和温度:
高16位: 湿度, 单位0.1%, 如325表示湿度=32.5%
低16位: 温度, 单位0.1℃, 如32表示3.2℃NA NA CHAMBER_HT EnvironmentTemperature Int RO 环境温度, 单位0.1℃, 如32表示3.2℃. 按strName读取时返回温度值; 对应TOUPCAM_OPTION_ENV_HT的低16位. NA NA EnvironmentHumidity Int RO 环境湿度, 单位0.1%, 如325表示32.5%. 按strName读取时返回湿度值; 对应TOUPCAM_OPTION_ENV_HT的高16位. NA NA Int RO 环境湿度和温度 NA NA ENV_HT PowerConsumption Int RO 获取功耗, 单位: 毫瓦 NA NA POWER Power Int RO 获取功耗, 单位毫瓦. NA NA ScanDirection Enum RW 扫描方向:
0: 正
1: 反
2: 交替0 是 SCAN_DIRECTION TestPattern Enum RW test pattern:
0: off
3: monochrome diagonal stripes
5: monochrome vertical stripes
7: monochrome horizontal stripes
9: chromatic diagonal stripes0 是 TESTPATTERN MechanicalShutter Enum RW 机械快门:
0: 开
1: 关0 是 MECHANICALSHUTTER ShutterTrigger Enum RW 快门触发方式:
0: 脉冲触发
1: 电平触发.型号特定 型号相关 ResetSeqTimestampMode Enum RW 选择重置相机输出帧的序列和时间戳模式:
1: 序列
2: 时间戳
3: 序列和时间戳2 是 ResetSeqTimestamp Enum WO 复位seq, timestamp:
1: seq
2: timestamp
3: bothNA 是 RESET_SEQ_TIMESTAMP ModeSeqTimestamp Enum RW seq和timestamp模式:
0: 主动复位到0
1: 从不主动复位0 是 MODE_SEQ_TIMESTAMP TailLight Enum RW 打开关闭尾灯:
0: 关
1: 开1 是 TAILLIGHT EventHardware Enum RW 启用或禁用硬件事件通知: iValue = 1 (enable), 0 (disable) (1) iOption = TOUPCAM_OPTION_EVENT_HARDWARE, 所有硬件事件通知的总开关只有总开关和特定类型的子开关都保持开启, 才算真正启用该类型的事件通知.
(2) iOption = TOUPCAM_OPTION_EVENT_HARDWARE | (event type), 特定类型的子开关
参阅这里和这里禁用 总开关: 否
子开关: 是EVENT_HARDWARE EventHardwareSelector Int WO 选择EventHardware不带序号时访问的事件类型; 0: 总开关, 其他值为硬件事件类型. 0 是 EventHardwareN Enum RW 编号N对应的硬件事件通知开关:
0: 禁用
1: 启用; N=0: 总开关.NA 型号相关 LightSource Int RW 光源亮度级别 50%最大级别 是 LIGHTSOURCE LightSourceMax Int RO 获取最大光源亮度级别
[0, max], 0: 关闭NA NA LIGHTSOURCE_MAX FilterWheelSlot Int RW 滤镜轮孔数 7 是 FILTERWHEEL_SLOT FilterWheelPosition Int RW 滤镜轮位置:
设置(set):-1: 校准获取(get):
val & 0xff: 位置
(val >> 8) & 0x1: 方向, 0: 顺时钟, 1: 自动方向-1: 动作中
val: 目标到达NA 是 FILTERWHEEL_POSITION FilterWheelSpeed Int RW 滤镜轮转动速度, 数值单位和范围由滤镜轮定义. 型号特定 型号相关 FilterWheelSlotNameN Str RW HID滤镜轮第N孔的名称, N范围[0, 15], 如FilterWheelSlotName0. NA 型号相关 MotorNumber Int RW 范围: [1, 20] MOTOR_NUMBER MotorPos Int RW 马达位置, 范围[1, 702]. 使用MotorPosN指定马达序号N, 如MotorPos1; 每个名称读写一个位置值. MOTOR_POS MotorPosN Int RW 第N个马达的位置, 如MotorPos1, 位置范围[1, 702]; 马达序号受MotorNumber限制. NA 型号相关 FocusPos Int RW 对焦马达位置 NA 是 FOCUSPOS AfMode Enum RW 自动对焦模式: 见ToupcamAFMode NA 是 AFMODE AfStatus Enum RO 自动对焦状态: 见ToupcamAFStaus NA NA AFSTATUS EEPROMSize Int RO 查询EEPROM容量. 本接口通过HRESULT返回容量, 不写入piValue; 负值表示失败. NA NA EEPROM_SIZE EEPROMCfg Enum RO 查询相机是否支持在EEPROM中保存配置: 支持时返回S_OK, 否则E_NOTIMPL; 此查询不写入piValue. NA NA LensState Enum WO 镜头状态加载/保存到EEPROM:
0: 加载
1: 保存LENSSTATE UserSet Int RW 用户设置: put_Int保存指定编号的设置; get_Int加载设置, 调用前须将*piValue设为要加载的编号, 并停止相机. 此处get_Int执行加载操作, 不读取当前设置值. 否 USER_SET Preset Enum RW get_Int返回预设数量; put_Int按索引加载预设. 使用Toupcam_get_Enum查询预设名称与索引. NA 型号相关 PresetLoad Str WO 按名称加载预设. NA 型号相关 PresetSave Str WO 以指定名称保存预设. NA 型号相关 PresetDelete Int WO 删除指定索引的预设. NA 型号相关 PresetOverwrite Int WO 以当前设置覆盖指定索引的预设. NA 型号相关 PresetRenameN Str WO 将第N个预设重命名为strValue, 如PresetRename0. NA 型号相关 PresetImport Str WO 从strValue指定的文件导入预设. NA 型号相关 PresetExport Str WO 向strValue指定的文件导出预设. NA 型号相关 ImportCfg Str WO 从strValue指定的文件加载配置. NA 型号相关 LoadCfg Str WO ImportCfg的别名, 从指定文件加载配置. NA 型号相关 ExportCfg Str WO 将当前配置导出到strValue指定的文件. NA 型号相关 DumpCfg Enum RW 0: 当相机被停止时, 不自动刷新配置到文件或EEPROM
1: 当相机被停止时, 自动刷新配置到文件或EEPROM
-1: 执行一次手动刷新配置到文件或EEPROM1 是 DUMP_CFG Factory Int WO 恢复出厂设置. 请注意恢复出厂设置可能导致分辨率改变 恒为0 否 FACTORY DeviceReset Int WO 重置相机的usb连接, 相当于模拟一次重新插拔 NA NA DEVICE_RESET ResetSensor Int WO 传感器复位 NA 是 RESET_SENSOR OpenErrorCode Int RO 打开相机的错误码 NA NA OPEN_ERRORCODE FrameGrabber:<name> Int / Str RW GenTL采集卡属性, 将<name>替换为采集卡提供的属性名. 支持的名称、类型和读写限制由采集卡定义 NA 型号相关 采集控制 (AcquisitionControl)
帧率、曝光、触发、采集模式和缓冲队列.
字符串名(strName) 取值方式 读写 说明 默认值 是否可以在相机处于运行状态设置该值
(调用Toupcam_StartXXXX之前或Toupcam_Stop之后)选项(旧接口)
(TOUPCAM_OPTION_XXXX)AcquisitionFrameRate Int RW 精确帧率: 单位0.1帧/秒, 如115表示11.5帧/秒
使用TOUPCAM_OPTION_MAX_PRECISE_FRAMERATE, TOUPCAM_OPTION_MIN_PRECISE_FRAMERATE获取范围. 如果设置的值超出范围, 将返回E_INVALIDARG最大帧率的90% 是 PRECISE_FRAMERATE MaxFramerate Int RO 获取最大精确帧率. 单位0.1帧/秒, 如115表示11.5帧/秒
最大帧率和带宽的设置/分辨率/位深度/ROI相关, 当这些设置发生改变时, 最大帧率也会发生改变.
相机处于非运行状态时返回E_UNEXPECTED, E_NOTIMPL表示不支持该功能NA NA MAX_PRECISE_FRAMERATE MinFramerate Int RO 获取最小精确帧率. 单位0.1帧/秒, 如15表示1.5帧/秒
最小帧率和带宽的设置/分辨率/位深度/ROI相关, 当这些设置发生改变时, 最小帧率也会发生改变
相机处于非运行状态时返回E_UNEXPECTED, E_NOTIMPL表示不支持该功能NA NA MIN_PRECISE_FRAMERATE Framerate Int RW 帧率限制(每秒帧数).
触发模式下帧率控制自动禁用.0
(表示不限制)否
(在相机处于运行状态时, 设置本选项, 函数返回E_UNEXPECTED)FRAMERATE FrameInterval Int RW 帧间隔(微秒) FRAMEINTERVAL Bandwidth Int RW 带宽, 范围：[1-100]%
设定带宽之后, 获取精确帧率的范围, 再设置精确帧率100 是 BANDWIDTH Speed Int RW 对于部分支持所谓精确帧率的相机, 建议使用精确帧率控制. 为了保持兼容, Speed仍然有效, 映射机制为: MaxSpeed为9(共10级), 分别对应Bandwidth从10%~100%时的最大帧率. 如设置speed为8, 等同于: 精确帧率设置为Bandwidth设置为90%时的最大帧率
对应函数: Toupcam_get/put_SpeedNA 是 ReadoutMode Enum RW 读出模式:
0: IWR (边读出边积分, Integrate While Read)
1: ITR (先积分后读出, Integrate Then Read)
探测器读出电路的工作模式可分为两种: ITR和IWR. 使用IWR读出模式, 可以大大提高帧频. 在ITR模式中, 第(n+1)帧积分在第n帧所有数据读出完成后开始, 而IWR模式中第(n+1)帧积分时, 同时读出第n帧的数据NA 是 READOUT_MODE OperationMode Enum RW TDI工作模式:
1: 面阵
2: TDI型号特定 是 OPERATIONMODE TDITriggerMode Enum RW TDI触发模式:
1: 普通
2: 双触发型号特定 是 TDITRIGGERMODE TDIStage Int RW TDI级数: 传感器扫描级数 型号特定 是 TDISTAGE RealTime Enum RW 实时模式:
0: 非实时(帧缓冲队列满时停止抓帧)
1: 实时(新帧到来时丢弃所有老帧)
2: 软实时(DDR缓冲不变更), 默认0, 一般不需要改动
对应函数: Toupcam_get/put_RealTime0 是 NoFrameTimeout Int RW 没有抓取到视频帧的超时时间. 当设定时间内没有获取到任何视频帧时, 触发事件TOUPCAM_EVENT_NOFRAMETIMEOUT
0: 禁用
正整数(>=TOUPCAM_NOFRAME_TIMEOUT_MIN) => 超时毫秒数0 是 NOFRAME_TIMEOUT DdrDepth Enum RW DDR最多可以缓存的帧数:
1: DDR最大缓存一帧
0: 自动, 视频模式下自动曝光开启时为1, 其他为全部容量
-1: DDR最多可缓存至DDR全部容量0 是 DDR_DEPTH CallbackThread Enum RW 单独的专门线程用于回调:
0: 禁用
1: 启用启用 否
(在相机处于运行状态时, 设置本选项, 函数返回E_UNEXPECTED)CALLBACK_THREAD FrontDequeLength Int RW 前端(裸数据)帧队列长度, 范围[2, 1024]
内存将在相机start的时候全部预分配, 请关注内存占用4 USB: 是
GigE: 使用gigepdrv时不支持, 其它支持
CL和CXP: 取决于采集卡FRONTEND_DEQUE_LENGTH BackDequeLength Int RW 后端(Pipeline处理后)帧队列长度(仅在拉模式下可用, Push模式下忽略), 范围[2, 1024]
内存将在相机start的时候全部预分配, 请关注内存占用3 是 BACKEND_DEQUE_LENGTH Reload Int RW 触发模式下发生帧丢失时恢复最后一帧的数据.
get返回值S_OK表示支持本功能, E_NOTIMPL表示不支持.NA 是 RELOAD HZ Enum RW 设置供电频率(防闪烁), 防闪烁功能能去除由于电源频率导致的副作用, 包括对于卷帘快门传感器的条纹和对于全局快门传感器的闪烁. 在50HZ的情况下, 曝光时间被限定为10ms的整数倍, 60HZ的情况下曝光时间被限定在(1000/120)ms的整数倍:
0: 60Hz交流
1: 50Hz交流
2: 直流
对应函数: Toupcam_get/put_HZNA 是 ExposureAuto Enum RW 设置自动曝光模式:
0: 关闭
1: 连续
2: 单次; 启用后设备调节曝光时间和模拟增益, 使所选区域的亮度接近曝光目标
对应函数: Toupcam_get/put_AutoExpoEnableNA 是 ExposureAutoOnce Int WO 执行一次自动曝光后停止
对应函数: Toupcam_put_AutoExpoEnable(mode=2)NA 是 ExposureTime Int RW 自动曝光关闭时可修改, 控制感光单元暴露于光线的持续时间, 单位为微秒, 范围由Toupcam_get_ExpTimeRange返回 NA 是 ActualExposureTime Int RO 实际曝光时间, 单位微秒; 可能不同于设定的ExposureTime. 对应Toupcam_get_RealExpoTime. NA NA TriggerMode Enum RW 0: 视频模式
1: 软件或模拟触发模式
2: 外部触发模式
3: 外部触发和软件触发都开启0 是 TRIGGER TriggerCancelMode Enum RW 触发取消模式:
0: 不输出帧
1: 输出帧0 是 TRIGGER_CANCEL_MODE ExposurePreDelay Int RW 曝光信号预延迟, 微秒 0 是 EXPOSURE_PRE_DELAY ExposurePostDelay Int RW 曝光信号后延迟, 微秒 0 是 EXPOSURE_POST_DELAY LinePreDelay Int RW 指定行预延迟, 微秒 0 是 LINE_PRE_DELAY LinePostDelay Int RW 指定行后延迟, 微秒 0 是 LINE_POST_DELAY TimedTriggerNum Int RW 定时触发: 数量 0(禁用) 是 TIMED_TRIGGER_NUM TimedTriggerSelector Int WO 选择TimedTriggerHigh和TimedTriggerLow不带序号时访问的触发项, 序号为非负整数. 0 是 TimedTriggerLow Int RW 定时触发: 64位触发时间低32位, 纳秒数(00:00:00 UTC on Thursday, 1 January 1970, see https://en.wikipedia.org/wiki/Unix_time) 0 是 TIMED_TRIGGER_LOW TimedTriggerLowN Int RW 第N项定时触发的时间低32位, 纳秒时间戳. NA 型号相关 TimedTriggerHigh Int RW 定时触发: 触发时间高32位. 必须先设置低32位, 后设置高32位 0 是 TIMED_TRIGGER_HIGH TimedTriggerHighN Int RW 第N项定时触发的时间高32位, N为非负整数. 必须先设置对应的低32位. NA 型号相关 TriggerSource Enum RW 选择用作触发源的内部信号或物理输入:
0: 光耦隔离输入
1: GPIO0
2: GPIO1
3: 计数器分频
4: PWM
5: 软件NA 是 TriggerSourceN Enum RW I/O线路N的TriggerSource属性. 不带序号时使用LineSelector指定的线路; 取值含义与TriggerSource相同. NA 型号相关 BurstCounter Int RW 突发模式下单个触发信号输出的帧数, 范围[1, 65535] NA 是 BurstCounterN Int RW I/O线路N的BurstCounter属性. 不带序号时使用LineSelector指定的线路; 取值含义与BurstCounter相同. NA 型号相关 SequencerMode Enum RW sequencer trigger: 开启/关闭 0 是 SEQUENCER_ONOFF SequencerNumber Int RW sequencer trigger: 数量, 范围[1, 255] NA 是 SEQUENCER_NUMBER SequencerSelector Int WO 选择SequencerExposureTime和SequencerGain不带序号时访问的组, 范围[1, 255]. NA 是 SequencerExposureTime Int RW sequencer trigger: 曝光时间
iOption = TOUPCAM_OPTION_SEQUENCER_EXPOTIME | index
iValue = 曝光时间值(不参考50/60HZ约束)
如设置第3组的曝光时间50ms, 则调用:
Toupcam_put_Option(h, TOUPCAM_OPTION_SEQUENCER_EXPOTIME | 3, 50000)NA 是 SEQUENCER_EXPOTIME SequencerExposureTimeN Int RW 第N组曝光时间, 单位微秒; N=0读取当前曝光时间, 其他组为[1, 255]. NA 型号相关 SequencerGain Int RW sequencer trigger: 增益
iOption = TOUPCAM_OPTION_SEQUENCER_EXPOGAIN | index
iValue = 增益值NA 是 SEQUENCER_EXPOGAIN SequencerGainN Int RW 第N组模拟增益, 100表示100%; 序号范围由Sequencer配置确定. NA 型号相关 SoftwareTrigger Int WO 生成内部触发信号, TriggerSource 需设置为 Software 或者触发模式为软触发
对应函数: Toupcam_TriggerNA 是 StrobeDelayMode Enum RW 触发模式下选择延迟方式:
0: 延迟曝光时间且输出不变
1: 仅延迟输出NA 是 StrobeDelayModeN Enum RW I/O线路N的StrobeDelayMode属性. 不带序号时使用LineSelector指定的线路; 取值含义与StrobeDelayMode相同. NA 型号相关 StrobeDelayTime Int RW 触发模式下控制所选延迟方式的延时时间(单位微秒), 范围[0, 5000000] NA 是 StrobeDelayTimeN Int RW I/O线路N的StrobeDelayTime属性. 不带序号时使用LineSelector指定的线路; 取值含义与StrobeDelayTime相同. NA 型号相关 Pause Enum RW 暂停或者继续视频流:
0: 继续
1: 暂停
对应函数: Toupcam_Pause0 是 FlushMode Enum RW 清空相机内部帧缓存的方式:
1: 硬flush(丢弃相机DDR缓存的帧)
2: 软flush(丢弃SDK内部缓存的帧)
3: 硬+软3 是 Flush Enum WO 1: 硬flush, 丢弃相机内部DDR缓存的帧(如果有的话)
2: 软flush, 丢弃toupcam.dll内部缓存的帧(如果有的话)
3: 硬+软
Toupcam_Flush是'硬+软'
成功时返回被软flush掉的帧数目, 失败时返回HRESULTNA NA FLUSH 模拟控制 (AnalogControl)
增益、暗电平、传感器模拟设置和工作模式.
字符串名(strName) 取值方式 读写 说明 默认值 是否可以在相机处于运行状态设置该值
(调用Toupcam_StartXXXX之前或Toupcam_Stop之后)选项(旧接口)
(TOUPCAM_OPTION_XXXX)Gain Int RW 控制施加到视频信号上的放大倍数, 使用百分比表示增益, 例如200表示200%增益
对应函数: Toupcam_get/put_ExpoAGain100 是 ActualGain Int RO 实际模拟增益, 100表示100%. 对应Toupcam_get_RealExpoGain. NA NA DigitalGain Int RW 数字增益, 具体单位与范围由相机型号定义. DIGITAL_GAIN ConversionGain
CGEnum RW 转换增益(Conversion Gain):
0: LCG
1: HCG
2: HDR(对于TOUPCAM_FLAG_CGHDR相机)
2: MCG(对于TOUPCAM_FLAG_GHOPTO相机)型号特定 是 CG GainMode Enum RW 设置相机的增益模式:
0: 高灵敏度
1: 高满阱
2: 平衡
3: HDRNA 否 BlackLevel Int RW 暗电平是指图像传感器在无光(完全黑暗)条件下, 输出的基准信号基础值.
在数字成像中, 系统会为信号人为施加一个固定的电压偏置(Offset), 确保暗部信号大于0, 从而防止在进行A/D转换时丢失暗部微弱的细节.
(a)防止截断(Clipping): 传感器电路的本底噪声有时会出现负值. 如果没有偏置, 负值会被强制归零, 导致暗部细节丢失.
(b)保留线性度: 垫高暗电平可以确保传感器在整个动态范围内的信号输出保持线性一致
对于不支持暗电平的相机返回E_NOTIMPL.0 是 BLACKLEVEL BlacklevelAutoAdjust Enum RW 黑电平自动调整功能设置:
0: 关闭
1: 开启
该选项通过OB(Optical Black)电平检测机制控制黑电平自动调整功能的开关. 在长曝光等场景下, 因暗电流泄漏等因素可能导致OB电平发生偏移. 此功能即为解决该类异常偏移问题而设置的其中一种解决方案.型号特定 是 BLACKLEVEL_AUTOADJUST ZeroOffset Enum RW 传感器输出偏移归零:
0: 关闭
1: 开启; 默认: 00 ZERO_OFFSET CDS Int RW 相关双采样: 0~100
参阅这里0 是 CDS CdsGain Enum RW 相关双采样增益挡位 型号特定 型号相关 LowNoise Enum RW 低噪声模式(更高的信噪比, 更低的帧率):
0: 禁用
1: 启用型号特定 是 LOW_NOISE LowPower Int RW 低功耗模式: 0: 禁用, 1: 启用, 大于1: 当曝光时间大于设定值时启用 NA 是 LowPowerConsumption Int RW 低功耗模式:
0 : 禁用
1 : 启用
> 1 : 曝光时间大于设定值时启用型号特定 是 LOW_POWERCONSUMPTION LowPowerExpoTime Int RW 低功耗模式: 曝光时间大于设定值时启用 型号特定 是 LOW_POWER_EXPOTIME GlobalReset Enum RW global reset mode 0 是 GLOBAL_RESET_MODE Lane Int RW 相机输出数据的通道数 型号特定 是 LANE AntiBlooming Int RW Blooming(溢出效应)发生在像素中的电荷量超过其饱和容量时, 此时多余的电荷会开始流入相邻像素.
一些传感器内部集成了专门的结构来抑制这种现象, 称为抗溢出结构. 抗溢出结构会在电荷即将从像素中溢出之前, 将多余的电荷导出(泄放), 从而防止Blooming的发生.
然而, 抗溢出结构也存在一些代价: 会降低传感器的有效量子效率(Quantum Efficiency, QE); 可能引入传感器响应的非线性(Non-Linearity)
因此, 对于需要极低照度成像或高精度定量测量等应用场景, 通常不推荐使用带抗溢出结构的传感器.型号特定 是 ANTI_BLOOMING AntiBloomingMax Int RO 高光溢出保护（anti-blooming) NA NA ANTI_BLOOMING_MAX OverClock Int RW 超频挡位 0 是 OVERCLOCK OverclockMax Int RO 获取超频最大挡位 NA NA OVERCLOCK_MAX AntiShutter Enum RW anti shutter effect:
1: 启用
0: 禁用禁用(0) 是 ANTI_SHUTTER_EFFECT HighFullwell Enum RW 高满阱模式:
0: 禁用
1: 启用型号特定 是 HIGH_FULLWELL Mode Enum RW 较高分辨率的相机支持2种采样模式, 一种是Bin模式(邻域平均), 一种是Skip模式(抽样提取). 相比较而言, 前者图像效果较好, 但是帧速率降低; 后者帧速率较高, 但是图像效果较差
对应函数: Toupcam_get/put_ModeNA 是 VoltageBias Int RW 电压偏置 型号特定 是 VOLTAGEBIAS VoltageBiasRange Int RO 电压偏置范围:
最小值 (低16位)
最大值 (高16位)NA NA VOLTAGEBIAS_RANGE 图像处理 (ImageProcessingControl)
白平衡、黑平衡、颜色、色调、去噪、锐化和图像变换.
字符串名(strName) 取值方式 读写 说明 默认值 是否可以在相机处于运行状态设置该值
(调用Toupcam_StartXXXX之前或Toupcam_Stop之后)选项(旧接口)
(TOUPCAM_OPTION_XXXX)ISP Enum RW 启用/禁用硬件ISP:
0: 自动 (RAW模式时禁用, 其它启用)
1: 启用
-1: 禁用0(自动) 否
(在相机处于运行状态时, 设置本选项, 函数返回E_UNEXPECTED)ISP MultiThread Enum RW 多线程图像处理 1 否
(在相机处于运行状态时, 设置本选项, 函数返回E_UNEXPECTED)MULTITHREAD ThreadPriority Enum RW 设置内部线程的优先级.
Win:0: THREAD_PRIORITY_NORMAL;Linux & macOS: 和Win类似
1: THREAD_PRIORITY_ABOVE_NORMAL;
2: THREAD_PRIORITY_HIGHEST;
3: THREAD_PRIORITY_TIME_CRITICAL;
请参阅: SetThreadPriority1 是 THREAD_PRIORITY WhiteBalanceOnce Int WO 在色温/色调模式下执行一次自动白平衡
对应函数: Toupcam_AwbOnceNA 是 WhiteBalanceTemperature Int RW 设置白平衡色温, 范围[2000, 15000], 默认值6503
对应函数: Toupcam_get/put_TempTint6503 是 Temp Int RW 白平衡色温, 范围[1000, 25000], 默认6503. 仅适用于Temp/Tint白平衡模式. 6503 是 WhiteBalanceTint Int RW 设置白平衡色调, 范围[200, 2500], 默认值1000
对应函数: Toupcam_get/put_TempTint1000 是 Tint Int RW 白平衡色调, 范围[100, 2500], 默认1000. 仅适用于Temp/Tint白平衡模式. 1000 是 WhiteBalanceRed Int RW 白平衡红通道增益, 仅RGB Gain白平衡模式可用; 范围和默认值通过同名Min/Max/Def查询. 0 是 WhiteBalanceGreen Int RW 白平衡绿通道增益, 仅RGB Gain白平衡模式可用; 范围和默认值通过同名Min/Max/Def查询. 0 是 WhiteBalanceBlue Int RW 白平衡蓝通道增益, 仅RGB Gain白平衡模式可用; 范围和默认值通过同名Min/Max/Def查询. 0 是 WbGain Enum RW 0: 关闭内部白平衡增益
1: 开启内部白平衡增益1 是 WBGAIN AwbContinuous Int RW 自动白平衡: 连续模式 0: 禁用
n>0: 每隔n毫秒
n<0: 每隔-n帧0(禁用) 是 AWB_CONTINUOUS AWBWidth Int RW 设置自动白平衡区域的宽度, 单位为像素, 最小宽度为4像素 WidthMax / 5 是 AWBHeight Int RW 设置自动白平衡区域的高度, 单位为像素, 最小高度为4像素 HeightMax / 5 是 AWBOffsetX Int RW 设置自动白平衡区域相对于原始分辨率的水平偏移, 单位为像素 WidthMax × 2 / 5 是 AWBOffsetY Int RW 设置自动白平衡区域相对于原始分辨率的垂直偏移, 单位为像素 HeightMax × 2 / 5 是 BlackBalanceOnce Int WO 执行一次自动黑平衡
对应函数: Toupcam_AbbOnceNA 是 BlackBalanceR Int RW 设置红色通道的黑平衡减除值, 范围[0, 2^位深-1], 如8位为0~255, 16位为0~65535, 默认值0
对应函数: Toupcam_get/put_BlackBalance0 是 BlackBalanceG Int RW 设置绿色通道的黑平衡减除值, 范围[0, 2^位深-1], 如8位为0~255, 16位为0~65535, 默认值0
对应函数: Toupcam_get/put_BlackBalance0 是 BlackBalanceB Int RW 设置蓝色通道的黑平衡减除值, 范围[0, 2^位深-1], 如8位为0~255, 16位为0~65535, 默认值0
对应函数: Toupcam_get/put_BlackBalance0 是 ABBWidth Int RW 设置自动黑平衡区域的宽度, 单位为像素, 最小宽度为4像素 WidthMax / 5 是 ABBHeight Int RW 设置自动黑平衡区域的高度, 单位为像素, 最小高度为4像素 HeightMax / 5 是 ABBOffsetX Int RW 设置自动黑平衡区域相对于原始分辨率的水平偏移, 单位为像素 WidthMax × 2 / 5 是 ABBOffsetY Int RW 设置自动黑平衡区域相对于原始分辨率的垂直偏移, 单位为像素 HeightMax × 2 / 5 是 LevelRangeAuto Int WO 根据直方图自动调整左右限并拉伸图像
对应函数: Toupcam_LevelRangeAutoNA 是 LevelRangeLowR Int RW 设置软件图像拉伸使用的红色通道直方图左限, 范围[0, 255], 不能大于红色右限 0 是 LevelRangeHighR Int RW 设置软件图像拉伸使用的红色通道直方图右限, 范围[0, 255], 不能小于红色左限 255 是 LevelRangeLowG Int RW 设置软件图像拉伸使用的绿色通道直方图左限, 范围[0, 255], 不能大于绿色右限 0 是 LevelRangeHighG Int RW 设置软件图像拉伸使用的绿色通道直方图右限, 范围[0, 255], 不能小于绿色左限 255 是 LevelRangeLowB Int RW 设置软件图像拉伸使用的蓝色通道直方图左限, 范围[0, 255], 不能大于蓝色右限 0 是 LevelRangeHighB Int RW 设置软件图像拉伸使用的蓝色通道直方图右限, 范围[0, 255], 不能小于蓝色左限 255 是 LevelRangeLowGray Int RW 设置软件图像拉伸使用的灰度直方图左限, 范围[0, 255], 不能大于灰度右限 0 是 LevelRangeHighGray Int RW 设置软件图像拉伸使用的灰度直方图右限, 范围[0, 255], 不能小于灰度左限 255 是 Hue Int RW 图像信号中用于表征色调与饱和度属性的色彩信息分量, 范围[-180, 180], 默认值0
对应函数: Toupcam_get/put_Hue0 是 Saturation Int RW 色彩的纯净度或鲜艳程度, 范围[0, 255], 默认值128
对应函数: Toupcam_get/put_Saturation128 是 Brightness Int RW 指图像信号中表征明暗等级的光度分量, 范围[-255, 255], 默认值0
对应函数: Toupcam_get/put_Brightness0 是 Contrast Int RW 指图像中最亮与最暗区域之间的亮度差异程度, 范围[-255, 255], 默认值0
对应函数: Toupcam_get/put_Contrast0 是 Gamma Int RW 控制像素强度的伽马校正, 通常用于补偿显示系统的非线性响应, 以百分比表示, 范围[20, 180], 默认值100
对应函数: Toupcam_get/put_Gamma100 是 Chrome Enum RW 色彩模式:
0: 多色模式
1: 单色模式
对应函数: Toupcam_get/put_ChromeNA 是 ToneMapping Enum RW 色调映射(tone mapping):
0: 关闭
1: 开启多项式(polynomial)拟合
2: 开启对数(logarithmic)拟合
启用色调映射会显著破坏线性度2 是 CURVE Linear Enum RW 内部linear tone mapping:
0: 关闭
1: 开启1 是 LINEAR ColorMatix Enum RW 0: 关闭内部颜色矩阵
1: 开启内部颜色矩阵1 是 COLORMATIX Demosaic Enum RW 视频和静态图像的Demosaic算法：(请参阅https://en.wikipedia.org/wiki/Demosaicing)
0: BILINEAR
1: VNG(Variable Number of Gradients, 可变数量梯度)
2: PPG(Patterned Pixel Grouping)
3: AHD(Adaptive Homogeneity Directed, 自适应同质导向)
4: EA(Edge Aware, 边缘感知)
就CPU使用率而言, EA是最低的, BILINEAR次之, 其它的都更高.
对于黑白相机始终返回E_NOTIMPL.0 是 DEMOSAIC DemosaicVideo Enum RW 视频的Demosaic算法 0 是 DEMOSAIC_VIDEO DemosaicStill Enum RW 静态图像的Demosaic算法 0 是 DEMOSAIC_STILL HdrKB Int RW HDR合成
K(高16位): [1, 25500]
B(低16位): [0, 65535]
0xffffffff: 设置为默认值型号特定 是 HDR_KB HdrK Int RO HDR合成系数K, 读取HdrKB的高16位, 范围[1, 25500]. 设置使用HdrKB组合编码. NA NA HdrB Int RO HDR合成偏移B, 读取HdrKB的低16位, 范围[0, 65535]. 设置使用HdrKB组合编码. NA NA HdrThreshold Int RW HDR合成
阈值: [1, 4094]
0xffffffff: 设置为默认值型号特定 是 HDR_THRESHOLD Rotate Enum RW 顺时针旋转: 0°, 90°, 180°, 270° 0 是 ROTATE UpsideDown Enum RW 倒置:
1: yes
0: no
请和Toupcam_put_VFlip区别, 后者需要耗费CPU对每帧数据执行数据搬动的工作Win: 1, Windows下默认倒置
Linux/MacOS/Android: 0, 默认不倒置否
(在相机处于运行状态时, 设置本选项, 函数返回E_UNEXPECTED)UPSIDE_DOWN VFlip Enum RW 图像垂直翻转:
0: 不翻转
1: 翻转
对应函数: Toupcam_get/put_VFlipNA 是 ReverseY Enum RW 垂直翻转:
0: 关闭
1: 开启; 对应VFlip.0 是 HFlip Enum RW 图像水平翻转:
0: 不翻转
1: 翻转
对应函数: Toupcam_get/put_HFlipNA 是 ReverseX Enum RW 水平翻转:
0: 关闭
1: 开启; 对应HFlip.0 是 Negative Enum RW 将当前视频按位取反显示:
0: 关闭
1: 开启
对应函数: Toupcam_get/put_NegativeNA 是 UsmSelect Enum RW 锐化处理方式选择:
0: 自动选择
1: 相机硬件处理
2: 软件处理; 可用方式取决于相机支持.型号特定 型号相关 SharpenStrength Int RW 锐化强度, 范围[0, 500], 0: 禁用. 按strName读写时直接使用强度值; TOUPCAM_OPTION_SHARPENING使用下述组合编码. 型号特定 是 SharpenRadius Int RW 锐化半径, 范围[1, 10]. 按strName读写时直接使用半径值; TOUPCAM_OPTION_SHARPENING使用下述组合编码. 2 是 SharpenThreshold Int RW 锐化阈值, 范围[0, 255]. 按strName读写时直接使用阈值; TOUPCAM_OPTION_SHARPENING使用下述组合编码. 0 是 Int RW 锐化, (threshold << 24) | (radius << 16) | strength) 强度(strength): [0, 500], default: 0 (disable)
半径(radius): [1, 10]
阈值(threshold): [0, 255]强度: 型号特定
半径: 2
阈值: 0是 SHARPENING Denoise Int RW 去噪
强度范围[0, 100], 0: 禁用型号特定 是 DENOISE DynamicDefectDead Int RW 动态坏点校正的死点系数t1, 范围[0, 100], 表示[0.0, 1.0]. 按strName直接读写t1; 对应TOUPCAM_OPTION_DYNAMIC_DEFECT的高16位. 参阅TOUPCAM_DYNAMIC_DEFECT_T1_(MIN/MAX/DEF). 0(不启用) 是 DynamicDefectHot Int RW 动态坏点校正的噪点系数t2, 范围[0, 100], 表示[0.0, 1.0]. 按strName直接读写t2; 对应TOUPCAM_OPTION_DYNAMIC_DEFECT的低16位. 参阅TOUPCAM_DYNAMIC_DEFECT_T2_(MIN/MAX/DEF). 0(不启用) 是 Int RW 动态坏点校正:
死点系数, t1(高16位): [0, 100], 表示[0.0, 1.0]
噪点系数, t2: (低16位): [0, 100], 表示[0.0, 1.0]
见:
TOUPCAM_DYNAMIC_DEFECT_T1_(MIN/MAX/DEF), TOUPCAM_DYNAMIC_DEFECT_T2_(MIN/MAX/DEF)不启用
(t1=0, t2=0)是 DYNAMIC_DEFECT PseudoColorEnable Enum RW 伪彩色:
-1: Custom(自定义): 使用起始颜色和结束颜色产生颜色映射表格
0: Disable(禁用)
1: Spot
2: Spring
3: Summer
4: Autumn
5: Winter
6: Bone
7: Jet
8: Rainbow
9: Deepgreen
10: Ocean
11: Cool
12: HSV
13: Pink
14: Hot
15: Parula
16: Magma
17: Inferno
18: Plasma
19: Viridis
20: Cividis
21: Twilight
22: TwilightShifted
23: Turbo
24: Red
25: Green
26: Blue
27: Spectrum0 是 PSEUDO_COLOR_ENABLE PseudoColorStart Int RW 伪彩色: 起始颜色, BGR格式 NA 是 PSEUDO_COLOR_START PseudoColorEnd Int RW 伪彩色: 结束颜色, BGR格式 NA 是 PSEUDO_COLOR_END Histogram Enum RW 0: 仅一次
1: 连续模式是 HISTOGRAM 校正控制 (CorrectionControl)
平场、暗场、固定模式噪声和坏点校正.
字符串名(strName) 取值方式 读写 说明 默认值 是否可以在相机处于运行状态设置该值
(调用Toupcam_StartXXXX之前或Toupcam_Stop之后)选项(旧接口)
(TOUPCAM_OPTION_XXXX)DFCStatus Int RO 暗场校正状态:
(val & 0xff): 0: 禁用, 1: 启用, 2: 已初始化
((val & 0xff00) >> 8): 序号
((val & 0xff0000) >> 16): 平均数0 NA Int RW 暗场校正(Dark Field Correction):
设置(set):0: 禁用获取(get):
1: 启用
-1: 重置
(0xff000000 | n): 设置平均数为n, [1, 255](val & 0xff): 0: 禁用, 1: 启用, 2: 已初始化
((val & 0xff00) >> 8): 序号
((val & 0xff0000) >> 16): 平均数0 是 DFC DFCEnable Enum RW 暗场校正开关:
0: 禁用
1: 启用; 设置-1可重置校正数据. 读取时返回0或1: 是否已启用.0 是 DFCNumber Int RW 暗场校正时需要拍摄的数量 5 是 DFCInit Int WO 暗场校正初始化: 设置参与平均的拍摄数量并执行一次校正. 可通过Toupcam_get_Int查询DFCInitMin / DFCInitMax / DFCInitDef获取数量范围和默认值; GenTL相机使用已配置的拍摄数量. 5 是 DFCImport Str WO 导入暗场校正的数据
对应函数: Toupcam_DfcImportNA 是 DFCExport Str WO 导出暗场校正的数据
对应函数: Toupcam_DfcExportNA 是 DFCFile Str WO GenTL相机的暗场校正数据文件路径. NA 型号相关 FFCStatus Int RO 平场校正状态:
(val & 0xff): 0: 禁用, 1: 启用, 2: 已初始化
((val & 0xff00) >> 8): 序号
((val & 0xff0000) >> 16): 平均数0 NA Int RW 平场校正(Flat Field Correction):
设置(set):0: 禁用获取(get):
1: 启用
-1: 重置
(0xff000000 | n): 设置平均数为n, [1, 255](val & 0xff): 0: 禁用, 1: 启用, 2: 已初始化
((val & 0xff00) >> 8): 序号
((val & 0xff0000) >> 16): 平均数0 是 FFC FFCEnable Enum RW 平场校正开关:
0: 禁用
1: 启用; 设置-1可重置校正数据. 读取时返回0或1: 是否已启用.0 是 FFCNumber Int RW 平场校正时需要拍摄的数量 5 是 FFCInit Int WO 平场校正初始化: 设置参与平均的拍摄数量并执行一次校正. 可通过Toupcam_get_Int查询FFCInitMin / FFCInitMax / FFCInitDef获取数量范围和默认值; GenTL相机使用已配置的拍摄数量. 5 是 FFCImport Str WO 导入平场校正的数据
对应函数: Toupcam_FfcImportNA 是 FFCExport Str WO 导出平场校正的数据
对应函数: Toupcam_FfcExportNA 是 FFCFile Str WO GenTL相机的平场校正数据文件路径. NA 型号相关 FPNCStatus Int RO 固定模式噪声校正状态:
(val & 0xff): 0: 禁用, 1: 启用, 2: 已初始化
((val & 0xff00) >> 8): 序号
((val & 0xff0000) >> 16): 平均数0 NA Int RW 固定模式噪声校正(Fixed Pattern Noise Correction):
设置(set):0: 禁用获取(get):
1: 启用
-1: 重置
(0xff000000 | n): 设置平均数为n, [1, 255](val & 0xff): 0: 禁用, 1: 启用, 2: 已初始化
((val & 0xff00) >> 8): 序号
((val & 0xff0000) >> 16): 平均数0 是 FPNC FPNCEnable Enum RW 固定模式噪声校正开关:
0: 禁用
1: 启用; 设置-1可重置校正数据. 读取时返回0或1: 是否已启用.0 是 FPNCNumber Int RW 固定模式噪声校正时需要拍摄的数量 5 是 FPNCInit Int WO 固定模式噪声校正初始化: 设置参与平均的拍摄数量并执行一次校正. 可通过Toupcam_get_Int查询FPNCInitMin / FPNCInitMax / FPNCInitDef获取数量范围和默认值; GenTL相机使用已配置的拍摄数量. 5 是 FPNCImport Str WO 导入固定模式噪声校正的数据
对应函数: Toupcam_FpncImportNA 是 FPNCExport Str WO 导出固定模式噪声校正的数据
对应函数: Toupcam_FpncExportNA 是 DefectPixel Enum RW 坏点校正
0: 禁用
1: 启用启用(1) 是 DEFECT_PIXEL FPNCFile Str WO GenTL相机的固定模式噪声校正数据文件路径. NA 型号相关 FpncHw Int WO 执行相机硬件固定模式噪声校正, 参数由相机定义; 不支持时返回E_NOTIMPL. NA 型号相关 DefectHw Enum RW 硬件坏点校正:
0: 禁用
1: 启用. 仅支持硬件坏点校正的相机可用.型号特定 型号相关 I/O控制 (IOControl)
输入输出线路、计数器、PWM、串口和曝光信号.
字符串名(strName) 取值方式 读写 说明 默认值 是否可以在相机处于运行状态设置该值
(调用Toupcam_StartXXXX之前或Toupcam_Stop之后)选项(旧接口)
(TOUPCAM_OPTION_XXXX)LineSelector Enum RW 选择要配置的物理I/O线路:
0: 光耦隔离输入
1: 光耦隔离输出
2: GPIO0
3: GPIO1; 其他线路控制属性作用于所选线路NA 是 SupportedMode Enum RO I/O支持的模式:
1: 输入
2: 输出
3: 输入和输出NA NA SupportedModeN Enum RO I/O线路N的SupportedMode属性. 不带序号时使用LineSelector指定的线路; 取值含义与SupportedMode相同. NA NA LineMode Enum RW 控制所选物理线路用作输入还是输出, 仅GPIO0和GPIO1支持模式选择:
0: 输入
1: 输出NA 是 LineModeN Enum RW I/O线路N的LineMode属性. 不带序号时使用LineSelector指定的线路; 取值含义与LineMode相同. NA 型号相关 LineFormat Enum RO 所选物理输入或输出线路的电气格式:
0: 未连接
1: 三态
2: TTL电平
3: LVDS电平
4: RS422电平
5: 光耦隔离NA NA LineFormatN Enum RW I/O线路N的LineFormat属性. 不带序号时使用LineSelector指定的线路; 取值含义与LineFormat相同. NA 型号相关 LineInverter Enum RW 控制所选输入或输出线路信号的反相:
0: 不反相
1: 反相, 仅输出线路支持NA 是 LineInverterN Enum RW I/O线路N的LineInverter属性. 不带序号时使用LineSelector指定的线路; 取值含义与LineInverter相同. NA 型号相关 LineSource Enum RW 选择由所选输出线路驱动的内部采集或I/O信号:
0: 帧触发等待
1: 曝光有效
2: 闪光灯
3: 用户输出
4: 计数器有效
5: 定时器有效; LineMode 必须设置为 OutputNA 是 LineSourceN Enum RW I/O线路N的LineSource属性. 不带序号时使用LineSelector指定的线路; 取值含义与LineSource相同. NA 型号相关 OutputPause Enum WO 输出暂停:
0: 继续输出
1: 暂停输出NA 是 OutputPauseN Enum WO I/O线路N的OutputPause属性. 不带序号时使用LineSelector指定的线路; 取值含义与OutputPause相同. NA 型号相关 InputActivation Enum RW 设置输入信号的触发沿:
0: 上升沿
1: 下降沿
2: 高电平
3: 低电平NA 是 InputActivationN Enum RW I/O线路N的InputActivation属性. 不带序号时使用LineSelector指定的线路; 取值含义与InputActivation相同. NA 型号相关 DebouncerTime Int RW 触发信号的消抖时间(单位微秒), 用于滤除触点抖动干扰, 范围[0, 20000] NA 是 DebouncerTimeN Int RW I/O线路N的DebouncerTime属性. 不带序号时使用LineSelector指定的线路; 取值含义与DebouncerTime相同. NA 型号相关 InputState Enum RO 线路的输入状态:
0: 低电平
1: 高电平NA NA InputStateN Enum RO I/O线路N的InputState属性. 不带序号时使用LineSelector指定的线路; 取值含义与InputState相同. NA NA TriggerDelay Int RW 指定接收到触发信号后、激活触发前应用的延迟时间, 单位为微秒, 范围[0, 5000000] NA 是 TriggerDelayN Int RW I/O线路N的TriggerDelay属性. 不带序号时使用LineSelector指定的线路; 取值含义与TriggerDelay相同. NA 型号相关 CounterSource Enum RW 计数器触发源:
0: 光耦隔离输入
1: GPIO0
2: GPIO1NA 是 CounterSourceN Enum RW I/O线路N的CounterSource属性. 不带序号时使用LineSelector指定的线路; 取值含义与CounterSource相同. NA 型号相关 CounterValue Int RW 计数器分频值, 用于对外部输入触发信号进行分频, 范围[1, 65535] NA 是 CounterValueN Int RW I/O线路N的CounterValue属性. 不带序号时使用LineSelector指定的线路; 取值含义与CounterValue相同. NA 型号相关 OutputCounterValue Int RW 输出计数器数值, 范围[0, 65535]. 不带序号时使用LineSelector选择的线路, 也可使用OutputCounterValueN指定线路N. NA 型号相关 OutputCounterValueN Int RW I/O线路N的OutputCounterValue属性. 不带序号时使用LineSelector指定的线路; 取值含义与OutputCounterValue相同. NA 型号相关 CounterReset Int WO 对所选计数器执行软件复位并启动计数, 除非计数器触发处于活动状态, 否则复位后立即开始计数 NA 是 CounterResetN Int WO I/O线路N的CounterReset属性. 不带序号时使用LineSelector指定的线路; 取值含义与CounterReset相同. NA 型号相关 PWMSource Enum RW PWM(脉冲模式)触发源:
0: 光耦隔离输入
1: GPIO0
2: GPIO1NA 是 PWMSourceN Enum RW I/O线路N的PWMSource属性. 不带序号时使用LineSelector指定的线路; 取值含义与PWMSource相同. NA 型号相关 PWMFreq Int RW PWM脉冲频率, 范围[0, 0xFFFFFFFF] NA 是 PWMFreqN Int RW I/O线路N的PWMFreq属性. 不带序号时使用LineSelector指定的线路; 取值含义与PWMFreq相同. NA 型号相关 PWMDutyRatio Int RW PWM占空比(高电平时间占整个周期的百分比), 范围[0, 100], 默认50 50 是 PWMDutyRatioN Int RW I/O线路N的PWMDutyRatio属性. 不带序号时使用LineSelector指定的线路; 取值含义与PWMDutyRatio相同. NA 型号相关 StrobeDuration Int RW 闪光灯脉冲宽度(单位微秒), 决定闪光灯信号高电平的持续时间, 范围[0, 5000000] NA 是 StrobeDurationN Int RW I/O线路N的StrobeDuration属性. 不带序号时使用LineSelector指定的线路; 取值含义与StrobeDuration相同. NA 型号相关 UserOutputValue Int RW 以位域方式设置全部用户输出寄存器位: bit0控制光耦隔离输出, bit1控制GPIO0, bit2控制GPIO1 NA 是 UserOutputValueN Int RW I/O线路N的UserOutputValue属性. 不带序号时使用LineSelector指定的线路; 取值含义与UserOutputValue相同. NA 型号相关 UserPulseHigh Int RW 用户脉冲的高电平时间(单位微秒), 范围[0, 0xFFFFFFFF] NA 是 UserPulseHighN Int RW I/O线路N的UserPulseHigh属性. 不带序号时使用LineSelector指定的线路; 取值含义与UserPulseHigh相同. NA 型号相关 UserPulseLow Int RW 用户脉冲的低电平时间(单位微秒), 范围[0, 0xFFFFFFFF] NA 是 UserPulseLowN Int RW I/O线路N的UserPulseLow属性. 不带序号时使用LineSelector指定的线路; 取值含义与UserPulseLow相同. NA 型号相关 UserPulseNumber Int RW 用户脉冲数量, 范围[0, 0xFFFFFFFF], 默认0 0 是 UserPulseNumberN Int RW I/O线路N的UserPulseNumber属性. 不带序号时使用LineSelector指定的线路; 取值含义与UserPulseNumber相同. NA 型号相关 UARTEnable Enum RW 串口使能:
0: 关闭
1: 开启0 是 UARTEnableN Enum RW I/O线路N的UARTEnable属性. 不带序号时使用LineSelector指定的线路; 取值含义与UARTEnable相同. NA 型号相关 UARTBaudrate Enum RW 串口波特率:
0: 9600
1: 19200
2: 38400
3: 57600
4: 115200NA 是 UARTBaudrateN Enum RW I/O线路N的UARTBaudrate属性. 不带序号时使用LineSelector指定的线路; 取值含义与UARTBaudrate相同. NA 型号相关 UARTLineMode Enum RW 串口线缆模式(配置GPIO0/GPIO1为TX或RX):
0: TX(GPIO_0)/RX(GPIO_1)
1: TX(GPIO_1)/RX(GPIO_0)NA 是 UARTLineModeN Enum RW I/O线路N的UARTLineMode属性. 不带序号时使用LineSelector指定的线路; 取值含义与UARTLineMode相同. NA 型号相关 ExpoActiveMode Enum RW 曝光有效信号的模式:
0: 指定行
1: 共同曝光时间NA 是 ExpoActiveModeN Enum RW I/O线路N的ExpoActiveMode属性. 不带序号时使用LineSelector指定的线路; 取值含义与ExpoActiveMode相同. NA 型号相关 ExpoEvtActiveMode Enum RW 曝光事件有效信号的模式:
0: 指定行
1: 共同曝光时间NA 是 ExpoEvtActiveModeN Enum RW I/O线路N的ExpoEvtActiveMode属性. 不带序号时使用LineSelector指定的线路; 取值含义与ExpoEvtActiveMode相同. NA 型号相关 ExpoStartLine Int RW 曝光有效信号模式选指定行时使能, 配置曝光有效信号的开始行, 范围[0, 16384], 默认0 0 是 ExpoStartLineN Int RW I/O线路N的ExpoStartLine属性. 不带序号时使用LineSelector指定的线路; 取值含义与ExpoStartLine相同. NA 型号相关 ExpoEndLine Int RW 曝光有效信号模式选指定行时使能, 配置曝光有效信号的结束行, 范围[0, 16384], 默认0, 不得小于开始行 0 是 ExpoEndLineN Int RW I/O线路N的ExpoEndLine属性. 不带序号时使用LineSelector指定的线路; 取值含义与ExpoEndLine相同. NA 型号相关 ExternalTriggerNumber Int RO 原始外部触发信号的计数结果 NA NA ExternalTriggerNumberN Int RO I/O线路N的ExternalTriggerNumber属性. 不带序号时使用LineSelector指定的线路; 取值含义与ExternalTriggerNumber相同. NA NA DebouncerTriggerNumber Int RO 经消抖处理后的外部触发信号计数结果 NA NA DebouncerTriggerNumberN Int RO I/O线路N的DebouncerTriggerNumber属性. 不带序号时使用LineSelector指定的线路; 取值含义与DebouncerTriggerNumber相同. NA NA EffectiveTriggerNumber Int RO 被判定为有效的外部触发信号计数结果 NA NA EffectiveTriggerNumberN Int RO I/O线路N的EffectiveTriggerNumber属性. 不带序号时使用LineSelector指定的线路; 取值含义与EffectiveTriggerNumber相同. NA NA 自动曝光控制 (AutoExposureControl)
自动曝光计算区域、目标、上下限、策略和收敛状态.
字符串名(strName) 取值方式 读写 说明 默认值 是否可以在相机处于运行状态设置该值
(调用Toupcam_StartXXXX之前或Toupcam_Stop之后)选项(旧接口)
(TOUPCAM_OPTION_XXXX)AEWidth Int RW 设置自动曝光计算亮度时所使用的感兴趣区域(ROI)的宽度 WidthMax / 5 是 AEHeight Int RW 设置自动曝光计算亮度时所使用的感兴趣区域(ROI)的高度 HeightMax / 5 是 AEOffsetX Int RW 设置自动曝光计算亮度时所使用的感兴趣区域(ROI)相对于图像左侧的X轴偏移量 WidthMax × 2 / 5 是 AEOffsetY Int RW 设置自动曝光计算亮度时所使用的感兴趣区域(ROI)相对于图像顶部的Y轴偏移量 HeightMax × 2 / 5 是 AETarget Int RW 如果启用自动曝光, 软件将自动设置曝光时间和模拟增益使得目标矩形的平均亮度尽量接近曝光目标
对应函数: Toupcam_get/put_AutoExpoTarget120 是 AEPolicy Enum RW 自动曝光策略:
0: 仅曝光
1: 曝光优先
2: 仅模拟增益
3: 模拟增益优先1 是 AUTOEXP_POLICY AETimeMax Int RW 设置自动曝光时允许使用的最大曝光时间 NA 是 AETimeMin Int RW 设置自动曝光时允许使用的最小曝光时间 NA 是 AEGainMax Int RW 设置自动曝光时允许使用的最大增益 NA 是 AEGainMin Int RW 设置自动曝光时允许使用的最小增益 NA 是 AEThreshold Int RW 自动曝光阈值,范围: [2~15] 5 是 AUTOEXP_THRESHOLD AEThldTrigger Int RW 指自动曝光已经收敛后, 允许当前亮度与目标亮度之间存在而不触发参数重新调节的最大偏差容限边界值, 范围[2, 64], 默认5 5 是 AUTOEXP_THLD_TRIGGER AEPeak Int RW 自动曝光亮度统计值峰值模式: 计算感兴趣区域中指定百分比最亮像素的平均亮度. 当背景较暗且目标在平均模式下曝光过度时启用本选项, 启用本选项时, 由于更多的CPU消耗, 帧速率可能会受到影响
1~99: 自动曝光ROI矩形内指定百分比最亮像素的平均亮度, 默认: 1
0或100: 自动曝光ROI矩形内全部像素的平均亮度, 意味着“禁用”0(禁用) 是 AUTOEXPOSURE_PERCENT AEDampTime Int RW 自动曝光阻尼系数: 曝光时间 (千分数)
阻尼系数越大, 曝光时间改变越平滑越慢0 是 AUTOEXP_EXPOTIME_DAMP AEDampGain Int RW 自动曝光阻尼系数: 增益 (千分数)
阻尼系数越大, 增益改变越平滑越慢0 是 AUTOEXP_GAIN_DAMP AETrigger Enum RW 触发模式下自动曝光:
1: 启用
0: 禁用0 是 AUTOEXPO_TRIGGER AEOverPolicy Int RW 自动曝光过曝策略: 当过曝时,
0: 直接降低曝光时间/增益到最小值; 或策略0的优点是收敛速度更快, 缺点是有黑屏.
1: 按当前和目标亮度的比例降低曝光时间/增益; 或
n(>1): 先将曝光时间调节为(自动曝光时间最大值*自动曝光增益最大值) * n / 1000, 然后再按1的策略进行调节
策略1避免黑屏, 但是收敛速度更慢.0 是 OVEREXP_POLICY AEConv Enum RO 自动曝光收敛状态:
1: 已收敛
0: 未收敛
-1: 未决.NA NA AutoExpoConv Enum RO 获取当前自动曝光收敛状态:
1: 是
0: 否
-1: PENDING, 未决NA AUTOEXPO_CONV 帧信息与统计 (FrameInfo)
帧队列统计、接收包计数和传感器时序信息.
字符串名(strName) 取值方式 读写 说明 默认值 是否可以在相机处于运行状态设置该值
(调用Toupcam_StartXXXX之前或Toupcam_Stop之后)选项(旧接口)
(TOUPCAM_OPTION_XXXX)DropFrame Int RO 已经从USB抓取但是被软件丢弃的帧数 NA NA NUMBER_DROP_FRAME FrontDequeCurrent Int RO 获取前端队列当前帧数目 NA NA FRONTEND_DEQUE_CURRENT BackDequeCurrent Int RO 获取后端队列当前帧数目 NA NA BACKEND_DEQUE_CURRENT FrontFull Int RO 获取前端队列满数目 NA NA FRONTEND_FULL BackFull Int RO 获取后端队列满数目 NA NA BACKEND_FULL PacketNumber Int RO 获取接收到的包数目 NA NA PACKET_NUMBER PacketNum Int RO USB设备已接收的包数量; 非USB设备返回E_NOTIMPL. NA NA LineLength Int RW 传感器行长(pixel clock) NA 是 LINE_LENGTH LineTime Int RO 传感器行时间(纳秒) NA NA LINE_TIME ReadTime Int RO 传感器读出时间, 不支持时返回E_NOTIMPL; 单位由相机型号定义. NA NA READ_TIME AllExpoTime Int RO 传感器整体曝光时间, 不支持时返回E_NOTIMPL; 单位由相机型号定义. NA NA ALL_EXPO_TIME CameraPeriod Int RO 相机采集周期, 不支持时返回E_NOTIMPL; 单位由相机型号定义. NA NA CAMERA_PERIOD 重要提示:
返回值：HRESULT类型表示成功或失败
参数：
HToupcam h：相机句柄
int val:
0: 非实时(Off)当帧缓冲队列满时停止抓帧, 直到队列中的帧被取走从而队列非满1: 实时(Both)使用最小的帧缓冲. 当新帧来到时, 不论帧缓冲区是否满, 都把所有的老帧全部丢弃.2: 软实时(Soft)
如果有DDR, 将同时把DDR帧缓冲也设为1.使用最小的帧缓冲. 当新帧来到时, 不论帧缓冲区是否满, 都把所有的老帧全部丢弃.
如果有DDR, DDR帧缓冲不做任何修改.
说明：如果设置RealTime模式为1, 更短的帧延时, 但是帧速率降低, 流畅性受损. 缺省设为0, 一般不需要改动.
返回值：HRESULT类型表示成功或失败
参数：
HToupcam h：相机句柄
0: 不启用自动曝光
1: 自动曝光连续模式
2: 自动曝光“单次”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：1(单色)或0(彩色)
说明：多色模式或者单色模式.
返回值：HRESULT类型表示成功或失败
参数： HToupcam h：相机句柄
说明：垂直或者水平翻转
返回值：HRESULT类型表示成功或失败
参数：
HToupcam h：相机句柄
unsigned short nSpeed：帧速率级别
说明：最小帧速率等级是0. 最大帧速率级别可以通过Toupcam_get_MaxSpeed函数得到, 和ToupcamModelV2的maxspeed是一个意思.
对于部分支持所谓精确帧率的相机, 建议使用精确帧率控制. 为了保持兼容, Speed仍然有效, 映射机制为: MaxSpeed为9(共10级), 分别对应Bandwidth从10%~100%时的最大帧率. 如设置speed为8, 等同于: 精确帧率设置为Bandwith设置为90%时的最大帧率.
返回值：HRESULT类型表示成功或失败
参数：
HToupcam h：相机句柄
unsigned* nFrame: 最近时间的帧数
unsigned* nTime: 时间(毫秒数)
unsigned* nTotalFrame: 相机开启以来收到的总帧数
说明：获取最近时间(大约几秒)相机实际帧率. 用以下算式计算:
返回值：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℃. 设置目标温度为"-2730"或以下表示使用本型号的默认值.
说明：读取传感器温度(TOUPCAM_FLAG_GETTEMPERATURE表示支持读取温度).
设置传感器目标温度, 和Toupcam_put_Option(, TOUPCAM_OPTION_TECTARGET, )等价.
返回值：HRESULT类型表示成功或失败
参数：
HToupcam h：相机句柄
int bSkip：Bin模式或者Skip模式
说明：设置Bin模式或者Skip模式. 较高分辨率的相机支持2种采样模式, 一种是Bin模式(邻域平均), 一种是Skip模式(抽样提取). 相比较而言, 前者图像效果较好, 但是帧速率降低；后者帧速率较高, 但是图像效果较差.
返回值：HRESULT类型表示成功或失败. Temp/Tint模式下起作用, RGB Gain模式下不起作用直接返回E_NOTIMPL. 对于黑白相机, 始终返回E_NOTIMPL.
参数：
HToupcam h：相机句柄
int nTemp, int nTint：色温和Tint
说明：Temp/Tint模式下设置/获取白平衡的色温和Tint参数. 请参阅这里.
返回值：HRESULT类型表示成功或失败. Temp/Tint模式下起作用, RGB Gain模式下不起作用直接返回E_NOTIMPL. 对于黑白相机, 始终返回E_NOTIMPL.
参数：
HToupcam h：相机句柄
PITOUPCAM_TEMPTINT_CALLBACK funTT, void* ctxTT：自动白平衡过程完成时的回调函数以及回调上下文.
说明：Temp/Tint白平衡模式下调用本函数来触发单次自动白平衡功能. 当白平衡参数计算完成的时候, TOUPCAM_EVENT_TEMPTINT事件会通知应用程序(Pull Mode)和调用回调函数. Pull mode中, 如果不使用回调函数, 请把函数指针设为NULL.
返回值：HRESULT类型表示成功或失败. RGB Gain模式下起作用, Temp/Tint模式下不起作用直接返回E_NOTIMPL. 对于黑白相机, 始终返回E_NOTIMPL.
参数：
HToupcam h：相机句柄
int aGain[3]：RGB增益值
说明：RGB Gain模式下设置/获取白平衡的RGB增益值. 请参阅这里.
返回值：HRESULT类型表示成功或失败. RGB Gain模式下起作用, Temp/Tint模式下不起作用直接返回E_NOTIMPL. 对于黑白相机, 始终返回E_NOTIMPL.
参数：
HToupcam h：相机句柄
PITOUPCAM_WHITEBALANCE_CALLBACK funWB, void* ctxWB：自动白平衡过程完成时的回调函数以及回调上下文.
说明：RGB Gain白平衡模式下调用本函数来触发单次自动白平衡功能. 当白平衡参数计算完成的时候, TOUPCAM_EVENT_WBGAIN事件会通知应用程序(Pull Mode)和调用回调函数. Pull mode中, 如果不使用回调函数, 请把函数指针设为NULL.
返回值：HRESULT类型表示成功或失败. 对于黑白相机, 始终返回E_NOTIMPL.
参数：
HToupcam h：相机句柄
PITOUPCAM_BLACKBALANCE_CALLBACK funBB, void* ctxBB：自动黑平衡过程完成时的回调函数以及回调上下文.
说明：调用本函数来触发单次自动黑平衡功能. 当黑平衡参数计算完成的时候, TOUPCAM_EVENT_BLACK事件会通知应用程序(Pull Mode)和调用回调函数. Pull mode中, 如果不使用回调函数, 请把函数指针设为NULL.
返回值：HRESULT类型表示成功或失败
参数：
HToupcam h：相机句柄
unsigned short aSub[3]：RGB偏移值
说明：设置/获取黑平衡的RGB偏移值
返回值：HRESULT类型表示成功或失败
参数：
HToupcam h：相机句柄
RECT: 矩形, 最小宽度高度: 4
说明：设置/获取自动白平衡和自动曝光和黑平衡的参考矩形. 默认矩形位于图像正中央, 宽度等于20%图像宽度, 高度等于20%图像高度.
注意：坐标永远是相对原始分辨率而言的, 请参阅这里.
对于黑白相机, 白平衡始终返回E_NOTIMPL.
返回值：S_OK表示单色模式, S_FALSE表示彩色模式
参数：HToupcam h：相机句柄
说明：是否单色相机, 对应ToupcamModelV2的flag: TOUPCAM_FLAG_MONO
返回值：相机支持的最大位深度(bitdepth)
参数：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
说明：每个相机都有一个唯一的序列号, 这里.
返回值：HRESULT类型表示成功或失败
参数：
HToupcam h：相机句柄
unsigned nResolutionIndex：分辨率序号
float* x, float* y: 传感器物理像元大小, 如2.4μm × 2.4μ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: 相机句柄
const unsigned char* pBuffer: 需要写入的数据
unsigned char* pBuffer: 读取缓冲区
unsigned nBufferLen: 缓冲区长度
说明：如果读写失败, 返回负数HRESULT；如果成功, 返回读写成功的字节数.
返回值：HRESULT类型表示成功或失败
参数：
HToupcam h：相机句柄
返回值：HRESULT类型表示成功或失败
参数：
HToupcam h：相机句柄
filepath: 文件路径
说明：导入导出*.raw或*.ffc, *.dfc, *.fpnc文件.
返回值：HRESULT类型表示成功或失败
参数：
HToupcam h：相机句柄
unsigned ioLine:
0 => Opto-isolated input
1 => Opto-isolated output
2 => GPIO0
3 => GPIO1unsigned 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 => 下降沿, 0x02 => 高电平, 0x03 => 低电平 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, 65535] TOUPCAM_IOCONTROLTYPE_SET_BURSTCOUNTER TOUPCAM_IOCONTROLTYPE_GET_COUNTERSOURCE 计数器模式信号源：
0x00 => 光耦隔离输入
0x01 => GPIO0
0x02 => GPIO1TOUPCAM_IOCONTROLTYPE_SET_COUNTERSOURCE TOUPCAM_IOCONTROLTYPE_GET_COUNTERVALUE 计数值, 范围：[1, 65535] TOUPCAM_IOCONTROLTYPE_SET_COUNTERVALUE TOUPCAM_IOCONTROLTYPE_SET_RESETCOUNTER 计数器复位 TOUPCAM_IOCONTROLTYPE_GET_PWM_FREQ PWM频率, 范围: [0, 0xffffffff] TOUPCAM_IOCONTROLTYPE_SET_PWM_FREQ TOUPCAM_IOCONTROLTYPE_SET_COUNTERVALUE TOUPCAM_IOCONTROLTYPE_GET_PWM_DUTYRATIO PWM占空比, 默认: 50, 范围: [0, 100] TOUPCAM_IOCONTROLTYPE_SET_COUNTERVALUE TOUPCAM_IOCONTROLTYPE_GET_PWMSOURCE 脉冲模式信号源：
0x00 => 光耦隔离输入
0x01 => GPIO0
0x02 => GPIO1TOUPCAM_IOCONTROLTYPE_SET_PWMSOURCE TOUPCAM_IOCONTROLTYPE_GET_OUTPUTMODE 输出模式：
0x00 => 触发等待信号
0x01 => 曝光有效信号
0x02 => 闪光灯信号
0x03 => 用户输出信号
0x04 => 计数器输出信号
0x05 => 定时器输出信号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 TOUPCAM_IOCONTROLTYPE_GET_EXPO_ACTIVE_MODE 曝光时间信号(exposure time signal):
0 => 指定行(specified line)
1 => common exposure timeTOUPCAM_IOCONTROLTYPE_SET_EXPO_ACTIVE_MODE TOUPCAM_IOCONTROLTYPE_GET_EXEVT_ACTIVE_MODE 曝光事件(exposure event):
0 => 指定行(specified line)
1 => common exposure timeTOUPCAM_IOCONTROLTYPE_SET_EXEVT_ACTIVE_MODE TOUPCAM_IOCONTROLTYPE_GET_EXPO_START_LINE 曝光开始行, 默认：0, 范围: [0, 16384] TOUPCAM_IOCONTROLTYPE_SET_EXPO_START_LINE TOUPCAM_IOCONTROLTYPE_GET_EXPO_END_LINE 曝光结束行, 默认：0, 范围: [0, 16384]
结束行必须不小于开始行TOUPCAM_IOCONTROLTYPE_SET_EXPO_END_LINE TOUPCAM_IOCONTROLTYPE_GET_OUTPUTCOUNTERVALUE 输出计数器, 范围: [0, 65535] TOUPCAM_IOCONTROLTYPE_SET_OUTPUTCOUNTERVALUE TOUPCAM_IOCONTROLTYPE_SET_OUTPUT_PAUSE 输出暂停: 1 => 暂停, 0 => 继续 TOUPCAM_IOCONTROLTYPE_GET_INPUT_STATE 输入状态: 0 (低电平) 或 1 (高电平) TOUPCAM_IOCONTROLTYPE_GET_USER_PULSE_HIGH 用户脉冲高电平时间(微秒), 范围: [0, 0xffffffff] TOUPCAM_IOCONTROLTYPE_SET_USER_PULSE_HIGH TOUPCAM_IOCONTROLTYPE_GET_USER_PULSE_LOW 用户脉冲低电平时间(微秒), 范围: [0, 0xffffffff] TOUPCAM_IOCONTROLTYPE_SET_USER_PULSE_LOW TOUPCAM_IOCONTROLTYPE_GET_USER_PULSE_NUMBER 用户脉冲数目, 默认值: 0, 范围: [0, 0xffffffff] TOUPCAM_IOCONTROLTYPE_SET_USER_PULSE_NUMBER TOUPCAM_IOCONTROLTYPE_GET_EXTERNAL_TRIGGER_NUMBER 外部触发信号计数 TOUPCAM_IOCONTROLTYPE_GET_DEBOUNCER_TRIGGER_NUMBER 消抖后的触发信号计数 TOUPCAM_IOCONTROLTYPE_GET_EFFECTIVE_TRIGGER_NUMBER 有效触发信号计数
返回值：HRESULT类型表示成功或失败
参数：
HToupcam h：相机句柄
unsigned short mode: 模式, 见下表
TOUPCAM_LEVELRANGE_MANUAL 手动模式 TOUPCAM_LEVELRANGE_ONCE 单次 TOUPCAM_LEVELRANGE_CONTINUE 持续模式 TOUPCAM_LEVELRANGE_ROI 更新ROI矩形 RECT* pRoiRect: ROI矩形
unsigned short aLow[4], unsigned short aHigh[4]: R, G, B和灰度的Level Range. RGB只对彩色图像有效, 灰度只对灰度图像有效.
说明：LevelRange相关.
返回值：HRESULT类型表示成功或失败
参数：
funDemosaic: 替换内建的demosaic函数
ctxDemosaic: 回调函数上下文
返回值：HRESULT类型表示成功或失败
参数：
camId：相机实例ID
filePath: *.ufw文件全路径
pFun, ctxProgress: 进度百分比回调函数
说明：固件升级. 升级过程中请千万不要拔出设备或断电, 这非常非常重要. 一旦升级过程中拔出设备或断电, 相机将不再可用, 只能返厂维修.
返回值：>0: 被插拔的相机数量; =0: 没有找到对应的相机; E_ACCESSDENIED: 权限不足, 需要管理员权限
参数：
camId：相机实例ID
说明：模拟插拔, 整个过程大约需要3秒钟
返回值：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 funHistogram, void* ctxHistogram：直方图数据的回调函数以及回调上下文
说明：获取直方图数据
| 参数 | 范围 | 默认值 | 获取 | 设置 | 自动 | ||
| Auto Exposure Target (自动曝光目标亮度) |
16~220 | 120 | Toupcam_get_AutoExpoTarget | Toupcam_put_AutoExpoTarget | |||
| Exposure Gain (曝光增益) |
100~ | 100 | Toupcam_get_ExpoAGain | Toupcam_put_ExpoAGain | |||
| 白平衡 | Temp/Tint模式 | Temp(色温) | 2000~15000 | 6503 | Toupcam_get_TempTint | Toupcam_put_TempTint | Toupcam_AwbOnce |
| Tint | 200~2500 | 1000 | |||||
| RGB Gain模式 | Red Gain | -127~127 | 0 | Toupcam_get_WhiteBalanceGain | Toupcam_put_WhiteBalanceGain | Toupcam_AwbInit | |
| Green Gain | |||||||
| Blue Gain | |||||||
| 黑平衡 | 0~255(位深度=8) 0~1023(位深度=10) 0~4095(位深度=12) 0~16383(位深度=14) 0~65535(位深度=16) | 0 | Toupcam_get_BlackBalance | Toupcam_put_BlackBalance | Toupcam_AbbOnce | ||
| LevelRange | 软件 | 0~255 | Low = 0 High = 255 |
Toupcam_get_LevelRange | Toupcam_put_LevelRange | Toupcam_LevelRangeAuto | |
| 硬件 | Toupcam_get_LevelRangeV2 | Toupcam_put_LevelRangeV2 | |||||
| Contrast(对比度) | -255~255 | 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(亮度) | -255~255 | 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_AutoExpoRange Toupcam_get_MaxAutoExpoTimeAGain Toupcam_get_MinAutoExpoTimeAGain |
Toupcam_put_AutoExpoRange Toupcam_put_MaxAutoExpoTimeAGain Toupcam_put_MinAutoExpoTimeAGain |
||
| Gain (增益) | 500 | ||||||
| Min(最小) | Exposure Time (曝光时间) |
0 | Toupcam_get_MinAutoExpoTimeAGain | Toupcam_put_MinAutoExpoTimeAGain | |||
| Gain (增益) | 100 | ||||||
| Percent(百分比) | 0~100 | 0(禁用) 10(启用) |
TOUPCAM_OPTION_AUTOEXPOSURE_PERCENT | ||||
| TEC目标 | 型号特定 | 型号特定 | TOUPCAM_OPTION_TECTARGET | ||||
Toupcam支持.NET开发环境(C#和VB.NET, .Net Framework, .Net Core).
toupcam.cs使用P/Invoke调用至toupcam.dll. 把toupcam.cs拷贝到你的C#工程中使用, 请参考示例代码.
请主意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, qt5.py, qt6.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调用至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放在合适目录
netsh interface ipv4 show subinterface |
安装: netcfg.exe -v -l gigepdrv.inf -c s -i gigepdrv |
禁用防火墙(网卡名称"xx"): Set-NetFirewallProfile -Name Private,Public,Domain -DisabledInterfaceAliases "xx" 恢复所有网卡: Set-NetFirewallProfile -Name Private,Public,Domain -DisabledInterfaceAliases @() |
| 名称 | 平台 | 语言 | 依赖 | 界面 | 描述 | |
| demosimplest | Win32 Linux macOS Android |
C++ | console | 最简单的示例, 大约70行代码. 截图. | ||
| imageptrsimplest | 最简单的使用ImagePtr示例, 大约50行代码 | |||||
| gigesimplest | 最简单使用GigE相机示例, 大约75行代码 | |||||
| demowait | 不使用回调函数, 使用Toupcam_WaitImageV4获取图像, 大约60行代码. | |||||
| demomulti | 打开所有枚举到的相机(可能多台)并获取图像, 大约90行代码. | |||||
| demostill | 最简单的静态图像抓拍, 大约120行代码. | |||||
| demosofttrigger | 最简单的软触发示例, 大约80行代码. | |||||
| demotriggersync | 同步软触发(TriggerSync)示例, 大约80行代码. | |||||
| democfg | 配置文件示例(参阅这里), 大约80行代码. | |||||
| demoexternaltrigger | 最简单的外部触发示例, 大约130行代码. | |||||
| demotriggerout | 最简单的输出信号示例, 大约150行代码. | |||||
| demoraw | RAW数据, 静态抓拍以及保存RAW数据到*.raw文件, 大约140行代码. 截图. | |||||
| demostillraw | 静态RAW抓拍并保存到*.raw文件, 大约140行代码. | |||||
| demoqt imageptrqt |
Win32 Linux macOS |
Qt | GUI | Qt示例, 截图. 两个示例的区别在于是否使用ImagePtr模式. 枚举设备, 打开设备, 预览视频, 抓拍(静态)图像, 设置分辨率, 保存图像到文件, 设置自动曝光和白平衡, 帧率(fps)计算, 等等. 这个示例使用Pull Mode机制, StartPullModeWithCallback |
||
| demotwoqt | Qt示例, 截图. 同时打开2台相机 |
|||||
| demolinecam | Qt示例. 线扫相机 |
|||||
| democpp imageptrcpp |
Win32 | ATL/WTL | 截图. 两个示例的区别在于是否使用ImagePtr模式. 枚举设备(响应设备插入/拔出通知), 初始化支持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 imageptrmfc |
MFC | 截图. 两个示例的区别在于是否使用ImagePtr模式. 打开设备, 预览视频, 抓拍图像, 设置分辨率, 多种图片格式(.bmp, .jpg, .png等)保存图像到文件, 等等. 这个示例使用Pull Mode机制 |
||||
| demod3d11 | 类似demomfc, 改用D3D11显示视频 | |||||
| autotest | 截图. 自动测试工具(用于自动测试开关相机, 分辨率切换, 抓拍, ROI, 位深度切换等等) | |||||
| demowpf | .NET | C# | WPF | winwpf示例, 截图. 支持枚举设备, 打开设备, 预览视频, 抓拍(静态)图像, 保存图片到文件, 设置自动曝光和白平衡, 帧率(fps)计算, 等等. 这个示例使用Pull Mode机制, StartPullModeWithCallback |
||
| demowinformcs imageptrwinform |
WinForm | winform示例, 截图. 两个示例的区别在于是否使用ImagePtr模式. 支持枚举设备, 打开设备, 预览视频, 抓拍(静态)图像, 保存图片到文件, 设置自动曝光和白平衡, 帧率(fps)计算, 等等. 这个示例使用Pull Mode机制, StartPullModeWithCallback |
||||
| demopushcs | winform示例, 使用Push Mode机制 | |||||
| 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 imageptrsimplest |
Win32 Linux macOS |
Java | jna | console | 最简单java示例. IntelliJ工程 两个示例的区别在于是否使用ImagePtr模式 |
| javafx | GUI | javafx示例. IntelliJ工程 | ||||
| swing | swing示例. IntelliJ工程 | |||||
| demopython | simplest imageptrsimplest | Python | console | 最简单python示例 两个示例的区别在于是否使用ImagePtr模式 |
||
| gigesimplest | 支持GigE相机最简单python示例 | |||||
| qt5 qt6 | 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示例同时打开两台相机 | |||||
| LVDemo3 | Labview示例, 截图. 打开设备, 预览视频, 抓拍(静态)图像, 设置分辨率, 设置自动曝光, 位深度切换, 颜色调整, 白(黑)平衡设置, 数字binning设置, 平场(暗场)校正, 等等. |
|||||
| demoopencv4 | Win32 Linux macOS |
C++ | OpenCV | opencv示例 | ||
| imagepro | liveedf | C++ | Qt | 景深扩展(EDF), Qt示例, snapshot. | ||
| C# | WinForm | 景深扩展(EDF), C#示例, snapshot. | ||||
| livestack | C++ | Qt | Qt示例, snapshot. | |||
| C# | WinForm | C#示例, snapshot. | ||||
| livestitch | C++ | Qt | 拼接, Qt示例 | |||
| C# | WinForm | 拼接, C#示例 | ||||
v60: 增加ImagePtr模式, 参阅这里
v59: 增加RAW=-1模式, 参阅这里
v58: 通过sn, name (GigE: ip, mac)参数Open相机
v57: 增加Toupcam_PullImageV4, ToupcamFrameInfoV4, GPS
v56: 性能提升: RAW模式下减少帧数据copy
v55: 增加支持HDR Pixel Format
v54: 增加支持GigE. 请参阅这里
v53: 增加ToupcamFrameInfoV3, Toupcam_PullImageV3, Toupcam_StartPushModeV4
v52: 安卓Java侧传递文件描述符给Toupcam_Open打开相机. 请参阅这里
v51: 支持自动曝光“单次”模式. 请参阅这里
v50: Windows(x86/x64), Linux(x64), Android(x64)平台上SIMD加速
前端和后端队列长度: TOUPCAM_OPTION_FRONTEND_DEQUE_LENGTH和TOUPCAM_OPTION_BACKEND_DEQUE_LENGTH
v49: 增加支持相机配置的保存和加载. 请参阅这里
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\autotest
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: 支持更多的位深度(bitdepth): 10bits, 12bits, 14bits, 16bits
v2: 支持RAW模式, 请参阅这里和这里；增加对Linux和macOS的支持
v1: 初始发布
