Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 224 lines (193 sloc) 11.705 kB
5aa900c @novas0x2a turn on autoreconf --force, and rename our install file so autoreconf…
novas0x2a authored
1 # __BEGIN_LICENSE__
2 #
3 # Copyright (C) 2006 United States Government as represented by the
4 # Administrator of the National Aeronautics and Space Administration
5 # (NASA). All Rights Reserved.
6 #
7 # Copyright 2006 Carnegie Mellon University. All rights reserved.
8 #
9 # This software is distributed under the NASA Open Source Agreement
10 # (NOSA), version 1.3. The NOSA has been approved by the Open Source
11 # Initiative. See the file COPYING at the top of the distribution
12 # directory tree for the complete NOSA document.
13 #
14 # THE SUBJECT SOFTWARE IS PROVIDED "AS IS" WITHOUT ANY WARRANTY OF ANY
15 # KIND, EITHER EXPRESSED, IMPLIED, OR STATUTORY, INCLUDING, BUT NOT
16 # LIMITED TO, ANY WARRANTY THAT THE SUBJECT SOFTWARE WILL CONFORM TO
17 # SPECIFICATIONS, ANY IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR
18 # A PARTICULAR PURPOSE, OR FREEDOM FROM INFRINGEMENT, ANY WARRANTY THAT
19 # THE SUBJECT SOFTWARE WILL BE ERROR FREE, OR ANY WARRANTY THAT
20 # DOCUMENTATION, IF PROVIDED, WILL CONFORM TO THE SUBJECT SOFTWARE.
21 #
22 # __END_LICENSE__
23
24
25 Requirements
26 ============
27
28 If you are reading this document then you already have a copy of the
29 Vision Workbench sources. You may want to confirm that you have the
30 most most up-to-date distribution, which will always be available from
31 the NASA Ames open-source software website, at:
32 http://ti.arc.nasa.gov/visionworkbench
33 There you will also be able to download an up-to-date copy of the
34 user's guide, called the Vision Workbook, which contains a more
35 complete description of how to get started with the Vision Workbench.
36
37 You will also need to obtain and install whichever pre-requisite
38 libraries you will need. The only strict requirement is the Boost C++
39 Libraries, a set of extensions to the standard C++ libraries that is
40 available at www.boost.org. Many modern Linux systems come with some
41 version of Boost already installed, generally in the directory
42 /usr/include/boost. The Vision Workbench has been tested with Boost
43 versions 1.32 and later.
44
45 Other libraries are required only if you want to use particular
46 features of the Vision Workbench. A summary of the various libraries
47 that the Vision Workbench will detect and use if present is given in
48 following table. It lists the particular Vision Workbench module that
49 uses the library, whether it is required or optional for that module,
50 and where the library can be obtained. If you are just starting out
51 with the Vision Workbench, it is generally fine to begin only with
52 Boost and support for one or two file formats. You can always go back
53 and rebuild the Vision Workbench with support for additional features
54 later if you discover that you need them.
55
56 Name | Used By | Source
57 ---------+-----------------------+------------------------------------
58 Boost | All | ttp://www.boost.org/
59 LAPACK | Portions of Math, HDR | See notes below
60 PNG | FileIO (opt.) | http://www.libpng.org/
61 JPEG | FileIO (opt.) | http://www.ijg.org/
62 TIFF | FileIO (opt.) | http://www.libtiff.org/
63 OpenEXR | FileIO (opt.) | http://www.openexr.com/
64 PROJ.4 | Cartography (req.) | http://www.remotesensing.org/proj/
65 GDAL | Cartography (opt.) | http://www.remotesensing.org/gdal/
66
67 One dependency that is worth discussing briefly is LAPACK, which
68 provides the Vision Workbench with a computational linear algebra back
69 end. LAPACK is a comprehensive and widely-used linear algebra support
70 library in the public domain. LAPACK also requires the Basic Linear
71 Algebra Subroutines (BLAS) library, which is usually bundled with
72 LAPACK.
73
74 The basic matrix and vector algebra in the Math module does not depend
75 on LAPACK and BLAS. However, the routines in <vw/Math/LinearAlgebra.h>
76 will only be built if LAPACK is detected by the build system. For
77 your convenience, we provide a stand-alone LAPACK and BLAS
78 distribution on the Vision Workbench website listed at the top of this
79 document. This distribution has been tested with the Vision
80 Workbench, so we recommend its use if you are installing LAPACK for
81 the first time. However, other versions of LAPACK and BLAS that come
82 pre-installed on your system will probably work just as well. In
83 particular, Mac OS X users {\em do not} need to install LAPACK;
84 optimized linear algebra support is provided by Apple's "veclib"
85 framework on Mac OS X. Remember to add the "-framework veclib" flag
86 when linking your application against the Vision Workbench if you are
87 using these functions on the Mac platform.
88
89
90 Building the Vision Workbench
91 =============================
92
93 First configure the build system by running "./configure" from the
94 base directory of the source distribution. This script will examine
95 your machine to determine what build tools to use and what libraries
96 are installed as well as where they are located. Near the end of its
97 output it will list whether or not it was able to find each library
98 and which Vision Workbench modules it is going to build. You should
99 examine this output to confirm that it was able to find all the
100 libraries that you had expected it to. If not then you may need to
101 configure the build system to search in the right places, as discussed
102 in the next section.
103
104 Assuming the output of the configure script looks good, you can now
105 proceed to build the Vision Workbench itself by running "make". Most
106 of the Vision Workbench is header-only, so "building" the Vision
107 Workbench should be relatively quick. Once the build is complete,
108 confirm that things are working properly by building and running the
109 unit tests by typing "make check". If there are no errors, the final
110 step is to install the Vision Workbench headers, library, and sample
111 programs using "make install". By default the installation location
112 is the directory /usr/local, so you will need to obtain the necessary
113 privileges to write to this directory using a command such as "sudo"
114 or "su". If you do not have administrator privileges on you computer
115 then see the next section for information on how to specify an
116 alternative installation directory.
117
118 Building the Vision Workbench under Windows is possible, but it is not
119 currently automatically supported. The easiest thing to do is to
120 include the .cc files from the Vision Workbench modules that you want
121 to use directly in your own project file. You will of course still
122 need to install the Boost libraries as well as any other libraries you
123 want to use. Pre-built Windows versions of a number of libraries,
124 such as the JPEG, PNG, and TIFF libraries, are available online from
125 the GnuWin32 project at gnuwin32.sourceforge.net. You will need to
126 configure your project's include file and library search paths
127 appropriately. Also be sure to configure your project to define the
128 preprocessor symbol "NOMINMAX" to disable the non-portable Windows
129 definitions of min() and max() macros, which interfere with the
130 standard C++ library functions of the same names.
131
132
133 Configuring the Build System
134 ============================
135
136 The Vision Workbench build system offers a variety of configuration
137 options that you provide as command-line flags to the "configure"
138 script. We'll discuss a few of the most important options here, but
139 for a complete list you can run "./configure --help". As an
140 alternative to specifying command-line flags every time, you may
141 instead create a file called "config.options" with your preferences in
142 the base directory of the Vision Workbench repository. A file called
143 "config.options.example" is provided that you can copy and edit to
144 your liking. Note that none of this has any impact on Visual Studio
145 users, who must instead configure their projects by hand.
146
147 The single most important option is the "--with-paths=PATHS" flag,
148 where you replace "PATHS" with a whitespace-separated list of paths
149 that the build system should search when looking for installed
150 libraries. For example if you specify "--with-paths=/foo/bar" then it
151 will search for header files in "/foo/bar/include", library files in
152 "/foo/bar/lib", and so on. The default search path includes a number
153 of common locations for user-installed libraries, such as
154 "/usr/local", "$(HOME)/local", and "/sw". The "PKG_PATHS"
155 configuration file variable has the same effect as this option.
156
157 The next most important options have the form "--enable-module-foo[=no]",
158 where "foo" is replaced by the lower-case name of a module such as
159 "mosaic" or "hdr". This allows you to control whether or not certain
160 modules are built. Disabling modules that you do not use can speed up
161 compilation and testing time, which is especially useful if you are
162 making changes to the Vision Workbench source and need to recompile
163 often. The corresponding configuration file variables have the form
164 "ENABLE_MODULE_FOO", in all-caps, and are set to either "yes" or "no".
165
166 Two handy options, "--enable-optimize" and "--enable-debug", determine
167 the compiler options used when building the few library files. You
168 can again specify an optional argument of the form "=no" to disable
169 the corresponding feature, and you can also specify a particular
170 optimization level in the same manner. For example, if you want to
171 make it as easy as possible to debug Vision Workbench code using a
172 debugger you might use "--enable-optimize=no --enable-debug" to
173 disable all optimizations and include debugging symbols. The
174 corresponding configuration file variables are "ENABLE_OPTIMIZE" and
175 "ENABLE_DEUBG". Keep in mind that since most Vision Workbench code is
176 header-only you should remember to configure your own project
177 similarly or you may not notice any difference. For normal
178 non-debugging use, we strongly recommend that you enable moderate
179 compiler optimization; much of the heavily templatized and generic
180 Vision Workbench code requires basic optimizations such as function
181 inlining to achieve a reasonable level of performance.
182
183 Finally, to specify that the build system should install the Vision
184 Workbench someplace other than "/usr/local", specify the path using
185 the "--prefix=PATH" option. The corresponding configuration file
186 variable is, of course, called "PREFIX".
187
188
189 Common Problems
190 ===============
191
192 * I have (library X) installed in one location that I want to use, and
193 there's another version installed system-wide. How do I get Vision
194 Workbench to build with the version I want?
195
196 Due to limitations in the underlying build system tools, the
197 autodetection will always detect the system-installed library and ignore
198 different installations, even if the PKG_PATHS environment variable is
199 set. To get around this, set the following environment variables (where
200 X is the name of the library as known by the configure script's
201 --with-X, in caps):
202
203 HAVE_PKG_X=yes
204 PKG_X_CPPFLAGS="-I/path/to/include/directory"
205 PKG_X_LDFLAGS="-L/path/to/library/directory"
206
207 (These can be set in the config.options file.) Vision Workbench should
208 then link against the library in the location specified in this manner.
209
210
211 * Vision Workbench crashes when opening a TIFF/GeoTIFF file!
212
213 When linking against a GDAL library that uses an internal libtiff, the
214 opening of TIFF files can fail to function correctly when Vision
215 Workbench also links against another libtiff. To see whether or not
216 GDAL is using an internal libtiff, run ldd on the gdal library and
217 check its linkage; if it does not link, then check gdalinfo --format.
218 If GTiff is supported, and ldd says that the gdal library is not linked
219 against libtiff, then GDAL is using an internal libtiff library.
220
221 In that case, you will want to disable libtiff. Add "--without-tiff" to
222 the ./configure command line. This does not effect the functionality of
223 Vision Workbench, as it will use GDAL to open TIFF files instead.
Something went wrong with that request. Please try again.