Copyright (C) 2014 Alina Kuznetsova

This program is free software: you can redistribute it and/or modify
it under the terms of the GNU Lesser General Public License as published by
the Free Software Foundation, either version 2.1 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU Lesser General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program.  If not, see <http://www.gnu.org/licenses/>.

Author: Alina Kuznetsova 

=================================News===========================================

- The test data collected using Intel Creative Depth Sensor can be downloaded from
here: http://www.tnt.uni-hannover.de/en/project/handposerecognition/data.zip

- The corner detector is switched to the automatic MATLAB corner detector - 
now you only need to select the regions where the checkerboard is and not the 
exact corners (-> faster)

================================================================================

Please cite the following work if you use the code:

Alina Kuznetsova, Bodo Rosenhahn 
"On calibration of a low-cost time-of-flight camera"
ECCVW 2013

@InProceedings{Kuznetsova_2014_ECCV_Workshops,
author = {Alina Kuznetsova and Bodo Rosenhahn},
title = {On calibration of a low-cost time-of-flight camera},
booktitle = {The IEEE European Conference on Computer Vision (ECCV) Workshops},
month = {September},
year = {2014}
}

If you have any questions, please contact me: [email protected]

=========================3d-party code used======================================

The following 3d-party code is used and included with the code:

1) the ToF Calibration toolbox is based on Matlab Kinect calibration toolbox (http://www.ee.oulu.fi/~dherrera/kinect/)
2) the code uses Gaussian Kernel regression by Youngmok Yun (http://youngmok.com/gaussian-kernel-regression-for-multidimensional-feature-with-matlab-code/)
3) the code uses fast distance matrix computation by Mo Chen (http://www.mathworks.de/matlabcentral/fileexchange/24599-pairwise-distance-matrix)

=========================Usage======================================

Please note, that right now the Toolbox supports only one color camera. 
This will be corrected in future releases.

Starting new calibration, firstly call:
 
global_vars(); %make all global variables visible in the workspace
dataset_path = '%ENTER YOUR PATH HERE%'; %set the path to the folder, containing RGB, conf and depth images
iterative_calib %start calibration

Then follow the instructions printed in MATLAB;
At some point, you will have to select checkerboard corners, but the corners might not be found correctly.
If it happends, break the process (Ctrl+C) and start again; the process will be started from the same point

The final calibration will be available in workspace as 

calib %object containing calibration parameters
errors %errors at each iteration

* To show color-depth overlay:
function color_depth_overlay(calib,rgbfile,depthfile) %show depth-to-rgb overlay
function color_depth_overlayi(calib,i) %show depth-to-rgb overlay of the i-th calibration image

* To transform depth to world coordinates

pn = get_dpoint_direction_Intel(p(1,:),p(2,:),calib.cK,calib.ckc); %pixel coordinates to normalized coordinates
p3D = [pn.*repmat(d,2,1); d]; %coordinates in 3D (d denotes corresponding depth value)

* To transform depth to rgb camera system

p3Drgb = calib.cR * p3D + repmat(calib.ct,1, size(p3D,2)); 

* To reproject depth points to RGB camera plane 

function prgb = depth2rgb(p,d,calib)
    
* Save all global variables

function save_globals(fn)

* Load all global variables

load(filename) %standard MATLAB function

* To run the calibration from the start, set the corresponding fields in calib0 to []