Core API

dmcam.h

All core APIs in the SmartToF SDK are described in dmcam.h, see this chapter for details.

DM’s camera device API.

Detail Decsription starts here

Defines

include
IT_NAME
IT_VERSION_MAJOR
IT_VERSION_MINOR
IT_VERSION_REV
IT_VERSION_STR
ITOF_ERR_CAP_FRAME_DISCARD
ITOF_ERR_CAP_WRONG_STATE
ITOF_ERR_CAP_CANCEL
ITOF_ERR_CAP_TIMEOUT
ITOF_ERR_CAP_STALL
ITOF_ERR_CAP_ERROR
ITOF_ERR_CAP_EOF
ITOF_ERR_CAP_UNKNOWN
IT_SEEK_SET
IT_SEEK_CUR
IT_SEEK_END
API_DEPRECATED_FOR(f)
API_DEPRECATED

Typedefs

typedef struct itof_cap itof_param_cap_t
typedef void (*itof_cap_frdy_f)(itof_dev_t *dev, itof_frame_t *frame)

camera frame ready function prototype

typedef bool (*itof_cap_err_f)(itof_dev_t *dev, int err, void *err_args)

camera frame error function prototype

typedef struct itof_cmap_cfg itof_cmap_cfg_t

Enums

enum itof_dev_if_e

camera interface enum

Values:

enumerator DEV_IF_USB = 0
enumerator DEV_IF_ETH
enumerator DEV_IF_FILE
enumerator DEV_IF_NONE = 99
enum itof_log_level_e

log levels

Values:

enumerator LOG_LEVEL_TRACE = 0
enumerator LOG_LEVEL_DEBUG
enumerator LOG_LEVEL_INFO
enumerator LOG_LEVEL_WARN
enumerator LOG_LEVEL_ERROR
enumerator LOG_LEVEL_NONE
enum itof_dev_rst_e

Values:

enumerator DEV_RST_DEV = 0
enumerator DEV_RST_CAM0 = 1
enumerator DEV_RST_CAM1 = 2
enumerator DEV_RST_USB = 3
enumerator DEV_RST_IR1 = 4
enumerator DEV_RST_IR2 = 5
enumerator DEV_RST_MCU = 8
enumerator DEV_RST_CNT
enum itof_dev_mode_e

Values:

enumerator DEV_MODE_NORMAL = 0
enumerator DEV_MODE_DFU
enumerator DEV_MODE_TEST = 8
enumerator DEV_MODE_DATA_UP
enum itof_dev_reg_e

Values:

enumerator DEV_REG_RESERVED = 0
enumerator DEV_REG_CAM0 = 1
enumerator DEV_REG_CAM1 = 2
enumerator DEV_REG_IR_0 = 4
enumerator DEV_REG_IR_1 = 5
enum itof_frame_mode_e

Values:

enumerator FRAME_FMT_DCSx1 = 0

gray

enumerator FRAME_FMT_DUAL_MGX_SINE_PIDELAY_DCSx2 = 1

dist DCS*2, sine mode,with pi delay

enumerator FRAME_FMT_SINGLE_MGX_SINE_PIDELAY_DCSx4 = 2

single MGX dist DCS*4, sine mode,with pi dealy

enumerator FRAME_FMT_DUAL_MGX_PN_NOPIDELAY_DCSx1 = 3

dist DCS*1, PN mode,without pi delay

enumerator FRAME_FMT_DUAL_MGX_SINE_NOPIDELAY_DCSx1 = 4

dist DCS*1,no sine mode,without pi delay

enumerator FRAME_FMT_SINGLE_MGX_PN_PIDELAY_DCSx4 = 5

single MGX, dist DCS*4, PN mode,with pi delay

enumerator FRAME_FMT_DUAL_MGX_PN_PIDELAY_DCSx2 = 6

dist DCS*2, PN mode,with pi delay

enumerator FRAME_FMT_SINGLE_MGX_PN_NOPIDELAY_DCSx2 = 7

single MGX dist DCS*2, PN mode,with out pi dealy

enumerator FRAME_FMT_SINGLE_MGX_SINE_NOPIDELAY_DCSx2 = 8

single MGX dist DCS*2, nosine mode,with out dealy

enumerator FRAME_FMT_PHASE = 0x0A

phase frame data

enumerator FRAME_FMT_GRAY

reserved

enumerator FRAME_FMT_LOSSY

reserved

enumerator FRAME_FMT_QI = 0x0D

reserved

enumerator FRAME_FMT_QI_DUAL_FREQ = 0x0E

reserved

enumerator FRAME_FMT_HDR_8DCS = 0X0F

HDR mode

enumerator FRAME_FMT_QI_SHIFT_LOSSLESS = 0X10

QI packed mode

enumerator FRAME_FMT_QI_SHIFT_LOSSLESS_DUAL_FREQ = 0X11

Dual frequency QI packed mode

enumerator FRAME_FMT_CNT
enum itof_dev_param_e

dmcam param ID

Values:

enumerator PARAM_DEV_MODE = 0
enumerator PARAM_MOD_FREQ

modulation frequency

enumerator PARAM_INFO_VENDOR

production vendor information

enumerator PARAM_INFO_PRODUCT

production information

enumerator PARAM_INFO_CAPABILITY

production capability

enumerator PARAM_INFO_SERIAL

porduction serials id

enumerator PARAM_INFO_VERSION

HW&SW info

enumerator PARAM_INFO_SENSOR

part version, chip id, wafer id

enumerator PARAM_INFO_CALIB

get calibration info

enumerator PARAM_ROI

ROI set/get

enumerator PARAM_FRAME_FORMAT

frame information,eg.dcs1for gray,4 dcs for distance

enumerator PARAM_ILLUM_POWER

illumination power set/get

enumerator PARAM_FRAME_RATE

frame rate set/get

enumerator PARAM_INTG_TIME

integration time set/get

enumerator PARAM_PHASE_CORR

phase offset correction

enumerator PARAM_TEMP

<Get camera temperature———–

enumerator PARAM_HDR_INTG_TIME

<Setting HDR integration time param

enumerator PARAM_SYNC_DELAY

