Feature Descriptions (Gige_2_0 Camera)

Features Under the Device Component

TY_TRIGGER_PARAM_EX

Percipio cameras support multiple operating mode configurations:

  • TY_TRIGGER_MODE_OFF: Free-run acquisition mode

  • TY_TRIGGER_MODE_SLAVE: Software/Hardware trigger mode

  • TY_TRIGGER_MODE_M_SIG: Upon receiving a software trigger signal, the camera triggers itself and simultaneously outputs a signal on the Output pin to trigger slave devices.

  • TY_TRIGGER_MODE_M_PER: The camera triggers at a specified frame rate and simultaneously outputs a signal on the Output pin to trigger slave devices.

Lifecycle: start-stop

Configuration Method:

  • Configuration for TY_TRIGGER_MODE_OFF, TY_TRIGGER_MODE_SLAVE, and TY_TRIGGER_MODE_M_SIG is as follows:

    TY_TRIGGER_PARAM_EX trigger;
trigger.mode = TY_TRIGGER_MODE_OFF; // Configure according to the required operating mode
ASSERT_OK(TYSetStruct(hDevice, TY_COMPONENT_DEVICE, TY_STRUCT_TRIGGER_PARAM_EX, &trigger, sizeof(trigger)));

  • Configuration for TY_TRIGGER_MODE_M_PER is as follows:

    TY_TRIGGER_PARAM_EX param;
param.mode = TY_TRIGGER_MODE_M_PER;
param.fps = 5;
ASSERT_OK(TYSetStruct(cams[count].hDev, TY_COMPONENT_DEVICE, TY_STRUCT_TRIGGER_PARAM_EX, (void*)&param, sizeof(param)));

Note

Firmware version must be greater than 3.13.68 for TY_TRIGGER_MODE_M_SIG and TY_TRIGGER_MODE_M_PER modes. Otherwise, use TY_TRIGGER_PARAM for configuration.

TY_INT_FRAME_PER_TRIGGER

This feature sets the number of frames output by the camera upon receiving a single software/hardware trigger signal. By default, the camera outputs one frame per trigger.

Configuration Method

// Output 2 frames per trigger signal
int32_t value = 2;
ASSERT_OK(TYSetInt(hDevice, TY_COMPONENT_DEVICE, TY_INT_FRAME_PER_TRIGGER, value));

Lifecycle: open-close

TY_INT_PACKET_DELAY

This feature sets the delay between data packet transmissions. It is suitable for scenarios with poor network conditions, effectively improving transmission stability.

Configuration Method

int32_t value = 10000;
ASSERT_OK(TYSetInt(hDevice, TY_COMPONENT_DEVICE, TY_INT_PACKET_DELAY, value));

Adjusting Notes:

A higher TY_INT_PACKET_DELAY value results in a lower camera frame rate.

Lifecycle: Effective after configuration until power cycle or reconfiguration of other parameters.

TY_INT_PACKET_SIZE

This feature sets the size of camera data packets, used in suboptimal network environments.

Configuration Method

int32_t value = 100;
ASSERT_OK(TYSetInt(hDevice, TY_COMPONENT_DEVICE, TY_INT_PACKET_SIZE, value));

Adjusting Notes:

A smaller TY_INT_PACKET_SIZE value results in a lower camera frame rate.

Lifecycle: Effective after configuration until power cycle or reconfiguration of other parameters.

TY_BOOL_GVSP_RESEND

This feature enables network camera image retransmission.

Configuration Method

ASSERT_OK(TYSetBool(hDevice, TY_COMPONENT_DEVICE, TY_BOOL_GVSP_RESEND, true));

Adjusting Notes:

Network cameras default to having image retransmission disabled (false). Enabling retransmission effectively reduces the probability of the host failing to acquire images.

Lifecycle: init-deinit

TY_BOOL_TRIGGER_OUT_IO

This feature inverts the output level of trigger_out. It is writable but not readable.

Configuration Method

ASSERT_OK(TYSetBool(hDevice, TY_COMPONENT_DEVICE, TY_BOOL_TRIGGER_OUT_IO, false));

Adjusting Notes:

After powering the trigger circuit, observe the output signal on the camera’s Trigger_out pin using an oscilloscope.

  • TY_BOOL_TRIGGER_OUT_IO = true: Level is inverted.

  • TY_BOOL_TRIGGER_OUT_IO = false: Level is not inverted.

Lifecycle: start-stop

TY_BOOL_KEEP_ALIVE_ONOFF

This feature enables the keep-alive communication mechanism between the SDK and the camera. The default is true (keep-alive enabled).

Configuration Method

ASSERT_OK(TYSetBool(hDevice, TY_COMPONENT_DEVICE, TY_BOOL_KEEP_ALIVE_ONOFF, false));

Adjusting Notes:

After setting this feature to false, if the SDK’s image acquisition is abnormally terminated (e.g., via Ctrl+C) while the camera is running, the camera’s laser will remain lit, and the SDK will be unable to reopen the camera.

Lifecycle: start-stop

TY_INT_KEEP_ALIVE_TIMEOUT

This feature sets the keep-alive timeout for communication between the SDK and the camera. Default is 15000 ms for USB cameras and 3000 ms for network cameras. Unit: ms.

Configuration Method

int32_t value = 30000;
ASSERT_OK(TYSetInt(hDevice, TY_COMPONENT_DEVICE, TY_INT_KEEP_ALIVE_TIMEOUT, value));

Adjusting Notes:

After setting TY_INT_KEEP_ALIVE_TIMEOUT to 30000, if the SDK’s image acquisition is abnormally terminated (e.g., via Ctrl+C) while the camera is running, the camera’s laser will remain lit for 30000 ms before turning off.

Lifecycle: Effective after configuration until power cycle or reconfiguration of other parameters.

TY_INT_TRIGGER_DELAY_US

This feature sets the software/hardware trigger delay time. The camera will output images after a delay upon receiving a hardware trigger signal. Unit: us.

Configuration Method

int32_t value = 1300000;
ASSERT_OK(TYSetInt(hDevice, TY_COMPONENT_DEVICE, TY_INT_TRIGGER_DELAY_US, value));

Adjusting Notes:

After setting TY_INT_TRIGGER_DELAY_US to 1300000, the camera will output images 1300000 us (1.3 s) after receiving a hardware trigger signal.

