API Reference

Introduction

The camport3 libraries provide support for configuring PERCIPIO depth camera, data receiving and post-processing functionality.

API for Percipio depth camera

TYApi.h includes camera control and data receiving interface, which supports configuration for image resolution, frame rate, exposure time, gain, working mode,etc.

Defines

_STDBOOL_H
__bool_true_false_are_defined
bool
true
false
TY_DLLIMPORT
TY_DLLEXPORT
TY_STDC
TY_CDEC
TY_EXPORT
TY_EXTC
TY_LIB_VERSION_MAJOR
TY_LIB_VERSION_MINOR
TY_LIB_VERSION_PATCH
TY_DECLARE_IMAGE_MODE0(pix, res)
TY_DECLARE_IMAGE_MODE1(pix)
TY_CAPI

Typedefs

typedef enum TY_STATUS_LIST TY_STATUS_LIST

API call return status.

typedef int32_t TY_STATUS
typedef enum TY_EVENT_LIST TY_ENENT_LIST
typedef int32_t TY_EVENT
typedef void *TY_INTERFACE_HANDLE

Interface handle.

typedef void *TY_DEV_HANDLE

Device Handle.

typedef enum TY_DEVICE_COMPONENT_LIST TY_DEVICE_COMPONENT_LIST

Device Component list A device contains several component.

Each component can be controlled by its own features, such as image width, exposure time, etc..

See
To Know how to get feature information please refer to sample code DumpAllFeatures

typedef int32_t TY_COMPONENT_ID

component unique id

See
TY_DEVICE_COMPONENT_LIST

typedef enum TY_FEATURE_TYPE_LIST TY_FEATURE_TYPE_LIST

Feature Format Type definitions.

typedef int32_t TY_FEATURE_TYPE
typedef enum TY_FEATURE_ID_LIST TY_FEATURE_ID_LIST

feature for component definitions

typedef int32_t TY_FEATURE_ID

feature unique id

See
TY_FEATURE_ID_LIST

typedef enum TY_TRIGGER_ACTIVATION_LIST TY_TRIGGER_ACTIVATION_LIST

set external trigger signal edge

See
refer to sample SimpleView_TriggerMode for detail usage

typedef int32_t TY_TRIGGER_ACTIVATION
typedef enum TY_INTERFACE_TYPE_LIST TY_INTERFACE_TYPE_LIST

interface type definition

typedef int32_t TY_INTERFACE_TYPE
typedef enum TY_ACCESS_MODE_LIST TY_ACCESS_MODE_LIST

a feature is readable or writable

typedef int8_t TY_ACCESS_MODE
typedef enum TY_PIXEL_BITS_LIST TY_PIXEL_BITS_LIST

Pixel size type definitions.

typedef enum TY_PIXEL_FORMAT_LIST TY_PIXEL_FORMAT_LIST

pixel format definitions

typedef int32_t TY_PIXEL_FORMAT
typedef enum TY_RESOLUTION_MODE_LIST TY_RESOLUTION_MODE_LIST

predefined resolution list

typedef int32_t TY_RESOLUTION_MODE
typedef enum TY_IMAGE_MODE_LIST TY_IMAGE_MODE_LIST

Predefined Image Mode List image mode controls image resolution & format named like TY_IMAGE_MODE_MONO_160x120.

typedef int32_t TY_IMAGE_MODE
typedef enum TY_TRIGGER_MODE_LIST TY_TRIGGER_MODE_LIST

See
refer to sample SimpleView_TriggerMode for detail usage

typedef int16_t TY_TRIGGER_MODE
typedef struct TY_VERSION_INFO TY_VERSION_INFO
typedef struct TY_DEVICE_NET_INFO TY_DEVICE_NET_INFO
typedef struct TY_DEVICE_USB_INFO TY_DEVICE_USB_INFO
typedef struct TY_INTERFACE_INFO TY_INTERFACE_INFO

See
TYGetInterfaceList

typedef struct TY_DEVICE_BASE_INFO TY_DEVICE_BASE_INFO

See
TYGetDeviceList

typedef struct TY_FEATURE_INFO TY_FEATURE_INFO
typedef struct TY_INT_RANGE TY_INT_RANGE
typedef struct TY_FLOAT_RANGE TY_FLOAT_RANGE
typedef struct TY_ENUM_ENTRY TY_ENUM_ENTRY

enum feature entry information

See
TYGetEnumEntryInfo

typedef struct TY_VECT_3F TY_VECT_3F
typedef struct TY_CAMERA_INTRINSIC TY_CAMERA_INTRINSIC

a 3x3 matrix |.

|.|.| | ||| | fx| 0| cx| | 0| fy| cy| | 0| 0| 1|

typedef struct TY_CAMERA_EXTRINSIC TY_CAMERA_EXTRINSIC

a 4x4 matrix |.

|.|.|.| ||-|-|| |r11| r12| r13| t1| |r21| r22| r23| t2| |r31| r32| r33| t3| | 0 | 0| 0| 1|

typedef struct TY_CAMERA_DISTORTION TY_CAMERA_DISTORTION

camera distortion parameters

typedef struct TY_CAMERA_CALIB_INFO TY_CAMERA_CALIB_INFO

camera ‘s cailbration data

See
TYGetStruct

typedef struct TY_TRIGGER_PARAM TY_TRIGGER_PARAM
typedef struct TY_CAMERA_STATISTICS TY_CAMERA_STATISTICS
typedef struct TY_IMAGE_DATA TY_IMAGE_DATA
typedef struct TY_FRAME_DATA TY_FRAME_DATA
typedef struct TY_EVENT_INFO TY_EVENT_INFO
typedef void (*TY_EVENT_CALLBACK)(TY_EVENT_INFO *, void *userdata)

Enums

enum TY_STATUS_LIST

API call return status.

Values:

TY_STATUS_OK = 0
TY_STATUS_ERROR = -1001
TY_STATUS_NOT_INITED = -1002
TY_STATUS_NOT_IMPLEMENTED = -1003
TY_STATUS_NOT_PERMITTED = -1004
TY_STATUS_DEVICE_ERROR = -1005
TY_STATUS_INVALID_PARAMETER = -1006
TY_STATUS_INVALID_HANDLE = -1007
TY_STATUS_INVALID_COMPONENT = -1008
TY_STATUS_INVALID_FEATURE = -1009
TY_STATUS_WRONG_TYPE = -1010
TY_STATUS_WRONG_SIZE = -1011
TY_STATUS_OUT_OF_MEMORY = -1012
TY_STATUS_OUT_OF_RANGE = -1013
TY_STATUS_TIMEOUT = -1014
TY_STATUS_WRONG_MODE = -1015
TY_STATUS_BUSY = -1016
TY_STATUS_IDLE = -1017
TY_STATUS_NO_DATA = -1018
TY_STATUS_NO_BUFFER = -1019
TY_STATUS_NULL_POINTER = -1020
TY_STATUS_READONLY_FEATURE = -1021
TY_STATUS_INVALID_DESCRIPTOR = -1022
TY_STATUS_INVALID_INTERFACE = -1023
TY_STATUS_FIRMWARE_ERROR = -1024
enum TY_EVENT_LIST

Values:

TY_EVENT_DEVICE_OFFLINE = -2001
TY_EVENT_LICENSE_ERROR = -2002
TY_EVENT_FW_INIT_ERROR = -2003
enum TY_DEVICE_COMPONENT_LIST

Device Component list A device contains several component.

Each component can be controlled by its own features, such as image width, exposure time, etc..

See
To Know how to get feature information please refer to sample code DumpAllFeatures

Values:

TY_COMPONENT_DEVICE = 0x80000000

Abstract component stands for whole device, always enabled.

TY_COMPONENT_DEPTH_CAM = 0x00010000

Depth camera.

TY_COMPONENT_IR_CAM_LEFT = 0x00040000

Left IR camera.

TY_COMPONENT_IR_CAM_RIGHT = 0x00080000

Right IR camera.

TY_COMPONENT_RGB_CAM_LEFT = 0x00100000

Left RGB camera.

TY_COMPONENT_RGB_CAM_RIGHT = 0x00200000

Right RGB camera.

TY_COMPONENT_LASER = 0x00400000

Laser.

TY_COMPONENT_IMU = 0x00800000

Inertial Measurement Unit.

TY_COMPONENT_BRIGHT_HISTO = 0x01000000

virtual component for brightness histogram of ir

TY_COMPONENT_RGB_CAM = TY_COMPONENT_RGB_CAM_LEFT

Some device has only one RGB camera, map it to left.

enum TY_FEATURE_TYPE_LIST

Feature Format Type definitions.

Values:

