add resample() to fix #128

CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## [v3.27.0] - forthcoming
+
+### Added
+
+- resample
+
+### Removed
+
+### Deprecated
+
+###################################################################
+
 ## [v3.26.0] - 2024-07-21
 
 ### Added

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"

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)
-```

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).

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       

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