Lifecycle: start-stop

TY_INT_TRIGGER_DURATION_US

This feature sets the hold time for the output signal level. Unit: us.

Configuration Method

int32_t value = 100000;
ASSERT_OK(TYSetInt(hDevice, TY_COMPONENT_DEVICE, TY_INT_TRIGGER_DURATION_US, value));

Adjusting Notes:

After powering the trigger circuit, connect an oscilloscope probe to the camera’s Trigger_out pin. Set the camera operating mode to TY_TRIGGER_MODE_M_SIG. For cameras with a default high output level, the signal low-level hold time will be 100000 us; for cameras with a default low output level, the signal high-level hold time will be 100000 us.

Lifecycle: start-stop

TY_ENUM_STREAM_ASYNC

This feature configures data stream asynchronization.

  • TY_STREAM_ASYNC_OFF: Data stream synchronization

  • TY_STREAM_ASYNC_DEPTH: Depth data stream asynchronization

  • TY_STREAM_ASYNC_RGB: RGB data stream asynchronization

  • TY_STREAM_ASYNC_DEPTH_RGB: Depth and RGB data stream asynchronization

  • TY_STREAM_ASYNC_ALL: All data streams asynchronous

Configuration Method

ASSERT_OK(TYSetEnum(hDevice, TY_COMPONENT_DEVICE, TY_ENUM_STREAM_ASYNC, TY_STREAM_ASYNC_RGB));

Adjusting Notes:

Observe the program’s runtime log. Taking TY_STREAM_ASYNC_RGB as an example, the host first acquires an RGB frame, followed by a depth and IR frame. The depth and IR timestamps are consistent, while the RGB timestamp differs from the depth/IR timestamps. Depending on the camera used, the RGB frame may arrive earlier or later. However, for the same camera, the timing relative to depth/IR will be consistent.

Lifecycle: start-stop

TY_INT_CAPTURE_TIME_US

This feature reads the depth calculation time, applicable only in trigger mode. Unit: us.

Note

In free-run mode, the read depth calculation time is 0.

Read Method

int32_t default_value=0;
ASSERT_OK(TYGetInt(hDevice, TY_COMPONENT_DEVICE, TY_INT_CAPTURE_TIME_US, &default_value));

TY_ENUM_TIME_SYNC_TYPE

This feature configures the camera’s time synchronization functionality.

  • TY_TIME_SYNC_TYPE_NONE: No time synchronization.

  • TY_TIME_SYNC_TYPE_HOST: Camera synchronizes with the host machine.

  • TY_TIME_SYNC_TYPE_NTP: Camera synchronizes with an NTP server.

  • TY_TIME_SYNC_TYPE_PTP: Camera synchronizes with a PTP server (GM461-E1, GM465-E1, PMD02-E1, PMD03-E1, and V series cameras only).

  • TY_TIME_SYNC_TYPE_CAN: Camera synchronizes with a CAN network (FM862-GDW only).

  • TY_TIME_SYNC_TYPE_PTP_MASTER: Set the camera as a PTP server.

Configuration Method

ASSERT_OK(TYSetEnum(hDevice, TY_COMPONENT_DEVICE, TY_ENUM_TIME_SYNC_TYPE, TY_TIME_SYNC_TYPE_HOST));
while (1) {
bool sync_ready;
ASSERT_OK(TYGetBool(hDevice, TY_COMPONENT_DEVICE, TY_BOOL_TIME_SYNC_READY, &sync_ready));
if (sync_ready) {
break;
}
MSLEEP(10);
}

Adjusting Notes

  • TY_TIME_SYNC_TYPE_NONE: Image timestamps are shorter.

  • TY_TIME_SYNC_TYPE_HOST: Image timestamps match the host machine time. Changing the host time causes camera timestamps to update automatically.

  • TY_TIME_SYNC_TYPE_NTP: Image timestamps match the NTP server time. Changing the host time does not affect timestamps.

  • TY_TIME_SYNC_TYPE_PTP: Image timestamps match the PTP server time (LR custom function).

  • TY_TIME_SYNC_TYPE_CAN: Image timestamps match the CAN network server time (FM862-GDW only).

  • TY_TIME_SYNC_TYPE_PTP_MASTER: The camera acts as a PTP server, allowing other cameras to synchronize with it.

For NTP synchronization, additional verification is needed after specifying the server IP. Method:

const char* ntp_ip = " 119.29.26.206 ";
int32_t ip_i[4];
uint8_t ip_b[4];
int32_t ip32;
sscanf(ntp_ip, "%d.%d.%d.%d", &ip_i[0], &ip_i[1], &ip_i[2], &ip_i[3]);
ip_b[0] = ip_i[0]; ip_b[1] = ip_i[1]; ip_b[2] = ip_i[2]; ip_b[3] = ip_i[3];
ip32 = TYIPv4ToInt(ip_b);
LOGI("Set persistent IP 0x%x(%d.%d.%d.%d)", ip32, ip_b[0], ip_b[1], ip_b[2], ip_b[3]);
ASSERT_OK(TYSetInt(hDevice, TY_COMPONENT_DEVICE, TY_INT_NTP_SERVER_IP, ip32));
ASSERT_OK(TYGetInt(hDevice, TY_COMPONENT_DEVICE,TY_INT_NTP_SERVER_IP, &ip32));
TYIntToIPv4(ip32, ip_b);
LOGD("%d %d %d %d", ip_b[0], ip_b[1], ip_b[2], ip_b[3]);
LOGD("Set type of time sync mechanism");
ASSERT_OK(TYSetEnum(hDevice, TY_COMPONENT_DEVICE, TY_ENUM_TIME_SYNC_TYPE, TY_TIME_SYNC_TYPE_NTP));
LOGD("Wait for time sync ready");
while (1) {
bool sync_ready;
ASSERT_OK(TYGetBool(hDevice, TY_COMPONENT_DEVICE, TY_BOOL_TIME_SYNC_READY, &sync_ready));
if (sync_ready) {
break;
}
MSLEEP(10);
}

Lifecycle: init-deinit

TY_BOOL_TIME_SYNC_READY

This feature indicates whether time synchronization is successful.

Read Method

