dmcam 1.82.7
DM camera python extension

# Introduction

The **dmcam** Python extension is part of [SmartToF SDK](https://github.com/smarttofsdk/SDK), it's developed for python programmers to interacting with SmartToF Module. 



# Quick example
~~~Python
import sys, os
import numpy as np
import time

import dmcam

# --  init the lib with default log file
dmcam.init(None)
# --  init with specified log file
# dmcam.init("test.log")

# -- set debug level
dmcam.log_cfg(dmcam.LOG_LEVEL_INFO, dmcam.LOG_LEVEL_DEBUG, dmcam.LOG_LEVEL_NONE)

# -- list device
print(" Scanning dmcam device ..")
devs = dmcam.dev_list()
if devs is None:
    print(" No device found")
    sys.exit(1)

print("found %d device" % len(devs))

for i in range(len(devs)):
    print("#%d: %s" % (i, dmcam.dev_get_uri(devs[i], 256)[0]))

print(" Open dmcam device ..")
# open the first device
dev = dmcam.dev_open(devs[0])
# Or open by URI
# dev = dmcam.dev_open_by_uri("xxxx")
assert dev is not None

# - set capture config  -
cap_cfg = dmcam.cap_cfg_t()
cap_cfg.cache_frames_cnt = 10  # framebuffer = 10
cap_cfg.on_error = None        # use cap_set_callback_on_error to set cb
cap_cfg.on_frame_rdy = None    # use cap_set_callback_on_frame_ready to set cb
cap_cfg.en_save_replay = True  # True = save replay, False = not save
cap_cfg.en_save_dist_u16 = False # True to save dist stream for openni replay
cap_cfg.en_save_gray_u16 = False # True to save gray stream for openni replay
cap_cfg.fname_replay = os.fsencode("dm_replay.oni")  # set replay filename

dmcam.cap_config_set(dev, cap_cfg)
# dmcam.cap_set_callback_on_frame_ready(dev, on_frame_rdy)
# dmcam.cap_set_callback_on_error(dev, on_cap_err)

print(" Set paramters ...")
wparams = {
    dmcam.PARAM_INTG_TIME: dmcam.param_val_u(),
    dmcam.PARAM_FRAME_RATE: dmcam.param_val_u(),
}
wparams[dmcam.PARAM_INTG_TIME].intg.intg_us = 1000
wparams[dmcam.PARAM_FRAME_RATE].frame_rate.fps = 20

if not dmcam.param_batch_set(dev, wparams):
    print(" set parameter failed")

print(" Start capture ...")
dmcam.cap_start(dev)

f = bytearray(320 * 240 * 4 * 2)
print(" sampling 100 frames ...")
count = 0
run = True
while run:
    # get one frame
    finfo = dmcam.frame_t()
    ret = dmcam.cap_get_frames(dev, 1, f, finfo)
    # print("get %d frames" % ret)
    if ret > 0:
        w = finfo.frame_info.width
        h = finfo.frame_info.height

        print(" frame @ %d, %d, %dx%d" %
              (finfo.frame_info.frame_idx, finfo.frame_info.frame_size, w, h))

        dist_cnt, dist = dmcam.frame_get_dist_u16(dev, w * h, f, finfo.frame_info)
        gray_cnt, gray = dmcam.frame_get_gray_u16(dev, w * h, f, finfo.frame_info)

        count += 1
        if count >= 100:
            break

    else:
        break
    time.sleep(0.01)
    # break

print(" Stop capture ...")
dmcam.cap_stop(dev)

print(" Close dmcam device ..")
dmcam.dev_close(dev)

dmcam.uninit()
~~~

# Changelog

* 1.80.4:
  * **API change**
    * **New**: *dmcam_cmap_palette_set/get*
      * set and get default color palette for pesudo RGB image convertion colormap
      * support 60+ color palette (naming similar with matplotlib) in *dmcam_cmap_palette_e*
    * **Change**:  *dmcam_cmap_dist_f32_to_RGB/dmcam_cmap_dist_u16_to_RGB* 
      * add a *dmcam_cmap_cfg_t* parameter to support user specified color palette. 
      * For compatible, user can simply set this parameter to NULL to use the default color palette.
    * **New**:  *PARAM_FLIP*
      * added in *dmcam_dev_param_e* to support image flip in sensor side (currently IMX556 only).
    * **New**: *dmcam_cap_save_frame*
      * use to better choosing which frame to be saved into ONI replay file.
    * **New**: *en_save_manually*
      * added in *dmcam_cap_cfg_t* to enable user to use *dmcam_cap_save_frame*  to save specified frame.
    * **New**: *DMCAM_FILTER_ID_FLYNOISE* 
      * Added in *dmcam_filter_id_e* as fly noise filter id.
      * *fly_noise_threshold* is added in *dmcam_filter_args_u* as fly noise threshold, valid range from 0 to 255
    * **Enhance**: add parameter for *DMCAM_FILTER_ID_DEPTH_FILTER*  to fine control the filter strength
      * *depth_filter_mode/depth_filter_strength* is added to *dmcam_filter_args_u*
    * **REMOVE**: *dmcam_cmap_gray_u16_to_RGB32/dmcam_cmap_gray_f32_to_RGB32*
  * **Main features:**
    * All linux python wheel are generated with manylinux2010 standard
    * Support NEW SmartToF TC-S3 (SONY IMX556 VGA TOF) device.
    * Support Dual-freq mode for SONY TOF devices.
    * Support 60+ color palette which is similar with the colormap defined in matplotlib.
    * Add SSE2 optimization on depth filter/colormap conversion.
    * Make fly-noise filter accessible and the filter strength can be controlled by *DMCAM_FILTER_ID_FLYNOISE*  filter.
    * Enhance recording  function: *dmcam_cap_config_set* can be used to start/stop recording during capturing without the need to stop capturing.
  * **BUG fix:**
    * Fix stall of USB layer sometimes when cap_start/cap_stop are invoked in multi-thread  app.
    * Fix wrong value in IR image under ARM-v7 platform.
* 1.70.0:
  * **Recommend to upgrade device firmware to 1.70 to use this SDK**
  * **API change**
    * Remove deprecated *dmcam_cmap_float*
    * change *dmcam_param_roi_t* structure
    * remove filter id DMCAM_FILTER_ID_BINNING 
  * **New**:  support dual-freq of SONY IMX556
  * **New**:  support binning mode
    - EPC driver: 2x2, 4x4 and 2x4
    - IMX driver: 2x2, 4x4, and 8x8
  * **New**:  ethernet based Tof camera support 
  * **Enhance**: Use parameter set/get API with parameter id PARAM_ROI to set ROI and Binning instead of using filter interface. 
  * **Enhance**: better support replay in HDR /Dual-freq/Binning mode
  * **FIX**:
    * C sample compiling issue
    * wrong frame info when seeking frames of oni file
    * First frame checksum error sometimes
* 1.68.2:
  - **Fix:**  Correct to set gray/ir value to be zero when overexposure.
  - **New**:  add DMCAM_FILTER_ID_BINNING to support pix binning
  - **Enhance**: better support ROI.
* 1.68.1:
  * **Enhance:**  Optimize TC-E2 accuracy and error correction of calibration data.
  * **New**: add parameter id *PARAM_INFO_LENS* for user to get lens parameter through *dmcam_param_batch_get*
* 1.68.0:
  - **Enhance:**  
    - replay supports gray frames related with ambient compensation from FW 164
    - replay support switching between HDR to normal mode.
    - *dmcam_dev_get_uri* returns URI with token for eth devices
    - Enhance performance of *dmcam_frame_get_pcl_xyzd* and *dmcam_frame_get_pcl_xyzi*
  - **New**: 
    - add  *dmcam_frame_get_pcl_xyzi* api to get point clouds with gray as texture
    - add *dmcam_cap_seek_frame* api to seek frames when device is replay-file
    - add *dmcam_frame_get_dist_raw* for user to get raw distance without calibration
    - For sony sensors:
      - add compression support for SONY sensor
      - Filter chain optimized
      - Calibration method refined.
  - **Fix**:
    - lens paramter file not closed after open
    - recorded replay file without timestamp
    - device cannot close properly sometimes (FW ver= 164/165)
* 1.62.2:
  - **FIX:**  the problem that replay file size > 2GB may not work properly under windows 
  - **Enhance**: some kind of error tolerance on playing corrupted replay file.
  - **Enhance**:  add *en_fdev_rewind* in *dmcam_cap_cfg_t* to allow rewind replay when use dmcam replay file as device.
* 1.62.1:
  - **Enhance:** during file replay mode, **if fps is set to 0**,  frame capture is only ongoing after invoking *dmcam_get_frames/dmcam_get_frame*  . This is usefully to pause & resume  the replay at application level
* 1.62.0:
  * **Fix:** replay problem when switch from QVGA to VGA
  * **Fix:** replay file cannot played in Niviewer of OpenNI
  * **Enhance:** optimize env-light compensation
* 1.61.6:
  * **Enhance:** optimize DIST&GRAY calc performance further (boost about 50%). TC-E3 can reach up-to 115fps @ Cortex-A7 1Ghz
  * **FIX:** TC-E3 replay problem
  * **FIX:**  wrong return value of *dmcam_cap_get_frames* when the host process is slow.
  * **New**: support SONY sensors
  * **New**: support env-light compensation
* 1.61.2: 
  * **Enhance** : optimize DIST&GRAY calc performance (boost about 40%)
  * **FIX**: *dmcam_frame_get_pcl_xyzd* and *dmcam_frame_get_pcl_xyz*  now return number of points (x,y,z) / (x,y,z,d) equal to the number of pixels of the depth image. Invalid point in the cloud is denoted as (0,0,0) and (0,0,0,0) respectively.
* 1.61.1: **Fix** a possible problem cause memory exhaustion.
* 1.61.0: **Fix**: unicode problem, all python API should use 'bytes' instead of 'str' to invoke  C API in type of 'char*' 
* 1.60.0: Major release
  * Support save replay and play replay.