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
DM_NAME
DM_VERSION_MAJOR
DM_VERSION_MINOR
DM_VERSION_REV
DM_VERSION_STR
DMCAM_ERR_CAP_FRAME_DISCARD
DMCAM_ERR_CAP_WRONG_STATE
DMCAM_ERR_CAP_CANCEL
DMCAM_ERR_CAP_TIMEOUT
DMCAM_ERR_CAP_STALL
DMCAM_ERR_CAP_ERROR
DMCAM_ERR_CAP_EOF
DMCAM_ERR_CAP_UNKNOWN
DM_SEEK_SET
DM_SEEK_CUR
DM_SEEK_END
API_DEPRECATED_FOR(f)
API_DEPRECATED

Typedefs

typedef struct dmcam_cap dmcam_param_cap_t
typedef void(* dmcam_cap_frdy_f)(dmcam_dev_t *dev, dmcam_frame_t *frame)

camera frame ready function prototype

typedef bool(* dmcam_cap_err_f)(dmcam_dev_t *dev, int err, void *err_args)

camera frame error function prototype

typedef struct dmcam_cmap_cfg dmcam_cmap_cfg_t

Enums

dmcam_dev_if_e

camera interface enum

Values:

0
DEV_IF_ETH
DEV_IF_FILE
99
dmcam_log_level_e

log levels

Values:

0
LOG_LEVEL_DEBUG
LOG_LEVEL_INFO
LOG_LEVEL_WARN
LOG_LEVEL_ERROR
LOG_LEVEL_NONE
dmcam_dev_rst_e

Values:

0
1
2
3
4
5
8
DEV_RST_CNT
dmcam_dev_mode_e

Values:

0
DEV_MODE_DFU
8
DEV_MODE_DATA_UP
dmcam_dev_reg_e

Values:

0
1
2
4
5
dmcam_frame_mode_e

Values:

0

gray

1

dist DCS*2, sine mode,with pi delay

2

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

3

dist DCS*1, PN mode,without pi delay

4

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

5

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

6

dist DCS*2, PN mode,with pi delay

7

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

8

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

0x0A

phase frame data

FRAME_FMT_GRAY

reserved

FRAME_FMT_LOSSY

reserved

0x0D

reserved

0x0E

reserved

0X0F

HDR mode

0X10

QI packed mode

0X11

Dual frequency QI packed mode

FRAME_FMT_CNT
dmcam_dev_param_e

dmcam param ID

Values:

0
PARAM_MOD_FREQ

modulation frequency

PARAM_INFO_VENDOR

production vendor information

PARAM_INFO_PRODUCT

production information

PARAM_INFO_CAPABILITY

production capability

PARAM_INFO_SERIAL

porduction serials id

PARAM_INFO_VERSION

HW&SW info

PARAM_INFO_SENSOR

part version, chip id, wafer id

PARAM_INFO_CALIB

get calibration info

PARAM_ROI

ROI set/get

PARAM_FRAME_FORMAT

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

PARAM_ILLUM_POWER

illumination power set/get

PARAM_FRAME_RATE

frame rate set/get

PARAM_INTG_TIME

integration time set/get

PARAM_PHASE_CORR

phase offset correction

PARAM_TEMP

<Get camera temperature———–

PARAM_HDR_INTG_TIME

<Setting HDR integration time param

PARAM_SYNC_DELAY

<delay ms for sync use

PARAM_SYS_CALIB_COEFF

system calibration coefficent

PARAM_SYNC_SYS_TIME

set/get module time

PARAM_AMBIENT_LIGHT_COEFF

set ambient light calibration coeff.

PARAM_DUAL_MOD_FREQ

set mod_freq

PARAM_INFO_LENS

Get lens param

PARAM_FLIP

image flip

PARAM_RESERVED

rererved

PARAM_INFO_CALIB_FREQ

calibration information

PARAM_DEL_CALIB_DATA