TY_FEATURE_INT = 0x1000
TY_FEATURE_FLOAT = 0X2000
TY_FEATURE_ENUM = 0x3000
TY_FEATURE_BOOL = 0x4000
TY_FEATURE_STRING = 0x5000
TY_FEATURE_BYTEARRAY = 0x6000
TY_FEATURE_STRUCT = 0x7000
enum TY_FEATURE_ID_LIST

feature for component definitions

Values:

TY_STRUCT_CAM_INTRINSIC = 0x0000 | TY_FEATURE_STRUCT

see TY_CAMERA_INTRINSIC

TY_STRUCT_EXTRINSIC_TO_LEFT_IR = 0x0001 | TY_FEATURE_STRUCT

extrinsic from current component to left IR, see TY_CAMERA_EXTRINSIC

TY_STRUCT_CAM_DISTORTION = 0x0006 | TY_FEATURE_STRUCT

see TY_CAMERA_DISTORTION

TY_STRUCT_CAM_CALIB_DATA = 0x0007 | TY_FEATURE_STRUCT

see TY_CAMERA_CALIB_INFO

TY_INT_PERSISTENT_IP = 0x0010 | TY_FEATURE_INT
TY_INT_PERSISTENT_SUBMASK = 0x0011 | TY_FEATURE_INT
TY_INT_PERSISTENT_GATEWAY = 0x0012 | TY_FEATURE_INT
TY_BOOL_GVSP_RESEND = 0x0013 | TY_FEATURE_BOOL
TY_INT_PACKET_DELAY = 0x0014 | TY_FEATURE_INT

microseconds

TY_INT_ACCEPTABLE_PERCENT = 0x0015 | TY_FEATURE_INT
TY_STRUCT_CAM_STATISTICS = 0x00ff | TY_FEATURE_STRUCT

statistical information, see TY_CAMERA_STATISTICS

TY_INT_WIDTH_MAX = 0x0100 | TY_FEATURE_INT
TY_INT_HEIGHT_MAX = 0x0101 | TY_FEATURE_INT
TY_INT_OFFSET_X = 0x0102 | TY_FEATURE_INT
TY_INT_OFFSET_Y = 0x0103 | TY_FEATURE_INT
TY_INT_WIDTH = 0x0104 | TY_FEATURE_INT

Image width.

TY_INT_HEIGHT = 0x0105 | TY_FEATURE_INT

Image height.

TY_ENUM_IMAGE_MODE = 0x0109 | TY_FEATURE_ENUM

Resolution-PixelFromat mode, see TY_IMAGE_MODE_LIST.

TY_FLOAT_SCALE_UNIT = 0x010a | TY_FEATURE_FLOAT
TY_ENUM_TRIGGER_ACTIVATION = 0x0201 | TY_FEATURE_ENUM

Trigger activation, see TY_TRIGGER_ACTIVATION_LIST.

TY_INT_FRAME_PER_TRIGGER = 0x0202 | TY_FEATURE_INT

Number of frames captured per trigger.

TY_STRUCT_TRIGGER_PARAM = 0x0523 | TY_FEATURE_STRUCT

param of trigger, see TY_TRIGGER_PARAM

TY_BOOL_KEEP_ALIVE_ONOFF = 0x0203 | TY_FEATURE_BOOL

Keep Alive switch.

TY_INT_KEEP_ALIVE_TIMEOUT = 0x0204 | TY_FEATURE_INT

Keep Alive timeout.

TY_BOOL_CMOS_SYNC = 0x0205 | TY_FEATURE_BOOL

Cmos sync switch.

TY_INT_TRIGGER_DELAY_US = 0x0206 | TY_FEATURE_INT

Trigger delay time, in microseconds.

TY_BOOL_TRIGGER_OUT_IO = 0x0207 | TY_FEATURE_BOOL

Trigger out IO.

TY_BOOL_AUTO_EXPOSURE = 0x0300 | TY_FEATURE_BOOL

Auto exposure switch.

TY_INT_EXPOSURE_TIME = 0x0301 | TY_FEATURE_INT

Exposure time in percentage.

TY_BOOL_AUTO_GAIN = 0x0302 | TY_FEATURE_BOOL

Auto gain switch.

TY_INT_GAIN = 0x0303 | TY_FEATURE_INT

Sensor Gain.

TY_BOOL_AUTO_AWB = 0x0304 | TY_FEATURE_BOOL

Auto white balance.

TY_INT_LASER_POWER = 0x0500 | TY_FEATURE_INT

Laser power level.

TY_BOOL_LASER_AUTO_CTRL = 0x0501 | TY_FEATURE_BOOL

Laser auto ctrl.

TY_BOOL_UNDISTORTION = 0x0510 | TY_FEATURE_BOOL

Output undistorted image.

TY_BOOL_BRIGHTNESS_HISTOGRAM = 0x0511 | TY_FEATURE_BOOL

Output bright histogram.

TY_BOOL_DEPTH_POSTPROC = 0x0512 | TY_FEATURE_BOOL

Do depth image postproc.

TY_INT_R_GAIN = 0x0520 | TY_FEATURE_INT

Gain of R channel.

TY_INT_G_GAIN = 0x0521 | TY_FEATURE_INT

Gain of G channel.

TY_INT_B_GAIN = 0x0522 | TY_FEATURE_INT

Gain of B channel.

TY_INT_ANALOG_GAIN = 0x0524 | TY_FEATURE_INT

Analog gain.

enum TY_TRIGGER_ACTIVATION_LIST

set external trigger signal edge

See
refer to sample SimpleView_TriggerMode for detail usage

Values:

TY_TRIGGER_ACTIVATION_FALLINGEDGE = 0
TY_TRIGGER_ACTIVATION_RISINGEDGE = 1
enum TY_INTERFACE_TYPE_LIST

interface type definition

Values:

TY_INTERFACE_UNKNOWN = 0
TY_INTERFACE_RAW = 1
TY_INTERFACE_USB = 2
TY_INTERFACE_ETHERNET = 4
TY_INTERFACE_IEEE80211 = 8
TY_INTERFACE_ALL = 0xffff
enum TY_ACCESS_MODE_LIST

a feature is readable or writable

Values:

TY_ACCESS_READABLE = 0x1
TY_ACCESS_WRITABLE = 0x2
enum TY_PIXEL_BITS_LIST

Pixel size type definitions.

Values:

TY_PIXEL_8BIT = 0x1 << 28
TY_PIXEL_16BIT = 0x2 << 28
TY_PIXEL_24BIT = 0x3 << 28
TY_PIXEL_32BIT = 0x4 << 28
enum TY_PIXEL_FORMAT_LIST

pixel format definitions

Values:

TY_PIXEL_FORMAT_UNDEFINED = 0
TY_PIXEL_FORMAT_MONO = (TY_PIXEL_8BIT | (0x0 << 24))

0x10000000

TY_PIXEL_FORMAT_BAYER8GB = (TY_PIXEL_8BIT | (0x1 << 24))

0x11000000

TY_PIXEL_FORMAT_DEPTH16 = (TY_PIXEL_16BIT | (0x0 << 24))

0x20000000

TY_PIXEL_FORMAT_YVYU = (TY_PIXEL_16BIT | (0x1 << 24))

0x21000000, yvyu422

TY_PIXEL_FORMAT_YUYV = (TY_PIXEL_16BIT | (0x2 << 24))

0x22000000, yuyv422

TY_PIXEL_FORMAT_RGB = (TY_PIXEL_24BIT | (0x0 << 24))

0x30000000

TY_PIXEL_FORMAT_BGR = (TY_PIXEL_24BIT | (0x1 << 24))

0x31000000

TY_PIXEL_FORMAT_JPEG = (TY_PIXEL_24BIT | (0x2 << 24))

0x32000000

TY_PIXEL_FORMAT_MJPG = (TY_PIXEL_24BIT | (0x3 << 24))

0x33000000

enum TY_RESOLUTION_MODE_LIST

predefined resolution list

Values:

TY_RESOLUTION_MODE_160x120 = (160<<12)+120

0x000a0078

TY_RESOLUTION_MODE_240x320 = (240<<12)+320

0x000f0140

TY_RESOLUTION_MODE_320x180 = (320<<12)+180

0x001400b4

TY_RESOLUTION_MODE_320x200 = (320<<12)+200

0x001400c8

TY_RESOLUTION_MODE_320x240 = (320<<12)+240

0x001400f0

TY_RESOLUTION_MODE_480x640 = (480<<12)+640

0x001e0280

TY_RESOLUTION_MODE_640x360 = (640<<12)+360

0x00280168

TY_RESOLUTION_MODE_640x400 = (640<<12)+400

