Merge branch 'lagrange' into ali-dev

CHANGELOG.md

@@ -4,6 +4,8 @@ All notable changes to the gtk-fortran project are documented in this file. The
 ## [forcolormap dev]
 
 ### Added
+* A `shift()` method to apply a circular shift to a colormap (left is +, right is -).
+ * `example/modify.f90` demonstrates how you can modify a colormap with methods like shift(), in concrete cases.
 * A private `check()` method in the Colormap class. It checks the validity of the colormap and its parameters, prints warnings, and fixes problems if necessary.
 * A `colormaps_list/ForColormap.pdf` manual listing all the available colormaps.
 * A function `bezier(colors, levels)` to create a colormap from continuous Bezier interpolation of control colors, in `src/colormap_class.f90`. The corresponding demo was added in `example/demo.f90`.
@@ -29,6 +31,7 @@ All notable changes to the gtk-fortran project are documented in this file. The
 * A `colorbar()` type-bound procedure to write a PPM file with the colorbar.
 
 ### Changed
+* `TODO.md` was refactored and renamed `ROADMAP.md`.
 * Code refactoring.
 * Moved `test` subroutine to demo and example1.
 * Renamed `get_current()` to `get_name()`.

README.md

@@ -132,6 +132,7 @@ In the `example` directory, you will find these commented demos:
 * `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.
+* `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).
 

ROADMAP.md

