search

vmagnin / forcolormap

A Fortran library for colormaps
https://vmagnin.github.io/forcolormap/
MIT License
21 stars 4 forks source link
colormaps fortran fortran-package-manager

readme

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:

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:

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:

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

Web pages

About colormaps

Specific colormaps