0x00280190

TY_RESOLUTION_MODE_640x480 = (640<<12)+480

0x002801e0

TY_RESOLUTION_MODE_960x1280 = (960<<12)+1280

0x003c0500

TY_RESOLUTION_MODE_1280x720 = (1280<<12)+720

0x005002d0

TY_RESOLUTION_MODE_1280x800 = (1280<<12)+800

0x00500320

TY_RESOLUTION_MODE_1280x960 = (1280<<12)+960

0x005003c0

TY_RESOLUTION_MODE_2592x1944 = (2592<<12)+1944

0x00a20798

enum TY_IMAGE_MODE_LIST

Predefined Image Mode List image mode controls image resolution & format named like TY_IMAGE_MODE_MONO_160x120.

Values:

TY_DECLARE_IMAGE_MODE1 =(MONO)
TY_DECLARE_IMAGE_MODE1 =(MONO)
TY_DECLARE_IMAGE_MODE1 =(MONO)
TY_DECLARE_IMAGE_MODE1 =(MONO)
TY_DECLARE_IMAGE_MODE1 =(MONO)
TY_DECLARE_IMAGE_MODE1 =(MONO)
enum TY_TRIGGER_MODE_LIST

See
refer to sample SimpleView_TriggerMode for detail usage

Values:

TY_TRIGGER_MODE_OFF = 0

not trigger mode, continuous mode

TY_TRIGGER_MODE_SLAVE = 1

slave mode, receive soft/hardware triggers

TY_TRIGGER_MODE_M_SIG = 2

master mode 1, sending one trigger signal once received a soft/hardware trigger

TY_TRIGGER_MODE_M_PER = 3

master mode 2, periodic sending one trigger signals, ‘fps’ param should be set

Functions

static bool TYIsNetworkInterface(int32_t interfaceType)
static void TYIntToIPv4(uint32_t addr, uint8_t out[4])
static uint32_t TYIPv4ToInt(uint8_t ip[4])
static TY_IMAGE_DATA TYInitImageData(size_t size, void *buffer, size_t width, size_t height)

init a TY_IMAGE_DATA struct

static TY_FEATURE_TYPE TYFeatureType(TY_FEATURE_ID id)

get feature format type from feature id

static int32_t TYPixelSize(TY_IMAGE_MODE imageMode)

get pixel size in byte

static TY_IMAGE_MODE TYImageMode(TY_PIXEL_FORMAT pix, TY_RESOLUTION_MODE res)

make a image mode from pixel format & resolution mode

static TY_RESOLUTION_MODE TYResolutionMode2(int width, int height)

get a resoltuion mode from width & height

static TY_IMAGE_MODE TYImageMode2(TY_PIXEL_FORMAT pix, int width, int height)

create a image mode from pixel format , width & height

static TY_PIXEL_FORMAT TYPixelFormat(TY_IMAGE_MODE imageMode)

get pixel format from image mode

static TY_RESOLUTION_MODE TYResolutionMode(TY_IMAGE_MODE imageMode)

get a resoltuion mode from image mode

static int32_t TYImageWidth(TY_IMAGE_MODE imageMode)

get image width from image mode

static int32_t TYImageHeight(TY_IMAGE_MODE imageMode)

get image height from image mode

TY_EXTC TY_EXPORT const char *TY_STDC TYErrorString(TY_STATUS errorID)

Get error information.

Return
Error string.
Parameters
  • errorID: Error id.

TY_STATUS TYInitLib(void)

Init this library.

We make this function to be static inline, because we do a version check here. Some user may use the mismatched header file and dynamic library, and that’s quite difficult to locate the error.

Return Value
  • TY_STATUS_OK: Succeed.
  • TY_STATUS_ERROR: Has been inited.

TY_CAPI TYDeinitLib(void)

Deinit this library.

Return Value
  • TY_STATUS_OK: Succeed.

TY_CAPI TYLibVersion(TY_VERSION_INFO *version)

Get current library version.

Parameters
  • version: Version infomation to be filled.
Return Value
  • TY_STATUS_OK: Succeed.
  • TY_STATUS_NULL_POINTER: buffer is NULL.

TY_CAPI TYUpdateInterfaceList()

Update current interfaces.

call before TYGetInterfaceList

Return Value
  • TY_STATUS_OK: Succeed.
  • TY_STATUS_NOT_INITED: TYInitLib not called.

TY_CAPI TYGetInterfaceNumber(uint32_t *pNumIfaces)

Get number of current interfaces.

Parameters
  • pNumIfaces: Number of interfaces.
Return Value
  • TY_STATUS_OK: Succeed.
  • TY_STATUS_NOT_INITED: TYInitLib not called.
  • TY_STATUS_NULL_POINTER: deviceNumber is NULL.

TY_CAPI TYGetInterfaceList(TY_INTERFACE_INFO *pIfaceInfos, uint32_t bufferCount, uint32_t *filledCount)

Get interface info list.

Parameters
  • pIfaceInfos: Array of interface infos to be filled.
  • bufferCount: Array size of interface infos.
  • filledCount: Number of filled TY_INTERFACE_INFO.
Return Value
  • TY_STATUS_OK: Succeed.
  • TY_STATUS_NOT_INITED: TYInitLib not called.
  • TY_STATUS_NULL_POINTER: pIfaceInfos or filledCount is NULL.

TY_CAPI TYHasInterface(const char *ifaceID, bool *value)

Check if has interface.

See
TYGetInterfaceList
Parameters
  • ifaceID: Interface ID string, can be get from TY_INTERFACE_INFO.
  • value: True if the interface exists.
Return Value
  • TY_STATUS_OK: Succeed.
  • TY_STATUS_NOT_INITED: TYInitLib not called.
  • TY_STATUS_NULL_POINTER: ifaceID or outHandle is NULL.

TY_CAPI TYOpenInterface(const char *ifaceID, TY_INTERFACE_HANDLE *outHandle)

Open specified interface.

See
TYGetInterfaceList
Parameters
  • ifaceID: Interface ID string, can be get from TY_INTERFACE_INFO.
  • outHandle: Handle of opened interface.
Return Value
  • TY_STATUS_OK: Succeed.
  • TY_STATUS_NOT_INITED: TYInitLib not called.
  • TY_STATUS_NULL_POINTER: ifaceID or outHandle is NULL.
  • TY_STATUS_INVALID_INTERFACE: Interface not found.

TY_CAPI TYCloseInterface(TY_INTERFACE_HANDLE ifaceHandle)

Close interface.

Parameters
  • ifaceHandle: Interface to be closed.
Return Value
  • TY_STATUS_OK: Succeed.
  • TY_STATUS_NOT_INITED: TYInitLib not called.
  • TY_STATUS_INVALID_INTERFACE: Interface not found.

TY_CAPI TYUpdateDeviceList(TY_INTERFACE_HANDLE ifaceHandle)

Update current connected devices.

Parameters
  • ifaceHandle: Interface handle.
Return Value
  • TY_STATUS_OK: Succeed.
  • TY_STATUS_NOT_INITED: TYInitLib not called.
  • TY_STATUS_INVALID_INTERFACE: Invalid interface handle.

TY_CAPI TYGetDeviceNumber(TY_INTERFACE_HANDLE ifaceHandle, uint32_t *deviceNumber)

Get number of current connected devices.

Parameters
  • ifaceHandle: Interface handle.
  • deviceNumber: Number of connected devices.
Return Value
  • TY_STATUS_OK: Succeed.
  • TY_STATUS_NOT_INITED: TYInitLib not called.
  • TY_STATUS_INVALID_INTERFACE: Invalid interface handle.
  • TY_STATUS_NULL_POINTER: deviceNumber is NULL.

TY_CAPI TYGetDeviceList(TY_INTERFACE_HANDLE ifaceHandle, TY_DEVICE_BASE_INFO *deviceInfos, uint32_t bufferCount, uint32_t *filledDeviceCount)

Get device info list.

Parameters
  • ifaceHandle: Interface handle.
  • deviceInfos: Device info array to be filled.
  • bufferCount: Array size of deviceInfos.
  • filledDeviceCount: Number of filled TY_DEVICE_BASE_INFO.
Return Value
  • TY_STATUS_OK: Succeed.
  • TY_STATUS_NOT_INITED: TYInitLib not called.
  • TY_STATUS_INVALID_INTERFACE: Invalid interface handle.
  • TY_STATUS_NULL_POINTER: deviceInfos or filledDeviceCount is NULL.

TY_CAPI TYHasDevice(TY_INTERFACE_HANDLE ifaceHandle, const char *deviceID, bool *value)

Check whether the interface has the specified device.

