alan-turing-institute / distinctipy Goto Github PK

A lightweight package for generating visually distinct colours.

Home Page: https://distinctipy.readthedocs.io/en/latest/

License: MIT License

Python 100.00%

python colour color-palette matplotlib hut23

distinctipy's Introduction

distinctipy is a lightweight python package providing functions to generate colours that are visually distinct from one another.

Commonly available qualitative colormaps provided by the likes of matplotlib generally have no more than 20 colours, but for some applications it is useful to have many more colours that are clearly different from one another. distinctipy can generate lists of colours of any length, with each new colour added to the list being as visually distinct from the pre-existing colours in the list as possible.

Installation

distinctipy is designed for Python 3 and can be installed with pip by running:

python -m pip install distinctipy

Alternatively clone the repo and install it locally:

git clone https://github.com/alan-turing-institute/distinctipy.git
cd distinctipy
python -m pip install .

Optional Dependencies

Starting in version 1.2.1 distinctipy no longer bundles matplotlib, pandas or dev dependencies in the default installation. If you wish to view colours (e.g. with distinctipy.color_swatch) or examples you will need matplotlib and pandas installed. To do this, either install distinctipy with the optional flag:

python -m pip install distinctipy[extras]

⚠️ Warning ⚠️ Previous versions of distinctipy (before 1.3) used [optional] instead of [extras].

Or install them separately:

python -m pip install matplotlib pandas

For developers, to install the stack needed to run tests, generate docs etc. use:

python -m pip install distinctipy[extras,tests,docs]

Usage and Examples

distinctipy can:

Generate N visually distinct colours: distinctipy.get_colors(N)
Generate colours that are distinct from an existing list of colours: distinctipy.get_colors(N, existing_colors)
Generate pastel colours: distinctipy.get_colors(N, pastel_factor=0.7)
Select black or white as the best font colour for any background colour: distinctipy.get_text_color(background_color)
Convert lists of colours into matplotlib colormaps: distinctipy.get_colormap(colors)
Invert colours: distinctipy.invert_colors(colors)
Nicely display generated colours: distinctipy.color_swatch(colors)
Compare distinctipy colours to other common colormaps: examples.compare_clusters() and examples.compare_colors()
Simulate how colours look for someone with colourblindness: colorblind.simulate_colors(colors, colorblind_type='Deuteranomaly')
Attempt to generate colours as distinct as possible for someone with colourblindness distinctipy.get_colors(N, existing_colors, colorblind_type="Deuteranomaly")

For example, to create and then display N = 36 visually distinct colours:

import distinctipy

# number of colours to generate
N = 36

# generate N visually distinct colours
colors = distinctipy.get_colors(N)

# display the colours
distinctipy.color_swatch(colors)

More detailed usage and example output can be found in the notebook examples.ipynb and examples gallery.

References

distinctipy was heavily influenced and inspired by several web sources and stack overflow answers. In particular:

Random generation of distinct colours: Andrew Dewes on GitHub
Colour distance metric: Thiadmer Riemersma at CompuPhase
Best text colour for background: Mark Ransom on Stack Overflow
Colourblindness Filters: Matthew Wickline and the Human-Computer Interaction Resource Network (web archive)

Citing distinctipy

If you would like to cite distinctipy, please refer to the upload of the package on Zenodo: https://doi.org/10.5281/zenodo.3985191

distinctipy's People

Contributors

Stargazers

Watchers

Forkers

mxochicale passion4energy erotemic techthiyanes marioernestovaldes erol444 liuluo1979 jolonb kianmeng eddiethedean iq-scm coderesting abubelinha

distinctipy's Issues

color_swatch() font size problems with less than 9 colors

Hi. Great and very useful package!

I am testing black/white text thresholds by using color_swatch(), but for some reason it gets nuts when using less than 9 colors.
In those cases, font sizes become huge and they don't fit inside colored boxes.

	import distinctipy, matplotlib.pyplot as plt
	colors = distinctipy.get_colors(8) # with less than 9 colors, color_swatch will use huge font sizes
	thresholds = [0.4,0.6]
	fig, axes = plt.subplots(len(thresholds), 1, figsize=(6, 6))
	for i,t in enumerate(thresholds):
		print(colors,"\n",textcolors)
		distinctipy.color_swatch(colors, show_text=True, ax=axes[i], title="text_threshold={}".format(t), text_threshold=t)
	plt.show()

