README

************************************************************************
1. INTRODUCTION

The NASA Vision Workbench is a modular, extensible, cross-platform
computer vision software framework written in C++.  It was designed to
support a variety of space exploration tasks, including automated
science and engineering analysis, robot perception, and 2D/3D
environment reconstruction, though it can also serve as a
general-purpose image processing and machine vision framework in other
contexts as well.

This package is composed of several modules each of which provides a
separate C++ library.  The core library provides the basic image and
pixel data types as well as a range of fundamental image processing
operations.  The other modules provided in this release are:

 * Math: geometric, numeric, and other mathematical types and functions
 * GPU: accelerated image processing using commodity graphics hardware
 * HDR: creating, processing, and compressing high dynamic range images
 * InterestPoint: Detecting, tracking, and matching interest points
 * Mosaic: compositing, blending, and manipulating 2D image mosaics
 * Camera: camera models and related types and functions
 * Cartography: tools for manipulating geospatially-referenced images

Each of these modules and their dependencies are discussed in greater
detail in section 3, "LIBRARY STRUCTURE".

************************************************************************
2. LICENSE (see COPYING for the full text)

A. Copyright and License Summary

Copyright (C) 2009 United States Government as represented by the
Administrator of the National Aeronautics and Space Administration
(NASA).  All Rights Reserved.

This software is distributed under the NASA Open Source Agreement
(NOSA), version 1.3.  The NOSA has been approved by the Open Source
Initiative.  See the file "COPYING" at the top of the distribution
directory tree for the complete NOSA document.

THE SUBJECT SOFTWARE IS PROVIDED "AS IS" WITHOUT ANY WARRANTY OF ANY
KIND, EITHER EXPRESSED, IMPLIED, OR STATUTORY, INCLUDING, BUT NOT
LIMITED TO, ANY WARRANTY THAT THE SUBJECT SOFTWARE WILL CONFORM TO
SPECIFICATIONS, ANY IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR
A PARTICULAR PURPOSE, OR FREEDOM FROM INFRINGEMENT, ANY WARRANTY THAT
THE SUBJECT SOFTWARE WILL BE ERROR FREE, OR ANY WARRANTY THAT
DOCUMENTATION, IF PROVIDED, WILL CONFORM TO THE SUBJECT SOFTWARE.

B. Third-Party Libraries

This distribution includes some bundled third-party software as a
convenience to the user.  This software, located in the "thirdparty/"
directory, is not covered by the above-mentioned distribution
agreement or copyright.  See the included documentation for detailed
copyright and license information for any third-party software.  In
addition, various pieces of the Vision Workbench depend on additional
third-party libraries that the user is expected to have installed.
The specific dependencies of each component of the Vision Workbench
are discussed section 3, "LIBRARY STRUCTURE", and information of where
to obtain non-bundled third-party libraries is provided in section 4,
"INSTALLATION".

************************************************************************
3. LIBRARY STRUCTURE

The Vision Workbench software is located in the directory "src/vw/"
and consists of a core library and several optional libraries or
"modules".  Each module is contained in a subdirectory with the name
name as the module.

A. The Main Vision Workbench Library

At the center of the Vision Workbench are three modules that are
in fact linked together to form a single fundamental library.

i. The "Core/" module provides fundamental services that are not
specific to image processing, such as C++ exception types and type
computation classes.

ii. The "Image/" module provides the pixel and image types and
functions that form the heart of the Vision Workbench, including
support for various color spaces, filtering operations, and other
image processing primitives.

iii. The "FileIO/" module contains routines to support reading and
writing images from and to disk in a variety of file formats.

The only required dependency of the Vision Workbench core is the Boost
C++ libraries, which provide a variety of low-level C++ library
servies.  (These are actually many libraries by different authors
released under a common license, but they are generally distributed as
a package and we will treat them that way for simplicity.)  The file
I/O module has a number of optional dependencies, each providing
support for one or more image file formats.  Specifically these are:
libpng for PNG files, libjpeg for JPEG/JFIF files, libtiff for TIFF
files, NetPBM for PBM/PGM/etc. files, and OpenEXR for EXR files.