Parameters
  • ifaceHandle: Interface handle.
  • deviceID: Device ID string, can be get from TY_DEVICE_BASE_INFO.
  • value: True if the device exists.
Return Value
  • TY_STATUS_OK: Succeed.
  • TY_STATUS_NOT_INITED: TYInitLib not called.
  • TY_STATUS_INVALID_INTERFACE: Invalid interface handle.
  • TY_STATUS_NULL_POINTER: deviceID or value is NULL.

TY_CAPI TYOpenDevice(TY_INTERFACE_HANDLE ifaceHandle, const char *deviceID, TY_DEV_HANDLE *outDeviceHandle)

Open device by device ID.

Parameters
  • ifaceHandle: Interface handle.
  • deviceID: Device ID string, can be get from TY_DEVICE_BASE_INFO.
  • deviceHandle: Handle of opened device.
Return Value
  • TY_STATUS_OK: Succeed.
  • TY_STATUS_NOT_INITED: TYInitLib not called.
  • TY_STATUS_INVALID_INTERFACE: Invalid interface handle.
  • TY_STATUS_NULL_POINTER: deviceID or deviceHandle is NULL.
  • TY_STATUS_INVALID_PARAMETER: Device not found.
  • TY_STATUS_BUSY: Device has been opened.
  • TY_STATUS_DEVICE_ERROR: Open device failed.

TY_CAPI TYOpenDeviceWithIP(TY_INTERFACE_HANDLE ifaceHandle, const char *IP, TY_DEV_HANDLE *deviceHandle)

Open device by device IP, useful when a device is not listed.

Parameters
  • ifaceHandle: Interface handle.
  • IP: Device IP.
  • deviceHandle: Handle of opened device.
Return Value
  • TY_STATUS_OK: Succeed.
  • TY_STATUS_NOT_INITED: TYInitLib not called.
  • TY_STATUS_INVALID_INTERFACE: Invalid interface handle.
  • TY_STATUS_NULL_POINTER: IP or deviceHandle is NULL.
  • TY_STATUS_INVALID_PARAMETER: Device not found.
  • TY_STATUS_BUSY: Device has been opened, may occupied somewhere else.
  • TY_STATUS_DEVICE_ERROR: Open device failed.

TY_CAPI TYGetDeviceInterface(TY_DEV_HANDLE hDevice, TY_INTERFACE_HANDLE *pIface)

Get interface handle by device handle.

Parameters
  • hDevice: Device handle.
  • pIface: Interface handle.
Return Value
  • TY_STATUS_OK: Succeed.
  • TY_STATUS_INVALID_HANDLE: Invalid device handle.
  • TY_STATUS_NULL_POINTER: pIface is NULL.

TY_CAPI TYForceDeviceIP(TY_INTERFACE_HANDLE ifaceHandle, const char *MAC, const char *newIP, const char *newNetMask, const char *newGateway)

Force a ethernet device to use new IP address, useful when device use persistent IP and cannot be found.

Parameters
  • ifaceHandle: Interface handle.
  • MAC: Device MAC, should be “xx:xx:xx:xx:xx:xx”.
  • newIP: New IP.
  • newNetMask: New subnet mask.
  • newGateway: New gateway.
Return Value
  • TY_STATUS_OK: Succeed.
  • TY_STATUS_NOT_INITED: TYInitLib not called.
  • TY_STATUS_INVALID_INTERFACE: Invalid interface handle.
  • TY_STATUS_WRONG_TYPE: Wrong interface type, should be network.
  • TY_STATUS_NULL_POINTER: MAC or newIP/newNetMask/newGateway is NULL.
  • TY_STATUS_INVALID_PARAMETER: MAC is not valid.
  • TY_STATUS_TIMEOUT: No device found.
  • TY_STATUS_DEVICE_ERROR: Set new IP failed.

TY_CAPI TYCloseDevice(TY_DEV_HANDLE hDevice)

Close device by device handle.

Parameters
  • hDevice: Device handle.
Return Value
  • TY_STATUS_OK: Succeed.
  • TY_STATUS_INVALID_HANDLE: Invalid device handle.
  • TY_STATUS_IDLE: Device has been closed.

TY_CAPI TYGetDeviceInfo(TY_DEV_HANDLE hDevice, TY_DEVICE_BASE_INFO *info)

Get base info of the open device.

Parameters
  • hDevice: Device handle.
  • info: Base info out.
Return Value
  • TY_STATUS_OK: Succeed.
  • TY_STATUS_INVALID_HANDLE: Invalid device handle.
  • TY_STATUS_NULL_POINTER: componentIDs is NULL.

TY_CAPI TYGetComponentIDs(TY_DEV_HANDLE hDevice, int32_t *componentIDs)

Get all components IDs.

See
TY_DEVICE_COMPONENT_LIST
Parameters
  • hDevice: Device handle.
  • componentIDs: All component IDs this device has. (bit flag).
Return Value
  • TY_STATUS_OK: Succeed.
  • TY_STATUS_INVALID_HANDLE: Invalid device handle.
  • TY_STATUS_NULL_POINTER: componentIDs is NULL.

TY_CAPI TYGetEnabledComponents(TY_DEV_HANDLE hDevice, int32_t *componentIDs)

Get all enabled components IDs.

See
TY_DEVICE_COMPONENT_LIST
Parameters
  • hDevice: Device handle.
  • componentIDs: Enabled component IDs.(bit flag)
Return Value
  • TY_STATUS_OK: Succeed.
  • TY_STATUS_INVALID_HANDLE: Invalid device handle.
  • TY_STATUS_NULL_POINTER: componentIDs is NULL.

TY_CAPI TYEnableComponents(TY_DEV_HANDLE hDevice, int32_t componentIDs)

Enable components.

Parameters
  • hDevice: Device handle.
  • componentIDs: Components to be enabled.
Return Value
  • TY_STATUS_OK: Succeed.
  • TY_STATUS_INVALID_HANDLE: Invalid device handle.
  • TY_STATUS_INVALID_COMPONENT: Some components specified by componentIDs are invalid.
  • TY_STATUS_BUSY: Device is capturing.

TY_CAPI TYDisableComponents(TY_DEV_HANDLE hDevice, int32_t componentIDs)

Disable components.

See
TY_DEVICE_COMPONENT_LIST
Parameters
  • hDevice: Device handle.
  • componentIDs: Components to be disabled.
Return Value
  • TY_STATUS_OK: Succeed.
  • TY_STATUS_INVALID_HANDLE: Invalid device handle.
  • TY_STATUS_INVALID_COMPONENT: Some components specified by componentIDs are invalid.
  • TY_STATUS_BUSY: Device is capturing.

TY_CAPI TYGetFrameBufferSize(TY_DEV_HANDLE hDevice, uint32_t *bufferSize)

Get total buffer size of one frame in current configuration.

Parameters
  • hDevice: Device handle.
  • bufferSize: Buffer size per frame.
Return Value
  • TY_STATUS_OK: Succeed.
  • TY_STATUS_INVALID_HANDLE: Invalid device handle.
  • TY_STATUS_NULL_POINTER: bufferSize is NULL.

TY_CAPI TYEnqueueBuffer(TY_DEV_HANDLE hDevice, void *buffer, uint32_t bufferSize)

Enqueue a user allocated buffer.

Parameters
  • hDevice: Device handle.
  • buffer: Buffer to be enqueued.
  • bufferSize: Size of the input buffer.
Return Value
  • TY_STATUS_OK: Succeed.
  • TY_STATUS_INVALID_HANDLE: Invalid device handle.
  • TY_STATUS_NULL_POINTER: buffer is NULL.
  • TY_STATUS_WRONG_SIZE: The input buffer is not large enough.

TY_CAPI TYClearBufferQueue(TY_DEV_HANDLE hDevice)

Clear the internal buffer queue, so that user can release all the buffer.

Parameters
  • hDevice: Device handle.
Return Value
  • TY_STATUS_OK: Succeed.
  • TY_STATUS_INVALID_HANDLE: Invalid device handle.
  • TY_STATUS_BUSY: Device is capturing.

TY_CAPI TYStartCapture(TY_DEV_HANDLE hDevice)

Start capture.

Parameters
  • hDevice: Device handle.
Return Value
  • TY_STATUS_OK: Succeed.
  • TY_STATUS_INVALID_HANDLE: Invalid device handle.
  • TY_STATUS_INVALID_COMPONENT: No components enabled.
  • TY_STATUS_BUSY: Device has been started.
  • TY_STATUS_DEVICE_ERROR: Start capture failed.

TY_CAPI TYStopCapture(TY_DEV_HANDLE hDevice)

Stop capture.

Parameters
  • hDevice: Device handle.