bool sync_ready;
ASSERT_OK(TYGetBool(hDevice, TY_COMPONENT_DEVICE, TY_BOOL_TIME_SYNC_READY, &sync_ready));

Adjusting Notes

Set the camera for NTP synchronization. Print the synchronization success status every second. Before synchronization succeeds, the result is false. After synchronization succeeds, the result is true.

TY_BOOL_CMOS_SYNC

Left and right IR asynchronous exposure switch. true: Synchronous exposure; false: Asynchronous exposure.

Configuration Method

ASSERT_OK(TYSetBool(hDevice, TY_COMPONENT_DEVICE, TY_BOOL_CMOS_SYNC, false));

Adjusting Notes

For cameras supporting the TY_BOOL_CMOS_SYNC feature, the depth map frame rate is higher when TY_BOOL_CMOS_SYNC = false compared to TY_BOOL_CMOS_SYNC = true.

Lifecycle: Effective after configuration until power cycle or reconfiguration of other parameters.

TY_INT_ACCEPTABLE_PERCENT

Network packet loss tolerance threshold. Images for which the host receives a data packet percentage lower than this threshold will be discarded. Unit: %.

Configuration Method

ASSERT_OK(TYSetInt(hDevice, TY_COMPONENT_DEVICE, TY_INT_ACCEPTABLE_PERCENT, 90));

Adjusting Notes

After disabling network retransmission, setting TY_INT_ACCEPTABLE_PERCENT to a small value and running multiple cameras on a single computer, observe the output images from each camera. A low value may result in corrupted images received by the host (e.g., large green areas on the RGB image).

TY_STRUCT_CAM_STATISTICS

Retrieves network camera transmission statistics.

Read Method

TY_CAMERA_STATISTICS st;
ASSERT_OK( TYGetStruct(hDevice, TY_COMPONENT_DEVICE, TY_STRUCT_CAM_STATISTICS, &st, sizeof(st)) );
LOGI("Statistics:");
LOGI("  packetReceived: %" PRIu64 " ", st.packetReceived);
LOGI("  packetLost    : %" PRIu64 " ", st.packetLost);
LOGI("  imageOutputed : %" PRIu64 " ", st.imageOutputed);
LOGI("  imageDropped  : %" PRIu64 " ", st.imageDropped);

Where: - packetReceived: Total number of data packets received by the host. - packetLost: Total number of data packets not received by the host. - imageOutputed: Total number of images received by the host (integer multiple of the number of data streams). - imageDropped: Total number of images not received by the host.

TY_ENUM_TEMPERATURE_ID

Used with TY_STRUCT_TEMPERATURE to read the temperature at a specified location. Currently supported locations: left IR, right IR, color sensor, CPU, and mainboard.

Read Method

uint32_t n = 0;
ASSERT_OK(TYGetEnumEntryCount(hDevice, TY_COMPONENT_DEVICE, TY_ENUM_TEMPERATURE_ID, &n));
LOGD("===         %14s: entry count %d", "", n);
std::vector<TY_ENUM_ENTRY> feature_info(n);
if (n == 0) {
    LOGD("No temperature sensor exists!\n");
}
else {
    ASSERT_OK(TYGetEnumEntryInfo(hDevice, TY_COMPONENT_DEVICE, TY_ENUM_TEMPERATURE_ID, &feature_info[0], n, &n));
    for (int i = 0; i < n; i++) {
        int ret = TYSetEnum(hDevice, TY_COMPONENT_DEVICE, TY_ENUM_TEMPERATURE_ID, feature_info[i].value);
        if (ret < 0) {
            LOGD("Set temperature id[%d](%s) failed %d(%s)\n", feature_info[i].value, feature_info[i].description, ret, TYErrorString(ret));
            break;
        }
        TY_TEMP_DATA temp;
        memset(&temp, 0, sizeof(temp));
        ret = TYGetStruct(hDevice, TY_COMPONENT_DEVICE, TY_STRUCT_TEMPERATURE, &temp, sizeof(temp));
        if (ret < 0) {
            LOGD("Get temperature [%d](%s) failed %d(%s)\n", feature_info[i].value, feature_info[i].description, ret, TYErrorString(ret));
            break;
        }
        LOGD("Get temperature [%d](%s) temp %s\n", feature_info[i].value, feature_info[i].description, temp.temp);
    }
}

IP Configuration

IP configuration involves 3 features: - IP Address: TY_INT_PERSISTENT_IP - Subnet Mask: TY_INT_PERSISTENT_SUBMASK - Gateway: TY_INT_PERSISTENT_GATEWAY

Configuration Method

int32_t ip_i[4] = { 192, 168, 2, 199 };
uint8_t ip_b[4] = { ip_i[0], ip_i[1], ip_i[2], ip_i[3] };
int32_t ip32 = TYIPv4ToInt(ip_b);
LOGI("Set persistent IP 0x%x(%d.%d.%d.%d)", ip32, ip_b[0], ip_b[1], ip_b[2], ip_b[3]);
ASSERT_OK(TYSetInt(hDevice, TY_COMPONENT_DEVICE, TY_INT_PERSISTENT_IP, ip32));

int32_t mask_i[4] = { 255, 255, 255, 0 };
uint8_t mask_b[4] = { mask_i[0], mask_i[1], mask_i[2], mask_i[3] };
int32_t mask32 = TYIPv4ToInt(mask_b);
LOGI("Set persistent Netmask 0x%x(%d.%d.%d.%d)", mask32, mask_b[0], mask_b[1], mask_b[2], mask_b[3]);
ASSERT_OK(TYSetInt(hDevice, TY_COMPONENT_DEVICE, TY_INT_PERSISTENT_SUBMASK, mask32));

int32_t gateway_i[4] = { 192, 168, 2, 1 };
uint8_t gateway_b[4] = { gateway_i[0], gateway_i[1], gateway_i[2], gateway_i[3] };
int32_t gateway32 = TYIPv4ToInt(gateway_b);
LOGI("Set persistent Gateway 0x%x(%d.%d.%d.%d)", gateway32, gateway_b[0], gateway_b[1], gateway_b[2], gateway_b[3]);
ASSERT_OK(TYSetInt(hDevice, TY_COMPONENT_DEVICE, TY_INT_PERSISTENT_GATEWAY, gateway32));

