MI TOF API

REVISION HISTORY¶

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

1. Overview¶

1.1. Module Description¶

TOF (Time of Flight) calculates the distance of the target object by measuring the flight time of infrared light in the air. It is used for depth perception, 3D modeling, and gesture recognition. This article mainly introduces the MI_TOF related interfaces, which are mainly used to receive the original VIF data, perform depth calculation, correction, and filtering processing, and then output the TOF depth information.

1.2. Basic Structure¶

MI_TOF receives raw data from SENSOR->VIF, sends it to the internal algorithm processing demo calc_depth, and goes through calculate, calibration, and filter processes in sequence to output depth data.

Figure 1‑1：TOF Diagram of Data Flow

The architecture diagram based on the MI TOF is shown in the following figure:

1.TOF_DEMO：Used for processing depth data and transmitting it via UVC to the upper-level application.

2.MI VIF:Receive the data from the sensor module and send it to the TOF algorithm processing function for calculating the DEPTH data.

3.MI SENSOR:Call the underlying driver such as "drv_ms_cus_jm152a/jm152a" to obtain the raw image data

4.MI TOF/Algorithm:MI TOF api&cacl/calibration/filter algorithm

Figure 1‑2：architecture diagram

1.3. Function Introduction¶

MI TOF supports the following functions:

Input the raw MIPI data, and calculate the IR, depth, and PCL point cloud data.
Supports IIR/Denoise/FlyPixel and other filtering algorithms.
The software supports automatic exposure and allows you to configure different effects through parameter settings.
Support picture rotation and flipping.
Parse the end data of the package.

1.4. Application Scenarios¶

Mi tof is applied to tof development under Linux.

1.5. Development Process¶

Interface calls are as follows:

Figure 1‑3：API Call Flowchart

MI TOF calling process introduction:

_TOFParseCalibration:Parse calibration file calibration.bin.
_tof_dev_GetDeviceInfo:Obtain sensor configuration information.
MI_TOF_init:Tof initialization, create Algorithm thread, register algorithm callback Calc_depth.
MI_Tof_RegisterDepthCallBack:register Callback used for obtaining IR/depth/PCL;
tof_run thread:Obtain TOF RAW data and through API MI_Tof_PutRawIntoAlgo send Algorithm thread and Cacl_Depth done calculate/calibration/filter to get IR/DEPTH/PCL data.
Tof_GetDepth_Callback:Obtain deep data for the upper-level algorithms.
SDK support filter/AE etc.

1.6. Example Introduction¶

This example demonstrates the development process based on the MI_TOF API.

Data flow:

The underlying sensor collects the raw data and transmits it via MIPI to the VIF.
The uvc tof demo calls MI_Tof_PutRawIntoAlgo to transfer the VIF Raw data to the algorithm callback for calculation.
The uvc tof demo obtains data through the Tof_GetDepth_Callback function and sends it to the UVC Driver.
UVC transmits data to the PC end via v4l2.

Control flow:

The UVC driver sends the sensor control command to the uvc tof demo.
The bottom-level MI SENSOR receives and processes the cmd.
Through the set/get interfaces of the common sensor driver and the JM sensor driver, the driver is invoked.
Then, using MIPI, the cmd is converted into a register value and written/read into the sensor.

Figure 1‑4：TOF Flowchart

Note

The presented code cannot be directly compiled and run. Some processes are within callback functions and the sample code is not complete. For the complete code, please refer to:

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

MI_U32 Calc_Depth(void* inputData, void* outputData, void* config)
{
        calculate;
        calibration;
        filter;
        . . .
        pChannelParams->algoCallbackResult(channel, depth);
}

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;
}

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);
}

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 Reference¶

Functional Module API	API Name	Function
1	MI_Tof_Init	Initialize TOF Channel
2	MI_Tof_UnInit	Deinitialize TOF Channel
3	MI_Tof_RegisterCallBack	Register Mod function callback for TOF Channel
4	MI_Tof_UnRegisterCallBack	Unregister Mod function callback for TOF Channel
5	MI_Tof_PutRawIntoAlgo	Send a complete original TOF Channel Frame
6	MI_Tof_GetTofResult	Get INZI (brightness & depth) Frame
7	MI_Tof_ReleaseTofResult	Release previously obtained INZI Frame
8	MI_Tof_SetFilter	Dynamically enable/disable TOF iir/denoise filter.
9	MI_Tof_GetFilter	Get filter configuration information
10	MI_Tof_SetAutoExposure	Dynamically enable/disable TOF auto exposure.
11	MI_Tof_GetAutoExposure	Get AE switch status, configuration information, etc.
12	MI_Tof_SetDebugParams	Set TOF algorithm debug parameters
13	MI_Tof_SetAmplitudeFrameType	Dynamically control whether amplitude uses high/low gain data for calculation. Low gain is used by default.
14	MI_Tof_SetCalibrationType	Dynamically enable/disable calibration type. By default, all calibration types are enabled. Debug interface
15	MI_Tof_SetDebugLevel	Set MI_TOF debug level. Debug interface
16	MI_Tof_RegisterDepthCallBack	Register callback for "Get TOF depth".
17	MI_Tof_UnRegisterDepthCallBack	Unregister "Get TOF depth" callback.
18	MI_Tof_ParseEmbedInfo	Get information from the embed line
19	MI_Tof_EnableInterferenceDeteced	Enable "interference elimination during multi-device confrontation" function
20	MI_Tof_DisableInterferenceDeteced	Disable "interference elimination during multi-device confrontation" function
21	MI_Tof_SetFlip	Set different flip types
22	MI_Tof_SetIrThreshold	Set threshold, depth will output 0 if less than this threshold
23	MI_Tof_SetAeParam	Set AE parameters
24	MI_Tof_GetAeParam	Get AE parameters
25	MI_Tof_SetRotation	Set image rotation function

