[](https://badge.fury.io/py/ncolor)
[](https://pepy.tech/project/ncolor)
[](badges/tests.svg)
[](badges/coverage.svg)
# ncolor <img src="https://github.com/kevinjohncutler/ncolor/blob/main/logo.png?raw=true" width="400" title="bacteria" alt="bacteria" align="right" vspace = "0">
Fast remapping of instance labels 1,2,3,...,M to a smaller set of repeating, disjoint labels, 1,2,...,N. The [four color theorem](https://en.wikipedia.org/wiki/Four_color_theorem) guarantees that at most four colors are required for any 2D segmentation/map, but the stochastic algorithms of `ncolor` will opt for 5 or 6 to give an acceptable result if it fails to find a 4-color mapping quickly. Also works for 3D labels (<8 colors typically required) and perhaps higher dimensions as well.
### Usage
If you have an integer array called `masks`, you may transform it into an N-color representation as follows:
```python
import ncolor
ncolor_masks = ncolor.label(masks)
```
If you need the number of unique labels returned:
```python
ncolor_masks, num_labels = ncolor.label(masks,return_n=True)
```
If you need to convert back to `0,...,N` object labels:
```python
labels = ncolor.format_labels(ncolor_masks,clean=True)
```
Note that `format_labels` with ```clean=True``` will also remove small labels (<9px) by default. This behavior can be changed with the `min_area` parameter.
The integer array `ncolor_masks` can be visualized using any color map you prefer. The example in this README uses the viridis colormap. See `example.ipynb` for more details.
Thanks to Ryan Peters ([@ryanirl](https://github.com/ryanirl)) for suggesting the `expand_labels` function. This is applied by default to 2D images (optionally for 3D images with `expand=True`, but this can give bad results since objects in 3D have a lot more wiggle room to make contact when expanded). This preprocessing step eliminates cases where close (but not touching) or dispersed objects previously received the same label. I dug a layer back to use `ndimage.distance_transform_edt` for a speed boost. If undesired for 2D images, use `expand=False`.
Raw data
{
"_id": null,
"home_page": "https://github.com/kevinjohncutler/ncolor",
"name": "ncolor",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": null,
"author": "Kevin Cutler",
"author_email": "kevinjohncutler@outlook.com",
"download_url": "https://files.pythonhosted.org/packages/be/bc/0485485b8f7146d6ebed5f29ac8c24012713a10284511247cf62dba2db37/ncolor-1.4.5.tar.gz",
"platform": null,
"description": "[](https://badge.fury.io/py/ncolor)\n[](https://pepy.tech/project/ncolor)\n[](badges/tests.svg)\n[](badges/coverage.svg)\n\n# ncolor <img src=\"https://github.com/kevinjohncutler/ncolor/blob/main/logo.png?raw=true\" width=\"400\" title=\"bacteria\" alt=\"bacteria\" align=\"right\" vspace = \"0\">\n\nFast remapping of instance labels 1,2,3,...,M to a smaller set of repeating, disjoint labels, 1,2,...,N. The [four color theorem](https://en.wikipedia.org/wiki/Four_color_theorem) guarantees that at most four colors are required for any 2D segmentation/map, but the stochastic algorithms of `ncolor` will opt for 5 or 6 to give an acceptable result if it fails to find a 4-color mapping quickly. Also works for 3D labels (<8 colors typically required) and perhaps higher dimensions as well.\n\n### Usage\nIf you have an integer array called `masks`, you may transform it into an N-color representation as follows:\n\n```python\nimport ncolor \nncolor_masks = ncolor.label(masks)\n```\n\nIf you need the number of unique labels returned:\n```python\nncolor_masks, num_labels = ncolor.label(masks,return_n=True)\n\n```\nIf you need to convert back to `0,...,N` object labels:\n```python\nlabels = ncolor.format_labels(ncolor_masks,clean=True)\n\n```\n\nNote that `format_labels` with ```clean=True``` will also remove small labels (<9px) by default. This behavior can be changed with the `min_area` parameter. \n\n \nThe integer array `ncolor_masks` can be visualized using any color map you prefer. The example in this README uses the viridis colormap. See `example.ipynb` for more details.\n\nThanks to Ryan Peters ([@ryanirl](https://github.com/ryanirl)) for suggesting the `expand_labels` function. This is applied by default to 2D images (optionally for 3D images with `expand=True`, but this can give bad results since objects in 3D have a lot more wiggle room to make contact when expanded). This preprocessing step eliminates cases where close (but not touching) or dispersed objects previously received the same label. I dug a layer back to use `ndimage.distance_transform_edt` for a speed boost. If undesired for 2D images, use `expand=False`. \n",
"bugtrack_url": null,
"license": "BSD",
"summary": "label matrix coloring algorithm",
"version": "1.4.5",
"project_urls": {
"Homepage": "https://github.com/kevinjohncutler/ncolor"
},
"split_keywords": [],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "1aec6a636d60862e44bef06e570215ee8361b34f30183b2ede888a23fb9720ab",
"md5": "6af35517c2e6857b37d76d0fbbabd9b8",
"sha256": "6f120531bf7bfc98e448085e8c67a40c8700d7e1a47849e5959a629af6b360a4"
},
"downloads": -1,
"filename": "ncolor-1.4.5-py3-none-any.whl",
"has_sig": false,
"md5_digest": "6af35517c2e6857b37d76d0fbbabd9b8",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 9965,
"upload_time": "2025-08-08T08:49:33",
"upload_time_iso_8601": "2025-08-08T08:49:33.905789Z",
"url": "https://files.pythonhosted.org/packages/1a/ec/6a636d60862e44bef06e570215ee8361b34f30183b2ede888a23fb9720ab/ncolor-1.4.5-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "bebc0485485b8f7146d6ebed5f29ac8c24012713a10284511247cf62dba2db37",
"md5": "ae2ead71b7633cf3927df376d53917b2",
"sha256": "3db439eca49cbf895bd4440527abe3eba4013442f2b75e3da96857e1fc8108a1"
},
"downloads": -1,
"filename": "ncolor-1.4.5.tar.gz",
"has_sig": false,
"md5_digest": "ae2ead71b7633cf3927df376d53917b2",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 50630,
"upload_time": "2025-08-08T08:49:35",
"upload_time_iso_8601": "2025-08-08T08:49:35.045448Z",
"url": "https://files.pythonhosted.org/packages/be/bc/0485485b8f7146d6ebed5f29ac8c24012713a10284511247cf62dba2db37/ncolor-1.4.5.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-08 08:49:35",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "kevinjohncutler",
"github_project": "ncolor",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"tox": true,
"lcname": "ncolor"
}
JSON