Return Value
  • TY_STATUS_OK: Succeed.
  • TY_STATUS_INVALID_HANDLE: Invalid device handle.
  • TY_STATUS_IDLE: Device is not capturing.
  • TY_STATUS_DEVICE_ERROR: Stop capture failed.

TY_CAPI TYSendSoftTrigger(TY_DEV_HANDLE hDevice)

Send a software trigger to capture a frame when device works in trigger mode.

Parameters
  • hDevice: Device handle.
Return Value
  • TY_STATUS_OK: Succeed.
  • TY_STATUS_INVALID_HANDLE: Invalid device handle.
  • TY_STATUS_INVALID_FEATURE: Not support soft trigger.
  • TY_STATUS_IDLE: Device has not started capture.
  • TY_STATUS_WRONG_MODE: Not in trigger mode.

TY_CAPI TYRegisterEventCallback(TY_DEV_HANDLE hDevice, TY_EVENT_CALLBACK callback, void *userdata)

Register device status callback.

Register NULL to clean callback.

Parameters
  • hDevice: Device handle.
  • callback: Callback function.
  • userdata: User private data.
Return Value
  • TY_STATUS_OK: Succeed.
  • TY_STATUS_INVALID_HANDLE: Invalid device handle.
  • TY_STATUS_BUSY: Device is capturing.

TY_CAPI TYFetchFrame(TY_DEV_HANDLE hDevice, TY_FRAME_DATA *frame, int32_t timeout)

Fetch one frame.

Parameters
  • hDevice: Device handle.
  • frame: Frame data to be filled.
  • timeout: Timeout in milliseconds. <0 for infinite.
Return Value
  • TY_STATUS_OK: Succeed.
  • TY_STATUS_INVALID_HANDLE: Invalid device handle.
  • TY_STATUS_NULL_POINTER: frame is NULL.
  • TY_STATUS_IDLE: Device capturing is not started.
  • TY_STATUS_WRONG_MODE: Callback has been registered, this function is disabled.
  • TY_STATUS_TIMEOUT: Timeout.

TY_CAPI TYHasFeature(TY_DEV_HANDLE hDevice, TY_COMPONENT_ID componentID, TY_FEATURE_ID featureID, bool *value)

Check whether a component has a specific feature.

Parameters
  • hDevice: Device handle.
  • componentID: Component ID.
  • featureID: Feature ID.
  • value: Whether has feature.
Return Value
  • TY_STATUS_OK: Succeed.
  • TY_STATUS_INVALID_HANDLE: Invalid device handle.
  • TY_STATUS_INVALID_COMPONENT: Invalid component ID.
  • TY_STATUS_NULL_POINTER: value is NULL.

TY_CAPI TYGetFeatureInfo(TY_DEV_HANDLE hDevice, TY_COMPONENT_ID componentID, TY_FEATURE_ID featureID, TY_FEATURE_INFO *featureInfo)

Get feature info.

Parameters
  • hDevice: Device handle.
  • componentID: Component ID.
  • featureID: Feature ID.
  • featureInfo: Feature info.
Return Value
  • TY_STATUS_OK: Succeed.
  • TY_STATUS_INVALID_HANDLE: Invalid device handle.
  • TY_STATUS_INVALID_COMPONENT: Invalid component ID.
  • TY_STATUS_NULL_POINTER: featureInfo is NULL.

TY_CAPI TYGetIntRange(TY_DEV_HANDLE hDevice, TY_COMPONENT_ID componentID, TY_FEATURE_ID featureID, TY_INT_RANGE *intRange)

Get value range of integer feature.

Parameters
  • hDevice: Device handle.
  • componentID: Component ID.
  • featureID: Feature ID.
  • intRange: Integer range to be filled.
Return Value
  • TY_STATUS_OK: Succeed.
  • TY_STATUS_INVALID_HANDLE: Invalid device handle.
  • TY_STATUS_INVALID_COMPONENT: Invalid component ID.
  • TY_STATUS_INVALID_FEATURE: Invalid feature ID.
  • TY_STATUS_WRONG_TYPE: The feature’s type is not TY_FEATURE_INT.
  • TY_STATUS_NULL_POINTER: intRange is NULL.

TY_CAPI TYGetInt(TY_DEV_HANDLE hDevice, TY_COMPONENT_ID componentID, TY_FEATURE_ID featureID, int32_t *value)

Get value of integer feature.

Parameters
  • hDevice: Device handle.
  • componentID: Component ID.
  • featureID: Feature ID.
  • value: Integer value.
Return Value
  • TY_STATUS_OK: Succeed.
  • TY_STATUS_INVALID_HANDLE: Invalid device handle.
  • TY_STATUS_INVALID_COMPONENT: Invalid component ID.
  • TY_STATUS_INVALID_FEATURE: Invalid feature ID.
  • TY_STATUS_WRONG_TYPE: The feature’s type is not TY_FEATURE_INT.
  • TY_STATUS_NULL_POINTER: value is NULL.

TY_CAPI TYSetInt(TY_DEV_HANDLE hDevice, TY_COMPONENT_ID componentID, TY_FEATURE_ID featureID, int32_t value)

Set value of integer feature.

Parameters
  • hDevice: Device handle.
  • componentID: Component ID.
  • featureID: Feature ID.
  • value: Integer value.
Return Value
  • TY_STATUS_OK: Succeed.
  • TY_STATUS_INVALID_HANDLE: Invalid device handle.
  • TY_STATUS_INVALID_COMPONENT: Invalid component ID.
  • TY_STATUS_INVALID_FEATURE: Invalid feature ID.
  • TY_STATUS_NOT_PERMITTED: The feature is not writable.
  • TY_STATUS_WRONG_TYPE: The feature’s type is not TY_FEATURE_INT.
  • TY_STATUS_OUT_OF_RANGE: value is out of range.
  • TY_STATUS_BUSY: Device is capturing, the feature is locked.

TY_CAPI TYGetFloatRange(TY_DEV_HANDLE hDevice, TY_COMPONENT_ID componentID, TY_FEATURE_ID featureID, TY_FLOAT_RANGE *floatRange)

Get value range of float feature.

Parameters
  • hDevice: Device handle.
  • componentID: Component ID.
  • featureID: Feature ID.
  • floatRange: Float range to be filled.
Return Value
  • TY_STATUS_OK: Succeed.
  • TY_STATUS_INVALID_HANDLE: Invalid device handle.
  • TY_STATUS_INVALID_COMPONENT: Invalid component ID.
  • TY_STATUS_INVALID_FEATURE: Invalid feature ID.
  • TY_STATUS_WRONG_TYPE: The feature’s type is not TY_FEATURE_FLOAT.
  • TY_STATUS_NULL_POINTER: floatRange is NULL.

TY_CAPI TYGetFloat(TY_DEV_HANDLE hDevice, TY_COMPONENT_ID componentID, TY_FEATURE_ID featureID, float *value)

Get value of float feature.

Parameters
  • hDevice: Device handle.
  • componentID: Component ID.
  • featureID: Feature ID.
  • value: Float value.
Return Value
  • TY_STATUS_OK: Succeed.
  • TY_STATUS_INVALID_HANDLE: Invalid device handle.
  • TY_STATUS_INVALID_COMPONENT: Invalid component ID.
  • TY_STATUS_INVALID_FEATURE: Invalid feature ID.
  • TY_STATUS_WRONG_TYPE: The feature’s type is not TY_FEATURE_FLOAT.
  • TY_STATUS_NULL_POINTER: value is NULL.

TY_CAPI TYSetFloat(TY_DEV_HANDLE hDevice, TY_COMPONENT_ID componentID, TY_FEATURE_ID featureID, float value)

Set value of float feature.

Parameters
  • hDevice: Device handle.
  • componentID: Component ID.
  • featureID: Feature ID.
  • value: Float value.
Return Value
  • TY_STATUS_OK: Succeed.
  • TY_STATUS_INVALID_HANDLE: Invalid device handle.
  • TY_STATUS_INVALID_COMPONENT: Invalid component ID.
  • TY_STATUS_INVALID_FEATURE: Invalid feature ID.
  • TY_STATUS_NOT_PERMITTED: The feature is not writable.
  • TY_STATUS_WRONG_TYPE: The feature’s type is not TY_FEATURE_FLOAT.
  • TY_STATUS_OUT_OF_RANGE: value is out of range.
  • TY_STATUS_BUSY: Device is capturing, the feature is locked.

TY_CAPI TYGetEnumEntryCount(TY_DEV_HANDLE hDevice, TY_COMPONENT_ID componentID, TY_FEATURE_ID featureID, uint32_t *entryCount)

Get number of enum entries.

