# public visionworkbench /visionworkbench

### Subversion checkout URL

You can clone with HTTPS or Subversion.

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