\documentclass[english, 10pt, a4paper,headsepline]{scrbook}
\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}
\include{version}
\include{definitions}
%\makeatletter
\definecolor{listinggray}{gray}{0.9}
\lstset{backgroundcolor=\color{listinggray}}
\makeatother
\begin{document}
\vfill{}
\title{MIA User and Programming Guide \\Software Version: \miaversion}
\vfill{}
\date{01. March 2007}
\author{Gert Wollny}
\maketitle
\chapter*{Preface}
This is the MIA User and Programming Guide.
It is dedicated how to use the tools provided by MIA and how to develop software based on the infrastructure provided by MIA.
\section*{License}
Copyright (c) 2007 Gert Wollny.
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
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}
This is the MIA Programming Guide. This document describes, how mia can be installed and used to
write software.
This document is maintained by Gert Wollny <gert.wollny@acm.org>.
Additions, modifications or corrections may be mailed there for inclusion in the next release.
\section{Installation}
MIA has been tested on a variety of Platforms, namely GNU/Linux (x86), Max OS X Tiger (PowerPC), and MS Windows (32 Bit).
It provided interfaces to Mathworks MatLab(tm) and ITT Visual Information Solutions IDL.
\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 - GNU g++ (>=3.3) (http://gcc.gnu.org) is known to work.
\item CMake (http://www.cmake.org)
\item The BOOST >= 1.34 (http://www.boost.org) library
\end{enumerate}
Additionally, the following packages add to the functionallity of the software:
\begin{description}
\item [OpenEXR:] A HDR Image Library that supports 32 bit and floating point valued images (http://www.openexr.org)
\item [TIFF:] The Tagged Image File Format (http://www.remotesensing.org/libtiff/libtiff.html)
\item [PNG:] Portable Network Graphics (http://www.libpng.org)
\end{description}
Interfaces to MatLab and IDL are only build, when the according software package is installed.
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.0.tgz
mkdir build-mia
cd build-mia
cmake -DCMAKE
_INSTALL
_PREFIX=<path to install> ../mia-2.0.0
make
make install
\end{lstlisting}
In order to test some of the components, you may run ``make test''.
\subsection{MS Windows}
An installation package is provided based on the Nullsoft Scriptable Install System (NSIS).
One can just run it and install MIA to the desired location.
If you decide to compile MIA be yourself, it has so far only been tested by using Microsoft Visual Studio 2008 (Servicepack 1).
Unpack the source code, and run CMakeSetup on the root CMakeLists.txt.
Select ``NMake Makefiles'' as target and generate the build files.
Compiling is then done in a command shell by first initialising the Visual Studio build environment by runninng the
``...VC\\bin\\vcvarsXX.bat and then typing ``nmake package''.
This will create an installation package that then can be installed like given above.
Running the installation is a requirement, since some registration keys are generated.
\part{User Guide}
\include{running}
\include{idl}
\include{matlab}
\part{Program and Plug-in Reference}
\include{programs}
\include{plugins}
\part{Programming Guide}
This part of the MIA guide decribes, how to use the interfaces provided to write your own softwrae,
how to extend the the functionallity of MIA without touchting its core, and, finally, how to
change MIA itself.
\begin{itemize}
\item In chapter \ref{ch:simple} an example is provided, that describes how to scan the command line, load an image,
run some given filters on it and store the image.
\item Chapter \ref{ch:images} focuses images on writing an image filter that can handle various different gray scale pixel formats.
\item Chapter \ref{ch:io} decribes how to teach MIA to read and write additional image formats.
\item Chapter \ref{ch:filterplugin} will teach you, how to write an image filter plugin.
\item Chapter \ref{ch:addpluginstype} gives an insight how to create a new class of plug-ins.
\end{itemize}
\chapter{A simple program}
\label{ch:simple}
This chapter will teach you how to use the MIA-tools to scan command line parameters, read and store images,
create filters opbejcts from plug-ins and apply filter chains to the images.
In summary, the program described here is the \texttt{mia-2dimagefilter} from \texttt{src/2dimagefilter.cc}.
\section{The setup}
In this program we will with 2D images, therefore the program needs to include and in implementation files
(not in the header files \cite{sutter04coding}) we add some {\bf use} directives:
\lstset{language=c++}
\begin{lstlisting}
#include <mia/core.hh>
#include <mia/2d.hh>
NS_MIA_USE;
using namespace std;
\end{lstlisting}
To prepare the command line scanning, a few variables need to be defined at the beginning of the main function, and
the option set needs to be prepared:
\begin{lstlisting}
int main( int argc, const char *argv[] )
{
string in_filename;
string out_filename;
string out_type;
bool help_plugins = false;
try {
const C2DFilterPluginHandler::Instance& filter_plugins =
C2DFilterPluginHandler::instance();
const C2DImageIOPluginHandler::Instance& imageio =
C2DImageIOPluginHandler::instance();
CCmdOptionList options;
options.push_back(make_opt( in_filename, "in-file", 'i',
"input image(s) to be filtered", "input", true));
options.push_back(make_opt( out_filename, "out-file", 'o',
"output image(s) that have been filtered", "output", true));
options.push_back(make_opt( out_type, imageio.get_set(), "type", 't',
"output file type "
"(if not given deduct from output file name)" ,
"image-type"));
options.push_back(make_opt( help_plugins, "help-plugins", 0,
"give some help about the filter plugins", NULL));
...
}
catch ...
\end{lstlisting}
So let's have a look at the code:
First, the whole code is put in a try-catch block, since all of the errors in the
library are signalled by exceptions.
We certainly need to know about the input and the output file names.
The output file type might be forced, but usually it is not necessary, since the suffix of the output file name
will be used to pick the proper output file type.
Note, the out\_type options is provided with the set of available output plug-ins, so as to check the command line value.
Since the image filters are provided dynamically, via plug-ins, one might want to know a little more about what is
available and how should it be called.
Therefore, a boolean option \texttt{help\_plugins} is given as well.
Silently, in the background are some more options available, that deal with common tasks, such as printing out the general
help, printing out copyright information, and verbosity level of the output.
See chapter \ref{ch:prog} for details.
Now we are ready to parse the command line:
\begin{lstlisting}
options.parse(argc, argv);
vector<const char *> filter_chain = options.get_remaining();
\end{lstlisting}
\texttt{filter\_chain} collects all the command line parameters that do not belong to a named option.
As a result, the command
\lstset{language=bash}
\begin{lstlisting}
eva-2dimagefilter -i input.png -o output.png downscale:bx=2,by=2 bandpass:min=20,max=200
\end{lstlisting}
will be parsed like follows:
\lstset{language=c++}
\begin{itemize}
\item \texttt{in\_filename} = ``input.png''
\item \texttt{out\_filename} = ``output.png''
\item \texttt{filter\_chain} = (downscale:bx=2,by=2, bandpass:min=20,max=200)
\end{itemize}
After checking the validy of the given command line parameters, the input image can be loaded and,
of cource checked, whether there is actually an image:
\lstset{language=c++}
\begin{lstlisting}
C2DImageIOPluginHandler::PData in_image_list = imageio.load(in_filename);
if (!in_image_list || in_image_list->empty())
throw invalid_argument(string("No images found in ") + in_filename);
\end{lstlisting}
Image files may contain several images.
Therefore the return value \texttt{C2DImageIOPluginHandler::PData} is actually a vector of images.
The exact type is:
\begin{lstlisting}
C2DImageIOPluginHandler::PData =
::boost::shared_ptr<std::vector<::boost::shared_ptr<C2DImage> > >
\end{lstlisting}
Now the filter chain can be build from the descriptions given on the command line quite straight forward:
\begin{lstlisting}
list<C2DFilterPlugin::ProductPtr> filters;
for (vector<string>::const_iterator i = filter_chain.begin();
i != filter_chain.end(); ++i) {
C2DFilterPlugin::ProductPtr filter = filter_plugins.produce(i->c_str());
if (!filter){
stringstream error;
error << "Filter " << *i << " not found";
throw invalid_argument(error.str());
}
filters.push_back(filter);
}
\end{lstlisting}
Given the images and the filter chain, the latter can now be applied to the first, which is really
only a nested loop.
Note, the use of shared pointers makes it possible to store the filter result at the location
without thinking about memory leaks.
\begin{lstlisting}
std::vector<string>::const_iterator filter_name = filter_chain.begin();
for (std::list<C2DFilterPlugin::ProductPtr>::const_iterator f = filters.begin();
f != filters.end(); ++f) {
for (C2DImageIOPluginHandler::Data::iterator
i = in_image_list->begin(); i != in_image_list->end(); ++i)
*i = (*f)->filter(**i);
}
\end{lstlisting}
After the filtering, the result just needs to be saved and we are done.
\begin{lstlisting}
if ( !imageio.save(out_type, out_filename, *in_image_list) )
throw runtime_error(string("unable to save result to ") + out_filename);
return EXIT_SUCCESS;
\end{lstlisting}
The cleanup code catches possible exceptions and signals those to the user before exiting with a failure:
\begin{lstlisting}
catch (const runtime_error &e){
cerr << argv[0] << " runtime: " << e.what() << endl;
}
catch (const invalid_argument &e){
cerr << argv[0] << " error: " << e.what() << endl;
}
catch (const exception& e){
cerr << argv[0] << " error: " << e.what() << endl;
}
catch (...){
cerr << argv[0] << " unknown exception" << endl;
}
return EXIT_FAILURE;
}
\end{lstlisting}
This frame of a program describes, how the library can be used.
\chapter{Images and Filtering}
\label{ch:images}
In the following, the basic handling of images is described.
All the examples will use 2D images.
If not otherwise noted, 3D images are handled likewise.
\section{How to create and copy images of a certain image type}
The images supported in MIA may contain different pixel types, e.g. 1-bit, 8-bit, 16-bit, or even float valued ones.
MIA uses shared pointers to \texttt{C2DImage}, respectively, to hold images.
However, in order to account for the pixel type, at creation time a derivative class of the used pixel type needs to be specified.
In order to create an 16-bit image with unsigned pixel values with a given \texttt{size}, use:
\begin{lstlisting}
P2DImage image = P2DImage(new C2DUSImage(size));
\end{lstlisting}
In order to copy such an image, an image copy filter is provided, that can be invoked like follows:
\begin{lstlisting}
P2DImage image_copy = filter<T2DImage>(FCopyImage(), image);
\end{lstlisting}
\emph{Remark: a clone method might come in handy ...}
More about these image filters is described in the next section:
\section{An Image Filter}
\label{sec:filter}
In order to access the image data, its type needs to be known.
Of course it is possible to use the \texttt{get\_type} method of the \texttt{C2DImage} class and use
a switch statement in order to cast to the appropriate derived class.
However, since this needs to be done very often, MIA provides various template functions to handle the most cases
of image access.
Namely, functions \texttt{mia::filter} are provided that take a filter functor as argument as well as one image or two images.
Examples of its usage follow:
Imagine, an image thresh-holding filter, that takes an image, and sets all pixels above or below given thresholds to zero, and
all pixels within the range to one.
Such a filter would be defined like follows:
\begin{lstlisting}
#include <mona/core/filter.hh>
struct FThreshold: public TFilter<P2DImage> {
FThreshold(double min, double max):
_M_min(min),
_M_max(max)
{
}
typename <template T>
FThreshold::result_type operator()(const T2DImage<T>& image)const {
typename T2DImage<T>::const_iterator ii = image.begin();
typename T2DImage<T>::const_iterator ei = image.end();
C2DBitImage *r = new C2DBitImage(image.get_size(), image.get_attribute_list());
P2DImage result(r);
C2DBitImage::iterator ir = r->begin();
while (ii != ei) {
*ir++ = (*ii >= _M_min && *ii < _M_max);
++ii;
}
return result;
}
private:
double _M_min;
double _M_max;
);
\end{lstlisting}
Here, \texttt{TFilter} is a template, that defines the type \texttt{return\_type} that is needed for the call to the actual filter function.
The constructor of the filter functor \texttt{FThreshold} initialises the filter with the given parameters.
A \texttt{do\_threshold} function that makes use of this filter operator would look like this:
\begin{lstlisting}
P2DImage do_threshold(double min, double max, const C2DImage& image)
{
return mia::filter<T2DImage>(FThreshold(min,max), image);
}
\end{lstlisting}
The \texttt{filter<T2DImage>} function takes care of casting the input image depending on its pixel type, and then invokes
the operator () of \texttt{FThreshold} and returns its result.
\section{Pixel Type Dependant Filtering}
\label{sec:ptdf}
Imaging the situation, when a filter type is only appropriate for certain pixel types, or should behave differently for different
pixel types.
Then using template specification comes to the rescue.
Imagine, for example, in the above example, using the thresh-holding filter on a bit-valued image doesn't make much sense.
Therefore, we would like to report an error, if the filter is invoked with an bit valued image.
This can be done by additionally implementing a specialisation of the operator () of \texttt{FThreshold}:
\emph{I think another indirection is needed here ...}
\begin{lstlisting}
template <>
FTreshold::result_type FTreshold::operator(const C2DBitImage& image)const
{
throw invalid_argument("FTreshold can not be used on bit-valued images");
}
\end{lstlisting}
The compiler will take care of the rest, and if the user provides a bit valued image the above exception will be raised.
\chapter{Data IO}
\label{ch:io}
\section{Loading/Storing data}
\label{sec:lsd}
Loading and storing data in mia is done by using a common interface for all data types.
\section{Preparing for a new data type IO}
\label{sec:adddatatypeio}
\section{Adding a new IO plugin file type}
\label{sec:newfilehandler}
\chapter{Writing an Image Filter Plugin}
\label{ch:filterplugin}
\chapter{Adding a new general plugin type}
\label{ch:addpluginstype}
\bibliographystyle{plainnat}
\cleardoublepage\addcontentsline{toc}{chapter}{\bibname}
\bibliography{userguide}
\end{document}