# napari-czann-segment
[](https://github.com/sebi06/napari-czann-segment/raw/main/LICENSE)
[](https://pypi.org/project/napari-czann-segment)
[](https://python.org)
[](https://napari-hub.org/plugins/napari-czann-segment)
Semantic Segmentation of multidimensional images using Deep Learning ONNX models packaged as *.czann files.
----------------------------------
This [napari] plugin was generated with [Cookiecutter] using [@napari]'s [cookiecutter-napari-plugin] template.
## Installation
Before installing, please setup a conda environment. If you have never worked with conda environments, go through [this tutorial](https://biapol.github.io/blog/johannes_mueller/anaconda_getting_started/) first.
You can then install `napari-czann-segment` via [pip]:
pip install napari-czann-segment
## What does the plugin do
The plugin allows you to:
- Use a *.czann file containing the Deep Neural Network (ONNX) for semantic segmentation and metadata
- Segmentation will be applied per 2D plane for all dimensions
- Processing larger multidimensional images it uses the [cztile] package to chunk the individual 2d arrays using a specific overlap.
- multidimensional images will be processed plane-by-plane
## What does the plugin NOT do
**Before one can actually use a model it needs to be trained, which is NOT done by this plugin**.
There are two main ways hwo such a model can be created:
- Train the segmentation model fully automated on [APEER] and download the *.czann file
- Train your model in a Jupyter notebook etc. and package it using the [czmodel] python package as an *.czann
## Using this plugin
### Sample Data
A test image and a *.czann model file can be downloaded [here](https://github.com/sebi06/napari-czann-segment/tree/main/src/napari_czann_segment/_data).
- `PGC_20X.ome.tiff` --> use `PGC_20X_nucleus_detector.czann` to segment
In order to use this plugin the user has to do the following things:
- Open the image using "File - Open Files(s)" (requires [napari-aicsimageio] plugin).
- Click **napari-czann-segment: Segment with CZANN model** in the "Plugins" menu.
- **Select a czann file** to use the model for segmentation.
- metadata of the model will be shown (see example below)
| Parameter | Value | Explanation |
| :----------- | :------------------------------------------- | ------------------------------------------------------- |
| model_type | ModelType.SINGLE_CLASS_SEMANTIC_SEGMENTATION | see: [czmodel] for details |
| input_shape | [1024, 1024, 1] | tile dimensions of model input |
| output_shape | [1024, 1024, 3] | tile dimensions of model output |
| model_id | ba32bc6d-6bc9-4774-8b47-20646c7cb838 | unique GUID for that model |
| min_overlap | [128, 128] | tile overlap used during training (for this model) |
| classes | ['background', 'grains', 'inclusions'] | available classes |
| model_name | APEER-trained model | name of the model |
- Adjust the **minimum overlap** for the tiling (optional, see [cztile] for details).
- Select the **layer** to be segmented.
- Toggle **Use GPU for inference** checkbox to enable / disable using a GPU (Nvidia) for the segmentation (experimental feature).
- Press **Segment Selected Image Layer** to run the segmentation.
A successful is obviously only the starting point for further image analysis steps to extract the desired numbers from the segmented image.
Another example is shown below demonstrating a simple "Grain Size Analysis" using a deep-learning model trained on [APEER] used in [napari]
### Remarks
> **IMPORTANT**: Currently the plugin only supports using models trained on a **single channel** image. Therefore, make sure that during the training on [APEER] or somewhere else the correct inputs images are used.
> It is quite simple to train a single RGB image, which actually has three channels, load this image in [napari] and notice only then that the model will not work, because the image will 3 channels inside [napari].
- Only the CPU will be used for the inference using the ONNX runtime for the [ONNX-CPU] runtime
- GPUs are supported but require the [ONNX-GPU] runtime and the respective CUDA libraries.
- Please check the [YAML](env_napari_czann_segment.yml) for an example environment with GPU support.
- See also [pytorch] for instruction on how to install pytorch
## For developers
- **Please clone this repository first using your favorite tool.**
- **Ideally one creates a new [conda] environment or use an existing environment that already contains [Napari].**
Feel free to create a new environment using the [YAML](env_napari_czann_segment.yml) file at your own risk:
cd the-github-repo-with-YAML-file
conda env create --file conda_env_napari_czann_segment.yml
conda activate napari_czmodel
- **Install the plugin locally**
Please run the following command:
pip install -e .
To install latest development version:
pip install git+https://github.com/sebi06/napari_czann_segment.git
## Contributing
Contributions and Feedback are very welcome.
## License
Distributed under the terms of the [BSD-3] license,
"napari-czann-segment" is free and open source software
## Issues
If you encounter any problems, please [file an issue] along with a detailed description.
[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/sebi06/napari-czann-segment/issues
[tox]: https://tox.readthedocs.io/en/latest/
[pip]: https://pypi.org/project/pip/
[PyPI]: https://pypi.org/
[czmodel]: https://pypi.org/project/czmodel/
[cztile]: https://pypi.org/project/cztile/
[APEER]: https://www.apeer.com
[napari-aicsimageio]: https://github.com/AllenCellModeling/napari-aicsimageio
[ONNX-GPU]: https://pypi.org/project/onnxruntime-gpu/
[ONNX-CPU]: https://pypi.org/project/onnxruntime/
[conda]: https://docs.conda.io/projects/conda/en/latest/user-guide/getting-started.html
[pytorch]: https://pytorch.org/get-started/locally
Raw data
{
"_id": null,
"home_page": "https://github.com/sebi06/napari-czann-segment",
"name": "napari-czann-segment",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": "",
"keywords": "",
"author": "Sebastian Rhode",
"author_email": "sebrhode@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/b8/e2/1636415889b43d18e7e172f9088344b6ad5b146394ec8fd349ee7da54aad/napari-czann-segment-0.0.18.tar.gz",
"platform": null,
"description": "# napari-czann-segment\n\n[](https://github.com/sebi06/napari-czann-segment/raw/main/LICENSE)\n[](https://pypi.org/project/napari-czann-segment)\n[](https://python.org)\n[](https://napari-hub.org/plugins/napari-czann-segment)\n\nSemantic Segmentation of multidimensional images using Deep Learning ONNX models packaged as *.czann files.\n\n----------------------------------\n\nThis [napari] plugin was generated with [Cookiecutter] using [@napari]'s [cookiecutter-napari-plugin] template.\n\n\n\n## Installation\n\nBefore installing, please setup a conda environment. If you have never worked with conda environments, go through [this tutorial](https://biapol.github.io/blog/johannes_mueller/anaconda_getting_started/) first.\n\nYou can then install `napari-czann-segment` via [pip]:\n\n pip install napari-czann-segment\n\n## What does the plugin do\n\nThe plugin allows you to:\n\n- Use a *.czann file containing the Deep Neural Network (ONNX) for semantic segmentation and metadata\n- Segmentation will be applied per 2D plane for all dimensions\n- Processing larger multidimensional images it uses the [cztile] package to chunk the individual 2d arrays using a specific overlap.\n- multidimensional images will be processed plane-by-plane\n\n## What does the plugin NOT do\n\n**Before one can actually use a model it needs to be trained, which is NOT done by this plugin**.\n\nThere are two main ways hwo such a model can be created:\n\n- Train the segmentation model fully automated on [APEER] and download the *.czann file\n- Train your model in a Jupyter notebook etc. and package it using the [czmodel] python package as an *.czann\n\n## Using this plugin\n\n### Sample Data\n\nA test image and a *.czann model file can be downloaded [here](https://github.com/sebi06/napari-czann-segment/tree/main/src/napari_czann_segment/_data).\n\n- `PGC_20X.ome.tiff` --> use `PGC_20X_nucleus_detector.czann` to segment\n\nIn order to use this plugin the user has to do the following things:\n\n- Open the image using \"File - Open Files(s)\" (requires [napari-aicsimageio] plugin).\n- Click **napari-czann-segment: Segment with CZANN model** in the \"Plugins\" menu.\n- **Select a czann file** to use the model for segmentation.\n- metadata of the model will be shown (see example below)\n\n| Parameter | Value | Explanation |\n| :----------- | :------------------------------------------- | ------------------------------------------------------- |\n| model_type | ModelType.SINGLE_CLASS_SEMANTIC_SEGMENTATION | see: [czmodel] for details |\n| input_shape | [1024, 1024, 1] | tile dimensions of model input |\n| output_shape | [1024, 1024, 3] | tile dimensions of model output |\n| model_id | ba32bc6d-6bc9-4774-8b47-20646c7cb838 | unique GUID for that model |\n| min_overlap | [128, 128] | tile overlap used during training (for this model) |\n| classes | ['background', 'grains', 'inclusions'] | available classes |\n| model_name | APEER-trained model | name of the model |\n\n\n\n- Adjust the **minimum overlap** for the tiling (optional, see [cztile] for details).\n- Select the **layer** to be segmented.\n- Toggle **Use GPU for inference** checkbox to enable / disable using a GPU (Nvidia) for the segmentation (experimental feature).\n- Press **Segment Selected Image Layer** to run the segmentation.\n\n\n\nA successful is obviously only the starting point for further image analysis steps to extract the desired numbers from the segmented image.\nAnother example is shown below demonstrating a simple \"Grain Size Analysis\" using a deep-learning model trained on [APEER] used in [napari]\n\n\n\n### Remarks\n\n> **IMPORTANT**: Currently the plugin only supports using models trained on a **single channel** image. Therefore, make sure that during the training on [APEER] or somewhere else the correct inputs images are used.\n> It is quite simple to train a single RGB image, which actually has three channels, load this image in [napari] and notice only then that the model will not work, because the image will 3 channels inside [napari].\n\n- Only the CPU will be used for the inference using the ONNX runtime for the [ONNX-CPU] runtime\n- GPUs are supported but require the [ONNX-GPU] runtime and the respective CUDA libraries.\n- Please check the [YAML](env_napari_czann_segment.yml) for an example environment with GPU support.\n- See also [pytorch] for instruction on how to install pytorch\n\n## For developers\n\n- **Please clone this repository first using your favorite tool.**\n\n- **Ideally one creates a new [conda] environment or use an existing environment that already contains [Napari].**\n\nFeel free to create a new environment using the [YAML](env_napari_czann_segment.yml) file at your own risk:\n\n cd the-github-repo-with-YAML-file\n conda env create --file conda_env_napari_czann_segment.yml\n conda activate napari_czmodel\n\n- **Install the plugin locally**\n\nPlease run the following command:\n\n pip install -e .\n\nTo install latest development version:\n\n pip install git+https://github.com/sebi06/napari_czann_segment.git\n\n## Contributing\n\nContributions and Feedback are very welcome.\n\n## License\n\nDistributed under the terms of the [BSD-3] license,\n\"napari-czann-segment\" 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[file an issue]: https://github.com/sebi06/napari-czann-segment/issues\n[tox]: https://tox.readthedocs.io/en/latest/\n[pip]: https://pypi.org/project/pip/\n[PyPI]: https://pypi.org/\n[czmodel]: https://pypi.org/project/czmodel/\n[cztile]: https://pypi.org/project/cztile/\n[APEER]: https://www.apeer.com\n[napari-aicsimageio]: https://github.com/AllenCellModeling/napari-aicsimageio\n[ONNX-GPU]: https://pypi.org/project/onnxruntime-gpu/\n[ONNX-CPU]: https://pypi.org/project/onnxruntime/\n[conda]: https://docs.conda.io/projects/conda/en/latest/user-guide/getting-started.html\n[pytorch]: https://pytorch.org/get-started/locally\n",
"bugtrack_url": null,
"license": "BSD-3-Clause",
"summary": "Semantic Segmentation using Deep Learning ONNX models packaged as *.czann files",
"version": "0.0.18",
"project_urls": {
"Bug Tracker": "https://github.com/sebi06/napari-czann-segment/issues",
"Documentation": "https://github.com/sebi06/napari-czann-segment#README.md",
"Homepage": "https://github.com/sebi06/napari-czann-segment",
"Source Code": "https://github.com/sebi06/napari-czann-segment",
"User Support": "https://github.com/sebi06/napari-czann-segment/issues"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "14942c341d37b354c6132be10d5d5189d538055438d8d10afc8c03c8d56454a3",
"md5": "f069bb2188bd95a788654243de1cedf4",
"sha256": "ac98eba002be4fba4a85ae60e222dd7d86090ac3720ffd4a1e883644ef2afd3e"
},
"downloads": -1,
"filename": "napari_czann_segment-0.0.18-py3-none-any.whl",
"has_sig": false,
"md5_digest": "f069bb2188bd95a788654243de1cedf4",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 28091,
"upload_time": "2023-09-22T13:05:31",
"upload_time_iso_8601": "2023-09-22T13:05:31.368977Z",
"url": "https://files.pythonhosted.org/packages/14/94/2c341d37b354c6132be10d5d5189d538055438d8d10afc8c03c8d56454a3/napari_czann_segment-0.0.18-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "b8e21636415889b43d18e7e172f9088344b6ad5b146394ec8fd349ee7da54aad",
"md5": "b9a6564392028015256129f318a86b36",
"sha256": "aa8bf22f02c914dfbf43fa59785e8fdb77cb55d9a18639ef13b3275ab1e628da"
},
"downloads": -1,
"filename": "napari-czann-segment-0.0.18.tar.gz",
"has_sig": false,
"md5_digest": "b9a6564392028015256129f318a86b36",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 11797153,
"upload_time": "2023-09-22T13:05:33",
"upload_time_iso_8601": "2023-09-22T13:05:33.119950Z",
"url": "https://files.pythonhosted.org/packages/b8/e2/1636415889b43d18e7e172f9088344b6ad5b146394ec8fd349ee7da54aad/napari-czann-segment-0.0.18.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-09-22 13:05:33",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "sebi06",
"github_project": "napari-czann-segment",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"tox": true,
"lcname": "napari-czann-segment"
}
JSON
