Colormap docs (#179)

* Add colormap thumbnail script * Add colormaps doc * Coerce name to lower case * Apply black on data * Escape spaces in markdown * Replace space with underscore * Add docstring * rename geographic colormaps * add refs for custom colormaps * fix link * format Co-authored-by: Kyle Barron <[email protected]>
cogeotiff · May 6, 2020 · fb7da01 · fb7da01
1 parent 3f5d94a
commit fb7da01
Show file tree

Hide file tree

Showing 11 changed files with 223 additions and 1 deletion.
diff --git a/docs/colormap.md b/docs/colormap.md
@@ -0,0 +1,39 @@
+# Colormaps
+
+Rio-tiler includes many colormaps, some derived from Matplotlib and some custom
+ones that are commonly-used with raster data.
+
+You can load a colormap with `rio_tiler.colormap.get_colormap`, and then pass it
+to `rio_tiler.utils.render`:
+
+```py
+from rio_tiler.colormap import get_colormap
+from rio_tiler.utils import render
+
+colormap = get_colormap('cfastie')
+render(tile, mask, colormap=colormap)
+```
+
+![](img/custom.png)
+![](img/perceptually_uniform_sequential.png)
+![](img/sequential.png)
+![](img/sequential_(2).png)
+![](img/diverging.png)
+![](img/cyclic.png)
+![](img/qualitative.png)
+![](img/miscellaneous.png)
+
+### Refs
+- Matplotlib: https://matplotlib.org/3.1.0/tutorials/colors/colormaps.html
+- cfastie: http://publiclab.org/notes/cfastie/08-26-2014/new-ndvi-colormap
+- rplumbo: https://github.com/cogeotiff/rio-tiler/pull/90
+- schwarzwald: http://soliton.vm.bytemark.co.uk/pub/cpt-city/wkp/schwarzwald/tn/wiki-schwarzwald-cont.png.index.html
+
+### Update images for new colormaps
+
+To regenerate these images for new colormaps, update the list of colormaps at
+the top of `scripts/colormap_thumb.py` and then run
+
+```bash
+python scripts/colormap_thumb.py
+```
diff --git a/docs/img/custom.png b/docs/img/custom.png
diff --git a/docs/img/cyclic.png b/docs/img/cyclic.png
diff --git a/docs/img/diverging.png b/docs/img/diverging.png
diff --git a/docs/img/miscellaneous.png b/docs/img/miscellaneous.png
diff --git a/docs/img/perceptually_uniform_sequential.png b/docs/img/perceptually_uniform_sequential.png
diff --git a/docs/img/qualitative.png b/docs/img/qualitative.png
diff --git a/docs/img/sequential.png b/docs/img/sequential.png
diff --git a/docs/img/sequential_(2).png b/docs/img/sequential_(2).png
diff --git a/docs/scripts/colormap_thumb.py b/docs/scripts/colormap_thumb.py
@@ -0,0 +1,183 @@
+"""
+colormap_thumb.py: Create colormap thumbnails for documentation
+
+This file is derived from the matplotlib documentation.
+https://matplotlib.org/tutorials/colors/colormaps.html
+"""
+from pathlib import Path
+
+import matplotlib.pyplot as plt
+import numpy as np
+from matplotlib.colors import ListedColormap
+from rio_tiler.colormap import get_colormap, make_lut
+
+
+cmaps = [
+    ("Custom", ["cfastie", "rplumbo", "schwarzwald"]),
+    (
+        "Perceptually Uniform Sequential",
+        ["viridis", "plasma", "inferno", "magma", "cividis"],
+    ),
+    (
+        "Sequential",
+        [
+            "Greys",
+            "Purples",
+            "Blues",
+            "Greens",
+            "Oranges",
+            "Reds",
+            "YlOrBr",
+            "YlOrRd",
+            "OrRd",
+            "PuRd",
+            "RdPu",
+            "BuPu",
+            "GnBu",
+            "PuBu",
+            "YlGnBu",
+            "PuBuGn",
+            "BuGn",
+            "YlGn",
+        ],
+    ),
+    (
+        "Sequential (2)",
+        [
+            "binary",
+            "gist_yarg",
+            "gist_gray",
+            "gray",
+            "bone",
+            "pink",
+            "spring",
+            "summer",
+            "autumn",
+            "winter",
+            "cool",
+            "Wistia",
+            "hot",
+            "afmhot",
+            "gist_heat",
+            "copper",
+        ],
+    ),
+    (
+        "Diverging",
+        [
+            "PiYG",
+            "PRGn",
+            "BrBG",
+            "PuOr",
+            "RdGy",
+            "RdBu",
+            "RdYlBu",
+            "RdYlGn",
+            "Spectral",
+            "coolwarm",
+            "bwr",
+            "seismic",
+        ],
+    ),
+    ("Cyclic", ["twilight", "twilight_shifted", "hsv"]),
+    (
+        "Qualitative",
+        [
+            "Pastel1",
+            "Pastel2",
+            "Paired",
+            "Accent",
+            "Dark2",
+            "Set1",
+            "Set2",
+            "Set3",
+            "tab10",
+            "tab20",
+            "tab20b",
+            "tab20c",
+        ],
+    ),
+    (
+        "Miscellaneous",
+        [
+            "flag",
+            "prism",
+            "ocean",
+            "gist_earth",
+            "terrain",
+            "gist_stern",
+            "gnuplot",
+            "gnuplot2",
+            "CMRmap",
+            "cubehelix",
+            "brg",
+            "gist_rainbow",
+            "rainbow",
+            "jet",
+            "nipy_spectral",
+            "gist_ncar",
+        ],
+    ),
+]
+
+
+gradient = np.linspace(0, 1, 256)
+gradient = np.vstack((gradient, gradient))
+
+
+def make_colormap(name):
+    """Use rio-tiler colormap to create matplotlib colormap
+    """
+    cmap = make_lut(get_colormap(name))
+    # rescale to 0-1
+    return ListedColormap(cmap / 255, name=name)
+
+
+def plot_color_gradients(cmap_category, cmap_list):
+    """Make
+    """
+    # Create figure and adjust figure height to number of colormaps
+    nrows = len(cmap_list)
+    figh = 0.35 + 0.15 + (nrows + (nrows - 1) * 0.1) * 0.22
+    fig, axes = plt.subplots(nrows=nrows, figsize=(6.4, figh))
+    fig.subplots_adjust(top=1 - 0.35 / figh, bottom=0.15 / figh, left=0.2, right=0.99)
+
+    axes[0].set_title(cmap_category + " colormaps", fontsize=14)
+
+    for ax, name in zip(axes, cmap_list):
+        ax.imshow(gradient, aspect="auto", cmap=make_colormap(name))
+        ax.text(
+            -0.01,
+            0.5,
+            name,
+            va="center",
+            ha="right",
+            fontsize=10,
+            transform=ax.transAxes,
+        )
+
+    # Turn off *all* ticks & spines, not just the ones with colormaps.
+    for ax in axes:
+        ax.set_axis_off()
+
+    return fig
+
+
+def main():
+    """Create thumbnails"""
+    for cmap_category, cmap_list in cmaps:
+        plot_color_gradients(cmap_category, cmap_list)
+
+        # Export fig
+        out_path = (
+            Path(__file__).parents[0]
+            / ".."
+            / "img"
+            / (cmap_category.replace(" ", "_").lower() + ".png")
+        )
+        out_path.parents[0].mkdir(exist_ok=True)
+        plt.savefig(out_path, dpi=200)
+
+
+if __name__ == "__main__":
+    main()
diff --git a/rio_tiler/colormap.py b/rio_tiler/colormap.py
@@ -50,7 +50,7 @@ def get_colormap(name: str) -> Dict:
             GDAL RGBA Color Table dictionary.
 
     """
-    cmap_file = os.path.join(os.path.dirname(__file__), "cmap", f"{name}.npy")
+    cmap_file = os.path.join(os.path.dirname(__file__), "cmap", f"{name.lower()}.npy")
     cmap = numpy.load(cmap_file)
     assert cmap.shape == (256, 4)
     assert cmap.dtype == numpy.uint8