day 1

Author: T-Dynamos

materialyoucolor/__init__.py

@@ -1,16 +1,25 @@
-from materialyoucolor.hct import Hct
 from materialyoucolor.hct.cam16 import Cam16
+from materialyoucolor.hct.hct import Hct
+from materialyoucolor.utils.color_utils import lstar_from_argb
 from materialyoucolor.utils.math_utils import (
-    sanitize_degrees_double,
     difference_degrees,
     rotation_direction,
+    sanitize_degrees_double,
 )
-from materialyoucolor.utils.color_utils import lstar_from_argb
 
 
 class Blend:
+    """
+    Functions for blending in HCT and CAM16.
+    """
+
     @staticmethod
     def harmonize(design_color: int, source_color: int) -> int:
+        """
+        Blend the design color's HCT hue towards the key color's HCT
+        hue, in a way that leaves the original color recognizable and
+        recognizably shifted towards the key color.
+        """
         from_hct = Hct.from_int(design_color)
         to_hct = Hct.from_int(source_color)
         difference_degrees_ = difference_degrees(from_hct.hue, to_hct.hue)
@@ -22,17 +31,24 @@ def harmonize(design_color: int, source_color: int) -> int:
         return Hct.from_hct(output_hue, from_hct.chroma, from_hct.tone).to_int()
 
     @staticmethod
-    def hct_hue(from_: int, to: int, amount: int) -> int:
-        ucs = Blend.cam16_ucs(from_, to, amount)
+    def hct_hue(from_argb: int, to_argb: int, amount: float) -> int:
+        """
+        Blends hue from one color into another. The chroma and tone of
+        the original color are maintained.
+        """
+        ucs = Blend.cam16_ucs(from_argb, to_argb, amount)
         ucs_cam = Cam16.from_int(ucs)
-        from_cam = Cam16.from_int(from_)
-        blended = Hct.from_hct(ucs_cam.hue, from_cam.chroma, lstar_from_argb(from_))
+        from_cam = Cam16.from_int(from_argb)
+        blended = Hct.from_hct(ucs_cam.hue, from_cam.chroma, lstar_from_argb(from_argb))
         return blended.to_int()
 
     @staticmethod
-    def cam16_ucs(from_: int, to: int, amount: float) -> int:
-        from_cam = Cam16.from_int(from_)
-        to_cam = Cam16.from_int(to)
+    def cam16_ucs(from_argb: int, to_argb: int, amount: float) -> int:
+        """
+        Blend in CAM16-UCS space.
+        """
+        from_cam = Cam16.from_int(from_argb)
+        to_cam = Cam16.from_int(to_argb)
         from_j = from_cam.jstar
         from_a = from_cam.astar
         from_b = from_cam.bstar

materialyoucolor/blend/__init__.py

@@ -1,5 +1,5 @@
+from materialyoucolor.utils.color_utils import lstar_from_y, y_from_lstar
 from materialyoucolor.utils.math_utils import clamp_double
-from materialyoucolor.utils.color_utils import y_from_lstar, lstar_from_y
 
 
 class Contrast:
@@ -11,7 +11,7 @@ def ratio_of_tones(tone_a: float, tone_b: float) -> float:
 
     @staticmethod
     def ratio_of_ys(y1: float, y2: float) -> float:
-        lighter = y1 if y1 > y2 else y2
+        lighter = max(y1, y2)
         darker = y1 if lighter == y2 else y2
         return (lighter + 5.0) / (darker + 5.0)
 
@@ -25,11 +25,12 @@ def lighter(tone: float, ratio: float) -> float:
         real_contrast = Contrast.ratio_of_ys(light_y, dark_y)
         delta = abs(real_contrast - ratio)
         if real_contrast < ratio and delta > 0.04:
-            return -1
+            return -1.0
 
         return_value = lstar_from_y(light_y) + 0.4
         if return_value < 0 or return_value > 100:
             return -1.0
+
         return return_value
 
     @staticmethod
@@ -38,24 +39,25 @@ def darker(tone: float, ratio: float) -> float:
             return -1.0
 
         light_y = y_from_lstar(tone)
-        dark_y = (light_y + 5.0) / ratio - 5.0
+        dark_y = ((light_y + 5.0) / ratio) - 5.0
         real_contrast = Contrast.ratio_of_ys(light_y, dark_y)
 
         delta = abs(real_contrast - ratio)
         if real_contrast < ratio and delta > 0.04:
-            return -1
+            return -1.0
 
         return_value = lstar_from_y(dark_y) - 0.4
-        if return_value < 0 or return_value > 100:
-            return -1
+        if return_value < 0.0 or return_value > 100.0:
+            return -1.0
+
         return return_value
 
     @staticmethod
-    def lighter_unsafe(tone, ratio):
+    def lighter_unsafe(tone: float, ratio: float) -> float:
         lighter_safe = Contrast.lighter(tone, ratio)
         return 100.0 if lighter_safe < 0.0 else lighter_safe
 
     @staticmethod
-    def darker_unsafe(tone, ratio):
+    def darker_unsafe(tone: float, ratio: float) -> float:
         darker_safe = Contrast.darker(tone, ratio)
         return 0.0 if darker_safe < 0.0 else darker_safe

materialyoucolor/blend/blend.py

@@ -1,16 +1,41 @@
-from materialyoucolor.hct import Hct
+from materialyoucolor.hct.hct import Hct
 
 
 class DislikeAnalyzer:
+    """
+    Check and/or fix universally disliked colors.
+    Color science studies of color preference indicate universal distaste for
+    dark yellow-greens, and also show this is correlated to distate for
+    biological waste and rotting food.
+
+    See Palmer and Schloss, 2010 or Schloss and Palmer's Chapter 21 in Handbook
+    of Color Psychology (2015).
+    """
+
     @staticmethod
     def is_disliked(hct: Hct) -> bool:
+        """
+        Returns true if a color is disliked.
+
+        :param hct: A color to be judged.
+        :return: Whether the color is disliked.
+
+        Disliked is defined as a dark yellow-green that is not neutral.
+        """
         hue_passes = round(hct.hue) >= 90.0 and round(hct.hue) <= 111.0
         chroma_passes = round(hct.chroma) > 16.0
         tone_passes = round(hct.tone) < 65.0
         return hue_passes and chroma_passes and tone_passes
 
     @staticmethod
     def fix_if_disliked(hct: Hct) -> Hct:
+        """
+        If a color is disliked, lighten it to make it likable.
+
+        :param hct: A color to be judged.
+        :return: A new color if the original color is disliked, or the original
+          color if it is acceptable.
+        """
         if DislikeAnalyzer.is_disliked(hct):
             return Hct.from_hct(
                 hct.hue,