This toolkit provides a robust, feature-based image registration solution designed to streamline and enhance the alignment and analysis of images. Leveraging well-known algorithms, this tool enables accurate and efficient registration across various use cases:

1. Pair Registration: Aligns two images based on common features.
2. Serial Stack Registration: Registers a sequence of images, enabling seamless alignment in image stacks.
3. Multi-Channel Serial Stack Registration: Supports multi-channel image stacks, ensuring accurate registration across multiple image channels.

In addition to registration, this toolkit includes a Geometric Distortion Analysis feature that evaluates and visualizes distortions between images, allowing for in-depth analysis and correction of geometrical inconsistencies.

1. Introduction
2. Installation
3. Naming Structure for Serial Stack
4. Datasets
5. Citation

This open-source image registration toolkit provides cross-platform support with executable files available for both Windows (.exe) and Mac OS (.dmg). Developed using Python and designed with the Qt framework, this tool is accessible to a wide range of users, combining powerful functionality with a user-friendly interface.

In the following sections, you'll find detailed guidance for installation on both Windows and Mac OS, allowing you to get started quickly and easily.

To install ImageReg on Windows:

1. Navigate to the Releases section on the right-hand panel of this repository.
2. Select version v1.0.0 and download the file named ImageReg_Windows.zip.
3. Once downloaded, extract the content of the zip file.
4. Open the extracted folder and double-click to start and run ImageReg.

1. Navigate to the Releases section on the right-hand panel of this repository.
2. Select version v1.0.0 and download the file named ImageReg_Mac.zip.
3. After downloading, double-click the .dmg file to open it.
4. Drag the ImageReg icon into your Applications folder (if needed) to install the toolkit.

To run ImageReg from source code on Windows, follow these steps carefully:

1. Download the Project Files

   1.1 Clone or download the project from the repository:

   git clone https://github.com/UltraplexTools/ImageReg-Toolkit.git

   1.2 Alternatively, download the ZIP file from GitHub, extract it, and ensure all files are in a single project folder.

2. Download and Install Qt Designer

   2.1 Download Qt Designer for Windows from this link

   2.2 Follow the installation instructions to install Qt Designer, which will be required for UI adjustments.

3. Unzip Additional Files

   3.1 From the project’s downloaded files, unzip the following files:

   a. UserInterface_ui_Windows.zip

   b. ImageRegSpecWindows.zip

   d. requirements.txt

   3.2 Place these extracted files in the same directory as the other project files.

4. Set Up a Virtual Environment

   4.1 To manage dependencies and ensure compatibility, create a virtual environment. For guidance, you can follow these instructions.

   4.2 Ensure you activate the virtual environment once created.

5. Install Python 3.9.6 or newer version (If you do not have it)

   5.1 Download and install Python different version from this link.

   5.2 Confirm Python is active in your environment by running:

   python --version

6. Install Required Libraries

   6.1 With the virtual environment activated, install the libraries listed in the requirements.txt file by running the following command in the terminal:

   pip install -r requirements.txt

7. Run the Code

   7.1 Open the codes folder, or navigate to the directory where main.py is located.

   7.2 Run the application by executing:

   python main.py

To run ImageReg from source code on Windows, follow these steps carefully:

1. Download the Project Files

   1.1 Clone or download the project from the repository:

   git clone https://github.com/UltraplexTools/ImageReg-Toolkit.git

   1.2 Alternatively, download the ZIP file from GitHub, extract it, and ensure all files are in a single project folder.

2. Download and Install Qt Designer

   2.1 Download Qt Designer for Mac from this link

   2.2 Follow the installation instructions to install Qt Designer, which will be required for UI adjustments.

3. Unzip Additional Files

   3.1 From the project’s downloaded files, unzip the following files:

   a. UserInterface_ui_Mac.zip

   c. ImageRegSpecMac.zip

   d. requirements.txt

   3.2 Place these extracted files in the same directory as the other project files.

