-
Notifications
You must be signed in to change notification settings - Fork 0
/
INSTALL.txt
308 lines (207 loc) · 10.3 KB
/
INSTALL.txt
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
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
Section of Biomedical Image Analysis
Department of Radiology
University of Pennsylvania
3600 Market Street, Suite 380
Philadelphia, PA 19104
Web: http://www.rad.upenn.edu/sbia/
Email: sbia-software at uphs.upenn.edu
Copyright (c) 2012 University of Pennsylvania. All rights reserved.
See http://www.rad.upenn.edu/sbia/software/license.html or COPYING file.
INTRODUCTION
============
This document contains the build and installation instructions.
For general build and installation instructions which apply to any software
developed on top of the SBIA Build system And Software Implementation
Standard (BASIS) [1], please refer to the respective how-to guide of the
BASIS documentation [2].
OBTAINING A COPY OF THE SOFTWARE
================================
Please see the corresponding section of the BASIS how-to guide [2].
INSTALLING A BINARY DISTRIBUTION PACKAGE
========================================
Please see the corresponding section of the BASIS how-to guide [2].
RUNTIME REQUIREMENTS
====================
The main gondola function/program which implements the
Generative-Discriminative Basis Learning is written in MATLAB.
- MATLAB >= R2009b
Web Site: http://www.mathworks.com/
Download: n/a
MATLAB is required to execute the main gondola function if during the build
the option BASIS_COMPILE_MATLAB was set to OFF or if no MATLAB Compiler is
available. In this case, a Bash (Unix) or Windows NT Command (Windows)
script is generated by BASIS which calls MATLAB as follows:
/path/to/bin/matlab -nodesktop -nosplash -nojvm -c "gondola([options])"
with the proper formatting of the program options as arguments to the
gondola() MATLAB function.
- MATLAB Image Processing Toolbox
Web Site: http://www.mathworks.com/products/image/
Download: n/a
Required at runtime only if the MATLAB sources were not compiled using the
MATLAB Compiler.
- MATLAB Compiler Runtime
Web Site: http://www.mathworks.com/products/compiler/mcr/index.html
Downlaod: http://www.mathworks.com/products/compiler/mcr/index.html
If the software has been compiled using the MATLAB Compiler, the MATLAB
Compiler Runtime (MCR) has to be installed.
The scripts used to perform the cross-validation experiments are implemented in
Python, where Jython is further used to enable the use of the Weka Java API.
Additionally, the non-core Python modules of the SBIA Utilities, NumPy, and SciPy
packages (see Build Dependencies) are required to execute the gondola-crossval
script. The path to these modules is configured during the build of GONDOLA.
- Python >= 2.5.2
Web Site: http://www.python.org/
Download: http://www.python.org/getit/
The main scripts gondola-config and gondola-crossval are implemented in Python.
These are not required for the core algorithm which is implemented by the
gondola MATLAB function. However, Python is available for all supported platforms
and already intalled on most Unix systems.
- Jython >= 2.5.1
Web Site: http://www.jython.org/
Download: http://www.jython.org/downloads.html
Jython is a Java implementation of the Python language interpreter. It enables
the use of Java classes in scripts using the Python language and is in particular
required by the command-line tools which determine the best parameters for each
classifier and train them as these make use of the Weka Java API.
BUILDING THE SOFTWARE FROM SOURCES
==================================
Build Dependencies
------------------
The following software has to be installed (if not optional).
- BASIS >= 2.0
Web Site: http://www.rad.upenn.edu/sbia/software/basis/
Download: http://www.rad.upenn.edu/sbia/software/distributions/basis-2.0.0-source.tar.gz
This project is based on BASIS, a meta-project developed at SBIA to
standardize and simplify the software development.
- ITK >= 3.18
Web Site: http://www.itk.org/
Download: http://www.itk.org/ITK/resources/software.html
Although there have been major changes in ITK 4.0, there is likely enough
backward compatibility for this software which only makes use of the image
readers and writers of ITK. Nevertheless, we have NOT tested this software
with ITK 4.0.
- LIBLINEAR >= 1.8
Web Site: http://www.csie.ntu.edu.tw/~cjlin/liblinear/
Download: http://www.csie.ntu.edu.tw/~cjlin/cgi-bin/liblinear.cgi?+http://www.csie.ntu.edu.tw/~cjlin/liblinear+tar.gz
LIBLINEAR is a fast linear SVM solver used in the GONDOLA optimization procedure.
Make sure that you compile both LIBLINEAR and its MATLAB extensions (MEX-files).
- MOSEK >= 6.0
Web Site: http://www.mosek.com/
Download: n/a
This software was tested with version 6.0 of MOSEK. MOSEK is used in optimizing
one of the blocks. Since this is not free software and has a very limited application
within GONDOLA, it has been replaced by an implementation of the
Spectral Projected Gradient (SPG) algorithm. The running time with SPG is noticeably
better than with MOSEK, which is a more general purpose optimization framework.
We therefore do not recommend the use of MOSEK for external use of GONDOLA. The support
for MOSEK has mainly be kept for the further development of GONDOLA or methods derived
from it which may be easier using MOSEK.
- MATLAB >= R2009b
Web Site: http://www.mathworks.com/
Download: n/a
Note that the The Image Processing Toolbox is required by this software.
- MATLAB Image Processing Toolbox
Web Site: http://www.mathworks.com/products/image/
Download: n/a
- MATLAB Compiler >= R2009b
Web Site: http://www.mathworks.com/products/compiler/index.html
Download: n/a
The main gondola program can be either run from within MATLAB or the
command-line as binary exectuable when compiled using the MATLAB Compiler (mcc)
This requires a license for the MATLAB Compiler. Alternatively, BASIS can
generate a Bash or Windows NT Command script which runs the gondola
MATLAB function as follows:
/path/to/bin/matlab -nodesktop -nosplash -nojvm -c "gondola([options])"
While the compilation via the MATLAB Compiler does not require the
installation of all MATLAB source files, should there be no difference
in the running time.
If your GNU Compiler version is not compatible with your version of MATLAB,
you need to install a version which is compatible with the MATLAB Compiler.
You must further ensure to build all build dependencies listed here such
as the in particular the ITK with this version of the GNU Compiler.
Note that for example MATLAB R2010 is not compatible with the GNU Compiler
version >= 4.4, but version <= 4.3.
This software has been tested in particular with GNU Compiler version 4.1.2
on CentOS 5 and version 4.3 on Ubuntu, where the GNU Compiler has been
build from sources on Ubuntu to avoid the incompatibility issue with the
newer compiler version that is installed by default.
- NumPy
Web Site: http://numpy.scipy.org/
Download: http://www.scipy.org/Download
- SBIAUtilities >= 1.0.0
Web Site: n/a
Download: http://www.rad.upenn.edu/sbia/software/distributions/sbiautilities-1.0.0-source.tar.gz
The sbia.utilities.pyxel Python module of the SBIA Utilities package is used to read
and write spreadsheets with the results of the cross-validation experiments in the
CSV format.
- SciPy
Web Site: http://www.scipy.org/
Download: http://www.scipy.org/Download
- Weka >= 3.7.3
Web Site: http://www.cs.waikato.ac.nz/ml/weka/
Download:
Note that the main command-line programs of this software will also work with
Weka 3.6.0. The ranking of the basis vectors, however, requires Weka 3.7.
Build Steps
-----------
The common steps to build, test, and install software based on CMake,
including this software, are as follows:
1. Extract source files.
2. Create build directory and change to it.
3. Run CMake to configure the build tree.
4. Build the software using selected build tool.
5. Test the built software.
6. Install the built files.
On Unix-like systems with GNU Make as build tool, these build steps can be
summarized by the following sequence of commands executed in a shell,
where $package and $version are shell variables which represent the name
of this package and the obtained version of the software.
$ tar xzf $package-$version-source.tar.gz
$ mkdir $package-$version-build
$ cd $package-$version-build
$ ccmake -DBASIS_DIR:PATH=/path/to/basis ../$package-$version-source
- Press 'c' to configure the build system and 'e' to ignore warnings.
- Set CMAKE_INSTALL_PREFIX and other CMake variables and options.
- Continue pressing 'c' until the option 'g' is available.
- Then press 'g' to generate the configuration files for GNU Make.
$ make
$ make test (optional)
$ make install (optional)
An exhaustive list of minimum build dependencies, including the build tools
along detailed step-by-step build, test, and installation instructions can
be found in the corresponding "Building the Software from Sources" section
of the BASIS how-to guide on software installation [2].
Please refer to this guide first if you are uncertain about above steps or
have problems to build, test, or install the software on your system.
If this guide does not help you resolve the issue, please contact us at
<sbia-software at uphs.upenn.edu>. In case of failing tests, please attach
the output of the following command to your email:
$ ctest -V >& test.log
In the following, only package-specific CMake settings available to
configure the build and installation of this software are documented.
CMake Options
-------------
- MOSEK_DIR
- SBIAUtilities_DIR
- PythonModules_DIR
- Weka_DIR
- Weka_PACKAGES_DIR
- ITK_DIR
- LIBLINEAR_DIR
- MATLAB_DIR
Advanced CMake Options
----------------------
- BASIS_COMPILE_MATLAB
- MOSEK_mosekopt_MEX
- PYTHON_EXECUTABLE
- JYTHON_EXECUTABLE
- PythonModules_numpy_DIR
- PythonModules_scipy_DIR
- LIBLINEAR_libsvmread_MEX
- LIBLINEAR_libsvmwrite_MEX
- LIBLINEAR_predict_MEX
- LIBLINEAR_train_MEX
REFERENCES
==========
[1] http://www.rad.upenn.edu/sbia/software/basis/
[2] http://www.rad.upenn.edu/sbia/software/basis/howto/install/