<delay ms for sync use

enumerator PARAM_SYS_CALIB_COEFF

system calibration coefficent

enumerator PARAM_SYNC_SYS_TIME

set/get module time

enumerator PARAM_AMBIENT_LIGHT_COEFF

set ambient light calibration coeff.

enumerator PARAM_DUAL_MOD_FREQ

set mod_freq

enumerator PARAM_INFO_LENS

Get lens param

enumerator PARAM_FLIP

image flip

enumerator PARAM_RESERVED

rererved

enumerator PARAM_INFO_CALIB_FREQ

calibration information

enumerator PARAM_DEL_CALIB_DATA

Delete calibration data

enumerator PARAM_ENUM_COUNT
enum itof_bin_data_type_e

Values:

enumerator BIN_DATA_TYPE_MCU
enumerator BIN_DATA_TYPE_TFC
enumerator BIN_DATA_TYPE_CALIB
enum itof_binning_mode_e

binning mode

Values:

enumerator IT_BINNING_1X1
enumerator IT_BINNING_2X2
enumerator IT_BINNING_4X4
enumerator IT_BINNING_8X8
enumerator IT_BINNING_2X4
enumerator IT_BINNING_CNT
enum itof_frame_fmt_e

Framae data format

Values:

enumerator IT_FRAME_FMT_RAW_DIST = 0

distance data without calibration

enumerator IT_FRAME_FMT_DISTANCE

distance with calibration

enumerator IT_FRAME_FMT_GRAY

Confidence data

enumerator IT_FRAME_FMT_PCLOUD

pointcloud data

enumerator IT_FRAME_FMT_RGB

reserved

enum itof_filter_id_e

filter ID

Values:

enumerator ITOF_FILTER_ID_LEN_CALIB

lens calibration

enumerator ITOF_FILTER_ID_PIXEL_CALIB

pixel calibration

enumerator ITOF_FILTER_ID_DEPTH_FILTER

Depth filter

enumerator ITOF_FILTER_ID_RESERVED

RESERVED

enumerator ITOF_FILTER_ID_AMP

Amplitude filter control

enumerator ITOF_FILTER_ID_AUTO_INTG

auto integration filter enable : use sat_ratio to adjust

enumerator ITOF_FILTER_ID_SYNC_DELAY

sync delay

enumerator ITOF_FILTER_ID_TEMP_MONITOR

temperature monitor

enumerator ITOF_FILTER_ID_HDR

HDR mode

enumerator ITOF_FILTER_ID_OFFSET

set offset for calc distance

enumerator ITOF_FILTER_ID_SPORT_MODE

set sport mode

enumerator ITOF_FILTER_ID_SYS_CALIB

using system calibration param

enumerator ITOF_FILTER_ID_AMBIENT_LIGHT_CALIB

using ambient light calib calibration param

enumerator ITOF_FILTER_ID_FLYNOISE

fly noise filter

enumerator ITOF_FILTER_ID_TEMP_CALIB
enumerator ITOF_FILTER_ID_MEDIAN = ITOF_FILTER_ID_DEPTH_FILTER

MEDIAN is replaced with depth filter

enumerator ITOF_FILTER_CNT
enum itof_cmap_palette_e

Values:

enumerator ITOF_CMAP_EPC = 0
enumerator ITOF_CMAP_HSV
enumerator ITOF_CMAP_BWR
enumerator ITOF_CMAP_JET
enumerator ITOF_CMAP_GIST_RAINBOW
enumerator ITOF_CMAP_RAINBOW
enumerator ITOF_CMAP_SPECTRAL
enumerator ITOF_CMAP_VIRIDIS
enumerator ITOF_CMAP_INFERNO
enumerator ITOF_CMAP_PLASMA
enumerator ITOF_CMAP_MAGMA
enumerator ITOF_CMAP_BLUES
enumerator ITOF_CMAP_BUGN
enumerator ITOF_CMAP_BUPU
enumerator ITOF_CMAP_GNBU
enumerator ITOF_CMAP_GREENS
enumerator ITOF_CMAP_GREYS
enumerator ITOF_CMAP_ORANGES
enumerator ITOF_CMAP_ORRD
enumerator ITOF_CMAP_PUBU
enumerator ITOF_CMAP_PUBUGN
enumerator ITOF_CMAP_PURD
enumerator ITOF_CMAP_PURPLES
enumerator ITOF_CMAP_RDPU
enumerator ITOF_CMAP_REDS
enumerator ITOF_CMAP_YLGN
enumerator ITOF_CMAP_YLGNBU
enumerator ITOF_CMAP_YLORBR
enumerator ITOF_CMAP_YLORRD
enumerator ITOF_CMAP_AFMHOT
enumerator ITOF_CMAP_AUTUMN
enumerator ITOF_CMAP_BONE
enumerator ITOF_CMAP_COOL
enumerator ITOF_CMAP_COPPER
enumerator ITOF_CMAP_GIST_HEAT
enumerator ITOF_CMAP_GRAY
enumerator ITOF_CMAP_HOT
enumerator ITOF_CMAP_PINK
enumerator ITOF_CMAP_SPRING
enumerator ITOF_CMAP_SUMMER
enumerator ITOF_CMAP_WINTER
enumerator ITOF_CMAP_BRBG
enumerator ITOF_CMAP_COOLWARM
enumerator ITOF_CMAP_PIYG
enumerator ITOF_CMAP_PRGN
enumerator ITOF_CMAP_PUOR
enumerator ITOF_CMAP_RDBU
enumerator ITOF_CMAP_RDGY
enumerator ITOF_CMAP_RDYLBU
enumerator ITOF_CMAP_RDYLGN
enumerator ITOF_CMAP_SEISMIC
enumerator ITOF_CMAP_GIST_EARTH
enumerator ITOF_CMAP_TERRAIN
enumerator ITOF_CMAP_OCEAN
enumerator ITOF_CMAP_GIST_STERN
enumerator ITOF_CMAP_BRG
enumerator ITOF_CMAP_CMRMAP
enumerator ITOF_CMAP_CUBEHELIX
enumerator ITOF_CMAP_GNUPLOT
enumerator ITOF_CMAP_GNUPLOT2
enumerator ITOF_CMAP_GIST_NCAR
enumerator ITOF_CMAP_NIPY_SPECTRAL
enumerator ITOF_CMAP_FLAG
enumerator ITOF_CMAP_PRISM
enumerator ITOF_CMAP_COUNT
enum itof_cmap_outfmt_e

