
\documentclass[english, 10pt, a4paper,headsepline,openany]{book}
\usepackage[T1]{fontenc}
\usepackage[latin1]{inputenc}
\usepackage[left=2cm,right=1cm,top=2cm,bottom=2cm,twoside]{geometry}
\usepackage{array}
\usepackage{amsmath}
\usepackage{amssymb}
\usepackage[numbers]{natbib}
\usepackage{listings}
\usepackage{color}
\usepackage{graphics}
\usepackage{nonfloat}
\usepackage{babel}
\usepackage[colorlinks,linkcolor=blue]{hyperref}
\usepackage{multirow}
\usepackage{ifthen}
\usepackage{tabularx}
\usepackage{rotating}
\usepackage{colortbl}
\newcommand{\has}{\cellcolor[gray]{0.5}X}

\include{version}
\include{definitions}

%\makeatletter
\definecolor{listinggray}{gray}{0.9}
\lstset{backgroundcolor=\color{listinggray}}


\makeatother

\begin{document}

\vfill{}
\title{MIA User Guide \\Software Version: \miaversion}
\vfill{}


\author{Gert Wollny}

\maketitle

\section*{Preface}

This is the \emph{MIA User Reference}. 
In this document you will find descriptions for all the programs and plug-ins currently included in the 
  MIA software package. 
This document is maintained by Gert Wollny <gw.fossdev@gmail.com>. 
Additions, hints, modifications, and corrections are welcome. 

\section*{License}

Copyright (c) Leipzig, Madrid 1999-2011, Gert Wollny <gw.fossdev@gmail.com>
Permission is granted to copy, distribute and/or modify this document under the terms of the 
  GNU Free Documentation License, Version 1.1 or any later version published by the 
  Free Software Foundation; with no Invariant Sections, 
  with no Front-Cover Texts and with no Back-Cover Texts. 
A copy of the license is available at http://www.gnu.org/copyleft/fdl.html

\section*{Changes}

\begin{center}
\begin{tabular}{cc}
\hline 
Date  & Description\\
\hline
\hline 
01/09/2011 & Second Public Release  \\
01/10/2007 & First Public Release  \\
01/03/2007 & Second Beta \\
13/06/2007 & First Beta  \\
\hline
\end{tabular}
\end{center}

\tableofcontents{}

\pagestyle{headings}


\chapter{Introduction}

MIA is a library and a collection of command line programs for gray scale image processing. 
It's main focus is on research in image processing.
For that reason some of the programs are of a rather experimental nature and partially 
   duplicate funcionality. 
Nevertheless, the funcionality that is provided by the libraries and plug-ins is developed 
  using \emph{test driven development} to ensure reproducability of the results.
 


\section{Installation}

MIA has been tested on GNU/Linux (x86,amd64) but should be installable on any Posix compatible platform. 


\subsection{UNIX, Linux, Mac OS X} 

In order to use MIA, on these platforms the software is best installed from source code. 
To do so, your software environment has to meet the following pre-requisites: 