After configuring the IP as above, the settings take effect after power cycling the camera.

Alternatively, the IP can be set using the ForceDeviceIP sample program located at {Camport4 SDK download path}/camport4/sample/sample_v1.

Adjusting Notes

After setting a static IP, the camera retains the IP after a power cycle. This allows camera discovery and IP clearing across network segments. Only valid IP addresses can be successfully set. A valid IP address must belong to the same class of network address as the subnet mask.

Features Under the Laser Component

TY_BOOL_LASER_AUTO_CTRL

Laser automatic control switch.

Note

This does not mean automatically adjusting laser brightness based on ambient light.

Configuration Method

ASSERT_OK(TYSetBool(hDevice, TY_COMPONENT_LASER, TY_BOOL_LASER_AUTO_CTRL, false));

Adjusting Notes

  • For active stereo structured light cameras: When TY_BOOL_LASER_AUTO_CTRL = false, activating any data stream with laser_power ≠ 0 turns on the laser, and the IR image shows a speckle pattern. When TY_BOOL_LASER_AUTO_CTRL = true, the laser only turns on when depth data is output, and the IR image shows a Sobel pattern.

  • For active stereo fringe projection cameras: When TY_BOOL_LASER_AUTO_CTRL = false, activating any data stream with laser_power ≠ 0 turns on the fringe projector. When TY_BOOL_LASER_AUTO_CTRL = true, the fringe projector only turns on when depth data is output.

Lifecycle: start-stop

TY_INT_LASER_POWER

Sets the laser/fringe projector light source intensity.

Configuration Method

int32_t value = 0;
ASSERT_OK(TYSetInt(hDevice, TY_COMPONENT_LASER, TY_INT_LASER_POWER, value));

Adjusting Notes

A higher TY_INT_LASER_POWER value results in brighter projected light from the laser/fringe projector.

Lifecycle: open-close

TY_BOOL_IR_FLASHLIGHT

Enables the IR floodlight source.

Configuration Method

bool value = true;
ASSERT_OK(TYSetBool(hDevice, TY_COMPONENT_LASER, TY_BOOL_IR_FLASHLIGHT, value));

Adjusting Notes

After setting this feature to true, the IR floodlight source turns on.

Note

  • The IR floodlight source cannot be turned on simultaneously with the RGB floodlight source (if present) or the laser.

  • The IR floodlight cannot be turned on when the camera outputs depth images.

Lifecycle: start-stop

TY_BOOL_RGB_FLASHLIGHT

Enables the RGB floodlight source.

Configuration Method

bool value = true;
ASSERT_OK(TYSetBool(hDevice, TY_COMPONENT_LASER, TY_BOOL_RGB_FLASHLIGHT, value));

Adjusting Notes

After setting this feature to true, the RGB floodlight source turns on.

Lifecycle: start-stop

TY_INT_IR_FLASHLIGHT_INTENSITY

Sets the IR floodlight brightness intensity.

Configuration Method

int32_t value = 0;
ASSERT_OK(TYSetInt(hDevice, TY_COMPONENT_LASER, TY_INT_IR_FLASHLIGHT_INTENSITY, value));

Adjusting Notes

After enabling the IR floodlight, a higher intensity setting results in brighter light and a brighter IR image.

Lifecycle: Effective after configuration until power cycle or reconfiguration of other parameters.

TY_INT_RGB_FLASHLIGHT_INTENSITY

Sets the RGB floodlight brightness intensity.

Configuration Method

int32_t value = 0;
ASSERT_OK(TYSetInt(hDevice, TY_COMPONENT_LASER, TY_INT_RGB_FLASHLIGHT_INTENSITY, value));

Adjusting Notes

After enabling the RGB floodlight, a higher intensity setting results in brighter light and a brighter RGB image.

Lifecycle: Effective after configuration until power cycle or reconfiguration of other parameters.

Features Under the Depth Component

TY_FLOAT_SCALE_UNIT

Depth value unit.

Configuration Method

float value = 0.25;
ASSERT_OK(TYSetFloat(hDevice, TY_COMPONENT_DEPTH_CAM, TY_FLOAT_SCALE_UNIT,value));

Adjusting Notes

After configuration, the depth value printed by the program when clicking on the depth map will be an integer multiple of the TY_FLOAT_SCALE_UNIT setting. For example, if set to 0.25, the depth value will be a multiple of 0.25.

Lifecycle: open-close

TY_INT_SGBM_IMAGE_NUM

Number of IR images required for SGBM depth calculation.

Configuration Method

int32_t value = 10;
ASSERT_OK(TYSetInt(hDevice, TY_COMPONENT_DEPTH_CAM, TY_INT_SGBM_IMAGE_NUM, value));

Adjusting Notes

A smaller parameter value results in a higher frame rate.

Lifecycle: open-close

TY_INT_SGBM_DISPARITY_NUM

Disparity search range for SGBM depth calculation.

Configuration Method

int32_t value = 10;
ASSERT_OK(TYSetInt(hDevice, TY_COMPONENT_DEPTH_CAM, TY_INT_SGBM_DISPARITY_NUM, value));

Lifecycle: open-close

TY_INT_SGBM_DISPARITY_OFFSET

Starting disparity value for SGBM depth calculation search.

Configuration Method

int32_t value = 10;
ASSERT_OK(TYSetInt(hDevice, TY_COMPONENT_DEPTH_CAM, TY_INT_SGBM_DISPARITY_OFFSET, value));

Lifecycle: open-close

TY_INT_SGBM_MATCH_WIN_HEIGHT

Height of the matching window for SGBM depth calculation.

Configuration Method

int32_t value = 10;
ASSERT_OK(TYSetInt(hDevice, TY_COMPONENT_DEPTH_CAM, TY_INT_SGBM_MATCH_WIN_HEIGHT, value));

Lifecycle: open-close

Note

There is a constraint relationship between TY_INT_SGBM_MATCH_WIN_HEIGHT and TY_INT_SGBM_IMAGE_NUM. Refer to the camera’s config file for the specific constraints.

TY_INT_SGBM_MATCH_WIN_WIDTH

Width of the matching window for SGBM depth calculation.

Configuration Method

int32_t value = 10;
ASSERT_OK(TYSetInt(hDevice, TY_COMPONENT_DEPTH_CAM, TY_INT_SGBM_MATCH_WIN_WIDTH, value));

