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 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 /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 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//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 Build NVM cd ../3D cmake 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 ./ProjectName use mkdir ./ProjectName To create a default preference file that you can edit, use the command nvm -makepref