Delete calibration data

PARAM_ENUM_COUNT
dmcam_bin_data_type_e

Values:

BIN_DATA_TYPE_MCU
BIN_DATA_TYPE_TFC
BIN_DATA_TYPE_CALIB
dmcam_binning_mode_e

binning mode

Values:

DM_BINNING_1X1
DM_BINNING_2X2
DM_BINNING_4X4
DM_BINNING_8X8
DM_BINNING_2X4
DM_BINNING_CNT
dmcam_frame_fmt_e

Framae data format

Values:

0

distance data without calibration

DM_FRAME_FMT_DISTANCE

distance with calibration

DM_FRAME_FMT_GRAY

Confidence data

DM_FRAME_FMT_PCLOUD

pointcloud data

DM_FRAME_FMT_RGB

reserved

dmcam_filter_id_e

filter ID

Values:

DMCAM_FILTER_ID_LEN_CALIB

lens calibration

DMCAM_FILTER_ID_PIXEL_CALIB

pixel calibration

DMCAM_FILTER_ID_DEPTH_FILTER

Depth filter

DMCAM_FILTER_ID_RESERVED

RESERVED

DMCAM_FILTER_ID_AMP

Amplitude filter control

DMCAM_FILTER_ID_AUTO_INTG

auto integration filter enable : use sat_ratio to adjust

DMCAM_FILTER_ID_SYNC_DELAY

sync delay

DMCAM_FILTER_ID_TEMP_MONITOR

temperature monitor

DMCAM_FILTER_ID_HDR

HDR mode

DMCAM_FILTER_ID_OFFSET

set offset for calc distance

DMCAM_FILTER_ID_SPORT_MODE

set sport mode

DMCAM_FILTER_ID_SYS_CALIB

using system calibration param

DMCAM_FILTER_ID_AMBIENT_LIGHT_CALIB

using ambient light calib calibration param

DMCAM_FILTER_ID_FLYNOISE

fly noise filter

DMCAM_FILTER_ID_TEMP_CALIB
DMCAM_FILTER_ID_DEPTH_FILTER

MEDIAN is replaced with depth filter

DMCAM_FILTER_CNT
dmcam_cmap_palette_e

Values:

0
DMCAM_CMAP_HSV
DMCAM_CMAP_BWR
DMCAM_CMAP_JET
DMCAM_CMAP_GIST_RAINBOW
DMCAM_CMAP_RAINBOW
DMCAM_CMAP_SPECTRAL
DMCAM_CMAP_VIRIDIS
DMCAM_CMAP_INFERNO
DMCAM_CMAP_PLASMA
DMCAM_CMAP_MAGMA
DMCAM_CMAP_BLUES
DMCAM_CMAP_BUGN
DMCAM_CMAP_BUPU
DMCAM_CMAP_GNBU
DMCAM_CMAP_GREENS
DMCAM_CMAP_GREYS
DMCAM_CMAP_ORANGES
DMCAM_CMAP_ORRD
DMCAM_CMAP_PUBU
DMCAM_CMAP_PUBUGN
DMCAM_CMAP_PURD
DMCAM_CMAP_PURPLES
DMCAM_CMAP_RDPU
DMCAM_CMAP_REDS
DMCAM_CMAP_YLGN
DMCAM_CMAP_YLGNBU
DMCAM_CMAP_YLORBR
DMCAM_CMAP_YLORRD
DMCAM_CMAP_AFMHOT
DMCAM_CMAP_AUTUMN
DMCAM_CMAP_BONE
DMCAM_CMAP_COOL
DMCAM_CMAP_COPPER
DMCAM_CMAP_GIST_HEAT
DMCAM_CMAP_GRAY
DMCAM_CMAP_HOT
DMCAM_CMAP_PINK
DMCAM_CMAP_SPRING
DMCAM_CMAP_SUMMER
DMCAM_CMAP_WINTER
DMCAM_CMAP_BRBG
DMCAM_CMAP_COOLWARM
DMCAM_CMAP_PIYG
DMCAM_CMAP_PRGN
DMCAM_CMAP_PUOR
DMCAM_CMAP_RDBU
DMCAM_CMAP_RDGY
DMCAM_CMAP_RDYLBU
DMCAM_CMAP_RDYLGN
DMCAM_CMAP_SEISMIC
DMCAM_CMAP_GIST_EARTH
DMCAM_CMAP_TERRAIN
DMCAM_CMAP_OCEAN
DMCAM_CMAP_GIST_STERN
DMCAM_CMAP_BRG
DMCAM_CMAP_CMRMAP
DMCAM_CMAP_CUBEHELIX
DMCAM_CMAP_GNUPLOT
DMCAM_CMAP_GNUPLOT2
DMCAM_CMAP_GIST_NCAR
DMCAM_CMAP_NIPY_SPECTRAL
DMCAM_CMAP_FLAG
DMCAM_CMAP_PRISM
DMCAM_CMAP_COUNT
dmcam_cmap_outfmt_e