2.1. MI_Tof_Init¶

Function

Initialize TOF Channel

Syntax

MI_S32 MI_Tof_Init(MI_U8 channel, MiTofParams_t* pInitParams);

Parameters

Parameter Name	Description	Input/Output
Channel	Channel can support 0~3, maximum 4 Sensor channels by default. The upper layer needs to properly map Sensor chmap/Port and channel. MI_TOF will not bind to specific HW configuration.	Input
pInitParams	Initialization parameters, setting Sensor HW attributes, Cali/AE/Filter parameters corresponding to the channel	Input

Return Value
- E_SUCCESS: Successfully initialized TOF Channel. If reinitialized after previous success, also returns E_SUCCESS.
- -1: Initialization failed, insufficient resources or parameter error.
Dependencies
- Header files: PacketModule.h, mid_sys.h, mi_sys_datatype.h, tof_algorithm.h, TofChannelFrame.h
Note

Maximum 4 channels supported. Initialization will fail if system resources are insufficient.

Reference for AE parameter settings:

Figure 2‑1：AE Param Setting

Example

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 fail\n");
                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¶

Function

Deinitialize TOF Channel, release related Thread and Frame buffer
Syntax
```
MI_S32 MI_Tof_UnInit(MI_U8 channel);
```
Parameters

Parameter Name Description Input/Output

Channel TOF Channel to be deinitialized, corresponding to Init Input
Return Value
- E_SUCCESS or 0: Successfully deinitialized TOF Channel.
- -1: Deinitialization failed
Dependencies
- Header files: PacketModule.h, mid_sys.h, mi_sys_datatype.h, tof_algorithm.h, TofChannelFrame.h

2.3. MI_Tof_RegisterCallBack¶

Function

Register Mod function callback for TOF Channel

Syntax

MI_S32 MI_Tof_RegisterCallBack(MI_U8 channel,

MI_U32 Mod,

MI_S32 (*Callback)(void* inputData, void* outputData, void* config));

Parameters

Parameter Name Description Input/Output

Channel Channel ID Input

Mod Three enumerations defined in mi_tof_mod Input

Callback Function callback registered for each Mod Input
Return Value
- E_SUCCESS or 0: Successfully registered callback function.
- -1: Registration failed
Dependencies
- Header files: PacketModule.h, mid_sys.h, mi_sys_datatype.h, tof_algorithm.h, TofChannelFrame.h

2.4. MI_Tof_UnRegisterCallBack¶

Function

Unregister Mod function callback for TOF Channel

Syntax

MI_S32 MI_Tof_UnRegisterCallBack(MI_U8 channel, MI_U32 Mod);

Parameters

Parameter Name Description Input/Output

Channel Channel ID Input

Mod Three enumerations defined in mi_tof_mod Input
Return Value
- E_SUCCESS or 0: Successfully unregistered callback function.
- -1: Unregistration failed
Dependencies
- Header files: PacketModule.h, mid_sys.h, mi_sys_datatype.h, tof_algorithm.h, TofChannelFrame.h

2.5. MI_Tof_PutRawIntoAlgo¶

Function

Send a complete original TOF Frame to the corresponding TOF Channel

Syntax

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

Parameters

Parameter Name Description Input/Output

Channel Channel ID Input

pbuffer Complete TOF original Frame data Buffer Input

size Buffer size Input

nPts_in pts of Raw data Input
Return Value
- E_SUCCESS or 0: Successfully sent to frame buffer.
- -1: Sending failed, possibly because the channel was not created or the sent size does not match the size of TOF calculation raw data.
Dependencies
- Header files: PacketModule.h, mid_sys.h, mi_sys_datatype.h, tof_algorithm.h, TofChannelFrame.h

Example

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¶

Function

Get INZI (brightness & depth) frame.

Syntax

MI_S32 MI_Tof_GetTofResult(MI_U8 channel, mi_tof_INZI_data &depth);

Parameters

Parameter Name Description Input/Output

Channel Channel ID Input

depth INZI brightness/depth data Output
Return Value
- E_SUCCESS or 0: Successfully obtained INZI Frame.
- -1: Obtaining failed, possibly because the current frame buffer is empty or the channel was created.
Dependencies
- Header files: PacketModule.h, mid_sys.h, mi_sys_datatype.h, tof_algorithm.h, TofChannelFrame.h
Note

There are two methods to get INZI data. Note that the new version of SDK only retains method 2:
- Method 1: MI_Tof_GetTofResult/MI_Tof_ReleaseTofResult;
- Method 2: MI_Tof_RegisterDepthCallBack/MI_Tof_UnRegisterDepthCallBack;

2.7. MI_Tof_ReleaseTofResult¶

