ncolor


Namencolor JSON
Version 1.4.4 PyPI version JSON
download
home_pagehttps://github.com/kevinjohncutler/ncolor
Summarylabel matrix coloring algorithm
upload_time2025-07-12 21:20:54
maintainerNone
docs_urlNone
authorKevin Cutler
requires_pythonNone
licenseBSD
keywords
VCS
bugtrack_url
requirements No requirements were recorded.
Travis-CI No Travis.
coveralls test coverage No coveralls.
            [![PyPI version](https://badge.fury.io/py/ncolor.svg)](https://badge.fury.io/py/ncolor)
[![Downloads](https://static.pepy.tech/personalized-badge/ncolor?period=total&units=international_system&left_color=grey&right_color=green&left_text=Downloads)](https://pepy.tech/project/ncolor)

# 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 guarantees that at most four colors are required for any 2D segmentation/map, but this algorithm 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 (&lt;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/6a/48/46dc5c301339cbc84c6a3a28fcdfe10e069afffd13fab14673830fbb0705/ncolor-1.4.4.tar.gz",
    "platform": null,
    "description": "[![PyPI version](https://badge.fury.io/py/ncolor.svg)](https://badge.fury.io/py/ncolor)\n[![Downloads](https://static.pepy.tech/personalized-badge/ncolor?period=total&units=international_system&left_color=grey&right_color=green&left_text=Downloads)](https://pepy.tech/project/ncolor)\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 guarantees that at most four colors are required for any 2D segmentation/map, but this algorithm 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 (&lt;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.4",
    "project_urls": {
        "Homepage": "https://github.com/kevinjohncutler/ncolor"
    },
    "split_keywords": [],
    "urls": [
        {
            "comment_text": null,
            "digests": {
                "blake2b_256": "26b4ac5214dbaeab7d4a37c39c998edfd430502067f96b9053f0a5b51475a485",
                "md5": "db5aa2f584c70ac5f0fbf54a4ab45da2",
                "sha256": "0932bb92922465308ee7b0114021059c72cac3d3dd8dd475768d4a416ba5448e"
            },
            "downloads": -1,
            "filename": "ncolor-1.4.4-py3-none-any.whl",
            "has_sig": false,
            "md5_digest": "db5aa2f584c70ac5f0fbf54a4ab45da2",
            "packagetype": "bdist_wheel",
            "python_version": "py3",
            "requires_python": null,
            "size": 9898,
            "upload_time": "2025-07-12T21:20:53",
            "upload_time_iso_8601": "2025-07-12T21:20:53.360397Z",
            "url": "https://files.pythonhosted.org/packages/26/b4/ac5214dbaeab7d4a37c39c998edfd430502067f96b9053f0a5b51475a485/ncolor-1.4.4-py3-none-any.whl",
            "yanked": false,
            "yanked_reason": null
        },
        {
            "comment_text": null,
            "digests": {
                "blake2b_256": "6a4846dc5c301339cbc84c6a3a28fcdfe10e069afffd13fab14673830fbb0705",
                "md5": "dd370a8cdc3ec8780dd27e1df4ecb412",
                "sha256": "2c5fff43e701ebf357b7929b88c661d4bc08f8acb590f4b7ae9b7aeec7fb1284"
            },
            "downloads": -1,
            "filename": "ncolor-1.4.4.tar.gz",
            "has_sig": false,
            "md5_digest": "dd370a8cdc3ec8780dd27e1df4ecb412",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": null,
            "size": 47571,
            "upload_time": "2025-07-12T21:20:54",
            "upload_time_iso_8601": "2025-07-12T21:20:54.572073Z",
            "url": "https://files.pythonhosted.org/packages/6a/48/46dc5c301339cbc84c6a3a28fcdfe10e069afffd13fab14673830fbb0705/ncolor-1.4.4.tar.gz",
            "yanked": false,
            "yanked_reason": null
        }
    ],
    "upload_time": "2025-07-12 21:20:54",
    "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"
}
        
Elapsed time: 1.10796s