{"name":"napari-zplane-depth-colorizer","display_name":"napari-zplane-depth-colorizer","visibility":"public","icon":"","categories":["Annotation","Visualization"],"schema_version":"0.2.1","on_activate":null,"on_deactivate":null,"contributions":{"commands":[{"id":"napari-zplane-depth-colorizer.make_qwidget","title":"Interactive Widget","python_name":"napari_zplane_depth_colorizer:ColorQWidget","short_title":null,"category":null,"icon":null,"enablement":null}],"readers":null,"writers":null,"widgets":[{"command":"napari-zplane-depth-colorizer.make_qwidget","display_name":"Z-Color","autogenerate":false}],"sample_data":null,"themes":null,"menus":{},"submenus":null,"keybindings":null,"configuration":[]},"package_metadata":{"metadata_version":"2.2","name":"napari-zplane-depth-colorizer","version":"1.0.1","dynamic":null,"platform":null,"supported_platform":null,"summary":"A simple plugin to color and merge z-planes of 3D data to give depth information.","description":"# napari-zplane-depth-colorizer\n\n[](https://github.com/maihanhoang/napari-zplane-depth-colorizer/raw/main/LICENSE)\n[](https://pypi.org/project/napari-zplane-depth-colorizer)\n[](https://python.org)\n[](https://github.com/maihanhoang/napari-zplane-depth-colorizer/actions)\n[](https://codecov.io/gh/maihanhoang/napari-zplane-depth-colorizer)\n[](https://napari-hub.org/plugins/napari-zplane-depth-colorizer)\n\nA simple plugin for 3d+t files that visualizes z-planes in 3 colors for depth information. \n\n----------------------------------\n\nThis [napari] plugin was generated with [Cookiecutter] using [@napari]'s [cookiecutter-napari-plugin] template.\n\n\n\nThis plugin can colorize and provide depth information on single-channel 3D+t files. The color coding enhances the visibility of structures and the detection/annotations of dynamic events. \n\n
\n \n
\n\nIdentifying dynamic events such as cellular divisions can be challenging in 3D time-lapses of developing tissues such as organoids or embryos. Visualizing and annotating such events in dense 3D stacks obtained by light-sheet or two-photon microscopy where nuclei are almost in contact is especially challenging. With this visualization method, the tissue section can be \"augmented\" in 3D by visualizing the surrounding tissue layers in different colors. \n\nThis plugin is for bioimaging researchers who need to annotate events in time lapses of dense tissues. It supports 3D+t stacks in the TZYX format. \n\n## Installation\n\nYou can install `napari-zplane-depth-colorizer` via [pip]:\n\n pip install napari-zplane-depth-colorizer\n\nTo install latest development version :\n\n pip install git+https://github.com/maihanhoang/napari-zplane-depth-colorizer.git\n\n## Quick Start\nA sample file can be found at `src/napari_zplane_depth_colorizer/data/3D+t.tif`\n\n1. Open a 3D+t tif in napari, make sure it is in TZYX format\n2. If it's a 4D file, it will automatically appear in the drop-down menu of *Input*\n3. Use default parameters for *Z-Projection Type* and *Depth Range*\n4. Click *Merge to RGB*\n5. Result will appear in the viewer and in *Output*\n6. To save, select the colored stack in *Output*, select saving format (*Save as*), and click *Save RGB*\n\n## Parameters\nThere are two depth augmentation parameters for each RGB color channel: Z-Projection Type and Depth Range. Depth Range indicates which and how many z-planes are projected for a channel. The Z-Projection Type specifies which type of projection is applied. The **How it works** section below might help you understand the parameters better.\n\n### Z-Projection Types \nThe Z-projection types are the same ones found in [Fiji](https://imagej.net/software/fiji/), except for \"Raw. \"Raw is the original stack without any projection.\n\n### Depth Range\n- Depth Range is a range and consists of two numbers [range_start, range_end]. The range is inclusive and requires range_start <= range_end. \n\n- Exception if Z-Projection Type is \"Raw\" since no z-projection is applied. The Depth Range for Raw can either be empty (equals 0 then) or a single number. \n\n- The Depth Range indicates the z-planes relative to the reference plane that are projected and then assigned to a color channel. The reference plane is the plane for which the color merging is currently computed.\n\n- In the illustration below, the current reference plane is the 4. plane (indicated by the color wheel in the right stack). A Depth Range of [-3, -1] for the red channel denotes the first three planes above the reference plane. Similarly, a Depth Range of [1, 2] for the blue channel indicates the first two planes below the reference plane. Negative numbers are for the planes above, and positive numbers are for ones below the reference plane. 0 is the same as the reference plane (the green plane in the illustration). \n\n
\n \n
\n\n\n## How it works\n### Creating a colored image from a single-channel stack\n\nTo colorize a single-channel stack, multiple z-planes are assigned to different color (RGB) channels and then overlaid to create a composite colored image. For a simple z-stack with three planes, the 1. plane is assigned to red, the 2. to green, and the 3. plane to blue. They are overlaid/merged to create a single composite RGB-color plane. In the composite image, multiple z-planes are displayed simultaneously, with the colors providing the depth information. In this example, red indicates that cells are in the upper, while blue cells are in the deeper z-planes. The colors make it easier to detect and track cells that move or split in the z-direction. \n\n\n\n
\n \n
\n\nOn the left is an image of a single plane of an organoid and on the right is the colorized plane. To create the colors, the same plane was overlaid with the direct upper and lower plane, as shown in the illustration above. \n
\n \n \n
\n\n### Colorizing the entire stack\nTo obtain a colorized stack of the same size as the original stack, the merging is applied for each z-plane. At the boundaries, the colors can differ, as there are no further z-planes to assign to a color channel. For example, the first plane in the colorized stack consists of an overlay of only two planes in green and blue, which results in a blue/green/cyan-colored image. Similarly, the last plane of the colorized stack is a red/green/yellowish image since it lacks a blue channel. \n\n
\n \n
\n\n### Varying the depth with z-projections\nIt is also possible to vary the depth and overlay more than three planes. To do this, a z-projection is applied to the planes before assigning them to a color and merging. In the illustration below, a different number of planes is assigned to each color. Before merging the three RGB color channels, a z-projection is applied if more than one plane is assigned to a color. In the illustration below, three planes are selected for the red color channel. A z-projection (e.g. average intensity) is applied to generate a single plane for the red channel. This z-projected plane is merged with the raw, green plane and the z-projected plane of the blue channel. \n\n\n
\n \n
\n\nFor the entire stack:\n
\n \n
\n\nOn the left is an image of a single plane of an organoid, and on the right is the colorized plane. To create the colors, the same plane was overlaid with three upper and two lower z-planes, as shown in the illustration above. \n\n
\n \n \n
\n\n## Acknowledgements\n[Sham Tlili](https://scholar.google.com/citations?user=8ykCpTIAAAAJ&hl=fr) provided the sample data and developed the visualization method implemented in this plugin\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-zplane-depth-colorizer\" 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[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/maihanhoang/napari-zplane-depth-colorizer/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":null,"download_url":null,"author":"Mai Hoang","author_email":"maihan.hoang1208@gmail.com","maintainer":null,"maintainer_email":null,"license":"Copyright (c) 2024, Mai Hoang\nAll rights reserved.\n\nRedistribution and use in source and binary forms, with or without\nmodification, are permitted provided that the following conditions are met:\n\n* Redistributions of source code must retain the above copyright notice, this\n list of conditions and the following disclaimer.\n\n* Redistributions in binary form must reproduce the above copyright notice,\n this list of conditions and the following disclaimer in the documentation\n and/or other materials provided with the distribution.\n\n* Neither the name of copyright holder nor the names of its\n contributors may be used to endorse or promote products derived from\n this software without specific prior written permission.\n\nTHIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS \"AS IS\"\nAND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE\nIMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE\nDISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE\nFOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL\nDAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR\nSERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER\nCAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,\nOR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE\nOF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.\n","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.9","Programming Language :: Python :: 3.10","Programming Language :: Python :: 3.11","Programming Language :: Python :: 3.12","Topic :: Scientific/Engineering :: Image Processing"],"requires_dist":["numpy","magicgui","qtpy","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.9","requires_external":null,"project_url":["Bug Tracker, https://github.com/maihanhoang/napari-zplane-depth-colorizer/issues","Documentation, https://github.com/maihanhoang/napari-zplane-depth-colorizer#README.md","Source Code, https://github.com/maihanhoang/napari-zplane-depth-colorizer","User Support, https://github.com/maihanhoang/napari-zplane-depth-colorizer/issues"],"provides_extra":["testing"],"provides_dist":null,"obsoletes_dist":null},"npe1_shim":false}
![](\"https://github.com/maihanhoang/napari-zplane-depth-colorizer/raw/main/assets/plugin_demo.gif\")
\n![](\"https://github.com/maihanhoang/napari-zplane-depth-colorizer/raw/main/assets/entire_stack_zproj.jpg\")
\n![](\"https://github.com/maihanhoang/napari-zplane-depth-colorizer/raw/main/assets/3_plane_stack.gif\")
\n![](\"https://github.com/maihanhoang/napari-zplane-depth-colorizer/raw/main/assets/img_gray.png\")
\n ![](\"https://github.com/maihanhoang/napari-zplane-depth-colorizer/raw/main/assets/img_color.png\")
\n![](\"https://github.com/maihanhoang/napari-zplane-depth-colorizer/raw/main/assets/entire_stack.gif\")
\n![](\"https://github.com/maihanhoang/napari-zplane-depth-colorizer/raw/main/assets/entire_stack_zproj.gif\")
\n![](\"https://github.com/maihanhoang/napari-zplane-depth-colorizer/raw/main/assets/img_color_zproj.png\")
\n