Function

Release INZI (brightness & depth) Frame

Syntax

MI_S32 MI_Tof_ReleaseTofResult(MI_U8 channel, mi_tof_INZI_data &depth);

Parameters

Parameter Name Description Input/Output

Channel Channel ID Input

depth INZI brightness/depth data Input
Return Value
- E_SUCCESS or 0: Successfully released INZI Frame.
- -1: Release failed.
Dependencies
- Header files: PacketModule.h, mid_sys.h, mi_sys_datatype.h, tof_algorithm.h, TofChannelFrame.h

Example

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¶

Function

Dynamically enable/disable tof algorithm iir/denoise filter/flying pixel filter/dealise flying pixel filter.

Syntax

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

Parameters

Parameter Name	Description	Input/Output
Channel	Channel ID	Input
type	Different filter types defined by mi_tof_filter	Input
params	Different data structure definitions are passed in according to different filter types:MI_TOF_FILTER_IIR corresponds to MiTofFilterIirParam_t,MI_TOF_FILTER_DENOISE corresponds to MiTofFilterDenoiseParam_t,MI_TOF_FILTER_FLYING_PIXEL corresponds to MiTofFilterFlyPixelParam_t,MI_TOF_FILTER_DEALIASE_FLYPIXEL corresponds to MiTofDealiaseFlyPixelParams_t	Input

Return Value
- E_SUCCESS or 0: Success.
- -1: Failure
Dependencies
- Header files: PacketModule.h, mid_sys.h, mi_sys_datatype.h, tof_algorithm.h, TofChannelFrame.h

Example

//case1：Enable 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：Enable 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¶

Function

Get the status of tof algorithm iir/denoise filter/flying pixel filter/dealise flying pixel filter

Syntax

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

Parameters

Parameter Name	Description	Input/Output
Channel	Channel ID	Input
type	Different filter types defined by mi_tof_filter	Input
params	Different data structure definitions are passed in according to different filter types:MI_TOF_FILTER_IIR corresponds to MiTofFilterIirParam_t,MI_TOF_FILTER_DENOISE corresponds to MiTofFilterDenoiseParam_t,MI_TOF_FILTER_FLYING_PIXEL corresponds to MiTofFilterFlyPixelParam_t,MI_TOF_FILTER_DEALIASE_FLYPIXEL corresponds to MiTofDealiaseFlyPixelParams_t	Input

Return Value
- E_SUCCESS or 0: Success.
- -1: Failure

2.10. MI_Tof_SetAutoExposure¶

Function

Dynamically enable/disable auto exposure

Syntax

MI_S32 MI_Tof_SetAutoExposure(MI_U8 channel, bool enable);

Parameters

Parameter Name Description Input/Output

Channel Channel ID Input

enable 1: Enable AE; 0: Disable AE Input
Return Value
- E_SUCCESS or 0: Success.
- -1: Failure

2.11. MI_Tof_GetAutoExposure¶

Function

Dynamically enable/disable auto exposure

Syntax

MI_S32 MI_Tof_GetAutoExposure(MI_U8 channel, bool *enable);

Parameters

Parameter Name Description Input/Output

Channel Channel ID Input

enable 1: AE enabled; 0: AE disabled Output
Return Value
- E_SUCCESS or 0: Success.
- -1: Failure

2.12. MI_Tof_SetDebugParams¶

Function

Set algorithm debug parameters

Syntax

MI_S32 MI_Tof_SetDebugParams(MI_U8 channel, int* pDebugParams);

Parameters

Parameter Name	Description	Input/Output
Channel	Channel ID	Input
pDebugParams	pDebugParams[0]: Set debug level:0 – Turn off log printing1 – Algorithm uses golden raw data2 – Set algorithm debug level to INFO4 – Set algorithm debug level to ERRORpDebugParams[1][2]: Coordinates (x,y) of a point in the image for save data function. (-1,-1) means full image; (-1, x) (x>0) means column x; (x,-1) (x>0) means row x; (x>0, y>0) means a specific point.pDebugParams[3]: Frame number for save datapDebugParams[4]: Which stage of data to save. BIT[1] == 1 means save RAW data; BIT[6] == 1 means dump depth data (binary); BIT[7] == 1 means dump PCL (txt).Example: save pcl data:tofdebug 0 -1 -1 1 192	Input

Return Value
- E_SUCCESS or 0: Successfully obtained INZI Frame.
- -1: Obtaining failed, possibly because the current frame buffer is empty or the channel was created.

2.13. MI_Tof_SetAmplitudeFrameType¶

Function

Dynamically control whether amplitude uses high/low gain data for calculation. Low gain is used by default.

Syntax

MI_S32 MI_Tof_SetAmplitudeFrameType(MI_U8 channel, mi_tof_hdr_frame_type params);

Parameters

Parameter Name Description Input/Output

Channel Channel ID Input

params Hdr frame type. Refer to mi_tof_hdr_frame_type Input
Return Value
- E_SUCCESS or 0: Success.
- -1: Failure

2.14. MI_Tof_SetCalibrationType¶

Function

Dynamically enable/disable calibration type. By default, all calibration types are enabled. Debug interface.

Syntax

MI_S32 MI_Tof_SetCalibrationType(MI_U8 channel, uint32_t calib_type);

