MI TOF API

---

REVISION HISTORY

Revision No	Description	Date
1.0	Initial Release	10/11/2025

---

1. 概述

1.1. 模块说明

TOF(Time of Flight)通过红外光在空气中的飞行时间，计算出目标体的距离，用于深度感知、3D建模、手势识别。本文主要介绍MI_TOF相关接口，主要用于接收VIF原始数据，进行深度计算、校正、滤波处理后输出TOF深度信息的一套接口应用。

1.2. 基本结构

MI_TOF通过接收SENSOR->VIF的原始raw数据，送入内部算法calc_depth，依次经过calculate，calibration，filter流程，从而输出depth数据。

图1‑1：TOF数据流示意图

基于MI TOF 架构框图如下图：

1.TOF_DEMO：用于处理depth数据并通过uvc传输至上层app

2.MI VIF:接收sensor模块数据并送到TOF算法处理函数中计算DEPTH数据

3.MI SENSOR:调用底层驱动如drv_ms_cus_jm152a/jm152a获取原始图像数据

4.MI TOF/Algorithm:MI TOF api以及cacl/calibration/filter算法

图1‑2：MI tof架构图

1.3. 功能介绍

MI TOF支持以下功能：

1. 输入mipi的raw 数据，计算出IR、depth、PCL 点云数据
2. 支持IIR Denoise FlyPixel 等滤波算法
3. 支持软件自动曝光并可以通过参数配置不同的效果
4. 支持画面旋转/翻转
5. 解析包尾数据

1.4. 应用场景

MI tof应用于linux下tof的开发。

1.5. 开发流程

接口调用如下图：

图1‑3：API调用流程图

MI TOF处理流程介绍：

1. _TOFParseCalibration:解析标定文件calibration.bin;
2. _tof_dev_GetDeviceInfo:获取sensor的配置信息;
3. MI_TOF_init:TOF初始化，创建Algorithm线程，注册算法回调cacl_depth;
4. MI_Tof_RegisterDepthCallBack:注册Callback用于获取IR/depth/PCL;
5. tof_run线程:获取TOF RAW数据并通过API MI_Tof_PutRawIntoAlgo送入Algorithm线程并在Cacl_Depth中完成calculate/calibration/filter等动作得到IR/DEPTH/PCL数据;
6. Tof_GetDepth_Callback:获取深度数据用于上层的算法;
7. SDK 支持filter/AE 等功能;

---

1.6. 实例介绍

本实例展示了基于MI_TOF api进行开发的流程

数据流向:

• 底层sensor获取原始数据通过MIPI传输到VIF

• uvc tof demo调用MI_Tof_PutRawIntoAlgo把VIF Raw数据送到算法回调中进行计算

• uvc tof demo通过Tof_GetDepth_Callback获取数据送到UVC Driver

• UVC通过v4l2把数据送到PC端

控制流向:

• UVC driver向uvc tof demo发送sensor ctrl cmd

• 底层MI SENSOR接收并解析cmd

• 经过common sensor driver/JM sensor driver调用驱动的set/get接口

• 再通过MIPI把cmd转换成寄存器值写/读到sensor中

  
  图1-4：TOF流程图

注意：所展示的代码并不能直接编译运行，有部分流程处于回调函数中，实例代码并不完整，完整代码请参考：

• sdk\verify\sample_code\source\pcupid\uvc_tof\uvc_tof_demo\st_main_uvc.cpp

  /*
  处理raw数据，raw->phase->amplitude->depth，以及封装包尾数据，最后由callback输出depth数据
  */
  MI_U32 Calc_Depth(void* inputData, void* outputData, void* config)
  {
          calculate;
          calibration;
          filter;
          . . .
          pChannelParams->algoCallbackResult(channel, depth);
  }
  
  /*
  接收raw数据线程以及处理回调
  */
  void* AlgorithmThread(void* arg)
  {
  FrameInf_t                      instFrameInf;
  FrameInf_t                      outtFrameInf;
  mi_tof_pack_data                OutputPackId    = MI_TOF_PACK_DEPTH_DATA;
  MI_U32                          u32size     = 0x0;
  MI_TOF_Channel_Params_t*        pChannelParams =  NULL;
  MI_U8                           channel         = ((mi_tof_mod_thread_Arg *)arg)->channel;
  MI_U8                           mod             = ((mi_tof_mod_thread_Arg *)arg)->mod;
  
  if (channel >= MAX_TOTAL_TOF_CHANNEL)
  {
          TOF_ERR("algorithm error channel [%d]-->%p\n", channel,arg);
          return NULL;
  }
  
  pChannelParams =  pTofChannelParamsArray[channel];
  
  const static char str[][16] =
  {
          "Calc_Depth"
  };
  
  pChannelParams->u8ThreadRunning |= (0x01 << mod);
  
  printf("Algo channel[%d] [%s]start ThreadRunning=0x%x\n", channel, str[mod],pChannelParams->u8ThreadRunning);
  
  if (mod >= TOF_MOD_MAX)
  {
          TOF_ERR("no this mod[%d]", mod);
          pthread_exit(NULL);
          return NULL;
  }
  
  //Add exit thread Loop!!!!!!!
  while (pChannelParams->bForceStop == 0)
  {
          std::unique_lock<std::mutex> lck(pChannelParams->mtx);
          if(RawFrameQ[channel].empty())
          {
          pChannelParams->cv.wait_for(lck, std::chrono::seconds(FRAME_CAPTURE_TIME_OUT));
          continue;
          }
  
          u32size = _CalcTofFrameSize(OutputPackId, pChannelParams);
          outtFrameInf.pPacketAddr = (void *)malloc(u32size);
          if (NULL == outtFrameInf.pPacketAddr)
          {
          TOF_INFO("outtFrameInf pPacketAddr is null!\n");
          continue;
          }
  
          instFrameInf = (FrameInf_t)RawFrameQ[channel].front();
          outtFrameInf.nPts = instFrameInf.nPts;
          outtFrameInf.nFrameNum = instFrameInf.nFrameNum;
          TOF_TIME("->[ch%d]%s frame %lld cost %f ms\n",channel ,str[mod], instFrameInf.nFrameNum, (float)(MI_OS_GetTime() - instFrameInf.nPts)/1000.0);
  
          if (E_SUCCESS != pChannelParams->algoCallback[mod](&instFrameInf, &outtFrameInf, &channel))
          {
          free(outtFrameInf.pPacketAddr);
          outtFrameInf.pPacketAddr = NULL;
          }
  
          RawFrameQ[channel].pop();
  }
  
  TOF_WRN("\n Algo channel[%d] [%s]exit\n", channel, str[mod]);
  pChannelParams->u8ThreadRunning &= (~(0x01 << mod));
  pthread_exit(NULL);
  
  return E_SUCCESS;
  }
  
  /*
  tof run线程调用MI VIF api获取raw数据，并通过MI_Tof_PutRawIntoAlgo把vif raw数据送到AlgorithmThread线程进行下一步处理
  */
  void* Tof_Run(void *argv)
  {
          _GetSensorInfo(channel, tofCamerInfo);
          MI_SNR_SetFps(channel, 10);
          GetVifRawData(channel, VifRaw);
  
          ret = MI_Tof_PutRawIntoAlgo(channel, pOneFullFrame[idx], totalsz, VifRaw.stBufInfo.u64Pts);
  }
  
  /*
  main函数主要完成以下动作：
  1.ST_UvcInit->uvc device初始化，数据流和控制流通路
  2.ST_ParserIni->解析ini文件，获取系统初始化一些参数设定
  3.ST_Sys_Init->封装MI SYS api初始化SYSTEM模块
  4._TofCameraStart内部封装了_TOFCamera_Init和Tof_Init，
          _TOFCamera_Init->调用MI SNR api初始化sensor；调用_TOFParseCalibration解析标定文件calibration.bin，调用MI VIF api初始化vif
          Tof_Init->调用MI_Tof_Init初始化tof资源，创建AlgorithmThread线程，注册Calc_Depth算法回调
  5.创建tof_run线程，调用MI_Tof_RegisterDepthCallBack注册获取depth数据callback
  6.释放资源
  */
  int main(int argc, char **argv)
  {
  int ret = 0;
  
  MI_U8 i = 0;
  MI_U32 maxpacket[MAX_UVC_DEV_NUM] = {1024, 1024,192};
  MI_U8 mult[MAX_UVC_DEV_NUM] = {1, 1, 0},
  burst[MAX_UVC_DEV_NUM] = {0, 0, 0};
  MI_U8 intf[2 * MAX_UVC_DEV_NUM] = {0};
  MI_S32 mode = UVC_MEMORY_MMAP;
  MI_S32 trace_level = UVC_DBG_ERR;//UVC_DBG_TRACE;
  struct sigaction sigAction;
  sigAction.sa_handler = ST_HandleSig;
  sigemptyset(&sigAction.sa_mask);
  sigAction.sa_flags = 0;
  sigaction(SIGINT, &sigAction, NULL);
  MI_SNR_PAD_ID_e eSnrPad = E_MI_SNR_PAD_ID_NA;
  
  ST_DefaultArgs(&g_stConfig);
  #if TOF_SLAVE_MODE
  _tof_init_xvs();
  #endif
  
  // Init UVC
  ST_UVC_SetTraceLevel(trace_level);
  
  ST_UvcInit(g_device_num, maxpacket, mult, burst, intf, mode);
  
  printf("----------uvc_tof--------\n");
  
  for(i=1; i< argc; i++)
  {
          if(MI_SUCCESS != ST_ParserIni(argv[i], &eSnrPad))
          {
          printf("parse init fail \n");
          return 0;
          }
          strncpy(gSnrIni[eSnrPad], argv[i], ST_TOF_SNR_PATH_MAX);
          g_u8ChannelNum++;
  }
  
  /************************************************
  Step1:  init SYS
  *************************************************/
  STCHECKRESULT(ST_Sys_Init());
  
  //_TofCameraStart
  {
          MI_S32 s32Ret = 0;
  MI_S8 u8TaskName[64];
  
  MI_U16 tof_width = 0;
  MI_U16 tof_height = 0;
  mPthread_Run_Status = 1;
  
  for(int i=0; i<ST_MAX_SENSOR_NUM; i++)
  {
          if(gSnrPad[i] != E_MI_SNR_PAD_ID_NA)
          {
          //_TOFCamera_Init(gSnrPad[i], tof_width, tof_height);
          {
                  //sstar_init_snr(pstSensorAttr);
                  {
                          STCHECKRESULT(_TOFParseCalibration(eSnrPadId));
                  }
                  sstar_init_vif(pstVifAttr, tof_width, tof_height);
          }
          //Tof_Init(gSnrPad[i]);
          {
                  _GetSensorInfo(eSnrPad, g_tofCamerInfo)
                  //MI_Tof_Init(eSnrPad, &tofInitParams);
                  {
                          tof_set_amplitude_frame_type(pChannelParams->handle, (tof_hdr_frame_type)pChannelParams->tofParams.AmplitudeType);
  
                          {
                          mi_tof_mod_thread_Arg Arg1,Arg2,Arg3;
                          pthread_t             threadID;
  
                          Arg1.channel   = channel;
                          Arg1.mod       = MI_TOF_CALC;
  
                          sprintf((char *)threadname, "calc_depth#%1d", channel);
                          TOF_WRN("start AlgorithmThread:%s-->%p\n",threadname,&Arg1);
                          pthread_create(&threadID, NULL, AlgorithmThread, (void *)&Arg1);
                          pthread_setname_np(threadID, (char *)threadname);
                          pChannelParams->mRunAlgoThread[MI_TOF_CALC] = threadID;
                          MySystemDelay(1);
                          }
                          pChannelParams->algoCallback[MI_TOF_CALC]      = Calc_Depth;
                          tof_processor_set_hdr_mix_gain();
                  }
  
          }
          }
  }
  
  _TofCalcDepthSize(tof_width, tof_height, g_tof_irSize, g_tof_depthSize, g_tof_pclSize, g_tof_frameHeaderSize);
  printf("valid channelNum=%d g_tof_irSize=%d\n", g_u8ChannelNum, g_tof_irSize);
  
  for(int i=0; i<ST_MAX_SENSOR_NUM; i++)
  {
          if(gSnrPad[i] != E_MI_SNR_PAD_ID_NA)
          {
          if(pthread_create(&Tof_Thread_Run[i], NULL, Tof_Run, &gSnrPad[i]) == 0)
          {
          memset((char*)u8TaskName, 0x00, sizeof(u8TaskName));
          sprintf((char *)u8TaskName, "TofRun_%d",i);
          pthread_setname_np(Tof_Thread_Run[i] , (const char *)u8TaskName);
          }
          else
          {
          printf("%s tof run pthread_create failed\n", __func__);
          goto EXIT;
          }
          //use callback to get depth result
          MI_Tof_RegisterDepthCallBack(gSnrPad[i], Tof_GetDepth_Callback);
          g_u64lastTime[i] = MI_OS_GetTime();
          }
  }
  }
  
  while(!g_bExit)
  {
          MI_U32 u32Select = 0xff;
          printf("select 0: set depth low/high \n");
          printf("select 1: set debug params \n");
          printf("select 2: set sensor filter\n");
          printf("select 3: set sensor auto exposure\n");
          printf("select 13: exit\n");
          //printf("select 14: enable cus3a demo\n");
          scanf("%d", &u32Select);
          ST_Flush();
  
          if(u32Select == 0)
          {
          ST_TofSetDepthLowHigh();
          }
          else if(u32Select == 13)
          {
          g_bExit = TRUE;
          }
  
          usleep(100*1000);
  }
  _TofCameraStop();
  
  printf("!!!!!!!!!!!%s %d exit done\n",__FUNCTION__,__LINE__);
  
  EXIT:
  ST_UvcDeinit();
  
  return ret;
  }
  

