<commit_before>\chapter{Building Simple Applications with OTB}
\label{chap:Tutorials}

Well, that's it, you've just downloaded and installed OTB, lured by the promise
that you will be able to do everything with it. That's true, you will be able
to do everything but - there is always a {\em but} - some effort is required.

OTB uses the very powerful systems of generic programing, many classes are
already available, some powerful tools are defined to help you with recurrent
tasks, but it is not an easy world to enter.

These tutorials are designed to help you enter this world and grasp the logic
behind OTB. Each of these tutorials should not take more than 10 minutes (typing
included) and each is designed to highlight a specific point. You may not be
concerned by the latest tutorials but it is strongly advised to go through the
first few which cover the basics you'll use almost everywhere.


\section{Hello world}
\label{sec:TutorialHelloWorld}

\index{Hello World}

Let's start by the typical {\em Hello world} program. We are going to compile
this C++ program linking to your new OTB.

First, create a new folder to put your new programs (all the examples from this
tutorial) in and go into this folder.

Since all programs using OTB are handled using the CMake system, we need to create a
\code{CMakeLists.txt} that will be used by CMake to compile our program. An
example of this file can be found in the \code{OTB/Examples/Tutorials}
directory. The \code{CMakeLists.txt} will be very similar between your projects.

Open the \code{CMakeLists.txt} file and write in the few lines:


\begin{small}
\begin{verbatim}
PROJECT(Tutorials)

cmake_minimum_required(VERSION 2.6)

FIND_PACKAGE(OTB)
IF(OTB_FOUND)
  INCLUDE(${OTB_USE_FILE})
ELSE(OTB_FOUND)
  MESSAGE(FATAL_ERROR
      "Cannot build OTB project without OTB.  Please set OTB_DIR.")
ENDIF(OTB_FOUND)

ADD_EXECUTABLE(HelloWorldOTB HelloWorldOTB.cxx )
TARGET_LINK_LIBRARIES(HelloWorldOTB OTBCommon OTBIO)
\end{verbatim}
\end{small}


The first line defines the name of your project as it appears in Visual Studio
(it will have no effect under UNIX or Linux). The second line loads a CMake file
with a predefined strategy for finding OTB \footnote{Similar files are provided
in CMake for other commonly used libraries, all of them named
\code{Find*.cmake}}. If the strategy for finding OTB fails, CMake will prompt
you for the directory where OTB is installed in your system. In that case you
will write this information in the \code{OTB\_DIR} variable. The line \code{
INCLUDE(\$\{USE\_OTB\_FILE\})} loads the \code{UseOTB.cmake} file to set all the
configuration information from OTB.

The line \code{ADD\_EXECUTABLE} defines as its first argument the name of the
executable that will be produced as result of this project. The remaining
arguments of \code{ADD\_EXECUTABLE} are the names of the source files to be
compiled and linked.  Finally, the \code{TARGET\_LINK\_LIBRARIES} line specifies
which OTB libraries will be linked against this project.

\input HelloWorldOTB.tex

Once the file is written, run \code{ccmake} on the current directory
(that is \code{ccmake ./} under Linux/Unix). If OTB is
on a non standard place, you will have to tell CMake where it is. Once your
done with CMake (you shouldn't have to do it anymore) run \code{make}.

You finally have your program. When you run it, you will have the {\em OTB Hello
World !} printed.

Ok, well done! You've just compiled and executed your first OTB program. Actually,
using OTB for that is not very useful, and we doubt that you downloaded OTB only
to do that. It's time to move on to a more advanced level.


\section{Pipeline basics: read and write}
\label{sec:TutorialPipeline}

\index{Reader, Writer, Pipeline}

OTB is designed to read images, process them and write them to disk or
view the result. In this tutorial, we are going to see how to read and
write images and the basics of the pipeline system.

First, let's add the following lines at the end of the \code{CMakeLists.txt}
file:

\begin{small}
\begin{verbatim}
ADD_EXECUTABLE(Pipeline Pipeline.cxx )
TARGET_LINK_LIBRARIES(Pipeline OTBCommon OTBIO)
\end{verbatim}
\end{small}


Now, create a \code{Pipeline.cxx} file.

\input Pipeline.tex

Once this file is written you just have to run \code{make}. The
\code{ccmake} call is not required anymore.

Get one image from the \code{OTB/Examples/Data} directory in the OTB sources.
For example get \code{QB\_Suburb.png}.

Now, run your new program as \code{Pipeline QB\_Suburb.png output.png}. You
obtain the file \code{output.png} which is the same image as
\code{QB\_Suburb.png}. When you triggered the \code{Update()} method, OTB opened
the original image and wrote it back under another name.

Well\ldots that's nice but a bit complicated for a copy program!

Wait a minute! We didn't specify the file format anywhere! Let's try
\code{Pipeline QB\_Suburb.png output.jpg}. And voila! The output image is a jpeg
file.

That's starting to be a bit more interesting: this is not just a program to copy
image files, but also to convert between image formats.

You have just experienced the pipeline structure which executes the
filters only when needed and the automatic image format detection.

Now it's time to do some processing in between.


\section{Filtering pipeline}
\label{sec:TutorialFiltering}

\index{Filter, Pipeline}

We are now going to insert a simple filter to do some processing between the
reader and the writer.<commit_msg>DOC: fix reference to Examples/Data in software guide<commit_after>\chapter{Building Simple Applications with OTB}
\label{chap:Tutorials}

Well, that's it, you've just downloaded and installed OTB, lured by the promise
that you will be able to do everything with it. That's true, you will be able
to do everything but - there is always a {\em but} - some effort is required.

OTB uses the very powerful systems of generic programing, many classes are
already available, some powerful tools are defined to help you with recurrent
tasks, but it is not an easy world to enter.

These tutorials are designed to help you enter this world and grasp the logic
behind OTB. Each of these tutorials should not take more than 10 minutes (typing
included) and each is designed to highlight a specific point. You may not be
concerned by the latest tutorials but it is strongly advised to go through the
first few which cover the basics you'll use almost everywhere.


\section{Hello world}
\label{sec:TutorialHelloWorld}

\index{Hello World}

Let's start by the typical {\em Hello world} program. We are going to compile
this C++ program linking to your new OTB.

First, create a new folder to put your new programs (all the examples from this
tutorial) in and go into this folder.

Since all programs using OTB are handled using the CMake system, we need to create a
\code{CMakeLists.txt} that will be used by CMake to compile our program. An
example of this file can be found in the \code{OTB/Examples/Tutorials}
directory. The \code{CMakeLists.txt} will be very similar between your projects.

Open the \code{CMakeLists.txt} file and write in the few lines:


\begin{small}
\begin{verbatim}
PROJECT(Tutorials)

cmake_minimum_required(VERSION 2.6)

FIND_PACKAGE(OTB)
IF(OTB_FOUND)
  INCLUDE(${OTB_USE_FILE})
ELSE(OTB_FOUND)
  MESSAGE(FATAL_ERROR
      "Cannot build OTB project without OTB.  Please set OTB_DIR.")
ENDIF(OTB_FOUND)

ADD_EXECUTABLE(HelloWorldOTB HelloWorldOTB.cxx )
TARGET_LINK_LIBRARIES(HelloWorldOTB OTBCommon OTBIO)
\end{verbatim}
\end{small}


The first line defines the name of your project as it appears in Visual Studio
(it will have no effect under UNIX or Linux). The second line loads a CMake file
with a predefined strategy for finding OTB \footnote{Similar files are provided
in CMake for other commonly used libraries, all of them named
\code{Find*.cmake}}. If the strategy for finding OTB fails, CMake will prompt
you for the directory where OTB is installed in your system. In that case you
will write this information in the \code{OTB\_DIR} variable. The line \code{
INCLUDE(\$\{USE\_OTB\_FILE\})} loads the \code{UseOTB.cmake} file to set all the
configuration information from OTB.

The line \code{ADD\_EXECUTABLE} defines as its first argument the name of the
executable that will be produced as result of this project. The remaining
arguments of \code{ADD\_EXECUTABLE} are the names of the source files to be
compiled and linked.  Finally, the \code{TARGET\_LINK\_LIBRARIES} line specifies
which OTB libraries will be linked against this project.

\input HelloWorldOTB.tex

Once the file is written, run \code{ccmake} on the current directory
(that is \code{ccmake ./} under Linux/Unix). If OTB is
on a non standard place, you will have to tell CMake where it is. Once your
done with CMake (you shouldn't have to do it anymore) run \code{make}.

You finally have your program. When you run it, you will have the {\em OTB Hello
World !} printed.

Ok, well done! You've just compiled and executed your first OTB program. Actually,
using OTB for that is not very useful, and we doubt that you downloaded OTB only
to do that. It's time to move on to a more advanced level.


\section{Pipeline basics: read and write}
\label{sec:TutorialPipeline}

\index{Reader, Writer, Pipeline}

OTB is designed to read images, process them and write them to disk or
view the result. In this tutorial, we are going to see how to read and
write images and the basics of the pipeline system.

First, let's add the following lines at the end of the \code{CMakeLists.txt}
file:

\begin{small}
\begin{verbatim}
ADD_EXECUTABLE(Pipeline Pipeline.cxx )
TARGET_LINK_LIBRARIES(Pipeline OTBCommon OTBIO)
\end{verbatim}
\end{small}


Now, create a \code{Pipeline.cxx} file.

\input Pipeline.tex

Once this file is written you just have to run \code{make}. The
\code{ccmake} call is not required anymore.

Get one image from the \code{OTB-Data/Examples} directory from the OTB-Data
repository. You can get it either by cloning the OTB data repository 
(\code{hg clone http://hg.orfeo-toolbox.org/OTB-Data}), but that might be quite 
long as this also gets the data to run the tests. Alternatively, you can get it from 
\url{http://www.orfeo-toolbox.org/packages/OTB-Data-Examples.tgz}.
Take for example get \code{QB\_Suburb.png}.

Now, run your new program as \code{Pipeline QB\_Suburb.png output.png}. You
obtain the file \code{output.png} which is the same image as
\code{QB\_Suburb.png}. When you triggered the \code{Update()} method, OTB opened
the original image and wrote it back under another name.

Well\ldots that's nice but a bit complicated for a copy program!

Wait a minute! We didn't specify the file format anywhere! Let's try
\code{Pipeline QB\_Suburb.png output.jpg}. And voila! The output image is a jpeg
file.

That's starting to be a bit more interesting: this is not just a program to copy
image files, but also to convert between image formats.

You have just experienced the pipeline structure which executes the
filters only when needed and the automatic image format detection.

Now it's time to do some processing in between.


\section{Filtering pipeline}
\label{sec:TutorialFiltering}

\index{Filter, Pipeline}

We are now going to insert a simple filter to do some processing between the
reader and the writer.
{'fraction_non_alphanumeric': 0.06363234644277507, 'fraction_numerical': 0.0007070260715863897, 'mean_word_length': 4.419540229885057, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 3, 'https://': 0, 'lorem ipsum': 0, 'www.': 1, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 4, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '1187897', 'n_tokens_mistral': 3400, 'n_tokens_neox': 3191, 'n_words': 1664}