4. Set Up a Virtual Environment

   4.1 To manage dependencies and ensure compatibility, create a virtual environment. For guidance, you can follow these instructions.

   4.2 Ensure you activate the virtual environment once created.

5. Install Python 3.9.6 or newer version (If you do not have it)

   5.1 Download and install Python different version from this link.

   5.2 Confirm Python is active in your environment by running:

   python --version

6. Install Required Libraries

   6.1 With the virtual environment activated, install the libraries listed in the requirements.txt file by running the following command in the terminal:

   pip install -r requirements.txt

7. Run the Code

   7.1 Open the codes folder, or navigate to the directory where main.py is located.

   7.2 Run the application by executing:

   python main.py

When using the Serial Stack feature (both Single Channel and Multi-Channel), it’s essential to follow a specific naming structure to ensure the program can accurately identify and process images in the correct sequence.

1. Single Channel Stack: Name each image in the format:

   Anything_SecXXX

   Anything: Any text or identifier you prefer. SecXXX: A three-digit section number representing the sequence (e.g., 001, 002, etc.), which should be sorted numerically. Example: Sample_Sec001, Sample_Sec002, etc.
2. Multi-Channel Stack: Name each image in the format:

   Anything_SecXXX_chXX

   Anything: Any text or identifier you prefer. SecXXX: A three-digit section number for ordering the stack. chXX: A two-digit channel number representing the channel (e.g., 01, 02). Example: Sample_Sec001_ch00, Sample_Sec001_ch02, Sample_Sec002_ch00, Sample_Sec002_ch01 etc.

1. Navigate to the Releases section in the right-hand panel of this repository.
2. Locate the release titled Installable toolkit and datasets utilized for the submission of the paper.
3. Make sure the selected tag is v1.0-alpha.
4. Download the .zip file.

If you use this toolkit in your work, please include citations to the foundational papers that support its core functionalities. Some citations apply universally, while others are specific to the algorithms used within the toolkit.

Please cite these papers regardless of the specific algorithms used, as they support the foundational aspects of the toolkit:

1. ImageReg

2. RANSAC (Random Sample Consensus)

Fischler, M. A., & Bolles, R. C. (1981). Random sample consensus: a paradigm for model fitting with applications to image analysis and automated cartography. Communications of the ACM, 24(6), 381-395.

1. SIFT + ResNet50

Hamzehei, S., Bai, J., Raimondi, G., Tripp, R., Ostroff, L., & Nabavi, S. (2023, September). 3D Biological/Biomedical Image Registration with enhanced Feature Extraction and Outlier Detection. In Proceedings of the 14th ACM International Conference on Bioinformatics, Computational Biology, and Health Informatics (pp. 1-10).

Hamzehei, Sahand, et al. "Advanced Feature Extraction and Outlier Detection for 3D Biological/Biomedical Image Registration." IEEE Transactions on Computational Biology and Bioinformatics (2025).

2. AKAZE (Accelerated-KAZE)

Alcantarilla, P. F., & Solutions, T. (2011). Fast explicit diffusion for accelerated features in nonlinear scale spaces. IEEE Trans. Patt. Anal. Mach. Intell, 34(7), 1281-1298.

3. SIFT (Scale-Invariant Feature Transform)

Lowe, D. G. (1999, September). Object recognition from local scale-invariant features. In Proceedings of the seventh IEEE international conference on computer vision (Vol. 2, pp. 1150-1157). Ieee.

Lowe, D. G. (2004). Distinctive image features from scale-invariant keypoints. International journal of computer vision, 60, 91-110.

4. Affine Transformations

Wolberg, G. (1990). Digital Image Warping.

Ballard, D. H., & Brown, C. M. (1982). Computer vision. Prentice Hall Professional Technical Reference.

4. CAPTURE - Heatmap Distortion

Hamzehei, Sahand, et al. "CAPTURE: A Clustered Adaptive Patchwork Technique for Unified Registration Enhancement in Biological Imaging." Proceedings of the 15th ACM International Conference on Bioinformatics, Computational Biology and Health Informatics. 2024.