2. API参考

功能模块API

	API名	功能
1	MI_Tof_Init	初始化TOF Channel
2	MI_Tof_UnInit	反初始化TOF Channel
3	MI_Tof_RegisterCallBack	注册TOF Channel的Mod函数回调
4	MI_Tof_UnRegisterCallBack	反注册TOF Channel的Mod函数回调
5	MI_Tof_PutRawIntoAlgo	送入一个完整TOF Channel完整原始Frame
6	MI_Tof_GetTofResult	获取INZI(亮度&深度)Frame
7	MI_Tof_ReleaseTofResult	释放INZI之前获取到的Frame
8	MI_Tof_SetFilter	动态开关TOF iir/denoise filter.
9	MI_Tof_GetFilter	获取filter的配置信息
10	MI_Tof_SetAutoExposure	动态开关TOF auto exposure. D
11	MI_Tof_GetAutoExposure	获取AE的开关，配置信息等
12	MI_Tof_SetDebugParams	设置TOF演算法debug 参数
13	MI_Tof_SetAmplitudeFrameType	动态控制amplitude使用high/low gain data计算。默认使用low gain。
14	MI_Tof_SetCalibrationType	动态开启/关闭calibration type。默认calibration type均开启。Debug接口
15	MI_Tof_SetDebugLevel	设置MI_TOF debug level。Debug接口
16	MI_Tof_RegisterDepthCallBack	注册“Get TOF depth”的 callback。
17	MI_Tof_UnRegisterDepthCallBack	注销“Get TOF depth” callback。
18	MI_Tof_ParseEmbedInfo	Get the information from the embed line
19	MI_Tof_EnableInterferenceDeteced	开启“多机对射时的干扰排除”功能
20	MI_Tof_DisableInterferenceDeteced	关闭“多机对射时的干扰排除”功能
21	MI_Tof_SetFlip	设定不同的flip类型
22	MI_Tof_SetIrThreshold	设定threshold， 小于该threshold，depth会输出0
23	MI_Tof_SetAeParam	设定AE 参数
24	MI_Tof_GetAeParam	获取AE 参数
25	MI_Tof_SetRotation	设定画面Rotation 功能

2.1. MI_Tof_Init

• 功能

  初始化TOF Channel

• 语法

  MI_S32 MI_Tof_Init(MI_U8 channel,
  
  MiTofParams_t* pInitParams);
  

• 形参

  参数名称	描述	输入/输出
  Channel	Channel 可以支持0~3，默认最大支持4路Sensor chanel，需要需要上层做好Sensor chmap/Port和channel映射关系，MI_TOF不会去绑定具体的HW配置	输入
  pInitParams	初始化参数，设置channel对应Sensor HW属性，Cali/AE/Filter参数	输入

• 返回值

  • E_SUCCESS 成功初始化TOF Channel，重复创建，如果之前成功的话也是返回E_SUCCESS

  • -1 初始化失败，资源不足或者参数错误.

• 依赖

  • 头文件:PacketModule.h、mid_sys.h、mi_sys_datatype.h、tof_algorithm.h、TofChannelFrame.h

• 注意

  最多支持4路，若系统资源不足会初始化失败

  AE参数设定参考如下：

  
  图1‑5：AE参数设定图