Parameters
  • hDevice: Device handle.
  • componentID: Component ID.
  • featureID: Feature ID.
  • entryCount: Entry count.
Return Value
  • TY_STATUS_OK: Succeed.
  • TY_STATUS_INVALID_HANDLE: Invalid device handle.
  • TY_STATUS_INVALID_COMPONENT: Invalid component ID.
  • TY_STATUS_INVALID_FEATURE: Invalid feature ID.
  • TY_STATUS_WRONG_TYPE: The feature’s type is not TY_FEATURE_ENUM.
  • TY_STATUS_NULL_POINTER: entryCount is NULL.

TY_CAPI TYGetEnumEntryInfo(TY_DEV_HANDLE hDevice, TY_COMPONENT_ID componentID, TY_FEATURE_ID featureID, TY_ENUM_ENTRY *entries, uint32_t entryCount, uint32_t *filledEntryCount)

Get list of enum entries.

Parameters
  • hDevice: Device handle.
  • componentID: Component ID.
  • featureID: Feature ID.
  • entries: Output entries.
  • entryCount: Array size of input parameter “entries”.
  • filledEntryCount: Number of filled entries.
Return Value
  • TY_STATUS_OK: Succeed.
  • TY_STATUS_INVALID_HANDLE: Invalid device handle.
  • TY_STATUS_INVALID_COMPONENT: Invalid component ID.
  • TY_STATUS_INVALID_FEATURE: Invalid feature ID.
  • TY_STATUS_WRONG_TYPE: The feature’s type is not TY_FEATURE_ENUM.
  • TY_STATUS_NULL_POINTER: entries or filledEntryCount is NULL.

TY_CAPI TYGetEnum(TY_DEV_HANDLE hDevice, TY_COMPONENT_ID componentID, TY_FEATURE_ID featureID, int32_t *value)

Get current value of enum feature.

Parameters
  • hDevice: Device handle.
  • componentID: Component ID.
  • featureID: Feature ID.
  • value: Enum value.
Return Value
  • TY_STATUS_OK: Succeed.
  • TY_STATUS_INVALID_HANDLE: Invalid device handle.
  • TY_STATUS_INVALID_COMPONENT: Invalid component ID.
  • TY_STATUS_INVALID_FEATURE: Invalid feature ID.
  • TY_STATUS_WRONG_TYPE: The feature’s type is not TY_FEATURE_ENUM.
  • TY_STATUS_NULL_POINTER: value is NULL.

TY_CAPI TYSetEnum(TY_DEV_HANDLE hDevice, TY_COMPONENT_ID componentID, TY_FEATURE_ID featureID, int32_t value)

Set value of enum feature.

Parameters
  • hDevice: Device handle.
  • componentID: Component ID.
  • featureID: Feature ID.
  • value: Enum value.
Return Value
  • TY_STATUS_OK: Succeed.
  • TY_STATUS_INVALID_HANDLE: Invalid device handle.
  • TY_STATUS_INVALID_COMPONENT: Invalid component ID.
  • TY_STATUS_INVALID_FEATURE: Invalid feature ID.
  • TY_STATUS_NOT_PERMITTED: The feature is not writable.
  • TY_STATUS_WRONG_TYPE: The feature’s type is not TY_FEATURE_ENUM.
  • TY_STATUS_INVALID_PARAMETER: value is invalid.
  • TY_STATUS_BUSY: Device is capturing, the feature is locked.

TY_CAPI TYGetBool(TY_DEV_HANDLE hDevice, TY_COMPONENT_ID componentID, TY_FEATURE_ID featureID, bool *value)

Get value of bool feature.

Parameters
  • hDevice: Device handle.
  • componentID: Component ID.
  • featureID: Feature ID.
  • value: Bool value.
Return Value
  • TY_STATUS_OK: Succeed.
  • TY_STATUS_INVALID_HANDLE: Invalid device handle.
  • TY_STATUS_INVALID_COMPONENT: Invalid component ID.
  • TY_STATUS_INVALID_FEATURE: Invalid feature ID.
  • TY_STATUS_WRONG_TYPE: The feature’s type is not TY_FEATURE_BOOL.
  • TY_STATUS_NULL_POINTER: value is NULL.

TY_CAPI TYSetBool(TY_DEV_HANDLE hDevice, TY_COMPONENT_ID componentID, TY_FEATURE_ID featureID, bool value)

Set value of bool feature.

Parameters
  • hDevice: Device handle.
  • componentID: Component ID.
  • featureID: Feature ID.
  • value: Bool value.
Return Value
  • TY_STATUS_OK: Succeed.
  • TY_STATUS_INVALID_HANDLE: Invalid device handle.
  • TY_STATUS_INVALID_COMPONENT: Invalid component ID.
  • TY_STATUS_INVALID_FEATURE: Invalid feature ID.
  • TY_STATUS_NOT_PERMITTED: The feature is not writable.
  • TY_STATUS_WRONG_TYPE: The feature’s type is not TY_FEATURE_BOOL.
  • TY_STATUS_BUSY: Device is capturing, the feature is locked.

TY_CAPI TYGetStringLength(TY_DEV_HANDLE hDevice, TY_COMPONENT_ID componentID, TY_FEATURE_ID featureID, uint32_t *size)

Get internal buffer size of string feature.

See
TYGetString
Parameters
  • hDevice: Device handle.
  • componentID: Component ID.
  • featureID: Feature ID.
  • size: String length including ‘\0’.
Return Value
  • TY_STATUS_OK: Succeed.
  • TY_STATUS_INVALID_HANDLE: Invalid device handle.
  • TY_STATUS_INVALID_COMPONENT: Invalid component ID.
  • TY_STATUS_INVALID_FEATURE: Invalid feature ID.
  • TY_STATUS_WRONG_TYPE: The feature’s type is not TY_FEATURE_STRING.
  • TY_STATUS_NULL_POINTER: size is NULL.

TY_CAPI TYGetString(TY_DEV_HANDLE hDevice, TY_COMPONENT_ID componentID, TY_FEATURE_ID featureID, char *buffer, uint32_t bufferSize)

Get value of string feature.

See
TYGetStringLength
Parameters
  • hDevice: Device handle.
  • componentID: Component ID.
  • featureID: Feature ID.
  • buffer: String buffer.
  • bufferSize: Size of buffer.
Return Value
  • TY_STATUS_OK: Succeed.
  • TY_STATUS_INVALID_HANDLE: Invalid device handle.
  • TY_STATUS_INVALID_COMPONENT: Invalid component ID.
  • TY_STATUS_INVALID_FEATURE: Invalid feature ID.
  • TY_STATUS_WRONG_TYPE: The feature’s type is not TY_FEATURE_STRING.
  • TY_STATUS_NULL_POINTER: buffer is NULL.

TY_CAPI TYSetString(TY_DEV_HANDLE hDevice, TY_COMPONENT_ID componentID, TY_FEATURE_ID featureID, const char *buffer)

Set value of string feature.

Parameters
  • hDevice: Device handle.
  • componentID: Component ID.
  • featureID: Feature ID.
  • buffer: String buffer.
Return Value
  • TY_STATUS_OK: Succeed.
  • TY_STATUS_INVALID_HANDLE: Invalid device handle.
  • TY_STATUS_INVALID_COMPONENT: Invalid component ID.
  • TY_STATUS_INVALID_FEATURE: Invalid feature ID.
  • TY_STATUS_NOT_PERMITTED: The feature is not writable.
  • TY_STATUS_WRONG_TYPE: The feature’s type is not TY_FEATURE_STRING.
  • TY_STATUS_NULL_POINTER: buffer is NULL.
  • TY_STATUS_OUT_OF_RANGE: Input string is too long.
  • TY_STATUS_BUSY: Device is capturing, the feature is locked.

TY_CAPI TYGetStruct(TY_DEV_HANDLE hDevice, TY_COMPONENT_ID componentID, TY_FEATURE_ID featureID, void *pStruct, uint32_t structSize)

Get value of struct.

Parameters
  • hDevice: Device handle.
  • componentID: Component ID.
  • featureID: Feature ID.
  • pStruct: Pointer of struct.
  • structSize: Size of input buffer pStruct..
Return Value
  • TY_STATUS_OK: Succeed.
  • TY_STATUS_INVALID_HANDLE: Invalid device handle.
  • TY_STATUS_INVALID_COMPONENT: Invalid component ID.
  • TY_STATUS_INVALID_FEATURE: Invalid feature ID.
  • TY_STATUS_WRONG_TYPE: The feature’s type is not TY_FEATURE_STRUCT.
  • TY_STATUS_NULL_POINTER: pStruct is NULL.
  • TY_STATUS_WRONG_SIZE: structSize incorrect.

