Extract DSTIP (spatio-temporal interest points) and DCSF (local cuboid descriptor) from depth video captured by Kinect beta (2013-07-05)

download
==========================
http://cvrc.ece.utexas.edu/lu/index.html

Authors:
=============================
This code was developed by Lu Xia for paper Spatio-Temporal Depth Cuboid Similarity Feature for Activity Recongition Using Depth Camera". In Proceedings of the 24th IEEE Conference on Computer Vision and Pattern Recognition (CVPR), Portland, Oregon, June 2013. 
Note: the orignal code was refactored intensively to generate this executable, so some of the parameters maybe different from the description in the paper. Please read the code when in doubt.
******************************************** Runing Prebuild Binary *******************************************

Description:
=================================
The code in this directory contains two parts:
1. detect spatio-temporal interest points(STIPs) from depth videos

Input:
======================
The input depth video is in .bin format (see MSRAction3D or MSRDailyActivity3D dataset for more detail:http://research.microsoft.com/en-us/um/people/zliu/actionrecorsrc/)
The orignial Matlab code is given so developer can add a few lines to read data in other format.

Output:
===================
the output is the location of the DSTIPs in spatio-temporal and scale domains.
The output is an n by 5 matrix, n represents the number of DSTIPs extracted. Each row contains the location information of one DSTIP: x,y,t,sigma, tao.

Parameters:
===============
% 1.inputFile: the path+name of the input depth video, MSR '.bin' format
% 2.outputFile: the path+name of the output result file. '.txt' format
parameters:
% nPoints --No of Points to extract per video
% HSIZE-- window size of Gaussian filter
% SIGMA --  spatio scale, Gauss variance
% TAO -- temproal scale of Gabor filter; cannot be larger than video duration/2;
% boarder -- leave enough space to extract a cuboid around the DSTIPs
% noise suppressor --  set to 0 when there is no backgroud for faster process. The noise suppressor gives significant improvement when the scale of the human movement is small.
% noise_thresh -- larger value removes more noise (too large value may hurt fast movement)
% display -- 1: display the result, 0: no display

Note: parameters take different optimum values for different dataset and classification method. The default value does not guarantee best result. User should try out different parameters for the best performance.

2. compute the local spatio-temporal cuboid descriptors called Depth Cuboid Similarity Feature(DCSF) 
Input:
======================
1. depthFile: The input depth video is in .bin format (see MSRAction3D or MSRDailyActivity3D dataset for more detail:http://research.microsoft.com/en-us/um/people/zliu/actionrecorsrc/)
The orignial Matlab code is given so developer can add a few lines to read data in other format.
2. DSTIP file: The DSTIP file generated by part 1.

Output:
===================
the output is the descriptor with the location information of one DSTIP: x,y,z,t,sigma,tao. (Note: z is added)
column 1 to 6 is: x,y,z,t,sigma,tao.
column 7 to the end: the descriptor (lenght depend on the parameter NoCellX, NoCellY, NoCellZ)

Parameters:
===============
% 1. depthFile:  the path+name of the input depth video, MSR '.bin' format
% 2. DSTIPFile: the path+name of the input DSTIP location file. '.txt' format
% 3. outputFile: the path+name of the output file. '.txt' format
% optional parameters:
% LengthXY -- the size of the cuboid on x,y,dimension = 2*LengthXY*sigma;
% LengthT-- the size of the cuboid on t dimension = 2*LengthT*tao;
% DepthMin -- the cutoff value for the minimum depth (Kinect depth has closest distance limit)
% NoCellX -- divide the cuboid into 2*NoCellX blocks in x dimension 
% NoCellY -- divide the cuboid into 2*NoCellY blocks in y dimension 
% NoCellT -- divide the cuboid into 2*NoCellT blocks in t dimension
% NoBin -- the number of bins of the depth histogram  (denote by M in the paper)

Note: parameters take different optimum values for different dataset and classification method. The default value does not guarantee best result. User should try out different parameters for the best performance.

dependencies:
=============
requires Matlab Run Time (MCR) 7.14 (R2010b).

running
===================
Example:
>ExtractDSTIP.exe ..\video\a01_s01_e01_depth.bin   ..\DSTIP_result\a01_s01_e01_depth.txt nPoints 200 display 1
input File:
inputFile =
..\video\a01_s01_e01_depth.bin
output File:
outputFile =
..\DSTIP_result\a01_s01_e01_depth.txt
paramsStruct =
         nPoints: 200
		   HSIZE: 5
           SIGMA: 1
             TAO: 20
         boarder: 15
 noiseSuppressor: 1
    noise_thresh: 4
         display: 1
Elapsed time is 8.057224 seconds.

>ExtractDCSF.exe ..\video\a01_s01_e01_depth.bin   ..\DSTIP_result\a01_s01_e01_depth.txt  ..\DCSF_result\a01_s01_e01_depth.txt DepthMin 60
depth File:
depthFile =
..\video\a01_s01_e01_depth.bin
DSTIP file:
DSTIPFile =
..\DSTIP_result\a01_s01_e01_depth.txt
output File:
outputFile =
..\DCSF_result\a01_s01_e01_depth.txt
paramsStruct =
			LengthXY: 15
			LengthT: 1
			DepthMin: 60
			NoCellX: 4
			NoCellY: 4
			NoCellT: 2
			NoBin: 35
extracting...
total number of points
ans =
   200
Elapsed time is 3.966127 seconds.

************************** build executable from source file **********************************
The source code of the algorithm is given in matlab file.
To build your own executable from the .m file:
to build the extracting DSTIP part,type in matlab:
>>mcc -m ExtractDSTIP.m zc.m
to build the extracting DCSF part, type in matlab:
>>mcc -m ExtractDCSF.m ExtractDescriptor.m