• 举例

  MiTofParams_t tofInitParams;
  
  MiTofSensorHwParams_t TofHwParams;
  
  MixerRawBufInfo_t VifRaw;
  
  MiTofInterferenceDetecedParams_t pDectectdParams;
  
  memset(&VifRaw, 0x0, sizeof(MixerRawBufInfo_t));
  
  //Get Sensor Device infor
  
  tof_sensor_information tofCamerInfo;
  
  memset(&tofCamerInfo, 0, sizeof(tofCamerInfo));
  
  memset(&tofInitParams, 0, sizeof(MiTofParams_t));
  
  if (0 == MI_SNR_CustFunction(E_MI_SNR_PAD_ID_1, CMDID_GET_DEVICE_INFO, sizeof(tofCamerInfo), &tofCamerInfo, E_MI_SNR_CUSTDATA_TO_USER))
  
  {
  
  //setting TOF HW Sensor Params
  
  TofHwParams.width = tofCamerInfo.width;
  
  TofHwParams.height = tofCamerInfo.height;
  
  TofHwParams.pixel_size = tofCamerInfo.pixel_size;
  
  TofHwParams.raw_format = tofCamerInfo.raw_format;
  
  TofHwParams.hdr_type = tofCamerInfo.hdr_type;
  
  TofHwParams.dualFreq = tofCamerInfo.de_aliasing;
  
  TofHwParams.mod_freq1 = tofCamerInfo.mod_freq1;
  
  TofHwParams.mod_freq2 = tofCamerInfo.mod_freq2;
  
  TofHwParams.chip_id = tofCamerInfo.chip_id;
  
  TofHwParams.one_quad_one_footer = tofCamerInfo.one_quad_one_footer;
  
  tofInitParams.SensorHwParams = TofHwParams;
  
  tofInitParams.AmplitudeType = MI_TOF_HDR_FRAME_MIX; {
  
  if(tofCamerInfo.dll_sw_calib_capability)
  
  {
  
  tofInitParams.mDllFilterParams.SetDllClibSwConfig = _tof_SetDllClibSwConfig;
  
  tofInitParams.mDllFilterParams.filter_gain = 8;
  
  }
  
  //[SDR]
  
  tof_ae_sdr_params stAESdrParams =
  
  {
  
  .black_level = 16,
  
  .yth_low = 588,
  
  .yth_high = 1888,
  
  .upper_cnt_limitH = 6680,
  
  .upper_cnt_limitL = 1,
  
  .exp_limit_low = 20000,
  
  .exp_limit_high = 1500000,
  
  .exp_step_slow = 20000,
  
  .exp_step_fast = 500000,
  
  };
  
  //[HDR]
  
  tof_ae_hdr_params stAEHdrParams =
  
  {
  
  .black_level = 16,
  
  .yth_low = 280,
  
  .yth_high = 1080,
  
  .upper_cnt_limitH = 360,
  
  .upper_cnt_limitL = 1,
  
  .exp_limit_low = 10000,
  
  .exp_limit_high = 400000,
  
  .exp_step_slow = 10000,
  
  .exp_step_fast = 200000,
  
  };
  
  tofInitParams.AEParams.sdrParams = stAESdrParams;
  
  tofInitParams.AEParams.hdrParams = stAEHdrParams;
  
  tofInitParams.AEParams.GetAETimeNs = _tof_GetIntegratimTime;
  
  tofInitParams.AEParams.SetAETimeNs = _tof_SetIntegratimTime;
  
  tofInitParams.AEParams.AutoExposure = true;
  
  }
  
  //Fill filter Params
  
  {
  
  tof_iir_params iir_params;// = pTofChannelParams[channel]->tofParams.FilterParams.iirParams;
  
  tof_denoise_params denoise_params;// = pTofChannelParams[channel]->tofParams.FilterParams.denoiseParams;
  
  iir_params.gain = 128;
  
  denoise_params.mode = 1;
  
  denoise_params.lpf_th = 52;
  
  denoise_params.flypix_threshold = 1000;
  
  tofInitParams.FilterParams.iirParams = iir_params;
  
  tofInitParams.FilterParams.denoiseParams = denoise_params;
  
  tofInitParams.FilterParams.iirEnable = true;
  
  tofInitParams.FilterParams.denoiseEnable = true;
  
  if(TofHwParams.mod_freq2 != 0)
  
  {
  
  MiTofDealiaseFlyPixelParams_t dealiaseFPParams;
  
  dealiaseFPParams.low_threshold = 800;
  
  dealiaseFPParams.high_threshold = 3200;
  
  tofInitParams.FilterParams.dealiaseFlyPixelParams = dealiaseFPParams;
  
  tofInitParams.FilterParams.dealiaseFlyPixelEnable = true;
  
  }
  
  g_tofSetFilter |= ((tofInitParams.FilterParams.iirEnable)?MI_TOF_FILTER_IIR:0);
  
  if(tofInitParams.FilterParams.denoiseEnable)
  
  {
  
  switch(denoise_params.mode)
  
  {
  
  case 1:
  
  g_tofSetFilter |= MI_TOF_FILTER_DENOISE;
  
  break;
  
  case 2:
  
  g_tofSetFilter |= MI_TOF_FILTER_FLYING_PIXEL;
  
  break;
  
  default:
  
  break;
  
  }
  
  }
  
  g_tofSetFilter |= ((tofInitParams.FilterParams.dealiaseFlyPixelEnable)?MI_TOF_FILTER_DEALIASE_FLYPIXEL:0);
  
  g_tofSetFilter_pre = g_tofSetFilter;
  
  }
  
  // Fill Calib Params
  
  {
  
  char *binpath = (char *)"calibration.bin";
  
  jmcam_persistence_util_block_device_header block_device_header;
  
  char *block_image = NULL;
  
  struct stat buf;
  
  FILE *p = NULL;
  
  int result;
  
  result = stat("./calibration.bin", &buf);
  
  if (result != 0)
  
  {
  
  printf("error: Failed ^_^ n");
  
  }
  
  else
  
  {
  
  printf(" size of the file in bytes: %d !n",buf.st_size);
  
  }
  
  block_image = (char *)malloc(buf.st_size);
  
  if(block_image == NULL)
  
  {
  
  printf("@@@@@@@@@@@@Malloc block image failn");
  
  return -1;
  
  }
  
  p = fopen("./calibration.bin", "rb");
  
  fread(block_image, sizeof (char), buf.st_size, p);
  
  fclose(p);
  
  tofInitParams.mCaliParams.caliImage = block_image;
  
  tofInitParams.mCaliParams.caliImageSZ = (buf.st_size);
  
  tofInitParams.mCaliParams.CaliParams.calibartion = NULL;
  
  tofInitParams.mCaliParams.temperatureParams.sensor = 36;
  
  tofInitParams.mCaliParams.temperatureParams.illumination = 38;
  
  }
  
  tofInitParams.PclNeed = true;
  
  }
  
  tofInitParams.GetConfigID = _tof_GetConfigID;
  
  tofInitParams.SetConfigID = _tof_SetConfigID;
  
  pDectectdParams.SensorRestart = _tof_sensor_restart;
  
  MI_Tof_Init(MI_TOF_DEFAULT_CH, &tofInitParams);
  
  MI_Tof_EnableInterferenceDeteced(gSnrPad, &pDectectdParams);
  

2.2. MI_Tof_UnInit

• 功能

  反初始化TOF Channel，会释放相关的Thread、Frame buffer

• 语法

  MI_S32 MI_Tof_UnInit(MI_U8 channel);
  

• 形参

  参数名称	描述	输入/输出
  Channel	需要反初始化的TOF Channel，和Init相对应	输入

• 返回值

  • E_SUCCESS or 0 成功反初始化TOF Channel

  • -1 反初始化失败

• 依赖

  • 头文件:PacketModule.h、mid_sys.h、mi_sys_datatype.h、tof_algorithm.h、TofChannelFrame.h

2.3. MI_Tof_RegisterCallBack

• 功能

  注册TOF Channel的Mod函数回调

• 语法

  MI_S32 MI_Tof_RegisterCallBack(MI_U8 channel,
  
  MI_U32 Mod,
  
  MI_S32 (*Callback)(void* inputData, void* outputData, void* config));
  

• 形参

  参数名称	描述	输入/输出
  Channel	通道Channel ID	输入
  Mod	mi_tof_mod定义的中三种枚举	输入
  Callback	每个Mod注册函数回调	输入

• 返回值

  • E_SUCCESS or 0 注册回调函数成功

  • -1 注册失败

• 依赖

  • 头文件:PacketModule.h、mid_sys.h、mi_sys_datatype.h、tof_algorithm.h、TofChannelFrame.h

2.4. MI_Tof_UnRegisterCallBack

• 功能

  反注册TOF Channel的Mod函数回调

• 语法

  MI_S32 MI_Tof_UnRegisterCallBack(MI_U8 channel,
  
  MI_U32 Mod);
  

• 形参

  参数名称	描述	输入/输出
  Channel	通道Channel ID	输入
  Mod	mi_tof_mod定义的中三种枚举	输入

• 返回值

  • E_SUCCESS or 0 反注册回调函数成功。

  • -1 反注册失败

• 依赖

  • 头文件:PacketModule.h、mid_sys.h、mi_sys_datatype.h、tof_algorithm.h、TofChannelFrame.h

2.5. MI_Tof_PutRawIntoAlgo

