# napari-pystackreg
[](https://github.com/glichtner/napari-pystackreg/raw/main/LICENSE)
[](https://pypi.org/project/napari-pystackreg)
[](https://python.org)
[](https://github.com/glichtner/napari-pystackreg/actions)
[](https://codecov.io/gh/glichtner/napari-pystackreg)
[](https://napari-hub.org/plugins/napari-pystackreg)
Robust image registration for napari.
## Summary
napari-pystackreg offers the image registration capabilities of the python package
[pystackreg](https://github.com/glichtner/pystackreg) for napari.
## Description
pyStackReg is used to align (register) one or more images to a common reference image, as is required usually in
time-resolved fluorescence or wide-field microscopy.
It is directly ported from the source code of the ImageJ plugin ``TurboReg`` and provides additionally the
functionality of the ImageJ plugin ``StackReg``, both of which were written by Philippe Thevenaz/EPFL
(available at http://bigwww.epfl.ch/thevenaz/turboreg/).
pyStackReg provides the following five types of distortion:
- Translation
- Rigid body (translation + rotation)
- Scaled rotation (translation + rotation + scaling)
- Affine (translation + rotation + scaling + shearing)
- Bilinear (non-linear transformation; does not preserve straight lines)
pyStackReg supports the full functionality of StackReg plus some additional options, e.g., using different reference
images and having access to the actual transformation matrices (please see the examples below). Note that pyStackReg
uses the high quality (i.e. high accuracy) mode of TurboReg that uses cubic spline interpolation for transformation.
Please note: The bilinear transformation cannot be propagated, as a combination of bilinear transformations does not
generally result in a bilinear transformation. Therefore, stack registration/transform functions won't work with
bilinear transformation when using "previous" image as reference image. You can either use another reference (
"first" or "mean" for first or mean image, respectively), or try to register/transform each image of the stack
separately to its respective previous image (and use the already transformed previous image as reference for the
next image).
## Installation
You can install ``napari-pystackreg`` via [pip](https://pypi.org/project/pip/) from [PyPI](https://pypi.org/):
pip install napari-pystackreg
You can also install ``napari-pystackreg`` via [conda](https://docs.conda.io/en/latest/):
conda install -c conda-forge napari-pystackreg
Or install it via napari's plugin installer.
Plugins > Install/Uninstall Plugins... > Filter for "napari-pystackreg" > Install
To install latest development version:
pip install git+https://github.com/glichtner/napari-pystackreg.git
## Usage
### Open Plugin User Interface
Start up napari, e.g. from the command line:
napari
Then, load an image stack (e.g. via ``File > Open Image...``) that you want to register. You can also use the example
stack provided by the pluging (``File > Open Sample > napari-pystackreg: PC12 moving example``).
Then, select the ``napari-pystackreg`` plugin from the ``Plugins > napari-pystackreg: pystackreg`` menu.
### User Interface Options
A variety of options are available to control the registration process:
* `Image Stack`: The image layer that should be registered/transformed.
* `Transformation`: The type of transformation that should be applied.
- `Translation`: translation
- `Rigid body`: translation + rotation
- `Scaled rotation`: translation + rotation + scaling
- `Affine`: translation + rotation + scaling + shearing
- `Bilinear`: non-linear transformation; does not preserve straight lines
* `Reference frame:` The reference image for registration.
- `Previous frame`: Aligns each frame (image) to its previous frame in the stack
- `Mean (all frames)`: Aligns each frame (image) to the average of all images in the stack
- `Mean (first n frames)`: Aligns each frame (image) to the mean of the first n frames in the stack. n is a tuneable parameter.
* `Moving-average stack before register`: Apply a moving average to the stack before registration. This can be useful to
reduce noise in the stack (if the signal-to-noise ratio is very low). The moving average is applied to the stack only
for determining the transformation matrices, but not for the actual transforming of the stack.
* `Transformation matrix file`: Transformation matrices can be saved to or loaded from a file for permanent storage.
### Reference frame
The reference frame is the frame to which the other frames are aligned. The default option is to use the
`Previous frame`, which will register each frame to its respective previous frame in the stack. Alternatively, the
reference frame can be set to the mean of all frames in the stack (`Mean (all frames)`) or the mean of the first n
frames in the stack (`Mean (first n frames)`). The latter option can be useful if the first frames in the stack are more
stable than the later frames (e.g. if the first frames are taken before the sample is moved). When selecting the
`Mean (first n frames)` option, the number of frames to use for the mean can be set via the spinbox below the option.
### Moving average before registration
To increase registration performance with low signal-to-noise ratio stacks, a moving average can be applied to the
stack before registration. The moving average is applied to the stack only for determining the
transformation matrices, but not for the actual transforming of the stack. That means that the transformed stack will
still contain the original frames (however registered), but not the averaged frames.
When selecting the `Moving-average stack before register` option, the number of frames to use for the moving average can
be set via the spinbox below the option.
### Transformation matrix file
The transformation matrices can be saved to or loaded from a file for permanent storage. This can be useful if you want
to apply the same transformation to another stack (e.g. a different channel of the same sample). The transformation
matrices are saved as a numpy array in a binary file (``.npy``). The file can be loaded via the `Load` button and saved
via the `Save` button.
### Register/Transform
To perform the actual registration and transformation steps, click the `Register` and `Transform` buttons, respectively.
The `Register` button will register the stack to the reference by determining the appropriate transformation matrices,
without actually transforming the stack. The transformation matrices can be saved to a file via the `Save` button in the
`Transformation matrix file` section.
The `Transform` button (1) will transform the stack to the reference by applying the transformation matrices that are
currently loaded to the stack selected in `Image Stack`. For the button to become active, either the transformation
matrices have to be loaded from a file via the `Load` button in the `Transformation matrix file` section, or the
`Register` button has to be clicked first to determine the transformation matrices.
The `Transform` button will also add a new image layer to the napari viewer (2) with the transformed stack. The name of the
new layer will be the name of the original stack with the prefix `Registered`.
Finally, the `Register & Transform` button will perform both the registration and transformation steps in one go.
----------------------------------
## Contributing
Contributions are very welcome. Tests can be run with [tox], please ensure
the coverage at least stays the same before you submit a pull request.
## License
Distributed under the terms of the [Apache Software License 2.0] license,
"napari-pystackreg" is free and open source software.
## Issues
If you encounter any problems, please [file an issue] along with a detailed description.
## Acknowledgments
This [napari] plugin was generated with [Cookiecutter] using [@napari]'s [cookiecutter-napari-plugin] template.
[napari]: https://github.com/napari/napari
[Cookiecutter]: https://github.com/audreyr/cookiecutter
[@napari]: https://github.com/napari
[MIT]: http://opensource.org/licenses/MIT
[BSD-3]: http://opensource.org/licenses/BSD-3-Clause
[GNU GPL v3.0]: http://www.gnu.org/licenses/gpl-3.0.txt
[GNU LGPL v3.0]: http://www.gnu.org/licenses/lgpl-3.0.txt
[Apache Software License 2.0]: http://www.apache.org/licenses/LICENSE-2.0
[Mozilla Public License 2.0]: https://www.mozilla.org/media/MPL/2.0/index.txt
[cookiecutter-napari-plugin]: https://github.com/napari/cookiecutter-napari-plugin
[file an issue]: https://github.com/glichtner/napari-pystackreg/issues
[napari]: https://github.com/napari/napari
[tox]: https://tox.readthedocs.io/en/latest/
[pip]: https://pypi.org/project/pip/
[PyPI]: https://pypi.org/
Raw data
{
"_id": null,
"home_page": "https://github.com/glichtner/napari-pystackreg",
"name": "napari-pystackreg",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "",
"keywords": "",
"author": "Gregor Lichtner",
"author_email": "gregor.lichtner@med.uni-greifswald.de",
"download_url": "https://files.pythonhosted.org/packages/8d/d6/80d198df5a0a8b8f579228b562b3fc2285b4b3c1eb0b3ddc2530e3466a83/napari_pystackreg-0.1.4.tar.gz",
"platform": null,
"description": "# napari-pystackreg\n\n[](https://github.com/glichtner/napari-pystackreg/raw/main/LICENSE)\n[](https://pypi.org/project/napari-pystackreg)\n[](https://python.org)\n[](https://github.com/glichtner/napari-pystackreg/actions)\n[](https://codecov.io/gh/glichtner/napari-pystackreg)\n[](https://napari-hub.org/plugins/napari-pystackreg)\n\nRobust image registration for napari.\n\n## Summary\nnapari-pystackreg offers the image registration capabilities of the python package\n[pystackreg](https://github.com/glichtner/pystackreg) for napari.\n\n\n\n## Description\n\npyStackReg is used to align (register) one or more images to a common reference image, as is required usually in\ntime-resolved fluorescence or wide-field microscopy.\nIt is directly ported from the source code of the ImageJ plugin ``TurboReg`` and provides additionally the\nfunctionality of the ImageJ plugin ``StackReg``, both of which were written by Philippe Thevenaz/EPFL\n(available at http://bigwww.epfl.ch/thevenaz/turboreg/).\n\npyStackReg provides the following five types of distortion:\n\n- Translation\n- Rigid body (translation + rotation)\n- Scaled rotation (translation + rotation + scaling)\n- Affine (translation + rotation + scaling + shearing)\n- Bilinear (non-linear transformation; does not preserve straight lines)\n\npyStackReg supports the full functionality of StackReg plus some additional options, e.g., using different reference\nimages and having access to the actual transformation matrices (please see the examples below). Note that pyStackReg\nuses the high quality (i.e. high accuracy) mode of TurboReg that uses cubic spline interpolation for transformation.\n\nPlease note: The bilinear transformation cannot be propagated, as a combination of bilinear transformations does not\ngenerally result in a bilinear transformation. Therefore, stack registration/transform functions won't work with\nbilinear transformation when using \"previous\" image as reference image. You can either use another reference (\n\"first\" or \"mean\" for first or mean image, respectively), or try to register/transform each image of the stack\nseparately to its respective previous image (and use the already transformed previous image as reference for the\nnext image).\n\n## Installation\n\nYou can install ``napari-pystackreg`` via [pip](https://pypi.org/project/pip/) from [PyPI](https://pypi.org/):\n\n pip install napari-pystackreg\n\nYou can also install ``napari-pystackreg`` via [conda](https://docs.conda.io/en/latest/):\n\n conda install -c conda-forge napari-pystackreg\n\nOr install it via napari's plugin installer.\n\n Plugins > Install/Uninstall Plugins... > Filter for \"napari-pystackreg\" > Install\n\nTo install latest development version:\n\n pip install git+https://github.com/glichtner/napari-pystackreg.git\n\n## Usage\n\n\n### Open Plugin User Interface\n\nStart up napari, e.g. from the command line:\n\n napari\n\nThen, load an image stack (e.g. via ``File > Open Image...``) that you want to register. You can also use the example\nstack provided by the pluging (``File > Open Sample > napari-pystackreg: PC12 moving example``).\nThen, select the ``napari-pystackreg`` plugin from the ``Plugins > napari-pystackreg: pystackreg`` menu.\n\n\n\n### User Interface Options\nA variety of options are available to control the registration process:\n\n* `Image Stack`: The image layer that should be registered/transformed.\n* `Transformation`: The type of transformation that should be applied.\n - `Translation`: translation\n - `Rigid body`: translation + rotation\n - `Scaled rotation`: translation + rotation + scaling\n - `Affine`: translation + rotation + scaling + shearing\n - `Bilinear`: non-linear transformation; does not preserve straight lines\n* `Reference frame:` The reference image for registration.\n - `Previous frame`: Aligns each frame (image) to its previous frame in the stack\n - `Mean (all frames)`: Aligns each frame (image) to the average of all images in the stack\n - `Mean (first n frames)`: Aligns each frame (image) to the mean of the first n frames in the stack. n is a tuneable parameter.\n* `Moving-average stack before register`: Apply a moving average to the stack before registration. This can be useful to\n reduce noise in the stack (if the signal-to-noise ratio is very low). The moving average is applied to the stack only\n for determining the transformation matrices, but not for the actual transforming of the stack.\n* `Transformation matrix file`: Transformation matrices can be saved to or loaded from a file for permanent storage.\n\n### Reference frame\nThe reference frame is the frame to which the other frames are aligned. The default option is to use the\n`Previous frame`, which will register each frame to its respective previous frame in the stack. Alternatively, the\nreference frame can be set to the mean of all frames in the stack (`Mean (all frames)`) or the mean of the first n\nframes in the stack (`Mean (first n frames)`). The latter option can be useful if the first frames in the stack are more\nstable than the later frames (e.g. if the first frames are taken before the sample is moved). When selecting the\n`Mean (first n frames)` option, the number of frames to use for the mean can be set via the spinbox below the option.\n\n\n\n### Moving average before registration\nTo increase registration performance with low signal-to-noise ratio stacks, a moving average can be applied to the\nstack before registration. The moving average is applied to the stack only for determining the\ntransformation matrices, but not for the actual transforming of the stack. That means that the transformed stack will\nstill contain the original frames (however registered), but not the averaged frames.\n\nWhen selecting the `Moving-average stack before register` option, the number of frames to use for the moving average can\nbe set via the spinbox below the option.\n\n\n\n### Transformation matrix file\nThe transformation matrices can be saved to or loaded from a file for permanent storage. This can be useful if you want\nto apply the same transformation to another stack (e.g. a different channel of the same sample). The transformation\nmatrices are saved as a numpy array in a binary file (``.npy``). The file can be loaded via the `Load` button and saved\nvia the `Save` button.\n\n\n\n### Register/Transform\nTo perform the actual registration and transformation steps, click the `Register` and `Transform` buttons, respectively.\n\nThe `Register` button will register the stack to the reference by determining the appropriate transformation matrices,\nwithout actually transforming the stack. The transformation matrices can be saved to a file via the `Save` button in the\n`Transformation matrix file` section.\n\n\n\nThe `Transform` button (1) will transform the stack to the reference by applying the transformation matrices that are\ncurrently loaded to the stack selected in `Image Stack`. For the button to become active, either the transformation\nmatrices have to be loaded from a file via the `Load` button in the `Transformation matrix file` section, or the\n`Register` button has to be clicked first to determine the transformation matrices.\n\nThe `Transform` button will also add a new image layer to the napari viewer (2) with the transformed stack. The name of the\nnew layer will be the name of the original stack with the prefix `Registered`.\n\n\n\nFinally, the `Register & Transform` button will perform both the registration and transformation steps in one go.\n\n----------------------------------\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 [Apache Software License 2.0] license,\n\"napari-pystackreg\" is free and open source software.\n\n## Issues\n\nIf you encounter any problems, please [file an issue] along with a detailed description.\n\n## Acknowledgments\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/glichtner/napari-pystackreg/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",
"bugtrack_url": null,
"license": "Apache-2.0",
"summary": "Robust image registration for napari",
"version": "0.1.4",
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "8770c30930db639a962ec33795dc488185bb3796fe708a09857763f1ea881411",
"md5": "58c9e928c7f6171425bc538ecb9139e0",
"sha256": "98d83be79ee86216bbbbf7dc1c58a5afb1aba8a3c571268187464a9f68654e73"
},
"downloads": -1,
"filename": "napari_pystackreg-0.1.4-py3-none-any.whl",
"has_sig": false,
"md5_digest": "58c9e928c7f6171425bc538ecb9139e0",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 18529,
"upload_time": "2023-01-15T13:51:23",
"upload_time_iso_8601": "2023-01-15T13:51:23.258961Z",
"url": "https://files.pythonhosted.org/packages/87/70/c30930db639a962ec33795dc488185bb3796fe708a09857763f1ea881411/napari_pystackreg-0.1.4-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "8dd680d198df5a0a8b8f579228b562b3fc2285b4b3c1eb0b3ddc2530e3466a83",
"md5": "ba7e70173e4e4fec81212d5e3e387c16",
"sha256": "ea3fb0b3ecc7b90b64f44c1ced4a85a6cf8231b07e5985ad59a6c1c152cd4cb3"
},
"downloads": -1,
"filename": "napari_pystackreg-0.1.4.tar.gz",
"has_sig": false,
"md5_digest": "ba7e70173e4e4fec81212d5e3e387c16",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 19720,
"upload_time": "2023-01-15T13:51:24",
"upload_time_iso_8601": "2023-01-15T13:51:24.803119Z",
"url": "https://files.pythonhosted.org/packages/8d/d6/80d198df5a0a8b8f579228b562b3fc2285b4b3c1eb0b3ddc2530e3466a83/napari_pystackreg-0.1.4.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-01-15 13:51:24",
"github": true,
"gitlab": false,
"bitbucket": false,
"github_user": "glichtner",
"github_project": "napari-pystackreg",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [],
"tox": true,
"lcname": "napari-pystackreg"
}
JSON
