API 详解 (Python)

ListDevice

该接口用于枚举与电脑连接的所有相机，示例如下：

dev_list = cl.ListDevice()

Open

该接口用于打开指定 SN 号的相机，示例如下：

handle =cl.Open("207000145055")
# 207000145055 为相机 SN 号。

OpenDeviceByIP

该接口用于打开指定 IP 的相机，示例如下：

handle =cl.OpenDeviceByIP("192.168.6.85")
# 192.168.6.85 为相机 IP 地址。

Close

该接口用于关闭相机，示例如下：

cl.Close(handle)

DeviceStreamEnable

该接口用于使能数据流。使能 Color 和 Depth 数据流的示例如下：

cl.DeviceStreamEnable(handle, PERCIPIO_STREAM_COLOR | PERCIPIO_STREAM_DEPTH)

DeviceStreamFormatDump

该接口用于列举数据流的分辨率和图像格式。以 Color 数据流为例，示例如下：

color_fmt_list = cl.DeviceStreamFormatDump(handle, PERCIPIO_STREAM_COLOR)

DeviceStreamFormatConfig

该接口用于配置数据流的分辨率，与 DeviceStreamFormatDump 联合使用，示例如下：

color_fmt_list = cl.DeviceStreamFormatDump(handle, PERCIPIO_STREAM_COLOR)
cl.DeviceStreamFormatConfig(handle, PERCIPIO_STREAM_COLOR, color_fmt_list[0])
# 0 表示配置列表中的第一个分辨率。

DeviceReadCurrentEnumData

该接口用于读取当前数据流所用的分辨率，以 Color 数据流为例，示例如下：

color_enum_desc = TY_ENUM_ENTRY()
cl.DeviceReadCurrentEnumData(handle, PERCIPIO_STREAM_COLOR, color_enum_desc)
print('current color image mode  {}x{}-{}'.format(cl.Width(color_enum_desc), cl.Height(color_enum_desc),color_enum_desc.getDesc()))

DeviceReadCalibData

该接口用于读取数据流的标定参数，以 Color 数据流为例，示例如下：

color_calib_data   = cl.DeviceReadCalibData(handle, PERCIPIO_STREAM_COLOR)
color_calib_width  = color_calib_data.Width()
color_calib_height = color_calib_data.Height()
color_calib_intr   = color_calib_data.Intrinsic()
color_calib_extr   = color_calib_data.Extrinsic()
color_calib_dis    = color_calib_data.Distortion()

DeviceStreamOn

开启数据流，示例如下：

cl.DeviceStreamOn(handle)

DeviceStreamOff

关闭数据流，示例如下：

cl.DeviceStreamOff(handle)

DeviceStreamRead

读取相机的传送的数据，示例如下：

image_list = cl.DeviceStreamRead(handle, -1)

DeviceStreamDepthRender

该接口用于解析和渲染 Depth 图，示例如下：

depth_render = image_data()
if frame.streamID == PERCIPIO_STREAM_DEPTH:
cl.DeviceStreamDepthRender(frame, depth_render)
arr = depth_render.as_nparray()
cv2.imshow('depth',arr)

DeviceStreamImageDecode

该接口用于解析 Color 图，示例如下：

rgb_image = image_data()
if frame.streamID == PERCIPIO_STREAM_COLOR:
cl.DeviceStreamImageDecode(frame, rgb_image)
arr = rgb_image.as_nparray()
cv2.imshow('color',arr)

DeviceStreamIRRender

该接口用于解析 IR 图像，示例如下：

img_ir = image_data()
if frame.streamID == PERCIPIO_STREAM_IR_LEFT:
cl.DeviceStreamIRRender(frame, img_ir)
arr = img_ir.as_nparray()
cv2.imshow('leftir',arr)

DeviceControlLaserPowerAutoControlEnable

该接口用于使能/失能 TY_BOOL_LASER_AUTO_CTRL 属性。用于需要分析 IR 散斑图时，点亮激光器。示例如下：

cl.DeviceControlLaserPowerAutoControlEnable(handle, False)

DeviceControlLaserPowerConfig

该接口用于调整激光器亮度，示例如下：

cl.DeviceControlLaserPowerConfig(handle, 80)

DeviceColorStreamIspEnable

该接口用于打开/关闭软件 ISP，示例如下：

cl.DeviceColorStreamIspEnable(handle, True)

DeviceStreamMapDepthImageToColorCoordinate

该接口用于将 Depth 图对齐到 Color 图。示例如下，可参考 fetch_registration.py：

cl.DeviceStreamMapDepthImageToColorCoordinate(depth_calib.data(), img_depth.width, img_depth.height, scale_unit,  img_depth,  color_calib.data(), img_color.width, img_color.height, img_registration_depth)

DeviceStreamDoUndistortion

该接口用于对 Color 图做畸变校正。示例如下，可参考 fetch_registration.py：

cl.DeviceStreamDoUndistortion(color_calib.data(), img_parsed_color, img_undistortion_color)

DeviceControlTriggerModeEnable

该接口用于设置相机的工作模式，0 代表 TY_TRIGGER_MODE_OFF，1 代表 TY_TRIGGER_MODE_SLAVE。示例如下：

cl.DeviceControlTriggerModeEnable(handle, 1)

DeviceControlTriggerModeSendTriggerSignal

该接口用于给相机发送软触发命令，示例如下：

cl.DeviceControlTriggerModeSendTriggerSignal(handle)

