Skip to content
The NASA Vision Workbench is a general purpose image processing and computer vision library developed by the Autonomous Systems and Robotics (ASR) Area in the Intelligent Systems Division at the NASA Ames Research Center.
C++ Perl GLSL Python C Protocol Buffer Other
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.


The NASA Vision Workbench Version 2.0.alpha5

This is an ALPHA release of the Vision Workbench.  There are many
known bugs and incomplete features, and the API will almost certainly
change prior to the final release of version 2.0.  Much of the
documentation is incomplete or incorrect.  Although we hope you will
find this release helpful, you use it at your own risk.


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.


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,


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 

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

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.


A. Obtaining the Software

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

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.)  |              |
| PROJ.4  | Cartography (req.) | |
| GDAL    | Cartography (opt.) | |
| GLEW    | GPU (req.)         |       |
| CG      | GPU (opt.)         |       |
| PNG     | FileIO (opt.)      |             |
| JPEG    | FileIO (opt.)      |                |
| TIFF    | FileIO (opt.)      |            |
| OpenEXR | FileIO (opt.)      |            |

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 

ii. Build the library, by running "make".

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

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

By default the library will be installed into a directory called 
"build/" within the Vision Workbench package tree, in a subdirectory 
named for the particular platform you've built it for.  If you prefer 
a more conventional installation into, for example, "/usr/local/", 
then pass the command line argument "--prefix=/usr/local" to 
the configure script in step i.

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.


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

Auto-generated API documentation is also available if you have a
working installation of Doxygen and latex.  Running "make doxygen" at
the top level of the source tree will generate documentation in the
"docs/api" directory.  Running "make doc" will automatically generate 
both the Workbook and the Doxygen documentation.


A. Mailing List

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

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

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

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.

The lead developers of the Vision Workbench are Michael Broxton and
Matthew Hancher.  The project manager is Terry Fong.  See the AUTHORS
file for a complete list of developers.
Something went wrong with that request. Please try again.