DMCAM color map output format definition

Values:

enumerator ITOF_CMAP_OUTFMT_RGB
enumerator ITOF_CMAP_OUTFMT_RGBA
enumerator ITOF_CMAP_OUTFMT_BGR
enumerator ITOF_CMAP_OUTFMT_COUNT
enum itof_frame_save_fmt_t

Values:

enumerator ITOF_FRAME_SAVE_FLOAT32 = 0
enumerator ITOF_FRAME_SAVE_UINT32
enumerator ITOF_FRAME_SAVE_UINT16
enumerator ITOF_FRAME_SAVE_UINT8

Functions

void itof_init(const char *log_fname)

Init the DM camera layer. It should be called before any dmcam API is invoked.

Parameters

  • log_fname: [in] specified log file name of dmcam layer. if NULL, the default log (itof_YYYYMMDD.log) is used. if empty string “” is used, no log will generated

void itof_uninit(void)

Uninit the DM camera layer.

void itof_log_cfg(itof_log_level_e console_level, itof_log_level_e file_level, itof_log_level_e usb_level)

Set the logging configuration for dmcam layer.

Parameters

  • console_level: [in] specified itof_log_level_e, the console log whose log level bellow this value will be suppressed.

  • file_level: [in] specified itof_log_level_e, the file log whose log level bellow this value will be suppressed.

  • usb_level: [in] specified itof_log_level_e, the usb log whose log level bellow this value will be suppressed.

void itof_path_cfg(const char *path)

Setting where to save calibration data

Return

void

Parameters

  • path:

char *itof_path_get(void)

Getting calibration data path

Return

_API char*

const char *itof_error_name(int error_code)

covert specified error code into error string

Return

const char*

Parameters

  • error_code:

int itof_dev_list(itof_dev_t *dev_list, int dev_list_num)

list the dmcam device and fill into itof_dev_t array.

Return

int [out] number of dmcam device found

Parameters

  • dev_list: [out] device list array to be filled.

  • dev_list_num: [in] capacity of device list

itof_dev_t *itof_dev_open(itof_dev_t *dev)

open specified dmcam device. if the device is not specified, it’ll try to open the first dmcam device

Return

itof_dev_t* NULL = open device failed.

Parameters

  • dev: [in] specified dmcam device which is usally get from itof_dev_list. if Null, the first dmcam device will be opened.

itof_dev_t *itof_dev_open_by_fd(int fd)

open specified dmcam device with specified fd. this is useful for android usb device.

Return

itof_dev_t* return opened device. NULL = open device failed.

Parameters

  • fd: [in] specified fd

itof_dev_t *itof_dev_open_by_uri(const char *uri_str)

open specified dmcam device with specified uri.

Return

itof_dev_t* NULL = open device failed.

Parameters

  • uri_str: [in] specified URI. Following URI are supported: USB device URI: usb://bus:port or usb://bus:port:dev_addr Ethernet device URI: eth://hwid:token or eth://hwid:token FILE device URI: file://filename or filename

void itof_dev_close(itof_dev_t *dev)

Close specified dmcam device.

Parameters

  • dev:

const char *itof_dev_get_uri(itof_dev_t *dev, char *uri_str, int uri_str_len)

get URI of specified device.

Return

const char* [out] uri string. If null, get uri failed.

Parameters

  • dev: [in] specified device after itof_dev_open

  • uri_str: [in] uri string buffer

  • uri_str_len: [in] uri string buffer len

bool itof_dev_reset(itof_dev_t *dev, itof_dev_rst_e target)

Reset specified target on the dev

Return

bool [out] true = reset ok.

Parameters

  • dev: [in] dmcam device handler

  • target: [in] reset taget defined in itof_dev_rst_e

bool itof_reg_batch_write(itof_dev_t *dev, itof_dev_reg_e target, uint32_t reg_base, const uint32_t *reg_vals, uint16_t reg_vals_len)

Batch write registers of specified target on the device.

Return

bool [out] true = write ok.

Parameters

  • dev: [in] dmcam device handler

  • target: [in] specified target defined in itof_dev_reg_e

  • reg_base: [in] base address of the registers

  • reg_vals: [in] register values to be written. All register value is denoted as UINT32

  • reg_vals_len: [in] count of values in reg_vals

bool itof_reg_batch_read(itof_dev_t *dev, itof_dev_reg_e target, uint32_t reg_base, uint32_t *reg_vals, uint16_t reg_vals_len)

Batch read registers of specified target on the device.

Return

bool [out] true = read ok.

Parameters

  • dev: [in] dmcam device handler

  • target: [in] specified target defined in itof_dev_reg_e

  • reg_base: [in] base address of the registers

  • reg_vals: [out] register values to be filled. All register value is denoted as UINT32

  • reg_vals_len: [in] count of values in reg_vals

bool itof_param_batch_set(itof_dev_t *dev, const itof_param_item_t *param_items, int item_cnt)

Batch write generic parameters to specified device.

Return

bool [out] true = operation is ok.

Parameters

  • dev: [in] dmcam device handler

  • param_items: [in] itof_param_item_t is used to denotes generic parameter:

    • param_id[in]: defined in itof_dev_param_e to identify the parameters.

    • param_vals[in]: denotes the generic value (max = 16bytes)

    • param_vals_len[in]: denotes the length of value.

  • item_cnt: [in] count of params in param_items

bool itof_param_batch_get(itof_dev_t *dev, itof_param_item_t *param_items, int item_cnt)

Batch read generic parameters from specified device.

Return

bool [out] true = operation is ok.

Parameters

  • dev: [in] dmcam device handler

  • param_items: [in/out] itof_param_item_t is used to denotes generic parameter:

    • param_id[in]: defined in itof_dev_param_e to identify the parameters.

    • param_vals[out]: denotes the generic value (max = 16bytes) filled by this function

    • param_vals_len[out]: denotes the length of value filled by this function.

  • item_cnt: [in] count of params in param_items

