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

KSJXS SDK · 采集与数据获取

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

启停采集、回调注册、主动取数据、超时与缓存、数据格式、帧率与 ZMap 重采样。

本组对应头文件 @defgroup Capture。取数有两条路径：回调模式（nMode=0） 与 主动采集模式（nMode=1），二者互斥。

回调注册函数一览

先 KSJXS_SetDataFormat 设定格式，再注册对应回调；只有格式匹配的回调才会被触发。

注册函数 回调类型 触发的数据格式 用途
KSJXS_RegisterImageModeCB KSJXS_IMAGE_MODE_CALLBACK KSJXS_DF_IMAGE 原图（调试参数）
KSJXS_RegisterLiveImageCB KSJXS_LIVE_IMAGE_CALLBACK 非原图模式 实时图像（调试；仅 USB 接口 UC3D，可能降低 3D 性能）
KSJXS_RegisterProfileCB KSJXS_PROFILE_CALLBACK KSJXS_DF_NON_UNIFORM 原始 3D 轮廓
KSJXS_RegisterPtCloudCB KSJXS_PTCLOUD_CALLBACK KSJXS_DF_NON_UNIFORM 原始 3D 点云
KSJXS_RegisterUniformXProfileCB KSJXS_UNIFORMX_PROFILE_CALLBACK KSJXS_DF_UNIFORMX X 重排轮廓
KSJXS_RegisterZMapCB KSJXS_ZMAP_CALLBACK KSJXS_DF_UNIFORMX ZMap 高度图
KSJXS_RegisterPIProfileCB KSJXS_PROFILE_I_CALLBACK KSJXS_DF_NON_UNIFORM_INTENSITY 轮廓 + 亮度
KSJXS_RegisterPICB KSJXS_PI_CALLBACK KSJXS_DF_NON_UNIFORM_INTENSITY 点云 + 亮度
KSJXS_RegisterZIProfileCB KSJXS_UNIFORMX_PROFILE_I_CALLBACK KSJXS_DF_UNIFORMX_INTENSITY 重排轮廓 + 亮度
KSJXS_RegisterZICB KSJXS_ZI_CALLBACK KSJXS_DF_UNIFORMX_INTENSITY ZMap + 亮度

注册函数签名统一为：int KSJXS_RegisterXxxCB(IN void* handle, <回调类型> pfCallback, void* lpContext)。

KSJXS_StartAcquisition

int KSJXS_StartAcquisition(IN void* handle, int nMode = 0)

启动相机开始采集。

参数 方向 说明
nMode in 采集模式：0 = 回调模式（默认），1 = 主动采集模式（用 KSJXS_CaptureData 取数）

返回：成功返回 KSJXS_RET_SUCCESS

说明

  • 启动后部分参数不可改（ROI、触发模式等），需先 KSJXS_StopAcquisition。

KSJXS_StopAcquisition

int KSJXS_StopAcquisition(IN void* handle)

停止相机采集。

参数 方向 说明
handle in 设备句柄

返回：成功返回 KSJXS_RET_SUCCESS；失败返回错误码

KSJXS_CaptureData

int KSJXS_CaptureData(IN void* handle, CaptureData** data)

主动采集一帧数据。

参数 方向 说明
data out 采集到的数据（CaptureData 联合体，按数据格式解析）

返回：成功返回 KSJXS_RET_SUCCESS

说明

  • 仅在 KSJXS_StartAcquisition 的 nMode = 1 时有效。
  • 取到数据后必须调用 KSJXS_ReleaseData 释放内存。

KSJXS_ReleaseData

int KSJXS_ReleaseData(IN void* handle, CaptureData* data)

释放 KSJXS_CaptureData 采集的数据内存。

参数 方向 说明
data in KSJXS_CaptureData 返回的数据指针

返回：成功返回 KSJXS_RET_SUCCESS；失败返回错误码

KSJXS_SetCaptureTimeout

int KSJXS_SetCaptureTimeout(IN void* handle, unsigned long dwTimeOut)

设置采集超时时间（对应 KSJXS_CaptureData 返回的最长时间）。

参数 方向 说明
dwTimeOut in 采集超时时间，单位：ms

返回：成功返回 KSJXS_RET_SUCCESS

说明

  • 外触发时该时间最好大于外触发可能的最大时间间隔。

KSJXS_GetCaptureTimeout

int KSJXS_GetCaptureTimeout(IN void* handle, unsigned long* pdwTimeOut)

获取采集超时时间。

参数 方向 说明
pdwTimeOut out 当前超时时间，单位：ms

返回：成功返回 KSJXS_RET_SUCCESS；失败返回错误码

KSJXS_SetImageTimeout

int KSJXS_SetImageTimeout(IN void* handle, unsigned long dwTimeOut)

（UC3D）设置采集图像超时时间。

参数 方向 说明
dwTimeOut in 采集超时时间，单位：ms

返回：成功返回 KSJXS_RET_SUCCESS

说明

  • 仅 UC3D 设备支持。

KSJXS_GetImageTimeout

int KSJXS_GetImageTimeout(IN void* handle, unsigned long* pdwTimeOut)

（UC3D）获取采集图像超时时间。

参数 方向 说明
pdwTimeOut out 当前超时时间，单位：ms

返回：成功返回 KSJXS_RET_SUCCESS

说明

  • 仅 UC3D 设备支持。