Parameters

Parameter Name	Description	Input/Output
Channel	Channel ID	Input
calib_type	0: Do not perform phase calibration.BIT[1]=1: Perform wiggling calibration;BIT[2]=1: Perform FPPN calibration;BIT[3]=1: Perform temperature calibration;	Input

Return Value
- E_SUCCESS or 0: Success.
- -1: Failure

Example

//case1 Enable wiggling、fppn、temperature calibration

MI_SNR_PAD_ID_e eSnrPad = gSnrPad;

MI_U32 calib_type = 7;

MI_Tof_SetCalibrationType(eSnrPad, calib_type);

//Enable DLL calibration

MI_SNR_PAD_ID_e eSnrPad = gSnrPad;

MI_U32 calib_type = 7 | (1<<4); //1<<4: Dll calibration

MI_Tof_SetCalibrationType(eSnrPad, calib_type);

2.15. MI_Tof_SetDebugLevel¶

Function

Set MI_TOF debug level. Debug interface.

Syntax

MI_S32 MI_Tof_SetDebugLevel(TofDebugLevel level, MI_U32 flag);

Parameters

Parameter Name	Description	Input/Output
TofDebugLevel	Debug level.typedef enum	Input
Flag	Set the time printing switch for algorithm threads.0: Do not print.BIT[0]=1: Print time for calculating phase and amplitude;BIT[1]=1: Print time for calibration;BIT[2]=1: Print time for filter, depth, and point cloud;	Input

Return Value
- E_SUCCESS or 0: Success.
- -1: Failure

2.16. MI_Tof_RegisterDepthCallBack¶

Function

Register callback for "Get TOF depth".

Syntax

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

Parameters

Parameter Name Description Input/Output

channel Channel ID Input

Depth Registration function callback for INZI brightness/depth data Input
Return Value
- E_SUCCESS or 0: Success.
- -1: Failure
Dependencies
- Header files: PacketModule.h, mid_sys.h, mi_sys_datatype.h, tof_algorithm.h, TofChannelFrame.h
Note

There are two methods to get INZI data:
- Method 1: MI_Tof_GetTofResult/MI_Tof_ReleaseTofResult;
- Method 2: MI_Tof_RegisterDepthCallBack/MI_Tof_UnRegisterDepthCallBack;

2.17. MI_Tof_UnRegisterDepthCallBack¶

Function

Unregister callback for "Get TOF depth".

Syntax

MI_S32 MI_Tof_UnRegisterDepthCallBack(MI_U8 channel);

Parameters

Parameter Name Description Input/Output

channel Channel ID Input
Return Value
- E_SUCCESS or 0: Success.
- -1: Failure
Note

There are two methods to get INZI data. The new SDK mainly supports method 2:
- Method 1: MI_Tof_GetTofResult/MI_Tof_ReleaseTofResult;
- Method 2: MI_Tof_RegisterDepthCallBack/MI_Tof_UnRegisterDepthCallBack;

2.18. MI_Tof_ParseEmbedInfo¶

Function

Get information from the embed line.

Syntax

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

Parameters

Parameter Name Description Input/Output

Channel Channel ID Input

embed Start address of footer buffer Input

info Footer information, such as frame number, quad number, etc. Output
Return Value
- E_SUCCESS or 0: Success.
- -1: Failure
Dependencies
- Header files: mi_parse_embed.h

2.19. MI_Tof_EnableInterferenceDeteced¶

Function

Enable "interference elimination during multi-device confrontation" function.

Syntax

MI_S32 MI_Tof_EnableInterferenceDeteced(MI_U8 channel, MiTofInterferenceDetecedParams_t* pDectectdParams);

Parameters

Parameter Name Description Input/Output

Channel Channel ID Input

pDectectdParams Input detection parameters, refer to struct MiTofInterferenceDetecedParams_t. Input
Return Value
- E_SUCCESS or 0: Success.
- -1: Failure
Dependencies
- Header files: mid_sys.h, mi_sys_datatype.h, tof_algorithm.h

2.20. MI_Tof_DisableInterferenceDeteced¶

Function

Disable "interference elimination during multi-device confrontation" function.

Syntax

MI_S32 MI_Tof_DisableInterferenceDeteced(MI_U8 channel);

Parameters

Parameter Name Description Input/Output

Channel Channel ID Input
Return Value
- E_SUCCESS or 0: Success.
- -1: Failure
Dependencies
- Header files: tof_algorithm.h

2.21. MI_Tof_SetFlip¶

Function

Set different flip types.

Syntax

MI_S32 MI_Tof_SetFlip(MI_U8 channel, mi_tof_flip_type type);

Parameters

Parameter Name Description Input/Output

Channel Channel ID Input

Type Flip type Input
Return Value
- E_SUCCESS or 0: Success.
- -1: Failure

2.22. MI_Tof_SetIrThreshold¶

Function

Set amplitude threshold. Pixels with values less than this will output depth 0.

Syntax

MI_S32 MI_Tof_SetIrThreshold(MI_U8 channel, MI_U32 value);

Parameters

Parameter Name Description Input/Output

Channel Channel ID Input

value Brightness value (0 to 4095) Input
Return Value
- E_SUCCESS or 0: Success.
- -1: Failure