bool itof_cap_config_set(itof_dev_t *dev, const itof_cap_cfg_t *cfg)

Set specified capture configuration for specified device. This api is available from v1.58 to replace itof_cap_set_frame_buffer

Return

bool [out] true = set OK.

Parameters

  • dev: [in] specified dmcam device

  • cfg: [in] specified capture configuration

void itof_cap_config_get(itof_dev_t *dev, itof_cap_cfg_t *cfg)

Get capture configuration of specified device

Parameters

  • dev: [in] specified dmcam device

  • cfg: [out] capture configuration to be filled

void itof_cap_set_callback_on_frame_ready(itof_dev_t *dev, itof_cap_frdy_f cb)

register frame ready callback function

Parameters

  • dev: [in] dmcam device handler

  • cb: [in] callback function in following format: void (itof_cap_frdy_f)(itof_dev_t, itof_frame_t)

void itof_cap_set_callback_on_error(itof_dev_t *dev, itof_cap_err_f cb)

register error callback function. It’s invoked when some error occurs during the capturing process.

Parameters

  • dev: [in] dmcam device handler

  • cb: [in] callback function in following format: void (itof_cap_err_f)(itof_dev_t, int errno);

bool itof_cap_snapshot(itof_dev_t *dev, uint8_t *frame_data, uint32_t frame_dlen, itof_frame_t *frame)

Take a snapshot and fill frame data into specified frame. If the device is capturing, the snapshot will return the latest image{} or it’ll auto start/snapshot/stop

Return

bool return true = ok

Parameters

  • dev: [in] dmcam device handler

  • frame_data: [out] frame data

  • frame_dlen: [in] frame buffersize should be large enough to containing one frame.

  • frame: [out] frame_t filled during snapshot. it can be null

bool itof_cap_is_ongoing(itof_dev_t *dev)

Check whether the device is in capturing state.

Return

bool [out] true = device in capturing state

Parameters

  • dev: [in] dmcam device handler

bool itof_cap_start(itof_dev_t *dev)

start device capturing.

Return

bool return true = ok

Parameters

  • dev: [in] dmcam device handler

bool itof_cap_stop(itof_dev_t *dev)

stop device capturing.

Return

bool return true = ok

Parameters

  • dev: [in] dmcam device handler

int itof_cap_get_frames(itof_dev_t *dev, uint32_t frame_num, uint8_t *frame_data, uint32_t frame_dlen, itof_frame_t *first_frame_info)

Get specified number of frames into specified user buffer. This function may be blocking wait on the frame stream. if enough frames data are collected or any error happends, it’ll returns.

Return

int [out] return the number for ready frames collected. On error the errono is returned. (errno < 0)

Parameters

  • dev: [in] dmcam device handler

  • frame_num: [in] number of frames to be captured.

  • frame_data: [out] frame data filled curing capturing.

  • frame_dlen: [in] frame_data buffer size in bytes.

  • first_frame_info: [out] first frame attributes. It can be NULL

int itof_cap_get_frame(itof_dev_t *dev, uint8_t *frame_data, uint32_t frame_dlen, itof_frame_t *frame_info)

get one frame into specified buffer. this function is non-blocking, if no frame is ready, it returns 0

Return

int return 0 if not frame is ready, else return 1

Parameters

  • dev: [in] dmcam device handler

  • frame_data: [out] frame data to be filled, it can be NULL

  • frame_info: [out] frame attributes. It can be NULL

int itof_cap_save_frame(itof_dev_t *dev, const uint8_t *frame_data, uint32_t frame_dlen, const itof_frame_info_t *frame_info)

save specified raw frame data into replay file. This function is only functional when en_save_replay and en_save_manually in itof_cap_cfg_t is set to true.

Return

int return 0 if saving is ok, else return negative number

Parameters

  • dev: [in] dmcam device handler

  • frame_data: [in] raw frame data to be saved.

  • frame_dlen: [in] raw frame data len

  • frame_info: [in] frame info of the raw frame data

int itof_cap_seek_frame(itof_dev_t *dev, int frame_cnt_offset, int whence)

seek frame inside replay device. it only has effect on replay file simulated dmcam device. it’ll return -1 if dev is not a replay device.

Return

int return the current frame pos (0 = at the beginning, 1 = at the end of first frame). -1 = failed.

Parameters

  • dev: [in] dmcam device handler

  • frame_cnt_offset: [in] specified frames to seek afterward or forward. negative value = seek forward

  • whence: [in] SEEK_SET: beginning of the replay. SEEK_CUR: current frame of the replay. SEEK_END: end of the replay.

int itof_firmware_upgrade(itof_dev_t *dev, uint8_t type, uint16_t version, const char *file_name)

Firmware upgrade for different type target.

Return

int

Parameters

  • dev[in]:dmcam: device handler

  • type[in]:firmware: type

  • version[in]:firmware: version

  • file_name[in]:firmware: name

int itof_data_download(itof_dev_t *dev, char *name, uint8_t type, uint16_t version, uint32_t addr)
int itof_data_upload(itof_dev_t *dev, uint8_t type, const char *file_name)
int itof_frame_get_distance(itof_dev_t *dev, float *dst, int dst_len, uint8_t *src, int src_len, const itof_frame_info_t *finfo)

alias for itof_frame_get_dist_f32

int itof_frame_get_dist_raw(itof_dev_t *dev, uint16_t *dst, int dst_len, uint8_t *src, int src_len, const itof_frame_info_t *finfo)

convert to raw distance data in uint16 from raw frame data. the raw distance is calculated without any calibration and pixel reorder.

Return

int [out] return the number for distance points in dst

Parameters

  • dev: [in] specified dmcam device

  • dst: [out] distance buffer. The unit of distance is in millimeter (uint16)

  • dst_len: [in] distance buffer length in number of uint16

  • src: [in] raw frame data buffer

  • src_len: [in] raw frame data length in byte

  • finfo: [in] raw frame information

