GrapeBio Pre : A Bio Image Preprocessing Software Package

GrapeBio Pre is developed based on OpenCV, and provides a simple yet effective image preprocessing pipeline to improve the quality of 4D bio images. Coupled with TGMM (https://www.nature.com/articles/nmeth.3036), it can substantially improve the segmenting and tracking accuracies.

This file contains basic instructions for installing and running the bio image preprocessing package of the software GrapeBio. The program provided here has been tested with the 64-bit version of Windows 10.

1. CONTENTS OF THE SOFTWARE ARCHIVE

We assume that the user has installed the software to a folder named "GrapeBio" or others, referred to here as $ROOT_GRAPEBIO.

$ROOT_GRAPEBIO contains the following subfolders:

• "bin" : All the needed .dll and .exe files.
• "raw": Raw imaging data (*.tif) for test.
• "result" : Preprocessed result data after each steps.

$ROOT_GRAPEBIO contains the following root files:

• "run.bat" : Double click to run all the preprocessing steps. Results will be generated in the "result" folder.
• "uninst.exe" : Double click to uninstall the software.
• "README.md" : Myself.

2. INSTALLATION AND SOFTWARE REQUIREMENTS

• The software can only run on the 64-bit version of Windows 7/10, Linux is NOT supported yet;
• A powerful computer is recommended, for example a workstation;
• CUDA 8.0(https://developer.nvidia.com/cuda-80-download-archive) must be installed before running this software;
• The available space on this hard disk should be greater than 8 GB;
• The user is strongly suggested NOT to install the software in the operation system disk (C disk), as in such case the program should be open as administrator to get the authority to write the result files;

• If the software is already installed in the system disk, Windows 10 offers a Power Users menu that you can access by pressing Windows-X or just right-clicking the Start button. On the Power Users menu, choose “Command Prompt (Admin)”. Subsequently, cd to the folder $ROOT_GRAPEBIO, type "run.bat" and enter:

  C:\WINDOWS\system32>cd $ROOT_GRAPEBIO

  $ROOT_GRAPEBIO>run.bat

3. RUNNING THE GRAPEBIO SOFTWARE

3.1 Run the test data

Double click the "run.bat" file, and wait a few minutes (depending on the performance of the computer) for the preprocessed images to be generated step-by-step to the "result" folder. The subfolders in the "result" folder contains the following intermediate results of individual steps:

• "1.subgauss" : Contains the image stack files after "Subtract Gaussian Background";
• "2.median" : Contains the image stack files after "De-noise by Median Blur";
• "3.hdr" : Contains the image stack files after "Single Image High-Dynamic Range";
• "4.balance" : Contains the image stack files after "Light Balance among Stack"
• "5.layercorrect" : Contains the image stack files after "Image Correction between Layers"
• "6.stackcorrectxy" : Contains the image stack files after "Image Correction between Stacks (XY)"
• "7.stackcorrectz" : Contains the image stack files after "Image Correction between Stacks (Z)"

We provide a test data set that allows the user to test the software before they applying to their own data sets. Two TIFF stack files are included in the folder "raw". The user can show and investigate the data using ImageJ (https://imagej.net).

3.2 Run the user data

Different data sets may require different parameters. The users can edit the "run.bat" file using Notepad, and change the corresponding parameters, explained as follow:

** simc_subgaussian.exe [src] [dst] [wsize] [sigma] [frame_begin] [frame_end] **

• Functionality : Gaussian Background Subtraction, subtract the low frequency Gaussian trend of the image background;
• [src] : the root folder of the source data files. TIFF files must be stored in subfolders named like '000/000.tif', '011/011.tif', etc.;
• [dst] : the root folder of the destinate data with the same hierarchical structure as [src];
• [wsize] : the window size of the Gaussian blur filter, should be greater than the cell size;
• [sigma] : the sigma parameter used in the Gaussian function to generate the non-uniform background;
• [frame_begin], [frame_end] : the range of frames to be processed;

** simc_medianfilter.exe [src] [dst] [wsize] [frame_begin] [frame_end] **

• Functionality : Filter the pulse (salt and pepper) noise;
• [src] : the root folder of the source data files. TIFF files must be stored in subfolders named like '000/000.tif', '011/011.tif', etc.;
• [dst] : the root folder of the destinate data with the same hierarchical structure as [src];
• [wsize] : the window size of the median blur filter, should NOT be greater than 5;
• [frame_begin], [frame_end] : the range of frames to be processed;

** simc_hdr.exe [src] [dst] [up_gamma] [down_gamma] [frame_begin] [frame_end] **

• Functionality : Enhances the dark cell nuclei while prevent the bright cell nuclei from overexposure;
• [src] : the root folder of the source data files. TIFF files must be stored in subfolders named like '000/000.tif', '011/011.tif', etc.;
• [dst] : the root folder of the destinate data with the same hierarchical structure as [src];
• [up_gamma] : used to generate the up curved Gamma transform;
• [down_gamma] : used to generate the down curved Gamma transform;
• [frame_begin], [frame_end] : the range of frames to be processed;

** simc_balance.exe [src] [dst] [target] [threshold] [frame_begin] [frame_end] **

• Functionality : Derives balanced fluorescence intensities on the image stacks;
• [src] : the root folder of the source data files. TIFF files must be stored in subfolders named like '000/000.tif', '011/011.tif', etc.;
• [dst] : the root folder of the destinate data with the same hierarchical structure as [src];
• [target] : the target mean fluorescence intensity to be adjusted;
• [threshold] : threshold to separate the foreground (cell nuclei) and the background;
• [frame_begin], [frame_end] : the range of frames to be processed;

** simc_layercorrect.exe [src] [dst] [frame_begin] [frame_end] **

• Functionality : Align adjacent layers in the image stacks using the image registration algorithm;
• [src] : the root folder of the source data files. TIFF files must be stored in subfolders named like '000/000.tif', '011/011.tif', etc.;
• [dst] : the root folder of the destinate data with the same hierarchical structure as [src];
• [frame_begin], [frame_end] : the range of frames to be processed;

** simc_projection.exe [src] [dst] [frame_begin] [frame_end] **

• Functionality : Generate the X/Y/Z project stacks at the same time;
• [src] : the root folder of the source data files. TIFF files must be stored in subfolders named like '000/000.tif', '011/011.tif', etc.;
• [dst] : the folder that contains the X/Y/Z project stacks;
• [frame_begin], [frame_end] : the range of frames to be processed;

** simc_registration.exe [src] [mode] **

• Functionality : Generate the homogeneous matrices (translation & rotation) of the embryos between adjacent frames by registering the x/z project stacks, and store the matrices in a csv file;
• [src] : the folder that contains the X/Z project stacks;
• [mode] : make translation & rotation registrations if mode == 0, make only translation registration if mode == 1;

** simc_stackcorrectxy.exe [src] [dst] [csv] **

• Functionality : Correct the X/Y drifting and rotating motions of the embryo that are observed along the Z-axis of the stack;
• [src] : the root folder of the source data. TIFF files must be stored in subfolders named like '000/000.tif', '011/011.tif', etc.;
• [dst] : the root folder of the destinate data with the same hierarchical structure as [src];
• [csv] : the .csv file that records the homogeneous matrices after registering the Z project stack;

** simc_stackcorrectz.exe [src] [dst] [csv] **

• Functionality : Correct the Z drifting and rotating motions of the embryo that are observed along the X or Y-axis of the stack;
• [src] : the root folder of the source data. TIFF files must be stored in subfolders named like '000/000.tif', '011/011.tif', etc.;
• [dst] : the root folder of the destinate data with the same hierarchical structure as [src];
• [csv] : the .csv file that records the homogeneous matrices after registering the X or Y project stack.

4. Copyright

Copyright (c) 2018- , GrapeTec Research Group, Beihang University, Beijing, P.R. China, 100191. All rights reserved.

5. Contacts:

Wenlei Xiao, Associate Professor

School of Mechanical Engineering and Automation，Beihang University

C-206, New Main Building, Beijing, P.R. China, 100191

Email: xiaowenlei@buaa.edu.cn

6. Developers (ordered by contributions):

• Wenlei Xiao, School of Mechanical Engineering & Automation, Beihang University, P.R. China;
• Jinghang Li, School of Software & Microelectronics, Peking University, P.R. China;
• Yazui Liu, School of Mechanical Engineering & Automation, Beihang University, P.R. China;
• Jingyi Wu, School of Software & Microelectronics, Peking University, P.R. China;