View source for Projects:MATLABSlicerExampleModule

<font color="red">'''See the [http://www.slicer.org/slicerWiki/index.php/Documentation/Nightly/Extensions/MatlabBridge MatlabBridge] extension for a comprehensive solution for calling Matlab functions from Slicer'''</font>
 Back to [[Algorithm:GATech|Georgia Tech Algorithms]], [[Engineering:Isomics|Isomics Engineering]]
= MATLAB Slicer Example Module =

The aim of this project to provide a simple command-line module which enables MATLAB code to run within Slicer3.  In other words, Slicer3 is used for data I/O, parameter setting, and visualizations.  Then, behind-the-scenes, MATLAB code is called to perform image analysis computations.

[http://teem.sourceforge.net/ TEEM] is used to pass data back-and-forth between MATLAB and Slicer3, using TEEM-based nrrdLoadWithMetadata() and nrrdSaveWithMetadata() functions.

= Description of the Slicer3 Module =

== Download ==

Download the latest (last updated: 07 Sep 2008):  [[Media:MATLABSlicerExampleModule.zip|MATLABSlicerExampleModule.zip]]

Files included in the Download:
* CLI-shell.sh - The command-line interface TCL shell script. This currently works only in Linux. Two lines towards the bottom must be edited to point to the proper places, see the comments at the end of the file.
* MATLAB/
** compilethis.m - this MATLAB script contains all of the information to be able to compile the nrrdLoadWithMetadata() and nrrdSaveWithMetadata() functions using Slicer3's TEEM libraries. Open it up and follow the instructions.
** nrrdLoadWithMetadata.c - this c function is used to load nrrd data into MATLAB with the header metadata information (currently supports all NRRD files that do not use key/value information and also has limited support for DWMRI key/value information).
** nrrdLoadWithMetadata.m - a MATLAB help file, which can be used within MATLAB by typing "help nrrdLoadWithMetadata"
** nrrdLoadWithMetadata.mexglx/.mexw32 - precompiled 32-bit functions (may not work for you until you recompile with the compilethis.m script).
** nrrdSaveWithMetadata.c - this c function is used to save nrrd data from MATLAB with the header metadata information (currently supports all NRRD files that do not use key/value information but does not support any key/value information).
** nrrdSaveWithMetadata.m - a MATLAB help file, which can be used within MATLAB by typing "help nrrdSaveWithMetadata"
** nrrdSaveWithMetadata.mexglx/.mexw32 - precompiled 32-bit functions (may not work for you until you recompile with the compilethis.m script).
** MATLABSlicerExampleModule.m - This is the MATLAB script which actually processes the data.  This is the part that can be replaced with your MATLAB script.

== Install and Run the Example Module ==

To try this out, DO THE FOLLOWING (Linux only):
# Make sure you have tclsh installed
# Download the zip file above
# Edit compilethis.m (follow the instructions inside the file) & and run within MATLAB to compile the nrrdLoadWithMetadata and nrrdSaveWithMetadata functions.
# Edit CLI-shell.sh (follow the instructions inside the file)
# Add the path in Slicer3 to point to this module:  View->Application Settings->Module Settings->Add a preset
# Close Slicer3 and Reopen Slicer3
# Slicer3 will autodetect the example MATLAB module
# Load in some data
# Select the example module, set the two inputs and the two outputs, and press "Apply"
# If there are errors, it is likely due to messed up paths in your CLI-shell.sh script.

== Description of nrrdLoadWithMetadata() ==
<pre>
% This function loads a nrrd volume into MATLAB with the associated
% metadata. Input is a string with the nrrd volume filename. Output
% is a struct containing the data and the metadata.
%
% The struct obeys the following conventions:
% - The fields in the struct are ordered as follows:
% -- 00 = data              (void *) nrrd->data
% -- 01 = space             (int) nrrd->space [enum]
% -- 02 = spacedirections   (double matrix) nrrd->axis[NRRD_DIM_MAX].spaceDirection[NRRD_SPACE_DIM_MAX]
% -- 03 = centerings        (int array) nrrd->axis[NRRD_DIM_MAX].center [enum]
% -- 04 = kinds             (int array) nrrd->axis[NRRD_DIM_MAX].kind [enum]
% -- 05 = spaceunits        (char * array) nrrd->spaceUnits[NRRD_SPACE_DIM_MAX]
% -- 06 = spaceorigin       (double array) nrrd->spaceOrigin[NRRD_SPACE_DIM_MAX]
% -- 07 = measurementframe  (double matrix) nrrd->measurementFrame[NRRD_SPACE_DIM_MAX][NRRD_SPACE_DIM_MAX]
% -- OPTIONAL:
% -- 08 = modality          (string) nrrd->kvp[1]
% -- 09 = bvalue            (double) bKVP
% -- 10 = gradientdirections(double matrix) info[dwiIdx]
</pre>

== Description of nrrdSaveWithMetadata() ==
<pre>
% This function saves a nrrd volume into MATLAB with the associated
% metadata. First input is a string with the nrrd volume
% filename. Second input is a MATLAB struct containing the data and
% the metadata according to the following conventions.
%
% The struct obeys the following conventions:
% - The fields in the struct are ordered as follows:
% -- 00 = data              (void *) nrrd->data
% -- 01 = space             (int) nrrd->space [enum]
% -- 02 = spacedirections   (double matrix) nrrd->axis[NRRD_DIM_MAX].spaceDirection[NRRD_SPACE_DIM_MAX]
% -- 03 = centerings        (int array) nrrd->axis[NRRD_DIM_MAX].center [enum]
% -- 04 = kinds             (int array) nrrd->axis[NRRD_DIM_MAX].kind [enum]
% -- 05 = spaceunits        (char * array) nrrd->spaceUnits[NRRD_SPACE_DIM_MAX]
% -- 06 = spaceorigin       (double array) nrrd->spaceOrigin[NRRD_SPACE_DIM_MAX]
% -- 07 = measurementframe  (double matrix) nrrd->measurementFrame[NRRD_SPACE_DIM_MAX][NRRD_SPACE_DIM_MAX]
% -- NOT YET IMPLEMENTED:
% -- 08 = modality          (string) nrrd->kvp[1]
% -- 09 = bvalue            (double) bKVP
% -- 10 = gradientdirections(double matrix) info[dwiIdx]
</pre>

== Documentation for the enums used in TEEM-1.9.0 ==
<pre>
%
% The following is an expansion of the enums for TEEM-1.9.0
%
% -- 01 = space:
%   nrrdSpaceUnknown,
%   nrrdSpaceRightAnteriorSuperior,     /*  1: NIFTI-1 (right-handed) */
%   nrrdSpaceLeftAnteriorSuperior,      /*  2: standard Analyze (left-handed) */
%   nrrdSpaceLeftPosteriorSuperior,     /*  3: DICOM 3.0 (right-handed) */
%   nrrdSpaceRightAnteriorSuperiorTime, /*  4: */
%   nrrdSpaceLeftAnteriorSuperiorTime,  /*  5: */
%   nrrdSpaceLeftPosteriorSuperiorTime, /*  6: */
%   nrrdSpaceScannerXYZ,                /*  7: ACR/NEMA 2.0 (pre-DICOM 3.0) */
%   nrrdSpaceScannerXYZTime,            /*  8: */
%   nrrdSpace3DRightHanded,             /*  9: */
%   nrrdSpace3DLeftHanded,              /* 10: */
%   nrrdSpace3DRightHandedTime,         /* 11: */
%   nrrdSpace3DLeftHandedTime,          /* 12: */
%   nrrdSpaceLast
%
% -- 03 = centerings:
%   nrrdCenterUnknown,         /* 0: no centering known for this axis */
%   nrrdCenterNode,            /* 1: samples at corners of things
%                                 (how "voxels" are usually imagined)
%                                 |\______/|\______/|\______/|
%                                 X        X        X        X   */
%   nrrdCenterCell,            /* 2: samples at middles of things
%                                 (characteristic of histogram bins)
%                                  \___|___/\___|___/\___|___/
%                                      X        X        X       */
%   nrrdCenterLast
%
% -- 04 = kinds:
%   nrrdKindUnknown,
%   nrrdKindDomain,            /*  1: any image domain */
%   nrrdKindSpace,             /*  2: a spatial domain */
%   nrrdKindTime,              /*  3: a temporal domain */
%   /* -------------------------- end domain kinds */
%   /* -------------------------- begin range kinds */
%   nrrdKindList,              /*  4: any list of values, non-resample-able */
%   nrrdKindPoint,             /*  5: coords of a point */
%   nrrdKindVector,            /*  6: coeffs of (contravariant) vector */
%   nrrdKindCovariantVector,   /*  7: coeffs of covariant vector (eg gradient) */
%   nrrdKindNormal,            /*  8: coeffs of unit-length covariant vector */
%   /* -------------------------- end arbitrary size kinds */
%   /* -------------------------- begin size-specific kinds */
%   nrrdKindStub,              /*  9: axis with one sample (a placeholder) */
%   nrrdKindScalar,            /* 10: effectively, same as a stub */
%   nrrdKindComplex,           /* 11: real and imaginary components */
%   nrrdKind2Vector,           /* 12: 2 component vector */
%   nrrdKind3Color,            /* 13: ANY 3-component color value */
%   nrrdKindRGBColor,          /* 14: RGB, no colorimetry */
%   nrrdKindHSVColor,          /* 15: HSV, no colorimetry */
%   nrrdKindXYZColor,          /* 16: perceptual primary colors */
%   nrrdKind4Color,            /* 17: ANY 4-component color value */
%   nrrdKindRGBAColor,         /* 18: RGBA, no colorimetry */
%   nrrdKind3Vector,           /* 19: 3-component vector */
%   nrrdKind3Gradient,         /* 20: 3-component covariant vector */
%   nrrdKind3Normal,           /* 21: 3-component covector, assumed normalized */
%   nrrdKind4Vector,           /* 22: 4-component vector */
%   nrrdKindQuaternion,        /* 23: (w,x,y,z), not necessarily normalized */
%   nrrdKind2DSymMatrix,       /* 24: Mxx Mxy Myy */
%   nrrdKind2DMaskedSymMatrix, /* 25: mask Mxx Mxy Myy */
%   nrrdKind2DMatrix,          /* 26: Mxx Mxy Myx Myy */
%   nrrdKind2DMaskedMatrix,    /* 27: mask Mxx Mxy Myx Myy */
%   nrrdKind3DSymMatrix,       /* 28: Mxx Mxy Mxz Myy Myz Mzz */
%   nrrdKind3DMaskedSymMatrix, /* 29: mask Mxx Mxy Mxz Myy Myz Mzz */
%   nrrdKind3DMatrix,          /* 30: Mxx Mxy Mxz Myx Myy Myz Mzx Mzy Mzz */
%   nrrdKind3DMaskedMatrix,    /* 31: mask Mxx Mxy Mxz Myx Myy Myz Mzx Mzy Mzz */
%   nrrdKindLast
</pre>

== Support ==

Contact John Melonakos (jmelonak <at> ece.gatech.edu) if you have questions.  This project is currently in beta phase and is seeking input from the broader community.

=2011 Updates=

The published code relies on an earlier release of Slicer, which used teem 1.9.0. You can download that version of teem here: http://sourceforge.net/projects/teem/files/teem/1.9.0/ and compile separately. While configuring, set BUILD_SHARED_LIBS to ON, and TEEN_ZLIB to ON. Add the directory ${TEEM_BIN_HOME}/bin to your $LD_LIBRARY_PATH.

= Key Investigators =

* Georgia Tech: John Melonakos (jmelonak <at> ece.gatech.edu), Yi Gao, Allen Tannenbaum
* Isomics: Steve Pieper
* BWH: C-F Westin, Gordon Kindlmann

[[Category:Slicer]]