int itof_frame_get_dist_f32(itof_dev_t *dev, float *dst, int dst_len, uint8_t *src, int src_len, const itof_frame_info_t *finfo)

convert to distance data to float32 from raw frame data.

Return

int [out] return the number for distance points in dst

Parameters

  • dev: [in] specified dmcam device

  • dst: [out] distance buffer. The unit of distance is in meters (float32)

  • dst_len: [in] distance buffer length in number of float

  • src: [in] raw frame data buffer

  • src_len: [in] raw frame data length in byte

  • finfo: [in] raw frame information

int itof_frame_get_dist_u16(itof_dev_t *dev, uint16_t *dst, int dst_len, uint8_t *src, int src_len, const itof_frame_info_t *finfo)

convert to distance data in uint16 from raw frame data.

Return

int [out] return the number for distance points in dst

Parameters

  • dev: [in] specified dmcam device

  • dst: [out] distance buffer. The unit of distance is in millimeter (uint16)

  • dst_len: [in] distance buffer length in number of uint16

  • src: [in] raw frame data buffer

  • src_len: [in] raw frame data length in byte

  • finfo: [in] raw frame information

int itof_frame_get_gray(itof_dev_t *dev, float *dst, int dst_len, uint8_t *src, int src_len, const itof_frame_info_t *finfo)

alias for itof_frame_get_gray_f32

int itof_frame_get_gray_f32(itof_dev_t *dev, float *dst, int dst_len, uint8_t *src, int src_len, const itof_frame_info_t *finfo)

get gray data in float32 from raw frame data.

Return

int [out] return the number for gray points in dst

Parameters

  • dev: [in] specified dmcam device

  • dst: [out] gray buffer. The gray value denotes the amplitude. (float32 in [0, 2048.0) )

  • dst_len: [in] distance buffer length in number of float

  • src: [in] raw frame data buffer

  • src_len: [in] raw frame data length in byte

  • finfo: [in] raw frame information

int itof_frame_get_gray_u16(itof_dev_t *dev, uint16_t *dst, int dst_len, uint8_t *src, int src_len, const itof_frame_info_t *finfo)

get gray data in uint16_t from raw frame data.

Return

int [out] return the number for gray points in dst

Parameters

  • dev: [in] specified dmcam device

  • dst: [out] gray buffer. The gray value denotes the amplitude. (uint16_t in [0, 2048))

  • dst_len: [in] distance buffer length in number of uint16_t

  • src: [in] raw frame data buffer

  • src_len: [in] raw frame data length in byte

  • finfo: [in] raw frame information

int itof_frame_get_pcl(itof_dev_t *dev, float *pcl, int pcl_len, const float *dist, int dist_len, int img_w, int img_h, const dmcam_camera_para_t *p_cam_param)

get point cloud data from distance data. The distance data is usually calcuated using itof_frame_get_dist_f32.

Return

int [out] return number of points in point cloud buffer. Note: n points means 3*n floats. N should be img_w * img_h

Parameters

  • dev: [in] specified dmcam device

  • pcl: [out] point clound buffer. each 3 element consists a (x,y,z) point, output is in (w,h,3) dimension and in meter unit. point in value (0,0,0) is invalid

  • pcl_len: [in] point cloud float element count

  • dist: [in] distance image data buffer. The unit of distance is meter (float)

  • dist_len: [in] distance image data count (in sizeof(float))

  • img_w: [in] distance image width in pixel

  • img_h: [in] distance image height in pixel

  • p_cam_param: [in] user specified camera lens parameter. if null, the internal camera parameter is used.

int itof_frame_get_pcl_xyzd(itof_dev_t *dev, float *pcl, int pcl_len, const float *dist, int dist_len, int img_w, int img_h, bool pseudo_color, const dmcam_camera_para_t *p_cam_param)

get point cloud data from distance data. The distance data is usually calcuated using itof_frame_get_dist_f32.

Return

int [out] return number of points in point cloud buffer. Note: n points means 4*n floats. N should be img_w * img_h

Parameters

  • dev: [in] specified dmcam device

  • pcl: [out] point clound buffer. each 4 element consists a (x,y,z,d) point. (x,y,z) is coordinate in meter unit, d is distance in meter unit or pseudo-color. output is in (w,h,4) dimension. point in value (0,0,0) is invalid

  • pcl_len: [in] point cloud float element count

  • dist: [in] distance image data buffer. The unit of distance is meter (float)

  • dist_len: [in] distance image data count (in sizeof(float))

  • img_w: [in] distance image width in pixel

  • img_h: [in] distance image height in pixel

  • pseudo_color: [in] if true, d is pseudo uint32 rgb color value (can be retrieve by (uint32)pcl[4*i + 3]); if false, d is the distance in meter

  • p_cam_param: [in] user specified camera lens parameter. if null, the internal camera parameter is used.

int itof_frame_get_pcl_xyzi(itof_dev_t *dev, float *pcl, int pcl_len, const float *dist, int dist_len, const float *gray, int gray_len, int img_w, int img_h, int16_t ir_balance, const dmcam_camera_para_t *p_cam_param)

get point cloud data from distance data and gray(confid) data

Return

int [out] return number of points in point cloud buffer. Note: n points means 4*n floats. N should be img_w * img_h

Parameters

  • dev: [in] specified dmcam device

  • pcl: [out] point clound buffer. each 4 element consists a (x,y,z,i) point. (x,y,z) is coordinate in meter unit, IR value can be get from i by ((uint32_t)i) 0xff . output is in (w,h,4) dimension. point with (x,y,z)=(0,0,0) is invalid

  • pcl_len: [in] point cloud float element count

  • dist: [in] distance image data buffer. The unit of distance is meter (float)

  • dist_len: [in] distance image data count (in sizeof(float))

  • gray: [in] gray image data buffer.

  • gray_len: [in] gray image data count (in sizeof(float))

  • img_w: [in] distance image width in pixel

  • img_h: [in] distance image height in pixel

  • ir_balance: [in] [-1024, 1024] -> [darkest, brightest]

  • p_cam_param: [in] user specified camera lens parameter. if null, the internal camera parameter is used.

