Feature/weighted avg (#476)

* Weighted average

* Use a rolling average

* When no weights are provided, assume all are 1

But fail if color count does not match weight count.

* Tweaks to plot scripts

* Update tests and documentation

Author: facelessuser

coloraide/average.py

@@ -2,13 +2,27 @@
 from __future__ import annotations
 import math
 from . import util
+import itertools as it
 from .spaces import HWBish
 from .types import ColorInput, AnyColor
 from typing import Iterable
 
+
+class Sentinel(float):
+    """Sentinel object that is specific to averaging that we shouldn't see defined anywhere else."""
+
+
+def _iter_colors(colors: Iterable[ColorInput]) -> Iterable[tuple[ColorInput, float]]:
+    """Iterate colors and return weights."""
+
+    for c in colors:
+        yield c, 1.0
+
+
 def average(
     color_cls: type[AnyColor],
     colors: Iterable[ColorInput],
+    weights: Iterable[float] | None,
     space: str,
     premultiplied: bool = True
 ) -> AnyColor:
@@ -18,6 +32,7 @@ def average(
     Polar coordinates use a circular mean: https://en.wikipedia.org/wiki/Circular_mean.
     """
 
+    sentinel = Sentinel()
     obj = color_cls(space, [])
 
     # Get channel information
@@ -31,67 +46,98 @@ def average(
     channels = cs.channels
     chan_count = len(channels)
     alpha_index = chan_count - 1
-    sums = [0.0] * chan_count
-    totals = [0.0] * chan_count
+    avgs = [0.0] * chan_count
+    counts = [0] * chan_count
     sin = 0.0
     cos = 0.0
+    wavg = 0.0
+    no_weights = weights is None
+    if no_weights:
+        weights = ()
+    mx = 0.0
 
-    # Sum channel values
-    i = -1
-    for c in colors:
-        obj.update(c)
+    # Sum channel values using a rolling average. Apply premultiplication and additional weighting as required.
+    count = 0
+    for c, w in (_iter_colors(colors) if no_weights else it.zip_longest(colors, weights, fillvalue=sentinel)):  # type: ignore[arg-type]
+
+        # Handle explicit weighted cases
+        if not no_weights:
+            # If there are more weights than colors, ignore additional weights
+            if c is sentinel:
+                break
+
+            # If there are less weights than colors, assume full weight for colors without weights
+            if w is sentinel:
+                w = mx
+
+            # Negative weights are considered as zero weight
+            if w < 0.0:
+                w = 0.0
+
+            # Track the largest weight so we can populate colors with no weights
+            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
         coords = obj[:]
         alpha = coords[-1]
         if math.isnan(alpha):
             alpha = 1.0
+        walpha = alpha * w
+        count += 1
+        wavg += (w - wavg) / count
         i = 0
         for coord in coords:
             # No need to average an undefined value or color components if alpha is zero
-            if not math.isnan(coord) and (premultiplied or alpha or i == alpha_index):
-                totals[i] += 1
+            is_alpha = i == alpha_index
+            if not math.isnan(coord) and (premultiplied or alpha or is_alpha):
+                counts[i] += 1
+                n = counts[i]
                 if i == hue_index:
                     rad = math.radians(coord)
                     if premultiplied:
-                        sin += math.sin(rad) * alpha
-                        cos += math.cos(rad) * alpha
+                        sin += ((math.sin(rad) * walpha) - sin) / n
+                        cos += ((math.cos(rad) * walpha) - cos) / n
                     else:
-                        sin += math.sin(rad)
-                        cos += math.cos(rad)
+                        sin += ((math.sin(rad) * w) - sin) / n
+                        cos += ((math.cos(rad) * w) - cos) / n
                 else:
-                    sums[i] += (coord * alpha) if premultiplied and i != alpha_index else coord
+                    avgs[i] += (((coord * walpha) if premultiplied and not is_alpha else (coord * w)) - avgs[i]) / n
             i += 1
 
-    if i == -1:
+    if not count:
         raise ValueError('At least one color must be provided in order to average colors')
 
-    # Get the mean
-    sums[-1] = alpha = math.nan if not totals[-1] else (sums[-1] / totals[-1])
+    # Undo premultiplication and weighting to get the final color
+    w_factor = math.nan if not wavg else wavg
+    avgs[-1] = alpha = math.nan if not counts[-1] else avgs[-1] / w_factor
     if math.isnan(alpha):
         alpha = 1.0
+    walpha = alpha * w_factor
+
     for i in range(chan_count - 1):
-        total = totals[i]
-        if not total or not alpha:
-            sums[i] = math.nan
+        if not counts[i] or not alpha:
+            avgs[i] = math.nan
         elif i == hue_index:
             if premultiplied:
-                sin /= total * alpha
-                cos /= total * alpha
+                sin /= walpha
+                cos /= walpha
             else:
-                sin /= total
-                cos /= total
+                sin /= w_factor
+                cos /= w_factor
             if abs(sin) < util.ACHROMATIC_THRESHOLD_SM and abs(cos) < util.ACHROMATIC_THRESHOLD_SM:
-                sums[i] = math.nan
+                avgs[i] = math.nan
             else:
                 avg_theta = math.degrees(math.atan2(sin, cos))
-                sums[i] = (avg_theta + 360) if avg_theta < 0 else avg_theta
+                avgs[i] = (avg_theta + 360) if avg_theta < 0 else avg_theta
         else:
-            sums[i] /= (total * alpha) if premultiplied else total
+            avgs[i] /= walpha if premultiplied else w_factor
 
-    # Create the color and if polar and there is no defined hue, force an achromatic state.
-    color = obj.update(space, sums[:-1], sums[-1])
+    # Create the color. If polar and there is no defined hue, force an achromatic state.
+    color = obj.update(space, avgs[:-1], avgs[-1])
     if cs.is_polar():
         if is_hwb and math.isnan(color[hue_index]):
             w, b = cs.indexes()[1:]  # type: ignore[attr-defined]

coloraide/color.py

@@ -1145,6 +1145,7 @@ def interpolate(
     def average(
         cls,
         colors: Iterable[ColorInput],
+        weights: Iterable[float] | None = None,
         *,
         space: str | None = None,
         out_space: str | None = None,
@@ -1166,6 +1167,7 @@ def average(
         return average.average(
             cls,
             colors,
+            weights,
             space,
             premultiplied
         ).convert(out_space, in_place=True)

docs/src/markdown/about/changelog.md

@@ -3,6 +3,7 @@
 ## 4.7
 
 -   **NEW**: Officially support Python 3.14.
+-   **NEW**: `average()` now accepts weights for weighted averaging.
 -   **ENHANCE**: Switch to deploying with PyPI's "Trusted Publisher".
 -   **ENHANCE**: Performance improvements for various algebraic calculations.
 -   **FIX**: Fix some corner cases with some algebraic calculations.

docs/src/markdown/average.md

@@ -1,51 +1,107 @@
 # Color Averaging
 
-Color averaging is the process of calculating an average color from a set of other colors by taking the mean of each
-color channel.
+Color averaging is the process taking multiple colors and calculating an average color from them, essentially mixing
+all the colors together. This involves looking at each color channel of all colors under consideration and averaging
+and averaging each channel independently. Additionally, by default, transparency is taken into account by using
+premultiplication which weights the colors such that more opaque colors have a greater significance in the mixing vs
+more translucent colors.
+
+![Average RGB](images/avg-rgb.png)
+
 
 Averaging under ColorAide can take as many colors as desired and will return a color that represents the average. This
-is not to be confused with interpolation which employs a different technique, but in certain situations, it can sort of
-function like mixing multiple colors.
+is not to be confused with interpolation which employs a different technique. One thing that sets it apart from
+interpolation is that when performing the operation, the order of the colors does not matter and will yield the same
+results even the colors are shuffled.
+
+Averaging can be used as a way to mix multiple colors into one color or simply determine what the overall average color
+is from a set of colors. Results are subject to the geometry of the color space in which the average is performed.
 
 ## Rectangular Space Averaging
 
-ColorAide, by default, averages in rectangular color spaces, the default being Linear sRGB. If desired, other color
-spaces can be used, such as perceptually uniform spaces like Oklab.
+ColorAide, by default, averages in the rectangular Linear sRGB color spaces. If desired, other color spaces can be used.
+Results will vary due to the geometry of the color space being used.
 
 ```py play
 Color.average(['red', 'blue'])
 Color.average(['red', 'blue'], space='srgb')
 Color.average(['red', 'blue'], space='oklab')
 ```
 
-Averaging is not restricted to any certain amount of colors.
+Averaging can be applied to any amount of colors.
 
 ```py play
 Color.average(['red', 'yellow', 'orange', 'green'])
 ```
 
 ## Cylindrical Space Averaging
 
-ColorAide can average colors in rectangular spaces and cylindrical spaces. When applying averaging in a cylindrical
-space, hues will be averaged taking the circular mean.
-
-Colors that appear to be achromatic will have their hue treated as undefined, even if the hue is defined.
-
-Cylindrical averaging may provide very different results that averaging in rectangular spaces.
+ColorAide can also average colors in cylindrical spaces. When applying averaging in a cylindrical space, hues will be
+averaged taking the circular mean. Due the difference in approach, colors can be quite different.
 
 ```py play
 Color.average(['purple', 'green', 'blue'])
 Color.average(['purple', 'green', 'blue'], space='hsl')
 ```
 
-It should be noted that when averaging colors with hues which are evenly distributed around the color wheel, the result
+Colors that are deemed achromatic will have their hue treated as undefined, even if the hue is defined. This is to
+ensure that the average color makes sense and isn't tainted by a non-functional hue.
+
+```py play
+Color.average(['white', 'blue'], space='hsl')
+```
+
+It should be noted that when averaging colors with hues which are evenly distributed around color space, the result
 will produce an achromatic hue. When achromatic hues are produced during circular mean, the color will discard
 chroma/saturation information, producing an achromatic color.
 
 ```py play
 Color.average(['red', 'green', 'blue'], space='hsl')
 ```
 
+## Weighted Averaging
+
+To allow for greater control and nuance of mixing multiple colors, ColorAide allows weights to be defined to adjust how
+much a specific color is mixed relative to other colors.
+
+As an example, let's assume we wanted to mix `#!color orange` and `#!color red` but brighten it up with `#!color white`.
+More specifically, let's say we want 4 times the amount of white for every 1 part of the other colors. We can simply
+specify weights intuitively as `#!py [1, 1, 4]`.
+
+
+```py play
+Color.average(['orange', 'red', 'white'])
+Color.average(['orange', 'red', 'white'], [1, 1, 4])
+```
+
+![Weighted Average](images/avg-weighted.png)
+
+Regardless of how big or small the numbers are, they are scaled relative to the largest value, so internally,
+`#!py [1, 1, 4]` and `#!py [0.25, 0.25, 1]` are essentially the same.
+
+```py play
+Color.average(['orange', 'red', 'white'], [1, 1, 4])
+Color.average(['orange', 'red', 'white'], [0.25, 0.25, 1])
+```
+
+If more weights are provided that there are colors, the only the weights sufficient to satisfy the number of colors
+is consumed.
+
+```py play
+Color.average(['orange', 'red', 'white'], [1, 1, 4, 2, 1])
+```
+
+If more colors are provided than weights, colors without defined weights are assumed to be full weight.
+
+```py play
+Color.average(['orange', 'red', 'white'], [0, 1])
+```
+
+/// note
+It should be noted that negative weights are not allowed and will be clipped to zero, which treats the colors as if it
+is not included at all.
+///
+
 ## Averaging with Transparency
 
 ColorAide, by default, will account for transparency when averaging colors. Colors which are more transparent will have
@@ -59,11 +115,11 @@ for i in range(12):
     )
 ```
 
-There are cases where this approach of averaging may not be desired. It may be that color averaging is desired without
-considering transparency. If so, `premultiplied` can be disabled by setting it to `#!py False`. While the average of
-transparency is calculated, it can be discarded from the final result if desired.
+There are cases where this approach of averaging may not be desired and results are desired without considering
+transparency. If so, `premultiplied` can be disabled by setting it to `#!py False`. While the average of transparency is
+still calculated, it can be discarded from the final result if desired.
 
-It should be noted that when a color is fully transparent, its color components will be ignored, regardless of the
+It should also be noted that when a color is fully transparent, its color components will be ignored, regardless of the
 `premultiplied` parameter, as fully transparent colors provide no meaningful color information.
 
 ```py play
@@ -76,8 +132,10 @@ for i in range(12):
 
 ## Averaging with Undefined Values
 
-When averaging with undefined values, ColorAide will not consider the undefined values in the average. This is mainly
-provided for averaging cylindrical colors, particularly achromatic colors.
+When averaging with undefined values, ColorAide will not consider the undefined values in the average. In short, it
+will be treated as if there was no value contributing to the average. This is mainly provided for sane averaging of
+achromatic colors in cylindrical/polar color spaces. With that said, any channel that has manually specified a channel
+as undefined will be treated in this manner.
 
 ```py play
 Color.average(['white', 'color(srgb 0 0 1)'], space='hsl')
@@ -90,17 +148,17 @@ distort the average in a non-meaningful way.
 Color.average(['hsl(30 0 100)', 'hsl(240 100 50 / 1)'], space='hsl')
 ```
 
-While undefined logic is intended to handle achromatic hues, this logic will be applied to any channel. It should be
-noted that no attempt to carry forward the undefined values through conversion is made at this time. Conversions will
-remove any undefined status unless the channel is an achromatic hues.
+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
+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)'])
 ```
 
 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 the color is treated with full weight.
+unknown how to weight the color. Instead, a color with undefined transparency will be treated with full weight.
 
 ```py play
 Color.average(['darkgreen', f'color(srgb 0 0.50196 0 / none)', 'color(srgb 0 0 1)'])