Lifecycle: open-close

TY_INT_SGBM_SEMI_PARAM_P1

Penalty parameter for adjacent pixel (+/-1) constraints.

Configuration Method

int32_t value = 1;
ASSERT_OK(TYSetInt(hDevice, TY_COMPONENT_DEPTH_CAM, TY_INT_SGBM_SEMI_PARAM_P1, value));

Adjusting Notes

A smaller P1 value results in more small black holes in the depth map.

Lifecycle: open-close

TY_INT_SGBM_SEMI_PARAM_P1_SCALE

Adjacent pixel (+/-1) constraint penalty parameter P1_scale.

Configuration Method

int32_t value = 1;
ASSERT_OK(TYSetInt(hDevice, TY_COMPONENT_DEPTH_CAM, TY_INT_SGBM_SEMI_PARAM_P1_SCALE, value));

Adjusting Notes

A larger P1_Scale parameter results in more depth black holes.

Lifecycle: open-close

TY_INT_SGBM_SEMI_PARAM_P2

Surrounding pixel constraint penalty parameter P2.

Configuration Method

int32_t value = 1;
ASSERT_OK(TYSetInt(hDevice, TY_COMPONENT_DEPTH_CAM, TY_INT_SGBM_SEMI_PARAM_P2, value));

Lifecycle: open-close

TY_INT_SGBM_UNIQUE_FACTOR

Uniqueness check parameter 2: the difference between the best and second-best matching points.

Configuration Method

int32_t value = 1;
ASSERT_OK(TYSetInt(hDevice, TY_COMPONENT_DEPTH_CAM, TY_INT_SGBM_UNIQUE_FACTOR, value));

Adjusting Notes

A larger uniqueness percentage parameter results in more depth black holes.

Lifecycle: open-close

TY_INT_SGBM_UNIQUE_ABSDIFF

Uniqueness check parameter 1: the percentage difference between the best and second-best matching points.

Configuration Method

int32_t value = 1;
ASSERT_OK(TYSetInt(hDevice, TY_COMPONENT_DEPTH_CAM, TY_INT_SGBM_UNIQUE_ABSDIFF, value));

Adjusting Notes

A larger uniqueness difference parameter results in more depth black holes.

Lifecycle: open-close

TY_BOOL_SGBM_HFILTER_HALF_WIN

Search filter switch. Used to further optimize the depth map by removing noise and discontinuities; more friendly to object edge point clouds.

Configuration Method

bool value = true;
ASSERT_OK(TYSetBool(hDevice, TY_COMPONENT_DEPTH_CAM, TY_BOOL_SGBM_HFILTER_HALF_WIN, value));

Adjusting Notes

Disabling the search filter results in fewer depth black holes but more mismatched points.

Lifecycle: open-close

TY_BOOL_SGBM_MEDFILTER

Median filter switch, used to eliminate isolated noise points while preserving image edge information as much as possible.

Configuration Method

bool value = true;
ASSERT_OK(TYSetBool(hDevice, TY_COMPONENT_DEPTH_CAM, TY_BOOL_SGBM_MEDFILTER, value));

Adjusting Notes

Enabling the median filter reduces the root mean square error of plane fitting (viewable through the legacy Percipio Viewer 2.6.3 under “Planarity of ROI” for the depth map).

Lifecycle: open-close

TY_INT_SGBM_MEDFILTER_THRESH

Median filter threshold. A larger setting filters more noise points but may also cause loss of detail in the depth map.

Configuration Method

int32_t value = 1;
ASSERT_OK(TYSetInt(hDevice, TY_COMPONENT_DEPTH_CAM, TY_INT_SGBM_MEDFILTER_THRESH, value));

Adjusting Notes

After enabling the median filter, a larger median filter threshold parameter results in a smaller root mean square error of plane fitting (viewable through the legacy Percipio Viewer 2.6.3 under “Planarity of ROI” for the depth map).

Lifecycle: open-close

TY_BOOL_SGBM_LRC

Left-right consistency check switch.

Configuration Method

bool value = false;
ASSERT_OK(TYSetBool(hDevice, TY_COMPONENT_DEPTH_CAM, TY_BOOL_SGBM_LRC, value));

Adjusting Notes

Disabling the left-right consistency check results in more mismatched points.

Lifecycle: open-close

TY_INT_SGBM_LRC_DIFF

Median filter threshold. A larger setting filters more noise points but may also cause loss of detail in the depth map.

Configuration Method

int32_t value = 1;
ASSERT_OK(TYSetInt(hDevice, TY_COMPONENT_DEPTH_CAM, TY_INT_SGBM_LRC_DIFF, value));

Adjusting Notes

After enabling the left-right consistency check, a larger consistency check parameter results in more mismatched points.

Lifecycle: open-close

TY_ENUM_DEPTH_QUALITY

Depth image quality for ToF cameras.

Configuration Method

uint32_t value = 0;
ASSERT_OK(TYSetEnum(hDevice, TY_COMPONENT_DEPTH_CAM, feature_id, value));

Lifecycle: Effective after configuration until power cycle or reconfiguration of other parameters.

TY_INT_TOF_MODULATION_THRESHOLD

Threshold for ToF depth camera received laser modulation light intensity. Pixels with intensity below this threshold do not participate in depth calculation; their depth value is set to 0.

Configuration Method

int32_t value = 1;
ASSERT_OK(TYSetInt(hDevice, TY_COMPONENT_DEPTH_CAM, TY_INT_TOF_MODULATION_THRESHOLD, value));

Adjusting Notes

A larger parameter results in a lower percentage of valid depth pixels.

Lifecycle: Effective after configuration until power cycle or reconfiguration of other parameters.

TY_INT_TOF_JITTER_THRESHOLD

Jitter filtering threshold for ToF depth cameras. A larger threshold setting results in less filtering of jittering depth data at depth map edges.

Configuration Method

int32_t value = 1;
ASSERT_OK(TYSetInt(hDevice, TY_COMPONENT_DEPTH_CAM, TY_INT_TOF_JITTER_THRESHOLD, value));

Adjusting Notes

A smaller parameter results in a lower percentage of valid depth pixels.

Lifecycle: Effective after configuration until power cycle or reconfiguration of other parameters.