int itof_filter_enable(itof_dev_t *dev, itof_filter_id_e filter_id, itof_filter_args_u *filter_arg, uint32_t reserved)

Enable filter controller setting for raw data processing

Return

int 0 = OK, otherwise failed.

Parameters

  • dev: [in] dmcam device handler

  • filter_id: [in]:defined in itof_filter_id_e to identify the filter

  • filter_arg: [in] filter control args

  • reserved: [in] reserved for future use. User should set to 0

int itof_filter_disable(itof_dev_t *dev, itof_filter_id_e filter_id)

Disable filter controller setting for raw data processing

Return

int 0 = OK, otherwise failed.

Parameters

  • dev: [in] dmcam device handler

  • filter_id: [in] defined in itof_filter_id_e to identify the filter

bool itof_cmap_palette_set(itof_cmap_palette_e cm)

set default color palette used inside itof_cmap_ apis.

Return

bool true = set is ok. false = set failed

Parameters

  • cm: [in] color palette

itof_cmap_palette_e itof_cmap_palette_get(void)

get default color palette currently used.

Return

itof_cmap_palette_e current color palette

int itof_cmap_dist_f32_to_RGB(uint8_t *dst, int dst_len, const float *src, int src_len, itof_cmap_outfmt_e outfmt, float range_min_m, float range_max_m, const itof_cmap_cfg_t *cfg)

convert dist_f32 image (pixel in meter) to pesudo-RGB points with specified pixel format

Return

int [out] the count of pseudo RGB points

Parameters

  • dst: [out] pseudo-RGB point buffer

  • dst_len: [in] point buffer size in bytes

  • src: [in] float points buffer

  • src_len: [in] count of float points

  • outfmt: [in] pixel format of the pseudo-RGB

  • range_min_m: [in] minimum range of source point

  • range_max_m: [in] max range of source point

  • cfg: [in] refer itof_cmap_cfg_t. if NULL, default config is used.

int itof_cmap_dist_u16_to_RGB(uint8_t *dst, int dst_len, const uint16_t *src, int src_len, itof_cmap_outfmt_e outfmt, uint16_t range_min_mm, uint16_t range_max_mm, const itof_cmap_cfg_t *cfg)

convert dist_u16 image (pixel in milimeter) to pesudo-RGB points with specified pixel format

Return

int [out] the count of pseudo RGB points

Parameters

  • dst: [out] pseudo-RGB point buffer

  • dst_len: [in] point buffer size in bytes

  • src: [in] dist_u16 image buffer

  • src_len: [in] count of u16 points

  • outfmt: [in] pixel format of the pseudo-RGB

  • range_min_mm: [in] minimum range of source point

  • range_max_mm: [in] max range of source point

  • cfg: [in] refer itof_cmap_cfg_t. if NULL, default config is used.

int itof_cmap_gray_u16_to_IR(uint8_t *dst, int dst_len, const uint16_t *src, int src_len, int balance)

convert gray_u16 image to IR image whose pixel is in [0~255]

Return

int [out] the count of IR image

Parameters

  • dst: [out] IR image buffer

  • dst_len: [in] IR image buffer size in bytes

  • src: [in] gray_u16 image

  • src_len: [in] count of u16 points in gray_u16 image

  • balance: [in] [-1024, 1024] -> [darkest, brightest]

int itof_cmap_gray_f32_to_IR(uint8_t *dst, int dst_len, const float *src, int src_len, int balance)

convert gray_f32 image to IR image whose pixel is in [0~255]

Return

int [out] the count of IR image

Parameters

  • dst: [out] IR image buffer

  • dst_len: [in] IR image buffer size in bytes

  • src: [in] gray_f32 image

  • src_len: [in] count of f32 points in gray_f32 image

  • balance: [in] [-1024, 1024] -> [darkest, brightest]

int itof_file_open(const char *fname, const char *mode)

open specified file and get file descriptor for itof_frame_save_xxx apis.

Return

int [out] file descriptor. < 0 = failed

Parameters

  • fname: [in] specified filename

void itof_file_close(int fd)

close specified file descriptor

Parameters

  • fd: [in] specified file descriptor

bool itof_frame_save_raw(int fd, itof_frame_save_fmt_t save_fmt, const uint16_t *raw, int raw_len, int img_w, int img_h, int dcs_cnt, const char *raw_tag)

save specified raw data (in uin16_t) with specified pixcel width and height to file with specified saving format.

Return

bool [out] true = save raw frame ok, false = fail

Parameters

  • fd: [in] specified file handler

  • save_fmt: [in] file saving format defined in itof_frame_save_fmt_t. only followin format is supported: ITOF_FRAME_SAVE_UINT32 ITOF_FRAME_SAVE_UINT16

  • raw: [in] raw data

  • raw_len: [in] number of raw data (in count of uint16_t)

  • img_w: [in] dist data pixel width

  • img_h: [in] dist data pixel height

  • dcs_cnt: [in] dist data dcs sub-frame count

  • raw_tag: [in] any string. if want to used by replay, specify (itof_t*)dev->product string here.

bool itof_frame_save_distance(int fd, itof_frame_save_fmt_t save_fmt, const float *dist, int dist_len, int img_w, int img_h)

save specified distance data (in float32, unit: meter) with specified pixcel width and height to file with specified saving format.

Return

bool [out] true = save distance frame ok, false = fail

Parameters

  • fd: [in] specified file handler

  • save_fmt: [in] file saving format defined in @ itof_frame_save_fmt_t. only followin format is supported: ITOF_FRAME_SAVE_FLOAT32 ITOF_FRAME_SAVE_UINT32 ITOF_FRAME_SAVE_UINT16

  • dist: [in] distance data (in float32, unit: meter)

  • dist_len: [in] number of distance data (in count of float)

  • img_w: [in] dist data pixel width

  • img_h: [in] dist data pixel height

bool itof_frame_save_gray(int fd, itof_frame_save_fmt_t save_fmt, const float *src, int src_len, int img_w, int img_h)

save specified gray data (in float32) with specified pixcel width and height to file with specified saving format.

Return

bool [out] true = save distance frame ok, false = fail

