feat: Implement blend_colors function for color blending

src/readyplayerme/meshops/mesh.py

@@ -6,7 +6,7 @@
 import trimesh
 from scipy.spatial import cKDTree
 
-from readyplayerme.meshops.types import Edges, IndexGroups, Indices, Mesh, PixelCoord, UVs, Vertices
+from readyplayerme.meshops.types import Color, Edges, IndexGroups, Indices, Mesh, PixelCoord, UVs, Vertices
 
 
 def read_mesh(filename: str | Path) -> Mesh:
@@ -128,3 +128,35 @@ def uv_to_image_coords(
     img_coords[:, 1] = ((1 - wrapped_uvs[:, 1]) * (height - 0.5)).astype(np.uint16)
 
     return img_coords
+
+
+def blend_colors(colors: Color, index_groups: IndexGroups) -> Color:
+    """Blends colors according to the given groups.
+
+    :param index_groups: A list of groups of indices.
+    :param vertex_colors: A list of colors .
+    :return: Array containing the blended colors .
+    """
+    if not isinstance(colors, np.ndarray):
+        msg = "colors must be a NumPy array"
+        raise ValueError(msg)
+    if not len(colors):
+        return np.array(colors)
+
+    blended_colors = np.copy(colors)
+    if not index_groups or index_groups == []:
+        return blended_colors
+
+    try:
+        colors[np.hstack(index_groups)]
+    except IndexError as error:
+        msg = f"Index out of bounds in index groups: {error}"
+
+        raise IndexError(msg) from error
+
+    # Blending process
+    for group in index_groups:
+        if len(group):
+            blended_colors[group] = np.mean(colors[group], axis=0)
+
+    return blended_colors

src/readyplayerme/meshops/types.py

@@ -10,6 +10,7 @@
 Edges: TypeAlias = npt.NDArray[np.int32] | npt.NDArray[np.int64]  # Shape (e, 2)
 Faces: TypeAlias = npt.NDArray[np.int32] | npt.NDArray[np.int64]  # Shape (f, 3)
 IndexGroups: TypeAlias = list[npt.NDArray[np.uint32]]
+Color: TypeAlias = npt.NDArray[np.uint8]  # Shape RGBA: (c, 4) | RGB: (c, 3) | Grayscale: (c,
 
 UVs: TypeAlias = npt.NDArray[np.float32] | npt.NDArray[np.float64]  # Shape (i, 2)
 PixelCoord: TypeAlias = npt.NDArray[np.uint16]  # Shape (i, 2)

tests/readyplayerme/meshops/unit/test_mesh.py

@@ -168,3 +168,51 @@ def test_uv_to_image_coords_exceptions(uvs: UVs, width: int, height: int, indice
     """Test the uv_to_image_space function raises expected exceptions."""
     with pytest.raises(IndexError):
         mesh.uv_to_image_coords(uvs, width, height, indices)
+
+
+@pytest.mark.parametrize(
+    "colors, index_groups, expected",
+    [
+        # Case with simple groups and distinct colors
+        (
+            np.array([[255, 0, 0], [0, 255, 0], [0, 0, 255], [255, 255, 0]]),
+            [[0, 1], [2, 3]],
+            np.array([[127, 127, 0], [127, 127, 0], [127, 127, 127], [127, 127, 127]]),
+        ),
+        # Case with a single group
+        (
+            np.array([[100, 100, 100], [200, 200, 200]]),
+            [[0, 1]],
+            np.array([[150, 150, 150], [150, 150, 150]]),
+        ),
+        # Case with groups of 1 element
+        (
+            np.array([[100, 0, 0], [0, 100, 0], [0, 0, 100]]),
+            [[0], [1], [2]],
+            np.array([[100, 0, 0], [0, 100, 0], [0, 0, 100]]),
+        ),
+        # Case with empty colors array
+        (np.array([]), [[0, 1]], np.array([])),
+        # Case with empty groups
+        (np.array([[255, 0, 0], [0, 255, 0]]), [], np.array([[255, 0, 0], [0, 255, 0]])),
+    ],
+)
+def test_blend_colors(colors, index_groups, expected):
+    """Test the blend_colors function."""
+    blended_colors = mesh.blend_colors(colors, index_groups)
+    np.testing.assert_array_equal(blended_colors, expected)
+
+
+@pytest.mark.parametrize(
+    "colors, index_groups",
+    [
+        # Case with out-of-bounds indices
+        (np.array([[255, 0, 0], [0, 255, 0]]), [[0, 2]]),
+        # Case with negative index
+        (np.array([[255, 0, 0], [0, 255, 0]]), [[-3, 1]]),
+    ],
+)
+def test_blend_colors_error_handling(colors, index_groups):
+    """Test error handling in blend_colors function."""
+    with pytest.raises(IndexError):
+        mesh.blend_colors(colors, index_groups)