contrast_ratio() in pymatviz/utils/plotting.py to calculate color contrast according to WCAG 2.0

fix text color contrast for dark elements in pmv.structure_(2|3)d_plotly
this required adjusting the `pick_max_contrast_color` function to use a lower contrast threshold (2.0 instead of 2.5) to ensure dark-colored elements like Nickel and Barium get white text labels for better visibility

also fix the color comments in the ALLOY color scheme to accurately reflect the actual RGB values
minor cleanup in structure_viz/plotly.py

Author: janosh

assets/scripts/structure_viz/structure_3d_plotly.py

@@ -58,7 +58,7 @@
 title = "CoCrFeNiMn High-Entropy Alloy"
 fig.layout.title = title
 fig.show()
-pmv.io.save_and_compress_svg(fig, "hea-structure-3d-plotly")
+# pmv.io.save_and_compress_svg(fig, "hea-structure-3d-plotly")
 
 
 # %% Li-ion battery cathode material with Li vacancies: Li0.8CoO2
@@ -78,4 +78,4 @@
 title = "Li0.8CoO2 with Li Vacancies"
 fig.layout.title = title
 fig.show()
-pmv.io.save_and_compress_svg(fig, "lco-structure-3d-plotly")
+# pmv.io.save_and_compress_svg(fig, "lco-structure-3d-plotly")

pymatviz/colors.py