Parameters

  • fd: [in] specified file handler

  • save_fmt: [in] file saving format defined in itof_frame_save_fmt_t. only followin format is supported: ITOF_FRAME_SAVE_UINT16 ITOF_FRAME_SAVE_UINT8

  • src: [in] gray data (in float32)

  • src_len: [in] number of distance data (in count of float)

  • img_w: [in] dist data pixel width

  • img_h: [in] dist data pixel height

int itof_frame_load_raw(int fd, uint16_t *dst, int dst_len, int *dst_w, int *dst_h, int *dst_dcsn, char *dst_tag, int dst_tag_len)

load one raw frame from specified file fd.

Return

int [out] length of loaded raw data (in count of sizeof(uint16))

Parameters

  • fd: [in] specified data file fd. The fd related file is always saved by itof_frame_save_raw api

  • dst: [out] raw

  • dst_len: [in] dst buffer length (in count of sizeof(uint16_t))

  • dst_w: [out] raw frame pixel width

  • dst_h: [out] raw frame pixel height

  • dst_dcsn: [out] raw dcs cnt per frame

  • dst_tag: [out] raw data tag string

  • tag_len: [in] raw data tag buffer size

int itof_frame_load_distance(int fd, float *dst, int dst_len, int *dst_w, int *dst_h)

load one distance frame from specified file fd.

Return

int [out] length of loaded distance data (in count of sizeof(float))

Parameters

  • fd: [in] specified data file fd. The fd related file is always saved by itof_frame_save_distance api

  • dst: [out] distance in float (unit: meter)

  • dst_len: [in] dst buffer length (in count of sizeof(float))

  • dst_w: [out] distance frame pixel width

  • dst_h: [out] distance frame pixel height

int itof_frame_load_gray(int fd, float *dst, int dst_len, int *dst_w, int *dst_h)

load one gray frame from specified file fd.

Return

int [out] length of loaded gray data (in count of sizeof(float))

Parameters

  • fd: [in] specified data file fd. The fd related file is always saved by itof_frame_save_gray api

  • dst: [out] gray in float (unit: meter)

  • dst_len: [in] dst buffer length (in count of sizeof(float))

  • dst_w: [out] gray frame pixel width

  • dst_h: [out] gray frame pixel height

bool dmcam_get_lens_param(itof_dev_t *dev, dmcam_camera_para_t *param, uint8_t id)

get lens calibration data from calibration data

Return

bool[out] true=ok, false=failed

Parameters

  • dev[in]device: handler

  • : param

  • [int]iddefualt: use 0

struct itof_dev_if_info_usb

Public Members

uint8_t usb_bus_num
uint8_t usb_port_num
uint8_t usb_dev_addr
uint8_t usb_speed
struct itof_dev_if_info_eth

Public Members

uint8_t addr[16]
uint8_t reserved[16]
uint32_t token
uint32_t cid
struct itof_dev_if_info_fil

Public Members

void *fd
char *fname
struct itof_dev_if_info_t

Public Members

itof_dev_if_e type
struct itof_dev_if_info_usb usb
struct itof_dev_if_info_eth eth
struct itof_dev_if_info_fil fil
union itof_dev_if_info_t::@0 info
union itof_dev_ver_u

Public Members

uint16_t version[4]
uint16_t hw_ver
uint16_t sw_ver
uint16_t sw2_ver
uint16_t hw2_ver
struct itof_dev_ver_u::@1 ver
struct itof_dev_t
#include <dmcam.h>

dmcam device structure. It describes device usb port info, device info

Public Members

void *handler
itof_dev_if_info_t if_info
char product[32]
char vendor[32]
char serial[32]
uint64_t dev_id

device uniq id

itof_dev_ver_u version
char *expath

extract path to store calibration data,can be set by itof_path_cfg

void *lock

device lock

void *user_data0

used internally for python extension

void *user_data1

used internally for python extension

uint8_t init_flag

struct init flag

uint8_t alloc_flag

malloc flag used internally

uint8_t api_flag

sync between frame wait/get and normal api

struct dmcam_camera_para_t
#include <dmcam.h>

camera parameters

Public Members

float cx

center point x

float cy

center point y

float fx

focal length x

float fy

focal length y

float dcoeff[5]

distortion coef

struct itof_param_roi_t
#include <dmcam.h>

Frame size and Max frame size can be get from paramter interface using the PRAM_INFO_ROI parameter.

Note

: For PARAM_INFO_ROI, it’s format like follows. (srow,scol)_ _ _ _ _ _ _ _ _ | | | ROI | |_ _ _ _ _ _ _ _ _| (erow,ecol) frame size = (ecol - scol) * (erow - srow) * pixel_width;frame roi value

Public Members

uint16_t srow

start address for row,multiple of 16

uint16_t erow

end address for row,multiple of 16

uint16_t scol

start address for columon,multiple of 16

uint16_t ecol

end address for columon,multiple of 16

uint8_t binning

binning mode for some sensor

uint32_t max_fsize

MAX frame size

struct itof_cap

Public Members

uint16_t max_frame_width
uint16_t max_frame_height
uint16_t max_frame_depth
uint16_t max_fps
uint16_t max_intg_us
uint8_t illum_board_type
uint8_t sensor_board_type
union itof_param_val_u
#include <dmcam.h>

dmcam param value

Public Members

uint8_t raw[18]
uint32_t dev_mode
uint32_t mod_freq

system calibration frequency

uint32_t calib_data_type
char info_vendor[18]

camera vendor information

char info_product[18]

camera production information

uint16_t ambient_light_coeff
itof_param_cap_t info_capability

device capablity

uint32_t serial[3]

serials numbers

struct itof_param_val_u::@2 info_serial
uint16_t hw_ver

hardware1 version

uint16_t sw_ver

firmware1 version

uint16_t sw2_ver

firmware2 version

uint16_t hw2_ver

hardware2 version

struct itof_param_val_u::@3 info_version
uint32_t format

frame format

struct itof_param_val_u::@4 frame_format
uint32_t fps

frame rate

struct itof_param_val_u::@5 frame_rate
uint8_t random_delay_en
uint16_t delay
struct itof_param_val_u::@6 sync_delay
itof_param_roi_t roi

