# panoptica
[](https://pypi.org/project/panoptica/)
[](https://pypi.python.org/pypi/panoptica/)
[](http://panoptica.readthedocs.io/?badge=latest)
[](https://github.com/BrainLesion/panoptica/actions/workflows/tests.yml)
[](https://codecov.io/gh/BrainLesion/panoptica)
[](https://opensource.org/licenses/Apache-2.0)
Computing instance-wise segmentation quality metrics for 2D and 3D semantic- and instance segmentation maps.
[Use Cases & Tutorials](#use-cases--tutorials) | [Documentation](#documentation)
## Features
The package provides three core modules:
1. Instance Approximator: instance approximation algorithms to extract instances from semantic segmentation maps/model outputs.
2. Instance Matcher: matches predicted instances with reference instances.
3. Instance Evaluator: computes segmentation and detection quality metrics for pairs of predicted - and reference segmentation maps.
## Installation
With a Python 3.10+ environment, you can install panoptica from [pypi.org](https://pypi.org/project/panoptica/)
```sh
pip install panoptica
```
## Available Metrics
> [!NOTE]
> Panoptica supports a large range of metrics. <br>
> An overview of the supported metrics and their formulas can be found here: [panoptica/metrics.md](https://github.com/BrainLesion/panoptica/tree/main/metrics.md)
## Use Cases & Tutorials
### Minimal example
A minimal example of using panoptica could look e.g. like this (here with Matched Instances as Input):
```python
from panoptica import InputType, Panoptica_Evaluator
from panoptica.metrics import Metric
from auxiliary.nifti.io import read_nifti # feel free to use any other way to read nifti files
ref_masks = read_nifti("reference.nii.gz")
pred_masks = read_nifti("prediction.nii.gz")
evaluator = Panoptica_Evaluator(
expected_input=InputType.MATCHED_INSTANCE,
decision_metric=Metric.IOU,
decision_threshold=0.5,
)
result, intermediate_steps_data = evaluator.evaluate(pred_masks, ref_masks)["ungrouped"]
```
> [!TIP]
> We provide Jupyter Notebook tutorials showcasing various use cases. <br>
> You can explore them here: [BrainLesion/tutorials/panoptica](https://github.com/BrainLesion/tutorials/tree/main/panoptica) <br>
### Semantic Segmentation Input
<img src="https://github.com/BrainLesion/panoptica/blob/main/examples/figures/semantic.png?raw=true" alt="semantic_figure" height="300"/>
Although an instance-wise evaluation is highly relevant and desirable for many biomedical segmentation problems, they are still addressed as semantic segmentation problems due to the lack of appropriate instance labels.
This tutorial leverages all three modules of panoptica: instance approximation, -matching and -evaluation.
[](https://nbviewer.jupyter.org/github/BrainLesion/tutorials/blob/main/panoptica/example_spine_semantic.ipynb)
<a target="_blank" href="https://colab.research.google.com/github/BrainLesion/tutorials/blob/main/panoptica/example_spine_semantic.ipynb">
<img src="https://colab.research.google.com/assets/colab-badge.svg" alt="Open In Colab"/>
</a>
### Unmatched Instances Input
<img src="https://github.com/BrainLesion/panoptica/blob/main/examples/figures/unmatched_instance.png?raw=true" alt="unmatched_instance_figure" height="300"/>
It is a common issue that instance segmentation outputs feature good outlines but mismatched instance labels.
For this case, the matcher module can be utilized to match instances and the evaluator to report metrics.
[](https://nbviewer.jupyter.org/github/BrainLesion/tutorials/blob/main/panoptica/example_spine_unmatched_instance.ipynb)
<a target="_blank" href="https://colab.research.google.com/github/BrainLesion/tutorials/blob/main/panoptica/example_spine_unmatched_instance.ipynb">
<img src="https://colab.research.google.com/assets/colab-badge.svg" alt="Open In Colab"/>
</a>
### Matched Instances Input
<img src="https://github.com/BrainLesion/panoptica/blob/main/examples/figures/matched_instance.png?raw=true" alt="matched_instance_figure" height="300"/>
[](https://nbviewer.jupyter.org/github/BrainLesion/tutorials/blob/main/panoptica/example_spine_matched_instance.ipynb)
<a target="_blank" href="https://colab.research.google.com/github/BrainLesion/tutorials/blob/main/panoptica/example_spine_matched_instance.ipynb">
<img src="https://colab.research.google.com/assets/colab-badge.svg" alt="Open In Colab"/>
</a>
If your predicted instances already match the reference instances, you can directly compute metrics using the evaluator module.
### Matching Algorithm Example
[](https://nbviewer.jupyter.org/github/BrainLesion/tutorials/blob/main/panoptica/example_spine_matching_algorithm.ipynb)
<a target="_blank" href="https://colab.research.google.com/github/BrainLesion/tutorials/blob/main/panoptica/example_spine_matching_algorithm.ipynb">
<img src="https://colab.research.google.com/assets/colab-badge.svg" alt="Open In Colab"/>
</a>
### Using Configs (saving and loading)
You can construct Panoptica_Evaluator (among many others) objects and save their arguments, so you can save project-specific configurations and use them later.
It uses ruamel.yaml in a readable way.
[](https://nbviewer.jupyter.org/github/BrainLesion/tutorials/blob/main/panoptica/example_config.ipynb)
<a target="_blank" href="https://colab.research.google.com/github/BrainLesion/tutorials/blob/main/panoptica/example_config.ipynb">
<img src="https://colab.research.google.com/assets/colab-badge.svg" alt="Open In Colab"/>
</a>
## Documentation
We provide a readthedocs documentation of our codebase [here](https://panoptica.readthedocs.io/en/latest/?badge=latest)
## Citation
> [!IMPORTANT]
> If you use panoptica in your research, please cite it to support the development!
Kofler, F., Möller, H., Buchner, J. A., de la Rosa, E., Ezhov, I., Rosier, M., Mekki, I., Shit, S., Negwer, M., Al-Maskari, R., Ertürk, A., Vinayahalingam, S., Isensee, F., Pati, S., Rueckert, D., Kirschke, J. S., Ehrlich, S. K., Reinke, A., Menze, B., Wiestler, B., & Piraud, M. (2023). *Panoptica -- instance-wise evaluation of 3D semantic and instance segmentation maps.* [arXiv preprint arXiv:2312.02608](https://arxiv.org/abs/2312.02608).
```
@misc{kofler2023panoptica,
title={Panoptica -- instance-wise evaluation of 3D semantic and instance segmentation maps},
author={Florian Kofler and Hendrik Möller and Josef A. Buchner and Ezequiel de la Rosa and Ivan Ezhov and Marcel Rosier and Isra Mekki and Suprosanna Shit and Moritz Negwer and Rami Al-Maskari and Ali Ertürk and Shankeeth Vinayahalingam and Fabian Isensee and Sarthak Pati and Daniel Rueckert and Jan S. Kirschke and Stefan K. Ehrlich and Annika Reinke and Bjoern Menze and Benedikt Wiestler and Marie Piraud},
year={2023},
eprint={2312.02608},
archivePrefix={arXiv},
primaryClass={cs.CV}
}
```
## Contributing
We welcome all kinds of contributions from the community!
### Reporting Bugs, Feature Requests and Questions
Please open a new issue [here](https://github.com/BrainLesion/panoptica/issues).
Raw data
{
"_id": null,
"home_page": "https://github.com/BrainLesion/panoptica",
"name": "panoptica",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0,>=3.10",
"maintainer_email": null,
"keywords": null,
"author": "Florian Kofler",
"author_email": "florian.kofler@tum.de",
"download_url": null,
"platform": null,
"description": "\n\n# panoptica\n\n[](https://pypi.org/project/panoptica/)\n[](https://pypi.python.org/pypi/panoptica/)\n[](http://panoptica.readthedocs.io/?badge=latest)\n[](https://github.com/BrainLesion/panoptica/actions/workflows/tests.yml)\n[](https://codecov.io/gh/BrainLesion/panoptica)\n[](https://opensource.org/licenses/Apache-2.0)\n\nComputing instance-wise segmentation quality metrics for 2D and 3D semantic- and instance segmentation maps.\n\n \n[Use Cases & Tutorials](#use-cases--tutorials) | [Documentation](#documentation)\n\n## Features\n\nThe package provides three core modules:\n\n1. Instance Approximator: instance approximation algorithms to extract instances from semantic segmentation maps/model outputs.\n2. Instance Matcher: matches predicted instances with reference instances.\n3. Instance Evaluator: computes segmentation and detection quality metrics for pairs of predicted - and reference segmentation maps.\n\n\n\n## Installation\n\nWith a Python 3.10+ environment, you can install panoptica from [pypi.org](https://pypi.org/project/panoptica/)\n\n```sh\npip install panoptica\n```\n\n## Available Metrics\n\n> [!NOTE]\n> Panoptica supports a large range of metrics. <br>\n> An overview of the supported metrics and their formulas can be found here: [panoptica/metrics.md](https://github.com/BrainLesion/panoptica/tree/main/metrics.md)\n\n## Use Cases & Tutorials\n\n\n### Minimal example\n\nA minimal example of using panoptica could look e.g. like this (here with Matched Instances as Input):\n```python\nfrom panoptica import InputType, Panoptica_Evaluator\nfrom panoptica.metrics import Metric\n\nfrom auxiliary.nifti.io import read_nifti # feel free to use any other way to read nifti files\n\nref_masks = read_nifti(\"reference.nii.gz\")\npred_masks = read_nifti(\"prediction.nii.gz\")\n\nevaluator = Panoptica_Evaluator(\n expected_input=InputType.MATCHED_INSTANCE,\n decision_metric=Metric.IOU,\n decision_threshold=0.5,\n)\n\nresult, intermediate_steps_data = evaluator.evaluate(pred_masks, ref_masks)[\"ungrouped\"]\n```\n\n\n> [!TIP]\n> We provide Jupyter Notebook tutorials showcasing various use cases. <br>\n> You can explore them here: [BrainLesion/tutorials/panoptica](https://github.com/BrainLesion/tutorials/tree/main/panoptica) <br>\n\n### Semantic Segmentation Input\n\n<img src=\"https://github.com/BrainLesion/panoptica/blob/main/examples/figures/semantic.png?raw=true\" alt=\"semantic_figure\" height=\"300\"/>\n\nAlthough an instance-wise evaluation is highly relevant and desirable for many biomedical segmentation problems, they are still addressed as semantic segmentation problems due to the lack of appropriate instance labels.\n\nThis tutorial leverages all three modules of panoptica: instance approximation, -matching and -evaluation.\n\n[](https://nbviewer.jupyter.org/github/BrainLesion/tutorials/blob/main/panoptica/example_spine_semantic.ipynb)\n<a target=\"_blank\" href=\"https://colab.research.google.com/github/BrainLesion/tutorials/blob/main/panoptica/example_spine_semantic.ipynb\">\n <img src=\"https://colab.research.google.com/assets/colab-badge.svg\" alt=\"Open In Colab\"/>\n</a>\n\n\n### Unmatched Instances Input\n\n<img src=\"https://github.com/BrainLesion/panoptica/blob/main/examples/figures/unmatched_instance.png?raw=true\" alt=\"unmatched_instance_figure\" height=\"300\"/>\n\nIt is a common issue that instance segmentation outputs feature good outlines but mismatched instance labels.\nFor this case, the matcher module can be utilized to match instances and the evaluator to report metrics.\n\n[](https://nbviewer.jupyter.org/github/BrainLesion/tutorials/blob/main/panoptica/example_spine_unmatched_instance.ipynb)\n<a target=\"_blank\" href=\"https://colab.research.google.com/github/BrainLesion/tutorials/blob/main/panoptica/example_spine_unmatched_instance.ipynb\">\n <img src=\"https://colab.research.google.com/assets/colab-badge.svg\" alt=\"Open In Colab\"/>\n</a>\n\n\n\n### Matched Instances Input\n\n<img src=\"https://github.com/BrainLesion/panoptica/blob/main/examples/figures/matched_instance.png?raw=true\" alt=\"matched_instance_figure\" height=\"300\"/>\n\n[](https://nbviewer.jupyter.org/github/BrainLesion/tutorials/blob/main/panoptica/example_spine_matched_instance.ipynb)\n<a target=\"_blank\" href=\"https://colab.research.google.com/github/BrainLesion/tutorials/blob/main/panoptica/example_spine_matched_instance.ipynb\">\n <img src=\"https://colab.research.google.com/assets/colab-badge.svg\" alt=\"Open In Colab\"/>\n</a>\n\nIf your predicted instances already match the reference instances, you can directly compute metrics using the evaluator module.\n\n### Matching Algorithm Example\n[](https://nbviewer.jupyter.org/github/BrainLesion/tutorials/blob/main/panoptica/example_spine_matching_algorithm.ipynb)\n<a target=\"_blank\" href=\"https://colab.research.google.com/github/BrainLesion/tutorials/blob/main/panoptica/example_spine_matching_algorithm.ipynb\">\n <img src=\"https://colab.research.google.com/assets/colab-badge.svg\" alt=\"Open In Colab\"/>\n</a>\n\n\n### Using Configs (saving and loading)\n\nYou can construct Panoptica_Evaluator (among many others) objects and save their arguments, so you can save project-specific configurations and use them later.\nIt uses ruamel.yaml in a readable way.\n\n[](https://nbviewer.jupyter.org/github/BrainLesion/tutorials/blob/main/panoptica/example_config.ipynb)\n<a target=\"_blank\" href=\"https://colab.research.google.com/github/BrainLesion/tutorials/blob/main/panoptica/example_config.ipynb\">\n <img src=\"https://colab.research.google.com/assets/colab-badge.svg\" alt=\"Open In Colab\"/>\n</a>\n\n## Documentation\n\nWe provide a readthedocs documentation of our codebase [here](https://panoptica.readthedocs.io/en/latest/?badge=latest)\n\n## Citation\n\n> [!IMPORTANT]\n> If you use panoptica in your research, please cite it to support the development!\n\nKofler, F., M\u00f6ller, H., Buchner, J. A., de la Rosa, E., Ezhov, I., Rosier, M., Mekki, I., Shit, S., Negwer, M., Al-Maskari, R., Ert\u00fcrk, A., Vinayahalingam, S., Isensee, F., Pati, S., Rueckert, D., Kirschke, J. S., Ehrlich, S. K., Reinke, A., Menze, B., Wiestler, B., & Piraud, M. (2023). *Panoptica -- instance-wise evaluation of 3D semantic and instance segmentation maps.* [arXiv preprint arXiv:2312.02608](https://arxiv.org/abs/2312.02608).\n\n```\n@misc{kofler2023panoptica,\n title={Panoptica -- instance-wise evaluation of 3D semantic and instance segmentation maps}, \n author={Florian Kofler and Hendrik M\u00f6ller and Josef A. Buchner and Ezequiel de la Rosa and Ivan Ezhov and Marcel Rosier and Isra Mekki and Suprosanna Shit and Moritz Negwer and Rami Al-Maskari and Ali Ert\u00fcrk and Shankeeth Vinayahalingam and Fabian Isensee and Sarthak Pati and Daniel Rueckert and Jan S. Kirschke and Stefan K. Ehrlich and Annika Reinke and Bjoern Menze and Benedikt Wiestler and Marie Piraud},\n year={2023},\n eprint={2312.02608},\n archivePrefix={arXiv},\n primaryClass={cs.CV}\n}\n```\n\n## Contributing\n\nWe welcome all kinds of contributions from the community!\n\n### Reporting Bugs, Feature Requests and Questions\n\nPlease open a new issue [here](https://github.com/BrainLesion/panoptica/issues).\n",
"bugtrack_url": null,
"license": null,
"summary": "Panoptic Quality (PQ) computation for binary masks.",
"version": "1.1.8",
"project_urls": {
"Documentation": "https://panoptica.readthedocs.io/",
"Homepage": "https://github.com/BrainLesion/panoptica",
"Repository": "https://github.com/BrainLesion/panoptica"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "534dfef1e153845dd2d51d03a010cb47b6addb44e98b141c1113796865a2b88a",
"md5": "bbf81afb0b702ca73bb2f8f58384aff0",
"sha256": "8e4488fbe1a74d2fff2ee3fed90fd77827fe669d96514bd39eedb658fc3a7fb3"
},
"downloads": -1,
"filename": "panoptica-1.1.8-py3-none-any.whl",
"has_sig": false,
"md5_digest": "bbf81afb0b702ca73bb2f8f58384aff0",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.10",
"size": 64639,
"upload_time": "2024-11-25T12:37:03",
"upload_time_iso_8601": "2024-11-25T12:37:03.855171Z",
"url": "https://files.pythonhosted.org/packages/53/4d/fef1e153845dd2d51d03a010cb47b6addb44e98b141c1113796865a2b88a/panoptica-1.1.8-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-11-25 12:37:03",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "BrainLesion",
"github_project": "panoptica",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "panoptica"
}
JSON