2.23. MI_Tof_SetAeParam¶

Function

Set AE parameters.

Syntax

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

Parameters

Parameter Name Description Input/Output

Channel Channel ID Input

sdr AE parameter configuration for SDR Input

hdr AE parameter configuration for HDR Input
Return Value
- E_SUCCESS or 0: Success.
- -1: Failure

2.24. MI_Tof_GetAeParam¶

Function

Get AE parameters.

Syntax

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

Parameters

Parameter Name Description Input/Output

Channel Channel ID Input

sdr AE parameter configuration for SDR Output

hdr AE parameter configuration for HDR Output
Return Value
- E_SUCCESS or 0: Success.
- -1: Failure

2.25. MI_Tof_SetRotation¶

Function

Set rotation type.

Syntax

MI_S32 MI_Tof_SetRotation(MI_U8 channel, mi_tof_rotation_type type);

Parameters

Parameter Name Description Input/Output

Channel Channel ID Input

Type Rotation type Input
Return Value
- E_SUCCESS or 0: Success.
- -1: Failure

3. Application Case API Usage Flow¶

3.1 Method 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 Method 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);

    }

Explanation:

The above process is the most basic usage flow of MI Tof algorithm. For specific implementation details, please refer to mixer or tof demo.
Step 3 (putting raw data into the algorithm) and step 4 (getting depth data) can be performed in different threads, which allows algorithm processing of multiple raw data simultaneously to improve efficiency.

4. TOF Data Types¶

Data Type Definition	Data Type	Definition
1	mi_tof_mod	Define TOF calculation steps (Calc/Cali/Filter)
2	mi_tof_INZI_data	Define TOF calculated Frame type
3	MiTofSensorHwParams_t	Define Sensor HW description, converted from Sensor Driver
4	MiTofCaliParams_t	Define Calibration parameters
5	MiTofFilterParams_t	Define Filter parameters
6	MiTofAEParams_t	Define AE auto-exposure parameters and function callbacks
7	MiTofParams_t	Define TOF Channel initialization parameters
8	mi_tof_filter	Define filter types
9	tof_pixel_size	Define the size of each data unit in the RAW data output by the sensor, in bits
10	tof_raw_format	Define the Raw data format output by the sensor
11	tof_sensor_hdr_type	Define HDR type
12	tof_iir_params	Define iir filter structure
13	tof_denoise_params	Define denoise filter structure
14	tof_ae_sdr_params	Define auto-exposure parameters under SDR
15	tof_ae_hdr_params	Define auto-exposure parameters under HDR
16	mi_tof_hdr_frame_type	Define the method of using high gain or low gain to calculate amplitude
17	MiTofEmbedInfo	Define publicly available footer information
18	MiTofInterferenceDetecedParams_t	Define parameters required for enabling "interference elimination during multi-device confrontation" function
19	MiTofDllFilterParams_t	Define Dll calibration software config params.
20	MiTofDllFitlerCode_t	Define Dll calibration software config callback params.
21	MiTofDealiaseFlyPixelParams_t	Define parameters required for enabling flying pixel filter under dual frequency.

4.1. mi_tof_mod¶

Description

Define TOF calculation stages

Definition

typedef enum

{

MI_TOF_CALC = 0,

MI_TOF_CALI,

MI_TOF_FILTER,

TOF_MOD_MAX,

}mi_tof_mod;

Members

Member Description

MI_TOF_CALC Phase calculation

MI_TOF_CALI Phase calibration

MI_TOF_FILTER Filter optimization for phase

4.2. mi_tof_INZI_data¶

Description

Define TOF calculated Frame type, refer to 2.8.1. V4L2_PIX_FMT_INZI ('INZI') — The Linux Kernel documentation

Definition

#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 ()

Members

Member	Description
pts	Current frame timestamp
frameNum	Current frame sequence (reserved)
Ir	Brightness amplitude value (0~4096)
depth	Floating-point depth Z-axis distance
pcl	Floating-point point cloud data
depthInt	Integer depth Z-axis distance
pclInt	Integer point cloud data
width	Resolution width
height	Resolution height
frameHeader	Pointer to one buffer with integration-time and temperature, the buffer size is "width" Bytes

Note

Floating-point and integer depth/pcl data cannot be obtained simultaneously. Floating-point is obtained by default.Integer data can be obtained by enabling the DepthIntNeed parameter in MI_Tof_Init.

4.3. MiTofSensorHwParams_t¶

Description

Sensor HW description or HW parameters

Definition

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;

Members

Member	Description
width	Sensor resolution width
height	Sensor resolution height
pixel_size	Number of bits per pixel.
raw_format	Raw data format output by Sensor.
hdr_type	HDR type:0: Normal mode.1: Pixel HDR mode.2: Time HDR mode
dualFreq	Whether dual frequency is supported. Supporting dual frequency extends the test distance.
chip_id	CHIP ID
one_quad_one_footer	Whether the script has 1 quad with 1 footer
mod_freq1	High frequency
mod_freq2	Low frequency
ir_type	IR type
vcsel_type	VCSEL type, currently supports 3011 and JM2519

Note

These should be obtained through the 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¶

Description

TOF Calibration parameters

Definition

typedef struct _MiTofCaliParams

