Skip to content

Setting up the INI file

Jump to bottom
Rob Campbell edited this page Mar 12, 2017 · 10 revisions

StitchIt uses an INI file to configure various parameters such as the hardware used to acquire the data, 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 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 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. With the TissueVision system there is a System ID that constitutes the name of the microscope. You can change this in the protocol file. 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 the X/Y resolution

By default StitchIt places tiles in the correct locations based on the assumed position of the stage and the number of microns per pixel. If you are using a TissueCyte system, you will need to measure the number of microns per pixel for the objectives and scan ranges which you use. For other systems, we assume the image meta-data will contain the correct value. So for the TissueCyte only you will be editing the [experiment], [micsPerPixel], and the objective sections. Unfortunately, the implementation of the image resolution for the TissueVision is a bit of a horrible hack as it was done by trial and error and not updated. Hopefully it will be cleaned up at some point (Issue #18). In the mean time, do the following:

  • Make all microns per pixel measures using the image size defined by numPix in your INI file. We defined the number of microns per pixel with respect to 1664 x 1664 images. StitchIt automatically extrapolates the image scale to other image sizes (e.g. 832 by 832 pixels) so just do all of your measurements at 1664 by 1664.
  • For each objective and scan range you will use, measure the number of microns per pixel. You will end up with a bunch of sections like this:
[Nikon16x_2_2]
micsPerPixelMeasured=0.480
micsPerPixelRows=0.474
micsPerPixelCols=0.459

[Nikon16x_3_0]
micsPerPixelMeasured=0.650
micsPerPixelRows=0.650
micsPerPixelCols=0.650

  • Define one or more names for your objectives using objectiveName under the [experiment] section. In the example INI file you will see there are two objectives, one of which is defined at two different scan amplitudes (zooms). Comment out the unused objectives. Each experiment is stitched using one objective.

  • For each objective you will need to specify the number of microns per pixel using the micsPerPixelMeasured variable.

  • The pixels really should be square, but you might get better stitching accuracy by specifying slightly different values in X and Y. You can do this by defining micsPerPixelRows and micsPerPixelCols and setting usemeasured to 0.

  • Use the chess-board stitching option in stitchSection to stitch a single section, check the alignment of your tiles, and tweak the microns per pixel values until the overlap looks as good as possible.

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. 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 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.
Clone this wiki locally