• 功能

  送入一个完整原始TOF Frame到对应TOF Channel

• 语法

  MI_S32 MI_Tof_PutRawIntoAlgo(MI_U8 channel, char* pbuffer, MI_U32 size, MI_U64 nPts_in);
  

• 形参

  参数名称	描述	输入/输出
  Channel	通道Channel ID	输入
  pbuffer	完整TOF原始Frame数据Buffer	输入
  size	Buffer大小	输入
  nPts_in	Raw 数据的pts	输入

• 返回值

  • E_SUCCESS or 0 送入frame buffer成功。

  • -1 送入失败，可能是channel没有创建有关系，还是送入大小和TOF计算原始数据大小不一致

• 依赖

  • 头文件:PacketModule.h、mid_sys.h、mi_sys_datatype.h、tof_algorithm.h、TofChannelFrame.h

• 举例

  char* pOneFullFrame = (char*)malloc(totalsz);
  
  memset(pOneFullFrame, 0, totalsz);
  
  while (mPthread_Run_Status)
  
  {
  
  //1.get vif date
  
  if (MI_SUCCESS == GetVifRawData(VifRaw))
  
  {
  
  if (TofHwParams.dualFreq == 1)
  
  {
  
  if (_waitTofDualFreqOneFrameReady((char*)VifRaw.stBufInfo.stFrameData.pVirAddr[0], pOneFullFrame, &TofHwParams))
  
  {
  
  **MI_Tof_PutRawIntoAlgo**(MI_TOF_DEFAULT_CH, pOneFullFrame, totalsz, VifRaw.stBufInfo.u64Pts);
  
  }
  
  }
  
  else
  
  {
  
  //2.to algo
  
  **MI_Tof_PutRawIntoAlgo**(MI_TOF_DEFAULT_CH, (char*)VifRaw.stBufInfo.stFrameData.pVirAddr[0], VifRaw.stBufInfo.stFrameData.u32BufSize, VifRaw.stBufInfo.u64Pts);
  
  }
  
  ReleaseOneRaw(VifRaw.hHandle);
  
  }
  
  }
  

2.6. MI_Tof_GetTofResult

• 功能

  获取INZI(亮度&深度)帧。

• 语法

  MI_S32 MI_Tof_GetTofResult(MI_U8 channel,
  
  mi_tof_INZI_data &depth);
  

• 形参

  参数名称	描述	输入/输出
  Channel	通道Channel ID	输入
  depth	INZI 亮度/深度数据	输出

• 返回值

  • E_SUCCESS or 0 获取INZI Frame成功。

  • -1 获取失败，可能当前frame buffer中已经空或者channel创建

• 依赖

  • 头文件:PacketModule.h、mid_sys.h、mi_sys_datatype.h、tof_algorithm.h、TofChannelFrame.h

• 注意

  拿INZI数据的方法有二,请注意，目前新版本的SDK只保留方法2

  • 法1：MI_Tof_GetTofResult/MI_Tof_ReleaseTofResult；

  • 法2：MI_Tof_RegisterDepthCallBack/MI_Tof_UnRegisterDepthCallBack；

2.7. MI_Tof_ReleaseTofResult

• 功能

  释放INZI(亮度&深)Frame

• 语法

  MI_S32 MI_Tof_ReleaseTofResult(MI_U8 channel, mi_tof_INZI_data &depth);
  

• 形参

  参数名称	描述	输入/输出
  Channel	通道Channel ID	输入
  depth	INZI 亮度/深度数据	输入

• 返回值

  • E_SUCCESS or 0 释放INZI Frame成功。

  • -1 释放失败.

• 依赖

  • 头文件:PacketModule.h、mid_sys.h、mi_sys_datatype.h、tof_algorithm.h、TofChannelFrame.h

• 举例

  mi_tof_INZI_data depth;
  
  while (mPthread_Run_Status)
  
  {
  
  //3.get
  
  if (E_SUCCESS == **MI_Tof_GetTofResult**(MI_TOF_DEFAULT_CH, depth))
  
  {
  
  //send to disp
  
  {
  
  //to do…
  
  }
  
  MI_Tof_ReleaseTofResult(MI_TOF_DEFAULT_CH, depth);
  
  }
  
  }
  

2.8. MI_Tof_SetFilter

• 功能

  动态开关tof 演算法iir/denoise filter/flying pixel filter/dealise flying pixel fiter。

• 语法

  MI_S32 MI_Tof_SetFilter(MI_U8 channel, mi_tof_filter type, void* param);
  

• 形参

  参数名称	描述	输入/输出
  Channel	通道Channel ID	输入
  type	mi_tof_filter 定义的不同的filter 类型	输入
  params	根据不同的filter 类型，分别传入不同的数据结构定义，MI_TOF_FILTER_IIR 对应 MiTofFilterIirParam_t，MI_TOF_FILTER_DENOISE 对应 MiTofFilterDenoiseParam_t，MI_TOF_FILTER_FLYING_PIXEL 对应 MiTofFilterFlyPixelParam_t，MI_TOF_FILTER_DEALIASE_FLYPIXEL 对应MiTofDealiaseFlyPixelParams_t	输入

• 返回值

  • E_SUCCESS or 0成功。

  • -1 失败

• 依赖

  • 头文件:PacketModule.h、mid_sys.h、mi_sys_datatype.h、tof_algorithm.h、TofChannelFrame.h

• 举例

  //case1：打开iir filter
  
  MiTofFilterIirParam_t iirParams;
  
  iirParams.enable = (cus_param->filterParam.iir.enable==0)?false:true;
  
  iirParams.gain = cus_param->filterParam.iir.gain;
  
  MI_Tof_SetFilter(channel, MI_TOF_FILTER_IIR, (void*)&iirParams);
  
  //case2：打开denoise filter
  
  MiTofFilterDenoiseParam_t denoiseParams;
  
  denoiseParams.enable = (cus_param->filterParam.denoise.enable==0)?false:true;
  
  denoiseParams.lpf_th = cus_param->filterParam.denoise.lpf_th;
  
  denoiseParams.flypix_threshold = cus_param->filterParam.denoise.flypix_threshold;
  
  MI_Tof_SetFilter(channel, MI_TOF_FILTER_DENOISE, (void*)&denoiseParams);
  

2.9. MI_Tof_GetFilter

• 功能

  获取tof 演算法iir/denoise filter/flying pixel filter/dealise flying pixel fiter的状态

• 语法

  MI_S32 MI_Tof_GetFilter(MI_U8 channel, mi_tof_filter type, void* param);
  

• 形参

  参数名称	描述	输入/输出
  Channel	通道Channel ID	输入
  type	mi_tof_filter 定义的不同的filter 类型	输入
  params	根据不同的filter 类型，分别传入不同的数据结构定义，MI_TOF_FILTER_IIR 对应 MiTofFilterIirParam_t，MI_TOF_FILTER_DENOISE 对应 MiTofFilterDenoiseParam_t，MI_TOF_FILTER_FLYING_PIXEL 对应 MiTofFilterFlyPixelParam_t，MI_TOF_FILTER_DEALIASE_FLYPIXEL 对应MiTofDealiaseFlyPixelParams_t	输入

• 返回值

  • E_SUCCESS or 0成功。

  • -1 失败

2.10. MI_Tof_SetAutoExposure

• 功能

  动态开关auto exposure

• 语法

  MI_S32 MI_Tof_SetAutoExposure(MI_U8 channel, bool enable);
  

• 形参

  参数名称	描述	输入/输出
  Channel	通道Channel ID	输入
  enable	1：开AE 0:关AE	输入

• 返回值

  • E_SUCCESS or 0成功。

  • -1 失败

2.11. MI_Tof_GetAutoExposure

• 功能

  动态开关auto exposure

• 语法

  MI_S32 MI_Tof_GetAutoExposure(MI_U8 channel, bool *enable);
  

• 形参

  参数名称	描述	输入/输出
  Channel	通道Channel ID	输入
  enable	1：开AE 0:关AE	输出

• 返回值

  • E_SUCCESS or 0成功。

  • -1 失败

2.12. MI_Tof_SetDebugParams

• 功能

  设置演算法debug参数

• 语法

  MI_S32 MI_Tof_SetDebugParams(MI_U8 channel, int* pDebugParams);
  

• 形参

  参数名称	描述	输入/输出
  Channel	通道Channel ID	输入
  pDebugParams	pDebugParams[0]：设置debug level：0 – 关闭log打印1 – 演算法用golden raw data2 – 设置演算法debug level 为INFO4 – 设置演算法debug level为ERRORpDebugParams[1][2]:代表save data功能的画面某点坐标(x,y)。当为(-1,-1)时代表全画面；当为（-1，x）时（x>0），代表x列；当为（x，-1）时（x>0），代表x行；当为（x>0，y>0），代表某点；pDebugParams[3]:代表save data的frame numberpDebugParams[4]：代表save data哪个stage的data，BIT[1] == 1时,表示save RAW data；BIT[6] == 1时,表示dump depth data（binary）；BIT[7] == 1时,表示dump PCL（txt）；举例：save pcl data：tofdebug 0 -1 -1 1 192	输入

