Add carryforward support to average

Author: facelessuser

coloraide/__meta__.py

@@ -204,5 +204,5 @@ def parse_version(ver: str) -> Version:
     return Version(major, minor, micro, release, pre, post, dev)
 
 
-__version_info__ = Version(8, 5, 1, "final")
+__version_info__ = Version(8, 6, 0, "final")
 __version__ = __version_info__._get_canonical()

coloraide/average.py

@@ -5,6 +5,7 @@
 import itertools as it
 from .spaces import HWBish
 from .types import ColorInput, AnyColor
+from .interpolate import carryforward_convert
 from typing import Iterable
 
 
@@ -24,7 +25,8 @@ def average(
     colors: Iterable[ColorInput],
     weights: Iterable[float] | None,
     space: str,
-    premultiplied: bool = True
+    premultiplied: bool = True,
+    carryforward: bool = False
 ) -> AnyColor:
     """
     Average a list of colors together.
@@ -33,10 +35,9 @@ def average(
     """
 
     sentinel = Sentinel()
-    obj = color_cls(space, [])
 
     # Get channel information
-    cs = obj.CS_MAP[space]
+    cs = color_cls.CS_MAP[space]
     if cs.is_polar():
         hue_index = cs.hue_index()  # type: ignore[attr-defined]
         is_hwb = isinstance(cs, HWBish)