TY_CAPI TYSetStruct(TY_DEV_HANDLE hDevice, TY_COMPONENT_ID componentID, TY_FEATURE_ID featureID, void *pStruct, uint32_t structSize)

Set value of struct.

Parameters
  • hDevice: Device handle.
  • componentID: Component ID.
  • featureID: Feature ID.
  • pStruct: Pointer of struct.
  • structSize: Size of struct.
Return Value
  • TY_STATUS_OK: Succeed.
  • TY_STATUS_INVALID_HANDLE: Invalid device handle.
  • TY_STATUS_INVALID_COMPONENT: Invalid component ID.
  • TY_STATUS_INVALID_FEATURE: Invalid feature ID.
  • TY_STATUS_NOT_PERMITTED: The feature is not writable.
  • TY_STATUS_WRONG_TYPE: The feature’s type is not TY_FEATURE_STRUCT.
  • TY_STATUS_NULL_POINTER: pStruct is NULL.
  • TY_STATUS_WRONG_SIZE: structSize incorrect.
  • TY_STATUS_BUSY: Device is capturing, the feature is locked.

TY_CAPI _TYInitLib(void)
struct TY_VERSION_INFO
#include <TYApi.h>

Public Members

int32_t major
int32_t minor
int32_t patch
int32_t reserved
struct TY_DEVICE_NET_INFO
#include <TYApi.h>

Public Members

char mac[32]
char ip[32]
char netmask[32]
char gateway[32]
char broadcast[32]
char reserved[96]
struct TY_DEVICE_USB_INFO
#include <TYApi.h>

Public Members

int bus
int addr
char reserved[248]
struct TY_INTERFACE_INFO
#include <TYApi.h>

See
TYGetInterfaceList

Public Members

char name[32]
char id[32]
TY_INTERFACE_TYPE type
char reserved[4]
TY_DEVICE_NET_INFO netInfo
struct TY_DEVICE_BASE_INFO
#include <TYApi.h>

See
TYGetDeviceList

Public Members

TY_INTERFACE_INFO iface
char id[32]

device serial number

char vendorName[32]
char modelName[32]

device model name

TY_VERSION_INFO hardwareVersion

deprecated

TY_VERSION_INFO firmwareVersion

deprecated

TY_DEVICE_NET_INFO netInfo
TY_DEVICE_USB_INFO usbInfo
union TY_DEVICE_BASE_INFO::@0 @1
char reserved[256]
struct TY_FEATURE_INFO
#include <TYApi.h>

Public Members

bool isValid

true if feature exists, false otherwise

TY_ACCESS_MODE accessMode

feature access privilege

bool writableAtRun

feature can be written while capturing

char reserved0[1]
TY_COMPONENT_ID componentID

owner of this feature

TY_FEATURE_ID featureID

feature unique id

char name[32]

describe string

int32_t bindComponentID

component ID current feature bind to

int32_t bindFeatureID

feature ID current feature bind to

char reserved[252]
struct TY_INT_RANGE
#include <TYApi.h>

Public Members

int32_t min
int32_t max
int32_t inc

increaing step

int32_t reserved[1]
struct TY_FLOAT_RANGE
#include <TYApi.h>

Public Members

float min
float max
float inc

increaing step

float reserved[1]
struct TY_ENUM_ENTRY
#include <TYApi.h>

enum feature entry information

See
TYGetEnumEntryInfo

Public Members

char description[64]
int32_t value
int32_t reserved[3]
struct TY_VECT_3F
#include <TYApi.h>

Public Members

float x
float y
float z
struct TY_CAMERA_INTRINSIC
#include <TYApi.h>

a 3x3 matrix |.

|.|.| | ||| | fx| 0| cx| | 0| fy| cy| | 0| 0| 1|

Public Members

float data[3 * 3]
struct TY_CAMERA_EXTRINSIC
#include <TYApi.h>

a 4x4 matrix |.

|.|.|.| ||-|-|| |r11| r12| r13| t1| |r21| r22| r23| t2| |r31| r32| r33| t3| | 0 | 0| 0| 1|

Public Members

float data[4 * 4]
struct TY_CAMERA_DISTORTION
#include <TYApi.h>

camera distortion parameters

Public Members

float data[12]

Definition is compatible with opencv3.0+ :k1,k2,p1,p2,k3,k4,k5,k6,s1,s2,s3,s4.

struct TY_CAMERA_CALIB_INFO
#include <TYApi.h>

camera ‘s cailbration data

See
TYGetStruct

Public Members

int32_t intrinsicWidth
int32_t intrinsicHeight
TY_CAMERA_INTRINSIC intrinsic
TY_CAMERA_EXTRINSIC extrinsic
TY_CAMERA_DISTORTION distortion
struct TY_TRIGGER_PARAM
#include <TYApi.h>

Public Members

TY_TRIGGER_MODE mode
int8_t fps
int8_t rsvd
struct TY_CAMERA_STATISTICS
#include <TYApi.h>

Public Members

int32_t packetReceived
int32_t packetLost
int32_t imageOutputed
int32_t imageDropped
uint8_t rsvd[1024]
struct TY_IMAGE_DATA
#include <TYApi.h>

Public Members

uint64_t timestamp

Timestamp in microseconds.

int32_t imageIndex

image index used in trigger mode

int32_t status

Status of this buffer.

int32_t componentID

Where current data come from.

int32_t size

Buffer size.

void *buffer

Pointer to data buffer.

int32_t width

Image width in pixels.

int32_t height

Image height in pixels.

int32_t pixelFormat

Pixel format, see TY_PIXEL_FORMAT_LIST.

int32_t reserved[9]

Reserved.

struct TY_FRAME_DATA
#include <TYApi.h>

Public Members

void *userBuffer

Pointer to user enqueued buffer, user should enqueue this buffer in the end of callback.

int32_t bufferSize

Size of userBuffer.

int32_t validCount

Number of valid data.

int32_t reserved[6]

Reserved.

TY_IMAGE_DATA image[10]

Buffer data, max to 10 images per frame, each buffer data could be an image or something else.

struct TY_EVENT_INFO
#include <TYApi.h>

Public Members

TY_EVENT eventId
char message[124]

API for coodinate mapping functions

Coordinate Conversion API.

Note
Considering performance, we leave the responsibility of parameters check to users.
Copyright
Copyright(C)2016-2018 Percipio All Rights Reserved

Defines

TYMAP_CHECKRET(f, bufToFree)

Typedefs

typedef struct TY_PIXEL_DESC TY_PIXEL_DESC

Functions

TY_CAPI TYInvertExtrinsic(const TY_CAMERA_EXTRINSIC *orgExtrinsic, TY_CAMERA_EXTRINSIC *invExtrinsic)

Calculate 4x4 extrinsic matrix’s inverse matrix.

Parameters
  • orgExtrinsic: Input extrinsic matrix.
  • invExtrinsic: Inverse matrix.
Return Value
  • TY_STATUS_OK: Succeed.
  • TY_STATUS_ERROR: Calculation failed.

TY_CAPI TYMapDepthToPoint3d(const TY_CAMERA_CALIB_INFO *src_calib, uint32_t depthW, uint32_t depthH, const TY_PIXEL_DESC *depthPixels, uint32_t count, TY_VECT_3F *point3d)

Map pixels on depth image to 3D points.

Parameters
  • src_calib: Depth image’s calibration data.
  • depthW: Width of depth image.
  • depthH: Height of depth image.
  • depthPixels: Pixels on depth image.
  • count: Number of depth pixels.
  • point3d: Output point3D.
Return Value
  • TY_STATUS_OK: Succeed.

TY_CAPI TYMapPoint3dToDepth(const TY_CAMERA_CALIB_INFO *dst_calib, const TY_VECT_3F *point3d, uint32_t count, uint32_t depthW, uint32_t depthH, TY_PIXEL_DESC *depth)

Map 3D points to pixels on depth image.

Reverse operation of TYMapDepthToPoint3d.

Parameters
  • dst_calib: Target depth image’s calibration data.
  • point3d: Input 3D points.
  • count: Number of points.
  • depthW: Width of target depth image.
  • depthH: Height of target depth image.
  • depth: Output depth pixels.
Return Value
  • TY_STATUS_OK: Succeed.

TY_CAPI TYMapDepthImageToPoint3d(const TY_CAMERA_CALIB_INFO *src_calib, uint32_t imageW, uint32_t imageH, const uint16_t *depth, TY_VECT_3F *point3d)

Map depth image to 3D points.

0 depth pixels maps to (NAN, NAN, NAN).

