Chapter 1
Welcome

Welcome to the ORFEO ToolBox (OTB) Software Guide.

This document presents the essential concepts used in OTB. It will guide you through the road of learning and using OTB. The Doxygen documentation for the OTB application programming interface is available on line at https://www.orfeo-_toolbox.org/doxygen.

1.1 Organization

This software guide is divided into several parts, each of which is further divided into several chapters. Part I is a general introduction to OTB, with—in the next chapter—a description of how to install the ORFEO Toolbox on your computer. Part I also introduces basic system concepts such as an overview of the system architecture, and how to build applications in the C++ programming language. Part II is a short guide with gradual difficulty to get you start programming with OTB. Part III describes the system from the user point of view. Dozens of examples are used to illustrate important system features. Part IV is for the OTB developer. It explains how to create your own classes and extend the system.

1.2 How to Learn OTB

There are two broad categories of users of OTB. First are class developers, those who create classes in C++. The second, users, employ existing C++ classes to build applications. Class developers must be proficient in C++, and if they are extending or modifying OTB, they must also be familiar with OTB’s internal structures and design (material covered in Part IV).

The key to learning how to use OTB is to become familiar with its palette of objects and the ways of combining them. We recommend that you learn the system by studying the examples and then, if you are a class developer, study the source code. Start by the first few tutorials in Part II to get familiar with the build process and the general program organization, follow by reading Chapter 3, which provides an overview of some of the key concepts in the system, and then review the examples in Part III. You may also wish to compile and run the dozens of examples distributed with the source code found in the directory OTB/Examples. (Please see the file OTB/Examples/README.txt for a description of the examples contained in the various subdirectories.) There are also several hundreds of tests found in the source distribution in OTB/Testing/Code, most of which are minimally documented testing code. However, they may be useful to see how classes are used together in OTB, especially since they are designed to exercise as much of the functionality of each class as possible.

1.3 Software Organization

The following sections describe the directory contents, summarize the software functionality in each directory, and locate the documentation and data.

1.3.1 Obtaining the Software

Periodic releases of the software are available on the OTB Website. These official releases are available a few times a year and announced on the ORFEO Web pages and mailing lists.

This software guide assumes that you are working with the latest official OTB release (available on the OTB Web site).

OTB can be downloaded without cost from the following web site:

http://www.orfeo-_toolbox.org/

In order to track the kind of applications for which OTB is being used, you will be asked to complete a form prior to downloading the software. The information you provide in this form will help developers to get a better idea of the interests and skills of the toolkit users.

Once you fill out this form you will have access to the download page. This page can be book marked to facilitate subsequent visits to the download site without having to complete any form again.

Then choose the tarball that better fits your system. The options are .zip and .tgz files. The first type is better suited for MS-Windows while the second one is the preferred format for UNIX systems.

Once you unzip or untar the file, a directory called OTB will be created in your disk and you will be ready for starting the configuration process described in Section 2.

There are two other ways of getting the OTB source code:

These last two options need a proper Git installation. To get source code from Git, do:

git clone https://gitlab.orfeo-toolbox.org/orfeotoolbox/otb.git

Using Git, you can easily navigate through the different versions. The master branch contains the latest stable version:

git checkout master

Specific versions are availables with tags:

git checkout 5.2.0

Finally, this brings you to the latest development version:

git checkout develop

There is also a mirror of OTB official repository on GitHub. You can find more information on the OTB git workflow in the wiki.

1.3.2 Directory Structure

To begin your OTB odyssey, you will first need to know something about OTB’s software organization and directory structure. It is helpful to know enough to navigate through the code base to find examples, code, and documentation.

The OTB contains the following subdirectories:

OTB is organized into different modules, each one covering different part of image processing. It is therefore important to understand the source code directory structure—found in OTB/Modules—.

See also chapter 31 for more information about how to write modules.

1.3.3 Documentation

Besides this text, there are other documentation resources that you should be aware of.

Doxygen Documentation.
The Doxygen documentation is an essential resource when working with OTB. These extensive Web pages describe in detail every class and method in the system. The documentation also contains inheritance and collaboration diagrams, listing of event invocations, and data members. The documentation is heavily hyper-linked to other classes and to the source code. The Doxygen documentation is available on-line at http://www.orfeo-_toolbox.org/doxygen/.
Header Files.
Each OTB class is implemented with a .h and .cxx/.txx file (.txx file for templated classes). All methods found in the .h header files are documented and provide a quick way to find documentation for a particular method. (Indeed, Doxygen uses the header documentation to produces its output.)

1.3.4 Data

The OTB Toolkit was designed to support the ORFEO Acompaniment Program and its associated data. This data is available at http://smsc.cnes.fr/PLEIADES/index.htm.

1.4 The OTB Community and Support

1.4.1 Join the Mailing List

It is strongly recommended that you join the users mailing list. This is one of the primary resources for guidance and help regarding the use of the toolkit. You can subscribe to the users list online at

http://groups.google.com/group/otb-_users

The otb-users mailing list is also the best mechanism for expressing your opinions about the toolbox and to let developers know about features that you find useful, desirable or even unnecessary. OTB developers are committed to creating a self-sustaining open-source OTB community. Feedback from users is fundamental to achieving this goal.

1.4.2 Community

OTB was created from its inception as a collaborative, community effort. Research, teaching, and commercial uses of the toolkit are expected. If you would like to participate in the community, there are a number of possibilities.

Orfeo ToolBox is currently in the incubation stage of being part of the OSGeo1 foundation.Within the ORFEO ToolBox community we act respectfully toward others in line with the OSGeo Code of Conduct2 .

1.5 A Brief History of OTB

Beside the Pleiades (PHR) and Cosmo-Skymed (CSK) systems developments forming ORFEO, the dual and bilateral system (France - Italy) for Earth Observation, the ORFEO Accompaniment Program was set up, to prepare, accompany and promote the use and the exploitation of the images derived from these sensors.

The creation of a preparatory program3 is needed because of :

This program was initiated by CNES mid-2003 and will last until 2010 at least It consists in two parts, between which it is necessary to keep a strong interaction :

The Thematic part covers a large range of applications (civil and defence ones), and aims at specifying and validating value added products and services required by end users. This part includes consideration about products integration in the operational systems or processing lines. It also includes a careful thought on intermediary structures to be developed to help non-autonomous users. Lastly, this part aims at raising future users awareness, through practical demonstrations and validations.

The Methodological part objective is the definition and the development of tools for the operational exploitation of the future submetric optic and radar images (tridimensional aspects, change detection, texture analysis, pattern matching, optic radar complementarities). It is mainly based on R&D studies and doctorate and post-doctorate research.

In this context, CNES4 decided to develop the ORFEO ToolBox (OTB), a set of algorithms encapsulated in a software library. The goals of the OTB is to capitalize a methological savoir faire in order to adopt an incremental development approach aiming to efficiently exploit the results obtained in the frame of methodological R&D studies.

All the developments are based on FLOSS (Free/Libre Open Source Software) or existing CNES developments.

OTB is implemented in C++ and is mainly based on ITK5 (Insight Toolkit):

1.5.1 ITK’s history

In 1999 the US National Library of Medicine of the National Institutes of Health awarded six three-year contracts to develop an open-source registration and segmentation toolkit, that eventually came to be known as the Insight Toolkit (ITK) and formed the basis of the Insight Software Consortium. ITK’s NIH/NLM Project Manager was Dr. Terry Yoo, who coordinated the six prime contractors composing the Insight consortium. These consortium members included three commercial partners—GE Corporate R&D, Kitware, Inc., and MathSoft (the company name is now Insightful)—and three academic partners—University of North Carolina (UNC), University of Tennessee (UT) (Ross Whitaker subsequently moved to University of Utah), and University of Pennsylvania (UPenn). The Principle Investigators for these partners were, respectively, Bill Lorensen at GE CRD, Will Schroeder at Kitware, Vikram Chalana at Insightful, Stephen Aylward with Luis Ibáñez at UNC (Luis is now at Kitware), Ross Whitaker with Josh Cates at UT (both now at Utah), and Dimitri Metaxas at UPenn (now at Rutgers). In addition, several subcontractors rounded out the consortium including Peter Raitu at Brigham & Women’s Hospital, Celina Imielinska and Pat Molholt at Columbia University, Jim Gee at UPenn’s Grasp Lab, and George Stetten at the University of Pittsburgh.

In 2002 the first official public release of ITK was made available.