Instructions for Compiling, Installing, and running NVM 

NVM - beta release

nvm: A tool for making precise measurements in MR brain images

                Neuromorphometrics, Inc.
                22 Westminster Street
                Somerville, MA  02144-1630  USA

                http://neuromorphometrics.com

                See file "LICENSE.txt" for licensing information
                See file "nvm_version.h" for version information

*************************************************************************
*                                                                       *
*         (c) Copyright 2000-2005 Neuromorphometrics, Inc.              *
*                        All rights reserved                            *
*                                                                       *
*************************************************************************

NOTE: This is a beta release of NVM.  We use it internally and it is being
used at a couple other places, but it is not quite "ready for prime time".
The program works very well for our normal usage.  Any non-standard use
will likely lead to program crashes.  We are releasing it early and often
in the spirit of open source.  The instructions below assume familiarity
with computers and with medical image files.  Attempts by novice computer
users to set up and use NVM will likely be very frustrating.

Since NVM was originally developed for Linux it was meant to be launched
from a command line.  Scripts are included to launch NVM for the Windows
and Macintosh OS X versions.  Proper use of NVM requires a 3 button
mouse.

---------------------------------------------------------------------
                      Contents of this file:
---------------------------------------------------------------------

Linux: Quick start
Linux: Compiling NVM
Windows XP: Running and Building NVM
Macintosh OS X: Running NVM
Running NVM with your own data
 Example: typical usage
 Example: 8-bit single-file scan that is 256x256x256 
Customizing NVM



---------------------------------------------------------------------
        Linux: Quick start (using precompiled binary file)
---------------------------------------------------------------------

NOTE: The following assumes that you want to install NVM in /usr/local.
If you want to put it somewhere else, in the following just change 
</usr/local> to whatever you want.
And where it says "NVM_1.XX", the "XX" indicate the sub-version number.


- Unpack archive file:

  cd /usr/local 		# you must have write permission here
  tar zxf <path-to-downloaded-file>/NVM_1.XX.tgz


- Update symbolic links:

  rm NVM 
  ln -s NVM_1.XX NVM
  cd /usr/local/bin/ 
  rm nvm
  ln -s /usr/local/NVM/build/linux/nvm nvm


- Set environment variable: NVM_HOME

  Put this in your .bashrc file:

    NVM_HOME=/usr/local/NVM; export NVM_HOME

  where <path> is the path to the main nvm source code
  directory.  And since this file was not read when you started your
  current shell, type "source .bashrc"


- Run Netscape (so you can see the help information):

  netscape &


- Change directories and run nvm using test data:

  cd /usr/local/NVM/SegMentor/Test/data/
  ../../../build/linux/nvm -preferences nvm_preferences.xml 11 10

This causes NVM to use the testing version of the preference file
located in that directory.


- Bring up the Help Index page:

  Choose the "Help:Help Index" menu
  Click on "Getting Started" in Netscape


- Run the test script using SegMentor:

  Click on the SegMentor button
  In the SegMentor window, choose the "File:Open" menu
  Click on the "Test" sub-directory
  Click on the file "test.11_10.xml"
  Press "ok"
  Follow the instructions in the SegMentor Window
  Follow along in the "Getting Started" Help document.


---------------------------------------------------------------------
                       Linux: Compiling NVM
---------------------------------------------------------------------

These instructions describe how to build NVM and the packages that it 
needs: Cmake, VTK, and FLTK.  This assumes you have already downloaded
and unarchived the NVM source files.


	Get download files for VTK, Cmake, and FLTK,
cmake-1.6.7-x86-linux.tar
VTKData-4.2.tar
VTK-4.2-LatestRelease.tar
fltk-1.1.4rc2-source.tar


	Choose Install Type of Packages
VTK and FLTK can be built and installed when you won't be changing
versions of them or they can be built and NVM can use the built version
of them. 

	Install Cmake
tar -xvf cmake-1.6.7-x86-linux.tar
	This will extract another tarfile and README
cd /usr/local
su
tar -xvf cmake-1.6.7-x86-linux-files.tar
exit
	to quit su

	Install FLTK
cd ~/NVM
tar -xvf fltk-1.1.4rc2-source.tar
	creates fltk-1.1.4/
cd fltk-1.1.4
./configure
make
	this will take a couple minutes
su
make install
	you can verify install by running fluid

	Install VTK