B. Math Module

This module provides a variety of mathematical data types and
algorithms.  It is centered around fundamental vector, matrix, and
quaternion data types which support the usual range of mathematical
operations.  On top of that foundation there are higher-level types
and algorithms for geometric computation, linear algebra,
optimization, and statistics, and so forth.

The linear algebra numerical algorithms rely on the standard low-level
routines provided by LAPACK (Linear Algebra Package) and BLAS (Basic
Linear Algebra Subprograms).  Many computers (e.g. those running OS X)
come with optimized implementations of LAPACK and BLAS, in which case
you can (and probably should) just use those.  To support other
platforms we provide public-domain implementations automatically
translated from the original Fortran and taken from the online Netlib
repository.

C. GPU Module

Most modern graphics hardware includes a general-purpose graphics
processing unit (GPU), and this module provides an interface to take
advantage of that high-performance hardware for a variety of basic
image-processing operations.  Under Linux it requires that you have
installed the OpenGL interface library GLEW.  It can optionally also
take advantage of the NVIDIA CG library, which provides an alternative
low-level framework which may be preferable on some graphics hardware.

D. HDR Module

While the core Vision Workbench library supports working with high
dynamic range (HDR) image data directly, most input and output devices
(e.g. digital cameras and displays) only support a limited dynamic range.
This module provides tools for interfacing between the two worlds, by
generating HDR images from collections of ordinary images as well as
providing several methods to compress HDR images for display on ordinary
output devices.

E. InterestPoint Module

Interest points are points in an image that can be reliably detected and
tracked, such as corners or peaks.  This module provides tools for
locating interest points in images in a variety of ways.  It can also
generate local descriptors for those points using several methods which
can then be used to locate corresponding points in sets of images.

F. Mosaic Module

The Mosaic module provides tools for working with large images
assembled from many smaller images, such as panoramas or aerial maps.
It includes support for assembling source images into a mosaic,
blending the images in the mosaic to create a single large image, and
dicing the extremely large images that result into better formats for
visualization.

G. Camera Module

The Camera module provides a variety of data types and tools for
working with camera models and camera data.  Most notably it includes
support for a variety of standard camera geometries, the ability to
transform images between camera models, and the ability to interpret
camera data stored in the EXIF headers of image files generated by
digital cameras.

H. Cartography Module

The Cartography module provides a variety of 2D and 3D mapping
capabilities.  It allows you to georeference an image, specifying its
projection, position within the projected space, and altitude
reference (or "datum"), and it supports reprojecting images into the
desired projection.  It requires the PROJ.4 cartographic projection
library, and also optionally depends on the GDAL library which
provides support for a variety of GIS file formats.

I. Testing Frameworks

Each module includes a collection of tests located in that module's
"tests/" subdirectory.  You can use these tests to confirm that the
library is installed and working properly on your system.  To do this,
simply run "make check" after building the library.  Please report any
errors you encounter, using the contact information at the bottom of
this file.  Note that while the tests do currently exercise a
significant portion of the library, they are not yet fully exhaustive.

************************************************************************
4. INSTALLATION AND USE

A. Obtaining the Software

If you are reading this text then presumably you have a copy of
the software.  However, you can obtain the most recent version from

  http://ti.arc.nasa.gov/visionworkbench

Before attempting to configure, build or install the Vision Workbench
you should obtain and install any prerequisite libraries that you
need.  The only absolute requirement is the Boost.  The others are
either required to build a specific module, or will enable a
particular feature if available.  A complete list of dependencies
is shown in the table below, where each library is noted as being
either a required or optional dependency of one or modules.  All of
these libraries are distributed under some variation on the themes
of the MIT and BSD licenses.  See each individual library's
documentation for details.