That code is for 8 colors.
I am using:

python v. 3.8.7
matplotlib v. 3.6.3
distinctipy v. 1.2.3

This is my output for 2, 3, 8 and 9 colors:

2 colors:

3 colors:

8 colors:

9 colors:

Is there any way I can choose the font size to be used?
Thanks
@abubelinha

Add algorithm description to docs

Use W3C guidelines for text colour choice

See updated comment in https://stackoverflow.com/a/3943023 (first equation is what's used in distinctipy)

Python 3.7 is broken in 1.3.x

The package metadata indicates the Python 3.7 is supported, however, as of version 1.3.2 the distinctipy/__init__.py now uses importlib.metadata, which is only available in Python 3.8+.

There are two solutions:

Revert to using __init__.py as the single source of version truth (which is probably difficult if you want to stick with pyproject.toml structure)
Change requires-python = ">=3.7" to requires-python = ">=3.8" in pyproject.toml

The second option is probably the best. It might also be worthwhile to yank 1.3.2 and 1.3.3 because Python 3.7 might incorrectly think that those packages are comaptible with it.

Add pre-commit config

Improve tests and coverage

Ordering the colors generated

Hello,

Thank you for your work. This library is of great help to me. I have a small suggestion. For many use cases, the labels and classes being visualized are ordered and it is better if the colors are ordered as well. When using distinctipy.get_colors(), it would be great if there is an option that the colors follow some order instead of being completely random.

[Feature request] Add class `Color`

I would add a main class Color (naming TBD), and the whole library would work with it.

eg. distinct_color() returns Color. color_distance() takes 2x Color as argument. The why is that we don't need to create our own helper classes for normalization/color order conversion.

distinctipy.distinct_color().bgr().normalize(256).tuple() # Returns tuple of ints, 0..255, BGR order
# Same as:
distinctipy.distinct_color().cv2() # New proposed method


color = distinctipy.distinct_color()
cv2.putText(image, 'Text', (20,20), font, 1, color.cv2(), thickness, cv2.LINE_AA)
cv2.putText(image, 'Text', (20,40), font, 1, color.get_text_color().cv2(), thickness, cv2.LINE_AA)

Let me know your thoughts, as I (or one of our team members) would like to start working on this.
Thanks, Erik

Optimise assignment of colours

The use case of distinctipy is that you need N distinct colours for N different groups in some kind of visualisation. The part of picking N colours is implemented, but it would be nice to also try to optimise which colour should be assigned to which group. E.g. Given co-ordinates for each group/the members of each group, find a colour assignment that maximises the colour distinction between the group and its neighbours.

MANUALLY RE-ORDER COLORS FROM CREATED DISTINCT COLORS

Please How can I extract the distinct colors created and use them continuously such that it does not change when I re-run the code. This is because I need specific colors to be repeated. e.g in_cols = [black,black,black,blue,blue,blue ...etc]