KSJXS_SetBufferNumber

int KSJXS_SetBufferNumber(IN void* handle, int nNumber)

设置 API 轮廓的缓存数目。

参数 方向 说明
nNumber in 图像帧缓存数目

返回：成功返回 KSJXS_RET_SUCCESS

说明

  • 缓存越大占用内存越多，越能防止 PC 性能波动造成的丢帧。

KSJXS_GetBufferNumber

int KSJXS_GetBufferNumber(IN void* handle, int* pnNumber)

获取 API 轮廓的缓存数目。

参数 方向 说明
pnNumber out 图像缓存数目

返回：成功返回 KSJXS_RET_SUCCESS；失败返回错误码

KSJXS_SetDataFormat

int KSJXS_SetDataFormat(IN void* handle, KSJXS_DATA_FORMAT DataFormat)

设置 3D 图像数据格式。

参数 方向 说明
DataFormat in 数据格式，见 KSJXS_DATA_FORMAT

返回：成功返回 KSJXS_RET_SUCCESS

说明

  • 应在 KSJXS_GetRoi 之前调用；采集前必须确定数据格式。

KSJXS_GetDataFormat

int KSJXS_GetDataFormat(IN void* handle, KSJXS_DATA_FORMAT* pDataFormat)

获取当前 3D 图像数据格式。

参数 方向 说明
pDataFormat out 当前数据格式

返回：成功返回 KSJXS_RET_SUCCESS；失败返回错误码

KSJXS_GetSystemClock

int KSJXS_GetSystemClock(IN void* handle, float* pfSysmClockMHz)

获取系统时钟频率。

参数 方向 说明
pfSysmClockMHz out 系统时钟频率，单位：MHz

返回：成功返回 KSJXS_RET_SUCCESS

说明

  • 1 / pfSysmClockMHz 即 ullTimesTamp 时间戳的时间单位（μs）。

KSJXS_GetTransmissionRate

int KSJXS_GetTransmissionRate(IN void* handle, float* pfTransmissionRate)

获取采集帧率。

参数 方向 说明
pfTransmissionRate out 采集帧率

返回：成功返回 KSJXS_RET_SUCCESS

说明

  • 代表当前实际采集过程中轮廓数据的采集频率。

KSJXS_GetExternalTriggerRate

int KSJXS_GetExternalTriggerRate(IN void* handle, float* pfExternalTriggerRateHz)

获取轮廓触发频率。

参数 方向 说明
pfExternalTriggerRateHz out 轮廓触发频率

返回：成功返回 KSJXS_RET_SUCCESS

说明

  • Internal 模式：传感器内部按"内触发频率"实际产生的触发频率。
  • External 模式：滤波后、分频前的轮廓外触发信号输入频率。

KSJXS_GetZMapUniformXYSize

int KSJXS_GetZMapUniformXYSize(int* nOutWidth, int* nOutHeight, int nWidth, int nHeight, float fXRes, float fYRes, float fRes)

计算 XY 等距重采样后的数据尺寸。

参数 方向 说明
nOutWidth out 重采样后 X 方向数据点数
nOutHeight out 重采样后 Y 方向数据点数
nWidth in 原始 X 方向数据点数
nHeight in 原始 Y 方向数据点数
fXRes in X 方向精度，单位：mm
fYRes in Y 方向精度，单位：mm
fRes in 重采样精度，单位：mm

返回：成功返回 KSJXS_RET_SUCCESS

说明

  • 配合 KSJXS_ZMapUniformXY 使用，先算尺寸再分配内存。

KSJXS_ZMapUniformXY

int KSJXS_ZMapUniformXY(IN void* handle, float* pfZOut, float* pfZIn, int nWidth, int nHeight, float fXRes, float fYRes, float fRes)

ZMap 数据 X、Y 方向等距重采样，解决 XY 精度不同导致的变形。

参数 方向 说明
pfZOut out 重采样后 3D 数据内存指针
pfZIn in 原始 3D 数据内存指针
nWidth in X 方向数据点数
nHeight in Y 方向数据点数
fXRes in X 方向精度，单位：mm
fYRes in Y 方向精度，单位：mm
fRes in 重采样精度，单位：mm

返回：成功返回 KSJXS_RET_SUCCESS

说明

  • 输出内存需提前分配，大小由 KSJXS_GetZMapUniformXYSize 计算。

KSJXS_ZMapIntensityUniformXY

int KSJXS_ZMapIntensityUniformXY(IN void* handle, float* pfZOut, float* pfZIn, unsigned char* pIOut, unsigned char* pIIn, int nWidth, int nHeight, float fXRes, float fYRes, float fRes)

ZMap 与亮度数据 X、Y 方向等距重采样。

参数 方向 说明
pfZOut out 重采样后 3D 数据内存指针
pfZIn in 原始 3D 数据内存指针
pIOut out 重采样后亮度数据内存指针
pIIn in 原始亮度数据内存指针
nWidth in 重采样前 X 方向数据点数
nHeight in 重采样前 Y 方向数据点数
fXRes in X 方向精度，单位：mm
fYRes in Y 方向精度，单位：mm
fRes in 重采样精度，单位：mm

返回：成功返回 KSJXS_RET_SUCCESS

说明

  • 输出内存需提前分配，大小由 KSJXS_GetZMapUniformXYSize 计算。