\begin{enumerate}
\item You need a ANSI-compatible C++ compiler that supports some features of the C++2011 standard 
        -- GNU g++ ($\ge 4.5$) \url{http://gcc.gnu.org} is known to work. 
\item Intel Threading Building Blocks for Open Source ($\ge 3.0$) \url{http://threadingbuildingblocks.org/} 
\item CMake \url{http://www.cmake.org}
\item The BOOST >= 1.46.1 \url{http://www.boost.org} library
\item gsl The GNU Scientific Library \url{http://www.gnu.org/software/gsl/}
\item A library that provides the CBLAS interface, e.g. ATLAS \url{http://math-atlas.sourceforge.net/}.
\item The Intel Threading Building Blocks \url{http://threadingbuildingblocks.org/}
\end{enumerate}

\noindent 
Additionally, packages listed in Table \ref{tab:external} add to the functionallity of the software, 
   if available and enabled.

\begin{table}[h]
\caption{\label{tab:external}Supported external packages}
\begin{tabularx}{\linewidth}{lX}
\hline 
{\bf Package } & {\bf Additional information} \\
\hline 
\hline 
{ OpenEXR } & A HDR Image Library that supports 32 bit and floating point valued 
                 images \url{http://www.openexr.org} \\
\hline 
{ TIFF } & The Tagged Image File Format \url{http://www.remotesensing.org/libtiff/libtiff.html} \\
\hline 
{ PNG } & Portable Network Graphics \url{http://www.libpng.org} \\
\hline 
{ DCMTK } & DICOM image IO (partial support) \url{http://dicom.offis.de/dcmtk} \\
\hline 
{ nlopt } & Nonlinear optimizers library  \url{http://ab-initio.mit.edu/wiki/index.php/NLopt} \\
\hline 
{ it++ } & Signal processing library \url{http://itpp.sourceforge.net}  \\
\hline 
{ xml++ } & Input/output of XML files, support for certain segmentation features \url{http://libxmlplusplus.sourceforge.net/} \\
\hline 
{ fftw } & Fast Fourier Transformation \url{http://www.fftw.org}  \\
\hline 
\end{tabularx}
\end{table}

If all of the above pre-requisites are met, the installation of MIA boils down to:

\lstset{language=bash}
\begin{lstlisting}
  tar -zxvf mia-2.0.X.tgz
  mkdir build
  cd build
  cmake -DCMAKE_INSTALL_PREFIX=<path to install> ../mia-2.0.X
  make
  make install
\end{lstlisting}
In order to test some of the components, you may run ``make test''. 

\subsection{MS Windows} 

Currently broken, may work with cygwin. 

\subsection{Creating the documentation} 

In order to create the documentation, a working installation of Doxygen \url{http://www.doxygen.org/}, 
  LaTeX \url{http://www.latex-project.org/}, and Python \url{http://www.python.org/} is required. 

With these pre-requisites, the documentation, including this document and the library reference, 
  can be build after configuring the build environment of MIA as given above by running: 
\lstset{language=bash}
\begin{lstlisting}
  cd build/doc 
  make doc 
\end{lstlisting}
 
The equivalent of this document is created as \emph{userguide.pdf}. 

\chapter{User Reference}


In its essence, MIA is a collection of command line programs and supporting plug-ins. 


\section{Image and pixel formats}

The MIA library operates exclusively on gray scale and binary images. 
The supported pixel formats are given in Table \ref{tab:pixform}. 

\begin{table}[h]
\caption{\label{tab:pixform}Supported pixel formats}
\begin{tabular}{lrr}
Short name & C data type & size in bit \\
\hline 
\hline 
bit    & bool          & 1  \\
\hline 
sbyte  & signed char   & 8  \\ 
\hline 
ubyte  & unsigned char & 8  \\ 
\hline 
sshort & signed short  & 16 \\
\hline 
ushort & unsigned short& 16 \\
\hline 
sint   & signed int    & 32 \\
\hline 
uint   & unsigned int  & 32 \\
\hline 
float  & float         & 32 \\
\hline 
double & double        & 64 \\
\hline 
\end{tabular}
\end{table}

The supported file formats depend, in part, on the external libraries that were enabled during build time. 
Table \ref{tab:fileformats} lists all file formats can can be enabled. 

\begin{table}[h]
\caption{\label{tab:fileformats}Supported image file formats}
\begin{tabular}{lll|c|c|c|c|c|c|c|c|c|c}
          &     &  & \multicolumn{9}{c|}{\bf Supported pixel types} & \\

{\bf Format}    &  {\bf Extension }    &  {\bf Depends} & \ventry{bit} & \ventry{sbyte} & \ventry{ubyte} & \ventry{sshort} 
                                             & \ventry{ushort} & \ventry{sint} & \ventry{uint} & \ventry{float} 
                                             & \ventry{double} & \ventry{multi-}-\ventry{record} \\
\hline 
\hline 
\multicolumn{3}{l}{\bf 2D image files types} & \multicolumn{9}{l}{} & \\
\hline 
Windows bitmap            & bmp &            & \has &    &\has &    &\has &    &    &   &   &   \\
\hline 
Internal storage          & @   &            &\has& \has&\has &\has &\has &\has &\has &\has&\has&   \\
\hline 
DICOM                     & dcm & dcmtk      &   &    &    &\has &    &    &    &   &   &   \\
\hline 
OpenExr                   & exr & openexr    &   &    &    &    &    &    &\has &\has&   &\has\\
\hline 
Portable Network Graphics & png & libpng     &\has&    &\has &    &\has &    &    &   &   &   \\
\hline 
Raw data (output)         & raw &            &\has&\has &\has &\has &\has &\has &\has &\has&\has&   \\
\hline 
Tagged Image File Format  & tif, tiff & tiff &\has&    &\has &    &\has &    &    &   &   &\has\\
\hline 
Vista file format         & v   &            &\has&\has &\has &\has &    &\has &    &\has&\has&\has\\
\hline 
\multicolumn{3}{l}{\bf 3D image files types} & \multicolumn{9}{l}{} &\\
\hline 
Analyze                   & hdr+img  &       &   &    &\has &\has &    &\has &    &\has&\has&\has\\
\hline 
DICOM (as series of files)& dcm & dcmtk      &   &    &    &\has &    &    &    &   &   &   \\
\hline 
INRIA 3D File format      &     &            &   &\has &\has &\has &\has &\has &\has &\has&\has&   \\
\hline 
Internal storage          & @   &            &\has& \has&\has &\has &\has &\has &\has &\has&\has&   \\
\hline 
Sun TAAC Image File Format& vff &            &   &    &\has &\has &    &    &    &   &   &   \\
\hline 
Vista file format         & v   &            &\has&\has &\has &\has &    &\has &    &\has&\has&\has\\
\hline 
\end{tabular}
\end{table}



%\include{running}

\chapter{Programs}
\label{ch:prog}

\lstset{language={}}

This chapter lists all the software tools provided by mia. 
The descriptions follow a designated pattern: 

\subsection*{The command line program name}
\begin{description}
\item [Description:]A description of the program
\item [Options:] list of options

\noindent 
\optiontable{
long name & short name & value type & description of the parameter \\
\hline
}

\noindent 
If no value type is given, then the option is a flag that defaults to \emph{false} and accepts no 
     further value. 
All programs support the following options: 

\optiontable{
\cmdopt{help}{h}{}{Print out some help}
\cmdopt{usage}{?}{}{Print out a short help}
\cmdopt{version}{v}{}{Print out version information}
\cmdopt{copyright}{}{}{Print out copyright information}
\cmdopt{verbose}{V}{string}{set the verbosity of the output out of (debug, message, warning, fail, error, fatal)}
}

\item [Example:] Example how to run the program 

\item [Remarks:] additional notes
\item [See also:] Cross reference to related programs. 
\end{description}

For all programs, the \texttt{-{}-help} option will print out additional information, like which parameters 
  are required and what are the default values (if set).
Note, when other options are set alongside the \texttt{-{}-help} option, then for these options, the given value 
  will be shown as default and the \emph{required} tag will not be shown.
When a program is called with two (or more) conflicting options then one option takes automatically 
  precedence as it is documented. 

\subsection*{An additional note for setting command line options}

Option values that belong to one option \emph{must not} contain whitespace characters, otherwise, 
  the command line parser will seperate the parts. 
As an alternative, the command line parameter may be protected by quotes or double quotes. 
Note, however, when you give free parameters by using ``?'' or ``*'' to use the shell expansion to indicate 
  more then one file, quoting the parameter will inhibit parameter expansion, and internally, all programs 
  take the letters ``?'' and ``*'' literal. 
Also note, that some options require the use of the charaters ``<'' and ``>''. 
Since these letters are also interpreted by the shell, the parameters using these characters must be 
  protected by quotes.

\include{programs}

\chapter{Plug-ins}
\label{ch:plugins}

In this chapter the plug-ins are described that are provided by the library.
\include{plugins}

\bibliographystyle{plainnat}
\cleardoublepage\addcontentsline{toc}{chapter}{\bibname}
\bibliography{userguide}

\end{document}