{

char* caliImage;

MI_U32 caliImageSZ;

}MiTofCaliParams_t;

Members

Member Description

caliImage Calibration Image buffer address

caliImageSZ Calibration Image size
Note

caliImage does not need to be released; MI_Tof_Uninit will release it.

4.5. MiTofFilterParams_t¶

Description

Filter parameters

Definition

typedef struct _MiTofFilterParams

{

MiTofFilterIirParam_t iirParams;

MiTofFilterDenoiseParam_t denoiseParams;

MiTofFilterFlyPixelParam_t flyPixelParams;

MiTofDealiaseFlyPixelParams_t dealiaseFlyPixelParams;

}MiTofFilterParams_t;

Members

Member	Description
iirParams	IIR Filter parameters.
denoiseParams	Denoise filter parameters.
dealiaseFlyPixelParams	Flying pixel filter parameters under dual frequency, refer to MiTofDealiaseFlyPixelParams_t.
flyPixelParams	Fly pixel filter parameters

4.6. MiTofAEParams_t¶

Description

Auto-exposure parameters

Definition

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;

Members

Member	Description
sdrParams	SDR exposure strategy parameters.
hdrParams	HDR exposure strategy parameters.
GetAETimeNs	Callback function to get current Sensor exposure time
SetAETimeNs	Callback function to set Sensor exposure time
AutoExposure	Enable auto-exposure

4.7. MiTofParams_t¶

Description

TOF Channel initialization parameters

Definition

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;

Members

Member	Description
SensorHwParams	Sensor hardware configuration parameters
mCaliParams	Calibration calculation parameters
AEParams	Auto-exposure parameters
FilterParams	Filter parameters
PclNeed	Enable point cloud algorithm
DepthIntNeed	Enable getting int depth
AmplitudeType	Configure amplitude type. The buffer size for externally provided amplitude will be allocated at this stage.
GetConfigID	Get config ID from sensor driver, generally used with SetConfigID to check if frame has been updated
SetConfigID	Similar to above
amplitude_threshold	Set amplitude threshold. Pixels below this threshold are invalid.
mDllFilterParams	Set Dll calibration filter parameters, such as gain. The smaller the setting, the more stable the phase; the larger the setting, the greater the weight of the current frame's dll code, and the faster the tracking speed when the measured phase changes drastically. See 4.19 for details.
amplitude_gain	IR image output effect control parameter:gamma curve 10==linear, setting range value 1-30, default 6, 0 = no fusion
amplitudeU8Need	Control whether IR outputs as U8, default is U16

4.8. mi_tof_filter¶

Description

Define TOF filter types

Definition

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;

Members

Member	Description
MI_TOF_FILTER_NONE	No tof filter
MI_TOF_FILTER_IIR	Tof iir filter.
MI_TOF_FILTER_DENOISE	Tof denoise filter (mode = 1), only different from "MI_TOF_FILTER_FLYING_PIXEL" in mode, only one can be selected.
MI_TOF_FILTER_FLYING_PIXEL	Flying pixel filter (mode = 2).
MI_TOF_FILTER_DEALIASE_FLYPIXEL	Flying pixel filter can be enabled under dual frequency

4.9. tof_pixel_size¶

Description

Define the size of each data unit in the RAW data output by the sensor, in bits.

Definition

typedef enum

{

TOF_PIXEL_SIZE_RAW12 = 12,

TOF_PIXEL_SIZE_RAW16 = 16,

TOF_PIXEL_SIZE_MAX = 0xFFFF,

}tof_pixel_size;

Members

Member	Description
TOF_PIXEL_SIZE_RAW12	Each data is 12 bits.If the Raw data format is one of the following, 1 pixel is 1 data, so 1 pixel is 12 bits:TOF_RAW_FORMAT_A_PLUS_BTOF_RAW_FORMAT_A_MINUS_B
TOF_PIXEL_SIZE_RAW16	Each data is 16 bits.If the Raw data format is one of the following, 1 pixel is 1 data, so 1 pixel is 16 bits:TOF_RAW_FORMAT_A_PLUS_BTOF_RAW_FORMAT_A_MINUS_B

4.10. tof_raw_format¶

Description

Define the Raw data format output by the sensor

Definition

typedef enum

{

TOF_RAW_FORMAT_A_PLUS_B,

TOF_RAW_FORMAT_A_MINUS_B,

TOF_RAW_FORMAT_NUM,

}tof_raw_format;

Members

Member Description

TOF_RAW_FORMAT_A_PLUS_B A+B mode for short. Sensor only outputs (A+B) DATA.

TOF_RAW_FORMAT_A_MINUS_B A-B mode for short. Sensor only outputs (A-B) DATA

4.11. tof_sensor_hdr_type¶

Description

Define HDR type

Definition

typedef enum

{

TOF_SENSOR_HDR_NONE,

TOF_SENSOR_HDR_PIXEL,

TOF_SENSOR_HDR_TIME,

TOF_SENSOR_HDR_NUM,

}tof_sensor_hdr_type;

Members

Member Description

TOF_SENSOR_HDR_NONE Normal mode. Indicates HDR is not enabled.

TOF_SENSOR_HDR_PIXEL HDR mode. Indicates pixel HDR case.

TOF_SENSOR_HDR_TIME TIME HDR mode

