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

KSJAPI SDK · 采集与数据获取

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

主动采集原始/彩色数据、清帧存采集、16 位数据、超时与主动结束、流模式、图像存盘。

本组接口来自 KSJApiBase.h、KSJApi16Bits.h、KSJApiTriggerMode.h、KSJApiStream.h、KSJApiCustom.h。

KSJ_Capture* 系列是阻塞调用：无图像返回时会一直等到超时（超时时间由 KSJ_CaptureSetTimeOut 设定）。
调用前应先通过 KSJ_CaptureGetSizeEx 取得图像尺寸，并为缓冲区分配 宽 × 高 × 位深 / 8 字节。

函数一览

函数 说明
KSJ_CaptureRawData 采集一帧原始或黑白图像数据（单通道）。
KSJ_CaptureRgbData 采集一帧 8 位原始/灰度或 24/32 位彩色数据。
KSJ_CaptureRgbDataEx 采集一帧图像，同时返回实际宽高与位深。
KSJ_CaptureRawDataAfterEmptyFrameBuffer 清空帧存后采集一帧原始/黑白图像（保证拿到的是最新帧）。
KSJ_CaptureRgbDataAfterEmptyFrameBuffer 清空帧存后采集一帧彩色/灰度图像。
KSJ_CaptureRgbDataExAfterEmptyFrameBuffer 清空帧存后采集一帧图像并返回宽高位深。
KSJ_SendPktEnd 主动结束当前传输请求，使正在阻塞的 Capture 立即返回。
KSJ_CaptureSetTimeOut 设置采集图像的超时时间（单位：毫秒）。
KSJ_CaptureGetTimeOut 获取读取一帧图像的超时时间（毫秒）。
KSJ_GetADCResolution 获取图像传感器的 ADC 转换精度（比特位数，如 8/10/12）。
KSJ_SetData16Bits 设置相机是否以 16bit 方式传输数据。
KSJ_GetData16Bits 获取相机是否以 16bit 原始数据传输。
KSJ_IsSupportStreamMode 查看相机是否支持流模式。
KSJ_StreamIsStart 查看相机是否已开启流模式。
KSJ_StreamStart 开启流模式。
KSJ_StreamStop 关闭流模式。
KSJ_HelperSaveToBmp 将图像数据保存为 BMP 文件。
KSJ_HelperSaveToJpg 将图像数据保存为 JPG 文件（nQulity 为图像质量）。
KSJ_HelperSaveToTiff 将图像保存为 Tiff 格式。

关键函数详解

KSJ_CaptureRawData

int __stdcall KSJ_CaptureRawData(int nIndex, unsigned char* pRawData);

采集一帧原始或黑白图像数据（单通道）。

返回：成功返回 RET_SUCCESS(1)；超时/帧错误返回对应负值

说明

  • pRawData 须由调用者提前分配，大小为 宽 × 高；若为 16bit 数据则应再 ×2。

KSJ_CaptureRgbData

int __stdcall KSJ_CaptureRgbData(int nIndex, unsigned char* pRgbData);

采集一帧 8 位原始/灰度或 24/32 位彩色数据。

返回：成功返回 RET_SUCCESS(1)

说明

  • pRgbData 大小应为 宽 × 高 × 位深 / 8（位深由 KSJ_CaptureGetSizeEx 取得）。
  • 黑白相机取回的即原始灰度图，与 KSJ_CaptureRawData 结果一致。

KSJ_SendPktEnd

int __stdcall KSJ_SendPktEnd(int nIndex);

主动结束当前传输请求，使正在阻塞的 Capture 立即返回。

返回：成功返回 RET_SUCCESS(1)

说明

  • 长时间没有图像返回（如外触发下无触发信号）时可用本函数结束采集。
  • Capture 会立即返回零帧 RET_ZEROFRAME 或半帧 RET_INVALIDFRAME。
  • 若当前没有执行采集时调用，则下一次采集会得到一个零帧 RET_ZEROFRAME。

KSJ_CaptureSetTimeOut

int __stdcall KSJ_CaptureSetTimeOut(int nIndex, unsigned long dwTimeOut);

设置采集图像的超时时间（单位：毫秒）。

返回：成功返回 RET_SUCCESS(1)

说明

  • 外触发模式下，该时间最好大于外触发信号可能的最大间隔。

KSJ_SetData16Bits

int __stdcall KSJ_SetData16Bits(int nIndex, bool bEnable);

设置相机是否以 16bit 方式传输数据。

返回：成功返回 RET_SUCCESS(1)

说明

  • 相机以 10bit 或 12bit 采样时，转 16bit 传输为高位补 0、低位有效。

KSJ_HelperSaveToBmp

int __stdcall KSJ_HelperSaveToBmp(unsigned char* pData, int nWidth, int nHeight, int nBitCount, const TCHAR* pszFileName);

将图像数据保存为 BMP 文件。

参数 方向 说明
pData in 图像数据首地址
nWidth / nHeight in 图像宽高（像素）
nBitCount in 8 = 灰度，24 = 24 位彩色（其他不支持）
pszFileName in 保存文件全路径（所在目录须已存在）

返回：成功返回 RET_SUCCESS(1)

说明

  • 可在任意时刻调用。

KSJ_HelperSaveToTiff

int __stdcall KSJ_HelperSaveToTiff(unsigned char* pData, int nWidth, int nHeight, int nBitPerSample, int nSamplesPerPixel, const TCHAR* pszFileName);

将图像保存为 Tiff 格式。

返回：成功返回 RET_SUCCESS(1)

说明

  • nSamplesPerPixel = 1 / 3 / 4，分别对应 BitCount = 8 / 24 / 32。