Parameters
  • src_calib: Depth image’s calibration data.
  • depthW: Width of depth image.
  • depthH: Height of depth image.
  • depth: Depth image.
  • point3d: Output point3D image.
Return Value
  • TY_STATUS_OK: Succeed.

TY_CAPI TYMapPoint3dToDepthImage(const TY_CAMERA_CALIB_INFO *dst_calib, const TY_VECT_3F *point3d, uint32_t count, uint32_t depthW, uint32_t depthH, uint16_t *depth)

Map 3D points to depth image.

(NAN, NAN, NAN) will be skipped.

Parameters
  • dst_calib: Target depth image’s calibration data.
  • point3d: Input 3D points.
  • count: Number of points.
  • depthW: Width of target depth image.
  • depthH: Height of target depth image.
  • depth: Depth image buffer.
Return Value
  • TY_STATUS_OK: Succeed.

TY_CAPI TYMapPoint3dToPoint3d(const TY_CAMERA_EXTRINSIC *extrinsic, const TY_VECT_3F *point3dFrom, uint32_t count, TY_VECT_3F *point3dTo)

Map 3D points to another coordinate.

Parameters
  • extrinsic: Extrinsic matrix.
  • point3dFrom: Source 3D points.
  • count: Number of source 3D points.
  • point3dTo: Target 3D points.
Return Value
  • TY_STATUS_OK: Succeed.

static TY_STATUS TYMapDepthToColorCoordinate(const TY_CAMERA_CALIB_INFO *depth_calib, uint32_t depthW, uint32_t depthH, const TY_PIXEL_DESC *depth, uint32_t count, const TY_CAMERA_CALIB_INFO *color_calib, uint32_t mappedW, uint32_t mappedH, TY_PIXEL_DESC *mappedDepth)

Map depth pixels to color coordinate pixels.

Parameters
  • depth_calib: Depth image’s calibration data.
  • depthW: Width of current depth image.
  • depthH: Height of current depth image.
  • depth: Depth image pixels.
  • count: Number of depth image pixels.
  • color_calib: Color image’s calibration data.
  • mappedW: Width of target depth image.
  • mappedH: Height of target depth image.
  • mappedDepth: Output pixels.
Return Value
  • TY_STATUS_OK: Succeed.

static TY_STATUS TYMapDepthImageToColorCoordinate(const TY_CAMERA_CALIB_INFO *depth_calib, uint32_t depthW, uint32_t depthH, const uint16_t *depth, const TY_CAMERA_CALIB_INFO *color_calib, uint32_t mappedW, uint32_t mappedH, uint16_t *mappedDepth)

Map original depth image to color coordinate depth image.

Parameters
  • depth_calib: Depth image’s calibration data.
  • depthW: Width of current depth image.
  • depthH: Height of current depth image.
  • depth: Depth image.
  • color_calib: Color image’s calibration data.
  • mappedW: Width of target depth image.
  • mappedH: Height of target depth image.
  • mappedDepth: Output pixels.
Return Value
  • TY_STATUS_OK: Succeed.

static TY_STATUS TYCreateDepthToColorCoordinateLookupTable(const TY_CAMERA_CALIB_INFO *depth_calib, uint32_t depthW, uint32_t depthH, const uint16_t *depth, const TY_CAMERA_CALIB_INFO *color_calib, uint32_t mappedW, uint32_t mappedH, TY_PIXEL_DESC *lut)

Create depth image to color coordinate lookup table.

Parameters
  • depth_calib: Depth image’s calibration data.
  • depthW: Width of current depth image.
  • depthH: Height of current depth image.
  • depth: Depth image.
  • color_calib: Color image’s calibration data.
  • mappedW: Width of target depth image.
  • mappedH: Height of target depth image.
  • lut: Output lookup table.
Return Value
  • TY_STATUS_OK: Succeed.

static TY_STATUS TYMapRGBImageToDepthCoordinate(const TY_CAMERA_CALIB_INFO *depth_calib, uint32_t depthW, uint32_t depthH, const uint16_t *depth, const TY_CAMERA_CALIB_INFO *color_calib, uint32_t rgbW, uint32_t rgbH, const uint8_t *inRgb, uint8_t *mappedRgb)

Map original RGB image to depth coordinate RGB image.

Parameters
  • depth_calib: Depth image’s calibration data.
  • depthW: Width of current depth image.
  • depthH: Height of current depth image.
  • depth: Current depth image.
  • color_calib: Color image’s calibration data.
  • rgbW: Width of RGB image.
  • rgbH: Height of RGB image.
  • inRgb: Current RGB image.
  • mappedRgb: Output RGB image.
Return Value
  • TY_STATUS_OK: Succeed.

static TY_STATUS TYMapMono8ImageToDepthCoordinate(const TY_CAMERA_CALIB_INFO *depth_calib, uint32_t depthW, uint32_t depthH, const uint16_t *depth, const TY_CAMERA_CALIB_INFO *color_calib, uint32_t monoW, uint32_t monoH, const uint8_t *inMono, uint8_t *mappedMono)

Map original MONO8 image to depth coordinate MONO8 image.

Parameters
  • depth_calib: Depth image’s calibration data.
  • depthW: Width of current depth image.
  • depthH: Height of current depth image.
  • depth: Current depth image.
  • color_calib: Color image’s calibration data.
  • monoW: Width of MONO8 image.
  • monoH: Height of MONO8 image.
  • inMono: Current MONO8 image.
  • mappedMono: Output MONO8 image.
Return Value
  • TY_STATUS_OK: Succeed.

struct TY_PIXEL_DESC
#include <TYCoordinateMapper.h>

Public Members

int16_t x
int16_t y
uint16_t depth
uint16_t rsvd

API for image post processing

Image post-process API

Copyright
Copyright(C)2016-2018 Percipio All Rights Reserved

Defines

DepthSpeckleFilterParameters_Initializer
DepthEnhenceParameters_Initializer

Functions

TY_CAPI TYUndistortImage(const TY_CAMERA_CALIB_INFO *srcCalibInfo, const TY_IMAGE_DATA *srcImage, const TY_CAMERA_INTRINSIC *cameraNewIntrinsic, TY_IMAGE_DATA *dstImage)

Do image undistortion, only support TY_PIXEL_FORMAT_MONO ,TY_PIXEL_FORMAT_RGB,TY_PIXEL_FORMAT_BGR.

Parameters
  • srcCalibInfo: Image calibration data.
  • srcImage: Source image.
  • cameraNewIntrinsic: Expected new image intrinsic, will use srcCalibInfo for new image intrinsic if set to NULL.
  • dstImage: Output image.
Return Value
  • TY_STATUS_OK: Succeed.
  • TY_STATUS_NULL_POINTER: Any srcCalibInfo, srcImage, dstImage, srcImage->buffer, dstImage->buffer is NULL.
  • TY_STATUS_INVALID_PARAMETER: Invalid srcImage->width, srcImage->height, dstImage->width, dstImage->height or unsupported pixel format.

TY_CAPI TYDepthSpeckleFilter(TY_IMAGE_DATA *depthImage, const DepthSpeckleFilterParameters *param)

Remove speckles on depth image.

Parameters
  • depthImage: Depth image to be processed.
  • param: Algorithm parameters.
Return Value
  • TY_STATUS_OK: Succeed.
  • TY_STATUS_NULL_POINTER: Any depth, param or depth->buffer is NULL.
  • TY_STATUS_INVALID_PARAMETER: param->max_speckle_size <= 0 or param->max_speckle_diff <= 0

TY_CAPI TYDepthEnhenceFilter(const TY_IMAGE_DATA *depthImages, int imageNum, TY_IMAGE_DATA *guide, TY_IMAGE_DATA *output, const DepthEnhenceParameters *param)

Remove speckles on depth image.

Parameters
  • depthImage: Pointer to depth image array.
  • imageNum: Depth image array size.
  • guide: Guide image.
  • output: Output depth image.
  • param: Algorithm parameters.
Return Value
  • TY_STATUS_OK: Succeed.
  • TY_STATUS_NULL_POINTER: Any depthImage, param, output or output->buffer is NULL.
  • TY_STATUS_INVALID_PARAMETER: imageNum >= 5 or imageNum <= 0, or any image invalid
  • TY_STATUS_OUT_OF_MEMORY: Output image not suitable.

struct DepthSpeckleFilterParameters
#include <TYImageProc.h>

default parameter value definition

Public Members

int max_speckle_size
int max_speckle_diff
struct DepthEnhenceParameters
#include <TYImageProc.h>

default parameter value definition

Public Members

float sigma_s

filter param on space

float sigma_r

filter param on range

int outlier_win_sz

outlier filter windows ize

float outlier_rate