TY_INT_FILTER_THRESHOLD

Flying point filter threshold for ToF depth cameras. Default is 0 (no filtering). A smaller filter threshold setting filters more flying points.

Configuration Method

int32_t value = 1;
ASSERT_OK(TYSetInt(hDevice, TY_COMPONENT_DEPTH_CAM, TY_INT_FILTER_THRESHOLD, value));

Adjusting Notes

A smaller parameter results in a lower percentage of valid depth pixels.

Lifecycle: Effective after configuration until power cycle or reconfiguration of other parameters.

TY_INT_TOF_CHANNEL

Modulation channel for ToF depth cameras. Different modulation channels have different modulation frequencies and do not interfere. To run multiple ToF depth cameras in the same scene, first ensure cameras of the same series use different modulation channels.

Configuration Method

int32_t value = 1;
ASSERT_OK(TYSetInt(hDevice, TY_COMPONENT_DEPTH_CAM, TY_INT_TOF_CHANNEL, value));

Adjusting Notes

  • Using multiple cameras with the same frequency for opposing shots results in abnormal depth maps.

  • Using multiple cameras with different frequencies for opposing shots does not interfere with depth maps.

Lifecycle: Effective after configuration until power cycle or reconfiguration of other parameters.

TY_INT_TOF_HDR_RATIO

High dynamic range ratio threshold, to be used in TY_ENUM_DEPTH_QUALITY=HIGH mode.

Configuration Method

int32_t value = 1;
ASSERT_OK(TYSetInt(hDevice, TY_COMPONENT_DEPTH_CAM, TY_INT_TOF_HDR_RATIO, value));

Adjusting Notes

Optimizes imaging of highly reflective objects.

Lifecycle: open-close

TY_INT_TOF_ANTI_SUNLIGHT_INDEX

ToF anti-sunlight index.

Configuration Method

int32_t value = 1;
ASSERT_OK(TYSetInt(hDevice, TY_COMPONENT_DEPTH_CAM, TY_INT_TOF_ANTI_SUNLIGHT_INDEX, value));

Adjusting Notes

Under sunlight, configuring this parameter effectively reduces solar interference.

Lifecycle: Effective after configuration until power cycle or reconfiguration of other parameters.

TY_INT_MAX_SPECKLE_DIFF

Speckle filter clustering threshold. Unit: mm. If the depth difference between adjacent pixels is less than this threshold, they are considered part of the same clustered speckle.

Configuration Method

int32_t value = 200;
ASSERT_OK(TYSetInt(hDevice, TY_COMPONENT_DEPTH_CAM, TY_INT_MAX_SPECKLE_DIFF, value));

Adjusting Notes

A smaller threshold results in more speckles filtered from the image. The effect is noticeable when debugging TY_INT_MAX_SPECKLE_DIFF with a large TY_INT_MAX_SPECKLE_SIZE value.

Lifecycle: Effective after configuration until power cycle or reconfiguration of other parameters.

TY_INT_MAX_SPECKLE_SIZE

Speckle filter area threshold. Unit: pixels. Clustered speckles with an area smaller than this threshold are filtered out.

Configuration Method

int32_t value = 200;
ASSERT_OK(TYSetInt(hDevice, TY_COMPONENT_DEPTH_CAM, TY_INT_MAX_SPECKLE_SIZE, value));

Adjusting Notes

A larger threshold results in more speckles filtered from the image.

Lifecycle: Effective after configuration until power cycle or reconfiguration of other parameters.

TY_BOOL_TOF_ANTI_INTERFERENCE

Anti-multi-camera interference switch. Applicable when the number of dToF cameras in a scene exceeds the number of ToF_channels. Effectively avoids multi-camera interference.

Configuration Method

bool value = true;
ASSERT_OK(TYSetBool(hDevice, TY_COMPONENT_DEPTH_CAM, TY_BOOL_TOF_ANTI_INTERFERENCE, value));

Adjusting Notes

Enabling anti-multi-camera interference effectively reduces mutual interference among multiple dToF cameras in the same scene.

Lifecycle: Effective after configuration until power cycle or reconfiguration of other parameters.

TY_ENUM_CONFIG_MODE

Preset parameters for V-series cameras. Different modes offer different camera accuracies.

Configuration Method

uint32_t value = TY_CONFIG_MODE_PRESET1;
ASSERT_OK(TYSetEnum(hDevice, TY_COMPONENT_DEVICE, TY_ENUM_CONFIG_MODE, value));

Lifecycle: start-stop

TY_INT_SGBM_TEXTURE_THRESH

Addresses depth image anomalies when the measured object has no background or the background is far away.

Configuration Method

int32_t value = 500;
TYSetInt(hDevice, TY_COMPONENT_DEPTH_CAM, TY_INT_SGBM_TEXTURE_THRESH, value);

Lifecycle: open-close

TY_INT_SGBM_TEXTURE_OFFSET

Addresses poor depth imaging due to missing or distant backgrounds. This feature is read-only.

Read Method

int32_t value;
TYGetInt(hDevice, TY_COMPONENT_DEPTH_CAM, TY_INT_SGBM_TEXTURE_OFFSET, &value);

TY_INT_DEPTH_MIN_MM

Sets the minimum cutoff distance for depth values. Unit: mm. This feature is readable and writable.

Configuration Method

ASSERT_OK(TYSetInt(hDevice, TY_COMPONENT_DEPTH_CAM, TY_INT_DEPTH_MIN_MM, 1400));

Read Method

int min = 0;
ASSERT_OK(TYGetInt(hDevice, TY_COMPONENT_DEPTH_CAM, TY_INT_DEPTH_MIN_MM, &min));
printf("min: %d\n", min);

Adjusting Notes

Setting TY_INT_DEPTH_MIN_MM to 1400 masks all depth data closer than 1400 mm, appearing as black holes on the depth map.

Lifecycle: open-close

TY_INT_DEPTH_MAX_MM

Sets the maximum cutoff distance for depth values. Unit: mm. This feature is readable and writable.

Configuration Method

ASSERT_OK(TYSetInt(hDevice, TY_COMPONENT_DEPTH_CAM, TY_INT_DEPTH_MAX_MM, 1500));

Read Method

