KSJAPI SDK 快速开始 - 凯视佳产品文档

关于本 SDK

KSJAPI 是凯视佳工业相机（USB2.0 / USB3.0 / GigE 面阵、线阵相机）的通用 C 接口开发包，
导出函数前缀统一为 KSJ_，采用 __stdcall 调用约定，返回 int 状态码。

⚠️ 返回码约定与常见 SDK 不同：RET_SUCCESS 的值为 1（不是 0）。所有函数都返回 int，
必须逐个判断是否等于 RET_SUCCESS。详见「错误码」章节。

开发包组成

KSJApi.Inc 目录包含 27 个头文件，其中 KSJApi.h 是总入口，自动包含以下子模块：

头文件	模块用途
`KSJApi.h`	总入口，include 全部子模块
`KSJCode.h`	返回码定义（`RET_*`）
`KSJApiBase.h`	基础：设备信息、参数、视场、采集、预览、黑电平
`KSJApiFunction.h`	相机功能查询（`KSJ_FUNCTION`）
`KSJApiTriggerMode.h`	触发模式、外触发条件、编码器、延时、开始结束模式
`KSJApiCallback.h`	预览回调函数
`KSJApiMatrix.h`	色彩模式：白平衡、色温、颜色校正矩阵（CCM）
`KSJApi3A.h`	自动曝光（AE）、自动白平衡（AWB）区域与回调
`KSJApiImage.h`	图像处理：饱和度、Gamma、对比度、亮度、锐化、坏点校正
`KSJApiBayer.h`	Bayer 转换模式与滤波模式
`KSJApiCompanding.h`	LUT 查找表与灵敏度（截位）模式
`KSJApi16Bits.h`	16 位数据传输、ADC 精度、Tiff 保存
`KSJApiMultiFrames.h`	多帧垂直拼图（线阵常用）
`KSJApiRecord.h`	视频录影
`KSJApiIo.h`	GPIO、闪光灯、输入输出滤波、DAC
`KSJApiWaterMark.h`	水印信息、精准时钟与时间同步
`KSJApiCustom.h`	自定义：图像格式、负片、FFC 平场校正、畸变校正、预曝光、缓存
`KSJApiAwaiba.h`	AWAIBA 线阵相机的区段增益/黑电平等
`KSJApiProgram.h`	厂商读写区：序号、LUT 信息、硬件白平衡/CCM、参数固化
`KSJApiStream.h`	流模式
`KSJApiMultiProcess.h`	多进程下的相机打开/关闭
`KSJApiString.h`	语言设置与枚举字符串获取（未被总入口包含，需单独 include）
`KSJApiRoiSizeList.h`	常用 ROI 列表（需单独 include）
`KSJApiBarcodeReader.h`	条码解码库（需单独 include）
`KSJApiUserZone.H`	用户 EEPROM 读写区域（需单独 include）
`KSJObsolete.h`	兼容旧版本保留、已不推荐使用的函数
`KSJApiInternal.h`	凯视佳内部调试接口，不对外提供，请勿调用

开发环境引用方式

#include "KSJApi.h"
#pragma comment( lib, "KSJApi.Lib\\x64\\KSJApi.lib" )   // 32 位则用 x86

动态库 KSJApi.dll 需与可执行文件同目录或在 PATH 中。x86 / x64 各一份，务必与工程平台一致。

调用流程总览

KSJ_Init                    初始化 SDK（相机须在此前已连接主机）
KSJ_DeviceGetCount          获取相机数目
KSJ_DeviceGetInformation    读型号 / 序号 / 固件版本
KSJ_DeviceOpen              打开设备（多进程场景必须；单进程可选）
  ├─ 设置：KSJ_CaptureSetFieldOfView / KSJ_SetParam / KSJ_ExposureTimeSet …
  ├─ 触发：KSJ_TriggerModeSet / KSJ_TriggerMethodSet / KSJ_EncoderDirectionSet …
  ├─ 预览模式：KSJ_PreviewSetPos → KSJ_PreviewStart(true) → 回调
  └─ 主动采集：KSJ_CaptureRgbData / KSJ_CaptureRawData（阻塞取一帧）
KSJ_DeviceClose             关闭设备
KSJ_UnInit                  反初始化（释放资源并关闭本进程所有相机）

⚠️ 关键约束

相机必须在 KSJ_Init 之前与电脑连接，否则枚举不到。
重新枚举后操作索引 nIndex 可能改变：不能靠索引区分相机，应先用 KSJ_SetSerials 给相机分配序号
（0-255，保存到相机内部），再用 KSJ_GetDeviceIndex 由序号反查当前索引。
返回码 RET_SUCCESS = 1，判断成功要用 == RET_SUCCESS，不能写 > 0 或 == 0。
预览流程有顺序要求：必须先 KSJ_PreviewSetPos 建立预览窗口和位置，再 KSJ_PreviewStart，
否则看不到画面。
Capture 系列是阻塞调用：无图像返回时会一直等到超时。外触发模式下没有触发信号时，
可用 KSJ_SendPktEnd 主动结束当前传输（会得到零帧 RET_ZEROFRAME 或半帧 RET_INVALIDFRAME）。
参数固化：KSJ_ParamProgram 把当前主要参数（预览/采集视场、曝光、增益）写入相机，
断电重连后自动加载；KSJ_ParamErase 擦除后相机恢复出厂设置。

单位约定速查

量	单位 / 说明
曝光时间	毫秒（ms）
外触发延时	时间步长 100μs（读到的值 ×100 为 μs）
触发/IO 滤波	微秒（μs）
采集超时	毫秒（ms）
固定帧率	帧/秒（fps）
水印时间戳	微秒（μs）；支持精准时钟时为「时钟计数」，需按系统时钟 MHz 换算
DAC 值	数字量
视场起始/宽高	像素

线程注意

KSJ_PreviewSetCallback / KSJ_AESetCallbackEx 等回调工作在 SDK 线程。涉及 UI 更新时必须投递回主线程
（Qt 中用 queued signal，自定义类型先 qRegisterMetaType 注册）；回调内不要做耗时操作，否则会丢帧。