• 返回值

  • E_SUCCESS or 0 获取INZI Frame成功。

  • -1 获取失败，可能当前frame buffer中已经空或者channel创建

2.13. MI_Tof_SetAmplitudeFrameType

• 功能

  动态控制amplitude使用high/low gain data计算。默认使用low gain。

• 语法

  MI_S32 MI_Tof_ SetAmplitudeFrameType(MI_U8 channel, mi_tof_hdr_frame_type params);
  

• 形参

  参数名称	描述	输入/输出
  Channel	通道Channel ID	输入
  params	Hdr frame type。参考mi_tof_hdr_frame_type	输入

• 返回值

  • E_SUCCESS or 0成功。

  • -1 失败

2.14. MI_Tof_SetCalibrationType

• 功能

  动态开启/关闭calibration type。默认calibration type均开启。Debug接口。

• 语法

  MI_S32 MI_Tof_SetCalibrationType(MI_U8 channel, uint32_t calib_type);
  

• 形参

  参数名称	描述	输入/输出
  Channel	通道Channel ID	输入
  calib_type	0:代表不做phase calibration。BIT[1]=1: 代表做wiggling calibration；BIT[2]=1: 代表做FPPN calibration；BIT[3]=1: 代表做temperature calibration；	输入

• 返回值

  • E_SUCCESS or 0成功。

  • -1 失败

• 举例

  //case1 开启wiggling、fppn、温度校正
  
  MI_SNR_PAD_ID_e eSnrPad = gSnrPad;
  
  MI_U32 calib_type = 7;
  
  MI_Tof_SetCalibrationType(eSnrPad, calib_type);
  
  //在case1基础上开启DLL 校正
  
  MI_SNR_PAD_ID_e eSnrPad = gSnrPad;
  
  MI_U32 calib_type = 7 | (1<<4); //1<<4: 表示Dll校正
  
  MI_Tof_SetCalibrationType(eSnrPad, calib_type);
  

2.15. MI_Tof_SetDebugLevel

• 功能

  设置MI_TOF debug level。Debug接口。

• 语法

  MI_S32 MI_Tof_SetDebugLevel(TofDebugLevel level,MI_U32 flag);
  

• 形参

  参数名称	描述	输入/输出
  TofDebugLevel	Debug level。typedef enum	输入
  Flag	设置演算法线程消耗的时间打印开关。0:代表不打印。BIT[0]=1: 代表打印计算phase和amplitude的时间；BIT[1]=1: 代表打印calibration的时间；BIT[2]=1: 代表打印filter、depth、点云的时间；	输入

• 返回值

  • E_SUCCESS or 0成功。

  • -1 失败

2.16. MI_Tof_RegisterDepthCallBack

• 功能

  注册“Get TOF depth”的callback。

• 语法

  MI_S32 MI_Tof_RegisterDepthCallBack(MI_U8 channel, MI_S32 (*Callback)(MI_U8 channel, mi_tof_INZI_data &depth));
  

• 形参

  参数名称	描述	输入/输出
  channel	通道Channel ID	输入
  Depth	INZI 亮度/深度数据的注册函数回调	输入

• 返回值

  • E_SUCCESS or 0成功。

  • -1 失败

• 依赖

  • 头文件:PacketModule.h、mid_sys.h、mi_sys_datatype.h、tof_algorithm.h、TofChannelFrame.h

• 注意

  拿INZI数据的方法有二：

  • 法1：MI_Tof_GetTofResult/MI_Tof_ReleaseTofResult；

  • 法2：MI_Tof_RegisterDepthCallBack/MI_Tof_UnRegisterDepthCallBack；

2.17. MI_Tof_UnRegisterDepthCallBack

• 功能

  注销“Get TOF depth”的callback。

• 语法

  MI_S32 MI_Tof_UnRegisterDepthCallBack(MI_U8 channel);
  

• 形参

  参数名称	描述	输入/输出
  channel	通道Channel ID	输入

• 返回值

  • E_SUCCESS or 0成功。

  • -1 失败

• 注意

  拿INZI数据的方法有二，目前新的sdk 主要支持方法2.

  • 法1：MI_Tof_GetTofResult/MI_Tof_ReleaseTofResult；

  • 法2：MI_Tof_RegisterDepthCallBack/MI_Tof_UnRegisterDepthCallBack；

2.18. MI_Tof_ParseEmbedInfo

• 功能

  Get the information from the embed line.

• 语法

  MI_S32 MI_Tof_ParseEmbedInfo(MI_U8 channel, char* embed, MiTofEmbedInfo* info);
  

• 形参

  参数名称	描述	输入/输出
  Channel	通道Channel ID	输入
  embed	包尾buffer首地址	输入
  info	包尾信息，比如frame number, quad number,etc.	输出

• 返回值

  • E_SUCCESS or 0成功。

  • -1 失败

• 依赖

  • 头文件:mi_parse_embed.h

2.19. MI_Tof_EnableInterferenceDeteced

• 功能

  开启“多机对射时的干扰排除”功能。

• 语法

  MI_S32 MI_Tof_EnableInterferenceDeteced(MI_U8 channel, MiTofInterferenceDetecedParams_t* pDectectdParams);
  

• 形参

  参数名称	描述	输入/输出
  Channel	通道Channel ID	输入
  pDectectdParams	输入Detect参数，参考struct MiTofInterferenceDetecedParams_t.	输入

• 返回值

  • E_SUCCESS or 0成功。

  • -1 失败

• 依赖

  • 头文件:mid_sys.h、mi_sys_datatype.h、tof_algorithm.h

2.20. MI_Tof_DisableInterferenceDeteced

• 功能

  关闭“多机对射时的干扰排除”功能。

• 语法

  MI_S32 MI_Tof_DisableInterferenceDeteced(MI_U8 channel);
  

• 形参

  参数名称	描述	输入/输出
  Channel	通道Channel ID	输入

• 返回值

  • E_SUCCESS or 0成功。

  • -1 失败

• 依赖

  • 头文件:tof_algorithm.h

2.21. MI_Tof_SetFlip

• 功能

  设定不同的flip类型。

• 语法

  MI_S32 MI_Tof_SetFlip(MI_U8 channel, mi_tof_flip_type type);
  

• 形参

  参数名称	描述	输入/输出
  Channel	通道Channel ID	输入
  Type	Flip type	输入

• 返回值

  • E_SUCCESS or 0成功。

  • -1 失败

2.22. MI_Tof_SetIrThreshold

• 功能

  设定amplitude threshold，小于该值的pixel，深度输出为0。

• 语法

  MI_S32 MI_Tof_SetIrThreshold(MI_U8 channel, MI_U32 value);
  

• 形参

  参数名称	描述	输入/输出
  Channel	通道Channel ID	输入
  value	亮度值 （0到4095）	输入

• 返回值

  • E_SUCCESS or 0成功。

  • -1 失败

2.23. MI_Tof_SetAeParam

• 功能

  设定AE 参数。

• 语法

  MI_S32 MI_Tof_SetAeParam(MI_U8 channel, MiTofAeSdrParam_t* sdr, MiTofAeHdrParam_t* hdr);
  

• 形参

  参数名称	描述	输入/输出
  Channel	通道Channel ID	输入
  sdr	sdr的AE 参数配置	输入
  hdr	hdr的AE 参数配置	输入

• 返回值

  • E_SUCCESS or 0成功。

  • -1 失败

2.24. MI_Tof_GetAeParam

• 功能

  获取AE 参数。

• 语法

  MI_S32 MI_Tof_GetAeParam(MI_U8 channel, MiTofAeSdrParam_t* sdr, MiTofAeHdrParam_t* hdr);
  

• 形参

  参数名称	描述	输入/输出
  Channel	通道Channel ID	输入
  sdr	sdr的AE 参数配置	输出
  hdr	hdr的AE 参数配置	输出

• 返回值

  • E_SUCCESS or 0成功。

  • -1 失败

2.25. MI_Tof_SetRotation

• 功能

  设定Rotation类型。

• 语法

  MI_S32 MI_Tof_SetRotation(MI_U8 channel, mi_tof_rotation_type type);
  

• 形参

  参数名称	描述	输入/输出
  Channel	通道Channel ID	输入
  Type	旋转类型	输入

• 返回值

  • E_SUCCESS or 0成功。

  • -1 失败

3. 应用case API使用流程