int max = 0;
ASSERT_OK(TYGetInt(hDevice, TY_COMPONENT_DEPTH_CAM, TY_INT_DEPTH_MAX_MM, &max));
printf("max: %d\n", max);

Adjusting Notes

Setting TY_INT_DEPTH_MAX_MM to 1500 masks all depth data farther than 1500 mm, appearing as black holes on the depth map.

Lifecycle: open-close

Features Under the RGB Component

TY_INT_ANALOG_GAIN

Sets the RGB analog gain.

Configuration Method

int32_t value = 2;
ASSERT_OK(TYSetInt(hDevice, TY_COMPONENT_RGB_CAM, TY_INT_ANALOG_GAIN, value));

Adjusting Notes

A larger value results in a brighter RGB image.

Note that increasing analog gain also amplifies sensor noise, potentially increasing image noise and reducing signal-to-noise ratio. It is recommended to use the lowest analog gain that meets brightness requirements for better image quality.

Lifecycle: Effective after configuration until power cycle or reconfiguration of other parameters.

TY_INT_R_GAIN

Sets the RGB red channel gain.

Configuration Method

int32_t value = 2;
ASSERT_OK(TYSetInt(hDevice, TY_COMPONENT_RGB_CAM, TY_INT_R_GAIN, value));

Adjusting Notes

A larger value results in a redder RGB image.

Lifecycle: Effective after configuration until power cycle or reconfiguration of other parameters.

TY_INT_G_GAIN

Sets the RGB green channel gain.

Configuration Method

int32_t value = 2;
ASSERT_OK(TYSetInt(hDevice, TY_COMPONENT_RGB_CAM, TY_INT_G_GAIN, value));

Adjusting Notes

A larger value results in a greener RGB image.

Lifecycle: Effective after configuration until power cycle or reconfiguration of other parameters.

TY_INT_B_GAIN

Sets the RGB blue channel gain.

Configuration Method

int32_t value = 2;
ASSERT_OK(TYSetInt(hDevice, TY_COMPONENT_RGB_CAM, TY_INT_B_GAIN, value));

Adjusting Notes

A larger value results in a bluer RGB image.

Lifecycle: Effective after configuration until power cycle or reconfiguration of other parameters.

TY_INT_EXPOSURE_TIME

Sets the RGB exposure time.

Configuration Method

int32_t value = 100;
ASSERT_OK(TYSetInt(hDevice, TY_COMPONENT_RGB_CAM, TY_INT_EXPOSURE_TIME, value));

Adjusting Notes

A larger value results in a brighter RGB image.

Lifecycle: Effective after configuration until power cycle or reconfiguration of other parameters.

TY_FLOAT_EXPOSURE_TIME_US

Sets the actual exposure time for the color sensor. Unit: us.

Configuration Method

float value = 23000.0;
ASSERT_OK(TYSetFloat(hDevice, TY_COMPONENT_RGB_CAM, TY_FLOAT_EXPOSURE_TIME_US, value));

Adjusting Notes

A larger value results in a brighter RGB image.

Note

There is a computational relationship between this and TY_INT_EXPOSURE_TIME. Refer to the camera’s fetch_config.xml file.

Lifecycle: Effective after configuration until power cycle or reconfiguration of other parameters.

TY_INT_AE_TARGET_Y

Target brightness for AEC adjustment.

Configuration Method

int32_t value = 200;
ASSERT_OK(TYSetInt(hDevice, TY_COMPONENT_RGB_CAM, TY_INT_AE_TARGET_Y, value));

Adjusting Notes

After enabling AEC, a smaller value results in a darker image; a larger value results in a brighter image.

Lifecycle: Effective after configuration until power cycle or reconfiguration of other parameters.

TY_STRUCT_AEC_ROI

Region of Interest (ROI) for AEC adjustment. Once set, the exposure time is automatically adjusted based on the brightness within the ROI.

Configuration Method

TY_AEC_ROI_PARAM roi;
roi.x = 0;
roi.y = 0;
roi.w = 100;
roi.h = 100;
ASSERT_OK(TYSetStruct(hDevice, TY_COMPONENT_RGB_CAM, TY_STRUCT_AEC_ROI, &roi, sizeof(roi)));

Adjusting Notes

  • If the ROI is overexposed (e.g., fluorescent light), the entire image becomes darker.

  • If the ROI is underexposed (e.g., black object), the entire image becomes brighter.

Lifecycle: Effective after configuration until power cycle or reconfiguration of other parameters.

TY_BOOL_AUTO_EXPOSURE

RGB auto-exposure switch.

Configuration Method

bool value = true;
ASSERT_OK(TYSetBool(hDevice, TY_COMPONENT_RGB_CAM, TY_BOOL_AUTO_EXPOSURE, value));

Adjusting Notes

  • Method 1: After enabling RGB auto-exposure, point the camera at a fluorescent light, cover the RGB lens with your hand, and then remove your hand. The image will undergo a convergence process.

  • Method 2: After disabling RGB auto-exposure, set the exposure time to the minimum, then enable RGB auto-exposure. The image will become brighter.

Lifecycle: Effective after configuration until power cycle or reconfiguration of other parameters.

TY_BOOL_AUTO_AWB

RGB automatic white balance function.

Configuration Method

bool value = true;
ASSERT_OK(TYSetBool(hDevice, TY_COMPONENT_RGB_CAM, TY_BOOL_AUTO_AWB, value));

Adjusting Notes

If the RGB image has color cast, enabling automatic white balance restores normal color.

Lifecycle: Effective after configuration until power cycle or reconfiguration of other parameters.

AUTO_ISP

Software ISP function developed by Percipio for the FM851-E2 camera, involving 3 APIs: TYISPCreate(), ColorIspInitSetting(), and TYISPUpdateDevice().

Adjusting Notes

Connect an FM851-E2 camera and run the sample programs located at {Camport4 SDK download path}/camport4/sample/sample_v1.

  • SimpleView_FetchFrame: This sample includes the software ISP function, producing RGB images closer to the actual object color.

  • SimpleView_TriggerMode1: This sample does not include the software ISP function; the RGB image appears greenish.

Note

After enabling auto ISP, TY_INT_ANALOG_GAIN will be set to 1.

Features Under the IR Component

TY_INT_EXPOSURE_TIME

Sets the left and right IR exposure time.

Configuration Method

int32_t value = 100;
ASSERT_OK(TYSetInt(hDevice, TY_COMPONENT_IR_CAM_LEFT, TY_INT_EXPOSURE_TIME, value));

Adjusting Notes

A larger value results in brighter IR images.

Lifecycle: Effective after configuration until power cycle or reconfiguration of other parameters.

TY_FLOAT_EXPOSURE_TIME_US

Sets the absolute true value of left and right IR exposure time. Unit: us.

Configuration Method

float value = 23000.0;
ASSERT_OK(TYSetFloat(hDevice, TY_COMPONENT_IR_CAM_LEFT, TY_FLOAT_EXPOSURE_TIME_US, value));

Adjusting Notes

A larger value results in brighter IR images.

Note

There is a computational relationship between this and TY_INT_EXPOSURE_TIME. Refer to the fetch_config.xml file for the specific conversion.

Lifecycle: Effective after configuration until power cycle or reconfiguration of other parameters.

TY_INT_ANALOG_GAIN

Sets the left and right IR analog gain.

Configuration Method

int32_t value = 2;
ASSERT_OK(TYSetInt(hDevice, TY_COMPONENT_IR_CAM_LEFT, TY_INT_ANALOG_GAIN, value));

Adjusting Notes

A larger value results in brighter IR images.

Lifecycle: Effective after configuration until power cycle or reconfiguration of other parameters.

TY_INT_GAIN

Sets the left and right IR gain.

Configuration Method

int32_t value = 2;
ASSERT_OK(TYSetInt(hDevice, TY_COMPONENT_IR_CAM_LEFT, TY_INT_GAIN, value));

Adjusting Notes

A larger value results in brighter IR images.

Lifecycle: Effective after configuration until power cycle or reconfiguration of other parameters.

TY_BOOL_UNDISTORTION

Left and right IR distortion correction switch. Enabled means correction is applied; default is disabled.

Configuration Method

bool value = true;
ASSERT_OK(TYSetBool(hDevice, TY_COMPONENT_IR_CAM_LEFT, TY_BOOL_UNDISTORTION, value));

Lifecycle: start-stop

Note

The left and right IR settings are bound; they must be enabled or disabled synchronously. The final state is determined by the last configured parameter.

TY_BOOL_HDR

Left and right IR HDR switch.

Configuration Method

bool value = true;
ASSERT_OK(TYSetBool(hDevice, TY_COMPONENT_IR_CAM_LEFT, TY_BOOL_HDR, value));

Lifecycle: Effective after configuration until power cycle or reconfiguration of other parameters.

TY_BYTEARRAY_HDR_PARAMETER

HDR exposure ratio parameters.

Configuration Method

  1. Read the size of the HDR array.

uint32_t hdr_size;
ASSERT_OK(TYGetByteArraySize(hDevice, TY_COMPONENT_IR_CAM_LEFT, TY_BYTEARRAY_HDR_PARAMETER, &hdr_size));
printf("hdr_size %d\n", hdr_size);

  1. Read the default HDR parameters.

uint32_t hdr_param[8];
hdr_param[0] = -1;
hdr_param[1] = -1;
ASSERT_OK(TYGetByteArray(hDevice, TY_COMPONENT_IR_CAM_LEFT, TY_BYTEARRAY_HDR_PARAMETER, (uint8_t*)&hdr_param[0], hdr_size));
printf("default %d  %d\n", hdr_param[0], hdr_param[1]);

  1. Set HDR parameters.

hdr_param[0] = 0;
hdr_param[1] = 0;
ASSERT_OK(TYSetByteArray(hDevice, TY_COMPONENT_IR_CAM_LEFT, TY_BYTEARRAY_HDR_PARAMETER, (uint8_t*)&hdr_param[0], hdr_size));

Adjusting Notes

HDR parameter range [0,2]. After enabling HDR, a smaller parameter value results in a brighter image.

Lifecycle: Effective after configuration until power cycle or reconfiguration of other parameters.

TY_STRUCT_CAM_RECTIFIED_ROTATION

Used to obtain the IR rotation from the new config, primarily for V-series camera calibration based on IR.

Read Method

TY_CAMERA_ROTATION rotation;
ASSERT_OK(TYGetStruct(hDevice, TY_COMPONENT_IR_CAM_LEFT, TY_STRUCT_CAM_RECTIFIED_ROTATION, &rotation, sizeof(rotation)));
LOGD("===%23s%f %f %f", "", rotation.data[0], rotation.data[1], rotation.data[2]);
LOGD("===%23s%f %f %f", "", rotation.data[3], rotation.data[4], rotation.data[5]);
LOGD("===%23s%f %f %f", "", rotation.data[6], rotation.data[7], rotation.data[8]);

Features Under the Storage Component

Methods for operating storage space can be found in the DeviceStorage sample program or SimpleView_SaveLoadConfig or SaveLoadConfig_v2.

Note

Operate storage space using the API only. Do not access the camera’s underlying system by writing content via methods like echo.

TY_BYTEARRAY_CUSTOM_BLOCK

Used to obtain the size of the custom_block.bin storage space.

Read Method

uint32_t block_size;
ASSERT_OK( TYGetByteArraySize(hDevice, TY_COMPONENT_STORAGE, TY_BYTEARRAY_CUSTOM_BLOCK, &block_size) );
LOGD("custom block bin size %d", block_size);

For more detailed examples, refer to the sample program {Camport4 SDK download path}/camport4/sample/sample_v1/DeviceStorage.

Note

For structured light cameras, file content is typically 0xFF; for ToF cameras, content is typically NUL. For structured light cameras, starting from firmware version R3.13.81, the custom_block.bin file location has moved from /mnt/.cali/ to /home/percipio/ (hidden file), and the size has changed from 4 KB to 64 KB.

TY_BYTEARRAY_ISP_BLOCK

Used to obtain the size of the isp_block.bin storage space.

Read Method

uint32_t block_size;
ASSERT_OK(TYGetByteArraySize(hDevice, TY_COMPONENT_STORAGE, TY_BYTEARRAY_ISP_BLOCK, &block_size));
LOGD("isp block bin size %d", block_size);

For more detailed examples, refer to the sample program {Camport4 SDK download path}/camport4/sample/sample_v1/DeviceStorage.