{"name":"napari-manual-registration","display_name":"Manual registration","visibility":"public","icon":"","categories":[],"schema_version":"0.2.1","on_activate":null,"on_deactivate":null,"contributions":{"commands":[{"id":"napari-manual-registration.run_registration","title":"Run manual registration","python_name":"napari_manual_registration:RegistrationWidget","short_title":null,"category":null,"icon":null,"enablement":null}],"readers":null,"writers":null,"widgets":[{"command":"napari-manual-registration.run_registration","display_name":"Manual registration","autogenerate":false}],"sample_data":null,"themes":null,"menus":{},"submenus":null,"keybindings":null,"configuration":[]},"package_metadata":{"metadata_version":"2.4","name":"napari-manual-registration","version":"0.0.4","dynamic":["license-file"],"platform":null,"supported_platform":null,"summary":"A simple plugin to register 2 views of the same object","description":"# :herb: napari-manual-registration\n\n[](https://github.com/jules-vanaret/napari-manual-registration/raw/main/LICENSE)\n[](https://pypi.org/project/napari-manual-registration)\n[](https://python.org)\n[](https://github.com/jules-vanaret/napari-manual-registration/actions)\n[](https://codecov.io/gh/jules-vanaret/napari-manual-registration)\n[](https://napari-hub.org/plugins/napari-manual-registration)\n\n![](\"https://github.com/GuignardLab/tapenade/blob/main/imgs/tapenade3.png\")
\n\nA plugin to obtain parameters for affine transform used to register two views of the same object, e.g as obtained with dual-view microscopes. \n\n`napari-manual-registration` is a [napari] plugin that is part of the [Tapenade](https://github.com/GuignardLab/tapenade) project. Tapenade is a tool for the analysis of dense 3D tissues acquired with deep imaging microscopy. It is designed to be user-friendly and to provide a comprehensive analysis of the data.\n\nIf you use this plugin for your research, please [cite us](https://github.com/GuignardLab/tapenade/blob/main/README.md#how-to-cite).\n\n## Overview\n\nA. Registration by annotating salient landmarks|B. Registration by selecting explicit transformation parameters\n--|--\n![](\"imgs/napari_registration_demo2_3.gif\")
|![](\"imgs/napari_registration_demo_3.gif\")
\n\nWhile working with large and dense 3D and 3D+time gastruloid datasets, we found that being able to visualise and interact with the data dynamically greatly helped processing it.\nDuring the pre-processing stage, dynamical exploration and interaction led to faster tuning of the parameters by allowing direct visual feedback, and gave key biophysical insight during the analysis stage. \n\nWhen using our automatic registration tool to spatially register two views of the same organoid, we were sometimes faced with the issue that the tool would not converge to the true registration transformation. This happens when the initial position and orientation of the floating view are too far from their target values. We thus designed a Napari plugin to quickly find a transformation that can be used to initialize our registration tool close to the optimal transformation. From two images loaded in Napari representing two views of the same organoid, the plugin allows the user to \n\n1. **annotate matching salient landmarks** (e.g bright dead cells or lumen-like structures) in both the reference and floating views, from which an optimal rigid transformation can be found automatically using principal component analysis.\n\n\n\n2. **manually define a rigid transformation** by continually varying 3D rotations and translations while observing the results until a satisfying fit is found\n\n![](\"imgs/Fig_Napari_registration.png\")
\n\n## Installation\n\nThe plugin obviously requires [napari] to run. If you don't have it yet, follow the instructions [here](https://napari.org/stable/tutorials/fundamentals/installation.html).\n\nThe simplest way to install `napari-manual-registration` is via the [napari] plugin manager. Open Napari, go to `Plugins > Install/Uninstall Packages...` and search for `napari-manual-registration`. Click on the install button and you are ready to go!\n\nYou can also install `napari-manual-registration` via [pip]:\n\n pip install napari-manual-registration\n\nTo install latest development version :\n\n pip install git+https://github.com/jules-vanaret/napari-manual-registration.git\n\n## Usage\n\nThe plugin provides two methods to register two views of the same object. The first method consists in manually drawing landmarks in both views, from which the optimal transformation is found automatically using principal component analysis. The second one consists in selecting manually each transformation parameter (rotation and translation) while observing the result in real-time, either in 2D or 3D (the user can switch between 2D and 3D at any time).\n\n> [!CAUTION]\n> Be aware that the visualization does not accomodate for voxel anisotropy, so we recommend using isotropic data, or to resize you anisotropic data to an isotropic voxel size (e.g by using [napari-tapenade-processing](https://github.com/GuignardLab/napari-tapenade-processing)).\n\n### A. Registration by annotating salient landmarks\n\n![](\"imgs/reg_2_3.png\")
\n\nSteps:\n1. First, load your images in Napari. You can drag and drop them from your file explorer to the Napari viewer, or open them using the `File > Open files...` menu.\n2. Click on the `Plugins > Manual Registration` menu to open the plugin.\n3. Select the reference layer from the combo box. The reference layer is chosen to be the one that does not move.\n4. Select the floating layer from the combo box. The floating layer is the one that will be transformed.\n5. Click the `Create landmarks layers` button to create two new Labels layers that will be used to annotate the landmarks in the reference and floating views.\n6. We recommend pressing the `Format layers for landmarks matching` button so that your layers are automatically formatted for you to begin the registration process. Napari offers a wide range of customisation options for the layers appearances, so feel free to play with them if our formatting does not fit your preferences. ;)\n7. We first recommend hiding the reference layer and the reference landmarks layer by clicking on the eye icon next to the layer name in the layer list. This will allow you to focus on the floating layer and the floating landmarks layer.\n8. Click on the `landmarks_floating` layer in the layer list to select it. \n9. Click on the `Activate the paint brush` button in the layer properties widget. This will allow you to draw landmarks in the floating view.\n10. Navigate through the z-slices of your images using the slider at the bottom of the plugin window.\n11. When you have found a salient landmark in the floating view, start drawing a \"blob\" around it by clicking and dragging your mouse. You can adjust the size of the brush using the `Brush size` slider in the layer properties widget. The shape of the \"blob\" you draw does not matter, as the plugin currently only uses the center of mass of the \"blob\" to locate the landmark.\n12. Once you have drawn a landmark, click on the `+` button in the layer properties widget to increase the label value. This will allow you to draw another landmark. Change label value after each landmark you draw. Repeat steps 10 to 12 until you have annotated all the salient landmarks in the floating view.\n13. Once you have annotated all the salient landmarks in the floating view, hide the floating layers, and show the reference layers and the reference landmarks layer by clicking on the eye icon next to the layer name in the layer list.\n14. Click on the `landmarks_reference` layer in the layer list to select it.\n15. Navigate to the z-slice of the reference view that corresponds to the z-slice of the floating view where you drew the first landmark.\n16. Draw a \"blob\" around the corresponding landmark in the reference view by clicking and dragging your mouse.\n17. Increment your label value by clicking on the `+` button in the layer properties widget each time you draw a new widget. Repeat steps 15 to 17 until you have annotated all the salient landmarks in the reference view.\n18. Once you have annotated all the salient landmarks in the reference view, click on the `Run landmark registration` button. The plugin will automatically find the optimal transformation that aligns the floating landmarks to the reference landmarks using principal component analysis. \n19. If you are satisfied with the registration, choose a directory to save the transformation parameters by clicking on the `Choose directory` button. The transformation parameters will be saved in a `.json` file in this directory. Finally, click on the `Save to JSON` button to save the transformation parameters.\n\n### B. Registration by selecting explicit transformation parameters\n\n\n#### Registration with 3D view\n\nWe describe below the steps to register two views of the same object in a purely 3D manner. Note that the plugin also allows to switch between 2D and 3D at any time, and 2D view is described in the next section. \n\n![](\"imgs/reg_0.png\")
\n\nSteps:\n1. First, load your images in Napari. You can drag and drop them from your file explorer to the Napari viewer, or open them using the `File > Open files...` menu.\n2. Click on the `Plugins > Manual Registration` menu to open the plugin.\n3. Select the reference layer from the combo box. The reference layer is chosen to be the one that does not move.\n4. Select the floating layer from the combo box. The floating layer is the one that will be transformed.\n5. We recommend pressing the `Format layers for explicit registration` button so that your layers are automatically formatted for you to begin the registration process. Napari offers a wide range of customisation options for the layers appearances, so feel free to play with them if our formatting does not fit your preferences. ;)\n6. You can now start the registration process by moving the `Translations` and `Rotations` sliders. The floating layer will be transformed in real-time according to the selected parameters. \n7. To optimize the visibility of your images, you can change the contrast limits and opacity of a layer by clicking on the layer name in the layer list and adjusting the sliders in the layer properties widget.\n8. If you wish to hide a layer, you can click on the eye icon next to the layer name in the layer list.\n9. Once you are satisfied with the registration, choose a directory to save the transformation parameters by clicking on the `Choose directory` button. The transformation parameters will be saved in a `.json` file in this directory.\n10. Finally, click on the `Save to JSON` button to save the transformation parameters.\n\n#### Registration with 2D view\n\n![](\"imgs/reg_1.png\")
\n\nSteps (the steps 1 to 5 are the same as for the 3D registration):\n6. If you want to switch to the 2D view, click on the `Toggle 2D/3D view` button (it resembles a square when in 2D mode, or a cube when in 3D mode).\n7. Again, feel free to play with the contrast limits and opacity of the layers to optimize the visibility of your images. First click on the layer name in the layer list, then adjust the sliders in the layer properties widget.\n8. If you wish to hide a layer, you can click on the eye icon next to the layer name in the layer list.\n9. In 2D mode, a slider appears at the bottom of the plugin window. You can use it to slide through the z-slices of your images.\n10. You can now start the registration process by moving the `Translations` and `Rotations` sliders. The floating layer will be transformed in real-time according to the selected parameters.\n11. Once you are satisfied with the registration, choose a directory to save the transformation parameters by clicking on the `Choose directory` button. The transformation parameters will be saved in a `.json` file in this directory. Finally, click on the `Save to JSON` button to save the transformation parameters.\n\n## Demo dataset\n\nA demo dataset is available [here](https://amubox.univ-amu.fr/s/HLktPNLGgMF4jHT).\n\n### Content\n\nThis test dataset is composed of two 3D images `bottom_small.tif` and `top_small.tif` that correspond to two halves of the same sample.\n\n### How to use\n\n - Load the images from the folder (either drag and drop, or \"File>Open file(s)\").\n - Specify one of the images as the \"Reference layer\" (which is fixed), and the other one as the \"Layer to move\" (usually called \"floating\").\n - Choose between the \"Explicit transforms\" or \"Landmarks matching\" modes, and follow instructions on the plugin repository for further use. \n\n## Contributing\n\nContributions are very welcome. Tests can be run with [tox], please ensure\nthe coverage at least stays the same before you submit a pull request.\n\n## License\n\nDistributed under the terms of the [BSD-3] license,\n\"napari-manual-registration\" is free and open source software\n\n## Issues\n\nIf you encounter any problem using this plugin, please [file an issue] on the GitHub repository.\n\n----------------------------------\n\nThis [napari] plugin was generated with [Cookiecutter] using [@napari]'s [cookiecutter-napari-plugin] template.\n\n[napari]: https://github.com/napari/napari\n[Cookiecutter]: https://github.com/audreyr/cookiecutter\n[@napari]: https://github.com/napari\n[MIT]: http://opensource.org/licenses/MIT\n[BSD-3]: http://opensource.org/licenses/BSD-3-Clause\n[GNU GPL v3.0]: http://www.gnu.org/licenses/gpl-3.0.txt\n[GNU LGPL v3.0]: http://www.gnu.org/licenses/lgpl-3.0.txt\n[Apache Software License 2.0]: http://www.apache.org/licenses/LICENSE-2.0\n[Mozilla Public License 2.0]: https://www.mozilla.org/media/MPL/2.0/index.txt\n[cookiecutter-napari-plugin]: https://github.com/napari/cookiecutter-napari-plugin\n\n[file an issue]: https://github.com/jules-vanaret/napari-manual-registration/issues\n\n[napari]: https://github.com/napari/napari\n[tox]: https://tox.readthedocs.io/en/latest/\n[pip]: https://pypi.org/project/pip/\n[PyPI]: https://pypi.org/\n","description_content_type":"text/markdown","keywords":null,"home_page":"https://github.com/jules-vanaret/napari-manual-registration","download_url":null,"author":"Alice Gros, Jules Vanaret","author_email":"jules.vanaret@univ-amu.fr","maintainer":null,"maintainer_email":null,"license":"BSD-3-Clause","classifier":["Development Status :: 2 - Pre-Alpha","Framework :: napari","Intended Audience :: Developers","License :: OSI Approved :: BSD License","Operating System :: OS Independent","Programming Language :: Python","Programming Language :: Python :: 3","Programming Language :: Python :: 3 :: Only","Programming Language :: Python :: 3.8","Programming Language :: Python :: 3.9","Programming Language :: Python :: 3.10","Topic :: Scientific/Engineering :: Image Processing"],"requires_dist":["numpy","scipy","magicgui","qtpy","pyclesperanto_prototype","scikit-image","tox; extra == \"testing\"","pytest; extra == \"testing\"","pytest-cov; extra == \"testing\"","pytest-qt; extra == \"testing\"","napari; extra == \"testing\"","pyqt5; extra == \"testing\""],"requires_python":">=3.8","requires_external":null,"project_url":["Bug Tracker, https://github.com/jules-vanaret/napari-manual-registration/issues","Documentation, https://github.com/jules-vanaret/napari-manual-registration#README.md","Source Code, https://github.com/jules-vanaret/napari-manual-registration","User Support, https://github.com/jules-vanaret/napari-manual-registration/issues"],"provides_extra":["testing"],"provides_dist":null,"obsoletes_dist":null},"npe1_shim":false}