image roi

uint8_t percent

illumination power

struct itof_param_val_u::@7 illum_power
uint16_t intg_us

first integration time(normal mode or HDR mode)

struct itof_param_val_u::@8 intg
uint16_t intg_3dhdr

second integration time in HDR mdoe

struct itof_param_val_u::@9 intg_hdr
uint16_t corr1
uint16_t corr2
struct itof_param_val_u::@10 phase_corr
int16_t tl_cal
int16_t tr_cal
int16_t bl_cal
int16_t br_cal
int16_t ib_cal
struct itof_param_val_u::@11 temp
uint8_t valid

data is valid;1==valid

1:coeff is valid; 0: coeff in not valid

uint8_t flag

0:no compression used;1:zip compression used

uint32_t ID

data info, version

uint32_t timestamp

calibration date

uint32_t fsize

head+data+paddingsize

uint32_t datasize

data size

struct itof_param_val_u::@12 cinfo

calibration info

uint16_t part_ver

chip part version

uint16_t chip_id

chip id

uint16_t wafer_id

wafer id

struct itof_param_val_u::@13 chip_info
float offset

system calib offset

float coeff

system calib coeff

uint32_t random_freq

random frequency

uint8_t frm_format

calibration frame format

struct itof_param_val_u::@14 sys_calib_coeff
uint32_t sec
uint32_t us
struct itof_param_val_u::@15 sync_time
uint32_t mod_freq0

modulation frequency0

uint32_t mod_freq1

modulation frequency1

struct itof_param_val_u::@16 dual_freq
float cx

center point x

float cy

center point y

float fx

focal length x

float fy

focal length y

struct itof_param_val_u::@17 lens_param
uint8_t total_cnt

calibration frequency count

uint8_t remain_cnt
uint8_t freq[4]
struct itof_param_val_u::@18 calib_freq
struct itof_param_item_t
#include <dmcam.h>

param data struct

Public Members

itof_dev_param_e param_id

param id

uint8_t param_val_len

param length

itof_param_val_u param_val

param value

struct itof_frame_info_t
#include <dmcam.h>

Used for store frame information

Public Members

uint32_t frame_size

frame size in bytes

uint16_t frame_format

frame format code (sensor dependent)

uint16_t frame_idx

frame index

uint32_t width

image width

uint32_t height

image height

uint8_t depth

reserved

uint8_t pixel_format

internal use

uint16_t priv_code

internal use

int16_t temp0
int16_t temp1

sensor and illumination board temperature

uint32_t rx_ts

frame rx unix timestamp

uint32_t rx_us

frame rx microseconds

struct itof_frame_t
#include <dmcam.h>

frame data struct

Public Members

itof_frame_info_t frame_info

frame informatin

void *frame_data

frame data pointer

struct itof_cap_cfg_t
#include <dmcam.h>

capture configuration params

Public Members

uint32_t cache_frames_cnt

max frame count in frame buffer (cache)

itof_cap_frdy_f on_frame_ready

callback when frame is ready in the frame buffer; invoked in itof_cap_get_frames

itof_cap_err_f on_error

callback when error happens during capturing; invoked in itof_cap_get_frames

uint8_t en_save_manually

if set to 1, saving is manually controlled by itof_cap_save_frame/dist/gray

uint8_t en_save_replay

enable saving replay file during capturing. saving happens in itof_cap_get_frames

uint8_t en_save_dist_u16

enable saving dist_u16 file during capturing. saving happends in itof_cap_get_dist_xx

uint8_t en_save_gray_u16

enable saving gray_u16 file during capturing. saving happends in itof_cap_get_gray_xx

char *fname_replay

replay file name

uint8_t en_fdev_rewind

only used when type of the device is reaply-file. if true, capture will auto rewind when the EOF of file is met

union itof_filter_args_u
#include <dmcam.h>

filter args

Public Members

uint16_t raw
uint8_t case_idx

User Scenario index

uint32_t lens_id

ITOF_FILTER_ID_LEN_CALIB parameter: length index

uint16_t min_amp

ITOF_FILTER_ID_AMP parameter: Min amplitude threshold

uint16_t sat_ratio

ITOF_FILTER_ID_AUTO_INTG parameter: saturation ratio threshold

uint16_t sync_delay

ITOF_FILTER_ID_SYNC_DELAY parameter: sync delay: 0 = random delay, 1 = specified delay in ms

int16_t temp_threshold

ITOF_FILTER_ID_TEMP_MONITOR paramter: Temperature threshold for temperature monitor

uint16_t intg_3d

intg_3d: exposure time 0

uint16_t intg_3dhdr

intg_3dhdr: exposure time 1

struct itof_filter_args_u::@19 intg

ITOF_FILTER_ID_HDR paramter

uint8_t median_ksize

ITOF_FILTER_ID_MEDIAN paramter: DEPRECATED, please use ITOF_FILTER_ID_DEPTH_FILTER

int32_t offset_mm

ITOF_FILTER_ID_OFFSET paramter : offset in mm for DMCMA_FILTER_ID_OFFSET filter

uint8_t sport_mode

ITOF_FILTER_ID_SPORT_MODE parameter: 0 = high motion mode, 1 = extrem high motion mode

uint16_t k_ambient_light

ITOF_FILTER_ID_AMBIENT_LIGHT_CALIB kcoeff of ambient light calibration

uint8_t col_reduction

column binning:0 no binning, 1 by half

uint8_t row_reduction

row binning: 0 no binning, 1 by half, 2 a quarter

struct itof_filter_args_u::@20 binning_info
uint8_t depth_filter_mode

0xF0 = filter strength controlled by depth_filter_strength Other values = filter controlled automatically

uint8_t depth_filter_strength

ITOF_FILTER_ID_DEPTH_FILTER strength: [0, 31]

struct itof_filter_args_u::@21 @22
uint8_t fly_noise_threshold

fly noise threshold 0~255

struct itof_filter_args_u::@23 @24
struct itof_cmap_cfg

Public Members

itof_cmap_palette_e color_palette
uint8_t histeq_en