diff --git a/README.md b/README.md index 7e77c0f..b1dd0e5 100644 --- a/README.md +++ b/README.md @@ -9,7 +9,7 @@ **Images_Alignment** is an application dedicated to ease the images alignment using affine transformation matrices calculated either from the [pyStackReg](https://github.com/glichtner/pystackreg) or [SIFT](https://scikit-image.org/docs/stable/auto_examples/features_detection/plot_sift.html) algorithm, a combined approach, or from a user driven approach (specifying manually the matching points). -Once the parameters have been set, these ones can be applied automatically to a set of images as a workflow. +Once the parameters have been set, they can be automatically applied to a set of images as part of a workflow.


diff --git a/doc/source/index.rst b/doc/source/index.rst index b920840..4edc1c1 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -2,6 +2,54 @@ Welcome to the Image_Alignment documentation ! ============================================== +**Images_Alignment** is an application dedicated to ease the images alignment using affine transformation matrices calculated either from the `pyStackReg `_ or `SIFT `_ algorithm, a combined approach, or from a user driven approach (specifying manually the matching points). + +Once the parameters have been set, they can be automatically applied to a set of images as part of a workflow. + +**This documentation mainly focuses on using the application in GUI mode.** + +For a **scripting mode usage**, please refer to the final section of this documentation. + + +Installation +------------ + +Assuming you have a python environment which is activated in a terminal, the application can be installed thanks the ``pip`` command: + +```bash +pip install git+https://github.com/CEA-MetroCarac/images_alignment.git +``` + +Once installed, the application can be launched directly from a terminal (with the previous python environment activated), by: + +```bash +images_alignment +``` + +Tests execution +--------------- + +For developers, the full package including examples and tests can be installed via: + +```bash +git clone https://github.com/CEA-MetroCarac/images_alignment.git +cd images_alignment +pip install . +``` + +The tests can be executed via the following commands: + +```bash +pip install pytest +pytest tests +``` + + + +Image_Alignment documentation +----------------------------- + + .. toctree:: :maxdepth: 1 :caption: GUI Mode diff --git a/doc/source/user_guide/application.rst b/doc/source/user_guide/application.rst index 44bf243..d7ea434 100644 --- a/doc/source/user_guide/application.rst +++ b/doc/source/user_guide/application.rst @@ -6,11 +6,11 @@ The application of the previously defined parameters to a set of images is handl This requires the user to have pre-defined a **"results"** folder to store the alignment results. This **"results"** folder will contain two sub-folders: **fixed_images** and **moving_images**, which will contain the processed images. .. note:: - Since the user can choose to invert the "Fixed/Moving" roles using the ``INV`` button, each **Fixed** (corresponding to a moving image in the ``INV`` mode) is saved with an extension related to its processing order in the workflow. + In the case of a 1-to-N image processing, the ``INV`` mode can not be activated. .. warning:: - To facilitate the viewing of the realigned images after processing, the images displayed in the visualization windows are those located in the **"results"** directories. Changing the images in the processed set can be done using the image selection frames. Consequently, the displayed images are no longer the original images. + To facilitate the viewing of the realigned images after processing, the images displayed in the visualization windows are those located in the **"results"** directories. - Any new registration will then apply to these processed images and potentially overwrite them. + **Consequently**, any new alignment will then be performed from these already processed images, with the risk to overwrite them when saving. - To reprocess the original images, it is necessary to uncheck the ``Show results`` checkbox. \ No newline at end of file + **To go back to the original images, uncheck the ``Show results`` checkbox.** \ No newline at end of file diff --git a/doc/source/user_guide/intro.rst b/doc/source/user_guide/intro.rst index 03e6983..4252c51 100644 --- a/doc/source/user_guide/intro.rst +++ b/doc/source/user_guide/intro.rst @@ -1,11 +1,7 @@ Introduction ============ -**Images_Alignment** is an application dedicated to ease the images alignment using affine transformation matrices calculated either from the `pyStackReg `_ or `SIFT `_ algorithm, a combined approach, or from a user driven approach (specifying manually the matching points). -**This documentation mainly focuses on using the application in GUI mode.** - -For scripting mode usage, please refer to the final section of this documentation. The application's GUI consists of 4 main panels, described in the following pages. diff --git a/doc/source/user_guide/parameters.rst b/doc/source/user_guide/parameters.rst index d174898..6293e53 100644 --- a/doc/source/user_guide/parameters.rst +++ b/doc/source/user_guide/parameters.rst @@ -1,6 +1,8 @@ Files selection / Parameters settings ------------------------------------- +This section and the the following ones address features belonging to the Panel **1** (as defined in the 'Intro' section). + Files selection ~~~~~~~~~~~~~~~ @@ -33,7 +35,7 @@ The **alignment** is performed in pairs. By consequence the number of selected i Defining ROIs ~~~~~~~~~~~~~ -In addition to defining ROIs (regions of interest) using the mouse, they can also be specified textually in the dedicated fields, following the convention: **[xmin, xmax, ymin, ymax]**, based on the coordinate system of the image displayed in **Panel 4**. +In addition to defining ROIs (regions of interest) using the mouse ni the main Figure window (Panel **4**), they can also be specified textually in the related fields, following the convention: **[xmin, xmax, ymin, ymax]**, based on the coordinate system of the image displayed in **Panel 4**. .. figure:: ../_static/roi.png diff --git a/doc/source/user_guide/processing.rst b/doc/source/user_guide/processing.rst index cd866c9..68a67e0 100644 --- a/doc/source/user_guide/processing.rst +++ b/doc/source/user_guide/processing.rst @@ -18,11 +18,11 @@ With each registration computation, the matrix corresponding to the **affine tra [ -0.63508967 1.16203181 52.11186476] [ 0. 0. 1. ]] -The ``INV`` mode allows the roles of "fixed" and "moving" images to be reversed. +The ``INV`` mode allows the roles of **Fixed** and **Moving** images to be reversed during the registration processing. -After registration, the resulting images can be saved via the ``SAVE IMAGES`` button. +After registration, each of these images can be saved via the ``SAVE IMAGES`` button. -The alignment parameters (e.g., ROIs, binarization thresholds) can also be saved in .json file using ``SAVE PARAMS`` for later reuse with ``RELOAD PARAMS``. +The alignment parameters (e.g., ROIs, thresholds, ...) can also be saved in a .json file using ``SAVE PARAMS`` for later reuse with ``RELOAD PARAMS``. .. note:: To reduce computation times during the registration processing, high-resolution images are sub-sampled to a size of **512 pixels** per dimension. This criterion can be adjusted through the ``Max image size`` parameter under the **Registration** section in the ``Options`` tab. \ No newline at end of file diff --git a/doc/source/user_guide/registration.rst b/doc/source/user_guide/registration.rst index 600df0d..3a6b2be 100644 --- a/doc/source/user_guide/registration.rst +++ b/doc/source/user_guide/registration.rst @@ -6,13 +6,13 @@ Registration algorithms StackReg ~~~~~~~~ -This algorithm is based on a minimization processing based on **cross-correlation** of binarized images (of identical size). Binarization and image resizing are handled automatically within the code. Binarization is performed to achieve, as closely as possible, a 50-50 distribution of True-False (or 0-1) values for the selected regions (either ROIs or entire images). In some cases, users have to adjust this threshold in the ``Options`` tab to better highlight features essential for accurate alignment. +This algorithm is based on a minimization processing based on **cross-correlation** of binarized images of similar size. Binarization and image resizing are handled automatically within the code. Binarization is performed to achieve, by default and as closely as possible, a 50-50 distribution of True-False (or 0-1) values for the selected regions (either ROIs or entire images). In some cases, users have to adjust this threshold in the ``Options`` tab to better highlight features essential for accurate alignment. .. figure:: ../_static/stackreg_threshold.png :align: center :width: 100% - Adjustment of the Threshold related to the binarization in the ``Options`` tab. + Illustration of adjusting the ``Threshold`` in the ``Options`` tab to reveal features. It is important to note that ``StackReg`` relies on a gradient descent method to minimize misalignment. Therefore, it requires the images to already have significant overlap in their features to function effectively. @@ -40,7 +40,7 @@ Due to the random sampling process used to match features between images, consec SIFT + StackReg ~~~~~~~~~~~~~~~ -This combined approach leverages the strengths of both methods. ``SIFT`` first performs a coarse alignment, bringing potentially highly misaligned images closer together. Then, ``StackReg`` refines this alignment to achieve possibily a higher level of precision. +This combined approach leverages the strengths of both methods. ``SIFT`` first performs a primary alignment, bringing potentially highly misaligned images closer together. Then, ``StackReg`` refines this alignment to achieve possibily a higher level of precision. User-Driven diff --git a/doc/source/user_guide/scripting.rst b/doc/source/user_guide/scripting.rst index 3e6e16f..e551470 100644 --- a/doc/source/user_guide/scripting.rst +++ b/doc/source/user_guide/scripting.rst @@ -1,13 +1,11 @@ Scripting --------- -Every operation performed through the GUI can also be executed in scripting mode. - -Below is a brief illustration of image alignment by adjusting a few parameters:: +Every operation performed through the GUI can also be executed in scripting mode. Here is a brief illustration:: from images_alignment import ImagesAlign - imgalign = ImagesAlign(fixed_images=['img1.tif'], fnames_moving=['img2_1.tif', 'img2_2.tif', 'img2_3.tif', ...]) + imgalign = ImagesAlign(fixed_images=['img1.tif'], fnames_moving=['img2_1.tif', 'img2_2.tif', ...]) imgalign.angles = [0, 90] imgalign.thresholds = [0.50, 0.65] diff --git a/doc/source/user_guide/visualization.rst b/doc/source/user_guide/visualization.rst index f2bb38c..86412b6 100644 --- a/doc/source/user_guide/visualization.rst +++ b/doc/source/user_guide/visualization.rst @@ -17,7 +17,7 @@ Once the images to be processed are selected (see next section), **Panel 2** pro - Selecting the juxtaposition mode: choosing between horizontal or vertical alignment of the images. -- Displaying the Combined images considering the full frame or their overlapping regions only (Apply Mask to ``True``). +- Displaying the Combined images considering the full frame or their overlapping regions only (enabling ``Apply Mask``). **Panel 3** as 'thumbnails' allows users to select the type of image (**Fixed image**, **Moving image**, **Juxtaposed images** or **Combined image**) to view in within **Panel 4**. diff --git a/pyproject.toml b/pyproject.toml index 4b04736..852ff60 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -4,13 +4,20 @@ build-backend = 'setuptools.build_meta' [project] name = "images_alignment" -version = "2024.2beta" +version = "2024.2" description = "images alignment application" authors = [{ name = "Patrick Quéméré", email = "patrick.quemere@cea.fr" }] readme = "README.md" +requires-python = ">= 3.8" classifiers = [ "License :: OSI Approved :: GNU General Public License v3", "Operating System :: OS Independent", + "Programming Language :: Python", + "Programming Language :: Python :: 3.8", + "Programming Language :: Python :: 3.9", + "Programming Language :: Python :: 3.10", + "Programming Language :: Python :: 3.11", + "Programming Language :: Python :: 3.12", ] dependencies = [ "numpy",