API Descriptions (C#)

This section introduces the basic concepts and usage methods of the C# APIs. For details on how to set camera features using the APIs, please refer to .

ListDevice

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

DeviceInfoVector dev_list= cl.ListDevice();

Open

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

System.IntPtr 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:

System.IntPtr 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:

EnumEntryVector 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:

EnumEntryVector 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:

TY_ENUM_ENTRY color_enum_desc = new TY_ENUM_ENTRY();
cl.DeviceReadCurrentEnumData(handle, PERCIPIO_STREAM_COLOR, color_enum_desc);
Console.WriteLine($"current color image mode{cl.Width(color_enum_desc)} x {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:

PercipioCalibData color_calib_data   = cl.DeviceReadCalibData(handle, PERCIPIO_STREAM_COLOR);
int color_calib_width  = color_calib_data.Width();
int color_calib_height = color_calib_data.Height();
CalibDataVector color_calib_intr   = color_calib_data.Intrinsic();
CalibDataVector color_calib_extr   = color_calib_data.Extrinsic();
CalibDataVector 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:

FrameVector frames = cl.DeviceStreamRead(handle, 5000);

DeviceStreamDepthRender

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

image_data depth = new image_data();
cl.DeviceStreamDepthRender(frames[i], depth);
IntPtr pt = depth.buffer.getCPtr();
Bitmap bmp_depth = new Bitmap(depth.width, depth.height, depth.width * 3, PixelFormat.Format24bppRgb, pt);
pictureBox1.Image = (Image)(new Bitmap(bmp_depth, new Size(640, 480))).Clone();

DeviceStreamImageDecode

Parse the color image. An example is as follows:

image_data bgr = new image_data();
cl.DeviceStreamImageDecode(frames[i], bgr);
IntPtr pt = bgr.buffer.getCPtr();
Bitmap bmp_color = new Bitmap(bgr.width, bgr.height, bgr.width * 3, PixelFormat.Format24bppRgb, pt);
pictureBox2.Image = (Image)(new Bitmap(bmp_color, new Size(640, 480))).Clone();

DeviceStreamIRRender

Parse IR images. An example is as follows:

image_data rightIR = new image_data();
cl.DeviceStreamIRRender(frames[i], rightIR);
IntPtr pt = rightIR.buffer.getCPtr();
Bitmap rightIR_BMP = new Bitmap(rightIR.width, rightIR.height, 3*rightIR.width, PixelFormat.Format24bppRgb, pt);
pictureBox2.Image = (Image)(new Bitmap(rightIR_BMP, new Size(640, 480))).Clone();

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 map to the color image coordinates. An example is as follows. For more details, you can refer to fetch_registration.cs.

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

DeviceStreamMapRGBImageToDepthCoordinate

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

cl.DeviceStreamMapRGBImageToDepthCoordinate(depth_calib,depth,scale_unit,color_calib, undsitortion_color,registration_color);

DeviceStreamDoUndistortion

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

cl.DeviceStreamDoUndistortion(color_calib.data(), color, undsitortion_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 map to point cloud data. An example is as follows. For more details, you can refer to fetch_point3d.cs.

cl.DeviceStreamMapDepthImageToPoint3D(image, depth_calib_data, f_depth_scale, p3d_list);

DevParamFrom

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

DevParam 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:

DevParam 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:
```
DevParam 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:
```
DevParam 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

DevParam param = cl.DevParamFromInt(1088);
cl.DeviceSetParameter(handle, TY_COMPONENT_RGB_CAM, TY_INT_EXPOSURE_TIME, param);
DevParam read_param = cl.DeviceGetParameter(handle, TY_COMPONENT_RGB_CAM, TY_INT_EXPOSURE_TIME);
int m_read_param = read_param.toInt();
Console.WriteLine($"current value {m_read_param}");
int min = read_param.mMin();
int max = read_param.mMax();
int inc = read_param.mInc();
Console.WriteLine($"min: {min},max: {max},inc: {inc}");

Enum type

DevParam param = cl.DevParamFromEnum(TY_TIME_SYNC_TYPE_HOST);
cl.DeviceSetParameter(handle, TY_COMPONENT_DEVICE, TY_ENUM_TIME_SYNC_TYPE, param);
DevParam read_param = cl.DeviceGetParameter(handle, TY_COMPONENT_DEVICE, TY_ENUM_TIME_SYNC_TYPE);
uint m_read_param = read_param.toEnum();
Console.WriteLine($"current value {m_read_param}");
EnumEntryVector m_read_param2 = read_param.eList();
for (int i = 0; i < m_read_param2.Count(); i++){
        Console.WriteLine($"{ m_read_param2[i].value}");
}

Bool type

DevParam param = cl.DevParamFromBool(false);
cl.DeviceSetParameter(handle, TY_COMPONENT_RGB_CAM, TY_BOOL_AUTO_EXPOSURE, param);
DevParam status = cl.DeviceGetParameter(handle, TY_COMPONENT_RGB_CAM, TY_BOOL_AUTO_EXPOSURE);
bool m_status = status.toBool();
Console.WriteLine($"current value {m_status}");

Float type

DevParam param = cl.DevParamFromFloat(0.0125f);
cl.DeviceSetParameter(handle, TY_COMPONENT_DEPTH_CAM, TY_FLOAT_SCALE_UNIT, param);
DevParam read_param = cl.DeviceGetParameter(handle, TY_COMPONENT_DEPTH_CAM, TY_FLOAT_SCALE_UNIT);
float m_read_param = read_param.toFloat();
Console.WriteLine($"current value {m_read_param}");
float min = read_param.fMin();
float max = read_param.fMax();
float inc = read_param.fInc();
Console.WriteLine($"min: {min},max: {max},inc: {inc}");

ByteArray type

ByteArrayVector array = new ByteArrayVector { 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 11, 0, 0, 0, 14, 0, 0, 0 };
DevParam arr = cl.DevParamFromByteArray(array);
cl.DeviceSetParameter(handle, TY_COMPONENT_IR_CAM_LEFT, TY_BYTEARRAY_HDR_PARAMETER,arr);
DevParam hdr_arry = cl.DeviceGetParameter(handle, TY_COMPONENT_IR_CAM_LEFT, TY_BYTEARRAY_HDR_PARAMETER);
ByteArrayVector hdr_arry_1 = hdr_arry.toByteArray();
for (int i = 0; i < hdr_arry_1.Count(); i++)
   {
     Console.Write($",{hdr_arry_1[i]}");
}

Struct (roi) type

PercipioAecROI roi = new PercipioAecROI(0, 0, 640, 480);
DevParam param = cl.DevParamFromPercipioAecROI(roi);
cl.DeviceSetParameter(handle, TY_COMPONENT_RGB_CAM, TY_STRUCT_AEC_ROI, param);
DevParam readParam = cl.DeviceGetParameter(handle, TY_COMPONENT_RGB_CAM, TY_STRUCT_AEC_ROI);
ArrayVector mReadParam = readParam.toArray();
Console.WriteLine("aec roi: " + string.Join(",", mReadParam));

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:

handle = cl.Open(dev_list[select].id);
Console.WriteLine("ip {0}", dev_list[select].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:

string filePath = @"C:\Users\G\Desktop\1.json";
cl.DeviceWriteDefaultParametersFromJSFile(handle, filePath);

DeviceLoadDefaultParameters

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

int err = cl.DeviceLoadDefaultParameters(handle);
   if (err != TY_STATUS_OK)
      Console.WriteLine(string.Format("Load default parameters fail: {0}!", err));
   else
      Console.WriteLine(string.Format("Load default parameters successful!"));

The supported parameter types 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:

cl.DeviceClearDefaultParameters(handle);

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 right IR data stream:

bool has_stream = false;
has_stream = cl.DeviceHasStream(handle, PERCIPIO_STREAM_IR_RIGHT);
Console.WriteLine($"has right ir {has_stream}");

DeviceReadRectifiedRotationData

Retrieve the IR rotation parameter. An example is as follows:

PercipioRectifyRotaData LEFTIR_rot_data = cl.DeviceReadRectifiedRotationData(handle, PERCIPIO_STREAM_IR_LEFT);
CalibDataVector LEFTIR_r_data = LEFTIR_rot_data.Data();
Console.WriteLine(string.Format(":IR_rot_data"));
dump_calib_data(LEFTIR_r_data, 3, 3);

DeviceReadRectifiedIntrData

Retrieve the IR rectified intrinsic parameter. An example is as follows:

PercipioRectifyIntrData LEFTIR_int_data = cl.DeviceReadRectifiedIntrData(handle, PERCIPIO_STREAM_IR_LEFT);
CalibDataVector LEFTIR_i_data = LEFTIR_int_data.Data();
Console.WriteLine(string.Format(":IR_ntrinsic _data"));
dump_calib_data(LEFTIR_i_data, 3, 3);

DeviceControlReadTemperature

Read the temperature value of the temperature sensors inside the camera. An example is as follows:

DevParam param5 = cl.DevParamFromEnum(TY_TEMPERATURE_LEFT);
int error5 = cl.DeviceSetParameter(handle, TY_COMPONENT_DEVICE, TY_ENUM_TEMPERATURE_ID, param5);
DevParam read_param5 = cl.DeviceGetParameter(handle, TY_COMPONENT_DEVICE, TY_ENUM_TEMPERATURE_ID);
uint m_read_param5 = read_param5.toEnum();
Console.WriteLine($"current value {m_read_param5}");
EnumEntryVector l_read_param5 = read_param5.eList();
for (int i = 0; i < l_read_param5.Count(); i++)
{
   float tmp= cl.DeviceControlReadTemperature(handle, l_read_param5[i].value);
   Console.WriteLine(string.Format("{0}={1}",l_read_param5[i].description,tmp));
}