|PyPI| |conda-forge| |Python| |GitHub| |JOSS|
*CMasher*: Scientific colormaps for making accessible, informative and *cmashing* plots
=======================================================================================
The *CMasher* package provides a collection of scientific colormaps and utility functions to be used by different *Python* packages and projects, mainly in combination with `matplotlib`_, showcased in the `online documentation`_ (where I also describe how to use the colormaps in other languages and applications).
The colormaps in *CMasher* are all designed to be perceptually uniform sequential using the `viscm`_ package; most of them are color-vision deficiency friendly; and they cover a wide range of different color combinations to accommodate for most applications.
It offers several alternatives to commonly used colormaps, like *chroma* and *rainforest* for *jet*; *sunburst* for *hot*; *neutral* for *binary*; and *fusion* and *redshift* for *coolwarm*.
If you cannot find your ideal colormap, then please open an `issue`_, provide the colors and/or style you want, and I will try to create one to your liking!
Let's get rid of all bad colormaps in the world together!
*If you use CMasher for your work, then please star the repo, such that I can keep track of how many users it has and more easily raise awareness of bad colormaps.*
*Additionally, if you use CMasher as part of your workflow in a scientific publication, please consider citing the CMasher paper* (*BibTeX:* ``cmr.get_bibtex``).
.. _issue: https://github.com/1313e/CMasher/issues
.. _online documentation: https://cmasher.readthedocs.io
.. _matplotlib: https://github.com/matplotlib/matplotlib
.. _viscm: https://github.com/matplotlib/viscm
Colormap overview
-----------------
Below is an overview of all the colormaps that are currently in *CMasher* (made with the ``cmr.create_cmap_overview()`` function).
For more information, see the `online documentation`_.
.. image:: https://github.com/1313e/CMasher/raw/master/static/cmap_overview.png
:width: 100%
:align: center
:target: https://cmasher.readthedocs.io
:alt: CMasher Colormap Overview
In the figure, one can see this wide range of color combinations that *CMasher* has to offer, as I wanted to make sure that *CMasher* has a colormap for everyone.
Because of this, *CMasher*'s sequential colormaps range from single major color maps like *amber*; *ember*; *flamingo*; *freeze*; *gothic*; and *jungle*, to colormaps with high perceptual ranges like *apple*; *chroma*; *torch*; *neon*; and *rainforest*.
The diverging colormaps in *CMasher* have a similar variety, but more importantly, several of them have a black center instead of a white center, like *iceburn*; *redshift*; *watermelon*; and *wildfire*.
Black centered diverging colormaps are quite rare as most researchers are used to white centered ones, even though a black centered diverging colormap can be rather useful in certain cases, like plotting a radial velocity map (the further away from the common center, the higher the velocity in either direction, and thus the corresponding color should be brighter).
Installation & Use
==================
How to install
--------------
*CMasher* can be easily installed directly from `PyPI`_ with::
$ pip install cmasher
or from `conda-forge`_ with::
$ conda install -c conda-forge cmasher # If conda-forge is not set up as a channel
$ conda install cmasher # If conda-forge is set up as a channel
If required, one can also clone the `repository`_ and install *CMasher* manually::
$ git clone https://github.com/1313e/CMasher
$ cd CMasher
$ pip install .
*CMasher* can now be imported as a package with ``import cmasher as cmr``.
Besides Python, *CMasher*'s colormaps can also be accessed in various other languages and applications.
A list of all currently known languages and applications that support *CMasher* can be found in the online documentation `here <https://cmasher.readthedocs.io/user/usage.html#accessing-colormaps>`_.
.. _repository: https://github.com/1313e/CMasher
.. _PyPI: https://pypi.org/project/CMasher
.. _conda-forge: https://anaconda.org/conda-forge/CMasher
Example use
-----------
The colormaps shown above can be accessed by simply importing *CMasher*.
This makes them available in the ``cmasher`` module, in addition to registering them in *matplotlib*'s ``cm`` module (with added ``'cmr.'`` prefix to avoid name clashes).
So, for example, if one were to use the *rainforest* colormap, this could be done with:
.. code:: python
# Import CMasher to register colormaps
import cmasher as cmr
# Import packages for plotting
import matplotlib as mpl
import matplotlib.pyplot as plt
import numpy as np
# Access rainforest colormap through CMasher or MPL
cmap = cmr.rainforest # CMasher
cmap = mpl.colormaps['cmr.rainforest'] # MPL
# Generate some data to plot
x = np.random.rand(100)
y = np.random.rand(100)
z = x**2+y**2
# Make scatter plot of data with colormap
plt.scatter(x, y, c=z, cmap=cmap, s=300)
plt.show()
For other use-cases, including an overview of *CMasher*'s utility functions and how to use *CMasher* in other programming languages and applications, see the `online documentation`_.
.. |PyPI| image:: https://img.shields.io/pypi/v/CMasher.svg?logo=pypi&logoColor=white&label=PyPI
:target: https://pypi.python.org/pypi/CMasher
:alt: PyPI - Latest Release
.. |Python| image:: https://img.shields.io/pypi/pyversions/CMasher?logo=python&logoColor=white&label=Python
:target: https://pypi.python.org/pypi/CMasher
:alt: PyPI - Python Versions
.. |GitHub| image:: https://img.shields.io/github/actions/workflow/status/1313e/CMasher/.github/workflows/test.yml?branch=dev
:target: https://github.com/1313e/CMasher/actions
:alt: GitHub Actions - Build Status
.. |ReadTheDocs| image:: https://img.shields.io/readthedocs/cmasher/latest.svg?logo=read%20the%20docs&logoColor=white&label=Docs
:target: https://cmasher.readthedocs.io
:alt: ReadTheDocs - Build Status
.. |JOSS| image:: https://img.shields.io/badge/JOSS-paper-brightgreen
:target: https://doi.org/10.21105/joss.02004
:alt: JOSS - Submission Status
.. |conda-forge| image:: https://img.shields.io/conda/vn/conda-forge/cmasher.svg?logo=conda-forge&logoColor=white
:target: https://anaconda.org/conda-forge/cmasher
:alt: Conda-Forge - Latest Release
Raw data
{
"_id": null,
"home_page": null,
"name": "cmasher",
"maintainer": null,
"docs_url": null,
"requires_python": "<4,>=3.10",
"maintainer_email": null,
"keywords": "cmasher perceptually uniform sequential colormaps plotting python visualization",
"author": null,
"author_email": "Ellert van der Velden <ellert_vandervelden@outlook.com>",
"download_url": "https://files.pythonhosted.org/packages/f6/a2/beb240e84976be6bb8ca156abdddf515924fc558150d34ccdd2296ddd82b/cmasher-1.9.1.tar.gz",
"platform": null,
"description": "|PyPI| |conda-forge| |Python| |GitHub| |JOSS|\n\n*CMasher*: Scientific colormaps for making accessible, informative and *cmashing* plots\n=======================================================================================\nThe *CMasher* package provides a collection of scientific colormaps and utility functions to be used by different *Python* packages and projects, mainly in combination with `matplotlib`_, showcased in the `online documentation`_ (where I also describe how to use the colormaps in other languages and applications).\nThe colormaps in *CMasher* are all designed to be perceptually uniform sequential using the `viscm`_ package; most of them are color-vision deficiency friendly; and they cover a wide range of different color combinations to accommodate for most applications.\nIt offers several alternatives to commonly used colormaps, like *chroma* and *rainforest* for *jet*; *sunburst* for *hot*; *neutral* for *binary*; and *fusion* and *redshift* for *coolwarm*.\nIf you cannot find your ideal colormap, then please open an `issue`_, provide the colors and/or style you want, and I will try to create one to your liking!\nLet's get rid of all bad colormaps in the world together!\n\n*If you use CMasher for your work, then please star the repo, such that I can keep track of how many users it has and more easily raise awareness of bad colormaps.*\n*Additionally, if you use CMasher as part of your workflow in a scientific publication, please consider citing the CMasher paper* (*BibTeX:* ``cmr.get_bibtex``).\n\n.. _issue: https://github.com/1313e/CMasher/issues\n.. _online documentation: https://cmasher.readthedocs.io\n.. _matplotlib: https://github.com/matplotlib/matplotlib\n.. _viscm: https://github.com/matplotlib/viscm\n\nColormap overview\n-----------------\nBelow is an overview of all the colormaps that are currently in *CMasher* (made with the ``cmr.create_cmap_overview()`` function).\nFor more information, see the `online documentation`_.\n\n.. image:: https://github.com/1313e/CMasher/raw/master/static/cmap_overview.png\n :width: 100%\n :align: center\n :target: https://cmasher.readthedocs.io\n :alt: CMasher Colormap Overview\n\nIn the figure, one can see this wide range of color combinations that *CMasher* has to offer, as I wanted to make sure that *CMasher* has a colormap for everyone.\nBecause of this, *CMasher*'s sequential colormaps range from single major color maps like *amber*; *ember*; *flamingo*; *freeze*; *gothic*; and *jungle*, to colormaps with high perceptual ranges like *apple*; *chroma*; *torch*; *neon*; and *rainforest*.\nThe diverging colormaps in *CMasher* have a similar variety, but more importantly, several of them have a black center instead of a white center, like *iceburn*; *redshift*; *watermelon*; and *wildfire*.\nBlack centered diverging colormaps are quite rare as most researchers are used to white centered ones, even though a black centered diverging colormap can be rather useful in certain cases, like plotting a radial velocity map (the further away from the common center, the higher the velocity in either direction, and thus the corresponding color should be brighter).\n\n\nInstallation & Use\n==================\nHow to install\n--------------\n*CMasher* can be easily installed directly from `PyPI`_ with::\n\n $ pip install cmasher\n\nor from `conda-forge`_ with::\n\n $ conda install -c conda-forge cmasher # If conda-forge is not set up as a channel\n $ conda install cmasher # If conda-forge is set up as a channel\n\nIf required, one can also clone the `repository`_ and install *CMasher* manually::\n\n $ git clone https://github.com/1313e/CMasher\n $ cd CMasher\n $ pip install .\n\n*CMasher* can now be imported as a package with ``import cmasher as cmr``.\n\nBesides Python, *CMasher*'s colormaps can also be accessed in various other languages and applications.\nA list of all currently known languages and applications that support *CMasher* can be found in the online documentation `here <https://cmasher.readthedocs.io/user/usage.html#accessing-colormaps>`_.\n\n.. _repository: https://github.com/1313e/CMasher\n.. _PyPI: https://pypi.org/project/CMasher\n.. _conda-forge: https://anaconda.org/conda-forge/CMasher\n\nExample use\n-----------\nThe colormaps shown above can be accessed by simply importing *CMasher*.\nThis makes them available in the ``cmasher`` module, in addition to registering them in *matplotlib*'s ``cm`` module (with added ``'cmr.'`` prefix to avoid name clashes).\nSo, for example, if one were to use the *rainforest* colormap, this could be done with:\n\n.. code:: python\n\n # Import CMasher to register colormaps\n import cmasher as cmr\n\n # Import packages for plotting\n import matplotlib as mpl\n import matplotlib.pyplot as plt\n import numpy as np\n\n # Access rainforest colormap through CMasher or MPL\n cmap = cmr.rainforest # CMasher\n cmap = mpl.colormaps['cmr.rainforest'] # MPL\n\n # Generate some data to plot\n x = np.random.rand(100)\n y = np.random.rand(100)\n z = x**2+y**2\n\n # Make scatter plot of data with colormap\n plt.scatter(x, y, c=z, cmap=cmap, s=300)\n plt.show()\n\nFor other use-cases, including an overview of *CMasher*'s utility functions and how to use *CMasher* in other programming languages and applications, see the `online documentation`_.\n\n\n.. |PyPI| image:: https://img.shields.io/pypi/v/CMasher.svg?logo=pypi&logoColor=white&label=PyPI\n :target: https://pypi.python.org/pypi/CMasher\n :alt: PyPI - Latest Release\n.. |Python| image:: https://img.shields.io/pypi/pyversions/CMasher?logo=python&logoColor=white&label=Python\n :target: https://pypi.python.org/pypi/CMasher\n :alt: PyPI - Python Versions\n.. |GitHub| image:: https://img.shields.io/github/actions/workflow/status/1313e/CMasher/.github/workflows/test.yml?branch=dev\n :target: https://github.com/1313e/CMasher/actions\n :alt: GitHub Actions - Build Status\n\n.. |ReadTheDocs| image:: https://img.shields.io/readthedocs/cmasher/latest.svg?logo=read%20the%20docs&logoColor=white&label=Docs\n :target: https://cmasher.readthedocs.io\n :alt: ReadTheDocs - Build Status\n.. |JOSS| image:: https://img.shields.io/badge/JOSS-paper-brightgreen\n :target: https://doi.org/10.21105/joss.02004\n :alt: JOSS - Submission Status\n.. |conda-forge| image:: https://img.shields.io/conda/vn/conda-forge/cmasher.svg?logo=conda-forge&logoColor=white\n :target: https://anaconda.org/conda-forge/cmasher\n :alt: Conda-Forge - Latest Release\n",
"bugtrack_url": null,
"license": "BSD-3",
"summary": "Scientific colormaps for making accessible, informative and 'cmashing' plots",
"version": "1.9.1",
"project_urls": {
"Documentation": "https://cmasher.readthedocs.io",
"Homepage": "https://cmasher.readthedocs.io",
"Source Code": "https://github.com/1313e/CMasher"
},
"split_keywords": [
"cmasher",
"perceptually",
"uniform",
"sequential",
"colormaps",
"plotting",
"python",
"visualization"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "f9dc0c6acd95479edcb151c1ed352fe3d92c7beb9f693f4eaa643d5d50e57d02",
"md5": "182da4d52e09078bef46e58b4245b130",
"sha256": "9c5b35336b90591361d8c765abb7c5cba46448e1b4dbf59d0e5116f89fef0ceb"
},
"downloads": -1,
"filename": "cmasher-1.9.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "182da4d52e09078bef46e58b4245b130",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4,>=3.10",
"size": 37416128,
"upload_time": "2024-11-19T09:18:44",
"upload_time_iso_8601": "2024-11-19T09:18:44.049055Z",
"url": "https://files.pythonhosted.org/packages/f9/dc/0c6acd95479edcb151c1ed352fe3d92c7beb9f693f4eaa643d5d50e57d02/cmasher-1.9.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "f6a2beb240e84976be6bb8ca156abdddf515924fc558150d34ccdd2296ddd82b",
"md5": "d32d813c7db1257e5293279b4b612d1a",
"sha256": "edb0b2fd224db305cffbb40932a091212d198db697e712e774b1f6156dbca4f6"
},
"downloads": -1,
"filename": "cmasher-1.9.1.tar.gz",
"has_sig": false,
"md5_digest": "d32d813c7db1257e5293279b4b612d1a",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4,>=3.10",
"size": 50152523,
"upload_time": "2024-11-19T09:18:48",
"upload_time_iso_8601": "2024-11-19T09:18:48.336536Z",
"url": "https://files.pythonhosted.org/packages/f6/a2/beb240e84976be6bb8ca156abdddf515924fc558150d34ccdd2296ddd82b/cmasher-1.9.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-11-19 09:18:48",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "1313e",
"github_project": "CMasher",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "cmasher"
}
JSON
