Metadata-Version: 2.1
Name: cmap
Version: 0.0.1
Summary: Scientific colormaps for python, without dependencies
Project-URL: homepage, https://github.com/tlambert03/cmap
Project-URL: repository, https://github.com/tlambert03/cmap
Author-email: Talley Lambert <talley.lambert@gmail.com>
License: BSD 3-Clause License
License-File: LICENSE/LICENSE
License-File: LICENSE/LICENSE_CMOCEAN
License-File: LICENSE/LICENSE_COLORBREWER
License-File: LICENSE/LICENSE_COLORCET
License-File: LICENSE/LICENSE_CRAMERI
License-File: LICENSE/LICENSE_CVIDIS
License-File: LICENSE/LICENSE_GLASBEY
License-File: LICENSE/LICENSE_WISTIA
License-File: LICENSE/LICENSE_YORICK
Classifier: Development Status :: 3 - Alpha
Classifier: License :: OSI Approved :: BSD License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Requires-Python: >=3.8
Requires-Dist: numpy
Provides-Extra: dev
Requires-Dist: black; extra == 'dev'
Requires-Dist: ipython; extra == 'dev'
Requires-Dist: mypy; extra == 'dev'
Requires-Dist: pdbpp; extra == 'dev'
Requires-Dist: pre-commit; extra == 'dev'
Requires-Dist: pytest; extra == 'dev'
Requires-Dist: pytest-cov; extra == 'dev'
Requires-Dist: rich; extra == 'dev'
Requires-Dist: ruff; extra == 'dev'
Provides-Extra: docs
Requires-Dist: colorcet; extra == 'docs'
Requires-Dist: colorspacious; extra == 'docs'
Requires-Dist: imageio; extra == 'docs'
Requires-Dist: mkdocs; extra == 'docs'
Requires-Dist: mkdocs-gen-files; extra == 'docs'
Requires-Dist: mkdocs-literate-nav; extra == 'docs'
Requires-Dist: mkdocs-material; extra == 'docs'
Requires-Dist: mkdocs-minify-plugin; extra == 'docs'
Requires-Dist: mkdocstrings-python; extra == 'docs'
Provides-Extra: test
Requires-Dist: numba; python_version < '3.11' and extra == 'test'
Requires-Dist: pytest-cov; extra == 'test'
Requires-Dist: pytest>=6.0; extra == 'test'
Provides-Extra: thirdparty
Requires-Dist: bokeh; extra == 'thirdparty'
Requires-Dist: colour; extra == 'thirdparty'
Requires-Dist: matplotlib; extra == 'thirdparty'
Requires-Dist: napari; extra == 'thirdparty'
Requires-Dist: plotly; extra == 'thirdparty'
Requires-Dist: pydantic; extra == 'thirdparty'
Requires-Dist: pygfx; extra == 'thirdparty'
Requires-Dist: pyqt5; extra == 'thirdparty'
Requires-Dist: pytest-qt; extra == 'thirdparty'
Requires-Dist: rich; extra == 'thirdparty'
Requires-Dist: viscm; extra == 'thirdparty'
Requires-Dist: vispy; extra == 'thirdparty'
Description-Content-Type: text/markdown

# cmap

