From f7dc4cd02c59fc2433e9deed0c7d4f47600564c9 Mon Sep 17 00:00:00 2001
From: cormullion <cormullion@mac.com>
Date: Wed, 11 Sep 2024 16:38:11 +0100
Subject: [PATCH] add resample() to fix #128

---
 CHANGELOG.md        | 12 ++++++++++++
 Project.toml        |  2 +-
 docs/src/basics.md  | 42 +++++++++++++++++++++++++++++-------------
 docs/src/index.md   |  3 +++
 src/ColorSchemes.jl | 43 +++++++++++++++++++++++++++++++++++++++++++
 test/runtests.jl    |  7 +++++++
 6 files changed, 95 insertions(+), 14 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index a03117d..7850e27 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,5 +1,17 @@
 # Changelog
 
+## [v3.27.0] - forthcoming
+
+### Added
+
+- resample
+
+### Removed
+
+### Deprecated
+
+###################################################################
+
 ## [v3.26.0] - 2024-07-21
 
 ### Added
diff --git a/Project.toml b/Project.toml
index 6c996c3..ac4cba7 100644
--- a/Project.toml
+++ b/Project.toml
@@ -1,7 +1,7 @@
 name = "ColorSchemes"
 uuid = "35d6a980-a343-548e-a6ea-1d62b119f2f4"
 authors = ["cormullion", "rafaqz", "gustaphe", "lwabeke", "NHDaly", "stevengj", "t-bltg", "asinghvi17", "davibarreira", "adrhill", "tecosaur", "jarredclloyd"]
-version = "3.26.0"
+version = "3.27.0"
 
 [deps]
 ColorTypes = "3da002f7-5984-5a60-b8a6-cbb66c0b333f"
diff --git a/docs/src/basics.md b/docs/src/basics.md
index 140791a..4d7290c 100644
--- a/docs/src/basics.md
+++ b/docs/src/basics.md
@@ -327,6 +327,35 @@ using Colors, ColorSchemes
 ColorScheme(distinguishable_colors(10, transform=protanopic))
 ```
 
+## The `resample()` function
+
+Use `resample()` to make a new colorscheme by resampling an existing one:
+
+```@example
+using Colors, ColorSchemes # hide
+ColorSchemes.turbo
+```
+```@example
+using Colors, ColorSchemes # hide
+resample(ColorSchemes.turbo, 9) 
+```
+
+You can pass a function to `resample()` to control the alpha opacity of each color in the color scheme.
+
+```@example
+using Colors, ColorSchemes # hide
+resample(ColorSchemes.turbo, 9, (alpha) -> 0.5) 
+```
+
+This sets the alpha value of every color to 0.5.
+
+```@example
+using Colors, ColorSchemes # hide
+resample(ColorSchemes.turbo, 30, (alpha) -> sin(alpha * π)) 
+```
+
+This example varies the alpha from 0 (at 0.0), 1 (at 0.5), and 0 (at 1.0). 
+
 ## More about color sampling
 
 You can access the specific colors of a colorscheme by indexing (eg `leonardo[2]` or `leonardo[5:end]`). Or you can sample a ColorScheme at a point between 0.0 and 1.0 as if it were a continuous range of colors:
@@ -411,16 +440,3 @@ for (k, v) in matplotlibcmaps
    end
 end
 ```
-
-## Alpha transparency
-
-To convert a colorscheme to one with transparency, you could use a function like this:
-
-```julia
-function colorscheme_alpha(cscheme::ColorScheme, alpha::T = 0.5; 
-        ncolors=12) where T<:Real
-    return ColorScheme([RGBA(get(cscheme, k), alpha) for k in range(0, 1, length=ncolors)])
-end
-
-colors = colorscheme_alpha(ColorSchemes.ice, ncolors=12)
-```
diff --git a/docs/src/index.md b/docs/src/index.md
index dd1bed0..3b737dc 100644
--- a/docs/src/index.md
+++ b/docs/src/index.md
@@ -69,6 +69,9 @@ ColorScheme([colorant"red", colorant"green", colorant"blue"])
 
 get(ColorSchemes.darkrainbow, range(0.0, 1.0, length=20)) |> ColorScheme
 # new colorscheme by resampling existing
+
+resample(ColorSchemes.darkrainbow, 20)
+# new colorscheme by resampling using `resample()` 
 ```
 
 Original version by [cormullion](https://github.com/cormullion).
diff --git a/src/ColorSchemes.jl b/src/ColorSchemes.jl
index 7c56821..d54950c 100644
--- a/src/ColorSchemes.jl
+++ b/src/ColorSchemes.jl
@@ -26,6 +26,7 @@ export ColorScheme,
        colourschemes,
        loadcolourscheme,
        findcolourscheme,
+       resample,
        ColourSchemeCategory
 
 """
@@ -405,6 +406,48 @@ Create new colorscheme by concatenating two colorschemes.
 """
 *(cscheme1::ColorScheme, cscheme2::ColorScheme) = ColorScheme(vcat(cscheme1.colors, cscheme2.colors))
 
+"""
+    resample(cs::colorscheme, n=10)
+
+Create a new colorscheme that samples an existing colorscheme `cs` `n` times.
+
+```julia
+resample(ColorSchemes.turbo)
+resample(ColorSchemes.turbo, 5)
+```
+"""
+function resample(cs::ColorScheme, n=10)
+    return ColorScheme(
+        [get(cs, i) for i in range(0, 1, length=max(n, 2))],
+        cs.category,
+        cs.notes * " resampled $n")
+end
+
+"""
+    resample(cs::colorscheme, n, alphafunction)
+
+Create a new colorscheme with RGBA colors that samples an existing colorscheme
+`cs` `n` times and applies the single argument `alphafunction` at each sampling
+point to set the alpha opacity value.
+
+```julia
+# set all 20 colors in scheme to alpha  0.5
+resample(ColorSchemes.turbo, 20, (α) -> 0.5)
+
+# set first 10 of 20 colors in scheme to alpha = 1
+resample(ColorSchemes.turbo, 20, (alpha) -> alpha > 0.5 ? 1 : 0.0)
+
+# set alpha value to sine; values around 0.5 are opaque 
+resample(ColorSchemes.leonardo, 10, (alpha) -> sin(alpha * π))
+```
+"""
+function resample(cs::ColorScheme, n, alpha::Function)
+    return ColorScheme(
+        [ColorSchemes.RGBA(get(cs, i), alpha(i)) for i in range(0, 1, length=max(n, 2))],
+        cs.category,
+        cs.notes * " resampled $n with alpha")
+end
+
 include("precompile.jl")
 
 # Aliases - Oxford spelling       
diff --git a/test/runtests.jl b/test/runtests.jl
index 9f396f8..42d893b 100644
--- a/test/runtests.jl
+++ b/test/runtests.jl
@@ -138,6 +138,13 @@ end
 
     # test findcolorschemes()
     @test length(findcolorscheme("rainbow")) > 0
+
+    # test resample
+    csa = resample(ColorSchemes.turbo, 20)
+    @test length(csa) == 20
+
+    csa = resample(ColorSchemes.turbo, 20, (α) -> 0.5)
+    @test csa[1].alpha == 0.5
 end
 
 # these won't error but they don't yet work correctly either