Introduce seed in random_color method to produce colors deterministically (#4265)

* add a random generator to hold the seed for random generation

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* add DOCSTRING for new class RandomColorGenerator

* fix RandomColorGenerator doctest

* introduce the sample colors param in RandomColorGenerator

* Update docstrings to include sample_colors param for RandomColorGenerator

* fix cyclic import issues

* fix indentations for code blocks

* docstring formatting changes

* removed performance warning
added class method

---------

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Co-authored-by: Benjamin Hackl <[email protected]>

Author: 3 people

manim/utils/color/core.py

@@ -1501,17 +1501,124 @@ def random_bright_color() -> ManimColor:
 def random_color() -> ManimColor:
     """Return a random :class:`ManimColor`.
 
-    .. warning::
-        This operation is very expensive. Please keep in mind the performance loss.
-
     Returns
     -------
     ManimColor
         A random :class:`ManimColor`.
     """
-    import manim.utils.color.manim_colors as manim_colors
+    return RandomColorGenerator._random_color()
+
+
+class RandomColorGenerator:
+    _singleton: RandomColorGenerator | None = None
+    """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 :class:`.ManimColor` instances. If no seed is provided, the selection is
+    non-deterministic using Python’s global random state.
+
+    Parameters
+    ----------
+    seed
+        A seed value to initialize the internal random number generator.
+        If ``None`` (the default), colors are chosen using the global random state.
+
+    sample_colors
+        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')
+    """
+
+    def __init__(
+        self,
+        seed: int | None = None,
+        sample_colors: list[ManimColor] | None = None,
+    ) -> None:
+        self.choice = random.choice if seed is None else random.Random(seed).choice
+
+        from manim.utils.color.manim_colors import _all_manim_colors
 
-    return random.choice(manim_colors._all_manim_colors)
+        self.colors = _all_manim_colors if sample_colors is None else 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
+        --------
+        Usage::
+
+            >>> from manim import RandomColorGenerator, RED
+            >>> rnd = RandomColorGenerator(sample_colors=[RED])
+            >>> rnd.next()
+            ManimColor('#FC6255')
+        """
+        return self.choice(self.colors)
+
+    @classmethod
+    def _random_color(cls) -> ManimColor:
+        """Internal method to generate a random color using the singleton instance of
+        `RandomColorGenerator`.
+        It will be used by proxy method `random_color` publicly available
+        and makes it backwards compatible.
+
+        Returns
+        -------
+        ManimColor:
+            A randomly selected color from the configured color list of
+            the singleton instance.
+        """
+        if cls._singleton is None:
+            cls._singleton = cls()
+        return cls._singleton.next()
 
 
 def get_shaded_rgb(
@@ -1567,6 +1674,7 @@ def get_shaded_rgb(
     "average_color",
     "random_bright_color",
     "random_color",
+    "RandomColorGenerator",
     "get_shaded_rgb",
     "HSV",
     "RGBA",