[![License](https://img.shields.io/pypi/l/cmap.svg?color=green)](https://github.com/tlambert03/cmap/raw/main/LICENSE)
[![PyPI](https://img.shields.io/pypi/v/cmap.svg?color=green)](https://pypi.org/project/cmap)
[![Python Version](https://img.shields.io/pypi/pyversions/cmap.svg?color=green)](https://python.org)
[![CI](https://github.com/tlambert03/cmap/actions/workflows/ci.yml/badge.svg)](https://github.com/tlambert03/cmap/actions/workflows/ci.yml)
[![codecov](https://codecov.io/gh/tlambert03/cmap/branch/main/graph/badge.svg)](https://codecov.io/gh/tlambert03/cmap)
[![Documentation Status](https://readthedocs.org/projects/cmap-docs/badge/?version=latest)](https://cmap-docs.readthedocs.io/en/latest/?badge=latest)

Scientific colormaps for python, with no dependencies beyond numpy.

With `cmap`, you can use any of the colormaps from [matplotlib](https://matplotlib.org/stable/tutorials/colors/colormaps.html) or [cmocean](https://matplotlib.org/cmocean/) in your python code, without having to install matplotlib or cmocean.

There are a number of python libraries that provide or require colormaps or
basic color support, but they all either depend on matplotlib, provide a
specialized set of colormaps intended to extend those provided by matplotlib, or
roll their own colormap solution that vendors/duplicates other libraries.

`cmap` is a lightweight, library that provides all of the open-source colormaps
from matplotlib and cmocean, with no dependencies beyond numpy.  It provides
exports to a number of known third-party colormap objects, allowing it to be
used across a wide range of python visualization libraries.  The intention is to provide
a library that can be used by any python library that needs colormaps, without
forcing the user to install matplotlib (while still being compatible with matplotlib
and other libraries that use matplotlib colormaps).

`cmap` is strictly typed and fully tested, with a focus on good developer experience.

## API

### [`cmap.Color`](https://cmap-docs.readthedocs.io/en/latest/colors/)

The `cmap.Color` object is a simple wrapper around a tuple of RGBA scalars, with
a few convenience methods for converting to other color objects.

```python
from cmap import Color

red = Color("red")  # or a variety of other "color like" inputs
```

### [`cmap.Colormap`](https://cmap-docs.readthedocs.io/en/latest/colormaps/)

The `cmap.Colormap` object is a callable that can map a scalar value (or numpy
array of values) to an RGBA color (or a numpy array of RGBA colors).  API is
intended to mimic the behavior of a
[`matplotlib.colors.Colormap`](https://matplotlib.org/stable/api/_as_gen/matplotlib.colors.Colormap.html#matplotlib.colors.Colormap)
object (without requiring matplotlib)

```python
In [1]: import cmap

# or a variety of other "colormap like" inputs
In [2]: cmap1 = cmap.Colormap(["red", "green", "blue"])

In [3]: cmap1(np.linspace(0,1,5))
Out[3]:
array([[1.        , 0.        , 0.        , 1.        ],
       [0.50393701, 0.24900417, 0.        , 1.        ],
       [0.        , 0.50196078, 0.        , 1.        ],
       [0.        , 0.24900417, 0.50393701, 1.        ],
       [0.        , 0.        , 1.        , 1.        ]])
```

## Third Party Library Support

The `cmap.Colormap` object has convenience methods that allow it to be used with a number of third-party colormap objects (like
`matplotlib`, `vispy`, `napari`, `plotly`, etc...).

See [documentation](https://cmap-docs.readthedocs.io/en/latest/colormaps/#usage-with-external-visualization-libraries)
for details.

If you would like to see support added for a particular library, please open an issue or PR. 

## Alternatives

Other libraries providing colormaps:


- [matplotlib](https://matplotlib.org/stable/tutorials/colors/colormaps.html)
- [seaborn](https://seaborn.pydata.org/tutorial/color_palettes.html)  (subclasses matplotlib)
- [proplot](https://proplot.readthedocs.io/en/latest/colormaps.html)  (subclasses matplotlib)
- [palettable](https://jiffyclub.github.io/palettable/) (mostly data, import doesn't depend on matplotlib, but usage largely does)
- [cmocean](https://matplotlib.org/cmocean/) (mostly data, outputs matplotlib colormaps)
- [colorcet](https://colorcet.holoviz.org/) (mostly data, usage requires either matplotlib or bokeh)
- [cmasher](https://cmasher.readthedocs.io/) (requires matplotlib)
- [cmyt](https://github.com/yt-project/cmyt) (requires matplotlib)
- [cmcrameri](https://github.com/callumrollo/cmcrameri) (requires matplotlib, wraps <https://www.fabiocrameri.ch/colourmaps/>)
- [distinctipy](https://github.com/alan-turing-institute/distinctipy)  (generates distinct color sets, only requires numpy)
- [Farrow & Ball Matplotlib](https://github.com/vork/farrowandball) (requires matplotlib)
- [mplcyberpunk](https://github.com/dhaitz/mplcyberpunk) (requires matplotlib)

## References and Further reading

- [Choosing Colormaps in Matplotlib](https://matplotlib.org/stable/tutorials/colors/colormaps.html)
- [A Better Default Colormap for Matplotlib | SciPy 2015 | Nathaniel Smith and Stéfan van der Walt](https://www.youtube.com/watch?v=xAoljeRJ3lU)
- blog post for above video: <https://bids.github.io/colormap/>
- [Origins of Colormaps, Cleve Moler, February 2, 2015](https://blogs.mathworks.com/cleve/2015/02/02/origins-of-colormaps/)
- [Documenting the matplotlib colormaps, @endolith](https://gist.github.com/endolith/2719900)
- [Color Map Advice for Scientific Visualization](https://www.kennethmoreland.com/color-advice/)
- <https://colorcet.com/>, Peter Kovesi
- [Kovesi: Good Colour Maps: How to Design Them.](https://arxiv.org/abs/1509.03700)
- https://www.fabiocrameri.ch/colourmaps/