cd ~/NVM
tar -xvf  VTKData-4.2.tar
tar -xvf VTK-4.2-LatestRelease.tar
	this creates VTKData-release-4-2/ and VTK-4.2.2/
cd VTK-4.2.2
cmake -i
Keep default: not to see advanced options
The following settings need to be changed:
(I'm not positive about examples and hybrid)
	BUILD_EXAMPLES	OFF
	SHARED_LIBS	OFF
	CMAKE_COMPATIBILITY	1.6
	BUILD_TYPE	Debug	recommended
	DATA_ROOT	/home/<user>/NVM/VTKData-release-4-2
	USE_HYBRID	ON
make
	you'll get warnings about deprecated headers
	this will take about 18 minutes
su
make install
	To verify install you can ?

	Configure vtkFLTK
cd NVM/vtkFLTK
cmake (NOW: ccmake .)

	Build NVM
cd ../3D
cmake (NOW: ccmake .)
cd ..
make rebuild
	This should take 2.5 minutes or so


	Run NVM
in NVM
export NVM_HOME=$(pwd)
cd SegMentor/Test/data
./test1

---------------------------------------------------------------------
                Windows XP: Running and Building NVM
---------------------------------------------------------------------

(Only Windows XP is supported, Home, Pro, or Server 2003.)

	Running NVM :

The Windows distribution is a .zip file, NVMwv1.36.zip, which Windows XP
can open and extract.  It's made with 7-zip.

The zip file contains NVM and vtk42
NVMw/{NVM, vtk42}.
It contains dlls needed to run a VisualStudio.Net app.

Extract the files to the drive and folder of your choice,
for example: extract NVMw from the zip file to D:\.

cd D:\NVMw\NVM\platform
runNVMgdf

The .bat file will set up the environment, change to the SegMentor\Test\data\
dir, and run a bat file to run NVM.

To run nvm again from there, 
test3d
or test3dd to run the debug version.

	Building NVM :

Windows build of NVM needs personal.h, which is not supplied.  If you do not
want to turn on any options you may create a blank personal.h.  For the choices of
options see build/personal.env.EXAMPLE and use C++ syntax, instead of makefile syntax.


To build NVM you need VTK, FLTK, and VisualStudio.NET (2002 version, VC7.0 or newer).

VTK4.2 is included in the zip file.

To get FLTK 1.1.4 you can download from http://www.fltk.org/ and install,
or get it from us when we provide the full zip file with VTK and FLTK included.

You can buy Microsoft Visual Studio.NET or you can download the command line compiler/linker for free!
Visual C++ home page:
 http://msdn.microsoft.com/visualc/default.aspx
which should have a link to
"Download the Visual C++ Toolkit 2003"
http://msdn.microsoft.com/visualc/default.aspx
which has a link to the download page:
http://www.microsoft.com/downloads/details.aspx?FamilyId=272BE09D-40BB-49FD-9CB0-4BFA122FA91B&displaylang=en
which has the download, a 32MB file.
 
We use the IDE and build with project files.  If you want to use the free VC++ command line
tools then you will probably need cmake also.  We do not currently support this build approach
but it *should* work.

---------------------------------------------------------------------
                 Macintosh OS X: Running NVM
---------------------------------------------------------------------

Copy all items in the "nvm" disk image into a new folder.

You can run the test script by double-clicking on the "runNVM.command"
shell script.  This script shows the commands to use to run NVM in
a terminal window.  NVM will be run using the testing version of the 
preference file located in that NVM/SegMentor/Test/data directory.

- After NVM launches, bring up the Help Index page:

  Choose the "Help:Help Index" menu
  Click on "Getting Started" in your browser

- Run the test script using SegMentor:

  Click on the SegMentor button
  In the SegMentor window, choose the "File:Open" menu
  Click on the "Test" sub-directory
  Click on the file "test.11_10.xml"
  Press "ok"
  Follow the instructions in the SegMentor Window
  Follow along in the "Getting Started" Help document.

You MIGHT be able to follow the Linux instructions above to build NVM
for the Macintosh.


---------------------------------------------------------------------
                  Running NVM with your own data
---------------------------------------------------------------------
Example: typical usage

 Getting NVM to load an 8-bit single-file scan that is 256x256x256 
 voxels named "CORall" 

 /Data			# root directory containing all project data 
 /Data/77		# directory for all scans for patient number 77
 /Data/77/45		# directory for scan number 45 for this patient
 /Data/77/45/77_45.xml	# the "info" file for this scan giving 
 			  image size, resolution, paths to the 
			  image(s), etc
 /Data/77/45/img	# a directory to hold the scan image data
 /Data/77/45/otl	# a directory to hold results (outline files)
 /Data/77/45/log	# a directory to hold log files

- Create the following directories if they do not exist:

 mkdir /Data
 mkdir /Data/77
 mkdir /Data/77/45
 mkdir /Data/77/45/img

- Put your scan image data into this last directory:

 mv brain_ana.img /Data/77/45/img/	# all slices are in one file

- run NVM:

 nvm 77 45

This will ask to create the "otl" sub-directory, say yes.  Then NVM 
will complaint about some errors when it can't find various files and
it will bring up a window where you can describe your scan image data:

- Set "Data type" to match your voxel size (16 or 8 bit)
- Leave "Mask type" set to "Not a mask".
- Set "Orientation" to Coronal, Sagittal, or Axial if apropriate, 
  otherwise, set this to "Oblique".
- Set "Columns", "Rows", and "Slices" and their resolutions.
- Set "Slices in each file"  to be the number of slices present
  in each data file.  Usually, this will be 1, but if all slices
  are in a single file, enter the same number as "Slices" above.
- Set "File path" to "img/"
- Set "File name" and "File name tail" to describe the file name,
  e.g. use "brain_ana" and ".img" if the file is "brain_ana.img".
  If the slices are in individual files, e.g. "slice_12.img" then
  use "slice_" and ".img" for the namea and tail (respectively).
- If there are multiple slices and if the slice count should have
  leading zeros in it, give the number of zeros, e.g. if the slice
  files are 001.img 002.img ... 128.img, set this to 2.
- Click on "little endian?" if the data was created on a little-endian
  machine.

This will create an "info" file in the /Data/77/45 directory so next 
time you only have to type "nvm 77 45" to load that scan.

If you run into trouble, delete the "info" file and re-run nvm to have
it create a new "info" file:

  rm /Data/77/45/77_45.xml ; nvm 77 45

Or, you can edit the "info" file in a text editor.


---------------------------------------------------------------------
Example: 
 Getting NVM to load an 8-bit single-file scan that is 256x256x256 
 voxels named "CORall" 

Run nvm with the subject and scan number like:
  nvm 78 1

It will say:
  The directory /Data/78 does not exist.  Should it be created?

Say "Yes" and it will create subdirectories:
  /Data/78
  /Data/78/1
  /Data/78/1/log
  /Data/78/1/otl

A window will appear, enter the following:
  Data type: "8 bit unsigned integer"
  Mask type: "Not a mask" (leave alone)
  Orientation: Coronal (or set to whatever it is)

Fill out: 
            number    resolution
  Columns    256          1
     Rows    256          1
   Slices    256          1

Set First Slice to "1" 
Put "256" for the number of slices in each file

Set the actual file path, name, and tail, e.g. for a file called
    '/Image/study/234/CORall' (with no tail) use:
  File path: "/Image/study/234"
  File name: "CORall"
  File name tail: ""

Count with zeros: "no"

Change "little endian" to be checked

The endian part is important because NVM will convert the 8-bit data
to 16 bit and if you don't say "little endian" on a little endian machine
(e.g Linux), it will swap the bytes and corrupt the scan.  You can check
this by taking a histogram of a slice and the range should still be within
0..255.  If you are on a big endian machine (e.g. Macintosh, Sun), UN-check 
the "little endian" box.

NVM will write an "info" file called (in the above case):
  /Data/78/1/78_1.xml

so next time you run NVM like "nvm 78 1" you won't have to enter all that 
stuff again.


---------------------------------------------------------------------
                          Customizing NVM
---------------------------------------------------------------------

NVM is felxible: many settings can be customized by editing your
"preference" file which is normally located in your home directory
and is called, ".nvm_preferences.xml".

If you want to use a different main directory besides "/Data", edit the
"LogFilePath" and "ResultPath" values in your preference file to have
the full or relative path name that you want.  Then make this directory,
e.g., for a preference file line like

 <ResultPath>./ProjectName</ResultPath>

use

 mkdir ./ProjectName

To create a default preference file that you can edit, use the command

 nvm -makepref