manim 0.18.0.post0__py3-none-any.whl → 0.19.0__py3-none-any.whl

manim/utils/color/core.py

@@ -1,10 +1,9 @@
-"""Manim's (internal) color data structure and some utilities for
-color conversion.
+"""Manim's (internal) color data structure and some utilities for color conversion.
 
-This module contains the implementation of :class:`.ManimColor`,
-the data structure internally used to represent colors.
+This module contains the implementation of :class:`.ManimColor`, the data structure
+internally used to represent colors.
 
-The preferred way of using these colors is by importing their constants from manim:
+The preferred way of using these colors is by importing their constants from Manim:
 
 .. code-block:: pycon
 
@@ -12,12 +11,54 @@ The preferred way of using these colors is by importing their constants from man
     >>> print(RED)
     #FC6255
 
-Note this way uses the name of the colors in UPPERCASE.
+Note that this way uses the name of the colors in UPPERCASE.
 
 .. note::
 
-    The colors of type "C" have an alias equal to the colorname without a letter,
-    e.g. GREEN = GREEN_C
+    The colors with a ``_C`` suffix have an alias equal to the colorname without a
+    letter. For example, ``GREEN = GREEN_C``.
+
+===================
+Custom Color Spaces
+===================
+
+Hello, dear visitor. You seem to be interested in implementing a custom color class for
+a color space we don't currently support.
+
+The current system is using a few indirections for ensuring a consistent behavior with
+all other color types in Manim.
+
+To implement a custom color space, you must subclass :class:`ManimColor` and implement
+three important methods:
+
+  - :attr:`~.ManimColor._internal_value`: a ``@property`` implemented on
+    :class:`ManimColor` with the goal of keeping a consistent internal representation
+    which can be referenced by other functions in :class:`ManimColor`. This property acts
+    as a proxy to whatever representation you need in your class.
+
+      - The getter should always return a NumPy array in the format ``[r,g,b,a]``, in
+        accordance with the type :class:`ManimColorInternal`.
+
+      - The setter should always accept a value in the format ``[r,g,b,a]`` which can be
+        converted to whatever attributes you need.
+
+  - :attr:`~ManimColor._internal_space`: a read-only ``@property`` implemented on
+    :class:`ManimColor` with the goal of providing a useful representation which can be
+    used by operators, interpolation and color transform functions.
+
+    The only constraints on this value are:
+
+      - It must be a NumPy array.
+
+      - The last value must be the opacity in a range ``0.0`` to ``1.0``.
+
+    Additionally, your ``__init__`` must support this format as an initialization value
+    without additional parameters to ensure correct functionality of all other methods in
+    :class:`ManimColor`.
+
+  - :meth:`~ManimColor._from_internal`: a ``@classmethod`` which converts an
+    ``[r,g,b,a]`` value into suitable parameters for your ``__init__`` method and calls
+    the ``cls`` parameter.
 """
 
 from __future__ import annotations
@@ -27,17 +68,24 @@ import colorsys
 # logger = _config.logger
 import random
 import re
-from typing import Any, Sequence, TypeVar, Union, overload
+from collections.abc import Sequence
+from typing import TypeVar, Union, overload
 
 import numpy as np
 import numpy.typing as npt
-from typing_extensions import Self, TypeAlias
+from typing_extensions import Self, TypeAlias, TypeIs, override
 
 from manim.typing import (
+    HSL_Array_Float,
+    HSL_Tuple_Float,
     HSV_Array_Float,
     HSV_Tuple_Float,
+    HSVA_Array_Float,
+    HSVA_Tuple_Float,
     ManimColorDType,
     ManimColorInternal,
+    ManimFloat,
+    Point3D,
     RGB_Array_Float,
     RGB_Array_Int,
     RGB_Tuple_Float,
@@ -46,48 +94,66 @@ from manim.typing import (
     RGBA_Array_Int,
     RGBA_Tuple_Float,
     RGBA_Tuple_Int,
+    Vector3D,
 )
 
 from ...utils.space_ops import normalize
 
 # import manim._config as _config
 
-
-re_hex = re.compile("((?<=#)|(?<=0x))[A-F0-9]{6,8}", re.IGNORECASE)
+re_hex = re.compile("((?<=#)|(?<=0x))[A-F0-9]{3,8}", re.IGNORECASE)
 
 
 class ManimColor:
     """Internal representation of a color.
 
-    The ManimColor class is the main class for the representation of a color.
-    It's internal representation is a 4 element array of floats corresponding
-    to a [r,g,b,a] value where r,g,b,a can be between 0 to 1.
+    The :class:`ManimColor` class is the main class for the representation of a color.
+    Its internal representation is an array of 4 floats corresponding to a ``[r,g,b,a]``
+    value where ``r,g,b,a`` can be between 0.0 and 1.0.
 
-    This is done in order to reduce the amount of color inconsitencies by constantly
+    This is done in order to reduce the amount of color inconsistencies by constantly
     casting between integers and floats which introduces errors.
 
     The class can accept any value of type :class:`ParsableManimColor` i.e.
 
-    ManimColor, int, str, RGB_Tuple_Int, RGB_Tuple_Float, RGBA_Tuple_Int, RGBA_Tuple_Float, RGB_Array_Int,
-    RGB_Array_Float, RGBA_Array_Int, RGBA_Array_Float
+    ``ManimColor, int, str, RGB_Tuple_Int, RGB_Tuple_Float, RGBA_Tuple_Int, RGBA_Tuple_Float, RGB_Array_Int,
+    RGB_Array_Float, RGBA_Array_Int, RGBA_Array_Float``
 
-    ManimColor itself only accepts singular values and will directly interpret them into a single color if possible
-    Be careful when passing strings to ManimColor it can create a big overhead for the color processing.
+    :class:`ManimColor` itself only accepts singular values and will directly interpret
+    them into a single color if possible. Be careful when passing strings to
+    :class:`ManimColor`: it can create a big overhead for the color processing.
 
-    If you want to parse a list of colors use the function :meth:`parse` in :class:`ManimColor` which assumes that
-    you are going to pass a list of color so arrays will not bei interpreted as a single color.
+    If you want to parse a list of colors, use the :meth:`parse` method, which assumes
+    that you're going to pass a list of colors so that arrays will not be interpreted as
+    a single color.
 
     .. warning::
-        If you pass an array of numbers to :meth:`parse` it will interpret the r,g,b,a numbers in that array as colors
-        so instead of the expect singular color you get and array with 4 colors.
+        If you pass an array of numbers to :meth:`parse`, it will interpret the
+        ``r,g,b,a`` numbers in that array as colors: Instead of the expected
+        singular color, you will get an array with 4 colors.
+
+    For conversion behaviors, see the ``_internal`` functions for further documentation.
+
+    You can create a :class:`ManimColor` instance via its classmethods. See the
+    respective methods for more info.
 
-    For conversion behaviors see the _internal functions for further documentation
+    .. code-block:: python
+
+        mycolor = ManimColor.from_rgb((0, 1, 0.4, 0.5))
+        myothercolor = ManimColor.from_rgb((153, 255, 255))
+
+    You can also convert between different color spaces:
+
+    .. code-block:: python
+
+        mycolor_hex = mycolor.to_hex()
+        myoriginalcolor = ManimColor.from_hex(mycolor_hex).to_hsv()
 
     Parameters
     ----------
     value
         Some representation of a color (e.g., a string or
-        a suitable tuple).
+        a suitable tuple). The default ``None`` is ``BLACK``.
     alpha
         The opacity of the color. By default, colors are
         fully opaque (value 1.0).
@@ -118,14 +184,14 @@ class ManimColor:
                 # This is not expected to be called on module initialization time
                 # It can be horribly slow to convert a string to a color because
                 # it has to access the dictionary of colors and find the right color
