INSTALLGUIDE

# __BEGIN_LICENSE__
# 
# Copyright (C) 2006 United States Government as represented by the
# Administrator of the National Aeronautics and Space Administration
# (NASA).  All Rights Reserved.
# 
# Copyright 2006 Carnegie Mellon University. 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.
# 
# __END_LICENSE__


Requirements
============

If you are reading this document then you already have a copy of the 
Vision Workbench sources.  You may want to confirm that you have the 
most most up-to-date distribution, which will always be available from 
the NASA Ames open-source software website, at:
   http://ti.arc.nasa.gov/visionworkbench
There you will also be able to download an up-to-date copy of the
user's guide, called the Vision Workbook, which contains a more
complete description of how to get started with the Vision Workbench.

You will also need to obtain and install whichever pre-requisite
libraries you will need.  The only strict requirement is the Boost C++
Libraries, a set of extensions to the standard C++ libraries that is
available at www.boost.org.  Many modern Linux systems come with some
version of Boost already installed, generally in the directory
/usr/include/boost.  The Vision Workbench has been tested with Boost
versions 1.32 and later.

Other libraries are required only if you want to use particular
features of the Vision Workbench.  A summary of the various libraries
that the Vision Workbench will detect and use if present is given in
following table.  It lists the particular Vision Workbench module that
uses the library, whether it is required or optional for that module,
and where the library can be obtained.  If you are just starting out
with the Vision Workbench, it is generally fine to begin only with
Boost and support for one or two file formats.  You can always go back
and rebuild the Vision Workbench with support for additional features
later if you discover that you need them.

 Name    | Used By               | Source
---------+-----------------------+------------------------------------
 Boost   | All                   | ttp://www.boost.org/
 LAPACK  | Portions of Math, HDR | See notes below
 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/
 PROJ.4  | Cartography (req.)    | http://www.remotesensing.org/proj/
 GDAL    | Cartography (opt.)    | http://www.remotesensing.org/gdal/

One dependency that is worth discussing briefly is LAPACK, which
provides the Vision Workbench with a computational linear algebra back
end.  LAPACK is a comprehensive and widely-used linear algebra support
library in the public domain.  LAPACK also requires the Basic Linear
Algebra Subroutines (BLAS) library, which is usually bundled with
LAPACK.

The basic matrix and vector algebra in the Math module does not depend
on LAPACK and BLAS.  However, the routines in <vw/Math/LinearAlgebra.h> 
will only be built if LAPACK is detected by the build system.  For
your convenience, we provide a stand-alone LAPACK and BLAS
distribution on the Vision Workbench website listed at the top of this
document.  This distribution has been tested with the Vision
Workbench, so we recommend its use if you are installing LAPACK for
the first time.  However, other versions of LAPACK and BLAS that come
pre-installed on your system will probably work just as well.  In
particular, Mac OS X users {\em do not} need to install LAPACK;
optimized linear algebra support is provided by Apple's "veclib"
framework on Mac OS X.  Remember to add the "-framework veclib" flag
when linking your application against the Vision Workbench if you are
using these functions on the Mac platform.


Building the Vision Workbench
=============================

First configure the build system by running "./configure" from the
base directory of the source distribution.  This script will examine
your machine to determine what build tools to use and what libraries
are installed as well as where they are located.  Near the end of its
output it will list whether or not it was able to find each library
and which Vision Workbench modules it is going to build.  You should
examine this output to confirm that it was able to find all the
libraries that you had expected it to.  If not then you may need to
configure the build system to search in the right places, as discussed
in the next section.

Assuming the output of the configure script looks good, you can now
proceed to build the Vision Workbench itself by running "make".  Most
of the Vision Workbench is header-only, so "building" the Vision
Workbench should be relatively quick.  Once the build is complete,
confirm that things are working properly by building and running the
unit tests by typing "make check".  If there are no errors, the final
step is to install the Vision Workbench headers, library, and sample
programs using "make install".  By default the installation location
is the directory /usr/local, so you will need to obtain the necessary
privileges to write to this directory using a command such as "sudo"
or "su".  If you do not have administrator privileges on you computer
then see the next section for information on how to specify an
alternative installation directory.

