\documentclass[headsepline]{article}

\usepackage{listings}
\usepackage{latexsym}
\usepackage{wrapfig}
\usepackage{eso-pic,graphicx}
\usepackage{booktabs}
\usepackage{hyperref}
\usepackage{helvet} 
\usepackage{sectsty}
\usepackage{url}
\usepackage{color}
\usepackage{colortbl}
\usepackage{geometry}
\usepackage{amsmath}

%% define paper geometry
\geometry{a4paper, top=40mm, left=30mm, right=30mm, bottom=30mm, headsep=25mm, footskip=15mm, footnotesep=15mm}


%% Define path and directory templates
\newcommand{\QTPath}{\texttt{<QT\_DIR\_PATH>}}
\newcommand{\LibPath}{\texttt{.../libs/}}
\newcommand{\ITKPath}{\texttt{InsightToolkit-3.20.1/}}
\newcommand{\VTKPath}{\texttt{VTK-5.6.1/}}
\newcommand{\VSbin}{\texttt{VC-10}}
\newcommand{\VStudio}{\textit{VS2010}}
\newcommand{\RITKinstalldir}{\texttt{<RITK\_SOURCE\_DIR>}}
\newcommand{\RITKsrcdir}{\texttt{/SurfaceImaging/RITK/v10/RITK}}
\newcommand{\RITKbindir}{\texttt{<RITK\_BIN\_DIR>}}
\newcommand{\vdist}{12mm}