-                self._internal_value = ManimColor._internal_from_string(value)
+                self._internal_value = ManimColor._internal_from_string(value, alpha)
         elif isinstance(value, (list, tuple, np.ndarray)):
             length = len(value)
             if all(isinstance(x, float) for x in value):
                 if length == 3:
-                    self._internal_value = ManimColor._internal_from_rgb(value, alpha)  # type: ignore
+                    self._internal_value = ManimColor._internal_from_rgb(value, alpha)  # type: ignore[arg-type]
                 elif length == 4:
-                    self._internal_value = ManimColor._internal_from_rgba(value)  # type: ignore
+                    self._internal_value = ManimColor._internal_from_rgba(value)  # type: ignore[arg-type]
                 else:
                     raise ValueError(
                         f"ManimColor only accepts lists/tuples/arrays of length 3 or 4, not {length}"
@@ -133,10 +199,11 @@ class ManimColor:
             else:
                 if length == 3:
                     self._internal_value = ManimColor._internal_from_int_rgb(
-                        value, alpha  # type: ignore
+                        value,  # type: ignore[arg-type]
+                        alpha,
                     )
                 elif length == 4:
-                    self._internal_value = ManimColor._internal_from_int_rgba(value)  # type: ignore
+                    self._internal_value = ManimColor._internal_from_int_rgba(value)  # type: ignore[arg-type]
                 else:
                     raise ValueError(
                         f"ManimColor only accepts lists/tuples/arrays of length 3 or 4, not {length}"
@@ -145,7 +212,6 @@ class ManimColor:
             result = re_hex.search(value.get_hex())
             if result is None:
                 raise ValueError(f"Failed to parse a color from {value}")
-
             self._internal_value = ManimColor._internal_from_hex_string(
                 result.group(), alpha
             )
@@ -157,37 +223,59 @@ class ManimColor:
                 f"list[float, float, float, float], not {type(value)}"
             )
 
+    @property
+    def _internal_space(self) -> npt.NDArray[ManimFloat]:
+        """This is a readonly property which is a custom representation for color space
+        operations. It is used for operators and can be used when implementing a custom
+        color space.
+        """
+        return self._internal_value
+
     @property
     def _internal_value(self) -> ManimColorInternal:
-        """Returns the internal value of the current Manim color [r,g,b,a] float array
+        """Return the internal value of the current Manim color ``[r,g,b,a]`` float
+        array.
 
         Returns
         -------
         ManimColorInternal
-            internal color representation
+            Internal color representation.
         """
         return self.__value
 
     @_internal_value.setter
     def _internal_value(self, value: ManimColorInternal) -> None:
-        """Overwrites the internal color value of the ManimColor object
+        """Overwrite the internal color value of this :class:`ManimColor`.
 
         Parameters
         ----------
-        value : ManimColorInternal
-            The value which will overwrite the current color
+        value
+            The value which will overwrite the current color.
 
         Raises
         ------
         TypeError
-            Raises a TypeError if an invalid array is passed
+            If an invalid array is passed.
         """
         if not isinstance(value, np.ndarray):
-            raise TypeError("value must be a numpy array")
+            raise TypeError("Value must be a NumPy array.")
         if value.shape[0] != 4:
-            raise TypeError("Array must have 4 values exactly")
+            raise TypeError("Array must have exactly 4 values.")
         self.__value: ManimColorInternal = value
 
+    @classmethod
+    def _construct_from_space(
+        cls,
+        _space: npt.NDArray[ManimFloat]
+        | tuple[float, float, float]
+        | tuple[float, float, float, float],
+    ) -> Self:
+        """This function is used as a proxy for constructing a color with an internal
+        value. This can be used by subclasses to hook into the construction of new
+        objects using the internal value format.
+        """
+        return cls(_space)
+
     @staticmethod
     def _internal_from_integer(value: int, alpha: float) -> ManimColorInternal:
         return np.asarray(
@@ -200,32 +288,41 @@ class ManimColor:
             dtype=ManimColorDType,
         )
 
-    # TODO: Maybe make 8 nibble hex also convertible ?
     @staticmethod
-    def _internal_from_hex_string(hex: str, alpha: float) -> ManimColorInternal:
-        """Internal function for converting a hex string into the internal representation of a ManimColor.
+    def _internal_from_hex_string(hex_: str, alpha: float) -> ManimColorInternal:
+        """Internal function for converting a hex string into the internal representation
+        of a :class:`ManimColor`.
 
         .. warning::
             This does not accept any prefixes like # or similar in front of the hex string.
-            This is just intended for the raw hex part
+            This is just intended for the raw hex part.
 
         *For internal use only*
 
         Parameters
         ----------
-        hex : str
-            hex string to be parsed
-        alpha : float
-            alpha value used for the color
+        hex
+            Hex string to be parsed.
+        alpha
+            Alpha value used for the color, if the color is only 3 bytes long. Otherwise,
+            if the color is 4 bytes long, this parameter will not be used.
 
         Returns
         -------
         ManimColorInternal
             Internal color representation
         """
-        if len(hex) == 6:
-            hex += "00"
-        tmp = int(hex, 16)
+        if len(hex_) in (3, 4):
+            hex_ = "".join([x * 2 for x in hex_])
+        if len(hex_) == 6:
+            hex_ += "FF"
+        elif len(hex_) == 8:
+            alpha = (int(hex_, 16) & 0xFF) / 255
+        else:
+            raise ValueError(
+                "Hex colors must be specified with either 0x or # as prefix and contain 6 or 8 hexadecimal numbers"
+            )
+        tmp = int(hex_, 16)
         return np.asarray(
             (
                 ((tmp >> 24) & 0xFF) / 255,
@@ -240,22 +337,22 @@ class ManimColor:
     def _internal_from_int_rgb(
         rgb: RGB_Tuple_Int, alpha: float = 1.0
     ) -> ManimColorInternal:
-        """Internal function for converting a rgb tuple of integers into the internal representation of a ManimColor.
+        """Internal function for converting an RGB tuple of integers into the internal
+        representation of a :class:`ManimColor`.
 
         *For internal use only*
 
         Parameters
         ----------
-        rgb : RGB_Tuple_Int
-            integer rgb tuple to be parsed
-        alpha : float, optional
-            optional alpha value, by default 1.0
+        rgb
+            Integer RGB tuple to be parsed
+        alpha
+            Optional alpha value. Default is 1.0.
 
         Returns
         -------
         ManimColorInternal
-            Internal color representation
-
+            Internal color representation.
         """
         value: np.ndarray = np.asarray(rgb, dtype=ManimColorDType).copy() / 255
         value.resize(4, refcheck=False)
@@ -266,22 +363,22 @@ class ManimColor:
     def _internal_from_rgb(
         rgb: RGB_Tuple_Float, alpha: float = 1.0
     ) -> ManimColorInternal:
-        """Internal function for converting a rgb tuple of floats into the internal representation of a ManimColor.
+        """Internal function for converting a rgb tuple of floats into the internal
+        representation of a :class:`ManimColor`.
 
         *For internal use only*
 
         Parameters
         ----------
-        rgb : RGB_Tuple_Float
-            float rgb tuple to be parsed
-
-        alpha : float, optional
-            optional alpha value, by default 1.0
+        rgb
+            Float RGB tuple to be parsed.
+        alpha
+            Optional alpha value. Default is 1.0.
 
         Returns
         -------
         ManimColorInternal
-            Internal color representation
+            Internal color representation.
         """
         value: np.ndarray = np.asarray(rgb, dtype=ManimColorDType).copy()
         value.resize(4, refcheck=False)
@@ -290,324 +387,527 @@ class ManimColor:
 
     @staticmethod
     def _internal_from_int_rgba(rgba: RGBA_Tuple_Int) -> ManimColorInternal:
-        """Internal function for converting a rgba tuple of integers into the internal representation of a ManimColor.
+        """Internal function for converting an RGBA tuple of integers into the internal
+        representation of a :class:`ManimColor`.
 
         *For internal use only*
 
         Parameters
         ----------
-        rgba : RGBA_Tuple_Int
-            int rgba tuple to be parsed
+        rgba
+            Int RGBA tuple to be parsed.
 
         Returns
         -------
         ManimColorInternal
-            Internal color representation
+            Internal color representation.
         """
         return np.asarray(rgba, dtype=ManimColorDType) / 255
 
     @staticmethod
     def _internal_from_rgba(rgba: RGBA_Tuple_Float) -> ManimColorInternal:
-        """Internal function for converting a rgba tuple of floats into the internal representation of a ManimColor.
+        """Internal function for converting an RGBA tuple of floats into the internal
+        representation of a :class:`ManimColor`.
 
         *For internal use only*
 
         Parameters
         ----------
-        rgba : RGBA_Tuple_Float
-            int rgba tuple to be parsed
+        rgba
+            Int RGBA tuple to be parsed.
 
         Returns
         -------
         ManimColorInternal
-            Internal color representation
+            Internal color representation.
         """
         return np.asarray(rgba, dtype=ManimColorDType)
 
     @staticmethod
-    def _internal_from_string(name: str) -> ManimColorInternal:
-        """Internal function for converting a string into the internal representation of a ManimColor.
-        This is not used for hex strings, please refer to :meth:`_internal_from_hex` for this functionality.
+    def _internal_from_string(name: str, alpha: float) -> ManimColorInternal:
+        """Internal function for converting a string into the internal representation of
+        a :class:`ManimColor`. This is not used for hex strings: please refer to
+        :meth:`_internal_from_hex` for this functionality.
 
         *For internal use only*
 
         Parameters
         ----------
-        name : str
-            The color name to be parsed into a color. Refer to the different color Modules in the documentation Page to
-            find the corresponding Color names.
+        name
+            The color name to be parsed into a color. Refer to the different color
+            modules in the documentation page to find the corresponding color names.
 
         Returns
         -------
         ManimColorInternal
-            Internal color representation
+            Internal color representation.
 
         Raises
         ------
         ValueError
-            Raises a ValueError if the color name is not present with manim
+            If the color name is not present in Manim.
         """
         from . import _all_color_dict
 
-        upper_name = name.upper()
-
-        if upper_name in _all_color_dict:
-            return _all_color_dict[upper_name]._internal_value
+        if tmp := _all_color_dict.get(name.upper()):
+            tmp._internal_value[3] = alpha
+            return tmp._internal_value.copy()
         else:
             raise ValueError(f"Color {name} not found")
 
     def to_integer(self) -> int:
-        """Converts the current ManimColor into an integer
+        """Convert the current :class:`ManimColor` into an integer.
+
+        .. warning::
+            This will return only the RGB part of the color.
 
         Returns
         -------
         int
-            integer representation of the color
-
-        .. warning::
-            This will return only the rgb part of the color
+            Integer representation of the color.
         """
-        return int.from_bytes(
-            (self._internal_value[:3] * 255).astype(int).tobytes(), "big"
-        )
+        tmp = (self._internal_value[:3] * 255).astype(dtype=np.byte).tobytes()
+        return int.from_bytes(tmp, "big")
 
     def to_rgb(self) -> RGB_Array_Float:
-        """Converts the current ManimColor into a rgb array of floats
+        """Convert the current :class:`ManimColor` into an RGB array of floats.
 
         Returns
         -------
         RGB_Array_Float
-            rgb array with 3 elements of type float
+            RGB array of 3 floats from 0.0 to 1.0.
         """
         return self._internal_value[:3]
 
     def to_int_rgb(self) -> RGB_Array_Int:
-        """Converts the current ManimColor into a rgb array of int
+        """Convert the current :class:`ManimColor` into an RGB array of integers.
 
         Returns
         -------
         RGB_Array_Int
-            rgb array with 3 elements of type int
+            RGB array of 3 integers from 0 to 255.
         """
         return (self._internal_value[:3] * 255).astype(int)
 
     def to_rgba(self) -> RGBA_Array_Float:
-        """Converts the current ManimColor into a rgba array of floats
+        """Convert the current :class:`ManimColor` into an RGBA array of floats.
 
         Returns
         -------
         RGBA_Array_Float
-            rgba array with 4 elements of type float
+            RGBA array of 4 floats from 0.0 to 1.0.
         """
         return self._internal_value
 
     def to_int_rgba(self) -> RGBA_Array_Int:
-        """Converts the current ManimColor into a rgba array of int
+        """Convert the current ManimColor into an RGBA array of integers.
 
 
         Returns
         -------
         RGBA_Array_Int
-            rgba array with 4 elements of type int
+            RGBA array of 4 integers from 0 to 255.
         """
         return (self._internal_value * 255).astype(int)
 
     def to_rgba_with_alpha(self, alpha: float) -> RGBA_Array_Float:
-        """Converts the current ManimColor into a rgba array of float as :meth:`to_rgba` but you can change the alpha
-        value.
+        """Convert the current :class:`ManimColor` into an RGBA array of floats. This is
+        similar to :meth:`to_rgba`, but you can change the alpha value.
 
         Parameters
         ----------
-        alpha : float
-            alpha value to be used in the return value
+        alpha
+            Alpha value to be used in the return value.
 
         Returns
         -------
         RGBA_Array_Float
-            rgba array with 4 elements of type float
+            RGBA array of 4 floats from 0.0 to 1.0.
         """
         return np.fromiter((*self._internal_value[:3], alpha), dtype=ManimColorDType)
 
     def to_int_rgba_with_alpha(self, alpha: float) -> RGBA_Array_Int:
-        """Converts the current ManimColor into a rgba array of integers as :meth:`to_int_rgba` but you can change the alpha
-        value.
+        """Convert the current :class:`ManimColor` into an RGBA array of integers. This
+        is similar to :meth:`to_int_rgba`, but you can change the alpha value.
 
         Parameters
         ----------
-        alpha : float
-            alpha value to be used for the return value. (Will automatically be scaled from 0-1 to 0-255 so just pass 0-1)
+        alpha
+            Alpha value to be used for the return value. Pass a float between 0.0 and
+            1.0: it will automatically be scaled to an integer between 0 and 255.
 
         Returns
         -------
         RGBA_Array_Int
-            rgba array with 4 elements of type int
+            RGBA array of 4 integers from 0 to 255.
         """
         tmp = self._internal_value * 255
         tmp[3] = alpha * 255
         return tmp.astype(int)
 
     def to_hex(self, with_alpha: bool = False) -> str:
-        """Converts the manim color to a hexadecimal representation of the color
+        """Convert the :class:`ManimColor` to a hexadecimal representation of the color.
 
         Parameters
         ----------
-        with_alpha : bool, optional
-            Changes the result from 6 to 8 values where the last 2 nibbles represent the alpha value of 0-255,
-            by default False
+        with_alpha
+            If ``True``, append 2 extra characters to the hex string which represent the
+            alpha value of the color between 0 and 255. Default is ``False``.
 
         Returns
         -------
         str
-            A hex string starting with a # with either 6 or 8 nibbles depending on your input, by default 6 i.e #XXXXXX
+            A hex string starting with a ``#``, with either 6 or 8 nibbles depending on
+            the ``with_alpha`` parameter. By default, it has 6 nibbles, i.e. ``#XXXXXX``.
         """
-        tmp = f"#{int(self._internal_value[0]*255):02X}{int(self._internal_value[1]*255):02X}{int(self._internal_value[2]*255):02X}"
+        tmp = (
+            f"#{int(self._internal_value[0] * 255):02X}"
+            f"{int(self._internal_value[1] * 255):02X}"
+            f"{int(self._internal_value[2] * 255):02X}"
+        )
         if with_alpha:
-            tmp += f"{int(self._internal_value[3]*255):02X}"
+            tmp += f"{int(self._internal_value[3] * 255):02X}"
         return tmp
 
     def to_hsv(self) -> HSV_Array_Float:
-        """Converts the Manim Color to HSV array.
+        """Convert the :class:`ManimColor` to an HSV array.
 
         .. note::
-           Be careful this returns an array in the form `[h, s, v]` where the elements are floats.
-           This might be confusing because rgb can also be an array of floats so you might want to annotate the usage
-           of this function in your code by typing the variables with :class:`HSV_Array_Float` in order to differentiate
-           between rgb arrays and hsv arrays
+           Be careful: this returns an array in the form ``[h, s, v]``, where the
+           elements are floats. This might be confusing, because RGB can also be an array
+           of floats. You might want to annotate the usage of this function in your code
+           by typing your HSV array variables as :class:`HSV_Array_Float` in order to
+           differentiate them from RGB arrays.
 
         Returns
         -------
         HSV_Array_Float
-            A hsv array containing 3 elements of type float ranging from 0 to 1
+            An HSV array of 3 floats from 0.0 to 1.0.
         """
-        return colorsys.rgb_to_hsv(*self.to_rgb())
+        return np.array(colorsys.rgb_to_hsv(*self.to_rgb()))
 
-    def invert(self, with_alpha=False) -> ManimColor:
-        """Returns an linearly inverted version of the color (no inplace changes)
+    def to_hsl(self) -> HSL_Array_Float:
+        """Convert the :class:`ManimColor` to an HSL array.
+
+        .. note::
+           Be careful: this returns an array in the form ``[h, s, l]``, where the
+           elements are floats. This might be confusing, because RGB can also be an array
+           of floats. You might want to annotate the usage of this function in your code
+           by typing your HSL array variables as :class:`HSL_Array_Float` in order to
+           differentiate them from RGB arrays.
+
+        Returns
+        -------
+        HSL_Array_Float
+            An HSL array of 3 floats from 0.0 to 1.0.
+        """
+        return np.array(colorsys.rgb_to_hls(*self.to_rgb()))
+
+    def invert(self, with_alpha: bool = False) -> Self:
+        """Return a new, linearly inverted version of this :class:`ManimColor` (no
+        inplace changes).
 
         Parameters
         ----------
-        with_alpha : bool, optional
-            if true the alpha value will be inverted too, by default False
+        with_alpha
+            If ``True``, the alpha value will be inverted too. Default is ``False``.
 
             .. note::
-                This can result in unintended behavior where objects are not displayed because their alpha
-                value is suddenly 0 or very low. Please keep that in mind when setting this to true
+                Setting ``with_alpha=True`` can result in unintended behavior where
+                objects are not displayed because their new alpha value is suddenly 0 or
+                very low.
 
         Returns
         -------
         ManimColor
-            The linearly inverted ManimColor
+            The linearly inverted :class:`ManimColor`.
         """
-        return ManimColor(1.0 - self._internal_value, with_alpha)
+        if with_alpha:
+            return self._construct_from_space(1.0 - self._internal_space)
+        else:
+            alpha = self._internal_space[3]
+            new = 1.0 - self._internal_space
+            new[-1] = alpha
+            return self._construct_from_space(new)
 
-    def interpolate(self, other: ManimColor, alpha: float) -> ManimColor:
-        """Interpolates between the current and the given ManimColor an returns the interpolated color
+    def interpolate(self, other: Self, alpha: float) -> Self:
+        """Interpolate between the current and the given :class:`ManimColor`, and return
+        the result.
 
         Parameters
         ----------
-        other : ManimColor
-            The other ManimColor to be used for interpolation
-        alpha : float
-            A point on the line in rgba colorspace connecting the two colors i.e. the interpolation point
-
-            0 corresponds to the current ManimColor and 1 corresponds to the other ManimColor
+        other
+            The other :class:`ManimColor` to be used for interpolation.
+        alpha
+            A point on the line in RGBA colorspace connecting the two colors, i.e. the
+            interpolation point. 0.0 corresponds to the current :class:`ManimColor` and
+            1.0 corresponds to the other :class:`ManimColor`.
 
         Returns
         -------
         ManimColor
-            The interpolated ManimColor
+            The interpolated :class:`ManimColor`.
         """
-        return ManimColor(
-            self._internal_value * (1 - alpha) + other._internal_value * alpha
+        return self._construct_from_space(
+            self._internal_space * (1 - alpha) + other._internal_space * alpha
         )
 
+    def darker(self, blend: float = 0.2) -> Self:
+        """Return a new color that is darker than the current color, i.e.
+        interpolated with ``BLACK``. The opacity is unchanged.
+
+        Parameters
+        ----------
+        blend
+            The blend ratio for the interpolation, from 0.0 (the current color
+            unchanged) to 1.0 (pure black). Default is 0.2, which results in a
+            slightly darker color.
+
+        Returns
+        -------
+        ManimColor
+            The darker :class:`ManimColor`.
+
+        See Also
+        --------
+        :meth:`lighter`
+        """
+        from manim.utils.color.manim_colors import BLACK
+
+        alpha = self._internal_space[3]
+        black = self._from_internal(BLACK._internal_value)
+        return self.interpolate(black, blend).opacity(alpha)
+
+    def lighter(self, blend: float = 0.2) -> Self:
+        """Return a new color that is lighter than the current color, i.e.
+        interpolated with ``WHITE``. The opacity is unchanged.
+
+        Parameters
+        ----------
+        blend
+            The blend ratio for the interpolation, from 0.0 (the current color
+            unchanged) to 1.0 (pure white). Default is 0.2, which results in a
+            slightly lighter color.
+
+        Returns
+        -------
+        ManimColor
+            The lighter :class:`ManimColor`.
+
+        See Also
+        --------
+        :meth:`darker`
+        """
+        from manim.utils.color.manim_colors import WHITE
+
+        alpha = self._internal_space[3]
+        white = self._from_internal(WHITE._internal_value)
+        return self.interpolate(white, blend).opacity(alpha)
+
+    def contrasting(
+        self,
+        threshold: float = 0.5,
+        light: Self | None = None,
+        dark: Self | None = None,
+    ) -> Self:
+        """Return one of two colors, light or dark (by default white or black),
+        that contrasts with the current color (depending on its luminance).
+        This is typically used to set text in a contrasting color that ensures
+        it is readable against a background of the current color.
+
+        Parameters
+        ----------
+        threshold
+            The luminance threshold which dictates whether the current color is
+            considered light or dark (and thus whether to return the dark or
+            light color, respectively). Default is 0.5.
+        light
+            The light color to return if the current color is considered dark.
+            Default is ``None``: in this case, pure ``WHITE`` will be returned.
+        dark
+            The dark color to return if the current color is considered light,
+            Default is ``None``: in this case, pure ``BLACK`` will be returned.
+
+        Returns
+        -------
+        ManimColor
+            The contrasting :class:`ManimColor`.
+        """
+        from manim.utils.color.manim_colors import BLACK, WHITE
+
+        luminance, _, _ = colorsys.rgb_to_yiq(*self.to_rgb())
+        if luminance < threshold:
+            if light is not None:
+                return light
+            return self._from_internal(WHITE._internal_value)
+        else:
+            if dark is not None:
+                return dark
+            return self._from_internal(BLACK._internal_value)
+
+    def opacity(self, opacity: float) -> Self:
+        """Create a new :class:`ManimColor` with the given opacity and the same color
+        values as before.
+
+        Parameters
+        ----------
+        opacity
+            The new opacity value to be used.
+
+        Returns
+        -------
+        ManimColor
+            The new :class:`ManimColor` with the same color values and the new opacity.
+        """
+        tmp = self._internal_space.copy()
+        tmp[-1] = opacity
+        return self._construct_from_space(tmp)
+
+    def into(self, class_type: type[ManimColorT]) -> ManimColorT:
+        """Convert the current color into a different colorspace given by ``class_type``,
+        without changing the :attr:`_internal_value`.
+
+        Parameters
+        ----------
+        class_type
+            The class that is used for conversion. It must be a subclass of
+            :class:`ManimColor` which respects the specification HSV, RGBA, ...
+
+        Returns
+        -------
+        ManimColorT
+            A new color object of type ``class_type`` and the same
+            :attr:`_internal_value` as the original color.
+        """
+        return class_type._from_internal(self._internal_value)
+
+    @classmethod
+    def _from_internal(cls, value: ManimColorInternal) -> Self:
+        """This method is intended to be overwritten by custom color space classes
+        which are subtypes of :class:`ManimColor`.
+
+        The method constructs a new object of the given class by transforming the value
+        in the internal format ``[r,g,b,a]`` into a format which the constructor of the
+        custom class can understand. Look at :class:`.HSV` for an example.
+        """
+        return cls(value)
+
     @classmethod
     def from_rgb(
         cls,
         rgb: RGB_Array_Float | RGB_Tuple_Float | RGB_Array_Int | RGB_Tuple_Int,
         alpha: float = 1.0,
     ) -> Self:
-        """Creates a ManimColor from an RGB Array. Automagically decides which type it is int/float
+        """Create a ManimColor from an RGB array. Automagically decides which type it
+        is: ``int`` or ``float``.
 
         .. warning::
-            Please make sure that your elements are not floats if you want integers. A 5.0 will result in the input
-            being interpreted as if it was a float rgb array with the value 5.0 and not the integer 5
+            Please make sure that your elements are not floats if you want integers. A
+            ``5.0`` will result in the input being interpreted as if it was an RGB float
+            array with the value ``5.0`` and not the integer ``5``.
 
 
         Parameters
         ----------
-        rgb : RGB_Array_Float | RGB_Tuple_Float | RGB_Array_Int | RGB_Tuple_Int
-            Any 3 Element Iterable
-        alpha : float, optional
-            alpha value to be used in the color, by default 1.0
+        rgb
+            Any iterable of 3 floats or 3 integers.
+        alpha
+            Alpha value to be used in the color. Default is 1.0.
 
         Returns
         -------
         ManimColor
-            Returns the ManimColor object
+            The :class:`ManimColor` which corresponds to the given ``rgb``.
         """
-        return cls(rgb, alpha)
+        return cls._from_internal(ManimColor(rgb, alpha)._internal_value)
 
     @classmethod
     def from_rgba(
         cls, rgba: RGBA_Array_Float | RGBA_Tuple_Float | RGBA_Array_Int | RGBA_Tuple_Int
     ) -> Self:
-        """Creates a ManimColor from an RGBA Array. Automagically decides which type it is int/float
+        """Create a ManimColor from an RGBA Array. Automagically decides which type it
+        is: ``int`` or ``float``.
 
         .. warning::
-            Please make sure that your elements are not floats if you want integers. A 5.0 will result in the input
-            being interpreted as if it was a float rgb array with the value 5.0 and not the integer 5
+            Please make sure that your elements are not floats if you want integers. A
+            ``5.0`` will result in the input being interpreted as if it was a float RGB
+            array with the float ``5.0`` and not the integer ``5``.
 
         Parameters
         ----------
-        rgba : RGBA_Array_Float | RGBA_Tuple_Float | RGBA_Array_Int | RGBA_Tuple_Int
-            Any 4 Element Iterable
+        rgba
+            Any iterable of 4 floats or 4 integers.
 
         Returns
         -------
         ManimColor
-            Returns the ManimColor object
+            The :class:`ManimColor` corresponding to the given ``rgba``.
         """
         return cls(rgba)
 
     @classmethod
-    def from_hex(cls, hex: str, alpha: float = 1.0) -> Self:
-        """Creates a Manim Color from a hex string, prefixes allowed # and 0x
+    def from_hex(cls, hex_str: str, alpha: float = 1.0) -> Self:
+        """Create a :class:`ManimColor` from a hex string.
 
         Parameters
         ----------
-        hex : str
-            The hex string to be converted (currently only supports 6 nibbles)
-        alpha : float, optional
-            alpha value to be used for the hex string, by default 1.0
+        hex_str
+            The hex string to be converted.  The allowed prefixes for this string are
+            ``#`` and ``0x``. Currently, this method only supports 6 nibbles, i.e. only
+            strings in the format ``#XXXXXX`` or ``0xXXXXXX``.
+        alpha
+            Alpha value to be used for the hex string. Default is 1.0.
 
         Returns
         -------
         ManimColor
-            The ManimColor represented by the hex string
+            The :class:`ManimColor` represented by the hex string.
         """
-        return cls(hex, alpha)
+        return cls._from_internal(ManimColor(hex_str, alpha)._internal_value)
 
     @classmethod
     def from_hsv(
         cls, hsv: HSV_Array_Float | HSV_Tuple_Float, alpha: float = 1.0
     ) -> Self:
-        """Creates a ManimColor from an HSV Array
+        """Create a :class:`ManimColor` from an HSV array.
 
         Parameters
         ----------
-        hsv : HSV_Array_Float | HSV_Tuple_Float
-            Any 3 Element Iterable containing floats from 0-1
-        alpha : float, optional
-            the alpha value to be used, by default 1.0
+        hsv
+            Any iterable containing 3 floats from 0.0 to 1.0.
+        alpha
+            The alpha value to be used. Default is 1.0.
 
         Returns
         -------
         ManimColor
-            The ManimColor with the corresponding RGB values to the HSV
+            The :class:`ManimColor` with the corresponding RGB values to the given HSV
+            array.
         """
         rgb = colorsys.hsv_to_rgb(*hsv)
-        return cls(rgb, alpha)
+        return cls._from_internal(ManimColor(rgb, alpha)._internal_value)
+
+    @classmethod
+    def from_hsl(
+        cls, hsl: HSL_Array_Float | HSL_Tuple_Float, alpha: float = 1.0
+    ) -> Self:
+        """Create a :class:`ManimColor` from an HSL array.
+
+        Parameters
+        ----------
+        hsl
+            Any iterable containing 3 floats from 0.0 to 1.0.
+        alpha
+            The alpha value to be used. Default is 1.0.
+
+        Returns
+        -------
+        ManimColor
+            The :class:`ManimColor` with the corresponding RGB values to the given HSL
+            array.
+        """
+        rgb = colorsys.hls_to_rgb(*hsl)
+        return cls._from_internal(ManimColor(rgb, alpha)._internal_value)
 
     @overload
     @classmethod
@@ -615,8 +915,7 @@ class ManimColor:
         cls,
         color: ParsableManimColor | None,
         alpha: float = ...,
-    ) -> Self:
-        ...
+    ) -> Self: ...
 
     @overload
     @classmethod
@@ -624,37 +923,51 @@ class ManimColor:
         cls,
         color: Sequence[ParsableManimColor],
         alpha: float = ...,
-    ) -> list[Self]:
-        ...
+    ) -> list[Self]: ...
 
     @classmethod
     def parse(
         cls,
-        color: ParsableManimColor | list[ParsableManimColor] | None,
+        color: ParsableManimColor | Sequence[ParsableManimColor] | None,
         alpha: float = 1.0,
     ) -> Self | list[Self]:
-        """
-        Handles the parsing of a list of colors or a single color.
+        """Parse one color as a :class:`ManimColor` or a sequence of colors as a list of
+        :class:`ManimColor`'s.
 
         Parameters
         ----------
         color
-            The color or list of colors to parse. Note that this function can not accept rgba tuples. It will assume that you mean list[ManimColor] and will return a list of ManimColors.
+            The color or list of colors to parse. Note that this function can not accept
+            tuples: it will assume that you mean ``Sequence[ParsableManimColor]`` and will
+            return a ``list[ManimColor]``.
         alpha
-            The alpha value to use if a single color is passed. or if a list of colors is passed to set the value of all colors.
+            The alpha (opacity) value to use for the passed color(s).
 
         Returns
         -------
-        ManimColor
-            Either a list of colors or a singular color depending on the input
+        ManimColor | list[ManimColor]
+            Either a list of colors or a singular color, depending on the input.
         """
-        if isinstance(color, (list, tuple)):
-            return [cls(c, alpha) for c in color]  # type: ignore
-        return cls(color, alpha)  # type: ignore
+
+        def is_sequence(
+            color: ParsableManimColor | Sequence[ParsableManimColor] | None,
+        ) -> TypeIs[Sequence[ParsableManimColor]]:
+            return isinstance(color, (list, tuple))
+
+        if is_sequence(color):
+            return [
+                cls._from_internal(ManimColor(c, alpha)._internal_value) for c in color
+            ]
+        else:
+            return cls._from_internal(ManimColor(color, alpha)._internal_value)
 
     @staticmethod
-    def gradient(colors: list[ManimColor], length: int):
-        """This is not implemented by now refer to :func:`color_gradient` for a working implementation for now"""
+    def gradient(
+        colors: list[ManimColor], length: int
+    ) -> ManimColor | list[ManimColor]:
+        """This method is currently not implemented. Refer to :func:`color_gradient` for
+        a working implementation for now.
+        """
         # TODO: implement proper gradient, research good implementation for this or look at 3b1b implementation
         raise NotImplementedError
 
@@ -669,37 +982,240 @@ class ManimColor:
             raise TypeError(
                 f"Cannot compare {self.__class__.__name__} with {other.__class__.__name__}"
             )
-        return np.allclose(self._internal_value, other._internal_value)
+        are_equal: bool = np.allclose(self._internal_value, other._internal_value)
+        return are_equal
+
+    def __add__(self, other: int | float | Self) -> Self:
+        if isinstance(other, (int, float)):
+            return self._construct_from_space(self._internal_space + other)
+        else:
+            return self._construct_from_space(
+                self._internal_space + other._internal_space
+            )
+
+    def __radd__(self, other: int | float | Self) -> Self:
+        return self + other
+
+    def __sub__(self, other: int | float | Self) -> Self:
+        if isinstance(other, (int, float)):
+            return self._construct_from_space(self._internal_space - other)
+        else:
+            return self._construct_from_space(
+                self._internal_space - other._internal_space
+            )
+
+    def __rsub__(self, other: int | float | Self) -> Self:
+        return self - other
+
+    def __mul__(self, other: int | float | Self) -> Self:
+        if isinstance(other, (int, float)):
+            return self._construct_from_space(self._internal_space * other)
+        else:
+            return self._construct_from_space(
+                self._internal_space * other._internal_space
+            )
+
+    def __rmul__(self, other: int | float | Self) -> Self:
+        return self * other
+
+    def __truediv__(self, other: int | float | Self) -> Self:
+        if isinstance(other, (int, float)):
+            return self._construct_from_space(self._internal_space / other)
+        else:
+            return self._construct_from_space(
+                self._internal_space / other._internal_space
+            )
+
+    def __rtruediv__(self, other: int | float | Self) -> Self:
+        return self / other
+
+    def __floordiv__(self, other: int | float | Self) -> Self:
+        if isinstance(other, (int, float)):
+            return self._construct_from_space(self._internal_space // other)
+        else:
+            return self._construct_from_space(
+                self._internal_space // other._internal_space
+            )
+
+    def __rfloordiv__(self, other: int | float | Self) -> Self:
+        return self // other
+
+    def __mod__(self, other: int | float | Self) -> Self:
+        if isinstance(other, (int, float)):
+            return self._construct_from_space(self._internal_space % other)
+        else:
+            return self._construct_from_space(
+                self._internal_space % other._internal_space
+            )
+
+    def __rmod__(self, other: int | float | Self) -> Self:
+        return self % other
+
+    def __pow__(self, other: int | float | Self) -> Self:
+        if isinstance(other, (int, float)):
+            return self._construct_from_space(self._internal_space**other)
+        else:
+            return self._construct_from_space(
+                self._internal_space**other._internal_space
+            )
+
+    def __rpow__(self, other: int | float | Self) -> Self:
+        return self**other
+
+    def __invert__(self) -> Self:
+        return self.invert()
+
+    def __int__(self) -> int:
+        return self.to_integer()
+
+    def __getitem__(self, index: int) -> float:
+        item: float = self._internal_space[index]
+        return item
+
+    def __and__(self, other: Self) -> Self:
+        return self._construct_from_space(
+            self._internal_from_integer(self.to_integer() & int(other), 1.0)
+        )
+
+    def __or__(self, other: Self) -> Self:
+        return self._construct_from_space(
+            self._internal_from_integer(self.to_integer() | int(other), 1.0)
+        )
+
+    def __xor__(self, other: Self) -> Self:
+        return self._construct_from_space(
+            self._internal_from_integer(self.to_integer() ^ int(other), 1.0)
+        )
+
+    def __hash__(self) -> int:
+        return hash(self.to_hex(with_alpha=True))
+
+
+RGBA = ManimColor
+"""RGBA Color Space"""
+
+
+class HSV(ManimColor):
+    """HSV Color Space"""
+
+    def __init__(
+        self,
+        hsv: HSV_Array_Float | HSV_Tuple_Float | HSVA_Array_Float | HSVA_Tuple_Float,
+        alpha: float = 1.0,
+    ) -> None:
+        super().__init__(None)
+        self.__hsv: HSVA_Array_Float
+        if len(hsv) == 3:
+            self.__hsv = np.asarray((*hsv, alpha))
+        elif len(hsv) == 4:
+            self.__hsv = np.asarray(hsv)
+        else:
+            raise ValueError("HSV Color must be an array of 3 values")
+
+    @classmethod
+    @override
+    def _from_internal(cls, value: ManimColorInternal) -> Self:
+        hsv = colorsys.rgb_to_hsv(*value[:3])
+        hsva = [*hsv, value[-1]]
+        return cls(np.array(hsva))
+
+    @property
+    def hue(self) -> float:
+        hue: float = self.__hsv[0]
+        return hue
+
+    @hue.setter
+    def hue(self, hue: float) -> None:
+        self.__hsv[0] = hue
+
+    @property
+    def saturation(self) -> float:
+        saturation: float = self.__hsv[1]
+        return saturation
+
+    @saturation.setter
+    def saturation(self, saturation: float) -> None:
+        self.__hsv[1] = saturation
 
-    def __add__(self, other: ManimColor) -> ManimColor:
-        return ManimColor(self._internal_value + other._internal_value)
+    @property
+    def value(self) -> float:
+        value: float = self.__hsv[2]
+        return value
 
-    def __sub__(self, other: ManimColor) -> ManimColor:
-        return ManimColor(self._internal_value - other._internal_value)
+    @value.setter
+    def value(self, value: float) -> None:
+        self.__hsv[2] = value
 
-    def __mul__(self, other: ManimColor) -> ManimColor:
-        return ManimColor(self._internal_value * other._internal_value)
+    @property
+    def h(self) -> float:
+        hue: float = self.__hsv[0]
+        return hue
 
-    def __truediv__(self, other: ManimColor) -> ManimColor:
-        return ManimColor(self._internal_value / other._internal_value)
+    @h.setter
+    def h(self, hue: float) -> None:
+        self.__hsv[0] = hue
 
-    def __floordiv__(self, other: ManimColor) -> ManimColor:
-        return ManimColor(self._internal_value // other._internal_value)
+    @property
+    def s(self) -> float:
+        saturation: float = self.__hsv[1]
+        return saturation
 
-    def __mod__(self, other: ManimColor) -> ManimColor:
-        return ManimColor(self._internal_value % other._internal_value)
+    @s.setter
+    def s(self, saturation: float) -> None:
+        self.__hsv[1] = saturation
 
-    def __pow__(self, other: ManimColor) -> ManimColor:
-        return ManimColor(self._internal_value**other._internal_value)
+    @property
+    def v(self) -> float:
+        value: float = self.__hsv[2]
+        return value
 
-    def __and__(self, other: ManimColor) -> ManimColor:
-        return ManimColor(self.to_integer() & other.to_integer())
+    @v.setter
+    def v(self, value: float) -> None:
+        self.__hsv[2] = value
+
+    @property
+    def _internal_space(self) -> npt.NDArray:
+        return self.__hsv
+
+    @property
+    def _internal_value(self) -> ManimColorInternal:
+        """Return the internal value of the current :class:`ManimColor` as an
+        ``[r,g,b,a]`` float array.
+
+        Returns
+        -------
+        ManimColorInternal
+            Internal color representation.
+        """
+        return np.array(
+            [
+                *colorsys.hsv_to_rgb(self.__hsv[0], self.__hsv[1], self.__hsv[2]),
+                self.__alpha,
+            ],
+            dtype=ManimColorDType,
+        )
+
+    @_internal_value.setter
+    def _internal_value(self, value: ManimColorInternal) -> None:
+        """Overwrite the internal color value of this :class:`ManimColor`.
 
-    def __or__(self, other: ManimColor) -> ManimColor:
-        return ManimColor(self.to_integer() | other.to_integer())
+        Parameters
+        ----------
+        value
+            The value which will overwrite the current color.
 
-    def __xor__(self, other: ManimColor) -> ManimColor:
-        return ManimColor(self.to_integer() ^ other.to_integer())
+        Raises
+        ------
+        TypeError
+            If an invalid array is passed.
+        """
+        if not isinstance(value, np.ndarray):
+            raise TypeError("Value must be a NumPy array.")
+        if value.shape[0] != 4:
+            raise TypeError("Array must have exactly 4 values.")
+        tmp = colorsys.rgb_to_hsv(value[0], value[1], value[2])
+        self.__hsv = np.array(tmp)
+        self.__alpha = value[3]
 
 
 ParsableManimColor: TypeAlias = Union[
@@ -715,76 +1231,84 @@ ParsableManimColor: TypeAlias = Union[
     RGBA_Array_Int,
     RGBA_Array_Float,
 ]
-"""ParsableManimColor is the representation for all types that are parsable to a color in manim"""
+"""`ParsableManimColor` represents all the types which can be parsed
+to a :class:`ManimColor` in Manim.
+"""
 
 
 ManimColorT = TypeVar("ManimColorT", bound=ManimColor)
 
 
 def color_to_rgb(color: ParsableManimColor) -> RGB_Array_Float:
-    """Helper function for use in functional style programming refer to :meth:`to_rgb` in :class:`ManimColor`
+    """Helper function for use in functional style programming.
+    Refer to :meth:`ManimColor.to_rgb`.
 
     Parameters
     ----------
-    color : ParsableManimColor
-        A color
+    color
+        A color to convert to an RGB float array.
 
     Returns
     -------
     RGB_Array_Float
-        the corresponding rgb array
+        The corresponding RGB float array.
     """
     return ManimColor(color).to_rgb()
 
 
-def color_to_rgba(color: ParsableManimColor, alpha: float = 1) -> RGBA_Array_Float:
-    """Helper function for use in functional style programming refer to :meth:`to_rgba_with_alpha` in :class:`ManimColor`
+def color_to_rgba(color: ParsableManimColor, alpha: float = 1.0) -> RGBA_Array_Float:
+    """Helper function for use in functional style programming. Refer to
+    :meth:`ManimColor.to_rgba_with_alpha`.
 
     Parameters
     ----------
-    color : ParsableManimColor
-        A color
-    alpha : float, optional
-        alpha value to be used in the color, by default 1
+    color
+        A color to convert to an RGBA float array.
+    alpha
+        An alpha value between 0.0 and 1.0 to be used as opacity in the color. Default is
+        1.0.
 
     Returns
     -------
     RGBA_Array_Float
-        the corresponding rgba array
+        The corresponding RGBA float array.
     """
     return ManimColor(color).to_rgba_with_alpha(alpha)
 
 
 def color_to_int_rgb(color: ParsableManimColor) -> RGB_Array_Int:
-    """Helper function for use in functional style programming refer to :meth:`to_int_rgb` in :class:`ManimColor`
+    """Helper function for use in functional style programming. Refer to
+    :meth:`ManimColor.to_int_rgb`.
 
     Parameters
     ----------
-    color : ParsableManimColor
-        A color
+    color
+        A color to convert to an RGB integer array.
 
     Returns
     -------
     RGB_Array_Int
-        the corresponding int rgb array
+        The corresponding RGB integer array.
     """
     return ManimColor(color).to_int_rgb()
 
 
 def color_to_int_rgba(color: ParsableManimColor, alpha: float = 1.0) -> RGBA_Array_Int:
-    """Helper function for use in functional style programming refer to :meth:`to_int_rgba_with_alpha` in :class:`ManimColor`
+    """Helper function for use in functional style programming. Refer to
+    :meth:`ManimColor.to_int_rgba_with_alpha`.
 
     Parameters
     ----------
-    color : ParsableManimColor
-        A color
-    alpha : float, optional
-        alpha value to be used in the color, by default 1.0
+    color
+        A color to convert to an RGBA integer array.
+    alpha
+        An alpha value between 0.0 and 1.0 to be used as opacity in the color. Default is
+        1.0.
 
     Returns
     -------
     RGBA_Array_Int
-        the corresponding int rgba array
+        The corresponding RGBA integer array.
     """
     return ManimColor(color).to_int_rgba_with_alpha(alpha)
 
@@ -792,17 +1316,18 @@ def color_to_int_rgba(color: ParsableManimColor, alpha: float = 1.0) -> RGBA_Arr
 def rgb_to_color(
     rgb: RGB_Array_Float | RGB_Tuple_Float | RGB_Array_Int | RGB_Tuple_Int,
 ) -> ManimColor:
-    """Helper function for use in functional style programming refer to :meth:`from_rgb` in :class:`ManimColor`
+    """Helper function for use in functional style programming. Refer to
+    :meth:`ManimColor.from_rgb`.
 
     Parameters
     ----------
-    rgb : RGB_Array_Float | RGB_Tuple_Float
-        A 3 element iterable
+    rgb
+        A 3 element iterable.
 
     Returns
     -------
     ManimColor
-        A ManimColor with the corresponding value
+        A ManimColor with the corresponding value.
     """
     return ManimColor.from_rgb(rgb)
 
@@ -810,12 +1335,13 @@ def rgb_to_color(
 def rgba_to_color(
     rgba: RGBA_Array_Float | RGBA_Tuple_Float | RGBA_Array_Int | RGBA_Tuple_Int,
 ) -> ManimColor:
-    """Helper function for use in functional style programming refer to :meth:`from_rgba` in :class:`ManimColor`
+    """Helper function for use in functional style programming. Refer to
+    :meth:`ManimColor.from_rgba`.
 
     Parameters
     ----------
-    rgba : RGBA_Array_Float | RGBA_Tuple_Float
-        A 4 element iterable
+    rgba
+        A 4 element iterable.
 
     Returns
     -------
@@ -828,92 +1354,74 @@ def rgba_to_color(
 def rgb_to_hex(
     rgb: RGB_Array_Float | RGB_Tuple_Float | RGB_Array_Int | RGB_Tuple_Int,
 ) -> str:
-    """Helper function for use in functional style programming refer to :meth:`from_rgb` in :class:`ManimColor`
+    """Helper function for use in functional style programming. Refer to
+    :meth:`ManimColor.from_rgb` and :meth:`ManimColor.to_hex`.
 
     Parameters
     ----------
-    rgb : RGB_Array_Float | RGB_Tuple_Float
-        A 3 element iterable
+    rgb
+        A 3 element iterable.
 
     Returns
     -------
     str
-        A hex representation of the color, refer to :meth:`to_hex` in :class:`ManimColor`
+        A hex representation of the color.
     """
     return ManimColor.from_rgb(rgb).to_hex()
 
 
 def hex_to_rgb(hex_code: str) -> RGB_Array_Float:
-    """Helper function for use in functional style programming refer to :meth:`to_hex` in :class:`ManimColor`
+    """Helper function for use in functional style programming. Refer to
+    :meth:`ManimColor.to_rgb`.
 
     Parameters
     ----------
-    hex_code : str
-        A hex string representing a color
+    hex_code
+        A hex string representing a color.
 
     Returns
     -------
     RGB_Array_Float
-        RGB array representing the color
+        An RGB array representing the color.
     """
     return ManimColor(hex_code).to_rgb()
 
 
 def invert_color(color: ManimColorT) -> ManimColorT:
-    """Helper function for use in functional style programming refer to :meth:`invert` in :class:`ManimColor`
+    """Helper function for use in functional style programming. Refer to
+    :meth:`ManimColor.invert`
 
     Parameters
     ----------
-    color : ManimColor
-        A ManimColor
+    color
+        The :class:`ManimColor` to invert.
 
     Returns
     -------
     ManimColor
-        The linearly inverted ManimColor
+        The linearly inverted :class:`ManimColor`.
     """
     return color.invert()
 
 
-def interpolate_arrays(
-    arr1: npt.NDArray[Any], arr2: npt.NDArray[Any], alpha: float
-) -> np.ndarray:
-    """Helper function used in Manim to fade between two objects smoothly
-
-    Parameters
-    ----------
-    arr1 : npt.NDArray[Any]
-        The first array of colors
-    arr2 : npt.NDArray[Any]
-        The second array of colors
-    alpha : float
-        The alpha value corresponding to the interpolation point between the two inputs
-
-    Returns
-    -------
-    np.ndarray
-        The interpolated value of the to arrays
-    """
-    return (1 - alpha) * arr1 + alpha * arr2
-
-
 def color_gradient(
     reference_colors: Sequence[ParsableManimColor],
     length_of_output: int,
 ) -> list[ManimColor] | ManimColor:
-    """Creates a list of colors interpolated between the input array of colors with a specific number of colors
+    """Create a list of colors interpolated between the input array of colors with a
+    specific number of colors.
 
     Parameters
     ----------
-    reference_colors : Sequence[ParsableManimColor]
-        The colors to be interpolated between or spread apart
-    length_of_output : int
-        The number of colors that the output should have, ideally more than the input
+    reference_colors
+        The colors to be interpolated between or spread apart.
+    length_of_output
+        The number of colors that the output should have, ideally more than the input.
 
     Returns
     -------
     list[ManimColor] | ManimColor
-        A list of ManimColor's which has the interpolated colors
+        A :class:`ManimColor` or a list of interpolated :class:`ManimColor`'s.
     """
     if length_of_output == 0:
         return ManimColor(reference_colors[0])
@@ -933,34 +1441,39 @@ def color_gradient(
 
 
 def interpolate_color(
-    color1: ManimColorT, color2: ManimColor, alpha: float
+    color1: ManimColorT, color2: ManimColorT, alpha: float
 ) -> ManimColorT:
-    """Standalone function to interpolate two ManimColors and get the result refer to :meth:`interpolate` in :class:`ManimColor`
+    """Standalone function to interpolate two ManimColors and get the result. Refer to
+    :meth:`ManimColor.interpolate`.
 
     Parameters
     ----------
-    color1 : ManimColor
-        First ManimColor
-    color2 : ManimColor
-        Second ManimColor
-    alpha : float
-        The alpha value determining the point of interpolation between the colors
+    color1
+        The first :class:`ManimColor`.
+    color2
+        The second :class:`ManimColor`.
+    alpha
+        The alpha value determining the point of interpolation between the colors.
 
     Returns
     -------
     ManimColor
-        The interpolated ManimColor
+        The interpolated ManimColor.
     """
     return color1.interpolate(color2, alpha)
 
 
 def average_color(*colors: ParsableManimColor) -> ManimColor:
-    """Determines the Average color of the given parameters
+    """Determine the average color between the given parameters.
+
+    .. note::
+        This operation does not consider the alphas (opacities) of the colors. The
+        generated color has an alpha or opacity of 1.0.
 
     Returns
     -------
     ManimColor
-        The average color of the input
+        The average color of the input.
     """
     rgbs = np.array([color_to_rgb(color) for color in colors])
     mean_rgb = np.apply_along_axis(np.mean, 0, rgbs)
@@ -968,31 +1481,31 @@ def average_color(*colors: ParsableManimColor) -> ManimColor:
 
 
 def random_bright_color() -> ManimColor:
-    """Returns you a random bright color
+    """Return a random bright color: a random color averaged with ``WHITE``.
 
     .. warning::
-        This operation is very expensive please keep in mind the performance loss.
+        This operation is very expensive. Please keep in mind the performance loss.
 
     Returns
     -------
     ManimColor
-        A bright ManimColor
+        A random bright :class:`ManimColor`.
     """
     curr_rgb = color_to_rgb(random_color())
-    new_rgb = interpolate_arrays(curr_rgb, np.ones(len(curr_rgb)), 0.5)
+    new_rgb = 0.5 * (curr_rgb + np.ones(3))
     return ManimColor(new_rgb)
 
 
 def random_color() -> ManimColor:
-    """Return you a random ManimColor
+    """Return a random :class:`ManimColor`.
 
     .. warning::
-        This operation is very expensive please keep in mind the performance loss.
+        This operation is very expensive. Please keep in mind the performance loss.
 
     Returns
     -------
     ManimColor
-        _description_
+        A random :class:`ManimColor`.
     """
     import manim.utils.color.manim_colors as manim_colors
 
@@ -1000,17 +1513,38 @@ def random_color() -> ManimColor:
 
 
 def get_shaded_rgb(
-    rgb: npt.NDArray[Any],
-    point: npt.NDArray[Any],
-    unit_normal_vect: npt.NDArray[Any],
-    light_source: npt.NDArray[Any],
-) -> RGBA_Array_Float:
+    rgb: RGB_Array_Float,
+    point: Point3D,
+    unit_normal_vect: Vector3D,
+    light_source: Point3D,
+) -> RGB_Array_Float:
+    """Add light or shadow to the ``rgb`` color of some surface which is located at a
+    given ``point`` in space and facing in the direction of ``unit_normal_vect``,
+    depending on whether the surface is facing a ``light_source`` or away from it.
+
+    Parameters
+    ----------
+    rgb
+        An RGB array of floats.
+    point
+        The location of the colored surface.
+    unit_normal_vect
+        The direction in which the colored surface is facing.
+    light_source
+        The location of a light source which might illuminate the surface.
+
+    Returns
+    -------
+    RGB_Array_Float
+        The color with added light or shadow, depending on the direction of the colored
+        surface.
+    """
     to_sun = normalize(light_source - point)
-    factor = 0.5 * np.dot(unit_normal_vect, to_sun) ** 3
-    if factor < 0:
-        factor *= 0.5
-    result = rgb + factor
-    return result
+    light = 0.5 * np.dot(unit_normal_vect, to_sun) ** 3
+    if light < 0:
+        light *= 0.5
+    shaded_rgb: RGB_Array_Float = rgb + light
+    return shaded_rgb
 
 
 __all__ = [
@@ -1026,11 +1560,12 @@ __all__ = [
     "rgb_to_hex",
     "hex_to_rgb",
     "invert_color",
-    "interpolate_arrays",
     "color_gradient",
     "interpolate_color",
     "average_color",
     "random_bright_color",
     "random_color",
     "get_shaded_rgb",
+    "HSV",
+    "RGBA",
 ]