# Installation

## Before you start

You will need a relatively powerful desktop machine. The pipeline is mainly IO-bound and won't need ridiculous quantities of RAM or unusual numbers of cores. The following will work just fine:

* **CPU**: i7-3930K, i7-5960X, or i7-4820 or similar.
* **RAM**: 32 GB is sufficient for 1 micron per pixel data sets and 64 GB will be adequate for 0.5 micron per pixel sets. These numbers are generous and assume 200 tiles per plane. Use more RAM if multiple people are likely to be using the machine at once. 
* We use X99 motherboards which will take 128 GB of RAM.
* **Storage**: We run with at least four platter drives using btrfs (software) RAID. 8 TB total local storage is generally adequate for us. You might want more. 

  SSDs are expensive and *not* necessary since stitching will be an order of magnitude faster than acquisition with the above setup.

We have had good results running with Ubuntu 16.04 and 18.04. Some aspects of the pipeline do not currently run on Windows. You will need MATLAB R2018a or later, with the the statistics, parallel computing, and image processing toolboxes.

## Cloning the repository

The first thing you need to do is get *StitchIt*'s code onto you machine. On the project's [main page](https://github.com/SainsburyWellcomeCentre/StitchIt) is a green button near the top right of the screen that says "Clone or download". From here you can download a zip file containing *StitchIt* or, much better, clone *StitchIt* using Git. If you plan on seriously using *StitchIt* you should **definitely** clone it with Git. *StitchIt* receives regular updates and Git makes it easy to keep track of these and stay up to date. To clone and stay up to date with Git do the following:

* Download and install free Git client such as [http://www.syntevo.com/smartgit/](https://github.com/raacampbell/stitchit_docs/tree/a039587c72f8852f44b5b53afb6c30f79b9990aa/SmartGit/README.md) or [GitHub Desktop](https://desktop.github.com/). 
* Clone the repository using the URL you see when you press the green "Clone or download" button. [SmartGit instructions](http://crunchify.com/smartgit-setup-guide-my-favorite-client-for-git-and-mercurial/) [GitHub Desktop](https://docs.github.com/en/desktop/contributing-and-collaborating-using-github-desktop/cloning-a-repository-from-github-to-github-desktop). 
* Once cloned, both of these tools have a "pull" button that checks for updates on GitHub and downloads them if available. 
* If all you're doing is *cloning* the repository and staying up to date with *pull* then that's all you need to do. If you would like to learn more about Git, possibly to contribute to *StitchIt*, then the [Atlassian Git tutorial](https://www.atlassian.com/git/tutorials/what-is-version-control) is a great starting point. 

## Installing in MATLAB

You should now have a directory somewhere on your computer that contains *StitchIt*. The easiest way of installing *StitchIt* in MATLAB is to add it to [the MATLAB path](https://www.mathworks.com/help/matlab/matlab_env/what-is-the-matlab-search-path.html) using the [pathtool](https://www.mathworks.com/help/matlab/ref/pathtool.html?searchHighlight=pathtool\&s_tid=doc_srchtitle) command:

* Start MATLAB.
* Run `pathtool` and a GUI will open.
* Click "Add with subfolders".
* Navigate to the *StitchIt* directory. Enter it and select the `code` directory then press "Open".
* The `code` directory and all it's subdirectories are now added to the "MATLAB search path" list. 
* Hit "Save". This will update a file called `pathdef.m` that contains the list of directories you see in the GUI.

A common problem is that MATLAB complains you don't have write access to save the `pathdef.m` file. This happens because by default you are attempting to save the `pathdef.m` file in the MATLAB install directory. A solution to this problem is [outlined here](https://www.mathworks.com/matlabcentral/answers/101765-why-am-i-unable-to-save-my-matlab-path-using-matlab-7-9-r2009b). Basically, the answer is to to tell the GUI to save the file in your [startup folder](https://www.mathworks.com/help/matlab/matlab_env/matlab-startup-folder.html). Typing `userpath` will report which the startup folder is. You save the `pathdef.m` file in there.

A better approach than the above is to create a file called `startup.m` in your startup folder. This file will be run every time MATLAB starts. In the `startup.m` file you can use the [genpath](https://www.mathworks.com/help/matlab/ref/genpath.html) and [addpath](https://www.mathworks.com/help/matlab/ref/addpath.html) commands to add directories to the path. Doing this has the **advantage** that if a future release of *StitchIt* has a different path (i.e. a directory is added or removed) then this will be automatically dealt with when `startup.m` runs. For example your `startup.m` file could look like this:

```
function startup
 stitchit=genpath('~/work/Anatomy/StitchIt/code');
 araTools=genpath('~/work/Anatomy/code/ARA_tools/code');

 addpath(...
    stitchit,...
    araTools,...
    '~/work/Anatomy/code/AllenBrainAPI/',...
    '~/work/Matlab_Scripts/yamlmatlab',...
    '~/work/Matlab_Scripts/MelastiX/code',...
    '~/work/Matlab_Scripts/SlackMatlab');
```

## Installing dependencies

In the same manner as for *StitchIt*, clone and add to your path [Slack MATLAB](https://github.com/DylanMuir/SlackMatlab) if you wish to send Slack progress messages during data acquisition. In the `pathtool` GUI just add the single project directory and don't add subfolders (as shown above). If you add subfolders MATLAB will add the hidden `.git` directory and all its many subfolders.\
Once everything is installed, move on to [setting up the INI file](https://stitchit.mouse.vision/installation/setting-up-the-ini-file).

## Problems?

*StitchIt* should have no other dependencies. If you get an error that indicates a function is missing, please [file a bug report](https://github.com/SainsburyWellcomeCentre/StitchIt/issues).