凯视佳产品文档 产品文档与技术支持

KSJXS SDK 快速开始

版本 1.0 · 更新于 2026-10-21 · 阅读 1

KSJXS SDK 的头文件、库文件、调用流程与关键顺序约束（GetRoi 必须在 SetDataFormat 之后）。

开发包组成

文件 说明
KSJXS_Device.h 主接口头文件：基础功能、ROI、参数、触发、采集等全部导出函数
KSJXS_CameraParams.h 数据结构与回调类型定义（设备信息、数据格式、回调 typedef、CaptureData）
KSJXS_ErrorDefine.h 返回码定义（KSJXS_RET_*）
KSJXS_Device.lib / .dll 导入库与动态库（Windows；32/64 位各一份）

引入方式：

#include "KSJXS_Device.h"   // 已内部包含 CameraParams.h 与 ErrorDefine.h

接口约定：所有导出函数均为 __stdcall 调用约定，返回 int 错误码；不使用异常，
每个返回值都要判断是否为 KSJXS_RET_SUCCESS。

调用流程总览

KSJXS_SetLog            （可选）开启日志，便于定位问题
KSJXS_Inital            初始化 SDK
KSJXS_EnumDevices       枚举设备 → 得到 KSJXS_DEVICE_INFO_LIST
KSJXS_CreateDeviceHandle 按设备信息创建设备句柄
KSJXS_OpenDevice        打开设备（独占）
  ├─ KSJXS_SetDataFormat   ← 先设置数据格式
  ├─ KSJXS_GetRoi          ← 再读 ROI（顺序约束，见下）
  ├─ 参数设置（曝光 / 增益 / 激光 / 触发 / 分辨率 …）
  ├─ KSJXS_RegisterXxxCB   回调模式注册回调（nMode = 0）
  ├─ KSJXS_StartAcquisition
  ├─ 取数据（回调 或 KSJXS_CaptureData）
  ├─ KSJXS_StopAcquisition
  └─（改参数 / 反复采集）
KSJXS_CloseDevice       关闭设备
KSJXS_DestroyDeviceHandle 销毁句柄
KSJXS_UnInitial         反初始化 SDK

⚠️ 关键调用顺序约束

KSJXS_GetRoi 必须在 KSJXS_SetDataFormat 之后调用。

KSJXS_GetRoi 返回的 ROI 与当前数据格式相关；在 KSJXS_SetDataFormat 之前读取，
得到的 ROI 数据未定义，可能导致裁剪区域错误或返回失败。这是最常踩的坑，
请把该顺序写进代码评审检查清单。

采集模式：回调 vs 主动

KSJXS_StartAcquisition(handle, nMode) 的 nMode 决定取数方式：

模式 nMode 取数方式 适用场景
回调模式（默认） 0 通过 KSJXS_RegisterXxxCB 注册的回调被 SDK 线程异步调用 UI 连续预览、实时处理
主动采集模式 1 调用线程通过 KSJXS_CaptureData 阻塞取一帧，用完 KSJXS_ReleaseData 释放 单次测量、同步逻辑

一旦 KSJXS_StartAcquisition，部分参数（ROI、触发模式等）不可再改动，需先
KSJXS_StopAcquisition。

回调与数据格式的对应关系

注册哪个回调、以及回调是否会被触发，由当前数据格式 KSJXS_DATA_FORMAT 决定：

数据格式 注册的回调 回调函数类型
KSJXS_DF_IMAGE KSJXS_RegisterImageModeCB KSJXS_IMAGE_MODE_CALLBACK
KSJXS_DF_NON_UNIFORM KSJXS_RegisterProfileCB / KSJXS_RegisterPtCloudCB KSJXS_PROFILE_CALLBACK / KSJXS_PTCLOUD_CALLBACK
KSJXS_DF_UNIFORMX KSJXS_RegisterUniformXProfileCB / KSJXS_RegisterZMapCB KSJXS_UNIFORMX_PROFILE_CALLBACK / KSJXS_ZMAP_CALLBACK
KSJXS_DF_NON_UNIFORM_INTENSITY KSJXS_RegisterPIProfileCB / KSJXS_RegisterPICB KSJXS_PROFILE_I_CALLBACK / KSJXS_PI_CALLBACK
KSJXS_DF_UNIFORMX_INTENSITY KSJXS_RegisterZIProfileCB / KSJXS_RegisterZICB KSJXS_UNIFORMX_PROFILE_I_CALLBACK / KSJXS_ZI_CALLBACK

无效点约定

回调与主动采集返回的坐标数据中，无效数据点的 x、z 值被赋为 -1000，
调用方以此为哨兵值排除无效点。坐标系原点为全视野的左下角。

线程注意

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

单位约定速查

量 单位
曝光时间 毫秒（ms）
触发滤波 / 延迟 微秒（μs）
坐标 X / Y / Z、精度、阈值、视野 毫米（mm）
ROI 起始 / 宽高 像素
系统时钟 MHz
超时时间 毫秒（ms）