%% LyX 1.3 created this file. For more info, see http://www.lyx.org/.
%% Do not edit unless you really know what you are doing.
\documentclass[english, 10pt, a4paper]{book}
\usepackage[T1]{fontenc}
\usepackage[latin1]{inputenc}
\usepackage[left=2cm,right=1cm,top=1cm,bottom=1cm,twoside]{geometry}
\usepackage{array}
\usepackage{amsmath}
\usepackage{amssymb}
\usepackage[numbers]{natbib}
\usepackage{listings}
\usepackage{color}
\include{version}
\newcommand{\libmona}{\emph{libmona}}
%\makeatletter
\definecolor{listinggray}{gray}{0.9}
\lstset{backgroundcolor=\color{listinggray}}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% LyX specific LaTeX commands.
%% Because html converters don't know tabularnewline
\usepackage{babel}
\makeatother
\begin{document}
\vfill{}
\title{\libmona Programming Guide \\Software Version: \libmonaversion}
\vfill{}
\date{11. July 2006}
\author{Gert Wollny}
\maketitle
This is the libmona Programming Guide.
It is dedicated how to write software based on the infrastructure provided by libmona.
\tableofcontents{}
\chapter*{Preface}
\section*{License}
Copyright (c) 2006 Gert Wollny, MPI for Evolutionary Anthropology
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}{|c|c|}
\hline
Date & Description of changes\\
\hline
\hline
11/07/2006 & Initial Release\\
\hline
\end{tabular}
\end{center}
\chapter{Introduction}
\libmona is a library that provides support to implement programs for 2D and 3D image processing of gray scale images.
Mainly it provides the following interfaces:
\begin{itemize}
\item command line option processing based on the POPT library \cite{popt}
\item 2D and 3D data containers
\item basic support for 3D triangular meshes
\item a general plug-in infrastructure
\item a 2D and 3D image IO plug-in infrastructure
\item a 2D and 3D image processing plug-in infrastructure
\end{itemize}
Additionally, it provides implementations for
\begin{itemize}
\item various 3D image IO plugins
\item various 3D image processing algorithms
\item various 3D triangular mesh IO plugins
\end{itemize}
Remark:These implementations will most probable be moved to another package.
\section{Using the Library}
\subsection{Command Line Options}
The command line option processing is based on the POPT library \cite{popt}.
Additions to POPT are implemented for a more easy use.
The following parameters are supported at the command line:
\begin{itemize}
\item flags (boolean options)
\item strings, integers, float, and double values
\item vectors of strings, integers, floats, and doubles
\item dictionary options
\end{itemize}
Additionally, each program, that makes use of the \libmona command line parsing supports the following options and the user doesn't have to take care
to implement these herself:
\begin{itemize}
\item --help | -? \t prints out some help
\item --usage \t prints out some short usage information
\item --version | -v \t prints out some library version information
\item --copyright \t prints out copyright information
\item --verbose |-V \t output verbosity
\end{itemize}
Defining an option table and using it can be done like follows:
Include the apropriate header file:
\lstset{language=c++}
\begin{lstlisting}
#include <libmona/monaPopt.hh>
\end{lstlisting}
Given the constructor for the options
\begin{lstlisting}
template <class T>
option(T &value, const char *LongOption, char ShortOption, const char *HelpStr, const char *DefaultValue);
\end{lstlisting}
end the specialisation for (boolean) flags
\begin{lstlisting}
option(bool &value, const char *LongOption, char ShortOption, const char *HelpStr);
\end{lstlisting}
a definition of the option table in the main function may looks like follows:
\begin{lstlisting}
int main(int argc, char *args[])
{
\ldots
std::string SomeString;
int SomeInteger;
float SomeFloat;
bool SomeFlag;
popt::COptions opts;
opts.push_back(popt::option( SomeString, "string", 's', "some string option", "default"));
opts.push_back(popt::option( SomeInteger, "int", 'i', "some int option", "42"));
opts.push_back(popt::option( SomeFloat, "float", 'f', "some float option", "3.1415926"));
opts.push_back(popt::option( SomeFlag, "flag", 'g', "some flag option"));
\ldots
\end{lstlisting}
In order to parse the command line invoke.
\begin{lstlisting}
std::vector<string> UnknownOptions;
popt::parse_options(argc, args, opts, non_UnknownOptions);
\end{lstlisting}
After parsing the command line, all values are set either to the value given at the command line, or to the default value
given at option definition time.
Boolen values always default to \emph{false} and are set to \emph{true} if the flag is given on the command line.
Command line arguments, that are not known from the optiopn table or do not belong to the predefined list of options are
stored in {\ttt UnknownOptions}.
Assume the above program is called {\ttt mona-useoptions}, then it will now support the following options:
\lstset{language=bash}
\begin{lstlisting}
mona-useoptions --help
Usage: mona-useoptions [OPTION...]
-s, --string=default some string option
-i, --int=42 some int option
-f, --float=3.1415926 some float option
-g, --flag some flag option
-V, --verbose=error verbosity of output
(debug|message|warning|error|fail|fatal)
Info options:
-v, --version show version
--copyright show copyright
Help options:
-?, --help Show this help message
--usage Display brief usage message
\end{lstlisting}
Assume now, you want to use a set of named values for a certain option, like, e.g. used by the {\ttt verbose} option.
Then you will have to define a dictionary that is then passed to the option constructor:
\lstset{language=c++}
\begin{lstlisting}
\ldots
enum EOperation {opAnd, opOr, opXor};
const popt::option::Dictionary CombineOption[] = {
{"and", opAnd},
{"or", opOr},
{"xor", opXor},
{NULL, 0},
};
int Combiner;
options.push_back(popt::option( Combiner, CombineOption, "op", 0, "combine operator", "and"));
\end{lstlisting}
The list of possible values is automatically added to the output of the help option.
\subsection{Working with images}
%\bibliographystyle{plainnat}
%\cleardoublepage\addcontentsline{toc}{chapter}{\bibname}\bibliography{guide}
\end{document}