Skip to content

Commit

Permalink
Merge branch 'vmagnin:main' into main
Browse files Browse the repository at this point in the history
  • Loading branch information
@gha3mi
gha3mi committed Jan 6, 2024
2 parents 0728c59 + 32decc8 commit 35c6d17
Showing 1 changed file with 25 additions and 24 deletions.
49 changes: 25 additions & 24 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,19 +1,15 @@
# ForColormap

This Fortran fpm library is independent of any graphical toolkit: its main functionnality is converting a real value to RGB values, that you can use with any toolkit offering bitmap drawing. And it offers various methods and options to manage colormaps.

It includes:
This Fortran fpm library is independent of any graphical toolkit: its main functionality is to convert a real value to RGB values that you can use with any drawing toolkit. It offers various methods and options to manage colormaps. It includes:

* a few basic colormaps: "grey", "fire", "rainbow", "inverted_rainbow", "zebra",
* the Dave Green's [cubehelix](https://www.mrao.cam.ac.uk/~dag/CUBEHELIX/) colormap,
* the "magma", "inferno","plasma", "viridis" [matplotlib colormaps](https://bids.github.io/colormap/),
* the 222 colormaps of the *Scientific colour maps* collection v8.0.1 by Fabio Crameri. See Fabio Crameri's poster ["Scientific Colour Maps"](https://www.fabiocrameri.ch/ws/media-library/a17d02961b3a4544961416de2d7900a4/posterscientificcolourmaps_crameri.pdf) for more information and my [No Bijection!](NO_BIJECTION.md) text about the mysteries and wonders of colors.

Note that **there is no default colormap** as we consider that the user must choose a colormap adapted to the properties of its data. This [guideline](https://s-ink.org/colour-map-guideline) can help you choosing the right kind of colormap.

## Basic usage

Assuming your graphical library has a `setpixelgb()`-like function and you know your `z` values will be in the [0, 2] range, you can write something like:
Assuming your graphical library has a `setpixelgb()`-like function and you know your `z` values will be for example in the [0, 2] range, you can write something like:

```fortran
use forcolormap, only: Colormap, colormaps_list, wp
Expand All @@ -32,38 +28,28 @@ call setpixelrgb(x, y, red, green, blue)

The library is using the precision `wp=>real64` defined in the module `iso_fortran_env`.

Look into the `example/demo.f90` file for more usage examples: you can create your own colormap, download a colormap from a text file, etc. The `example/demo_reverse.f90` file shows how to use the `reverse` option to reverse the direction of a colormap.

Note that **there is no default colormap** as we consider that the user must choose a colormap adapted to the properties of its data. This [guideline](https://s-ink.org/colour-map-guideline) can help you choosing the right kind of colormap.

## Installation

### Requirements

You need:
You need, whatever your operating system:

* a modern Fortran compiler, for example GFortran or the Intel ifort/ifx compilers. See the [Fortran-lang.org compilers page](https://fortran-lang.org/compilers/) for other compilers.
* The Fortran Package Manager [fpm](https://fpm.fortran-lang.org/).
* For writing PPM files, the library [ForImage](https://github.com/gha3mi/forimage) is used as a fpm dependency.
* Any operating system.

### Testing the project

If you have a GitHub account, just clone the repository and launch the demo example, which is creating [PPM files](https://en.wikipedia.org/wiki/Netpbm#File_formats) with colormaps and colorbars for all the available colormaps:
If you have a GitHub account, just clone the repository. Then launch the demo example, which is creating [PPM files](https://en.wikipedia.org/wiki/Netpbm#File_formats) with colormaps and colorbars for all the available colormaps:

```bash
$ git clone [email protected]:vmagnin/forcolormap.git
$ cd forcolormap
$ fpm run --example demo
```

Other examples/demos are available:

* `demo_reverse.f90` demonstrates the usage of the `reverse=.true.` option to reverse the direction of a colormap.
* `example1.f90` demonstrates how ForImage can be used to import/export PPM files.
* `extract.f90` demonstrates how to create a specific colormap by extracting a specified number of colors of a colormap.
* `info.f90` demonstrates how to obtain information about a colormap using the `Colormaps_info` class.


### Using ForColormap as a fpm dependency

To use ForColormap within your own `fpm` project, add the following lines to your `fpm.toml` manifest file:
Expand All @@ -73,14 +59,27 @@ To use ForColormap within your own `fpm` project, add the following lines to you
forcolormap = {git = "https://github.com/vmagnin/forcolormap.git" }
```

## Learning

In the `example` directory, you will find these commented demos:

* `demo.f90` creates demo PPM files for each built-in colormap, plus a PPM file with the corresponding colorbars. It also demonstrates how to create your own colormap defined in an array and how to download a colormap from a `.txt` file.
* `demo_reverse.f90` demonstrates the usage of the `reverse=.true.` option to reverse the direction of a colormap.
* `example1.f90` demonstrates how ForImage can be used to import/export PPM files.
* `extract.f90` demonstrates how to create a specific colormap by extracting a specified number of colors of a colormap.
* `info.f90` demonstrates how to obtain information about a colormap using the `Colormaps_info` class.

They can be launched with the command `fpm run --example name_of_the_example` (without the `.f90` extension).


## TODO / ideas for further developments

* [ ] Create a logo: a colored marble?
* [ ] Create a logo: a coloured marble?
* [ ] Improve the documentation.
* [ ] Include a few images in the README.md file.
* [ ] Which colormaps are colorblind friendly, perceptually uniform, B&W print safe, etc.
* [ ] Add in `src/colormaps_info.f90` and `COLORMAPS_LIST.md` the Matplotlib and miscellaneous colormaps.
* [ ] Add more colormaps.
* [ ] Colormaps could have an option for logscale.
* [ ] A `get_colorbar()` function could return an `array(:,:,1:3)` containing the RGB image of the colorbar. The arguments could be the width and height, the direction (horizontal/vertical), etc.
* [ ] A `save()` method could save a colormap as RGB values separated by spaces in a `.lut` text file.
Expand All @@ -94,20 +93,23 @@ This project is under MIT license.

## Citing colormaps

As any work, a colormap should be cited:

* For *Scientific colour maps,* please cite these two items:
* Crameri, F. (2018a), Scientific colour maps. *Zenodo.* https://doi.org/10.5281/zenodo.1243862
* Crameri, Fabio, Grace E. Shephard, and Philip J. Heron. “The Misuse of Colour in Science Communication.” *Nature Communications* 11, no. 1 (October 28, 2020): 5444. https://doi.org/10.1038/s41467-020-19160-7.
* For the matplotlib colormaps, you can cite this webpage https://bids.github.io/colormap/
* For the *cubehelix* colormap, please cite:
* Green, D. A. “A Colour Scheme for the Display of Astronomical Intensity Images.” *arXiv,* August 30, 2011. https://arxiv.org/abs/1108.5083.


## References

### Articles and books

* Nuñez, Jamie R., Christopher R. Anderton, and Ryan S. Renslow. “Optimizing Colormaps with Consideration for Color Vision Deficiency to Enable Accurate Interpretation of Scientific Data.” Edited by Jesús Malo. *PLOS ONE* 13, no. 7 (August 1, 2018): e0199239. https://doi.org/10.1371/journal.pone.0199239.
* Nuñez, Jamie R., Christopher R. Anderton, and Ryan S. Renslow. “Optimizing Colormaps with Consideration for Color Vision Deficiency to Enable Accurate Interpretation of Scientific Data.” Edited by Jesús Malo. *PLOS ONE* 13, no. 7, August 1, 2018, e0199239. https://doi.org/10.1371/journal.pone.0199239.
* Rogowitz, Bernice E, and Lloyd A Treinish. [“Why Should Engineers and Scientists Be Worried About Color?”](https://github.com/amadeusine/interesting-reads/blob/master/ibm-research__why-should-engineers-and-scientists-be-worried-about-color.pdf)
* Thyng, Kristen, Chad Greene, Robert Hetland, Heather Zimmerle, and Steven DiMarco. “True Colors of Oceanography: Guidelines for Effective and Accurate Colormap Selection.” *Oceanography* 29, no. 3 (September 1, 2016): 9–13. https://doi.org/10.5670/oceanog.2016.66.
* Thyng, Kristen, Chad Greene, Robert Hetland, Heather Zimmerle, and Steven DiMarco. “True Colors of Oceanography: Guidelines for Effective and Accurate Colormap Selection.” *Oceanography* 29, no. 3, September 1, 2016, pp. 9–13. https://doi.org/10.5670/oceanog.2016.66.
* Valeur, Bernard. *La couleur dans tous ses éclats.* Bibliothèque scientifique. Paris: Belin-"Pour la science", 2011, ISBN 9782701158761.
* Valeur, Bernard. *Lumière et luminescence - Ces phénomènes lumineux qui nous entourent.* Bibliothèque scientifique. Paris: Belin-"Pour la science", 2005, ISBN 9782701136035.

Expand All @@ -120,8 +122,7 @@ This project is under MIT license.
* "In Search of a Perfect Colormap", https://inversed.ru/Blog_2.htm

#### Specific colormaps
* Cubehelix (Dave Green, public domain):
* https://www.mrao.cam.ac.uk/~dag/CUBEHELIX/
* Cubehelix (Dave Green, public domain): https://www.mrao.cam.ac.uk/~dag/CUBEHELIX/
* Scientific colour maps (Fabio Crameri, MIT license):
* https://www.fabiocrameri.ch/colourmaps/
* https://s-ink.org/colour-map-guideline
Expand Down

0 comments on commit 35c6d17

Please sign in to comment.