Skip to content

Latest commit

 

History

History
204 lines (145 loc) · 10.7 KB

README.md

File metadata and controls

204 lines (145 loc) · 10.7 KB
Raw

The ForColormap Fortran 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 includes:

  • the 222 colormaps of the Scientific colour maps collection v8.0.1 by Fabio Crameri. See Fabio Crameri's poster "Scientific Colour Maps" for more information,
  • the "magma", "inferno","plasma", "viridis" matplotlib colormaps,
  • the Dave Green's cubehelix colormap,
  • a few basic colormaps: "black_body", "fire", "rainbow", "inv_rainbow", "zebra".

And it offers various methods and options to manage colormaps.

Basic usage

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:

use forcolormap, only: Colormap, wp
...
type(Colormap) :: cmap
integer  :: red, green, blue
real(wp) :: z, x, y
...
! Let's use the glasgow colormap:
call cmap%set("glasgow", 0.0_wp, 2.0_wp)
...
z = f(x,y)
call cmap%compute_RGB(z, red, green, blue)
call setpixelrgb(x, y, red, green, blue)

The library is using the precision wp=>real64 defined in the module iso_fortran_env. And depending on the integers expected by your graphical library, you may need to convert the kinds of red, green, blue variables.

This guideline can help you choose the right kind of colormap. And you can visually choose the available colormaps in the colormaps_list/ForColormap.pdf manual or on this page (under development): https://github.com/gha3mi/forcolormap/tree/dev

Installation

Requirements

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 for other compilers.
  • The Fortran Package Manager fpm or CMake (>=3.24) & pkg-config for building the project.
    • For writing PPM files, the library ForImage is used as a fpm or CMake dependency (automatically downloaded).

Testing the project with fpm

If you have a GitHub account, just clone the repository. Then launch the demo example, which is creating PPM files with colormaps and colorbars for all the available colormaps:

$ git clone git@github.com:vmagnin/forcolormap.git
$ cd forcolormap
$ fpm run --example demo

Using ForColormap as a fpm dependency

To use ForColormap within your own fpm project, add the following lines to your fpm.toml manifest file:

[dependencies]
forcolormap = {git = "https://github.com/vmagnin/forcolormap.git"}

Using CMake

You can also build the project with CMake:

$ git clone git@github.com:vmagnin/forcolormap.git
$ cd forcolormap
$ mkdir build && cd build
$ cmake ..
$ make
$ sudo make install

Static linking

By default, ForColormap is built as a static library by CMake. You can compile your program with the -static option:

$ gfortran -static my_program.f90 $(pkg-config --cflags --libs forcolormap forimage)

Note that ForColormap is depending on ForImage, and for static linking you must respect that order.

Dynamic linking

There is a CMake option to obtain a shared library:

$ cmake -D BUILD_SHARED_LIBS=true ..

You can compile your program like this:

$ gfortran my_program.f90 $(pkg-config --cflags --libs forcolormap)

If you encounter linking problems, you should verify the content of your PKG_CONFIG_PATH and LD_LIBRARY_PATH environment variables. For example, in Ubuntu or FreeBSD the .pc files will be installed in /usr/local/lib/pkgconfig/ and the libraries in /usr/local/lib/.

$ export PKG_CONFIG_PATH=/usr/local/lib/pkgconfig/

Building examples and tests

You can build the examples with:

$ cmake -D BUILD_FORCOLORMAP_EXAMPLES=true ..
$ make
$ cd example

The automatic tests can be run with:

$ cmake -D BUILD_TESTING=true ..
$ make
$ ctest

Uninstalling ForColormap

From the build directory:

$ sudo make uninstall_forcolormap

Note that its dependency ForImage will also be uninstalled! You will have to reinstall it if needed.

You can also choose and remove files listed in build/install_manifest.txt one by one.

See CMake basics for more information.

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.
  • colormaps_list.f90 generates the colormaps_list/COLORMAPS_LIST_*.md files.
  • example1.f90 demonstrates how ForImage can be used to import/export PPM files.
  • create.f90 demonstrates creating a custom colormap using methods like create_lagrange() and create_bezier().
  • 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.
  • modify.f90 demonstrates how you can modify a colormap with methods like shift(), in concrete cases.

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

In the gtk-fortran-extra repository, you will also find a physical model demonstrating the use of ForColormap. It creates a movie with Turing patterns, displayed with various colormaps:

https://www.youtube.com/watch?v=cVHLCVVvZ4U

Licenses

This project is under MIT license. The logo files are under license CC BY-SA 4.0.

Citing colormaps

As any work, a colormap should be cited:

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.
  • Rogowitz, Bernice E, and Lloyd A Treinish. “Why Should Engineers and Scientists Be Worried About Color?”
  • 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.

Web pages

About colormaps

Specific colormaps