forked from sandywang/N3
-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathREADME
271 lines (204 loc) · 11.6 KB
/
README
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
MNI Non-parametric Non-uniformity Normalization (N3) Package
DESCRIPTION
-----------
An artifact often seen in MRI is for the signal intensity to vary smoothly
across an image. Variously referred to as RF inhomogeneity, shading
artifact, or intensity non-uniformity, it is usually attributed to such
factors as poor radio frequency (RF) field uniformity, eddy currents driven
by the switching of field gradients, and patient anatomy both inside and
outside the field of view.
The perl script nu_correct implements a novel approach to correcting for
intensity non-uniformity in MR data that achieves high performance without
requiring supervision. By making relatively few assumptions about the
data, the method can be applied at an early stage in an automated data
analysis, before a tissue intensity or geometric model is available.
Described as Non-parametric Non-uniform intensity Normalization (N3), the
method is independent of pulse sequence and insensitive to pathological
data that might otherwise violate model assumptions. To eliminate the
dependence of the field estimate on anatomy, an iterative approach is
employed to estimate both the multiplicative bias field and the
distribution of the true tissue intensities. Preprocessing of MR data
using N3 has been shown [2] to substantially improve the accuracy of
anatomical analysis techniques such as tissue classification and cortical
surface extraction.
References:
[1] J.G. Sled, A.P. Zijdenbos and A.C. Evans, "A non-parametric method
for automatic correction of intensity non-uniformity in MRI data",
in "IEEE Transactions on Medical Imaging", vol. 17, pp. 87--97,
February 1998.
[2] J.G. Sled, "A Non-parametric Method for Automatic Correction of
Intensity Non-uniformity in MRI Data", Master's Thesis, McGill
University, Montreal, QC, May 1997
(available at http://www.bic.mni.mcgill.ca/~jgsled/thesis/)
[3] J.G. Sled, A.P. Zijdenbos and A.C. Evans, "A Comparison of
Retrospective Intensity Non-uniformity Correction Methods for MRI",
Information Processing in Medical Imaging, pp. 459-464, 1997
GETTING N3
----------
You can obtain a copy of the latest version of the MNI_N3
software from:
http://packages.bic.mni.mcgill.ca/tgz
Look for a file named N3-x.yy.tar.gz (where x.yy is the release
number).
MNI_N3 requires that both the MINC and netCDF packages be built and
installed first. The MINC file format is a highly flexible medical
image file format built on top of the netCDF generalized data format.
You will also need Perl 5, version 5.003 or later.
You can always find the latest version of Perl at at any
mirror of the Comprehensive Perl Archive Network (CPAN), in src/5.0/.
Lastly, you will need the perl library mni_perllib available at
http://packages.bic.mni.mcgill.ca/tgz
INSTALLATION
------------
In order to make the MNI N3 utilities:
0a) You will need a recent version (egcs-1.0 or later) of the GNU C++
compiler (g++) unless you are compiling under IRIX (see below).
GNU C++ can be obtained at
http://gcc.gnu.org/
In addition, you will also need a GNU version of make (gmake on
some systems), available at any GNU ftp site.
ftp://prep.ai.mit.edu/pub/gnu/
0b) SGI users do not need to obtain g++ as N3 will also compile using
the DCC compiler packaged with IRIX. SGI users still, however, need
to obtain a version of GNU make.
1) You may have to build and install the netCDF library.
2) You may have to build and install the MINC library
(check that you have version 0.6 or later).
3) You may have to build and install Perl 5. (check using perl -V that
it is version 5.003 or later)
4) You may have to build and install the mni_perllib package. If you
decide not to install the library in its default location
(/usr/local/lib/perl5/site_perl on many systems) then you will
need to set your PERLLIB environment variable. For example, if you
were to install the libraries to /usr/local/mni/lib/perl5 then you
would set the PERLLIB variable with
setenv PERLLIB /usr/local/mni/lib/perl5
(assuming you use a csh-variant) in your ~/.cshrc or the global
/etc/cshrc file. (Or, if you're a Bourne-shell, ksh, zsh, or bash
type of person, put
PERLLIB=/usr/local/mni/lib/perl5/site_perl ; export PERLLIB
in ~/.profile or /etc/profile.)
Also, note that during installation of the mni_perllib package you
will be queried for the default location where model data included
with the MNI_N3 package will be stored. In the future, most MNI
software packages will install their model data in a subdirectory of
a common data directory, which by default is called /usr/local/mni/data.
While the default location of model data can be overridden on a
package by package basis, doing so will require each user to specify
the model data's location using the environment variable
MNI_DATAPATH.
5) We have used the GNU autoconf program to create a `configure'
script that will automatically determine various system-
dependent values and generate Makefiles needed to
build the package.
In the directory where you unpacked the N3 tar file,
type
./configure
`configure' works by poking around your system to determine all
the system-specific values needed to build and install
MNI_N3. Once it has done that, it creates Makefile.include,
which is the granddaddy Makefile used by all the programs in the
package. If `configure' runs successfully, skip to step 7 below.
If `configure' complains about not being able to find certain
things, though, you may have to give it some hints. In
particular, this be necessary if you have installed netCDF, MINC,
Volume_IO, or Perl 5 in weird places. The easiest way to do that
is with the --prefix option; for instance, at the MNI, we keep
home-grown software under /usr/local/bic, so here we run
`configure' like this:
./configure --prefix=/usr/local/bic
and the MINC and Volume_IO files will be found in various
directories under /usr/local/bic. (netCDF is *not* home-grown, so
we keep it under /usr/local. Luckily, `configure' is smart enough
to look there if all else fails.)
If you simply can't get `configure' to find some files, you can set
various environment variables, e.g. NETCDF_INCLUDE to specify the
directory where netcdf.h lives. For instance, if you installed netCDF
to /tmp, its include file would be in /tmp/include, and you could
say:
env NETCDF_INCLUDE=/tmp/include ./configure
Here are all the environment variables you might want to set to
help configure find things:
NETCDF_INCLUDE where to find netCDF header (netcdf.h)
NETCDF_LIB where to find netCDF library (libnetcdf.a
on most Unix-like systems)
MINC_INCLUDE where to find MINC header (minc.h)
MINC_LIB where to find MINC library (libminc.a)
VOLUMEIO_INCLUDE where to find Volume_io headers (volume_io.h,
volumes.h, etc.)
VOLUMEIO_LIB where to find Volume_io library (libvolume_io.a)
PERL where to find Perl binary (must be Perl 5.003)
Note that these are all *inputs* required to build N3.
There are also a number of output directories that determine where
various files are installed to; these are explained below.
If you have built shared-library versions of netCDF, MINC, or
Volume_io, configure should be able to find these. It looks for
libraries first with a ".a" extension, then with ".so"; this
appears to be a quite common convention under various Unices, and
is known to work under IRIX and Linux. If your system has a
different scheme for naming shared libraries, you might need to
set the LIBEXT variable; e.g. to only look for ".so" files,
env LIBEXT=".so" ./configure
(LIBEXT is just a space-separated list of extensions, including
the dot on each one.)
6) You might also want to set various site-specific installation
directories when running `configure'. MNI_N3 installs many
files in various directories, and expects to find other files in
certain directories, so it's important to know where you want
stuff to go. By default, it all gets put under /usr/local, unless
you specify a different base directory with `--prefix'). In
particular:
binary executables: /usr/local/bin
scripts: /usr/local/bin
average brain mask: /usr/local/share/N3
(Binaries and scripts are distinguished in case you have a
multi-platform environment and want to share scripts between
machines, e.g. using /usr/local/share.) All of these
directories can be customized, either by setting an environment
variable before running `configure' or by editing
Makefile.include after `configure' has run. If you wish to use
environment variables, set them as follows:
BINDIR directory for binary executables
SCRIPTDIR directory for scripts (machine-independent executables)
Note that if you feel like setting ALL of these (e.g., to install
MNI_N3 to /tmp or your home directory), you're probably
better off to use `--prefix'.
If you prefer to edit Makefile.include, just read the instructions
there -- but be warned that any changes you make will be lost if
you re-reun `configure'!
7) In the directory where you have unpacked both the MNI_N3 package and
the test data, type:
make build
make test
make install
Note that you may need to set the environment variable TMPDIR to some
more appropriate place than /usr/tmp on systems where /usr/tmp has
little available space.
8) Now, you're ready to test nu_correct on real data. Start by typing
nu_correct -help
nu_correct makes use of a number of other binaries and scripts that
are also useful on their own. Their functionality is summarized below:
nu_correct estimates and removes intensity non-uniformity from
a volume.
nu_estimate estimates the intensity non-uniformity in a volume, storing
the result in a compact format referred to as an .imp file.
nu_evaluate corrects the intensity non-uniformity in a volume using
the given .imp file.
imp2field expands an .imp file into a MINC volume representation
of the correction field.
field2imp converts a MINC volume representation of a correction
field into an .imp file.
volume_stats prints a variety of summary statistic for a volume
or region of interest.
volume_hist produces a histogram of a volume.
spline_smooth smoothes a volume using tensor cubic B splines or thin
plate splines.
Further information
For further information you may want to checkout the N3 home page at
http://www.bic.mni.mcgill.ca/software/N3 where you can find the FAQ for
N3. Also, you can write to me, John Sled, at:
John Sled
McConnell Brain Imaging Centre Tel: (514) 398-8547
Montreal Neurological Institute Fax: (514) 398-8948
3801 University Street, Room WB208 Email: jgsled@bic.mni.mcgill.ca
Montreal, Quebec H3A 2B4 Canada