Building the Vision Workbench under Windows is possible, but it is not
currently automatically supported.  The easiest thing to do is to
include the .cc files from the Vision Workbench modules that you want
to use directly in your own project file.  You will of course still
need to install the Boost libraries as well as any other libraries you
want to use.  Pre-built Windows versions of a number of libraries,
such as the JPEG, PNG, and TIFF libraries, are available online from
the GnuWin32 project at gnuwin32.sourceforge.net.  You will need to
configure your project's include file and library search paths
appropriately.  Also be sure to configure your project to define the
preprocessor symbol "NOMINMAX" to disable the non-portable Windows
definitions of min() and max() macros, which interfere with the
standard C++ library functions of the same names. In addition, you
will need to define the preprocessor symbol "_USE_MATH_DEFINES" to
ensure that math.h defines constants such as M_PI.


Configuring the Build System
============================

The Vision Workbench build system offers a variety of configuration
options that you provide as command-line flags to the "configure"
script.  We'll discuss a few of the most important options here, but
for a complete list you can run "./configure --help".  As an
alternative to specifying command-line flags every time, you may
instead create a file called "config.options" with your preferences in
the base directory of the Vision Workbench repository.  A file called
"config.options.example" is provided that you can copy and edit to
your liking.  Note that none of this has any impact on Visual Studio
users, who must instead configure their projects by hand.

The single most important option is the "--with-paths=PATHS" flag,
where you replace "PATHS" with a whitespace-separated list of paths
that the build system should search when looking for installed
libraries.  For example if you specify "--with-paths=/foo/bar" then it
will search for header files in "/foo/bar/include", library files in
"/foo/bar/lib", and so on.  The default search path includes a number
of common locations for user-installed libraries, such as
"/usr/local", "$(HOME)/local", and "/sw".  The "PKG_PATHS"
configuration file variable has the same effect as this option.

The next most important options have the form "--enable-module-foo[=no]", 
where "foo" is replaced by the lower-case name of a module such as
"mosaic" or "hdr".  This allows you to control whether or not certain
modules are built.  Disabling modules that you do not use can speed up
compilation and testing time, which is especially useful if you are
making changes to the Vision Workbench source and need to recompile
often.  The corresponding configuration file variables have the form
"ENABLE_MODULE_FOO", in all-caps, and are set to either "yes" or "no".

Two handy options, "--enable-optimize" and "--enable-debug", determine
the compiler options used when building the few library files.  You
can again specify an optional argument of the form "=no" to disable
the corresponding feature, and you can also specify a particular
optimization level in the same manner.  For example, if you want to
make it as easy as possible to debug Vision Workbench code using a
debugger you might use "--enable-optimize=no --enable-debug" to
disable all optimizations and include debugging symbols.  The
corresponding configuration file variables are "ENABLE_OPTIMIZE" and
"ENABLE_DEUBG".  Keep in mind that since most Vision Workbench code is
header-only you should remember to configure your own project
similarly or you may not notice any difference.  For normal
non-debugging use, we strongly recommend that you enable moderate
compiler optimization; much of the heavily templatized and generic
Vision Workbench code requires basic optimizations such as function
inlining to achieve a reasonable level of performance.

Finally, to specify that the build system should install the Vision
Workbench someplace other than "/usr/local", specify the path using
the "--prefix=PATH" option.  The corresponding configuration file
variable is, of course, called "PREFIX".


Common Problems
===============

* I have (library X) installed in one location that I want to use, and 
there's another version installed system-wide. How do I get Vision 
Workbench to build with the version I want?

Due to limitations in the underlying build system tools, the 
autodetection will always detect the system-installed library and ignore 
different installations, even if the PKG_PATHS environment variable is 
set. To get around this, set the following environment variables (where 
X is the name of the library as known by the configure script's 
--with-X, in caps):

HAVE_PKG_X=yes
PKG_X_CPPFLAGS="-I/path/to/include/directory"
PKG_X_LDFLAGS="-L/path/to/library/directory"

(These can be set in the config.options file.) Vision Workbench should 
then link against the library in the location specified in this manner.


* Vision Workbench crashes when opening a TIFF/GeoTIFF file!

When linking against a GDAL library that uses an internal libtiff, the 
opening of TIFF files can fail to function correctly when Vision 
Workbench also links against another libtiff. To see whether or not 
GDAL is using an internal libtiff, run ldd on the gdal library and 
check its linkage; if it does not link, then check gdalinfo --format. 
If GTiff is supported, and ldd says that the gdal library is not linked 
against libtiff, then GDAL is using an internal libtiff library.

In that case, you will want to disable libtiff. Add "--without-tiff" to 
the ./configure command line. This does not effect the functionality of 
Vision Workbench, as it will use GDAL to open TIFF files instead.