4.12. MiTofFilterIirParam_t¶

Description

Parameters related to IR filter

Definition

typedef struct

{

bool enable;

uint8_t gain;

}MiTofFilterIirParam_t;

Members

Member	Description
gain	Used to adjust the strength of IIR filter [0~128]. The larger the value, the more reference to the previous frame, the more obvious the effect.0: off128: max level (default)Note: Default gain is 128. If the signal is good and temporal noise is small, the gain value can be reduced.

4.13. MiTofFilterDenoiseParam_t;¶

Description

Related definitions for Denoise filter

Definition

typedef struct

{

bool enable;

uint16_t lpf_th;

uint16_t flypix_threshold;

}MiTofFilterDenoiseParam_t;

Members

Member	Description
enable	Whether to enable
lpf_th	Adjustment range (0~640). The larger the value, the more Pixels will undergo this filter processing.Default: 58freq_ratio e.g. 100M80M 290
flypix_threshold	Adjustment range (0~8192). The smaller the value, the easier to perform flying pixel correction.Default: 1380freq_ratio e.g. 100M80M 6900

Note:

gcd = CAL_GCD(mod1_freq, mod2_freq);freq_ratio = max(mod1_freq, mod2_freq)/gcd;

4.14. MiTofFilterFlyPixelParam_t¶

Description

Parameter definitions related to FlyPixelFilter

Definition

typedef struct

{

bool enable;

uint16_t lpf_th;

uint16_t flypix_gradient_th;

uint16_t flypix_diff_sum_th;

}MiTofFilterFlyPixelParam_t;

Members

Member	Description
Enable	Enable/disable filter
lpf_th	Adjustment range (0~1024). The larger the value, the more Pixels will undergo this filter processing.Default: 128freq_ratio e.g. 100M80M 40
flypix_gradient_th	Adjustment range (0~4096). The smaller the value, the more points will be treated as flying pixels and processed as invalid points.Default: 680freq_ratio e.g. 100M80M 3400
flypix_diff_sum_th	Adjustment range (0~8192). The smaller the value, the more points will be treated as flying pixels and processed as invalid points.Default: 1024freq_ratio e.g. 100M80M 5120

Note:

gcd = CAL_GCD(mod1_freq, mod2_freq);freq_ratio = max(mod1_freq, mod2_freq)/gcd;

4.15. MiTofDealiaseFlyPixelParams_t¶

Description

Dealiase Flypixel filter parameters

Definition

typedef struct

{

bool enable;

MI_U32 low_threshold;

MI_U32 high_threshold;

}MiTofDealiaseFlyPixelParams_t;

Members

Member	Description
Enable	Enable/disable
low_threshold	Adjustment range (0~4086). Pixels greater than low_threshold are judged as flying pixels and processed as invalid values.Default: 800
high_threshold	Adjustment range (0~4096). Pixels less than high_threshold are judged as flying pixels and processed as invalid values.Default: 3200

4.16. tof_ae_sdr_params¶

Description

SDR Exposure strategy parameters

Definition

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;

Members

Member	Description
black_level	Average brightness reported by the sensor when integration time is set to 0
yth_low	Minimum average brightness required for the image when adjusting integration time
yth_high	Maximum average brightness required for the image when adjusting integration time
upper_cnt_limitH;	Maximum number of pixel counts that can exceed the pixel upper threshold when adjusting integration time
upper_cnt_limitL	Minimum number of pixel counts that can exceed the pixel upper threshold when adjusting integration time
exp_limit_low	Lower limit of integration time adjustment [ns]
exp_limit_high	Upper limit of integration time adjustment [ns]
exp_step_slow	Shortest interval time for each integration time adjustment [ns] (minimum difference between two consecutive adjustments)
exp_step_fast	Longest interval time for each integration time adjustment [ns] (maximum difference between two consecutive adjustments)

4.17. tof_ae_hdr_params¶

Description

HDR Exposure strategy parameters

Definition

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;

Members

Member	Description
black_level	Average brightness reported by the sensor when integration time is set to 0
yth_low	Minimum average brightness required for the image when adjusting integration time
yth_high	Maximum average brightness required for the image when adjusting integration time
upper_cnt_limitH;	Maximum number of pixel counts that can exceed the pixel upper threshold when adjusting integration time
upper_cnt_limitL	Minimum number of pixel counts that can exceed the pixel upper threshold when adjusting integration time
exp_limit_low	Lower limit of integration time adjustment [ns]
exp_limit_high	Upper limit of integration time adjustment [ns]
exp_step_slow	Shortest interval time for each integration time adjustment [ns] (minimum difference between two consecutive adjustments)
exp_step_fast	Longest interval time for each integration time adjustment [ns] (maximum difference between two consecutive adjustments)

4.18. mi_tof_hdr_frame_type¶

Description

Define the method of using high gain or low gain to calculate amplitude

Definition

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;

Members

Member	Description
MI_TOF_HDR_FRAME_HIGH_GAIN	Use high gain data for amplitude calculation
MI_TOF_HDR_FRAME_LOW_GAIN	Use low gain data for amplitude calculation
MI_TOF_HDR_FRAME_MIX	Currently equivalent to HDR_FRAME_LOW_GAIN in effect
MI_TOF_HDR_FRAME_BOTH	Provide both High gain and Low gain amplitudes.If this type of amplitude data is needed, it should be configured during MI_Tof_Init. Dynamic switching with other types is not supported.
MI_TOF_HDR_FRAME_NUM	-

