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

KSJXS SDK · ROI 与测量量程

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

视场（ROI）读写、ROI 上限，以及由 ROI 决定的 Z 量程与 X 视野。

本组对应头文件 @defgroup ROI。ROI 以原始图像左上角为原点，决定 X 方向测量区间与 Z 方向量程。

⚠️ 务必先调用 KSJXS_SetDataFormat 再调用 KSJXS_GetRoi。

KSJXS_GetRoiMax

int KSJXS_GetRoiMax(IN void* handle, int* pnColMax, int* pnRowMax)

获取 ROI 可设置的最大范围。

参数 方向 说明
pnColMax out 行宽（列）最大设置范围，单位：像素
pnRowMax out 行高（行）最大设置范围，单位：像素

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

KSJXS_SetRoi

int KSJXS_SetRoi(IN void* handle, int nColStart, int nRowStart, int nColSize, int nRowSize)

设置视场范围（ROI）。

参数 方向 说明
nColStart in 列起始：水平像素起始位置，主要决定 X 方向测量起始位置
nRowStart in 行起始：垂直行起始位置，主要决定 Z 方向测量量程的最大值
nColSize in 列宽：水平像素数，决定 X 方向测量量程
nRowSize in 行高：垂直像素数，决定 Z 方向测量量程

返回：成功返回 KSJXS_RET_SUCCESS

说明

  • 采集启动后 ROI 不可修改，需先停止采集。

KSJXS_GetRoi

int KSJXS_GetRoi(IN void* handle, int* pnColStart, int* pnRowStart, int* pnColSize, int* pnRowSize)

获取当前视场范围（ROI）。

参数 方向 说明
pnColStart out 列起始位置，单位：像素
pnRowStart out 行起始位置，单位：像素
pnColSize out 列宽（像素数）
pnRowSize out 行高（像素数）

返回：成功返回 KSJXS_RET_SUCCESS

说明

  • ⚠️ 必须在 KSJXS_SetDataFormat 之后调用，否则数据未定义。

KSJXS_GetMeasurementRangeMax

int KSJXS_GetMeasurementRangeMax(IN void* handle, float* pfZ, float* pfFovNear, float* pfFovFar)

获取设备可达到的最大测量范围。

参数 方向 说明
pfZ out Z 方向高度测量范围，单位：mm
pfFovNear out X 方向近端视野，单位：mm
pfFovFar out X 方向远端视野，单位：mm

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

KSJXS_GetMeasurementRange

int KSJXS_GetMeasurementRange(IN void* handle, float* pfZMin, float* pfZMax, float* pfFovNear, float* pfFovFar)

获取当前 ROI 设置下的测量范围。

参数 方向 说明
pfZMin out Z 方向相对零点的最小测量位置，单位：mm
pfZMax out Z 方向相对零点的最大测量位置，单位：mm
pfFovNear out X 方向近端视野，单位：mm
pfFovFar out X 方向远端视野，单位：mm

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