====== NeuroElf installation ======

===== Requirements =====
As said on the [[NeuroElf introduction|introduction]] page, NeuroElf requires one of the following environments:

  * Microsoft Windows (tested under Windows XP and Windows 7), using Matlab Version v7.5 (R2007b) and onwards
  * Linux (tested under S.u.S.E. Linux 11.2, 64-bit edition as well as Ubuntu 10, 32-bit edition), using Matlab Version v7.5 (R2007b) and onwards
  * Mac OSX (tested under Mac OSX 10.5 and 10.6 on an iMac with 64-bit support as well as a OSX 10.4 PPC PowerMac), using Matlab Version v7.5 (R2007b) and onwards
  * alternatively, you can try to use [[http://www.gnu.org/software/octave/|GNU Octave]], starting with version v3.4.0 (currently available for Intel-based Macs and as source code); **please note that no GUI elements currently work under GNU Octave!** (a restriction hopefully going away for future Octave versions...); **also note that when using the Installer ZIP file, you must use the ''-f'' option to override the check for the Matlab release/version!**

===== Process =====
{{ youtube>DktIMfu9UM8?320x204| NeuroElf v0.9c installation (video demonstration)}}
To install NeuroElf, please download the current version from the [[http://neuroelf.net/|main page]] (either the installer or flat folder/snapshot).

For a video demonstration, please watch the video on the right side (go to the [[NeuroElf installation video]] page for a full-size view).

==== Using the installer ====
In case you downloaded the installer, unzip the archive to a temporary location, which contains three files:
  * NeuroElf_vXY.m
  * NeuroElf_vXY.mat
  * ne_eo.m //(this is a compatibility file added to allow Octave to use NeuroElf's error handling scheme)//

The first ''.m'' file contains the code that unpacks the files from the ''.mat'' file within Matlab/Octave, runs some preliminary checks and, eventually, calls ''neuroelf_setup'', which performs some of the setup tasks (e.g. compiling the MEX files if necessary and creating the file format cache). To install the toolbox, change the current directory in Matlab to the temporary folder where you unzipped the archive and then call the installing ''.m'' file with the ''-i'' input argument:

<code neuroelf_installation.m>% change into folder containing installer
cd ~/Desktop

% call installer (in this case for version v0.9c)
NeuroElf_v09c -i

% when using Octave, you must use
% NeuroElf_v09c -f
% to override the Matlab release check!</code>

You will then be asked where to install the toolbox. **Please make sure to choose a path/folder that is writable to the user(s) regularly using the toolbox!!**

The folder into which the toolbox is installed will be added to Matlab/Octave path **temporarily**; in other words, if you wish to keep the toolbox on the path, please open the Path settings under File -> Set Path... or, alternatively, issue the ''savepath'' command on the Matlab/Octave prompt.

In case the MEX files were not compiled on your platform and also not part of the installation package, please first read the [[NeuroElf MEX files|page on MEX file compilation]] and, if that doesn't help, get in touch with me (see the [[NeuroElf - error report|error reporting page]] for instructions).

==== Using the flat folder/snapshot ====
In case you downloaded the flat folder or snapshot archive, simply unzip this archive to its final destination. The archive contains one folder which is named according to the version of the toolbox, e.g. ''NeuroElf_v09c''.

To finalize the installation, change into the installation folder in Matlab and issue the ''neuroelf_setup'' function manually:

<code neuroelf_installfromfolder.m>% change into NeuroElf installation folder
cd /usr/local/matlab/toolbox/NeuroElf_v09b

% call NeuroElf's setup
neuroelf_setup</code>

This time, you'll have to add the path manually and then save it, e.g. by issuing these commands:

<code matlab neuroelf_addpath.m>% adding NeuroElf to the path and saving the altered path
addpath(neuroelf_path);
savepath;</code>

===== Notes =====
  * whereas many toolboxes require to add several folders to the path, NeuroElf only needs it main folder to be added
  * the [[xff]] format files (text files that contain the instructions on how exactly to read/write different file formats) are parsed only once and the result is stored under ''_files/cache/cache.mat''; it is thus important that this folder is writable to the toolbox (particularly when the format files are updated!)
  * additional files can be created by using [[neuroelf_makefiles]] (see its page for settings); but as this might take quite a while to complete with full settings, there is a prepared file for download containing all files: [[http://neuroelf.net/NeuroElf_v09c_colin_aux.zip|NeuroElf_v09c_colin_aux.zip]] --after downloading the files from this archive should be unzipped into the ''_files/colin'' subfolder of the installation
  * support for [[http://www.gnu.org/software/octave/|GNU Octave]] is very preliminary (reading, altering, and writing files should work, but no GUI functionality is available!)

===== Errors / warnings during installation =====
Given that the setup function (''neuroelf_setup'') will try to compile some C-based code into MEX files (see [[NeuroElf MEX files]] for infos), it is possible that you will see some warning or error messages in case your system doesn't have a functional compiler installed or setup in Matlab. These error messages should only occur the first time you set up a particular NeuroElf version!

In that case, the setup function will try to copy the MEX files that come with the package into the NeuroElf installation folder, after which all subsequent routines should work without further problems.

**Note: On Windows machines that don't have a compiler installed, the ''mex'' function still asks to select a compiler and upon selecting "none" (0), the function exits without error. One user reported that it might be necessary to 1.) keep selecting ''0'' for each of the MEX files to be compiled, which is about 30 times, during the installation of NeuroElf (''NeuroElf_v0XY -i'' internally runs ''neuroelf_setup'') and then 2.) manually re-run the ''neuroelf_setup'' function again so that the MEX files are properly copied into the installation folder.** 

If you receive further warning/error messages about missing MEX files, the platform you're using is not supported (as of yet) by pre-built MEX files, and I would like to ask you to get in touch with me (at info _at_ neuroelf _dot_ net), so that I can add support for this platform by adding compiled files accordingly (for which I might require your assistance and some patience...).

===== Installation folder structure =====
Once the toolbox is installed and setup, the following folder structure should be present:

  * **''NeuroElf_vXY''** - root folder containing the functions that are added to the path and are available for scripting
    * **''@transimg''** - class directory of the [[transimg]] class that handles blending several RGBA layers to one image
    * **''@transio''** - class directory of the [[transio]] class that handles transparent I/O access for large numerical arrays
      * ''private'' - transio's privately used functions
    * **''@xff''** - class directory of the [[xff]] class that handles complex file/object I/O and method access
      * ''private'' - xff's privately used functions (this folder **also contains all objects' method files as type_Method.m files!**)
    * **''@xfigure''** - class directory of the [[xfigure]] class that handles additional functionality of Matlab's graphics handles
    * **''@xini''** - class directory of the [[xini]] class that handles configuration file I/O and access to settings
    * **''@xprogress''** - class directory of the [[xprogress]] class that provides a simplified access to graphics-based progress bars
    * **''private''** - this folder contains all functions that are used by the [[neuroelf_gui|GUI]] of NeuroElf
    * **''_core''** - this folder contains **required** auxiliary files in sub-folders
      * ''config'' - this folder contains the configuration (ini) files read and written to by the [[xini]] class; **this folder must be //writable//!**
      * ''dicom'' - this folder contains the (partial) DICOM dictionaries available in NeuroElf
        * ''OFFIS'' - this is a copy of an (older) dictionary of the OFFIS DICOM software package
        * ''Philips_Achieva'' - this is a (manually edited and partial) dictionary for Philips Achieva DICOM files
        * ''Philips_Intera'' - this is a (manually edited and partial) dictionary for Philips Intera DICOM files
      * **''formats''** - this folder contains the **BFF** (binary format file) and **TFF** (text format file) specifications that describe how [[xff]] files are read/written
      * ''icons'' - this folder contains TIF icons for the [[neuroelf_gui|GUI]]
      * ''lut'' - this folder contains the LUT (look-up table) definition files (in BrainVoyager's [[xff - OLT format|OLT format]])
      * ''splash'' - this folder contains the splash images used for the setup routine ([[neuroelf_setup]])
      * ''tfg'' - this folder contains the text-based representation of all complex figures (UI windows) of the toolbox
    * **''_files''** - this folder contains **optional** auxiliary files in sub-folders
      * ''cache'' - this folder contains the cached version of the ''_files/formats'' files' contents and the methods of all [[xff]] objects; **this folder must be //writable//!**
      * ''colin'' - this folder contains the colin_27 template and additional files that can be used to display data that is in MNI/ICBM space (during installation, additional files will be created in this folder!)
      * ''compiled'' - this folder (or rather, its subfolders) contain pre-compiled MEX files in case compilation of those files fails during installation
        * ''a64'' - compiled MEX files for the A64 (Linux) platform
        * ''glx'' - compiled MEX files for the GLX (Linux) platform
        * ''mac'' - compiled MEX files for the MAC (PowerPC-Mac) platform
        * ''maci'' - compiled MEX files for the MACI (Intel-Mac) platform
        * ''maci64'' - compiled MEX files for the MACI64 (64-bit Intel-Mac) platform
        * ''octave'' - compiled MEX files for Octave (subfolders for platforms, not listed here)
        * ''w32'' - compiled MEX files for the W32 (32-bit MS Windows) platform
        * ''w64'' - compiled MEX files for the W64 (64-bit MS Windows) platform
      * ''contrib'' - files that are not part of the main functionality but can potentially be useful for interested users (content not fix between distributions!)
      * ''libSVM'' - files bundled as a reference for the libSVM functionality
      * ''spm'' - files required for running SPM5/8 based processing steps (e.g. when using [[spm5_preprojobs]] for data preprocessing)
      * ''srf'' - additional surface files used for some of the surface-manipulating methods (unit cube, unit cylinder, and unit sphere)
      * ''tal'' - files required by the [[tdlocal2]] function for Talairach Demon Database inquiries as well as files for coordinate conversion from TAL to ICBM and vice versa
      * ''todo'' - if present (usually SNAPSHOTs only), a collection of files and folders that still require work