# INI file configuration

*StitchIt* uses an INI file to configure various parameters such as the hardware used to [acquire the data](https://github.com/raacampbell/stitchit_docs/tree/2da820113f110901e39e73326784845f47a942c4/The-acquisition-scenario.md), the location of your web sever for sending preview images during acquisition, etc. Before using *StitchIt* you will need to create and edit the INI file. INI files are composed of keys and values and divided into sections:

```
[section]
key_A = value
key_B = value

[another section]
key_A = value
key_B = value
```

## Creating the INI file

* The INI file should be located somewhere in your [MATLAB path](https://www.mathworks.com/help/matlab/matlab_env/what-is-the-matlab-search-path.html) that you have write access. 
* Start MATLAB, change to the directory in whcih you wish to place the INI file and run `makeLocalStitchItConf`.
* You will now have a file in this directory called `stitchitConf.ini`. 

  Open this in the text editor of your choice or just run `edit stitchitConf.ini` to edit it in the MATLAB editor.

Note that the INI file follows much the same [precedence rules](https://www.mathworks.com/help/matlab/matlab_prog/function-precedence-order.html) as `.m` files so you can, for instance, place a copy of the INI file in your experiment's root directory, `cd` to that directory, and your analyses will honour whatever is in this local INI file. You may use `which('StitchItConf.ini')` to determine which file *StitchIt* is currently using. If you regularly change INI file settings, then it might be good practice to keep a copy of the INI file used to assemble an experiment in the experiment's root directory.

## Creating system-specific INI files

You may create a different INI file for different microscopes. To create two different INI files for two different systems do the following:

* Follow the above instructions for make the INI file.
* If your first system is called *brainsaw*, make a copy of the INI file called `stitchitConf_brainsaw.ini`.
* If your second system is called *noodlecutter*, make a copy called `stitchitConf_noodlecutter.ini`.
* Edit the files independently. 
* When you are in an experiment directory containing data generated by *noodlecutter*  `readStitchItINI` will automatically read from `stitchitConf_noodlecutter.ini`.
* If *StitchIt* can not find a system-specific INI file it will attempt to read `stitchitConf.ini`.

## How to edit the INI file

* Lines starting with `;;` are a comment lines which provide instructions and documentation. 
* Lines such as `[micsPerPixel]` are used to indicate the beginning of a section. 

  They are read in by MATLAB so don't edit them.
* Lines such as `cropProportion=0.0216` are key/value pairs. `cropProportion` is the "key" or variable name and `0.0216` is the value that will be assigned to it. When the command `readStitchItINI` is run, it will create a structure which contains this information.

## Setting up syncAndCrunch

`syncAndCrunch` is a useful tool that does the following:

* Pre-process data during acquisition: calculates average tiles and builds an index of where the tiles fit in the final volume.
* Generate a stitched preview of the last completed section and send this to the web. 
* Initiate stitching when acquisition is completed. 
* Send a Slack notification when the sample is complete or if an error is encountered. The messaging system is modular, so you could send messages via a different protocol of your choice. 

The settings for `syncAndCrunch` are at the bottom of the INI file and are fairly self explanatory. The key things are:

* To send images to the web you will need a webserver to which you can make passwordless connection via [shared keys](https://www.digitalocean.com/community/tutorials/how-to-set-up-ssh-keys--2). 

  If you don't set up shared keys, the analysis will stall when it attempts to upload images to the web. 
* If you wish, you may use the HTML and JavaScript files in the repository to produce an attractive image on the website (see the `html` directory).
* If you wish to set up Slack notifications you will need to install [Slack MATLAB](https://github.com/DylanMuir/SlackMatlab) and create a Slack hook as described on that project's ReadMe page. 
* You can edit `postAcqFun` to run any arbitrary function once `syncAndCrunch` is complete.