3.1 方法一

    MiTofParams_t tofInitParams;

    MiTofSensorHwParams_t TofHwParams;

    //1.set tofInitParams

    MI_Tof_Init(MI_TOF_DEFAULT_CH, &tofInitParams);

    while (1)

    {

    //2.Get vif raw data

    //3.put raw to MI Tof algo

    MI_Tof_PutRawIntoAlgo(MI_TOF_DEFAULT_CH, rawbuf, rawsize);

    //4.get depth data

    if (E_SUCCESS == MI_Tof_GetTofResult(MI_TOF_DEFAULT_CH, depth))

    {

    //5.depth data to do next

    //6.release depth buf

    MI_Tof_ReleaseTofResult(MI_TOF_DEFAULT_CH, depth);

    }

    }

3.2 方法二

    MI_S32 Tof_GetDepth_Callback(MI_U8 channel, mi_tof_INZI_data &depth)

    {

    ……

    }

    int main(int argc, char **argv)

    {

    MiTofParams_t tofInitParams;

    MiTofSensorHwParams_t TofHwParams;

    //1.set tofInitParams

    MI_Tof_Init(MI_TOF_DEFAULT_CH, &tofInitParams);

    //use callback to get depth result

    MI_Tof_RegisterDepthCallBack(MI_TOF_DEFAULT_CH, Tof_GetDepth_Callback);

    ……

    MI_Tof_UnRegisterDepthCallBack(MI_TOF_DEFAULT_CH);

    }

• 说明：

  1.上诉过程为MI Tof算法最基本的使用流程，具体细节实现可以参考mixer或者tof demo

  2.第3步put raw数据到算法和第4步get depth数据可以放在不同的线程中进行，这样可以同时对多个raw数据进行算法处理，提高效率

4. TOF数据类型

数据类型定义

	数据类型	定义
1	mi_tof_mod	定义TOF计算步骤(Calc/Cali/Filter)
2	mi_tof_INZI_data	定义TOF计算后Frame类型
3	MiTofSensorHwParams_t	定义Sensor HW描述，从Sensor Driver获取到转化而来
4	MiTofCaliParams_t	定义Calibratition参数
5	MiTofFilterParams_t	定义Filter参数
6	MiTofAEParams_t	定义AE自动曝光参数和函数回调
7	MiTofParams_t	定义TOF Channel初始化参数
8	mi_tof_filter	定义filter类型
9	tof_pixel_size	定义sensor 输出的RAW data里每个data单元的size,单位bit
10	tof_raw_format	定义sensor 输出的Raw data format
11	tof_sensor_hdr_type	定义HDR type
12	tof_iir_params	定义iir filter 结构体
13	tof_denoise_params	定义denoise filter结构体
14	tof_ae_sdr_params	定义sdr下auto exposure 参数
15	tof_ae_hdr_params	定义hdr下auto exposure 参数
16	mi_tof_hdr_frame_type	定义使用high gain还是low gain来计算amplitude的方式
17	MiTofEmbedInfo	定义对外公开的包尾信息
18	MiTofInterferenceDetecedParams_t	定义开启“多机对射时的干扰排除”功能所需要的参数
19	MiTofDllFilterParams_t	定义Dll calibration software config params.
20	MiTofDllFitlerCode_t	定义Dll calibration software config callback params.
21	MiTofDealiaseFlyPixelParams_t	定义双频下开flying pixel filter需要的参数。

4.1. mi_tof_mod

• 说明

  定义 TOF计算阶段

• 定义

  typedef enum
  
  {
  
  MI_TOF_CALC = 0,
  
  MI_TOF_CALI,
  
  MI_TOF_FILTER,
  
  TOF_MOD_MAX,
  
  }mi_tof_mod;
  

• 成员

  成员	描述
  MI_TOF_CALC	Phase计算
  MI_TOF_CALI	Phase校正
  MI_TOF_FILTER	对phase进行filter调优

4.2. mi_tof_INZI_data

• 说明

  定义TOF计算后Frame类型，参考2.8.1. V4L2_PIX_FMT_INZI (‘INZI’) — The Linux Kernel documentation

• 定义

  #pragma pack (4)
  
  typedef struct
  
  {
  
  MI_U64 pts;
  
  MI_U32 frameNum;
  
  MI_U16* ir; // 1 uint16_t per IR pixel
  
  float* depth; // 1 float per depth pixel
  
  float* pcl; // 3 float per depth pixel
  
  MI_U16* depthInt; // 1 int per depth pixel
  
  MI_S16* pclInt; // 3 int per depth pixel
  
  MI_U16 width;
  
  MI_U16 height;
  
  MI_U8* frameHeader;// 1Line Byte with frame info:depth_frame_header_info
  
  }mi_tof_INZI_data;
  
  #pragma pack ()
  

• 成员

  成员	描述
  pts	当前frame时间戳
  frameNum	当前frame 序列（保留）
  Ir	亮度幅度值（0~4096）
  depth	浮点型深度Z轴距离
  pcl	浮点型点云数据
  depthInt	整型深度Z轴距离
  pclInt	整型点云数据
  width	分辨率宽度
  height	分辨率高度
  frameHeader	pointer to one buffer with intergration-time and temperature, the buffer size is “width” Bytes

• 注意

  浮点型和整型depth/pcl数据，不能够同时获取到，默认获取浮点型。

  MI_Tof_Init使能参数DepthIntNeed可以获取整型数据。

4.3. MiTofSensorHwParams_t

• 说明

  Sensor HW描述或者HW参数

• 定义

  typedef struct _MiTofRawBufInfo_t
  
  {
  
  uint16_t width;
  
  uint16_t height;
  
  tof_pixel_size pixel_size;
  
  tof_raw_format raw_format;
  
  tof_sensor_hdr_type hdr_type;
  
  bool dualFreq;
  
  uint16_t chip_id;
  
  uint8_t one_quad_one_footer;
  
  uint32_t mod_freq1;
  
  uint32_t mod_freq2;
  
  uint8_t ir_type;
  
  uint8_t vcsel_type;
  
  }MiTofSensorHwParams_t;
  

• 成员

  成员	描述
  width	Sensor分辨率宽度
  height	Sensor分辨率高度
  pixel_size	像素占用bit数。
  raw_format	Sensor输出的raw data格式。0：A+B1: A-B
  hdr_type	HDR类型：0：表示Normal mode。1：Pixel HDR mode。2：Time HDR mode
  dualFreq	是否支持双频，支持双频测试距离会更远
  chip_id	CHIP ID
  one_quad_one_footer	脚本是否是1quad 带1个包尾
  mod_freq1	高频频率
  mod_freq2	低频频率
  ir_type	ir 类型
  vcsel_type	vcsel的类型， 目前支持3011与JM2519

• 注意

  这些请通过Sensor User API

  MI_SNR_CustFunction(E_MI_SNR_PAD_ID_1, CMDID_GET_DEVICE_INFO, sizeof(tofCamerInfo), &tofCamerInfo, E_MI_SNR_CUSTDATA_TO_USER)获取

4.4. MiTofCaliParams_t

• 说明

  TOF Calibratition参数

• 定义

  typedef struct _MiTofCaliParams
  
  {
  
  char* caliImage;
  
  MI_U32 caliImageSZ;
  
  }MiTofCaliParams_t;
  

• 成员

  成员	描述
  caliImage	Calibration Image buffer地址
  caliImageSZ	Calibration Image size

• 注意

  caliImage可以不需要释放，MI_Tof_Uninit会释放

4.5. MiTofFilterParams_t

• 说明

  filter参数

• 定义

  typedef struct _MiTofFilterParams
  
  {
  
  MiTofFilterIirParam_t iirParams;
  
  MiTofFilterDenoiseParam_t denoiseParams;
  
  MiTofFilterFlyPixelParam_t flyPixelParams;
  
  MiTofDealiaseFlyPixelParams_t dealiaseFlyPixelParams;
  
  }MiTofFilterParams_t;
  

• 成员

  成员	描述
  iirParams	IIR Filter参数。
  denoiseParams	Denoise filter参数。
  dealiaseFlyPixelParams	双频下flying pixel filter参数，参考MiTofDealiaseFlyPixelParams_t.
  flyPixelParams	Fly pixel filter 参数

4.6. MiTofAEParams_t

• 说明

  自动曝光参数

• 定义

  typedef struct _MiTofAEParams
  
  {
  
  tof_ae_sdr_params sdrParams;
  
  tof_ae_hdr_params hdrParams;
  
  MI_S32 (*GetAETimeNs)(MI_U8 channel, MiTofIntergrationTime_t* stInttime);
  
  MI_S32 (*SetAETimeNs)(MI_U8 channel, MiTofIntergrationTime_t* stInttime);
  
  bool AutoExposure;
  
  }MiTofAEParams_t;
  

• 成员

  成员	描述
  sdrParams	SDR曝光策略参数。
  hdrParams	HDR曝光策略参数。
  GetAETimeNs	获取当前Sensor曝光时间函数回调
  SetAETimeNs	设置Sensor曝光时间函数回调
  AutoExposure	使能自动曝光