\newcommand{\appname}[1]{\textit{#1}}
\newcommand{\cmdname}[1]{\texttt{#1}}
\newcommand{\pathname}[1]{\texttt{#1}}

%% Define user colors using the RGB model
\definecolor{grau4}{rgb}{0.8,0.8,0.8}
\definecolor{grau5}{rgb}{0.95,0.95,0.95}
\definecolor{rowblue}{rgb}{0.83,0.87,0.93}


%% Font style
\allsectionsfont{\sffamily\selectfont}
\sffamily

%% Header Logo
\newcommand{\mylogo}{\includegraphics[scale=0.2]{images/ritk.pdf}}
\usepackage{scrpage2}
\pagestyle{scrheadings}
\clearscrheadfoot
\chead{\headmark}
\cfoot[\pagemark]{\pagemark}
\ohead[\mylogo]{\mylogo}
\ihead[\today]{\today}
\chead{RITK InstallGuide for Windows}

%% contents and titlepage
\title{RITK Installation Guide for Windows}
\begin{document}
\sffamily
\maketitle
\thispagestyle{empty} 

\begin{center}
	\includegraphics{images/ritk.pdf}
\end{center}

\vspace{\vdist}

\begin{center}
The Range Imaging Toolkit (RITK) is a software framework for the development of range imaging (RI) applications. The toolkit is developed at the \href{http://www5.informatik.uni-erlangen.de}{Pattern Recognition Lab}, University Erlangen-Nuremberg, Germany.\\

\end{center}

\begin{center}
Please send your feedback to this manual to \href{mailto:ritk@i5.informatik.uni-erlangen.de}{ritk@i5.informatik.uni-erlangen.de}
\end{center}
 
\vspace{\vdist}

\tableofcontents

\newpage

\section{Setting up the Environment}\label{env_setup}

\subsection{Applications}
\textbf{Download} and \textbf{install} the following applications that are required to install the libraries needed for the RITK (32 or 64-bit):
\newline
\newline
\noindent
\begin{tabular}{p{3cm}p{6.5cm}p{4cm}}\toprule
Name & Link   & Comment \\ \midrule
\rowcolor{rowblue}
Visual Studio 2010 (\VStudio) Express\footnotemark \footnotemark &  \url{http://www.microsoft.com/visualstudio/en-us/products/2010-editions/visual-cpp-express}    &  Download and install Visual 2010 C++ Express (hereafter denoted as \VStudio)\\
CMake   &  \url{http://www.cmake.org}    & Download newest version   \\

%% internal
%\rowcolor{rowblue}
%Tortoise SVN    & \url{http://tortoisesvn.net/downloads}      &  \\ 

\bottomrule
\end{tabular}
\newline\newline

\noindent
You can also use \appname{Visual Studio 2008} if you already have it installed on your system. Any older version is not guaranteed to work with RITK.
\newline

\noindent
\textit{Note that if you want to build the 64-bit version of RITK you will need the 64-bit version of Visual C++'s compiler \cmdname{cl.exe} which is \emph{not} included in the Express edition. Either you install the Professional or Ultimate versions, or download a version of the Windows SDK that includes \cmdname{cl.exe} from Microsoft's website.}

%% Fussnoten innerhalb der tabelle
\footnotetext[1]{You will need an emulation program to mount the VS2010 *.iso files. Use e.g. \href{http://www.daemon-tools.cc/eng/home}{deamon tools}}
\footnotetext[2]{via Microsoft's MSDNAA program you may also acquire the Professional or Ultimate versions if you are a student or university member}

\subsection{Libraries}
\textbf{Download} and \textbf{install} the following applications or sources that are required to install the libraries needed for the RITK (32 or 64 bit):
\newline
\newline
\noindent
\begin{tabular}{p{3cm}p{6.5cm}p{4cm}}\toprule
Name & Link   & Comment \\ \midrule
\rowcolor{rowblue}
Qt& \url{http://get.qt.nokia.com/qt/source/qt-everywhere-opensource-src-4.8.0.zip} & Compile newest version yourself or download precompiled binaries \\ 
CUDA 4.0 & \url{http://developer.nvidia.com/cuda-toolkit-40} & Download and install only the \textit{Toolkit}\\
\rowcolor{rowblue}

Insight Toolkit (ITK)& \url{http://itk.org/ITK/resources/software.html} & Source Files Version 3.20 (will \emph{not} work with ITK 4.0.0) \\

Visualization ToolKit (VTK)& \url{http://vtk.org/VTK/resources/software.html} & Source Files Version 5.8.0 or later\\
\bottomrule
\end{tabular}
\newline\newline

\noindent
These libraries are fundamental to RITK and thus have to be installed. Therefore we have included instructions on how to compile and install them in the following sections. But first note that for some of the plug-ins to compile, you will furthermore need the libraries listed in the following table.

\newpage\noindent
\noindent
\begin{tabular}{p{3cm}p{6.5cm}p{4cm}}\toprule
Name & Link   & Comment \\ \midrule
\rowcolor{rowblue}

%OpenCV\footnotemark 2.2.0 & \url{http://sourceforge.net/projects/opencvlibrary/files/opencv-win/2.2/} & Download \textit{OpenCV-2.2.0-win.zip} \\

MS Kinect SDK\footnotemark & \url{http://research.microsoft.com/en-us/um/redmond/projects/kinectsdk/download.aspx}& \\

OpenNI\textsuperscript{\ref{fn-kinect}}& \url{https://github.com/avin2/SensorKinect}& Follow the installation guide \href{http://www.codeproject.com/Articles/148251/How-to-Successfully-Install-Kinect-on-Windows-Open.aspx?msg=3778324}{here} \\

\rowcolor{rowblue}
libnoise & \url{http://libnoise.cvs.sourceforge.net/libnoise/} & download and compile the newest CVS sources \\
\bottomrule
\end{tabular}


%% Fussnoten innerhalb der tabelle
\footnotetext{\label{fn-kinect}Please note that you have to decide either for installing OpenNI or MS Kinect SDK. In general, both will not work side by side in general.}

%% Loesung fuer mehrere Fussnoten innerhalb der tabelle:
%\addtocounter{footnote}{-1}% Anzahl footnotemark - 1
%
%\footnotetext{foo1}
%\stepcounter{footnote}
%\footnotetext{foo2}
%\stepcounter{footnote}
%\footnotetext{foo3}
%%

\subsubsection[Qt Installation]  {Qt Installation (4.8.0)}
If you are compiling the 32-bit version of RITK probably the fastest and safest way to acquire Qt is by installing the appropriate binaries offered by Nokia. Just be sure that the binaries match your environment (e.g.\ in our case \appname{Microsoft Visual Studio 2010}), otherwise RITK won't work. 

There are a few reasons why you would want to compile Qt yourself: Firstly, Nokia does not provide 64-bit binaries, so you have to do it yourself. Secondly, you want more control over what Modules are built and installed; for example, you might want Qt to have less dependencies or use less disk space. Either way, follow these instructions to build Qt:
\begin{enumerate}
	\item Unpack the source archive to a custom destination, let us say \QTPath
	\addtocounter{enumi}{1}
	\item[\arabic{enumi}a.] If you want to compile the 32-bit version of RITK, open the \appname{\VStudio\ Command Prompt} from the Tools Menu or Windows Start Menu
	\item[\arabic{enumi}b.] If you want to compile the 64-bit version of RITK, open the \appname{\VStudio\ x64 Win64 Command Prompt} from the Windows Start Menu
	\item Add \QTPath\texttt{\textbackslash bin} to the \texttt{PATH} variable via
	\[\texttt{set PATH=\%PATH\%;\QTPath\textbackslash bin}\]
	\item Go to \QTPath, type 
\[\texttt{configure -platform win32-msvc2010}\]
 (this is for both builds; 64-bit version will build fine) and follow the instructions to configure Qt.
 
		\textit{This will build a full Qt system which might take several hours. If you want to shorten the compile time and just want to use Qt for RITK, consider adding the following arguments to the \cmdname{configure} command:
		\[\cmdname{-nomake examples -nomake demos}\]
		for omitting all examples and demos; furthermore
		\begin{align*}\cmdname{-no-webkit -no-script -no-scripttools -no-qt3support} \\ \cmdname{-no-phonon -no-phonon-backend -no-ltcg -no-multimedia}\end{align*}
		for omitting certain parts of Qt that are not needed by RITK.}
	\item Type \cmdname{nmake} to build the desired version of Qt (this may take several hours, depending on your configuration in the previous step)
	
		\textit{If you have a multi-core CPU you can speed up the build process by using Nokia's \href{https://qt.gitorious.org/qt-labs/jom}{\cmdname{jom}} instead of \cmdname{nmake}.}
	\item To facilitate the following compile processes, you may add the new environment variable \texttt{QTDIR} to your system, which should point to \QTPath (you can use an editor like \href{http://www.rapidee.com/en/download}{Rapid Environment Editor} or just go to System and Security in your Control Panel and then 
\[\text{System}\rightarrow\text{Advanced system settings}\rightarrow\text{Advanced}\rightarrow\text{Environment Variables...}\]
if you have Windows 7).
	\item It is also advisable to include \QTPath\pathname{\textbackslash bin} permanently in your \pathname{PATH} variable; otherwise you will have to copy all needed Qt DLLs into your RITK binary directory.
\end{enumerate}

\subsubsection[CUDA Installation]{CUDA Installation (4.0)}
Install the CUDA Toolkit 4.0 with the setup wizard by using its default settings.

\subsubsection[ITK Installation]{ITK Installation (3.20.1)}
ITK does not provide any setup wizard but has to be compiled. The first step is to unzip the archive into a subfolder in your library folder (e.g. \LibPath \ITKPath). In this folder you should now find a file called CMakeLists.txt. This file is now used by CMake to create a \VStudio\ Project:

\begin{enumerate}
	\item Open \appname{CMake} (\cmdname{cmake-gui}).
	\item Set the source path to the ITK root directory (\ITKPath).
	\item Set the directory where the binaries will be built (usually a subfolder of the source folder, as we are using \VStudio\ we call this folder \VSbin).
	\item Click \textit{Configure}. If \appname{CMake} asks whether to create the specified folder click \textit{Yes}.
	\item Now a window will pop up where you have to specify the generator. Select \appname{Visual Studio 10} for the 32-bit or \appname{Visual Studio 10 Win 64} for the 64-bit version and click \textit{Finish}. CMake will now configure the project. This could take a while.
	\item After configuring, CMake will show you some options (name and value) that depend on the actual project. For compiling ITK make sure that the option
		\subitem \texttt{BUILD\_SHARED\_LIBS} is enabled 
		\subitem \texttt{BUILD\_TESTING} and \texttt{BUILD\_EXAMPLES} is disabled (for faster compilation).
	\item Again, click \textit{Configure}.
	\item Click \textit{Generate} (This will create a \VStudio Solution \texttt{.sln} file).
	
\end{enumerate}

\noindent Now we are ready to compile ITK.\vspace{1em}\\
In the binary folder (e.g.\ \LibPath \ITKPath \VSbin) you should find a file \pathname{ITK.sln}, this is the \VStudio\ Solution file. A double-click will open the solution. Build the project in \texttt{RELEASE} and/or \texttt{DEBUG} configuration. This may take a while.


\subsubsection[VTK Installation]{VTK Installation (5.8.0)}

The steps to build VTK are in general the same as for ITK: Extract files to a subfolder in your library folder, open \texttt{CMakeLists.txt} with \appname{CMake} (make sure to update the source and binary paths), setting some options, generating a Visual Studio solution file and, finally, building the solution \pathname{VTK.sln} in \texttt{RELEASE} and/or \texttt{DEBUG} (debug built of Qt must be available) mode.\\
The following options have to be set:

\begin{enumerate}
	\item Make sure that you enable \texttt{BUILD\_SHARED\_LIBS}.
	\item Disable \texttt{BUILD\_TESTING}, and \texttt{BUILD\_EXAMPLE}, then click \textit{Configure} (you may want to enable them but this takes really long to compile).
	\item Switch to the \textit{Grouped} view and expand the VTK section, enable \texttt{VTK\_USE\_PARALLEL} and \texttt{VTK\_USE\_QT}, then click on \textit{Configure}.
	\item Make sure that \texttt{QT\_QMAKE\_EXECUTABLE} under \textit{QT} points to the correct Qt installation\\ (\QTPath\cmdname{\textbackslash bin\textbackslash qmake.exe} if you followed our compilation guide)
	\item Click on \textit{Configure} and then \textit{Generate} to create \pathname{VTK.sln} in your binary folder.
\end{enumerate}
Building VTK is now the same as for ITK. 

%\subsubsection{OpenCV Installation}
%To install OpenCV you just have to follow the wizard. Afterwards you need to set one environment variable in most windows systems: add to \texttt{PATH} the following directory \texttt{.../OpenCV/bin}.

\section{Setting up the RITK}
In this section, we will first build the RITK application and then the packaged plug-ins. RITK heavily utilizes the plug-in architecture, so be sure to compile and install them.

\subsection{Compiling the RITK}
Now on to the main part:
\begin{enumerate}
	\item Download the sources from \url{http://www5.cs.fau.de/ritk}.
	\item Unzip the files to a custom destination, let us say \RITKinstalldir .
	%%internal
	%\item go to your directory, where you want to download the files by using svn. Then do a right click with your mouse and select "SVN Checkout…". Enter the URL \texttt{https://svn.i5.informatik.uni-erlangen.de/svn/SurfaceImaging} and hit OK. Enter your svn-login and download all the files.
	\item Open \appname{CMake} (\cmdname{cmake-gui}) and select
		\subitem \RITKinstalldir \RITKsrcdir \ for the source directory
		\subitem \RITKinstalldir \RITKsrcdir /\VSbin \ for the build directory.
	\item Now click \textit{Configure} and set \texttt{CMAKE\_INSTALL\_PREFIX} to your needs, let us say \RITKbindir \\ (default: \pathname{C:/Program Files/RITK} resp.\ \pathname{C:/Program Files (x86)/RITK}).
	\item Again, click \textit{Configure} and finally \textit{Generate}.
	\item Build RITK with \VStudio\ (\texttt{DEBUG} if Qt, ITK and VTK debug builds are available, and \texttt{RELEASE}) in analogy to ITK/VTK .
	\item In \VStudio, right-click on the project "\texttt{INSTALL}" in the solution browser and choose "Project Only/Build only INSTALL..." to install RITK (you might need administrator privileges for this -- right-click on \VStudio\ in the Start Menu and choose "Run as administrator")
	\item Copy all required dll files into the folder \RITKbindir\texttt{/bin/debug (release)}
		\subitem Copy all VTK DLLs: \\ \LibPath \VTKPath \VSbin \texttt{/bin/debug (release)}
		\subitem Copy the ITK DLL: \\
			\LibPath \ITKPath \VSbin \texttt{/bin/debug (release)/ITKCommon.dll}
	
\end{enumerate}

\noindent
Now the RITK is ready to use, the application (debug/release versions) can be found in:
\begin{itemize}
	\item Debug: \RITKbindir \texttt{/bin/debug/ritkd.exe}
	\item Release \RITKbindir \texttt{/bin/release/ritk.exe}
\end{itemize}
\noindent If there are any problems with starting RITK (e.g.\ error messages where some entry point is missing), please copy the DLLs for QT, too -- in analogy to ITK/VTK. If problems persist, try using \href{http://www.dependencywalker.com}{\appname{DependencyWalker}} to identify missing dependencies.

\subsection{Setting up the Packaged Plug-ins}
Compiling and installing the plug-ins follows a very similar procedure.
\begin{enumerate}
\item Open \appname{CMake} and choose \pathname{RITKPlugins} as source directory, as well as an appropriate build directory.
\item Click on \textit{Configure} and afterwards set the correct library directories as requested by \appname{CMake}.\\
(Hint: you can omit plug-ins from the build process by checking "Advanced" and "Grouped" and removing the mark from the plug-in's name under RITK)
\item Also make sure that \texttt{RITK\_INSTALL\_DIR} points to the correct directory.
\item Finally, click \textit{Configure} and \textit{Generate}.
\item Open the generated solution and build it as usual.
\item Now build only the \pathname{INSTALL} project to install the plug-ins.
\end{enumerate}

\subsection{Testing the RITK}
You can now test RITK for correct operation. Start up \cmdname{ritk.exe} in your installation directory and press 'Ctrl+M' to open the plug-in manager. If there is one missing, check with \appname{DependencyWalker} whether all needed DLLs (e.g.\ \pathname{libnoise.dll}) are within reach (in a directory in the path or the directory \cmdname{ritk.exe} is in).

If all plug-ins load fine, try to click on the body of the Visualization plug-in and press 'c'. A configuration bar should pop up; if it does, everything works. You might try to load data into the RISimulator plug-in to test for correct visualization. If nothing shows up, press 'r' in order to reset the camera. Note that for the hot keys to work, the plug-in needs to be in focus.

\end{document}