DeviceStreamMapDepthImageToPoint3D

该接口用于将 Depth 图转换成点云数据。示例如下，可参考 fetch_point3d.py：

cl.DeviceStreamMapDepthImageToPoint3D(frame, depth_calib_data, scale_unit, pointcloud_data_arr)

DevParamFrom

DevParamFromInt 接口用于定义 Int、Enum 型的变量，示例如下：

Int型

param =  cl.DevParamFromInt(4096)

Enum型

param =  cl.DevParamFromInt(TY_DEPTH_QUALITY_BASIC)

DevParamFromBool 接口用于定义 Bool 型变量，用于设置 Bool 类型的属性，示例如下：
```
param =  cl.DevParamFromBool(True)
```
DevParamFromFloat 接口用于定义 Float 型变量，用于设置 Float 类型的属性，示例如下：
```
param =  cl.DevParamFromFloat(1)
```

DeviceSetParameter/DeviceGetParameter

DeviceSetParameter 接口用于设置相机参数，可以设置 Int、Enum、Bool、Float、ByteArray 型参数。

DeviceGetParameter 接口用于读取相机参数，可以读取 Int、Enum、Bool、Float、ByteArray 型参数。

DeviceSetParameter 与 DeviceGetParameter 的示例代码如下：

Int 型

para =cl.DevParamFromInt(100)
cl.DeviceSetParameter(handle,TY_COMPONENT_IR_CAM_LEFT,TY_INT_EXPOSURE_TIME,para)
value = cl.DeviceGetParameter(handle,TY_COMPONENT_IR_CAM_LEFT,TY_INT_EXPOSURE_TIME)
m_value = value.toInt()
value_min = value.mMin()
value_max = value.mMax()
value_inc = value.mInc()
print('min {} max {} inc {} cunrrent {}'.format(value_min,value_max,value_inc,m_value))

Enum 型

para =cl.DevParamFromInt(TY_DEPTH_QUALITY_BASIC)
cl.DeviceSetParameter(handle,TY_COMPONENT_DEPTH_CAM,TY_ENUM_DEPTH_QUALITY,para)
value = cl.DeviceGetParameter(handle,TY_COMPONENT_DEPTH_CAM,TY_ENUM_DEPTH_QUALITY)
m_value = value.toInt()
value_list = value.eList()
for i in range (len(value_list)):
print(' {}'.format(value_list[i].value))

Bool 型

param = cl.DevParamFromBool(False)
cl.DeviceSetParameter(handle, TY_COMPONENT_RGB_CAM, TY_BOOL_AUTO_EXPOSURE, param)
status =cl.DeviceGetParameter(handle, TY_COMPONENT_RGB_CAM, TY_BOOL_AUTO_EXPOSURE)
m_status=status.toBool()

Float 型

para =cl.DevParamFromFloat(1)
cl.DeviceSetParameter(handle,TY_COMPONENT_DEPTH_CAM,TY_FLOAT_SCALE_UNIT,para)
value = cl.DeviceGetParameter(handle,TY_COMPONENT_DEPTH_CAM,TY_FLOAT_SCALE_UNIT)
m_value = value.toFloat()
value_min = value.fMin()
value_max = value.fMax()
value_inc = value.fInc()
print('min {} max {} inc {} cunrrent {}'.format(value_min,value_max,value_inc,m_value))

ByteArray 型

para_array = cl.DevParamFromByteArray([2, 0, 0, 0, 2, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 8, 0, 0, 0, 31, 0, 0, 0])
cl.DeviceSetParameter(handle,TY_COMPONENT_IR_CAM_LEFT,TY_BYTEARRAY_HDR_PARAMETER,para_array)
hdr_array =cl.DeviceGetParameter(handle,TY_COMPONENT_IR_CAM_LEFT,TY_BYTEARRAY_HDR_PARAMETER)
hdr_array_1 =hdr_array.toByteArray()
for i in range (len(hdr_array_1)):
print(',',hdr_array_1[i],end='')

Struct(roi)型

roi = PercipioAecROI(0,0,640,480)
param =cl.DevParamFromPercipioAecROI(roi)
cl.DeviceSetParameter(handle, TY_COMPONENT_RGB_CAM, TY_STRUCT_AEC_ROI, param)
read_param = cl.DeviceGetParameter(handle, TY_COMPONENT_RGB_CAM, TY_STRUCT_AEC_ROI)
m_read_param=read_param.toArray()
print('aec roi',m_read_param)

get_netinfo

该接口可用于获取打开的网络相机的设备信息，如 IP、MAC、Netmask、Gateway。

IP 的获取示例如下：

sn = dev_list[selected_idx].id
handle = cl.Open(sn)
print('device_ip :{}'.format(dev_list[selected_idx].get_netinfo().ip()))

DeviceLoadDefaultParameters

该接口用于加载相机的配置文件（custom_block.bin 文件中保存了相机参数）。

err = cl.DeviceLoadDefaultParameters(handle)
    if err:
      print('Load default parameters fail: ', end='')
      print(cl.TYGetLastErrorCodedescription())
    else:
       print('Load default parameters successful')

支持加载的参数类型有 Int、Float、Enum、Bool、ByteArray。

DeviceHasStream

该接口用于判断相机是否具有特定的数据流，返回值为 Bool 型。

示例：判断相机是否具有 Color 数据流。

err = cl.DeviceHasStream(handle,PERCIPIO_STREAM_COLOR)