\documentclass[12pt]{article}
\usepackage{html,htmllist}

\topmargin 0in
\evensidemargin 0in
\oddsidemargin  0in

\pagestyle{empty}
\bibliographystyle{abbrv}
%\def\singlespace {\renewcommand{\baselinestretch}{1}\small\normalsize}
%\def\doublespace {\renewcommand{\baselinestretch}{1.55}\small\normalsize}

\setlength{\parindent}{0in}
\setlength{\parskip}{.15in}

%begin{latexonly}
\long\def\myverb#1{\def\next{#1}%
  {\tt\frenchspacing\expandafter\strip\meaning\next}}
\def\strip#1>{}  
%end{latexonly}
\begin{htmlonly}
  \newcommand{\myverb}[1]{#1}
\end{htmlonly}

\begin{document}

\begin{center}
\LARGE{The MNI\_ANIMAL Software Package\\
An Automated Non-Linear Registration Package
for Stereotaxic Transformation of MRI data.}\\[1em]
\large{Version 0.5 (second alpha release)}\\
\today
\end{center}

\begin{htmlonly}
  This is the home page of the MNI\_ANIMAL software package.  You can find
  a pre-release version of ANIMAL here, for use only within the
  MNI. (Actually, people from the outside are welcome to grab what hey
  want, but no support is offered or available.)  

  Note that it is best not to use ANIMAL directly, but to drive it with the
  new version of MRITOTAL contained here, since it contains a
  multi-resolution, heirarchical fitting strategy.

  If you are interested in obtaining and installing MNI\_ANIMAL or just
  finding out more about it, you can follow these links:
  \tableofchildlinks*
\end{htmlonly}

\section*{What is MNI\_ANIMAL?}

One of the main sources of difficulty when comparing anatomical data from a
number of subjects is anatomical variability.  Even after automatic linear
registration \cite{Collins94a}, there remains a residual non-linear
component of spatial mis-registration among brains that is largely due to
normal anatomical morphometric variability that can account for a
difference in position of up to 1-2cm for the same anatomical landmark
between subjects.

We have developed a completely automatic method, based on multi-scale,
three dimensional (3D) cross-correlation, to non-linearly register two MRI
volumes together, thus reducing the residual mis-registration remaining
after linear alignment.  

Spatial registration is completed automatically as a two step process.  The
first \cite{Collins94a} accounts for the linear part of the transformation
by using correlation between Gaussian-blurred features extracted from both
volumes.  In the second step, ANIMAL estimates the 3D deformation field
\cite{Collins96a} required to account for this variability.  The
deformation field is built by sequentially stepping through the target
volume in a 3D grid pattern.  At each grid-node $i$, the deformation vector
required to achieve local registration between the two volumes is found by
optimization of 3 translational parameters ($tx_i$,$ty_i$,$tz_i$) that
maximize the objective function evaluated only in the neighbourhood region
surrounding the node.  The algorithm is applied iteratively in a
multi-scale hierarchy, so that image blurring and grid size are reduced
after each iteration, thus refining the fit.


A Perl script (\verb?nlfit?) implements the multi-resolution fitting
strategy that has been used to map more than 600 brains into stereotaxic
space at the Montreal Neurological Institute.  At the heart of this
procedure is a new version of \verb?minctracc?, the program that
automatically finds the best non-linear transformation to map one
volumetric data set (stored in MINC format) on to another.  The program
uses optimization over a user selectable number of parameters to identify
the best transformation mapping voxel values of the first data set into the
second.

\begin{thebibliography}{1}
\bibitem{Collins94a} D.~L.  Collins, P. Neelin, T.~M.  Peters and A.~C.
  Evans, 
  ``Automatic 3D Inter-Subject Registration of MR Volumetric Data in
  Standardized Talairach Space,'' {\em Journal of Computer Assisted
    Tomography}, 18(2) pp192-205, 1994.  
\bibitem{Collins96a}
D.~L. Collins, C.~J. Holmes, T.~M. Peters, and A.~C. Evans, ``Automatic {3D}
  model-based neuro\-anatomical segmentation,'' {\em Human Brain Mapping},
  vol.~3, no.~3, pp.~190--208, 1995.

\end{thebibliography}

\section*{Getting MNI\_ANIMAL}

You can obtain a copy of the latest version of the MNI\_ANIMAL
software using anonymous FTP from:
\begin{description}
  \item
    \htmladdnormallink{\myverb{ftp://ftp.bic.mni.mcgill.ca/pub/mni_autoreg/}}
                      {ftp://ftp.bic.mni.mcgill.ca/pub/mni_autoreg/}
\end{description}
    
Look for a file named \verb?mni_animal-x.yy.tar.gz? (where \verb?x.yy?  is
the release number).  You'll need \verb?mni_animal-0.5.tar.gz? with
\verb?mni_autoreg-0.98d.tar.gz? or \verb?mni_animal-0.6.tar.gz? with
\verb?mni_autoreg-0.98e.tar.gz?.

MNI\_ANIMAL requires MNI\_Autoreg, since MNI\_ANIMAL is essentially copied
and built on top of the MNI\_Autoreg package (see the
\htmladdnormallink{\myverb{MNI_AutoReg}}
{http://www.bic.mni.mcgill.ca/software/mni_autoreg/} home page; you'll need
\verb+mni_autoreg-0.98d+ or later).  The MNI\_ANIMAL package replaces the
\verb?minctracc?  program and contains scripts to do non-linear
registration.


\section*{Installation}

It should be relatively easy to build the beta version of the MNI\_ANIMAL
package.  The tarfile \verb?mni_animal-x.yy.tar.gz? must be untarred within
the root of the \verb?mni_autoreg? directory tree after the MNI\_AutoReg package
has been built.  

I assume that all MNI\_AutoReg targets are built and installed before
building animal.  Note that a make clean should not be done, since some
of the programs are needed to run the tests below.
 
\begin{enumerate}
\item
  Get, build, test and install the MNI\_Autoreg package.  See the 
  \htmladdnormallink{\myverb{MNI_AutoReg}}
  {http://www.bic.mni.mcgill.ca/software/mni_autoreg/} home page (you'll
  need \verb?mni_autoreg-0.98d? or later).

  Do not run \verb?make clean? - MNI\_ANIMAL needs all the files in the
  MNI\_Autoreg directory.

\item
  Untar the the MNI\_ANIMAL package \verb?mni_animal-x.yy.tar.gz? from
  within the root of the MNI\_AutoReg package.

  \begin{description}
  \item \verb?cd /your/dir/package/mni_autoreg-0.98?
  \item \verb?guntar -xvfz mni_animal-0.5.tar.gz?
  \end{description}
  
\item
  Once untarred, there should be a file called \verb?build_animal? in the
  MNI\_AutoReg directory.  Look at it to make sure that things look ok,
  and then execute it.
  
  The \verb?build_animal? script will overwrite a few source files in the
  minctracc subdirectory and then rebuild the nonlinear version of
  \verb?minctracc? and rename it to \verb?animal?.  It will also build the
  \verb?mincbbox? program.

  Once compilation is completed, the \verb?build_animal? script will run a
  simple test on \verb?minctracc/animal? to exercise the code.  When
  completed, the volume correlation should close to 0.00465932.  If you are
  interested, you can use \verb?mincresample? to transform
  \verb?Testing/object1.mnc? like \verb?Testing/object2.mnc? using the
  recovered transformation and then look at the result with register.  For
  example type:
  
  \begin{description}
  \item
    \verb?cd /your/dir/package/mni_autoreg-0.98/Testing?
  \item
    \verb?mincresample object1.mnc object1_rsl.mnc -like object2.mnc -transformation ../animal.xfm?
  \item
    \verb?register object1_rsl.mnc object2.mnc?
  \end{description}

\item
  \verb?nlfit? is a development version of the non-linear stereotaxic
  registration script that will eventually replace \verb?mritotal? (from
  the MNI\_AutoReg package).  It calls \verb?animal? to do the non-linear
  registrations in a heirarchical multi-resolution strategy, and permits
  the user to control the start and stop resolutions of the fit.

  There are three lines that may have to be changed so that \verb?nlfit?
  will be able to locate configuration and model files normally used with
  \verb?mritotal?.  You should use your installed version of
  \verb?mritotal? to get the values for your system. The following lines of
  \verb?nlfit? have to be edited by hand:

  \begin{htmllist}
  \item[line 1:]    verify the path to perl5
  \item[line 572:] \$ModelDir = "/data/avgbrain1/brain/images/model"; make
    sure that the \$ModelDir is the same as line 500 of mritotal
  \item[line  612:] @ConfigPath = (\$ENV{"HOME"}, "/usr/local/mni/etc/mni_autoreg");
             make sure that the path is the same as line 530 of mritotal
           \end{htmllist}
\item
  Once completed, you will have to manually install the following files to
  your bin directory:

  \begin{itemize}
  \item \verb?minctracc/animal?
  \item \verb?minctracc/reversedef?
  \item \verb?mincbbox/mincbbox?
  \item \verb?./nlfit?
  \item \verb?./xfmtool?
  \item \verb?./make_model?
  \end{itemize}

  and copy the following file to your model directory (the same as line 572
  of \verb?nlfit-0.5?):

  \begin{itemize}
  \item \verb?./average_305_headmask.mnc?
  \end{itemize}
  
  Check out the \verb?NONLIN_README? file for more specific information
  (man page-like) on ANIMAL.

\end{enumerate}
    

\section*{System requirements and Portability}

We have gone to great lengths to ensure that MNI\_ANIMAL compiles and
runs correctly on a variety of Unix and Unix-like systems.  However, we
only have ready access to Linux, IRIX, and SunOS systems; successful use
of the package on other systems is not necessarily assured.  (For that
matter, its successful use anywhere is not assured -- you get what you
pay for!  See the copyright \ref{copyright}.)

That said, if you have trouble building and/or testing the package, we'd
like to hear about it.  But just telling us "it didn't build" or "a test
failed" is not enough -- ideally, you would provide us with a detailed
breakdown of your system configuration (architecture, operating system
and OS version, compiler and compiler version, C library -- including
header files -- and its version), and a comprehensive explanation of
what went wrong and how we can fix it without interfering with
portability to any {\em other} system.  We don't expect that every bug
report will have this amount of information, but keep in mind that
that's the ideal to strive for.

Please do not complain of portability problems unless you have first
made sure that your C compiler and library (including header files!) are
ANSI compliant.

\section*{Configuration and Protocol Files}

\verb?nlfit?  uses the same two external configuration files as
\verb?mritotal?, and are installed when MNI\_AutoReg is installed. There is
nothing extra to install for MNI\_ANIMAL.  

The two files are the configuration file (mritotal.cfg) and protocol file
(default is mritotal.default.cfg, but you can specify others using the
-protocol option).  If you follow all the instructions for installation of
MNI\_AutoReg, then these files will be correctly customized and installed
for your site.  If things go wrong, though, you should know the following:

\begin{itemize}
\item The directory where the configuration and protocol file(s) are
  installed defaults to \verb?/usr/local/etc/mni_autoreg?.  If you change
  this (ie. move the files after installing them) {\em without} changing
  \verb?Makefile.include? and doing "\verb?make build?" in the
  "\verb?perl/?" subdirectory, then mritotal will not be able to find them.
  That's because "\verb?make build?" modifies mritotal so that it points to the
  directory for config files.
 
\item The location of the model files is specified in the configuration
  file.  You should check that the directory where you installed the model
  files (which is specified in the \verb?Makefile? for the
  \verb?mni_autoreg_model? package) is the same as the directory given in
  \verb?mritotal.cfg? (using the \verb?-modeldir? option).  For instance,
  if \verb?mni_autoreg_model/Makefile? has the line:

     \begin{description}
     \item \verb?MODELDIR    = /data/avgbrain1/brain/images/model?
     \end{description}
        
     then \verb?mni_autoreg-0.98/perl/mritotal.cfg? should have the line:

     \begin{description}
     \item \verb?-modeldir /data/avgbrain1/brain/images/model?
     \end{description}

     and, if you want to be really complete, 
     \verb?mni_autoreg-0.98/Makefile.include? should have the line

     \begin{description}
     \item \verb?MODELDIR = /data/avgbrain1/brain/images/model?
     \end{description}
     

   \item If you find it necessary to make a new protocol for your site's
     data (for instance, if your MRI data consistently covers considerably
     more than the brain, but the heuristic used by the default protocol
     doesn't work -- see the mritotal man page for more information), then
     you should copy and change the default protocol file.  For instance,
     you might want to call the protocol "\verb?mysite?" -- in that case,
     copy \verb?mritotal.default.cfg? to \verb?mritotal.mysite.cfg?, and be
     {\em sure} to edit \verb?mritotal.cfg? so that it uses the new protocol by
     default.  That is, make sure it has "\verb?-protocol mysite?" instead
     of "\verb?-protocol default?".
\end{itemize}

That said, please notify Louis Collins
\htmladdnormallink{\myverb{<louis@bic.mni.mcgill.ca>}}{mailto:louis@bic.mni.mcgill.ca}
if the heuristics used by the default protocol don't work for your data.

\section*{Copyright}\label{copyright}



\centerline{MNI\_ANIMAL}

\centerline{Montreal Neurological Institute Automated Linear Registration Package}

Copyright (C) 1993-1998 Louis Collins and Greg Ward, McConnell Brain
Imaging Centre, Montreal Neurological Institute, McGill University.
Permission to use, copy, modify, and distribute this software and its
documentation for any purpose and without fee is hereby granted, provided
that the above copyright notice appear in all copies.  The authors and
McGill University make no representations about the suitability of this
software for any purpose.  It is provided "as is" without express or
implied warranty.  The authors are not responsible for any data loss,
equipment damage, property loss, or injury to subjects or patients
resulting from the use or misuse of this software package. The results of
any MNI\_ANIMAL registration should always be carefully checked by visual
inspection in all three spatial dimensions. MNI\_ANIMAL registrations
should never be used in a setting where an incorrect result could injure a
patient or subject or lead to an incorrect diagnosis. This package is
provided for research use only.

We make no warranty that this package is free of conceptual or programming
errors. The fact that this package has been provided to you does not imply
or assure any additional support beyond what is provided in this document.
Likewise, it does not guarantee that you will be notified of any
programming errors that are discovered or that you will be provided with
future updated versions of the software. The authors disclaim all liability
for direct or indirect damages resulting from your use of Montreal
Neurological Institute Automated NonLinear Registration Package.

We would appreciate that at least the following articles be referenced to
describe the registration method in all publications of data analyzed using
the MNI\_ANIMAL package:

DL Collins, P Neelin, TM Peters and AC Evans, Automatic 3D Inter-Subject
Registration of MR Volumetric Data in Standardized Talairach Space, Journal
of Computer Assisted Tomography, 18(2) p192-205, 1994 (for linear
registration)

DL Collins, CJ Holmes, TM Peters, and AC Evans, Automatic 3D model-based
neuro-anatomical segmentation, Human Brain Mapping, vol.~3, no.~3,
pp.~190--208, 1995 (for non-linear registration)


\section*{Further information}

Good luck!  Please let us know if anything goes wrong with the
installation or testing:

\begin{tabular}{@{}lll}
Louis Collins                  &         & \\
McConnell Brain Imaging Center &  e-mail:& \htmladdnormallink{\myverb{<louis@bic.mni.mcgill.ca>}}{mailto:louis@bic.mni.mcgill.ca}  \\
NeuroImaging Laboratory        &  tel: & (514)-398-1726,1996 \\
Montreal Neurological Institute&  Fax: & (514)-398-8948  \\
3801 University St.            &       & \\
Montreal, Quebec.  H3A 2B4     &       & \\
\end{tabular}



\end{document}