@@ -0,0 +1,120 @@
+# Roadmap
+
+## Version 0.9
+
+The main goal of v0.9 is to offer a usable library, sufficiently friendly, with a minimalist API documentation.
+
+### Features
+
+- [ ] Methods
+ - [x] Implement a `check()` method to fix colormap parameters if needed.
+ - [x] Include a few minimalist methods to create or manipulate colormaps. More will be added in subsequent releases.
+- [ ] Add facilities to pass 8 or 16-bit integers to C graphical libraries.
+ - [ ] Test with gtk-fortran and other libraries.
+- [x] Introspection (Colormap_info)
+ - [ ] Include all available colormaps.
+- [ ] Add Interpolation functions.
+ - [ ] Lagrange
+ - [x] Bezier
+- [ ] Add a `Colormap_test` class where the subroutine `test_colormap()` will be moved.
+
+### Examples
+
+- [x] Create a `modify` example:
+ - [x] For the `shift()` method.
+
+### Documentation
+
+- [x] Develop a PDF guide with all colorbars to aid in choosing a colormap.
+- [x] Develop a web version guide with all colorbars to aid in choosing a colormap.
+- [ ] Create a simple documentation generated with FORD.
+
+### Continuous Integration (CI)
+
+- [ ] Integrate fpm tests.
+- [ ] Integrate FORD documentation.
+
+### Building System
+
+- [x] Implement a CMake building system, allowing installation of a `.so`
+ - [x] Test on Linux.
+ - [ ] Test on FreeBSD.
+ - [ ] Test on Windows (MSYS2).
+ - [ ] Test on macOS.
+
+### Others
+
+- [x] Design a logo.
+
+<!-- ### Bug Fixes -->
+
+
+
+## Version 1.0
+
+The main goal of v1.0 is to offer a library with a stable API and a first version of a Diataxis documentation.
+
+### Documentation
+
+- [ ] Specify which colormaps are colorblind-friendly, perceptually uniform, B&W print safe, etc. This information could be included in the Diataxis documentation.
+
+### Deprecation
+
+- [ ] Consider removing a few naive colormaps (e.g., "fire" is very similar to "black_body")
+
+### Quality Assurance
+
+- [ ] Add more automatic tests in `test/check.f90`.
+
+
+
+## Version 1.1
+
+The main goal of v1.1 is to offer more features and to evolve the Diataxis documentation.
+
+
+# Ideas
+
+These concepts are open for implementation or consideration. They may or may not be implemented.
+
+### Features
+
+- [ ] Methods
+ - [ ] 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.
+ - [ ] Add a `save()` or `export()` method
+ - [ ] Transfer lut file subroutines from ForImage to ForColormap.
+ - [ ] Add suport `.xml` file for use in ParaView or other softwares.
+ - [ ] Improve the `shift()` method: 
+ - [ ] `shift_levels()`, `shift_real()`
+ - [ ] Possibly shifting automatically the colormap according to the [zmin, zmax] range. For example [-6, 3].
+ - [ ] `shift_region()`: shifting certain segments of colormaps.
+ - [ ] `split()` and `combine()` (could be useful to create a multi-sequential colormap) methods.
+ - [ ] Convert to greyscale (note: convert to grayscale is implemented in ForImage).
+ - [ ] Create and load colormaps based on other color formats (note: Color conversion is implemented in ForImage).
+ - [ ] `brighten()` and darken (note: this is implemented in ForImage).
+ - [ ] `mix()` two colormaps.
+- [ ] Develop a GUI using gtk-fortran to load, show, choose, modify, save, etc., colormaps.
+- [ ] Add Interpolation functions
+ - [ ] B-Splines
+ - [ ] NURBS
+- [ ] Colormaps
+ - [ ] Add more colormaps, only if similar ones are not already available and cannot be easily obtained with the available methods.
+
+### Examples
+
+- [ ] An example mixing gtk-fortran and ForColormap (to put in https://github.com/vmagnin/gtk-fortran-extra).
+
+### Continuous Integration (CI)
+
+- [ ] Set up continuous integration (CI) to automatically generate PDF files and colormap tables on a monthly basis or after each pull request.
+
+### Documentation
+
+- [ ] Include a few images in the `README.md` file.
+- [ ] Include real simulation images.
+
+### Publication
+
+- [ ] Obtain a DOI from Zenodo, for example.
+- [ ] And/or submit a JOSS *(Journal of Open Source Software)* paper similar to https://joss.theoj.org/papers/10.21105/joss.02004

example/CMakeLists.txt

@@ -17,3 +17,7 @@ target_link_libraries(extract ${PROJECT_NAME})
 # INFO
 add_executable(info info.f90)
 target_link_libraries(info ${PROJECT_NAME})
+
+# MODIFY
+add_executable(modify modify.f90)
+target_link_libraries(modify ${PROJECT_NAME})

example/README.md

@@ -7,3 +7,4 @@ They can be launched with the command `fpm run --example name_of_the_example` (w
 * `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.
+* `modify.f90` demonstrates how you can modify a colormap with methods like shift(), in concrete cases.

example/demo.f90

@@ -21,11 +21,11 @@
 ! SOFTWARE.
 !-------------------------------------------------------------------------------
 ! Contributed by vmagnin: 2023-09-26
-! Last modification: gha3mi 2024-01-28
+! Last modification: gha3mi 2024-01-28, vmagnin 2024-02-15
 !-------------------------------------------------------------------------------
 
 program demo
- use forcolormap, only: Colormap, colormaps_list, wp, bezier
+ use forcolormap, only: Colormap, colormaps_list, wp, bezier, lagrange
  implicit none
 
  integer :: i
@@ -47,25 +47,25 @@ program demo
  ! The built-in z=f(x,y) test function is in the [0, 2] range:
  do i = 1, size(colormaps_list)
  call cmap%set(trim(colormaps_list(i)), 0.0_wp, 2.0_wp)
- call cmap%colorbar(trim(colormaps_list(i))//'_colorbar', encoding='binary')
+ call cmap%colorbar(trim(colormaps_list(i))//'_colorbar')
  call test_colormap(cmap, trim(colormaps_list(i))//'_test', encoding='binary')
  print '("Colormap ", A30, " has ", I0, " levels")', trim(cmap%get_name()), cmap%get_levels()
  end do
 
  ! Cubehelix can also accept other parameters (varargs array):
  call cmap%set("cubehelix", 0.0_wp, 2.0_wp, 1024, [0.5_wp, -1.0_wp, 1.0_wp, 1.0_wp])
  ! We change the name for the output test files:
- call cmap%colorbar('cubehelix_customized_colorbar', encoding='binary')
+ call cmap%colorbar('cubehelix_customized_colorbar')
  call test_colormap(cmap, 'cubehelix_customized_test', encoding='binary')
 
  ! You can create your own colormap defined in an array:
  call custom_cmap%create('discrete', 0.0_wp, 2.0_wp, my_colormap)
- call custom_cmap%colorbar('discrete_colorbar', encoding='binary')
+ call custom_cmap%colorbar('discrete_colorbar')
  call test_colormap(custom_cmap, 'discrete_test', encoding='binary')
 
  ! Or you can download it from a .txt file:
  call custom_cmap%load("test_map_to_load.txt", 0.0_wp, 2.0_wp)
- call custom_cmap%colorbar('a_loaded_colorbar', encoding='binary')
+ call custom_cmap%colorbar('a_loaded_colorbar')
  call test_colormap(custom_cmap, 'a_loaded_colormap_test', encoding='binary')
  call custom_cmap%print()
 
@@ -76,9 +76,14 @@ program demo
  colors(2,:) = [0, 255, 0] ! Green
  colors(3,:) = [0, 0, 255] ! Blue
  call custom_cmap%create('custom_bezier', 0.0_wp, 2.0_wp, bezier(colors, levels=1024)) ! levels is optional, default is 256
- call custom_cmap%colorbar('custom_colorbar_bezier', encoding='binary')
+ call custom_cmap%colorbar('custom_colorbar_bezier')
  call test_colormap(custom_cmap, 'custom_test_bezier', encoding='binary') 
 
+ ! You can also create your own colormap using lagrange interpolation: 
+ call custom_cmap%create('custom_lagrange', 0.0_wp, 2.0_wp, lagrange(colors, levels=1024)) ! levels is optional, default is 256
+ call custom_cmap%colorbar('custom_colorbar_lagrange', encoding='binary')
+ call test_colormap(custom_cmap, 'custom_test_lagrange', encoding='binary') 
+
  contains
 
  subroutine test_colormap(self, filename, encoding)

example/demo_reverse.f90

@@ -21,7 +21,7 @@
 ! SOFTWARE.
 !-------------------------------------------------------------------------------
 ! Contributed by vmagnin: 2023-09-26
-! Last modification: gha3mi 2023-11-01
+! Last modification: gha3mi 2023-11-01, vmagnin 2024-02-15
 !-------------------------------------------------------------------------------
 
 program demo_reverse
@@ -46,25 +46,25 @@ program demo_reverse
  ! The built-in z=f(x,y) test function is in the [0, 2] range:
  do i = 1, size(colormaps_list)
  call cmap%set(trim(colormaps_list(i)), 0.0_wp, 2.0_wp, reverse=.true.)
- call cmap%colorbar(trim(colormaps_list(i))//'_reverse_colorbar', encoding='binary')
+ call cmap%colorbar(trim(colormaps_list(i))//'_reverse_colorbar')
  call test_colormap(cmap, trim(colormaps_list(i))//'_reverse_test', encoding='binary')
  print '("Colormap ", A30, " has ", I0, " levels")', trim(cmap%get_name()), cmap%get_levels()
  end do
 
  ! Cubehelix can also accept other parameters (varargs array):
  call cmap%set("cubehelix", 0.0_wp, 2.0_wp, 1024, [0.5_wp, -1.0_wp, 1.0_wp, 1.0_wp], reverse=.true.)
  ! We change the name for the output test files:
- call cmap%colorbar('cubehelix_customized_reverse_colorbar', encoding='binary')
+ call cmap%colorbar('cubehelix_customized_reverse_colorbar')
  call test_colormap(cmap, 'cubehelix_customized_reverse_test', encoding='binary')
 
  ! You can create your own colormap defined in an array:
  call custom_cmap%create('discrete', 0.0_wp, 2.0_wp, my_colormap, reverse=.true.)
- call custom_cmap%colorbar('discrete_reverse_colorbar', encoding='binary')
+ call custom_cmap%colorbar('discrete_reverse_colorbar')
  call test_colormap(custom_cmap, 'discrete_reverse_test', encoding='binary')
 
  ! Or you can download it from a .txt file:
  call custom_cmap%load("test_map_to_load.txt", 0.0_wp, 2.0_wp, reverse=.true.)
- call custom_cmap%colorbar('a_loaded_reverse_colorbar', encoding='binary')
+ call custom_cmap%colorbar('a_loaded_reverse_colorbar')
  call test_colormap(custom_cmap, 'a_loaded_reverse_colormap_test', encoding='binary')
  call custom_cmap%print()
 

example/extract.f90

@@ -21,7 +21,7 @@
 ! SOFTWARE.
 !-------------------------------------------------------------------------------
 ! Contributed by gha3mi: 2023-11-07
-! Last modification: gha3mi 2023-11-07
+! Last modification: gha3mi 2023-11-07, vmagnin 2024-02-15
 !-------------------------------------------------------------------------------
 
 ! This example demonstrates the process of extracting a specified number of colors.
@@ -42,7 +42,7 @@ program extract
  ! The extracted colormap will overwrite the existing colormap type (cmap)
  call cmap%extract(10)
 
- ! Generate a color bar for the extracted colormap with binary encoding
- call cmap%colorbar('fes10_ex_colorbar', encoding='binary')
- 
+ ! Generate a color bar for the extracted colormap
+ call cmap%colorbar('fes10_ex_colorbar')
+
 end program extract

example/modify.f90

@@ -0,0 +1,61 @@
+! The MIT License (MIT)
+!
+! Copyright (c) 2024 Vincent Magnin
+!
+! Permission is hereby granted, free of charge, to any person obtaining a copy
+! of this software and associated documentation files (the "Software"), to deal
+! in the Software without restriction, including without limitation the rights
+! to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+! copies of the Software, and to permit persons to whom the Software is
+! furnished to do so, subject to the following conditions:
+!
+! The above copyright notice and this permission notice shall be included in all
+! copies or substantial portions of the Software.
+!
+! THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+! IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+! FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+! AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+! LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+! OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+! SOFTWARE.
+!-------------------------------------------------------------------------------
+! Contributed by vmagnin: 2024-02-14
+! Last modification: vmagnin 2024-02-15
+!-------------------------------------------------------------------------------
+
+!> This example shows how you can modify a colormap with methods like shift(),
+!> in concrete cases.
+program modify
+ use forcolormap, only: Colormap, wp
+
+ implicit none
+ type(Colormap) :: cmap
+
+ !> In the Scientific colour maps collection, all cyclic colormaps have their
+ !> bright part in the middle. But we can shift the dark part towards the
+ !> center.
+ call cmap%set("bamO", 0.0_wp, 2.0_wp)
+ call cmap%colorbar("bamO")
+ call cmap%shift(cmap%get_levels() / 2)
+ call cmap%colorbar("bamO_shifted")
+ print *, "See the bamO.ppm and bamO_shifted.ppm colorbars"
+
+ !> In the Scientific colour maps collection, all categorical colormaps
+ !> begin with a dark colour, but a shift can be applied to begin with a
+ !> brighter colour.
+ call cmap%set("actonS", 0.0_wp, 2.0_wp)
+ call cmap%colorbar("actonS")
+ call cmap%shift(+2) !! Two levels towards left
+ call cmap%colorbar("actonS_shifted")
+ print *, "See the actonS.ppm and actonS_shifted.ppm colorbars"
+
+ !> Starting from a diverging colormap, we can obtain what could be called
+ !> a diverging multi-sequential colormap.
+ call cmap%set("bam", 0.0_wp, 2.0_wp)
+ call cmap%colorbar("bam")
+ call cmap%shift(cmap%get_levels() / 2)
+ call cmap%colorbar("bam_shifted")
+ print *, "See the bam.ppm and bam_shifted.ppm colorbars"
+
+end program modify

fpm.toml

@@ -42,6 +42,11 @@ name = "extract"
 source-dir = "example"
 main = "extract.f90"
 
+[[example]]
+name = "modify"
+source-dir = "example"
+main = "modify.f90"
+
 [build]
 auto-executables = true
 auto-tests = true