@@ -49,6 +50,8 @@ def average(
         hue_max = 0.0
         to_rad = 0.0
         to_hue = 0.0
+
+    obj = color_cls(space, [])
     channels = cs.channels
     chan_count = len(channels)
     avgs = [0.0] * chan_count
@@ -83,10 +86,15 @@ def average(
             elif w > mx:
                 mx = w
 
-        obj.update(c)  # type: ignore[arg-type]
-        # If cylindrical color is achromatic, ensure hue is undefined
-        if hue_index >= 0 and not math.isnan(obj[hue_index]) and obj.is_achromatic():
-            obj[hue_index] = math.nan
+        if carryforward:
+            obj.mutate(c)  # type: ignore[arg-type]
+            carryforward_convert(obj, space, hue_index, True)
+        else:
+            obj.update(c)  # type: ignore[arg-type]
+            # If cylindrical color is achromatic, ensure hue is undefined
+            if hue_index >= 0 and not math.isnan(obj[hue_index]) and obj.is_achromatic():
+                obj[hue_index] = math.nan
+
         coords = obj[:]
 
         # Average weights

coloraide/color.py

@@ -1226,6 +1226,7 @@ def average(
         space: str | None = None,
         out_space: str | None = None,
         premultiplied: bool = True,
+        carryforward: bool | None = False,
         **kwargs: Any
     ) -> Self:
         """Average the colors."""
@@ -1241,7 +1242,8 @@ def average(
             colors,
             weights,
             space,
-            premultiplied
+            premultiplied,
+            carryforward if carryforward is not None else cls.CARRYFORWARD
         ).convert(out_space, in_place=True)
 
     def filter(  # noqa: A003

docs/src/markdown/about/changelog.md

@@ -3,8 +3,9 @@ icon: lucide/scroll-text
 ---
 # Changelog
 
-## 8.5.1
+## 8.6
 
+-   **NEW**: Add support for `carryforward` within `average()`.
 -   **ENHANCE**: More accurate dominant wavelength calculations.
 
 ## 8.5

docs/src/markdown/average.md

@@ -64,6 +64,8 @@ It should be noted that when averaging colors with hues which are evenly distrib
 will produce an achromatic hue. When achromatic hues are produced during circular mean, the color will discard
 chroma/saturation information, producing an achromatic color.
 
+![Evenly Distributed Angles](images/avg-evenly-distributed.png)
+
 ```py play
 Color.average(['red', 'green', 'blue'], space='hsl')
 ```
@@ -157,14 +159,22 @@ Color.average(['hsl(30 0 100)', 'hsl(240 100 50 / 1)'], space='hsl')
 ```
 
 As stated earlier, undefined logic is applied to any channel with undefined values. It should be noted that no attempt
-to carry forward the undefined values through conversion is made at this time. If conversion is required, the
+to carry forward the undefined values through conversion is made by default. If conversion is required, the
 conversions will remove any undefined status unless the channel is an achromatic hues.
 
 ```py play
 for i in range(12):
     Color.average(['darkgreen', f'color(srgb 0 none 0 / {i / 11})', 'color(srgb 0 0 1)'])
 ```
 
+If desired, `carryforward` can be enabled, and if possible, undefined values will be carried into the target color
+space.
+
+```py play
+for i in range(12):
+    Color.average(['darkgreen', f'color(srgb 0 none 0 / {i / 11})', 'color(srgb 0 0 1)'], carryforward=True)
+```
+
 When `premultiplied` is enabled, premultiplication will not be applied to a color if its `alpha` is undefined as it is
 unknown how to weight the color. Instead, a color with undefined transparency will be treated with full weight.
 

docs/src/markdown/examples/3d_models.html

@@ -1133,7 +1133,7 @@ <h1>ColorAide Color Space Models</h1>
 let colorSpaces = null
 let colorGamuts = null
 let lastModel = null
-let package = 'coloraide-8.5.1-py3-none-any.whl'
+let package = 'coloraide-8.6-py3-none-any.whl'
 const defaultSpace = 'lab'
 const defaultGamut = 'srgb'
 const exceptions = new Set(['hwb', 'ryb', 'ryb-biased'])

docs/src/markdown/examples/colorpicker.html

@@ -421,7 +421,7 @@ <h1>ColorAide Color Picker</h1>
     let pyodide = null
     let webspace = ''
     let initial = 'oklab(0.69 0.13 -0.1 / 0.85)'
-    let package = 'coloraide-8.5.1-py3-none-any.whl'
+    let package = 'coloraide-8.6-py3-none-any.whl'
 
     const base = `${window.location.origin}/${window.location.pathname.split('/')[1]}/playground/`
     package = base + package

docs/src/markdown/images/avg-evenly-distributed.png

@@ -355,7 +355,7 @@ extra_javascript:
   - assets/pymdownx-extras/extra-loader-Ccztcqfq.js
   - https://cdn.jsdelivr.net/npm/ace-builds@1.43.0/src-min-noconflict/ace.js
   - https://cdn.jsdelivr.net/npm/mermaid@11.12.1/dist/mermaid.min.js
-  - playground-config-fadebc12.js
+  - playground-config-53d4fff2.js
   - https://cdn.jsdelivr.net/pyodide/v0.29.0/full/pyodide.js
   - assets/coloraide-extras/extra-notebook.js
   - https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js

docs/src/zensical.yml

@@ -1,5 +1,5 @@
 var colorNotebook = {
-    "playgroundWheels": ['micropip', 'pygments-2.19.2-py3-none-any.whl', 'coloraide-8.5.1-py3-none-any.whl'],
-    "notebookWheels": ['pyyaml', 'markdown-3.10.1-py3-none-any.whl', 'pymdown_extensions-10.20-py3-none-any.whl', 'micropip', 'pygments-2.19.2-py3-none-any.whl', 'coloraide-8.5.1-py3-none-any.whl'],
+    "playgroundWheels": ['micropip', 'pygments-2.19.2-py3-none-any.whl', 'coloraide-8.6-py3-none-any.whl'],
+    "notebookWheels": ['pyyaml', 'markdown-3.10.1-py3-none-any.whl', 'pymdown_extensions-10.20-py3-none-any.whl', 'micropip', 'pygments-2.19.2-py3-none-any.whl', 'coloraide-8.6-py3-none-any.whl'],
     "defaultPlayground": "import coloraide\ncoloraide.__version__\nColor('red')"
 }