4.19. MiTofEmbedInfo¶

Description

Define publicly available footer information

Definition

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;

Members

Member	Description
frame_num	Indicates the current frame number
sub_frame_number	Indicates the current sub frame count
quad_num	Indicates the current quad index
amp_mean	Indicates the average brightness of the high gain part in the current statistical area, data needed for AE
amp_mean_hdr	Indicates the average brightness of the low gain part in the current statistical area, data needed for AE
amp_upper_cnt	Indicates the number of pixels in the high gain part of the current statistical area that are higher than amp_threshhold, data needed for AE
amp_upper_cnt_hdr	Indicates the number of pixels in the low gain part of the current statistical area that are higher than amp_threshhold, data needed for AE
intergration_time	Indicates the integration time used for the current frame, data needed for AE
vcsel_temperature	Indicates the current driver IC temperature
sensor_temperature	Indicates the current sensor temperature
config_id	Indicates the config_id of the current frame, generally used to check if register settings with buffer buffering have taken effect
hdr_type	Indicates whether pixelhdr is enabled for the current frame configuration.
dllCode	Indicates the code value of HW DLL lock.

4.20. MiTofInterferenceDetecedParams_t¶

Description

Define parameters required for enabling "interference elimination during multi-device confrontation" function

Definition

typedef struct MiTofInterferenceDetecedParams

{

MI_S32 (*SensorRestart)(MI_U8 channel);

}MiTofInterferenceDetecedParams_t;

Members

Member Description

SensorRestart Callback function pointer: Close shutter -> Reset config_id -> Shutter.

4.21. MiTofDllFilterParams_t¶

Description

Define Dll calibration software config callback params.

Definition

typedef struct _MiTofDllFilterCode

{

MI_U16 filter_code;

bool selectOn;

}MiTofDllFitlerCode_t;

Members

Member Description

filter_code This value is only meaningful when selectOn is 1.

selectOn 0: Use HW auto Dll;1: Switch to using "software filter's dll code" method

4.22. MiTofDllFitlerCode_t¶

Description

Define Dll calibration software config params.

Definition

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;

Members

Member	Description
filter_gain	0: disable the dll calibration sw config function;Non-zero: [1~16]. The smaller the gain setting, the more stable the phase; the larger the setting, the greater the weight of the current frame's x-delay code, and the faster the tracking speed when the measured phase changes drastically.
SetDllClibSwConfig	Callback function pointer: Used to control sensor Drv to set related registers.

Note:

Be sure to decide whether to enable this function based on capability.

4.23. MiTofIntergrationTime_t¶

Description

Define integration time

Definition

typedef struct _MiTofIntergrationTime

{

MI_U32 normal_integration_time; //ns

MI_U32 hdr_integration_time; //ns

void *reserved;

}MiTofIntergrationTime_t;

Members

Member Description

normal_integration_time Normal integration time

hdr_integration_time Time HDR integration time

4.24. mi_tof_flip_type¶

Description

Define flip type

Definition

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;

Members

Member Description

MI_TOF_FLIP_NONE None

MI_TOF_FLIP_H Horizontal flip

MI_TOF_FLIP_V Vertical flip

MI_TOF_FLIP_HV Both horizontal and vertical flip

MI_TOF_FLIP_NUM Num

4.25. mi_tof_rotation_type¶

Description

Define rotation type.

Definition

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;

Members

Member	Description
MI_TOF_ROTATION_0	No rotation
MI_TOF_ROTATION_90	Rotate 90° clockwise
MI_TOF_ROTATION_180	Rotate 180° clockwise
MI_TOF_ROTATION_270	Rotate 270° clockwise
MI_TOF_ROTATION_NUM	Num

Member	Description
MI_TOF_CALC	Phase calculation
MI_TOF_CALI	Phase calibration
MI_TOF_FILTER	Filter optimization for phase

Member	Description
caliImage	Calibration Image buffer address
caliImageSZ	Calibration Image size

Member	Description
TOF_RAW_FORMAT_A_PLUS_B	A+B mode for short. Sensor only outputs (A+B) DATA.
TOF_RAW_FORMAT_A_MINUS_B	A-B mode for short. Sensor only outputs (A-B) DATA

Member	Description
TOF_SENSOR_HDR_NONE	Normal mode. Indicates HDR is not enabled.
TOF_SENSOR_HDR_PIXEL	HDR mode. Indicates pixel HDR case.
TOF_SENSOR_HDR_TIME	TIME HDR mode

Member	Description
filter_code	This value is only meaningful when selectOn is 1.
selectOn	0: Use HW auto Dll;1: Switch to using "software filter's dll code" method

Member	Description
normal_integration_time	Normal integration time
hdr_integration_time	Time HDR integration time

Member	Description
MI_TOF_FLIP_NONE	None
MI_TOF_FLIP_H	Horizontal flip
MI_TOF_FLIP_V	Vertical flip
MI_TOF_FLIP_HV	Both horizontal and vertical flip
MI_TOF_FLIP_NUM	Num