refactored subsampling param handling, added param to docs.

CHANGELOG.md

@@ -4,7 +4,7 @@ All notable changes to this project will be documented in this file.
 
 ### Added
 
-- Synonym for `chroma` encoder parameter: `subsampling`(usage is the same as in Pillow JPEG). #161
+- Synonym for `chroma` encoder parameter: `subsampling`(usage is the same as in Pillow JPEG). #161 #165
 - Pi-Heif: Python3.12 32-bit `armv7` wheels. #160
 
 ### Changed

pillow_heif/heif.py

@@ -332,6 +332,8 @@ def save(self, fp, **kwargs) -> None:
 
             ``chroma`` - custom subsampling value. Possible values: ``444``, ``422`` or ``420`` (``x265`` default).
 
+            ``subsampling`` - synonym for *chroma*. Format is string, compatible with Pillow: ``x:x:x``, e.g. '4:4:4'.
+
             ``format`` - string with encoder format name. Possible values: ``HEIF`` (default) or ``AVIF``.
 
             ``save_nclx_profile`` - boolean, see :py:attr:`~pillow_heif.options.SAVE_NCLX_PROFILE`

pillow_heif/misc.py

@@ -71,6 +71,12 @@
     "L": (1, 8, HeifColorspace.MONOCHROME, HeifChroma.MONOCHROME),
 }
 
+SUBSAMPLING_CHROMA_MAP = {
+    "4:4:4": 444,
+    "4:2:2": 422,
+    "4:2:0": 420,
+}
+
 
 def set_orientation(info: dict) -> Optional[int]:
     """Reset orientation in ``EXIF`` to ``1`` if any orientation present.
@@ -307,14 +313,8 @@ def __init__(self, compression_format: HeifCompressionFormat, **kwargs):
         self.ctx_write = _pillow_heif.CtxWrite(compression_format, -2 if quality is None else quality)
         enc_params = kwargs.get("enc_params", {})
         chroma = kwargs.get("chroma", None)
-        subsampling = kwargs.get("subsampling", None)
-        if chroma is None and subsampling:
-            subsampling_map = {
-                "4:4:4": 444,
-                "4:2:2": 422,
-                "4:2:0": 420,
-            }
-            chroma = subsampling_map.get(subsampling, None)
+        if chroma is None and "subsampling" in kwargs:
+            chroma = SUBSAMPLING_CHROMA_MAP.get(kwargs["subsampling"], None)
         if chroma:
             enc_params["chroma"] = chroma
         for key, value in enc_params.items():

tests/basic_test.py

@@ -16,8 +16,6 @@ def test_libheif_info():
     for key in ("HEIF", "AVIF"):
         assert key in info
     assert pillow_heif.libheif_version() in (
-        "1.12.0",
-        "1.13.0",
         "1.14.0",
         "1.14.1",
         "1.14.2",
@@ -26,6 +24,7 @@ def test_libheif_info():
         "1.16.1",
         "1.16.2",
         "1.17.1",
+        "1.17.3",
     )