Editing Installing the MATLAB interface to STIR

This page provides instructions on how to install STIR for MATLAB. You will need STIR 3.1 or later for this to work (at present, use the [[https://github.com/UCL/STIR github version]].

= Introduction =
You will need to use the instructions at [[Installing STIR with CMake]]. Here we
will give more specific information.

These are instructions on how to install the STIR+MATLAB interface have been tested on a unix system with ubuntu 14.04. It relies on CmakeGui (as usual) and an extension of SWIG that has to be installed first.

= Install SWIG =
First, prepare your system with some packages
<pre> sudo apt-get install libtool automake autoconf autogen bison </pre>
Get a version of SWIG with preliminary MATLAB support
<pre> mkdir swig
 cd swig
 git clone https://github.com/jaeandersson/swig.git swig_git </pre>
(you could try https://github.com/KrisThielemans/swig.git instead but this is currently out-of-date) and checkout the right branch
<pre> cd swig_git	
 git checkout matlab </pre>
SWIG can now be installed
<pre> ./autogen.sh	
 cd ..
 mkdir build
 cd build	
 ../swig_git/configure	
 make
 sudo make install </pre>

In the case were MATLAB is not installed globally, when use the following flag:
<pre> ../swig_git/configure --with-matlab=[PATH]
</pre>

Note that the install might fail at the end if it can't find yodl2man, but we don't care. 
Check with that we now have the right version (should say 3.0.3 or later)
<pre> swig -version </pre>

= Install STIR =
Follow the instructions on this page up to the point where you started cmake-gui.
* press configure    	
* press ok   
* set ''CMAKE_BUILD_TYPE'' to ''Release''
* enable ''BUILD_SWIG_MATLAB''
* If you want want to use openMP for acceleration, enable ''STIR_OPENMP''
* press configure
* check that CMake found the correct SWIG file (not the system one). If it did, replace the SWIG variable and "configure" again
* optionally adjust location of STIR-MATLAB files (''MATLAB_DEST'' variable)
* generate
* close cmake-gui
Then either install STIR as usual 
<pre> make    
 sudo make install </pre>
or you could build only the STIR+MATLAB first (just to see if it fails or not)
<pre> make stirMATLAB </pre>
Add path in MATLAB. E.g.
<pre> addpath /usr/local/matlab </pre>

= Potential problems =
== swig complains about mexname ==
The following error
<pre>
swig error : Unrecognized option -mexname swig error : Unrecognized option stirMATLAB_wrap 
Use 'swig -help' for available options.
</pre>
is caused by a slightly out-of-date swig. you can get around it by editing src/swig/CMakeLists.txt and removing ''-mexname stirMATLAB_wrap'' from the line (around L107) that sets ''SWIG_MODULE_stirMATLAB_EXTRA_FLAGS''.

== run-time errors in MATLAB ==
On Linux, you might see something like this
<pre>
Invalid MEX-file '/nobackup/umpw/STIR/STIR-Build/src/swig/stirMATLAB_wrap.mexa64':
/apps1/applications/matlab/R2016a/1/default/bin/glnxa64/../../sys/os/glnxa64/libstdc++.so.6: version `GLIBCXX_3.4.20' not found (required by /nobackup/umpw/STIR/STIR-Build/src/swig/stirMATLAB_wrap.mexa64)
</pre>
you might see something similar on Mac.

This problem  is caused by MathWorks making sure that MATLAB works by shipping its own version of system/gcc/dependent libraries, but breaking external code in the mean time. Our recommended solution is to compile EVERYTHING with a MATLAB compatible compiler. Check for instance https://uk.mathworks.com/support/sysreq/previous_releases.html.

On Linux/Mac you can do this as follows
<pre>
CC=gcc-4.7 CXX=g++4.7 ccmake ...
</pre>

If you want to use a more recent compiler (or have a corner case where you see the above error anyway), you 
could try to resolve by pre-loading your shared libraries. In bash, you can do for instance:
<pre>
LD_PRELOAD=/lib64/libstdc++.so.6:/lib64/libhdf5.so matlab&
</pre>
In certain systems, you might have to use <tt>LD_PRELOAD_64</tt>. Also, the exact path of your libraries will change. You can normally find out by locating the stirMATLAB_wrap.mex* file and doing something like
<pre>
ldd stirMATLAB_wrap.mexa64
</pre>

= Testing =
There are a few tests in STIR/src/swig/test/matlab. Just execute these adding the directory where you installed it to your matlab path (e.g. if you choose /usr/local as your CMAKE_INSTALL_PREFIX, in MATLAB do "addpath /usr/local/matlab")

= Examples =
Get started with the examples in STIR/examples/matlab