4.7. MiTofParams_t

• 说明

  TOF Channel初始化参数

• 定义

  typedef struct _MiTofParams
  
  {
  
  MiTofSensorHwParams_t SensorHwParams;
  
  MiTofCaliParams_t mCaliParams;
  
  MiTofAEParams_t AEParams;
  
  MiTofFilterParams_t FilterParams;
  
  bool PclNeed;
  
  bool DepthIntNeed;
  
  mi_tof_hdr_frame_type AmplitudeType;
  
  MI_S32 (*GetConfigID)(MI_U8 channel,uint16_t* config_id_value);
  
  MI_S32 (*SetConfigID)(MI_U8 channel, uint16_t config_id_value);
  
  uint16_t amplitude_threshold;
  
  MiTofDllFilterParams_t mDllFilterParams;
  
  uint8_t amplitude_gain; //gamma curve 10==linear,setting range value 1-30,default 6, 0 = no fusion
  
  uint8_t amplitudeU8Need; //0: amplitude value u16; 1 : amplitude value u8
  
  }MiTofParams_t;
  

• 成员

  成员	描述
  SensorHwParams	Sensor 硬件配置参数
  mCaliParams	校正计算参数
  AEParams	自动曝光参数
  FilterParams	Filter参数
  PclNeed	使能点云算法
  DepthIntNeed	使能获取int depth
  AmplitudeType	配置amplitude type。会在此阶段分配好对外提供的amplitude的buffer大小。
  GetConfigID	从sensor drv get config ID,一般与SetConfigID一起，用来check frame是否有更新
  SetConfigID	与上类同
  amplitude_threshold	设置amplitude threshold.小于这个threshold的pixel为无效pixel.
  mDllFilterParams	设置Dll calibration filter 参数，比如gain, 设置越小，phase越平稳；设置越大，当前帧的dll code权重越大，当测量phase发生巨变时，追踪的速度越大。详请看4.19.
  amplitude_gain	ir图输出效果控制参数：gamma curve 10==linear,setting range value 1-30,default 6, 0 = no fusion
  amplitudeU8Need	控制IR是否U8 输出， 默认是U16

4.8. mi_tof_filter

• 说明

  定义 TOF filter 类型

• 定义

  typedef enum
  
  {
  
  MI_TOF_FILTER_NONE = 0,
  
  MI_TOF_FILTER_IIR = 1 << 0,
  
  MI_TOF_FILTER_DENOISE = 1 << 1,
  
  MI_TOF_FILTER_FLYING_PIXEL = 1 << 2,
  
  MI_TOF_FILTER_DEALIASE_FLYPIXEL = 1 << 3,
  
  }mi_tof_filter;
  

• 成员

  成员	描述
  MI_TOF_FILTER_NONE	没有tof filter
  MI_TOF_FILTER_IIR	Tof iir filter.
  MI_TOF_FILTER_DENOISE	Tof denoise filter(mode = 1),与“ MI_TOF_FILTER_FLYING_PIXEL”只是mode的区别，只能选其一。
  MI_TOF_FILTER_FLYING_PIXEL	Flying pixel filter(mode = 2).
  MI_TOF_FILTER_DEALIASE_FLYPIXEL	双频下可以开flying pixel filter

4.9. tof_pixel_size

• 说明

  定义sensor 输出的RAW data里每个data单元 size,单位bit.

• 定义

  typedef enum
  
  {
  
  TOF_PIXEL_SIZE_RAW12 = 12,
  
  TOF_PIXEL_SIZE_RAW16 = 16,
  
  TOF_PIXEL_SIZE_MAX = 0xFFFF,
  
  }tof_pixel_size;
  

• 成员

  成员	描述
  TOF_PIXEL_SIZE_RAW12	每个data 12bit。如果Raw data format是下面几种，1个pixel是1个data，那么1个pixel是12bit：TOF_RAW_FORMAT_A_PLUS_BTOF_RAW_FORMAT_A_MINUS_B
  TOF_PIXEL_SIZE_RAW16	每个data 16bit。如果Raw data format是下面几种，1个pixel是1个data，那么1个pixel是16bit：TOF_RAW_FORMAT_A_PLUS_BTOF_RAW_FORMAT_A_MINUS_B

4.10. tof_raw_format

• 说明

  定义sensor 输出的Raw data format

• 定义

  typedef enum
  
  {
  
  TOF_RAW_FORMAT_A_PLUS_B,
  
  TOF_RAW_FORMAT_A_MINUS_B,
  
  TOF_RAW_FORMAT_NUM,
  
  }tof_raw_format;
  