@@ -273,47 +273,47 @@
 # overriding metal colors.
 ELEM_COLORS_ALLOY_256: dict[str, Rgb256ColorType] = ELEM_COLORS_VESTA_256 | {
     # Alkali metals - bright purples
-    "Li": (0, 53, 0),  # Bright purple
-    "Na": (0, 41, 255),  # Deep purple
-    "K": (0, 255, 0),  # Royal purple
-    "Rb": (0, 255, 255),  # Dark purple
-    "Cs": (255, 0, 0),  # Deep violet
+    "Li": (0, 53, 0),  # Dark green
+    "Na": (0, 41, 255),  # Deep blue
+    "K": (0, 255, 0),  # Bright green
+    "Rb": (0, 255, 255),  # Cyan
+    "Cs": (255, 0, 0),  # Bright red
     # Alkaline earth metals - yellows/oranges
-    "Be": (255, 0, 255),  # Golden yellow
-    "Mg": (255, 255, 0),  # Dark orange
-    "Ca": (255, 255, 255),  # Bright orange
-    "Sr": (38, 154, 0),  # Red-orange
-    "Ba": (0, 150, 255),  # Pure red
+    "Be": (255, 0, 255),  # Magenta
+    "Mg": (255, 255, 0),  # Yellow
+    "Ca": (255, 255, 255),  # White
+    "Sr": (38, 154, 0),  # Green
+    "Ba": (0, 150, 255),  # Blue
     # Transition metals - maximizing contrast
-    "Sc": (207, 26, 128),  # Light gray (from JMOL)
-    "Ti": (216, 219, 127),  # Purple (changed from blue for more contrast with Zr)
-    "V": (255, 150, 0),  # Pink
-    "Cr": (197, 163, 255),  # Bright green
-    "Mn": (0, 46, 133),  # Magenta
-    "Fe": (0, 151, 134),  # Bright orange (changed from JMOL)
-    "Co": (0, 255, 121),  # Deep blue
-    "Ni": (99, 0, 62),  # Orange (changed from green for contrast with Zr)
-    "Cu": (129, 0, 255),  # Brown (changed from JMOL)
-    "Zn": (168, 74, 0),  # Light blue
-    "Zr": (108, 96, 208),  # Cyan (kept)
-    "Nb": (134, 228, 15),  # Purple (new)
+    "Sc": (207, 26, 128),  # Pink
+    "Ti": (216, 219, 127),  # Light yellow-green
+    "V": (255, 150, 0),  # Orange
+    "Cr": (197, 163, 255),  # Light purple
+    "Mn": (0, 46, 133),  # Dark blue
+    "Fe": (0, 151, 134),  # Teal
+    "Co": (0, 255, 121),  # Bright green
+    "Ni": (99, 0, 62),  # Dark red/burgundy
+    "Cu": (129, 0, 255),  # Purple
+    "Zn": (168, 74, 0),  # Brown
+    "Zr": (108, 96, 208),  # Medium blue-purple
+    "Nb": (134, 228, 15),  # Lime green
     # Post-transition metals - earth tones
-    "Al": (102, 211, 188),  # Gray (from JMOL)
-    "Ga": (255, 121, 143),  # Rose
-    "In": (131, 143, 93),  # Dusty rose
-    "Sn": (197, 163, 255),  # Dark orange (changed from blue-gray for contrast with Zr)
-    "Tl": (0, 46, 133),  # Terra cotta
-    "Pb": (0, 151, 134),  # Dark gray
-    "Bi": (0, 255, 121),  # Purple
+    "Al": (102, 211, 188),  # Light teal
+    "Ga": (255, 121, 143),  # Pink
+    "In": (131, 143, 93),  # Olive green
+    "Sn": (197, 163, 255),  # Light purple
+    "Tl": (0, 46, 133),  # Dark blue
+    "Pb": (0, 151, 134),  # Teal
+    "Bi": (0, 255, 121),  # Bright green
     # Noble metals - preserving traditional colors
-    "Ru": (99, 0, 62),  # Teal
-    "Rh": (129, 0, 255),  # Hot pink
-    "Pd": (168, 74, 0),  # Blue (from JMOL)
-    "Ag": (108, 96, 208),  # Silver (from JMOL)
-    "Os": (134, 228, 15),  # Blue (from JMOL)
-    "Ir": (102, 211, 188),  # Dark blue (from JMOL)
-    "Pt": (255, 121, 143),  # Light gray (from JMOL)
-    "Au": (131, 143, 93),  # Gold (from JMOL)
+    "Ru": (99, 0, 62),  # Dark red/burgundy
+    "Rh": (129, 0, 255),  # Purple
+    "Pd": (168, 74, 0),  # Brown
+    "Ag": (108, 96, 208),  # Medium blue-purple
+    "Os": (134, 228, 15),  # Lime green
+    "Ir": (102, 211, 188),  # Light teal
+    "Pt": (255, 121, 143),  # Pink
+    "Au": (131, 143, 93),  # Olive green
 }
 
 ELEM_COLORS_ALLOY: dict[str, RgbColorType] = {

pymatviz/structure_viz/helpers.py

@@ -14,7 +14,8 @@
 
 from pymatviz.colors import ELEM_COLORS_ALLOY, ELEM_COLORS_JMOL, ELEM_COLORS_VESTA
 from pymatviz.enums import ElemColorScheme, Key, SiteCoords
-from pymatviz.utils import df_ptable, pick_max_contrast_color
+from pymatviz.utils import df_ptable
+from pymatviz.utils.plotting import pick_max_contrast_color
 
 
 if TYPE_CHECKING:
@@ -305,12 +306,15 @@ def draw_site(
     txt = generate_site_label(site_labels, site_idx, majority_species)
 
     marker = dict(
-        size=site_radius * atom_size * (0.8 if is_image else 1),
+        size=site_radius * atom_size,
         color=color,
-        opacity=0.5 if is_image else 1,
+        opacity=0.8 if is_image else 1,
+        line=dict(width=1, color="gray"),
     )
     marker.update(site_kwargs)
 
+    # Calculate text color based on background color for maximum contrast
+    text_color = pick_max_contrast_color(color)
     scatter_kwargs = dict(
         x=[coords[0]],
         y=[coords[1]],
@@ -319,7 +323,7 @@ def draw_site(
         text=txt,
         textposition="middle center",
         textfont=dict(
-            color=pick_max_contrast_color(color),
+            color=text_color,
             size=np.clip(atom_size * site_radius * (0.8 if is_image else 1), 10, 18),
         ),
         hoverinfo="text" if hover_text else None,

pymatviz/structure_viz/plotly.py

@@ -204,10 +204,6 @@ def structure_2d_plotly(
 
         # Plot atoms and vectors
         if show_sites:
-            site_kwargs = dict(line=dict(width=0.3, color="gray"))
-            if isinstance(show_sites, dict):
-                site_kwargs |= show_sites
-
             for site_idx, (site, coords) in enumerate(
                 zip(struct_i, rotated_coords, strict=False)
             ):
@@ -221,7 +217,7 @@ def structure_2d_plotly(
                     _atomic_radii,
                     atom_size,
                     scale,
-                    site_kwargs,
+                    {} if show_sites is True else show_sites,
                     is_3d=False,
                     row=row,
                     col=col,
@@ -251,17 +247,6 @@ def structure_2d_plotly(
 
                 # Add image sites
                 if show_image_sites:
-                    image_site_kwargs = dict(
-                        size=_atomic_radii[site.species.elements[0].symbol]
-                        * scale
-                        * atom_size
-                        * 0.8,
-                        color=_elem_colors.get(site.species.elements[0].symbol, "gray"),
-                        opacity=0.5,
-                    )
-                    if isinstance(show_image_sites, dict):
-                        image_site_kwargs |= show_image_sites
-
                     image_atoms = get_image_sites(site, struct_i.lattice)
                     if len(image_atoms) > 0:
                         rotated_image_atoms = np.dot(image_atoms, rotation_matrix)
@@ -277,7 +262,7 @@ def structure_2d_plotly(
                                 _atomic_radii,
                                 atom_size,
                                 scale,
-                                image_site_kwargs,
+                                {} if show_image_sites is True else show_image_sites,
                                 is_image=True,
                                 is_3d=False,
                                 row=row,
@@ -289,9 +274,7 @@ def structure_2d_plotly(
             draw_unit_cell(
                 fig,
                 struct_i,
-                unit_cell_kwargs=show_unit_cell
-                if isinstance(show_unit_cell, dict)
-                else {},
+                unit_cell_kwargs={} if show_unit_cell is True else show_unit_cell,
                 is_3d=False,
                 row=row,
                 col=col,
@@ -484,10 +467,6 @@ def structure_3d_plotly(
 
         # Plot atoms and vectors
         if show_sites:
-            site_kwargs = dict(line=dict(width=0.3, color="gray"))
-            if isinstance(show_sites, dict):
-                site_kwargs |= show_sites
-
             for site_idx, site in enumerate(struct_i):
                 draw_site(
                     fig,
@@ -499,7 +478,7 @@ def structure_3d_plotly(
                     _atomic_radii,
                     atom_size,
                     scale,
-                    site_kwargs,
+                    {} if show_sites is True else show_sites,
                     is_3d=True,
                     scene=f"scene{idx}",
                     name=f"site{site_idx}",
@@ -527,17 +506,6 @@ def structure_3d_plotly(
 
                 # Add image sites
                 if show_image_sites:
-                    image_site_kwargs = dict(
-                        size=_atomic_radii[site.species.elements[0].symbol]
-                        * scale
-                        * atom_size
-                        * 0.8,
-                        color=_elem_colors.get(site.species.elements[0].symbol, "gray"),
-                        opacity=0.5,
-                    )
-                    if isinstance(show_image_sites, dict):
-                        image_site_kwargs |= show_image_sites
-
                     image_atoms = get_image_sites(site, struct_i.lattice)
                     if len(image_atoms) > 0:
                         for image_coords in image_atoms:
@@ -551,7 +519,7 @@ def structure_3d_plotly(
                                 _atomic_radii,
                                 atom_size,
                                 scale,
-                                image_site_kwargs,
+                                {} if show_image_sites is True else show_image_sites,
                                 is_image=True,
                                 is_3d=True,
                                 scene=f"scene{idx}",
@@ -562,9 +530,7 @@ def structure_3d_plotly(
             draw_unit_cell(
                 fig,
                 struct_i,
-                unit_cell_kwargs=show_unit_cell
-                if isinstance(show_unit_cell, dict)
-                else {},
+                unit_cell_kwargs={} if show_unit_cell is True else show_unit_cell,
                 is_3d=True,
                 scene=f"scene{idx}",
             )

pymatviz/utils/plotting.py

@@ -203,8 +203,8 @@ def luminance(color: ColorType) -> float:
     """Compute the relative luminance of a color using the WCAG 2.0 formula.
 
     Args:
-        color (ColorType): RGB color tuple with values in [0, 1] or a color string
-            that can be converted to RGB.
+        color (ColorType): RGB color tuple with values in [0, 1] or [0, 255], or a color
+            string that can be converted to RGB.
 
     Returns:
         float: Relative luminance of the color in range [0, 1].
@@ -213,36 +213,84 @@ def luminance(color: ColorType) -> float:
         r, g, b, *_a = map(float, color.strip("rgb()").split(","))
         if r > 1 or g > 1 or b > 1:
             r, g, b = r / 255, g / 255, b / 255
+    elif isinstance(color, tuple) and len(color) >= 3:
+        # Check if any value is > 1, indicating 0-255 range
+        if any(c > 1 for c in color[:3]):
+            r, g, b = color[0] / 255, color[1] / 255, color[2] / 255
+        else:
+            r, g, b = color[:3]
     else:
         # raises ValueError if color invalid
         r, g, b, *_a = matplotlib.colors.to_rgba(color)
 
+    def _convert_rgb_to_linear(rgb: float) -> float:
+        """Convert an RGB value to linear RGB (remove gamma correction)."""
+        return rgb / 12.92 if rgb <= 0.03928 else ((rgb + 0.055) / 1.055) ** 2.4
+
+    # Convert RGB to linear RGB (remove gamma correction)
+    r, g, b = map(_convert_rgb_to_linear, (r, g, b))
+
     # Calculate relative luminance using WCAG 2.0 coefficients
     return 0.2126 * r + 0.7152 * g + 0.0722 * b
 
 
+def contrast_ratio(color1: ColorType, color2: ColorType) -> float:
+    """Calculate the contrast ratio between two colors according to WCAG 2.0.
+
+    Args:
+        color1 (ColorType): First color (RGB tuple with values in [0, 1] or [0, 255],
+            or a color string that can be converted to RGB).
+        color2 (ColorType): Second color (RGB tuple with values in [0, 1] or [0, 255],
+            or a color string that can be converted to RGB).
+
+    Returns:
+        float: Contrast ratio between the two colors, ranging from 1:1 to 21:1.
+    """
+    lum1 = luminance(color1)
+    lum2 = luminance(color2)
+
+    # Ensure lighter color is first for the formula
+    lighter = max(lum1, lum2)
+    darker = min(lum1, lum2)
+
+    # Calculate contrast ratio: (L1 + 0.05) / (L2 + 0.05)
+    return (lighter + 0.05) / (darker + 0.05)
+
+
 def pick_max_contrast_color(
     bg_color: ColorType,
-    luminance_threshold: float = 0.3,  # Threshold for light/dark color distinction
     colors: tuple[ColorType, ColorType] = ("white", "black"),
+    min_contrast_ratio: float = 2.0,  # Lower threshold makes dark colors get white text
 ) -> ColorType:
-    """Choose dark or light text color for a given background color based on WCAG 2.0.
+    """Choose text color for a given background color based on WCAG 2.0 contrast ratio.
+
+    This function calculates the contrast ratio between the background color and each
+    of the provided text colors, then returns the color with the highest contrast ratio.
+    If the contrast ratio with white is above the minimum contrast ratio, white will be
+    chosen even if black has a slightly higher contrast ratio. This ensures that darker
+    colors always get white text, which is often more readable in 3D visualizations.
 
     Args:
         bg_color (ColorType): Background color.
-        luminance_threshold (float, optional): Luminance threshold for choosing text
-            color. Defaults to 0.5 to distinguish between light and dark colors.
-        colors (tuple[ColorType, ColorType], optional): One light and one dark text
-            color to choose from in that order. Defaults to ("white", "black").
+        colors (tuple[ColorType, ColorType], optional): Text colors to choose
+            from. Defaults to ("white", "black").
+        min_contrast_ratio (float, optional): Minimum contrast ratio to prefer white
+            over black text. Defaults to 2.0 (lower than WCAG AA standard to ensure
+            dark colors get white text).
 
     Returns:
-        ColorType: The color that provides better contrast, usually "black" or "white".
+        ColorType: item in `colors` that provides the best contrast with bg_color.
     """
-    # Calculate luminance of the background color
-    bg_luminance = luminance(bg_color)
+    # Calculate contrast ratios for each potential text color
+    contrast_ratios = [contrast_ratio(bg_color, color) for color in colors]
+
+    # If the contrast ratio with white is above the minimum contrast ratio,
+    # prefer white text even if black has a slightly higher contrast ratio
+    if contrast_ratios[0] >= min_contrast_ratio:
+        return colors[0]
 
-    # Use black text on light colors (luminance > threshold)
-    return colors[1] if bg_luminance > luminance_threshold else colors[0]
+    # Otherwise, return the color with the highest contrast ratio
+    return colors[contrast_ratios.index(max(contrast_ratios))]
 
 
 def pretty_label(key: str, backend: Backend) -> str: