Introduce seed in random_color method to produce colors deterministically

manim/utils/color/core.py

@@ -1508,9 +1508,94 @@
     ManimColor
         A random :class:`ManimColor`.
     """
+    return RandomColorGenerator().next()
+
+
+class RandomColorGenerator:
+    """
+    A generator for producing random colors from a given list of Manim colors,
+    optionally in a reproducible sequence using a seed value.
+
+    When initialized with a specific seed, this class produces a deterministic
+    sequence of `ManimColor` instances. If no seed is provided, the selection is
+    non-deterministic using Python’s global random state.
+
+    Parameters
+    ----------
+    seed : int | None, optional
+        A seed value to initialize the internal random number generator.
+        If None (default), colors are chosen using the global random state.
+
+    sample_colors : list[ManimColor], optional
+        A custom list of Manim colors to sample from. Defaults to the full Manim color palette.
+
+    Examples
+    --------
+    Without a seed (non-deterministic):
+    >>> from manim import RandomColorGenerator, ManimColor, RED, GREEN, BLUE
+    >>> rnd = RandomColorGenerator()
+    >>> isinstance(rnd.next(), ManimColor)
+    True
+
+    With a seed (deterministic sequence):
+    >>> rnd = RandomColorGenerator(42)
+    >>> rnd.next()
+    ManimColor('#ECE7E2')
+    >>> rnd.next()
+    ManimColor('#BBBBBB')
+    >>> rnd.next()
+    ManimColor('#BBBBBB')
+
+    Re-initializing with the same seed gives the same sequence:
+    >>> rnd2 = RandomColorGenerator(42)
+    >>> rnd2.next()
+    ManimColor('#ECE7E2')
+    >>> rnd2.next()
+    ManimColor('#BBBBBB')
+    >>> rnd2.next()
+    ManimColor('#BBBBBB')
+
+    Using a custom color list:
+    >>> custom_palette = [RED, GREEN, BLUE]
+    >>> rnd_custom = RandomColorGenerator(1, sample_colors=custom_palette)
+    >>> rnd_custom.next() in custom_palette
+    True
+    >>> rnd_custom.next() in custom_palette
+    True
+
+    Without a seed and custom palette (non-deterministic):
+    >>> rnd_nodet = RandomColorGenerator(sample_colors=[RED])
+    >>> rnd_nodet.next()
+    ManimColor('#FC6255')
+    """
+
     import manim.utils.color.manim_colors as manim_colors
 
-    return random.choice(manim_colors._all_manim_colors)
+    def __init__(
+        self,
+        seed: int | None = None,
+        sample_colors: list[ManimColor] = manim_colors._all_manim_colors,
+    ) -> None:
+        self.choice = random.choice if seed is None else random.Random(seed).choice
+        self.colors = sample_colors
+
+    def next(self) -> ManimColor:
+        """
+        Returns the next color from the configured color list.
+
+        Returns
+        -------
+        ManimColor
+            A randomly selected color from the specified color list.
+
+        Examples
+        --------
+        >>> from manim import RandomColorGenerator, RED
+        >>> rnd = RandomColorGenerator(sample_colors=[RED])
+        >>> rnd.next()
+        ManimColor('#FC6255')
+        """
+        return self.choice(self.colors)
 
 
 def get_shaded_rgb(
@@ -1566,6 +1651,7 @@
     "average_color",
     "random_bright_color",
     "random_color",
+    "RandomColorGenerator",
     "get_shaded_rgb",
     "HSV",
     "RGBA",