I have tried the following but it seems not to work.
in_colors = [#2b1f53,#2b1f53,#2b1f53,#00ff00,#f300e8,#0080ff,#ff8000,#80bf80,#3702a4,#c1022d,
#0c7f17,#2dfef8,#e17eff,#ffff00,#00ff80,#8658a6,#096585,#85ad00,#f5b38a,#653b0e,
#75abfd,#8000ff,#fe417a,#0000ff,#21aeb0,#a3ff38,#9cfafd,#ac6d47,#2fc842,#b21299,#ffff80,#5249fb]
d=distinctipy.get_colors(in_colors)

Tighten up API

New init.py exposes everything when importing parent distinctipy. Would be better to tighten this up and only expose a few key functions.

Including test suite in pypi tarball

Would you be interested to include the tests in the pypi source tarball?

For packaging software it's often more reliable to download the sources from pypi, as it prohibits re-release, whereas on GitHub it's often possible for people to retroactively include changes without realizing that a lot of package managers will flare up at the checksum mismatch as it's identical to what might be a security problem.

Currently, if I do that, I won't be able to permit users to run the test suite and ascertain the functionality of the package:

[deco]/tmp/dispy ❱ wget https://github.com/alan-turing-institute/distinctipy/archive/refs/tags/v1.2.2.tar.gz
--2023-01-31 07:33:36--  https://github.com/alan-turing-institute/distinctipy/archive/refs/tags/v1.2.2.tar.gz
Resolving github.com... 140.82.113.3
Connecting to github.com|140.82.113.3|:443... connected.
HTTP request sent, awaiting response... 302 Found
Location: https://codeload.github.com/alan-turing-institute/distinctipy/tar.gz/refs/tags/v1.2.2 [following]
--2023-01-31 07:33:37--  https://codeload.github.com/alan-turing-institute/distinctipy/tar.gz/refs/tags/v1.2.2
Resolving codeload.github.com... 140.82.113.10
Connecting to codeload.github.com|140.82.113.10|:443... connected.
HTTP request sent, awaiting response... 200 OK
Length: unspecified [application/x-gzip]
Saving to: ‘v1.2.2.tar.gz’

v1.2.2.tar.gz                          [               <=>                                               ]   7.83M  2.54MB/s    in 3.1s

2023-01-31 07:33:40 (2.54 MB/s) - ‘v1.2.2.tar.gz’ saved [8215214]

[deco]/tmp/dispy ❱ tar xvf v1.2.2.tar.gz
distinctipy-1.2.2/
distinctipy-1.2.2/.flake8
distinctipy-1.2.2/.gitattributes
distinctipy-1.2.2/.github/
distinctipy-1.2.2/.github/workflows/
distinctipy-1.2.2/.github/workflows/pythonapp.yml
distinctipy-1.2.2/.github/workflows/pythonpublish.yml
distinctipy-1.2.2/.gitignore
distinctipy-1.2.2/.isort.cfg
distinctipy-1.2.2/LICENSE
distinctipy-1.2.2/README.md
distinctipy-1.2.2/distinctipy/
distinctipy-1.2.2/distinctipy/__init__.py
distinctipy-1.2.2/distinctipy/_colorsets_data.py
distinctipy-1.2.2/distinctipy/colorblind.py
distinctipy-1.2.2/distinctipy/colorsets.py
distinctipy-1.2.2/distinctipy/datasets/
distinctipy-1.2.2/distinctipy/datasets/LICENSE
distinctipy-1.2.2/distinctipy/datasets/a1.csv
distinctipy-1.2.2/distinctipy/datasets/a2.csv
distinctipy-1.2.2/distinctipy/datasets/a3.csv
distinctipy-1.2.2/distinctipy/datasets/b1.csv
distinctipy-1.2.2/distinctipy/datasets/balloons.png
distinctipy-1.2.2/distinctipy/datasets/flower.png
distinctipy-1.2.2/distinctipy/datasets/flowers.png
distinctipy-1.2.2/distinctipy/datasets/lights.png
distinctipy-1.2.2/distinctipy/datasets/powder.png
distinctipy-1.2.2/distinctipy/datasets/s1.csv
distinctipy-1.2.2/distinctipy/datasets/s2.csv
distinctipy-1.2.2/distinctipy/datasets/s3.csv
distinctipy-1.2.2/distinctipy/datasets/s4.csv
distinctipy-1.2.2/distinctipy/datasets/test.png
distinctipy-1.2.2/distinctipy/datasets/umbrellas.png
distinctipy-1.2.2/distinctipy/datasets/wall.png
distinctipy-1.2.2/distinctipy/distinctipy.py
distinctipy-1.2.2/distinctipy/examples.py
distinctipy-1.2.2/distinctipy_logo.png
distinctipy-1.2.2/docs/
distinctipy-1.2.2/docs/Makefile
distinctipy-1.2.2/docs/about.rst
distinctipy-1.2.2/docs/api.rst
distinctipy-1.2.2/docs/conf.py
distinctipy-1.2.2/docs/index.rst
distinctipy-1.2.2/docs/install.rst
distinctipy-1.2.2/docs/make.bat
distinctipy-1.2.2/docs/usage.ipynb
distinctipy-1.2.2/examples.ipynb
distinctipy-1.2.2/examples/
distinctipy-1.2.2/examples/36colours.png
distinctipy-1.2.2/examples/colourblind_clusters_normal.png
distinctipy-1.2.2/examples/colourblind_clusters_optimised.png
distinctipy-1.2.2/examples/colourblind_test_protanopia.png
distinctipy-1.2.2/examples/colourblind_tritanopia_normal.png
distinctipy-1.2.2/examples/colourblind_tritanopia_optimised.png
distinctipy-1.2.2/examples/compare_50clusters_nipy_spectral.png
distinctipy-1.2.2/examples/compare_64colours_tab20.png
distinctipy-1.2.2/examples/input_output.png
distinctipy-1.2.2/examples/pastel.png
distinctipy-1.2.2/examples/text_and_invert.png
distinctipy-1.2.2/requirements.txt
distinctipy-1.2.2/requirements/
distinctipy-1.2.2/requirements/docs.txt
distinctipy-1.2.2/requirements/optional.txt
distinctipy-1.2.2/requirements/runtime.txt
distinctipy-1.2.2/requirements/tests.txt
distinctipy-1.2.2/setup.py
distinctipy-1.2.2/tests/
distinctipy-1.2.2/tests/test_distinctipy.py
distinctipy-1.2.2/tests/test_examples.py
[deco]/tmp/dispy ❱ wget https://files.pythonhosted.org/packages/3c/57/da49e941e26d0063b5d59c730f324ca72b4a693bf37543ae15016d48e18f/distinctipy-1.2.2.tar.gz
--2023-01-31 07:34:07--  https://files.pythonhosted.org/packages/3c/57/da49e941e26d0063b5d59c730f324ca72b4a693bf37543ae15016d48e18f/distinctipy-1.2.2.tar.gz
Resolving files.pythonhosted.org... 151.101.1.63, 151.101.65.63, 151.101.129.63, ...
Connecting to files.pythonhosted.org|151.101.1.63|:443... connected.
HTTP request sent, awaiting response... 200 OK
Length: 27664 (27K) [application/x-tar]
Saving to: ‘distinctipy-1.2.2.tar.gz’

distinctipy-1.2.2.tar.gz           100%[================================================================>]  27.02K  --.-KB/s    in 0.002s

2023-01-31 07:34:07 (15.5 MB/s) - ‘distinctipy-1.2.2.tar.gz’ saved [27664/27664]

[deco]/tmp/dispy ❱ tar xvf distinctipy-1.2.2.tar.gz
distinctipy-1.2.2/
distinctipy-1.2.2/LICENSE
distinctipy-1.2.2/PKG-INFO
distinctipy-1.2.2/README.md
distinctipy-1.2.2/distinctipy/
distinctipy-1.2.2/distinctipy/__init__.py
distinctipy-1.2.2/distinctipy/_colorsets_data.py
distinctipy-1.2.2/distinctipy/colorblind.py
distinctipy-1.2.2/distinctipy/colorsets.py
distinctipy-1.2.2/distinctipy/distinctipy.py
distinctipy-1.2.2/distinctipy/examples.py
distinctipy-1.2.2/distinctipy.egg-info/
distinctipy-1.2.2/distinctipy.egg-info/PKG-INFO
distinctipy-1.2.2/distinctipy.egg-info/SOURCES.txt
distinctipy-1.2.2/distinctipy.egg-info/dependency_links.txt
distinctipy-1.2.2/distinctipy.egg-info/requires.txt
distinctipy-1.2.2/distinctipy.egg-info/top_level.txt
distinctipy-1.2.2/setup.cfg
distinctipy-1.2.2/setup.py

Conda package?

Improve colour distinction metric

My impression is that different shades of green are favoured a bit too much at the moment.

Add tests

Have a few but should increase coverage

Accompanying paper

Is there any paper accompanying the library? I want to cite the library in a paper

Update docs for new API

Update docs and examples to show that it's possible to use import distinctipy rather than from distinctipy import distinctipy now.

Optionally always generate same color pallete

Start with `why`

I believe this would be useful in AI field - where you have X number of classes as an output of an eg. object detection. In that case, it's much better to have bounding boxes with the same color each time you run the program - people get used to that color, so they don't need to look at the label of some object (to determine whether detector's output is correct).

Move to `what`:

Add an option to always get the same palette for the same number of colors.

End with `how`:

So it would be something similar to what seaborn does;

import seaborn
p = seaborn.color_palette("husl", 9)
# p will always be the same

Issue with seaborn is that it's huge and has tons of dependencies, which isn't ideal if you just want to get color palettes.
If you are using random numbers to generate colors, maybe we could insert seed num for these, so the output color palette would always look the same.

Thoughts?