DMCAM color map output format definition

Values:

DMCAM_CMAP_OUTFMT_RGB
DMCAM_CMAP_OUTFMT_RGBA
DMCAM_CMAP_OUTFMT_BGR
DMCAM_CMAP_OUTFMT_COUNT
dmcam_frame_save_fmt_t

Values:

0
DMCAM_FRAME_SAVE_UINT32
DMCAM_FRAME_SAVE_UINT16
DMCAM_FRAME_SAVE_UINT8

Functions

void dmcam_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 (dmcam_YYYYMMDD.log) is used. if empty string “” is used, no log will generated

void dmcam_uninit(void)

Uninit the DM camera layer.

void dmcam_log_cfg(dmcam_log_level_e console_level, dmcam_log_level_e file_level, dmcam_log_level_e usb_level)

Set the logging configuration for dmcam layer.

Parameters

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

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

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

void dmcam_path_cfg(const char * path)

Setting where to save calibration data

Return

void

Parameters

  • path:

char* dmcam_path_get(void)

Getting calibration data path

Return

_API char*

const char* dmcam_error_name(int error_code)

covert specified error code into error string

Return

const char*

Parameters

  • error_code:

int dmcam_dev_list(dmcam_dev_t * dev_list, int dev_list_num)

list the dmcam device and fill into dmcam_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

dmcam_dev_t* dmcam_dev_open(dmcam_dev_t * dev)

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

Return

dmcam_dev_t* NULL = open device failed.

Parameters

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

dmcam_dev_t* dmcam_dev_open_by_fd(int fd)

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

Return

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

Parameters

  • fd: [in] specified fd

dmcam_dev_t* dmcam_dev_open_by_uri(const char * uri_str)

open specified dmcam device with specified uri.

Return

dmcam_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 dmcam_dev_close(dmcam_dev_t * dev)

Close specified dmcam device.

Parameters

  • dev:

const char* dmcam_dev_get_uri(dmcam_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 dmcam_dev_open

  • uri_str: [in] uri string buffer

  • uri_str_len: [in] uri string buffer len

bool dmcam_dev_reset(dmcam_dev_t * dev, dmcam_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 dmcam_dev_rst_e

bool dmcam_reg_batch_write(dmcam_dev_t * dev, dmcam_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 dmcam_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 dmcam_reg_batch_read(dmcam_dev_t * dev, dmcam_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 dmcam_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 dmcam_param_batch_set(dmcam_dev_t * dev, const dmcam_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] dmcam_param_item_t is used to denotes generic parameter:

    • param_id[in]: defined in dmcam_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 dmcam_param_batch_get(dmcam_dev_t * dev, dmcam_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] dmcam_param_item_t is used to denotes generic parameter:

    • param_id[in]: defined in dmcam_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 dmcam_cap_config_set(dmcam_dev_t * dev, const dmcam_cap_cfg_t * cfg)

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

Return

bool [out] true = set OK.

Parameters

  • dev: [in] specified dmcam device

  • cfg: [in] specified capture configuration

void dmcam_cap_config_get(dmcam_dev_t * dev, dmcam_cap_cfg_t * cfg)

Get capture configuration of specified device

Parameters

  • dev: [in] specified dmcam device

  • cfg: [out] capture configuration to be filled

void dmcam_cap_set_callback_on_frame_ready(dmcam_dev_t * dev, dmcam_cap_frdy_f cb)

register frame ready callback function

Parameters

  • dev: [in] dmcam device handler

  • cb: [in] callback function in following format: void (dmcam_cap_frdy_f)(dmcam_dev_t, dmcam_frame_t)

void dmcam_cap_set_callback_on_error(dmcam_dev_t * dev, dmcam_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 (dmcam_cap_err_f)(dmcam_dev_t, int errno);

bool dmcam_cap_snapshot(dmcam_dev_t * dev, uint8_t * frame_data, uint32_t frame_dlen, dmcam_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 dmcam_cap_is_ongoing(dmcam_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 dmcam_cap_start(dmcam_dev_t * dev)

start device capturing.

Return

bool return true = ok

Parameters

  • dev: [in] dmcam device handler

bool dmcam_cap_stop(dmcam_dev_t * dev)

stop device capturing.

Return

bool return true = ok

Parameters

  • dev: [in] dmcam device handler

int dmcam_cap_get_frames(dmcam_dev_t * dev, uint32_t frame_num, uint8_t * frame_data, uint32_t frame_dlen, dmcam_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 dmcam_cap_get_frame(dmcam_dev_t * dev, uint8_t * frame_data, uint32_t frame_dlen, dmcam_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 dmcam_cap_save_frame(dmcam_dev_t * dev, const uint8_t * frame_data, uint32_t frame_dlen, const dmcam_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 dmcam_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 dmcam_cap_seek_frame(dmcam_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 dmcam_firmware_upgrade(dmcam_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 dmcam_data_download(dmcam_dev_t * dev, char * name, uint8_t type, uint16_t version, uint32_t addr)
int dmcam_data_upload(dmcam_dev_t * dev, uint8_t type, const char * file_name)
int dmcam_frame_get_distance(dmcam_dev_t * dev, float * dst, int dst_len, uint8_t * src, int src_len, const dmcam_frame_info_t * finfo)

alias for dmcam_frame_get_dist_f32

int dmcam_frame_get_dist_raw(dmcam_dev_t * dev, uint16_t * dst, int dst_len, uint8_t * src, int src_len, const dmcam_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 dmcam_frame_get_dist_f32(dmcam_dev_t * dev, float * dst, int dst_len, uint8_t * src, int src_len, const dmcam_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 dmcam_frame_get_dist_u16(dmcam_dev_t * dev, uint16_t * dst, int dst_len, uint8_t * src, int src_len, const dmcam_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 dmcam_frame_get_gray(dmcam_dev_t * dev, float * dst, int dst_len, uint8_t * src, int src_len, const dmcam_frame_info_t * finfo)

alias for dmcam_frame_get_gray_f32

int dmcam_frame_get_gray_f32(dmcam_dev_t * dev, float * dst, int dst_len, uint8_t * src, int src_len, const dmcam_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 dmcam_frame_get_gray_u16(dmcam_dev_t * dev, uint16_t * dst, int dst_len, uint8_t * src, int src_len, const dmcam_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 dmcam_frame_get_pcl(dmcam_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 dmcam_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 dmcam_frame_get_pcl_xyzd(dmcam_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 dmcam_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 dmcam_frame_get_pcl_xyzi(dmcam_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 dmcam_filter_enable(dmcam_dev_t * dev, dmcam_filter_id_e filter_id, dmcam_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 dmcam_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 dmcam_filter_disable(dmcam_dev_t * dev, dmcam_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 dmcam_filter_id_e to identify the filter

bool dmcam_cmap_palette_set(dmcam_cmap_palette_e cm)

set default color palette used inside dmcam_cmap_ apis.

Return

bool true = set is ok. false = set failed

Parameters

  • cm: [in] color palette

dmcam_cmap_palette_e dmcam_cmap_palette_get(void)

get default color palette currently used.

Return

dmcam_cmap_palette_e current color palette

int dmcam_cmap_dist_f32_to_RGB(uint8_t * dst, int dst_len, const float * src, int src_len, dmcam_cmap_outfmt_e outfmt, float range_min_m, float range_max_m, const dmcam_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 dmcam_cmap_cfg_t. if NULL, default config is used.

int dmcam_cmap_dist_u16_to_RGB(uint8_t * dst, int dst_len, const uint16_t * src, int src_len, dmcam_cmap_outfmt_e outfmt, uint16_t range_min_mm, uint16_t range_max_mm, const dmcam_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 dmcam_cmap_cfg_t. if NULL, default config is used.

int dmcam_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 dmcam_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 dmcam_file_open(const char * fname, const char * mode)

open specified file and get file descriptor for dmcam_frame_save_xxx apis.

Return

int [out] file descriptor. < 0 = failed

Parameters

  • fname: [in] specified filename

void dmcam_file_close(int fd)

close specified file descriptor

Parameters

  • fd: [in] specified file descriptor

bool dmcam_frame_save_raw(int fd, dmcam_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 dmcam_frame_save_fmt_t. only followin format is supported: DMCAM_FRAME_SAVE_UINT32 DMCAM_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 (dmcam_t*)dev->product string here.

bool dmcam_frame_save_distance(int fd, dmcam_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 @ dmcam_frame_save_fmt_t. only followin format is supported: DMCAM_FRAME_SAVE_FLOAT32 DMCAM_FRAME_SAVE_UINT32 DMCAM_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 dmcam_frame_save_gray(int fd, dmcam_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 dmcam_frame_save_fmt_t. only followin format is supported: DMCAM_FRAME_SAVE_UINT16 DMCAM_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 dmcam_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 dmcam_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 dmcam_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 dmcam_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 dmcam_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 dmcam_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(dmcam_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 dmcam_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 dmcam_dev_if_info_eth

Public Members

uint8_t dmcam_dev_if_info_eth::addr[16]
uint8_t dmcam_dev_if_info_eth::reserved[16]
uint32_t token
uint32_t cid
struct dmcam_dev_if_info_fil

Public Members

void* fd
char* fname
struct dmcam_dev_if_info_t

Public Members

dmcam_dev_if_e type
struct dmcam_dev_if_info_usb usb
struct dmcam_dev_if_info_eth eth
struct dmcam_dev_if_info_fil fil
union dmcam_dev_if_info_t::@0 info
union dmcam_dev_ver_u

Public Members

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

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

Public Members

void* handler
dmcam_dev_if_info_t if_info
char dmcam_dev_t::product[32]
char dmcam_dev_t::vendor[32]
char dmcam_dev_t::serial[32]
uint64_t dev_id

device uniq id

dmcam_dev_ver_u version
char* expath

extract path to store calibration data,can be set by dmcam_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 dmcam_camera_para_t::dcoeff[5]

distortion coef

struct dmcam_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 dmcam_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 dmcam_param_val_u
#include <dmcam.h>

dmcam param value

Public Members

uint8_t dmcam_param_val_u::raw[18]
uint32_t dev_mode
uint32_t mod_freq

system calibration frequency

uint32_t calib_data_type
char dmcam_param_val_u::info_vendor[18]

camera vendor information

char dmcam_param_val_u::info_product[18]

camera production information

uint16_t ambient_light_coeff
dmcam_param_cap_t info_capability

device capablity

uint32_t dmcam_param_val_u::serial[3]

serials numbers

struct dmcam_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 dmcam_param_val_u::@3 info_version
uint32_t format

frame format

struct dmcam_param_val_u::@4 frame_format
uint32_t fps

frame rate

struct dmcam_param_val_u::@5 frame_rate
uint8_t random_delay_en
uint16_t delay
struct dmcam_param_val_u::@6 sync_delay
dmcam_param_roi_t roi

image roi

uint8_t percent

illumination power

struct dmcam_param_val_u::@7 illum_power
uint16_t intg_us

first integration time(normal mode or HDR mode)

struct dmcam_param_val_u::@8 intg
uint16_t intg_3dhdr

second integration time in HDR mdoe

struct dmcam_param_val_u::@9 intg_hdr
uint16_t corr1
uint16_t corr2
struct dmcam_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 dmcam_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 dmcam_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 dmcam_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 dmcam_param_val_u::@14 sys_calib_coeff
uint32_t sec
uint32_t us
struct dmcam_param_val_u::@15 sync_time
uint32_t mod_freq0

modulation frequency0

uint32_t mod_freq1

modulation frequency1

struct dmcam_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 dmcam_param_val_u::@17 lens_param
uint8_t total_cnt

calibration frequency count

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

param data struct

Public Members

dmcam_dev_param_e param_id

param id

uint8_t param_val_len

param length

dmcam_param_val_u param_val

param value

struct dmcam_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 dmcam_frame_t
#include <dmcam.h>

frame data struct

Public Members

dmcam_frame_info_t frame_info

frame informatin

void* frame_data

frame data pointer

struct dmcam_cap_cfg_t
#include <dmcam.h>

capture configuration params

Public Members

uint32_t cache_frames_cnt

max frame count in frame buffer (cache)

dmcam_cap_frdy_f on_frame_ready

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

dmcam_cap_err_f on_error

callback when error happens during capturing; invoked in dmcam_cap_get_frames

uint8_t en_save_manually

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

uint8_t en_save_replay

enable saving replay file during capturing. saving happens in dmcam_cap_get_frames

uint8_t en_save_dist_u16

enable saving dist_u16 file during capturing. saving happends in dmcam_cap_get_dist_xx

uint8_t en_save_gray_u16

enable saving gray_u16 file during capturing. saving happends in dmcam_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 dmcam_filter_args_u
#include <dmcam.h>

filter args

Public Members

uint16_t raw
uint8_t case_idx

User Scenario index

uint32_t lens_id

DMCAM_FILTER_ID_LEN_CALIB parameter: length index

uint16_t min_amp

DMCAM_FILTER_ID_AMP parameter: Min amplitude threshold

uint16_t sat_ratio

DMCAM_FILTER_ID_AUTO_INTG parameter: saturation ratio threshold

uint16_t sync_delay

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

int16_t temp_threshold

DMCAM_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 dmcam_filter_args_u::@19 intg

DMCAM_FILTER_ID_HDR paramter

uint8_t median_ksize

DMCAM_FILTER_ID_MEDIAN paramter: DEPRECATED, please use DMCAM_FILTER_ID_DEPTH_FILTER

int32_t offset_mm

DMCAM_FILTER_ID_OFFSET paramter : offset in mm for DMCMA_FILTER_ID_OFFSET filter

uint8_t sport_mode

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

uint16_t k_ambient_light

DMCAM_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 dmcam_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

DMCAM_FILTER_ID_DEPTH_FILTER strength: [0, 31]

struct dmcam_filter_args_u::@21 dmcam_filter_args_u::@22
uint8_t fly_noise_threshold

fly noise threshold 0~255

struct dmcam_filter_args_u::@23 dmcam_filter_args_u::@24
struct dmcam_cmap_cfg

Public Members

dmcam_cmap_palette_e color_palette
uint8_t histeq_en