+---------+--------------------+------------------------------------+
| Library | Relevant Modules   | Source Website                     |
+---------+--------------------+------------------------------------+
| Boost   | Core, etc. (req.)  | http://www.boost.org/              |
| PROJ.4  | Cartography (req.) | http://www.remotesensing.org/proj/ |
| GDAL    | Cartography (opt.) | http://www.remotesensing.org/gdal/ |
| GLEW    | GPU (req.)         | http://glew.sourceforge.net/       |
| CG      | GPU (opt.)         | http://developer.nvidia.com/       |
| PNG     | FileIO (opt.)      | http://www.libpng.org/             |
| JPEG    | FileIO (opt.)      | http://www.ijg.org/                |
| TIFF    | FileIO (opt.)      | http://www.libtiff.org/            |
| OpenEXR | FileIO (opt.)      | http://www.openexr.com/            |
+---------+--------------------+------------------------------------+

In addition, the some Vision Workbench modules require other, lower
level modules to be built.  The internal Vision Workbench dependency
table appears below.

+------+--------+-------------+
| HDR  | Mosaic | Cartography |   Application-specific Toolkits
+------+--------+-------------+
+---------------+-------------+
|    FileIO     |    Camera   |   High-level Primatives
+---------------+-------------+
+---------------+-------------+
|    Image      |    Math     |   Low-level image processing/Linear Algrebra
+---------------+-------------+
+-----------------------------+
|             Core            |   Basic Programming Infrastructure
+-----------------------------+


B. Building and Installing

Once you have obtained and installed all of the prerequisite software
the process of building the Vision Workbench itself is generally
straightforward.  There are four steps:

i. Configure the library.  This is usually as simple as running the
"./configure" script from within the root Vision Workbench package
directory.

ii. Build the library by running "make".

iii. Run the tests by running "make check".

iv. Install the library by running "make install".

While this simple sequence will suffice for most users, the configure
script has many options that you can use to adjust various properties,
such as compiler optimization flags or the search paths used to find
required libraries.  See the "INSTALL" file in this directory for more
detailed information.

C. Using the Library

When you install the library it will place files into three
subdirectories in the installation location.  The header files which
you will need to develop software using the library are located in the
"include/" subdirectory.  The compiled libraries, which you will need
to link your software against, are located in the "lib/" subdirectory.
You will need to configure your software development environment as
appropriate to locate these files.  Finally, a number of simple
command-line tools are provided in the "bin/" directory.  These are
intended primarily as demo applications, but many of them are in fact
useful in their own right.  See the documentation for a complete list
of the tools.

************************************************************************
5. DOCUMENTATION

The primary source of documentation is the Vision Workbook, which is
provided in source form along with this distribution.  It includes a
gentle introduction to using the core image processing routines, as
well as documentation for each of the high level Vision Workbench
modules.  A copy of this document in PDF format should be available
from wherever you obtained this package.  The original source for this
document can be found in "docs/workbook" and it can be built by
running "make workbook".  This operation requires the latex typesetting
package.

************************************************************************
6. CONTACTS & CREDITS

A. Mailing List

All bugs, feature requests, and general discussion should be sent to
the Vision Workbench user mailing list:

  vision-workbench@lists.nasa.gov

To subscribe to this list, send an empty email message with the subject
'subscribe' (without the quotes) to

  vision-workbench-request@lists.nasa.gov

To contact the lead developers and project manager directly, send mail
to:

  vision-workbench-owner@lists.nasa.gov

Please do NOT use this second list for technical inquiries, which
should all be sent to the main vision-workbench list above.

B. Credits

The Vision Workbench was developed within the Autonomous Systems and
Robotics area of the Inteligent Systems Division at NASA's Ames
Research Center.  It leverages the Intelligent Robotics Group's (IRG)
extensive experience developing surface reconstruction and tools for
planetary exploration---e.g. the Mars Pathfinder and Mars Exploration
Rover missions---and rover autonomy.  It has also been developed in
collaboration with the Adaptive Control and Evolvable Systems (ACES)
group, and draws on their experience developing computer vision
techniques for autonomous vehicle control systems.

See the AUTHORS file for a complete list of developers.