|
Size: 2666
Comment: Added DICOM position tag information.
|
Size: 6622
Comment:
|
| Deletions are marked like this. | Additions are marked like this. |
| Line 2: | Line 2: |
| #acl WikiUserGroup:read,write,delete,revert All:read | |
| Line 3: | Line 4: |
| = Index = | '''Index''' |
| Line 5: | Line 6: |
| [[Navigation(children)]] [[TableOfContents]] |
<<TableOfContents>> |
| Line 8: | Line 8: |
| = File Format Information = | This page is targeted at Martinos Center users who wish develop within the Freesurfer code base and possibly contribute changes. Martinos and non-Martinos users who simply want to clone the repo and build on their home machine, but dont plan on contributing changes, should consult the [[http://surfer.nmr.mgh.harvard.edu/fswiki/freesurfer_linux_developers_page|read-only git repo]]. Lastly, users who just want access to the code can clone directly from the official freesurfer github page: |
| Line 10: | Line 10: |
| == DICOM == === DICOM Resources === [http://medical.nema.org/dicom/2003.html DICOM specification] [[BR]] [http://dclunie.com/medical-image-faq/html/part8.html DICOM informtion sources] |
https://github.com/freesurfer/freesurfer |
| Line 15: | Line 12: |
| === DICOM Position/Orientation Information === DICOM uses a "Tag" to retrieve "Attribute Name" information. The documentation can be found in the [http://medical.nema.org/dicom/2003.html DICOM specification]. The image position and the image orientation section is in Part 3:Information Object Definition, C.7.6.1.1.1 and C.7.6.2.1.1. |
=== Getting the Source Code === |
| Line 18: | Line 14: |
| The DICOM coordinate system is the LPS (left-posterior-superior), meanwhile the RAS coordinate system is right-anterior-superior. | In order to contribute changes to Freesurfer, a specific setup procedure needs to be followed where a users forks the Freesurfer github repository, clones the fork, and submit pull requests. This is described in detail here: |
| Line 20: | Line 16: |
| The tag for the image position is (0x20, 0x32) and returns the x, y, z position of the upper left-hand corner of the image (the center of the first voxel). The tag for the image orientation is (0x20, 0x37) and it returns the direction cosines of the first row and the first column with respect to the patient: first the value for the row x, y, z and then the value for the column x, y, z. For example, I get the string of the form "0.00000\\1.00000\\0.00000\\0.00000\\0.00000\\-1.00000". The tag for the patient orientation is (0x20, 0x20) and it returns the position relative to the image plane by two characters with respect to the positive row axis (left to right) and the positive column axis (top to bottom). The character used are A(anterior), P(posterior), R(right), L(left), H(head), and F(foot). For example, the string I got was "P\\F" (posterior, foot). |
https://surfer.nmr.mgh.harvard.edu/fswiki/Freesurfer_github |
| Line 27: | Line 19: |
| == Medical Image Format FAQ == [http://www.dclunie.com/medical-image-faq/html Medical Image Format FAQ] |
=== Building === |
| Line 30: | Line 21: |
| = CVS Checkout = | Once the source code has been cloned the next step is building it. The steps required to building the Freesurfer code base are described below: |
| Line 32: | Line 23: |
| There are several ways to do: pserver, ext, kserver, gserver. See, e.g. Chapter 2 of [http://cvsbook.red-bean.com/cvsbook.html Open Source Development with CVS] by K. Fogel and M. Bar (2nd Edition, Coriolis Group, 2001). | ==== Setup Configure ==== |
| Line 34: | Line 25: |
| '''pserver''' | It is necessary to run a pre-configure script, to create the platform specific tools required by configure (execute in the {{{freesurfer}}} directory created by {{{git clone}}}). This script runs a set of commands (aclocal, libtoolize, automake v1.9.6, autoconf v2.59) that creates the platform specific files for configure and puts them in the 'fsdev/config' directory. |
| Line 36: | Line 27: |
| `cvs -d :pserver:tosa@cvs.foobar.com:/space/repo/1/dev login` | {{{ ./setup_configure }}} |
| Line 38: | Line 31: |
| where username is "`tosa`" on the server "`cvs.foobar.com`". The cvs depository is `/space/repo/1/dev`. You get asked about the password. Once you stored your authentication in `.cvspass` file, you can run other CVS commands using a similar way. | ==== Configure ==== |
| Line 40: | Line 33: |
| `cvs -d :pserver:tosa@cvs.foobar.com:/space/repo/1/dev co dev` | Now you need to configure your building parameters for your machine by running the {{{configure}}} script. Users at the Martinos Center should for the most part be fine with the default settings, but the {{{configure}}} script does accept many options for pointing to specific libraries and other build specific parameters. One exception is if a user wants to perform a local installation of !FreeSurfer, he/she should use the {{{--prefix}}} flag. Type {{{./configure --help}}} for a full list of options. For example: |
| Line 42: | Line 35: |
| which checkout the entire directory `dev` into the current directory. | {{{ ## Default configuration ./configure |
| Line 44: | Line 39: |
| '''ext''' | ## Specify an installation location ./configure --prefix=~/freesurfer_install_dir |
| Line 46: | Line 42: |
| `export CVS_RSH=ssh` [[BR]] `cvs -d :ext:tosa@cvs.foobar.com:/space/repo/1/dev co dev` |
## See all possible options ./configure --help }}} |
| Line 49: | Line 46: |
| Note that even though CVS_RSH, we use `ssh`, which is a secure shell | Freesurfer builds against the following set of open-sourced libraries, which are installed under the {{{/usr/pubsw/packages}}} directory on all NMR computers: || Package || Version || || Package || Version || || CUDA || v5.0.35-rh5 || || ANN || v1.1 || || tiffjpegglut || v3.6, v6b, v3.7 || || itk || v3.16 || || VTK || v5.6 || || VXL || v1.14 || || MNI || v1.5 || || tcltktixblt || v8.4, v8.4, v8.1, v2.4z || || KWWWidgets || CVS checkout || || Qt || v4.7 || || wxWidgets || v2.8 || || cppunit || v1.10 || || xawplus || v3.1 || || petsc || v2.3 || All these packages will be found by default by the {{{./configure}}} script. But there are options to specify where certain packages exists if a user wishes to build against a different version of one of the open-source libraries. For example: {{{ ## Specify a specific version of qt ./configure --with-qt=/usr/pubsw/packages/qt/4.8.5/bin }}} ==== Compile ==== You can now run 'make' to build the all individual programs in the !FreeSurfer source tree. Binaries will automatically be placed in their individual subdirectories. {{{ make -j 4 }}} ''Handy hint: the -j 4 option to make tells it to run four simultaneous make processes, which, if building on a multi-processor machine, can speed-up the build.'' If you want to compile just one binary at a time, for example, if you are developing an app, than {{{cd}}} to the directory of the program you want and use 'make' to compile it: {{{ cd mri_info make }}} This creates mri_info in the mri_info/ directory. However, be aware the many program depends on the existence of libraries having already been build like libutils. Therefore users will need to build a few of the library directories first (e.g. utils, fsgdf, xml2, etc). ==== Install ==== To initial a local installation, type 'make install' from the top level directory: {{{ make install }}} This will create a local Freesurfer installation in the directory as specified by the {{{--prefix}}} option to {{{configure}}} script (see above). Note that if you do not specify this location, it will try to install to /usr/local, which will probably require root access. The first time you run 'make install', it will take a while to copy all the big data files to the new installation. Subsequent 'make installs' will only copy the changed files. If you only want to install a single binary, run 'make install' from a subdirectory. For example, running 'make install' from the {{{mri_convert}}} directory will copy the {{{mri_convert}}} binary to the proper locations. Running 'make install' from scripts/ will copy all the necessary scripts to the right location. === Adding a new binary to the tree === For this example we will assume you want to create a program called 'MYPROG' and want to add it to the !FreeSurfer tree: 1) Make a directory called {{{MYPROG}}} under the {{{freesurfer}}} directory, and put your source code there. In the simplest case you will have a single source code file called {{{MYPROG.c}}}. {{{ ## Create the MYPROG directory and 'cd' into it mkdir MYPROG cd MYPROG ## The MYPROG.c file goes here }}} 2) Copy {{{freesurfer/dummy/Makefile.am}}} into {{{MYPROG/}}} and customize it, replacing 'dummy' with 'MYPROG'. Also delete the notes that are there. Be sure to change: {{{ bin_PROGRAMS = MYPROG }}} 3) Modify {{{configure.in}}} to add {{{MYPROG/Makefile}}} to the list of files in the definition of {{{AC_OUTPUT}}} (these are in roughly alphabetical order). {{{ ## configure.in ## AC_OUTPUT( ... <list of files> ... MYPROG/Makefile ... <list of files> ... ) }}} 4) Modify {{{freesurfer/Makefile.am}}} to add {{{MYPROG}}} to the {{{MRISUBDIRS}}} or {{{MRISSUBDIRS}}} definition. (You can also alternatively add it to the end of any of the *SUBDIRS categories.) {{{ ## Makefile.am ## MRISUBDIRS= \ ... <list of files> ... MYPROG \ ... <list of files> ... }}} Once these 4 steps are complete MYPROG should automatically be built with the rest of !FreeSurfer. Try following the [[DevelopersGuide_git#Building|building steps from above]] to verify your binary compiles and builds successfully. ---- Send your comments/questions/feedback to zkaufman@nmr.mgh.harvard.edu |
Index
Contents
This page is targeted at Martinos Center users who wish develop within the Freesurfer code base and possibly contribute changes. Martinos and non-Martinos users who simply want to clone the repo and build on their home machine, but dont plan on contributing changes, should consult the read-only git repo. Lastly, users who just want access to the code can clone directly from the official freesurfer github page:
1. Getting the Source Code
In order to contribute changes to Freesurfer, a specific setup procedure needs to be followed where a users forks the Freesurfer github repository, clones the fork, and submit pull requests. This is described in detail here:
2. Building
Once the source code has been cloned the next step is building it. The steps required to building the Freesurfer code base are described below:
2.1. Setup Configure
It is necessary to run a pre-configure script, to create the platform specific tools required by configure (execute in the freesurfer directory created by git clone). This script runs a set of commands (aclocal, libtoolize, automake v1.9.6, autoconf v2.59) that creates the platform specific files for configure and puts them in the 'fsdev/config' directory.
./setup_configure
2.2. Configure
Now you need to configure your building parameters for your machine by running the configure script. Users at the Martinos Center should for the most part be fine with the default settings, but the configure script does accept many options for pointing to specific libraries and other build specific parameters. One exception is if a user wants to perform a local installation of FreeSurfer, he/she should use the --prefix flag. Type ./configure --help for a full list of options. For example:
## Default configuration ./configure ## Specify an installation location ./configure --prefix=~/freesurfer_install_dir ## See all possible options ./configure --help
Freesurfer builds against the following set of open-sourced libraries, which are installed under the /usr/pubsw/packages directory on all NMR computers:
Package
Version
Package
Version
CUDA
v5.0.35-rh5
ANN
v1.1
tiffjpegglut
v3.6, v6b, v3.7
itk
v3.16
VTK
v5.6
VXL
v1.14
MNI
v1.5
tcltktixblt
v8.4, v8.4, v8.1, v2.4z
KWWWidgets
CVS checkout
Qt
v4.7
wxWidgets
v2.8
cppunit
v1.10
xawplus
v3.1
petsc
v2.3
All these packages will be found by default by the ./configure script. But there are options to specify where certain packages exists if a user wishes to build against a different version of one of the open-source libraries. For example:
## Specify a specific version of qt ./configure --with-qt=/usr/pubsw/packages/qt/4.8.5/bin
2.3. Compile
You can now run 'make' to build the all individual programs in the FreeSurfer source tree. Binaries will automatically be placed in their individual subdirectories.
make -j 4
Handy hint: the -j 4 option to make tells it to run four simultaneous make processes, which, if building on a multi-processor machine, can speed-up the build.
If you want to compile just one binary at a time, for example, if you are developing an app, than cd to the directory of the program you want and use 'make' to compile it:
cd mri_info make
This creates mri_info in the mri_info/ directory. However, be aware the many program depends on the existence of libraries having already been build like libutils. Therefore users will need to build a few of the library directories first (e.g. utils, fsgdf, xml2, etc).
2.4. Install
To initial a local installation, type 'make install' from the top level directory:
make install
This will create a local Freesurfer installation in the directory as specified by the --prefix option to configure script (see above). Note that if you do not specify this location, it will try to install to /usr/local, which will probably require root access. The first time you run 'make install', it will take a while to copy all the big data files to the new installation. Subsequent 'make installs' will only copy the changed files.
If you only want to install a single binary, run 'make install' from a subdirectory. For example, running 'make install' from the mri_convert directory will copy the mri_convert binary to the proper locations. Running 'make install' from scripts/ will copy all the necessary scripts to the right location.
3. Adding a new binary to the tree
For this example we will assume you want to create a program called 'MYPROG' and want to add it to the FreeSurfer tree:
1) Make a directory called MYPROG under the freesurfer directory, and put your source code there. In the simplest case you will have a single source code file called MYPROG.c.
## Create the MYPROG directory and 'cd' into it mkdir MYPROG cd MYPROG ## The MYPROG.c file goes here
2) Copy freesurfer/dummy/Makefile.am into MYPROG/ and customize it, replacing 'dummy' with 'MYPROG'. Also delete the notes that are there. Be sure to change:
bin_PROGRAMS = MYPROG
3) Modify configure.in to add MYPROG/Makefile to the list of files in the definition of AC_OUTPUT (these are in roughly alphabetical order).
## configure.in ## AC_OUTPUT( ... <list of files> ... MYPROG/Makefile ... <list of files> ... )
4) Modify freesurfer/Makefile.am to add MYPROG to the MRISUBDIRS or MRISSUBDIRS definition. (You can also alternatively add it to the end of any of the *SUBDIRS categories.)
## Makefile.am ## MRISUBDIRS= \ ... <list of files> ... MYPROG \ ... <list of files> ...
Once these 4 steps are complete MYPROG should automatically be built with the rest of FreeSurfer. Try following the building steps from above to verify your binary compiles and builds successfully.
Send your comments/questions/feedback to zkaufman@nmr.mgh.harvard.edu