{"name":"napari-3dtimereg","display_name":"3D Movies Registration","visibility":"public","icon":"","categories":[],"schema_version":"0.2.1","on_activate":null,"on_deactivate":null,"contributions":{"commands":[{"id":"napari-3dtimereg.registration","title":"3D Movies Registration","python_name":"napari_3dtimereg.movieRegistration:start","short_title":null,"category":null,"icon":null,"enablement":null}],"readers":null,"writers":null,"widgets":[{"command":"napari-3dtimereg.registration","display_name":"Do 3D movie registration","autogenerate":false}],"sample_data":null,"themes":null,"menus":{},"submenus":null,"keybindings":null,"configuration":[]},"package_metadata":{"metadata_version":"2.1","name":"napari-3dtimereg","version":"0.0.13","dynamic":null,"platform":null,"supported_platform":null,"summary":"Registration of 3D movies applied to all channels","description":"# napari-3dtimereg\n\n[![License BSD-3](https://img.shields.io/pypi/l/napari-3dtimereg.svg?color=green)](https://gitlab.pasteur.fr/gletort/napari-3dtimereg/-/blob/main/LICENSE)\n[![PyPI](https://img.shields.io/pypi/v/napari-3dtimereg.svg?color=green)](https://pypi.org/project/napari-3dtimereg)\n[![Python Version](https://img.shields.io/pypi/pyversions/napari-3dtimereg.svg?color=green)](https://python.org)\n[![napari hub](https://img.shields.io/endpoint?url=https://api.napari-hub.org/shields/napari-3dtimereg)](https://napari-hub.org/plugins/napari-3dtimereg)\n\nTemporal registration of 2D/3D movies on one channel based on [itk-elastix](https://pypi.org/project/itk-elastix/), and transpose alignement to the other channels.\n\nAdaptated from [multireg](https://gitlab.pasteur.fr/gletort/multireg) for temporal movies.\nFor a tutorial on using `elastix` for registration, see [this tutorial](https://m-albert.github.io/elastix_tutorial/intro.html).\n\n* [Installation](#installation)\n    * [System requirement](#system-requirement)\n    * [Installation steps](#installation-steps)\n* [Usage](#usage)\n* [Demo](#demotest)\n* [License](#license)\n\n----------------------------------\n# Installation\n\n\n## System requirement\n\n`napari-3dtimereg` is a Napari plugin therefore can be installed on all operating systems. \nIt requires a python environement compatible with `Napari` and `elastix` version.\n\n### Tested system\nIt has been tested on python 3.9, napari XX and elastix XX.\n\n## Installation steps\n\nIn a python environment that contains Napari:\n\n* You can install the plugin directly in `Napari` by going to `Plugins>Install/Uninstall plugins` and search for `napari-3dtimereg`\n\n* Or you can install `napari-3dtimereg` via [pip]:\n\n    pip install napari-3dtimereg\n\n\nIf you don't have Napari installed yet, see [here](https://napari.org/stable/tutorials/fundamentals/quick_start.html#napari-quick-start) for installation instructions.\n\n\n# Usage\n\nYou can launch `3dtimereg` in napari by going to `Plugins>Do 3D movie registration (napari-3dtimereg)`.\n\n### Choose movie and reference chanel\n\nFirst, choose select the movie that you want to register. The plugin will create a folder `aligned` in the folder of your selected movie where the results will be saved.\n\nChoose the color chanel on which to calculate the registration (`reference chanel`). Color chanels are numbered from 0 to nchanels, and you can see their respective number in the layer list on the left panel of Napari. Click on `Update` when the correct chanel is selected to go to the registration calculation step.\n\n### Calculate temporal alignement\n\nThe registration is calculated iteratively from one frame to another. Thus the first frame is not moved and all the other frames are aligned to it.\nYou can tune several parameters in this plugin:\n\n![parameters screenshot](./imgs/parameters.png \"Registration parameters\")\n\nThe other parameters are parameters to use [itk-elastix](https://elastix.lumc.nl/) to calculate the registration.\n* `show log`: to see the log of Elastix calculation\n* `do rigid`: performs a rigid (affine) transformation step, that allowed to correct for translations/rotations.\n* `do bspline`: performs a b-spline based transformation step, that allowed for local deformations in the image.\n* `show advanced parameters`: to control the parameters used in the rigid and/or bspline transformations. These parameters control the size of the local registrations calculated, the resolutions at which the transformations are calculated, and can thus greatly impact the results.\n* `final order`: is the final order of the B-Splines used for the registration. \n* `resolution`: is the number of consecutives resolutions at which the registration will be made. First the registration is made at the lowest level of resolution, correcting global deformations/motions, then at each step, the registration is done on higher resolution, allowing to correct for more local deformations.\n* `final spacing`: is the physical spacing of the smallest resolution.\n* `iterations`: are the maximum number of iterations allowed to minimize the distance between the two images for each resolution and type of registration.\n\nIf both rigid and bspline transformations, the program first applies the rigid transformation to allow for a global registration of the images. Then it will performs the second step of b-spline transformation that can includes local deformations.\n\nFor each frame, after calculating the registration on the reference chanel, the plugin will apply the calculated transformation to all the other color chanels of the initial movie. All results are saved as separated images in the `aligned` folder during the computation.\n\n### Create the final aligned movie\n\nWhen all frames have been processed, each color chanel and each frame have been saved in the `aligned` folder as separated images. This is usefull to calculate the registration on large movies without having to keep all the intermediates and calculated images in memory. You can directly use these separated images, or reconstruct a single composite movie of the result.\n\nIf you click on `Concatenate aligned images` on the plugin interface, the plugin will create a single composite movie from the aligned images, save it and delete the separated images in the `aligned` folder. \n\n\n# Demo/Test\n\nTo test this plugin, you can use our [demo dataset](https://zenodo.org/records/15028169) proposed in a Zenodo repository or directly on your own dataset.\nIf you use the data from the Zenodo repository, the file to use to test this plugin is the movie `Registration_WTn1_Crop_V1.tif` which has been cropped from our dataset to reduce the size.\n\n## Steps\nThe input of the process should be a `.tiff` 3D and temporal stack with one or more channels. \nIf you want to use fix points registration option, you should have a file that contains the position of each tracked point at each time.\nSee in our demo dataset for the format of this file.\nIt can be for example generated from a [TrackMate](https://imagej.net/plugins/trackmate/) file with the macro [getTimePoints.py](./src/napari_3dtimereg/getTimePoints.py) proposed in this repository. \nRun it in Fiji by going to `Plugins>Macro>Edit`, openning the [getTimePoints.py](./src/napari_3dtimereg/getTimePoints.py) macro and then click `Run`.\nIt will generate a file `reference_points.csv` that you should put in the same folder as your movie to register (or select this file in the plugin interface in the `refpoints file` parameter).\n\nActivate your python virtual environement in which napari and the plugin are installed.\nFor example, if the name of the environment is `timereg-env`, type: `conda activate timereg-env`.\n\nWhen it's activated, type `napari` to start Napari. \nGo to `Plugins>napari-3dtimereg` to start it.\n\nLoad the movie to register. The plugin will ask you to choose the channel on which to calculate the registration, so choose a channel that should be immobile during the movie (for example, the channel containing the fibers which should be stable over time).\nSet the `reference channel` to the corresponding channel number (that you can see in the bottom left part of the viewer, with the layers name `Movie_C_*`). In our example dataset, choose `0` as the reference channel (the red channel that contains the fibers).\n\n![example screenshot](./imgs/load.png)\n\nClick `Update` to get to the step to choose the [registration parameters](#calculate-temporal-alignement).\n\n### Parameters\n\nIn [Sarde et al., 2025](https://www.biorxiv.org/content/10.1101/2025.03.13.643016v1), we used the following parameter values to register our intravital movies:\n* `use reference points: True`\n* `rigid resolution: 4`\n* `spline resolution: 2`\n* `iterations: 1000`\n* `rigid final spacing: 50`\n* `spline final spacing: 200`\n* `final order: 1`\n\nWhen the parameters have been selected, the registration will be calculated. \nThis step can take a lot of time depending on your movie size. \n\nWhen it will be finished, you get a single layer \"Res\" with the registered channels that have been combined in a single file.\n\n![result screenshot](./imgs/result.png)\n\n\n## Output\nAt the end of the process, you will get a folder named `aligned` in which the registered movie will be saved. \n\n**running time:** this plugin can be quite slow to run. In this cropped example, count around *1h* to run the registration, but for a full movie, it can takes up to several hours.\n\n\n# License\n\nDistributed under the terms of the [BSD-3] license, \"napari-3dtimereg\" is free and open source software.\n\nIf you use it, please cite our paper [Sarde et al., 2025](https://www.biorxiv.org/content/10.1101/2025.03.13.643016v1). \n\n\n[napari]: https://github.com/napari/napari\n[@napari]: https://github.com/napari\n[BSD-3]: http://opensource.org/licenses/BSD-3-Clause\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":null,"download_url":null,"author":null,"author_email":"Gaëlle Letort <gaelle.letort@pasteur.fr>","maintainer":null,"maintainer_email":null,"license":"BSD-3-Clause","classifier":["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","napari","magicgui","qtpy","tifffile","imaris-ims-file-reader","czifile","itk==5.3.0","itk-registration","itk-elastix","pydantic<=1.10.14"],"requires_python":">=3.8","requires_external":null,"project_url":["Homepage, https://gitlab.pasteur.fr/gletort/napari-3dtimereg","Bug Tracker, https://gitlab.pasteur.fr/gletort/napari-3dtimereg/issues","Documentation, https://gitlab.pasteur.fr/gletort/napari-3dtimereg#README.md","Source Code, https://gitlab.pasteur.fr/gletort/napari-3dtimereg"],"provides_extra":null,"provides_dist":null,"obsoletes_dist":null},"npe1_shim":false}