API Descriptions (Python)

ListDevice

List all cameras connected to the computer. An example is as follows:

dev_list = cl.ListDevice()

Open

Open a camera with a specified serial number (SN). An example is as follows:

handle = cl.Open("207000145055")
# 207000145055 is the camera serial number (SN).

OpenDeviceByIP

Open a camera with a specified IP address. An example is as follows:

handle = cl.OpenDeviceByIP("192.168.6.85")
# 192.168.6.85 is the camera IP address.

Close

Close the camera. An example is as follows:

cl.Close(handle)

DeviceStreamEnable

Enable the data streams. The following provides an example of enabling both the color and depth data streams:

cl.DeviceStreamEnable(handle, PERCIPIO_STREAM_COLOR | PERCIPIO_STREAM_DEPTH)

DeviceStreamFormatDump

List the supported resolutions and image formats for a specified data stream. The following provides an example using the color data stream:

color_fmt_list = cl.DeviceStreamFormatDump(handle, PERCIPIO_STREAM_COLOR)

DeviceStreamFormatConfig

Configure the resolution of a specified data stream. This API can be used in conjunction with DeviceStreamFormatDump. An example is as follows:

color_fmt_list = cl.DeviceStreamFormatDump(handle, PERCIPIO_STREAM_COLOR)
cl.DeviceStreamFormatConfig(handle, PERCIPIO_STREAM_COLOR, color_fmt_list[0])
# 0 represents the first resolution in the configuration list.

DeviceReadCurrentEnumData

Get the resolution of the current data stream. The following provides an example using the color data stream:

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

Get the calibration parameters of a specified data stream. The following provides an example using the color data stream:

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

Start camera data streaming. An example is as follows:

cl.DeviceStreamOn(handle)

DeviceStreamOff

Stop camera data streaming. An example is as follows:

cl.DeviceStreamOff(handle)

DeviceStreamRead

Read the data transmitted from the camera. An example is as follows:

image_list = cl.DeviceStreamRead(handle, -1)

DeviceStreamDepthRender

Parse and render the depth image. An example is as follows:

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

Parse the color image. An example is as follows:

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

Parse IR images. An example is as follows:

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

Enable or disable the TY_BOOL_LASER_AUTO_CTRL feature. It is used to activate the laser when analyzing IR speckle patterns. An example is as follows:

cl.DeviceControlLaserPowerAutoControlEnable(handle, False)

DeviceControlLaserPowerConfig

Adjust the laser power. An example is as follows:

cl.DeviceControlLaserPowerConfig(handle, 80)

DeviceColorStreamIspEnable

Enable or disable software ISP function. An example is as follows:

cl.DeviceColorStreamIspEnable(handle, True)

DeviceStreamMapDepthImageToColorCoordinate

Map the depth image to the color image coordinates. An example is as follows. For more details, you can refer to fetch_registration.py.

cl.DeviceStreamMapDepthImageToColorCoordinate(depth_calib,depth,scale_unit,color_calib,undistortion_color.width,undistortion_color.height,registration_depth);

DeviceStreamMapRGBImageToDepthCoordinate

Map the color image to the depth image coordinates. An example is as follows:

cl.DeviceStreamMapRGBImageToDepthCoordinate(depth_calib, img_depth, scale_unit, color_calib,img_undistortion_color, img_registration_color)

DeviceStreamDoUndistortion

Perform undistortion for the color image. An example is as follows. For more details, you can refer to fetch_registration.py.

cl.DeviceStreamDoUndistortion(color_calib, color, undistortion_color)

DeviceControlTriggerModeEnable

Set the camera work mode. 0 represents TY_TRIGGER_MODE_OFF, and 1 represents TY_TRIGGER_MODE_SLAVE. An example is as follows:

cl.DeviceControlTriggerModeEnable(handle, 1)

DeviceControlTriggerModeSendTriggerSignal

Send a software trigger command to the camera. An example is as follows:

cl.DeviceControlTriggerModeSendTriggerSignal(handle)

DeviceStreamMapDepthImageToPoint3D

Convert the depth image to point cloud data. An example is as follows. For more details, you can refer to fetch_point3d.py.

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

DevParamFrom

DevParamFromInt is used to define an Int type variable for setting features of the Int type. An example is as follows:

param =  cl.DevParamFromInt(4096)

DevParamFromEnum is used to define an Enum type variable for setting features of the Enum type. An example is as follows:

param =  cl.DevParamFromEnum(TY_DEPTH_QUALITY_BASIC)

DevParamFromBool is used to define a Bool type variable for setting features of the Bool type. An example is as follows:
```
param =  cl.DevParamFromBool(True)
```
DevParamFromFloat is used to define a Float type variable for setting features of the Float type. An example is as follows:
```
param =  cl.DevParamFromFloat(1)
```

DeviceSetParameter/DeviceGetParameter

DeviceSetParameter is used to set camera parameters. The supported data types include Int, Enum, Bool, Float, and ByteArray.

DeviceGetParameter is used to get camera parameters. The supported data types include Int, Enum, Bool, Float, and ByteArray.

Examples of DeviceSetParameter and DeviceGetParameter are provided below:

Int type

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 type

para =cl.DevParamFromEnum(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 type

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 type

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 type

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) type

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

Obtain the device information of an active network depth camera, such as IP, MAC, Netmask, and Gateway. An example of obtaining the IP address is provided below:

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

DeviceWriteDefaultParametersFromJSFile

Write the parameters saved in a local JSON file to the camera’s custom_block.bin storage area. An example is as follows:

from pathlib import Path
file_path = Path("C:/Users/G/Desktop/1.json")
cl.DeviceWriteDefaultParametersFromJSFile(handle,str(file_path))

DeviceLoadDefaultParameters

Load camera parameter configurations from the custom_block.bin storage area if available. An example is as follows:

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

The supported parameter types for loading include Int, Float, Enum, Bool, and ByteArray.

DeviceClearDefaultParameters

Clear camera parameter configurations stored in the custom_block.bin storage area. An example is as follows:

err = cl.DeviceClearDefaultParameters(handle)
print('DeviceClearDefaultParameters {}'.format(err))

DeviceHasStream

Determine whether the camera has a specific data stream, returning a bool type. The following provides an example of checking if the camera has the color data stream:

err = cl.DeviceHasStream(handle,PERCIPIO_STREAM_COLOR)