# publicvisionworkbench/visionworkbench

### Subversion checkout URL

You can clone with HTTPS or Subversion.

Fetching contributors…

Cannot retrieve contributors at this time

file 219 lines (189 sloc) 11.588 kb
 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 # __BEGIN_LICENSE__# Copyright (c) 2006-2012, United States Government as represented by the# Administrator of the National Aeronautics and Space Administration. All# rights reserved.## The NASA Vision Workbench is licensed under the Apache License,# Version 2.0 (the "License"); you may not use this file except in# compliance with the License. You may obtain a copy of the License at# http://www.apache.org/licenses/LICENSE-2.0## Unless required by applicable law or agreed to in writing, software# distributed under the License is distributed on an "AS IS" BASIS,# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.# See the License for the specific language governing permissions and# limitations under the License.# __END_LICENSE__Requirements============If you are reading this document then you already have a copy of theVision Workbench sources. You may want to confirm that you have themost most up-to-date distribution, which will always be available fromthe NASA Ames open-source software website, at:   http://irg.arc.nasa.gov/nasa-vision-workbenchThere you will also be able to download an up-to-date copy of theuser's guide, called the Vision Workbook, which contains a morecomplete description of how to get started with the Vision Workbench.You will also need to obtain and install whichever pre-requisitelibraries you will need. The only strict requirement is the Boost C++Libraries, a set of extensions to the standard C++ libraries that isavailable at www.boost.org. Many modern Linux systems come with someversion of Boost already installed, generally in the directory/usr/include/boost. The Vision Workbench has been tested with Boostversions 1.32 and later.Other libraries are required only if you want to use particularfeatures of the Vision Workbench. A summary of the various librariesthat the Vision Workbench will detect and use if present is given infollowing table. It lists the particular Vision Workbench module thatuses the library, whether it is required or optional for that module,and where the library can be obtained. If you are just starting outwith the Vision Workbench, it is generally fine to begin only withBoost and support for one or two file formats. You can always go backand rebuild the Vision Workbench with support for additional featureslater if you discover that you need them. Name | Used By | Source---------+-----------------------+------------------------------------ Boost | All | http://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, whichprovides the Vision Workbench with a computational linear algebra backend. LAPACK is a comprehensive and widely-used linear algebra supportlibrary in the public domain. LAPACK also requires the Basic LinearAlgebra Subroutines (BLAS) library, which is usually bundled withLAPACK.The basic matrix and vector algebra in the Math module does not dependon LAPACK and BLAS. However, the routines in will only be built if LAPACK is detected by the build system. Foryour convenience, we provide a stand-alone LAPACK and BLASdistribution on the Vision Workbench website listed at the top of thisdocument. This distribution has been tested with the VisionWorkbench, so we recommend its use if you are installing LAPACK forthe first time. However, other versions of LAPACK and BLAS that comepre-installed on your system will probably work just as well. Inparticular, 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" flagwhen linking your application against the Vision Workbench if you areusing these functions on the Mac platform.Building the Vision Workbench=============================First configure the build system by running "./configure" from thebase directory of the source distribution. This script will examineyour machine to determine what build tools to use and what librariesare installed as well as where they are located. Near the end of itsoutput it will list whether or not it was able to find each libraryand which Vision Workbench modules it is going to build. You shouldexamine this output to confirm that it was able to find all thelibraries that you had expected it to. If not then you may need toconfigure the build system to search in the right places, as discussedin the next section.Assuming the output of the configure script looks good, you can nowproceed to build the Vision Workbench itself by running "make". Mostof the Vision Workbench is header-only, so "building" the VisionWorkbench should be relatively quick. Once the build is complete,confirm that things are working properly by building and running theunit tests by typing "make check". If there are no errors, the finalstep is to install the Vision Workbench headers, library, and sampleprograms using "make install". By default the installation locationis the directory /usr/local, so you will need to obtain the necessaryprivileges to write to this directory using a command such as "sudo"or "su". If you do not have administrator privileges on you computerthen see the next section for information on how to specify analternative installation directory.Building the Vision Workbench under Windows is possible, but it is notcurrently automatically supported. The easiest thing to do is toinclude the .cc files from the Vision Workbench modules that you wantto use directly in your own project file. You will of course stillneed to install the Boost libraries as well as any other libraries youwant to use. Pre-built Windows versions of a number of libraries,such as the JPEG, PNG, and TIFF libraries, are available online fromthe GnuWin32 project at gnuwin32.sourceforge.net. You will need toconfigure your project's include file and library search pathsappropriately. Also be sure to configure your project to define thepreprocessor symbol "NOMINMAX" to disable the non-portable Windowsdefinitions of min() and max() macros, which interfere with thestandard C++ library functions of the same names. In addition, youwill need to define the preprocessor symbol "_USE_MATH_DEFINES" toensure that math.h defines constants such as M_PI.Configuring the Build System============================The Vision Workbench build system offers a variety of configurationoptions that you provide as command-line flags to the "configure"script. We'll discuss a few of the most important options here, butfor a complete list you can run "./configure --help". As analternative to specifying command-line flags every time, you mayinstead create a file called "config.options" with your preferences inthe base directory of the Vision Workbench repository. A file called"config.options.example" is provided that you can copy and edit toyour liking. Note that none of this has any impact on Visual Studiousers, 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 pathsthat the build system should search when looking for installedlibraries. For example if you specify "--with-paths=/foo/bar" then itwill search for header files in "/foo/bar/include", library files in"/foo/bar/lib", and so on. The default search path includes a numberof 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 certainmodules are built. Disabling modules that you do not use can speed upcompilation and testing time, which is especially useful if you aremaking changes to the Vision Workbench source and need to recompileoften. 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", determinethe compiler options used when building the few library files. Youcan again specify an optional argument of the form "=no" to disablethe corresponding feature, and you can also specify a particularoptimization level in the same manner. For example, if you want tomake it as easy as possible to debug Vision Workbench code using adebugger you might use "--enable-optimize=no --enable-debug" todisable all optimizations and include debugging symbols. Thecorresponding configuration file variables are "ENABLE_OPTIMIZE" and"ENABLE_DEUBG". Keep in mind that since most Vision Workbench code isheader-only you should remember to configure your own projectsimilarly or you may not notice any difference. For normalnon-debugging use, we strongly recommend that you enable moderatecompiler optimization; much of the heavily templatized and genericVision Workbench code requires basic optimizations such as functioninlining to achieve a reasonable level of performance.Finally, to specify that the build system should install the VisionWorkbench someplace other than "/usr/local", specify the path usingthe "--prefix=PATH" option. The corresponding configuration filevariable is, of course, called "PREFIX".Common Problems===============* I have (library X) installed in one location that I want to use, andthere's another version installed system-wide. How do I get VisionWorkbench to build with the version I want?Due to limitations in the underlying build system tools, theautodetection will always detect the system-installed library and ignoredifferent installations, even if the PKG_PATHS environment variable isset. To get around this, set the following environment variables (whereX is the name of the library as known by the configure script's--with-X, in caps):HAVE_PKG_X=yesPKG_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 shouldthen 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, theopening of TIFF files can fail to function correctly when VisionWorkbench also links against another libtiff. To see whether or notGDAL is using an internal libtiff, run ldd on the gdal library andcheck its linkage; if it does not link, then check gdalinfo --format.If GTiff is supported, and ldd says that the gdal library is not linkedagainst libtiff, then GDAL is using an internal libtiff library.In that case, you will want to disable libtiff. Add "--without-tiff" tothe ./configure command line. This does not effect the functionality ofVision Workbench, as it will use GDAL to open TIFF files instead.
Something went wrong with that request. Please try again.