Update readme, docstrings

Author: dofuuz

LICENSE.txt

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2021-23 Myungchul Keum
+Copyright (c) 2021 Myungchul Keum
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

README.md

@@ -5,9 +5,11 @@ A perceptually uniform colormaps with **full range of lightness**.
 
 ## Preview
 
-![roseus-bars](img/roseus-bars.png)
+![Colorbars](img/roseus-bars.png)
 
-![audacity-roseus](img/audacity-roseus.png)
+![Audio spectrogram using Roseus](img/audacity-roseus.png)
+
+![Depth map using Arcus](img/depthmap-arcus.png)
 
 
 ## Installation
@@ -16,7 +18,7 @@ A perceptually uniform colormaps with **full range of lightness**.
 pip install roseus
 ```
 
-If installation fails, upgrade pip with python -m pip install --upgrade pip and try again.
+If installation fails, upgrade pip with `python -m pip install --upgrade pip` and try again.
 
 
 ## Usage
@@ -27,9 +29,9 @@ To use with matplotlib, import `roseus.mpl`.
 import matplotlib.pyplot as plt
 import roseus.mpl as rs
 
-plt.imshow(x, cmap=rs.roseus)
+plt.imshow(x, cmap=rs.arcus)
 # or
-plt.imshow(x, cmap='rs.roseus')
+plt.imshow(x, cmap='rs.arcus')
 ```
 
 To prevent confusion in namespace, prefix `rs.` is added. (ex. `rs.arcus`, `rs.b`, `rs.gr`, ...)
@@ -49,6 +51,10 @@ https://cran.r-project.org/web/packages/viridis/vignettes/intro-to-viridis.html
 ## Look into the colormaps
 
 To plot measures of a colormap in Roseus family,
+```sh
+pip install "roseus[generate]"
+```
+install additional dependency. Then,
 
 ```python
 from roseus.util import plot_measures

img/audacity-roseus.png

@@ -11,13 +11,14 @@
 import numpy as np
 from scipy.ndimage import maximum_filter
 
-from roseus import gen_colormap
+import roseus.mpl as rs
+from roseus.generator import gen_colormap
 
 
 def batch_colormap(tasks):
     results = []
     for task in tasks:
-        _, score = gen_colormap(task, lightness_range=(3, 97))
+        _, score = gen_colormap(task, chroma_shape='sin', lightness_range=(2, 98))
         results.append(score)
     return results
 
@@ -47,7 +48,7 @@ def batch_colormap(tasks):
 
     arc_scores = np.asarray(results, dtype=np.float32)
 
-    plt.imshow(arc_scores.T, extent=(sr[0], sr[1], rr[1], rr[0]), interpolation='none')
+    plt.imshow(arc_scores.T, extent=(sr[0], sr[1], rr[1], rr[0]), interpolation='none', cmap=rs.roseus)
 
     max_index = np.unravel_index(arc_scores.argmax(), arc_scores.shape)
     print(max_index)

img/depthmap-arcus.png

@@ -3,7 +3,7 @@
 Roseus colormap generator
 https://github.com/dofuuz/roseus
 
-Roseus: A perceptually uniform colormap with full range of lightness
+Roseus: Perceptually uniform colormaps with full range of lightness
 """
 
 import bisect
@@ -20,6 +20,27 @@
 
 
 def gen_colormap(hue_range=(-185, 170), chroma_shape='cos', lightness_range=(2, 99), plots=False):
+    """ Generate a perceptually uniform colormap has symmetric and smooth chroma, hue transition.
+
+    Parameters
+    ----------
+    hue_range : tuple
+        Hue range in degrees.
+    chroma_shape :
+        Shape of chroma transition.
+        One of 'sin', 'circle', 'cos'.
+    lightness_range : tuple
+        Lightness range
+    plots :
+        Set `True` to print details.
+        Set 'verbose' to print additional measures.
+
+    Returns
+    -------
+        Tuple of (color_rgb, score).
+        `color_rgb` is RGB values of the colormap.
+        `score` is value represents how much colormap is colorful.
+    """
     rx = np.linspace(0, 1, RES)
 
     if chroma_shape == 'square':
@@ -96,8 +117,8 @@ def in_gamut(c_mul):
     arc_len = sum_len * c_mul * (lightness_range[1] - lightness_range[0])
 
     if plots:
-        print(c_mul)
-        print(arc_len)
+        print(f'Max chroma: {c_mul}')
+        print(f'Length of variation: {arc_len}')
 
     if plots == 'verbose':
         plot_jch(j, c_, h_)
@@ -107,7 +128,7 @@ def in_gamut(c_mul):
 
 
 def plot_jch(j, c_, h_):
-    # plot J, C, h
+    """ Plot transition of Lightness, Chroma, Hue """
     plt.figure(figsize=(6.4, 3.6))
 
     ax = plt.subplot(231)
@@ -144,6 +165,7 @@ def plot_jch(j, c_, h_):
 
 
 def plot_gamut(jab):
+    """ Plot sRGB gamut for colormaps. It is broken for most of colormaps for now."""
     j = jab[..., 0]
     a = jab[..., 1]
     b = jab[..., 2]
@@ -184,6 +206,7 @@ def plot_gamut(jab):
 
 
 def plot_rgb(rgb1):
+    """ Plot RGB values """
     rgbs = (rgb1*255).round().clip(0, 255).astype('uint8')
 
     seg_simple = 8