(4.2.0) Add direct support for PIL.Image (#84)

* Add PIL Image support

* Format

* Bump minor version, and add changelog

* Fix type

Author: qTipTip

CHANGELOG.md

@@ -10,6 +10,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 # Released
 
+## 4.2.0 - 08/11/2025
+
+### Added
+
+- Added support for `PIL.Image` type in `extract_colors`.
+
 ## 4.1.0 - 4/7/2025
 
 ### Added

Pylette/cmd.py

@@ -37,12 +37,17 @@ def main(
     out_filename: pathlib.Path | None = None,
     display_colors: bool = False,
     colorspace: ColorSpace = ColorSpace.rgb,
-    alpha_mask_threshold: int | None = typer.Option(None, min=0, max=255, help="Alpha threshold for transparent image masking (0-255). Pixels with alpha below this value are excluded."),
+    alpha_mask_threshold: int | None = typer.Option(
+        None,
+        min=0,
+        max=255,
+        help="Alpha threshold for transparent image masking (0-255). Pixels with alpha below this value are excluded.",
+    ),
 ):
     if filename is None and image_url is None:
         typer.echo(ctx.get_help())
         raise typer.Exit(code=0)
-    
+
     if filename is not None and image_url is not None:
         typer.echo("Please provide either a filename or an image-url, but not both.")
         raise typer.Exit(code=1)
@@ -54,7 +59,9 @@ def main(
         image = image_url
 
     output_file_path = str(out_filename) if out_filename is not None else None
-    palette = extract_colors(image=image, palette_size=n, sort_mode=sort_by.value, mode=mode.value, alpha_mask_threshold=alpha_mask_threshold)
+    palette = extract_colors(
+        image=image, palette_size=n, sort_mode=sort_by.value, mode=mode.value, alpha_mask_threshold=alpha_mask_threshold
+    )
     palette.to_csv(filename=output_file_path, frequency=True, stdout=stdout, colorspace=colorspace.value)
     if display_colors:
         palette.display()

Pylette/src/color_extraction.py

@@ -13,14 +13,15 @@
 from Pylette.src.extractors.median_cut import median_cut_extraction
 from Pylette.src.palette import Palette
 
-ImageType_T: TypeAlias = Union["os.PathLike[Any]", bytes, NDArray[float], str]
+ImageType_T: TypeAlias = Union["os.PathLike[Any]", bytes, NDArray[float], str, Image.Image]
 
 
 class ImageType(str, Enum):
     PATH = "path"
     BYTES = "bytes"
     ARRAY = "array"
     URL = "url"
+    PIL = "pil"
     NONE = "none"
 
 
@@ -35,6 +36,8 @@ def _parse_image_type(image: ImageType_T) -> ImageType:
     ImageType: The type of the input image.
     """
     match image:
+        case Image.Image():
+            image_type = ImageType.PIL
         case np.ndarray():
             image_type = ImageType.ARRAY
         case os.PathLike():
@@ -97,6 +100,8 @@ def extract_colors(
             img_obj = request_image(image)
         case ImageType.ARRAY:
             img_obj = Image.fromarray(image)
+        case ImageType.PIL:
+            img_obj = image
         case ImageType.NONE:
             raise ValueError(f"Unable to parse image source. Got image type {type(image)}")
 

README.md

@@ -95,8 +95,8 @@ from Pylette import extract_colors
 
 # Extract colors from a transparent PNG, ignoring pixels with alpha < 128
 palette = extract_colors(
-    image='transparent_image.png', 
-    palette_size=10, 
+    image='transparent_image.png',
+    palette_size=10,
     alpha_mask_threshold=128
 )
 ```

docs/index.md

@@ -94,8 +94,8 @@ See the [reference documentation](reference.md) for a complete list of available
 
     # Extract colors from a transparent PNG, ignoring pixels with alpha < 128
     palette = extract_colors(
-        image='transparent_image.png', 
-        palette_size=10, 
+        image='transparent_image.png',
+        palette_size=10,
         alpha_mask_threshold=128
     )
     ```

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "pylette"
-version = "4.1.0"
+version = "4.2.0"
 description = "A Python library for extracting color palettes from images."
 authors = [
     {name = "Ivar Stangeby"}

tests/integration/test_colorspaces.py

@@ -1,8 +1,10 @@
 import pathlib
+from typing import Literal
 
 import cv2
 import pytest
 from numpy.testing import assert_approx_equal
+from PIL import Image
 
 from Pylette.src.color_extraction import extract_colors
 
@@ -13,8 +15,14 @@ def test_image_from_opencv():
     return cv2.imread(str(test_image.absolute().resolve()))
 
 
+@pytest.fixture
+def test_image_from_PIL():
+    test_image = pathlib.Path(__file__).parent.parent / "data/test_image.png"
+    return Image.open(test_image)
+
+
 @pytest.fixture()
-def test_kmean_extracted_palette(test_image_path_as_str):
+def test_kmean_extracted_palette(test_image_path_as_str: str):
     return extract_colors(image=test_image_path_as_str, palette_size=10, resize=True, mode="KM")
 
 
@@ -23,7 +31,9 @@ def test_kmean_extracted_palette(test_image_path_as_str):
     "extraction_mode",
     ["KM", "MC"],
 )
-def test_palette_invariants_with_image_path(test_image_path_as_str, palette_size, extraction_mode):
+def test_palette_invariants_with_image_path(
+    test_image_path_as_str: str, palette_size: int, extraction_mode: Literal["KM", "MC"]
+):
     palette = extract_colors(
         image=test_image_path_as_str,
         palette_size=palette_size,
@@ -117,6 +127,39 @@ def test_palette_invariants_with_image_bytes(test_image_as_bytes, palette_size,
     )
 
 
+@pytest.mark.parametrize("palette_size", [1, 5, 10, 100])
+@pytest.mark.parametrize(
+    "extraction_mode",
+    ["KM", "MC"],
+)
+def test_palette_invariants_with_PIL_image(test_image_from_PIL, palette_size, extraction_mode):
+    palette = extract_colors(
+        image=test_image_from_PIL,
+        palette_size=palette_size,
+        resize=True,
+        mode=extraction_mode,
+    )
+
+    assert len(palette) == palette_size, f"Expected {palette_size} colors in palette, got {len(palette)}"
+    assert (
+        palette.number_of_colors == palette_size
+    ), f"Expected {palette_size} colors in palette, got {palette.number_of_colors}"
+    assert len(palette.colors) == palette_size, f"Expected {palette_size} colors in palette, got {len(palette.colors)}"
+    assert (
+        palette.colors[0].freq >= palette.colors[-1].freq
+    ), "Expected colors to be sorted by frequency in descending order"
+    assert palette.colors[0].freq > 0.0, "Expected the most frequent color to have a frequency greater than 0.0"
+    assert (
+        palette.colors[0].freq <= 1.0
+    ), "Expected the most frequent color to have a frequency less than or equal to 1.0"
+
+    assert_approx_equal(
+        sum(c.freq for c in palette.colors),
+        1.0,
+        err_msg="Expected the sum of all frequencies to be 1.0",
+    )
+
+
 @pytest.mark.parametrize("palette_size", [1, 5, 10, 100])
 @pytest.mark.parametrize(
     "extraction_mode",