• 成员

  成员	描述
  TOF_RAW_FORMAT_A_PLUS_B	简称A+B mode。sensor只输出(A+B） DATA。
  TOF_RAW_FORMAT_A_MINUS_B	简称A-B mode。sensor只输出(A-B） DATA

4.11. tof_sensor_hdr_type

• 说明

  定义HDR type

• 定义

  typedef enum
  
  {
  
  TOF_SENSOR_HDR_NONE,
  
  TOF_SENSOR_HDR_PIXEL,
  
  TOF_SENSOR_HDR_TIME,
  
  TOF_SENSOR_HDR_NUM,
  
  }tof_sensor_hdr_type;
  

• 成员

  成员	描述
  TOF_SENSOR_HDR_NONE	Normal mode。表不开启HDR case.
  TOF_SENSOR_HDR_PIXEL	HDR mode。表pixel HDR case.
  TOF_SENSOR_HDR_TIME	TIME HDR mode

4.12. MiTofFilterIirParam_t

• 说明

  IR filter的相关参数

• 定义

  typedef struct
  
  {
  
  bool enable;
  
  uint8_t gain;
  
  }MiTofFilterIirParam_t;
  

• 成员

  成员	描述
  gain	用来调整IIR filter 的强度 [0~128] 值越大，参考前一帧越多，效果越明显0: off128: max level (default)

• 注意

  Default gain是128，如果信号很好，temporal noise很小，可以减少gain value。

4.13. MiTofFilterDenoiseParam_t;

• 说明

  Denoise filter的相关定义

• 定义

  typedef struct
  
  {
  
  bool enable;
  
  uint16_t lpf_th;
  
  uint16_t flypix_threshold;
  
  }MiTofFilterDenoiseParam_t;
  

• 成员

  成员	描述
  enable	是否使能
  lpf_th	调整范围（0~640）越大就会有越多的Pixel执行该filter滤波；Default :58*freq_ratio 比如100M*80M 290
  flypix_threshold	调整范围（0~8192）越小越容易去做flying pixel correction；Default :1380*freq_ratio 比如100M*80M 6900

• 注意

  gcd = CAL_GCD(mod1_freq, mod2_freq);

  freq_ratio = max(mod1_freq, mod2_freq)/gcd;

4.14. MiTofFilterFlyPixelParam_t

• 说明

  FlyPixelFliter的相关参数定义

• 定义

  typedef struct
  
  {
  
  bool enable;
  
  uint16_t lpf_th;
  
  uint16_t flypix_gradient_th;
  
  uint16_t flypix_diff_sum_th;
  
  }MiTofFilterFlyPixelParam_t;
  

• 成员

  成员	描述
  Enable	开关filter
  lpf_th	调整范围（0~1024）越大就会有越多的Pixel执行该filter滤波；Default :128*freq_ratio 比如100M*80M 40
  flypix_gradient_th	调整范围（0~4096）越小越多的点会被当成flying pixel并被处理为无效点Default :680*freq_ratio 比如100M*80M 3400
  flypix_diff_sum_th	调整范围（0~8192）越小越多的点会被当成flying pixel并被处理为无效点Default :1024*freq_ratio 比如100M*80M 5120

• 注意

  gcd = CAL_GCD(mod1_freq, mod2_freq);

  freq_ratio = max(mod1_freq, mod2_freq)/gcd;

4.15. MiTofDealiaseFlyPixelParams_t

• 说明

  Dealiase Flypixel filter 参数

• 定义

  typedef struct
  
  {
  
  bool enable;
  
  MI_U32 low_threshold;
  
  MI_U32 high_threshold;
  
  }MiTofDealiaseFlyPixelParams_t;
  

• 成员

  成员	描述
  Enable	开关
  low_threshold	调整范围（0~4086）大于low_threshold的Pixel判别为flying pixel并被处理为无效值Default：800
  high_threshold	调整范围（0~4096）小于high_threshold的Pixel即判别为flying pixel并被处理为无效值Default：3200

4.16. tof_ae_sdr_params

• 说明

  SDR曝光策略参数

• 定义

  typedef struct _tof_ae_sdr_params
  
  {
  
  uint16_t black_level;
  
  uint16_t yth_low;
  
  uint16_t yth_high;
  
  uint16_t upper_cnt_limitH;
  
  uint16_t upper_cnt_limitL;
  
  uint32_t exp_limit_low;
  
  uint32_t exp_limit_high;
  
  uint32_t exp_step_slow;
  
  uint32_t exp_step_fast;
  
  }tof_ae_sdr_params;
  

• 成员

  成员	描述
  black_level	当integration time 设成0 时, sensor 统计报的平均亮度
  yth_low	调整integration time ,需要画面最小的平均亮度
  yth_high	调整integration time ,需要画面最大的平均亮度
  upper_cnt_limitH;	调整integration time ,可以接受最多的pixel counts 超过pixel upper threshold
  upper_cnt_limitL	调整integration time ,可以接受最少的pixel counts 超过pixel upper threshold
  exp_limit_low	调整integration time 的下限 [ns]
  exp_limit_high	调整integration time 的上限 [ns]
  exp_step_slow	每次调整integration time , 最短的间隔时间 [ns] (相隔两次的最小差值)
  exp_step_fast	每次调整integration time , 最长的间隔时间 [ns] (相隔两次的最大差值)

4.17. tof_ae_hdr_params

• 说明

  HDR曝光策略参数

• 定义

  typedef struct _tof_ae_hdr_params
  
  {
  
  uint16_t black_level;
  
  uint16_t yth_low;
  
  uint16_t yth_high;
  
  uint16_t upper_cnt_limitH;
  
  uint16_t upper_cnt_limitL;
  
  uint32_t exp_limit_low;
  
  uint32_t exp_limit_high;
  
  uint32_t exp_step_slow;
  
  uint32_t exp_step_fast;
  
  }tof_ae_hdr_params;
  

• 成员

  成员	描述
  black_level	当integration time 设成0 时, sensor 统计报的平均亮度
  yth_low	调整integration time ,需要画面最小的平均亮度
  yth_high	调整integration time ,需要画面最大的平均亮度
  upper_cnt_limitH;	调整integration time ,可以接受最多的pixel counts 超过pixel upper threshold
  upper_cnt_limitL	调整integration time ,可以接受最少的pixel counts 超过pixel upper threshold
  exp_limit_low	调整integration time 的下限 [ns]
  exp_limit_high	调整integration time 的上限 [ns]
  exp_step_slow	每次调整integration time , 最短的间隔时间 [ns] (相隔两次的最小差值)
  exp_step_fast	每次调整integration time , 最长的间隔时间 [ns] (相隔两次的最大差值)

4.18. mi_tof_hdr_frame_type

• 说明

  定义使用high gain还是low gain来计算amplitude的方式

• 定义

  typedef enum
  
  {
  
  MI_TOF_HDR_FRAME_HIGH_GAIN,
  
  MI_TOF_HDR_FRAME_LOW_GAIN,
  
  MI_TOF_HDR_FRAME_MIX,
  
  MI_TOF_HDR_FRAME_BOTH,
  
  MI_TOF_HDR_FRAME_NUM,
  
  } mi_tof_hdr_frame_type;
  

• 成员

  成员	描述
  MI_TOF_HDR_FRAME_HIGH_GAIN	计算amplitude用high gain数据
  MI_TOF_HDR_FRAME_LOW_GAIN	计算amplitude用low gain数据
  MI_TOF_HDR_FRAME_MIX	目前效果等效于HDR_FRAME_LOW_GAIN
  MI_TOF_HDR_FRAME_BOTH	同时提供High gain和Low gain的amplitude。如需要此种amplitude数据，请在MI_Tof_Init时就配置好。不支持跟其他type动态切换。
  MI_TOF_HDR_FRAME_NUM	-

4.19. MiTofEmbedInfo

• 说明

  定义对外公开的包尾信息

• 定义

  typedef struct
  
  {
  
  uint32_t frame_num;
  
  uint32_t sub_frame_number;
  
  uint32_t quad_num;
  
  uint32_t amp_mean;
  
  uint32_t amp_mean_hdr;
  
  uint32_t amp_upper_cnt;
  
  uint32_t amp_upper_cnt_hdr;
  
  uint32_t intergration_time;
  
  int16_t vcsel_temperature;
  
  int16_t sensor_temperature;
  
  uint16_t config_id;
  
  tof_sensor_hdr_type hdr_type;
  
  uint32_t dllCode;
  
  }MiTofEmbedInfo;
  

• 成员

  成员	描述
  frame_num	表示当前是第几帧
  sub_frame_number	表示当前的sub frame数目
  quad_num	表示当前是quad idx
  amp_mean	表示当前统计区域内high gain部分的平均亮度，AE需要的数据
  amp_mean_hdr	表示当前统计区域内low gain部分的平均亮度，AE需要的数据
  amp_upper_cnt	表示当前统计区域内high gain部分高于amp_threshhold的pixel数目，AE需要的数据
  amp_upper_cnt_hdr	表示当前统计区域内low gain部分高于amp_threshhold的pixel数目，AE需要的数据
  intergration_time	表示当前frame使用的intergration time，AE需要的数据
  vcsel_temperature	表示当前driver IC的温度
  sensor_temperature	表示当前sensor的温度
  config_id	表示当前frame的config_id,一般用于check 具有buffer 缓冲的register设置是否生效
  hdr_type	表示当前frame配置是否开启pixelhdr.
  dllCode	表示HW DLL lock的code value.

4.20. MiTofInterferenceDetecedParams_t

• 说明

  定义开启“多机对射时的干扰排除”功能所需要的参数

• 定义

  typedef struct MiTofInterferenceDetecedParams
  
  {
  
  MI_S32 (*SensorRestart)(MI_U8 channel);
  
  }MiTofInterferenceDetecedParams_t;
  

• 成员

  成员	描述
  SensorRestart	回调函数指针：关闭shutter->重新设置config_id->shutter.

4.21. MiTofDllFilterParams_t

• 说明

  定义Dll calibration software config callback params.

• 定义

  typedef struct _MiTofDllFilterCode
  
  {
  
  MI_U16 filter_code;
  
  bool selectOn;
  
  }MiTofDllFitlerCode_t;
  

• 成员

  成员	描述
  filter_code	当selectOn为1时，此值才有意义。
  selectOn	0：用HW auto Dll;1: 切换到使用“software filter的 dll code”的方法

4.22. MiTofDllFitlerCode_t

• 说明

  定义Dll calibration software config params.

• 定义

  typedef struct _MiTofDllFilterParams
  
  {
  
  uint8_t filter_gain; //zero:disable dll sw config. non-zero: 8 is good,range:1~16.
  
  MI_S32 (*SetDllClibSwConfig)(MI_U8 channel, MiTofDllFitlerCode_t* stFilter_code);
  
  }MiTofDllFilterParams_t;
  

• 成员

  成员	描述
  filter_gain	0：disable the dll calibration sw config function;Non-zero: [1~16]. Gain设置越小，phase越平稳；设置越大，当前帧的x-delay code权重越大，当测量phase发生巨变时，追踪的速度越大。
  SetDllClibSwConfig	回调函数指针：用于控制sensor Drv设置相关register.

• 注意

  请务必根据capability决定要不要开启此功能

4.23. MiTofIntergrationTime_t

• 说明

  定义积分时间

• 定义

  typedef struct _MiTofIntergrationTime
  
  {
  
  MI_U32 normal_integration_time; //ns
  
  MI_U32 hdr_integration_time; //ns
  
  void *reserved;
  
  }MiTofIntergrationTime_t;
  

• 成员

  成员	描述
  normal_integration_time	normal积分时间
  hdr_integration_time	timehdr 积分时间

4.24. mi_tof_flip_type

• 说明

  定义flip type

• 定义

  typedef enum
  
  {
  
  MI_TOF_FLIP_NONE,
  
  MI_TOF_FLIP_H,
  
  MI_TOF_FLIP_V,
  
  MI_TOF_FLIP_HV,
  
  MI_TOF_FLIP_NUM,
  
  }mi_tof_flip_type;
  

• 成员

  成员	描述
  MI_TOF_FLIP_NONE	none
  MI_TOF_FLIP_H	水平方向flip
  MI_TOF_FLIP_V	垂直方向flip
  MI_TOF_FLIP_HV	水平与垂直方向一起flip
  MI_TOF_FLIP_NUM	num

4.25. mi_tof_rotation_type

• 说明

  定义rotation type.

• 定义

  typedef enum
  
  {
  
  MI_TOF_ROTATION_0,
  
  MI_TOF_ROTATION_90,
  
  MI_TOF_ROTATION_180,
  
  MI_TOF_ROTATION_270,
  
  MI_TOF_ROTATION_NUM,
  
  }mi_tof_rotation_type;
  

• 成员

  成员	描述
  MI_TOF_ROTATION_0	不做旋转
  MI_TOF_ROTATION_90	顺时针90°旋转
  MI_TOF_ROTATION_180	顺时针180°旋转
  MI_TOF_ROTATION_270	顺时针270°旋转
  MI_TOF_ROTATION_NUM	Num