PyTurboJPEG 2.1.0__tar.gz → 2.2.0__tar.gz

{pyturbojpeg-2.1.0 → pyturbojpeg-2.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: PyTurboJPEG
-Version: 2.1.0
+Version: 2.2.0
 Summary: A Python wrapper of libjpeg-turbo for decoding and encoding JPEG image.
 Home-page: https://github.com/lilohuang/PyTurboJPEG
 Author: Lilo Huang
@@ -26,6 +26,11 @@ Dynamic: summary
 
 A Python wrapper for libjpeg-turbo that enables efficient JPEG image decoding and encoding.
 
+[![PyPI Version](https://img.shields.io/pypi/v/pyturbojpeg.svg?style=flat-square&color=blue)](https://pypi.org/project/pyturbojpeg/)
+![Python Version](https://img.shields.io/badge/python-3.6+-blue?logo=python&logoColor=white)
+[![Downloads](https://img.shields.io/pypi/dm/pyturbojpeg.svg?style=flat-square&color=orange)](https://pypistats.org/packages/pyturbojpeg)
+[![License](https://img.shields.io/github/license/lilohuang/PyTurboJPEG.svg?style=flat-square)](https://github.com/lilohuang/PyTurboJPEG/blob/master/LICENSE)
+
 ## Prerequisites
 
 - [libjpeg-turbo](https://github.com/libjpeg-turbo/libjpeg-turbo/releases) **3.0 or later** (required for PyTurboJPEG 2.0+)
@@ -239,6 +244,73 @@ cv2.imshow('transposed_image', transposed_image)
 cv2.waitKey(0)
 ```
 
+### ICC Color Management Workflow
+
+```python
+import io
+import numpy as np
+from PIL import Image, ImageCms
+from turbojpeg import TurboJPEG, TJPF_BGR
+
+def decode_jpeg_with_color_management(jpeg_path):
+    """
+    Decodes a JPEG and applies color management (ICC Profile to sRGB).
+    
+    Args:
+        jpeg_path (str): Path to the input JPEG file.
+        
+    Returns:
+        PIL.Image: The color-corrected sRGB Image object.
+    """
+    # 1. Initialize TurboJPEG
+    jpeg = TurboJPEG()
+    
+    with open(jpeg_path, 'rb') as f:
+        jpeg_data = f.read()
+    
+    # 2. Get image headers and decode pixels
+    # Using TJPF_BGR format (OpenCV standard) for the raw buffer
+    width, height, _, _ = jpeg.decode_header(jpeg_data)
+    pixels = jpeg.decode(jpeg_data, pixel_format=TJPF_BGR)
+    
+    # 3. Encapsulate into a Pillow Image object
+    # Key: Use 'raw' and 'BGR' decoder to correctly map BGR bytes to an RGB Image object
+    img = Image.frombytes('RGB', (width, height), pixels, 'raw', 'BGR')
+    
+    # 4. Handle ICC Profile transformation
+    try:
+        # Extract embedded ICC Profile
+        icc_profile = jpeg.get_icc_profile(jpeg_data)
+        
+        if icc_profile:
+            # Create Source and Destination Profile objects
+            src_profile = ImageCms.getOpenProfile(io.BytesIO(icc_profile))
+            dst_profile = ImageCms.createProfile("sRGB")
+            
+            # Perform color transformation (similar to "Convert to Profile" in Photoshop)
+            # This step recalculates pixel values to align with sRGB standards
+            img = ImageCms.profileToProfile(
+                img, 
+                src_profile, 
+                dst_profile, 
+                outputMode='RGB'
+            )
+            print(f"Successfully applied ICC profile from {jpeg_path}")
+        else:
+            print("No ICC profile found, assuming sRGB.")
+            
+    except Exception as e:
+        print(f"Color Management Error: {e}. Returning original raw image.")
+        
+    return img
+
+# --- Example Usage ---
+if __name__ == "__main__":
+    result_img = decode_jpeg_with_color_management('icc_profile.jpg')
+    result_img.show()
+    # result_img.save('output_srgb.jpg', quality=95)
+```
+
 ## High-Precision JPEG Support
 
 PyTurboJPEG 2.0+ supports 12-bit and 16-bit precision JPEG encoding and decoding using libjpeg-turbo 3.0+ APIs. This feature is ideal for medical imaging, scientific photography, and other applications requiring higher bit depth.
@@ -278,7 +350,34 @@ with open('output_12bit.jpg', 'rb') as f:
     decoded_from_file = jpeg.decode_12bit(f.read())
 ```
 
-### 16-bit JPEG (Lossless)
+### Lossless JPEG for 12-bit and 16-bit
+
+12-bit and 16-bit JPEG support lossless compression for perfect reconstruction:
+
+#### 12-bit Lossless JPEG
+
+12-bit precision with lossless compression:
+
+```python
+import numpy as np
+from turbojpeg import TurboJPEG
+
+jpeg = TurboJPEG()
+
+# Create 12-bit image
+img_12bit = np.random.randint(0, 4096, (480, 640, 3), dtype=np.uint16)
+
+# Encode to 12-bit lossless JPEG using encode_12bit() with lossless=True
+jpeg_data = jpeg.encode_12bit(img_12bit, lossless=True)
+
+# Decode using decode_12bit()
+decoded_img = jpeg.decode_12bit(jpeg_data)
+
+# Perfect reconstruction
+assert np.array_equal(img_12bit, decoded_img)  # True
+```
+
+#### 16-bit Lossless JPEG
 
 16-bit JPEG provides the highest precision with perfect reconstruction through lossless compression. The JPEG standard only supports 16-bit for lossless mode.
 
@@ -309,33 +408,6 @@ with open('output_16bit_lossless.jpg', 'rb') as f:
     decoded_from_file = jpeg.decode_16bit(f.read())
 ```
 
-### Lossless JPEG for 12-bit and 16-bit
-
-12-bit and 16-bit JPEG support lossless compression for perfect reconstruction:
-
-#### 12-bit Lossless JPEG
-
-12-bit precision with lossless compression:
-
-```python
-import numpy as np
-from turbojpeg import TurboJPEG
-
-jpeg = TurboJPEG()
-
-# Create 12-bit image
-img_12bit = np.random.randint(0, 4096, (480, 640, 3), dtype=np.uint16)
-
-# Encode to 12-bit lossless JPEG using encode_12bit() with lossless=True
-jpeg_data = jpeg.encode_12bit(img_12bit, lossless=True)
-
-# Decode using decode_12bit()
-decoded_img = jpeg.decode_12bit(jpeg_data)
-
-# Perfect reconstruction
-assert np.array_equal(img_12bit, decoded_img)  # True
-```
-
 ### Medical and Scientific Imaging
 
 For medical and scientific applications, 12-bit JPEG provides excellent precision while maintaining file size efficiency:

{pyturbojpeg-2.1.0 → pyturbojpeg-2.2.0}/PyTurboJPEG.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: PyTurboJPEG
-Version: 2.1.0
+Version: 2.2.0
 Summary: A Python wrapper of libjpeg-turbo for decoding and encoding JPEG image.
 Home-page: https://github.com/lilohuang/PyTurboJPEG
 Author: Lilo Huang
@@ -26,6 +26,11 @@ Dynamic: summary
 
 A Python wrapper for libjpeg-turbo that enables efficient JPEG image decoding and encoding.
 
+[![PyPI Version](https://img.shields.io/pypi/v/pyturbojpeg.svg?style=flat-square&color=blue)](https://pypi.org/project/pyturbojpeg/)
+![Python Version](https://img.shields.io/badge/python-3.6+-blue?logo=python&logoColor=white)
+[![Downloads](https://img.shields.io/pypi/dm/pyturbojpeg.svg?style=flat-square&color=orange)](https://pypistats.org/packages/pyturbojpeg)
+[![License](https://img.shields.io/github/license/lilohuang/PyTurboJPEG.svg?style=flat-square)](https://github.com/lilohuang/PyTurboJPEG/blob/master/LICENSE)
+
 ## Prerequisites
 
 - [libjpeg-turbo](https://github.com/libjpeg-turbo/libjpeg-turbo/releases) **3.0 or later** (required for PyTurboJPEG 2.0+)
@@ -239,6 +244,73 @@ cv2.imshow('transposed_image', transposed_image)
 cv2.waitKey(0)
 ```
 
+### ICC Color Management Workflow
+
+```python
+import io
+import numpy as np
+from PIL import Image, ImageCms
+from turbojpeg import TurboJPEG, TJPF_BGR
+
+def decode_jpeg_with_color_management(jpeg_path):
+    """
+    Decodes a JPEG and applies color management (ICC Profile to sRGB).
+    
+    Args:
+        jpeg_path (str): Path to the input JPEG file.
+        
+    Returns:
+        PIL.Image: The color-corrected sRGB Image object.
+    """
+    # 1. Initialize TurboJPEG
+    jpeg = TurboJPEG()
+    
+    with open(jpeg_path, 'rb') as f:
+        jpeg_data = f.read()
+    
+    # 2. Get image headers and decode pixels
+    # Using TJPF_BGR format (OpenCV standard) for the raw buffer
+    width, height, _, _ = jpeg.decode_header(jpeg_data)
+    pixels = jpeg.decode(jpeg_data, pixel_format=TJPF_BGR)
+    
+    # 3. Encapsulate into a Pillow Image object
+    # Key: Use 'raw' and 'BGR' decoder to correctly map BGR bytes to an RGB Image object
+    img = Image.frombytes('RGB', (width, height), pixels, 'raw', 'BGR')
+    
+    # 4. Handle ICC Profile transformation
+    try:
+        # Extract embedded ICC Profile
+        icc_profile = jpeg.get_icc_profile(jpeg_data)
+        
+        if icc_profile:
+            # Create Source and Destination Profile objects
+            src_profile = ImageCms.getOpenProfile(io.BytesIO(icc_profile))
+            dst_profile = ImageCms.createProfile("sRGB")
+            
+            # Perform color transformation (similar to "Convert to Profile" in Photoshop)
+            # This step recalculates pixel values to align with sRGB standards
+            img = ImageCms.profileToProfile(
+                img, 
+                src_profile, 
+                dst_profile, 
+                outputMode='RGB'
+            )
+            print(f"Successfully applied ICC profile from {jpeg_path}")
+        else:
+            print("No ICC profile found, assuming sRGB.")
+            
+    except Exception as e:
+        print(f"Color Management Error: {e}. Returning original raw image.")
+        
+    return img
+
+# --- Example Usage ---
+if __name__ == "__main__":
+    result_img = decode_jpeg_with_color_management('icc_profile.jpg')
+    result_img.show()
+    # result_img.save('output_srgb.jpg', quality=95)
+```
+
 ## High-Precision JPEG Support
 
 PyTurboJPEG 2.0+ supports 12-bit and 16-bit precision JPEG encoding and decoding using libjpeg-turbo 3.0+ APIs. This feature is ideal for medical imaging, scientific photography, and other applications requiring higher bit depth.
@@ -278,7 +350,34 @@ with open('output_12bit.jpg', 'rb') as f:
     decoded_from_file = jpeg.decode_12bit(f.read())
 ```
 
-### 16-bit JPEG (Lossless)
+### Lossless JPEG for 12-bit and 16-bit
+
+12-bit and 16-bit JPEG support lossless compression for perfect reconstruction:
+
+#### 12-bit Lossless JPEG
+
+12-bit precision with lossless compression:
+
+```python
+import numpy as np
+from turbojpeg import TurboJPEG
+
+jpeg = TurboJPEG()
+
+# Create 12-bit image
+img_12bit = np.random.randint(0, 4096, (480, 640, 3), dtype=np.uint16)
+
+# Encode to 12-bit lossless JPEG using encode_12bit() with lossless=True
+jpeg_data = jpeg.encode_12bit(img_12bit, lossless=True)
+
+# Decode using decode_12bit()
+decoded_img = jpeg.decode_12bit(jpeg_data)
+
+# Perfect reconstruction
+assert np.array_equal(img_12bit, decoded_img)  # True
+```
+
+#### 16-bit Lossless JPEG
 
 16-bit JPEG provides the highest precision with perfect reconstruction through lossless compression. The JPEG standard only supports 16-bit for lossless mode.
 
@@ -309,33 +408,6 @@ with open('output_16bit_lossless.jpg', 'rb') as f:
     decoded_from_file = jpeg.decode_16bit(f.read())
 ```
 
-### Lossless JPEG for 12-bit and 16-bit
-
-12-bit and 16-bit JPEG support lossless compression for perfect reconstruction:
-
-#### 12-bit Lossless JPEG
-
-12-bit precision with lossless compression:
-
-```python
-import numpy as np
-from turbojpeg import TurboJPEG
-
-jpeg = TurboJPEG()
-
-# Create 12-bit image
-img_12bit = np.random.randint(0, 4096, (480, 640, 3), dtype=np.uint16)
-
-# Encode to 12-bit lossless JPEG using encode_12bit() with lossless=True
-jpeg_data = jpeg.encode_12bit(img_12bit, lossless=True)
-
-# Decode using decode_12bit()
-decoded_img = jpeg.decode_12bit(jpeg_data)
-
-# Perfect reconstruction
-assert np.array_equal(img_12bit, decoded_img)  # True
-```
-
 ### Medical and Scientific Imaging
 
 For medical and scientific applications, 12-bit JPEG provides excellent precision while maintaining file size efficiency:

{pyturbojpeg-2.1.0 → pyturbojpeg-2.2.0}/README.md

@@ -2,6 +2,11 @@
 
 A Python wrapper for libjpeg-turbo that enables efficient JPEG image decoding and encoding.
 
+[![PyPI Version](https://img.shields.io/pypi/v/pyturbojpeg.svg?style=flat-square&color=blue)](https://pypi.org/project/pyturbojpeg/)
+![Python Version](https://img.shields.io/badge/python-3.6+-blue?logo=python&logoColor=white)
+[![Downloads](https://img.shields.io/pypi/dm/pyturbojpeg.svg?style=flat-square&color=orange)](https://pypistats.org/packages/pyturbojpeg)
+[![License](https://img.shields.io/github/license/lilohuang/PyTurboJPEG.svg?style=flat-square)](https://github.com/lilohuang/PyTurboJPEG/blob/master/LICENSE)
+
 ## Prerequisites
 
 - [libjpeg-turbo](https://github.com/libjpeg-turbo/libjpeg-turbo/releases) **3.0 or later** (required for PyTurboJPEG 2.0+)
@@ -215,6 +220,73 @@ cv2.imshow('transposed_image', transposed_image)
 cv2.waitKey(0)
 ```
 
+### ICC Color Management Workflow
+
+```python
+import io
+import numpy as np
+from PIL import Image, ImageCms
+from turbojpeg import TurboJPEG, TJPF_BGR
+
+def decode_jpeg_with_color_management(jpeg_path):
+    """
+    Decodes a JPEG and applies color management (ICC Profile to sRGB).
+    
+    Args:
+        jpeg_path (str): Path to the input JPEG file.
+        
+    Returns:
+        PIL.Image: The color-corrected sRGB Image object.
+    """
+    # 1. Initialize TurboJPEG
+    jpeg = TurboJPEG()
+    
+    with open(jpeg_path, 'rb') as f:
+        jpeg_data = f.read()
+    
+    # 2. Get image headers and decode pixels
+    # Using TJPF_BGR format (OpenCV standard) for the raw buffer
+    width, height, _, _ = jpeg.decode_header(jpeg_data)
+    pixels = jpeg.decode(jpeg_data, pixel_format=TJPF_BGR)
+    
+    # 3. Encapsulate into a Pillow Image object
+    # Key: Use 'raw' and 'BGR' decoder to correctly map BGR bytes to an RGB Image object
+    img = Image.frombytes('RGB', (width, height), pixels, 'raw', 'BGR')
+    
+    # 4. Handle ICC Profile transformation
+    try:
+        # Extract embedded ICC Profile
+        icc_profile = jpeg.get_icc_profile(jpeg_data)
+        
+        if icc_profile:
+            # Create Source and Destination Profile objects
+            src_profile = ImageCms.getOpenProfile(io.BytesIO(icc_profile))
+            dst_profile = ImageCms.createProfile("sRGB")
+            
+            # Perform color transformation (similar to "Convert to Profile" in Photoshop)
+            # This step recalculates pixel values to align with sRGB standards
+            img = ImageCms.profileToProfile(
+                img, 
+                src_profile, 
+                dst_profile, 
+                outputMode='RGB'
+            )
+            print(f"Successfully applied ICC profile from {jpeg_path}")
+        else:
+            print("No ICC profile found, assuming sRGB.")
+            
+    except Exception as e:
+        print(f"Color Management Error: {e}. Returning original raw image.")
+        
+    return img
+
+# --- Example Usage ---
+if __name__ == "__main__":
+    result_img = decode_jpeg_with_color_management('icc_profile.jpg')
+    result_img.show()
+    # result_img.save('output_srgb.jpg', quality=95)
+```
+
 ## High-Precision JPEG Support
 
 PyTurboJPEG 2.0+ supports 12-bit and 16-bit precision JPEG encoding and decoding using libjpeg-turbo 3.0+ APIs. This feature is ideal for medical imaging, scientific photography, and other applications requiring higher bit depth.
@@ -254,7 +326,34 @@ with open('output_12bit.jpg', 'rb') as f:
     decoded_from_file = jpeg.decode_12bit(f.read())
 ```
 
-### 16-bit JPEG (Lossless)
+### Lossless JPEG for 12-bit and 16-bit
+
+12-bit and 16-bit JPEG support lossless compression for perfect reconstruction:
+
+#### 12-bit Lossless JPEG
+
+12-bit precision with lossless compression:
+
+```python
+import numpy as np
+from turbojpeg import TurboJPEG
+
+jpeg = TurboJPEG()
+
+# Create 12-bit image
+img_12bit = np.random.randint(0, 4096, (480, 640, 3), dtype=np.uint16)
+
+# Encode to 12-bit lossless JPEG using encode_12bit() with lossless=True
+jpeg_data = jpeg.encode_12bit(img_12bit, lossless=True)
+
+# Decode using decode_12bit()
+decoded_img = jpeg.decode_12bit(jpeg_data)
+
+# Perfect reconstruction
+assert np.array_equal(img_12bit, decoded_img)  # True
+```
+
+#### 16-bit Lossless JPEG
 
 16-bit JPEG provides the highest precision with perfect reconstruction through lossless compression. The JPEG standard only supports 16-bit for lossless mode.
 
@@ -285,33 +384,6 @@ with open('output_16bit_lossless.jpg', 'rb') as f:
     decoded_from_file = jpeg.decode_16bit(f.read())
 ```
 
-### Lossless JPEG for 12-bit and 16-bit
-
-12-bit and 16-bit JPEG support lossless compression for perfect reconstruction:
-
-#### 12-bit Lossless JPEG
-
-12-bit precision with lossless compression:
-
-```python
-import numpy as np
-from turbojpeg import TurboJPEG
-
-jpeg = TurboJPEG()
-
-# Create 12-bit image
-img_12bit = np.random.randint(0, 4096, (480, 640, 3), dtype=np.uint16)
-
-# Encode to 12-bit lossless JPEG using encode_12bit() with lossless=True
-jpeg_data = jpeg.encode_12bit(img_12bit, lossless=True)
-
-# Decode using decode_12bit()
-decoded_img = jpeg.decode_12bit(jpeg_data)
-
-# Perfect reconstruction
-assert np.array_equal(img_12bit, decoded_img)  # True
-```
-
 ### Medical and Scientific Imaging
 
 For medical and scientific applications, 12-bit JPEG provides excellent precision while maintaining file size efficiency:

{pyturbojpeg-2.1.0 → pyturbojpeg-2.2.0}/setup.py

@@ -2,7 +2,7 @@ import io
 from setuptools import setup, find_packages
 setup(
     name='PyTurboJPEG',
-    version='2.1.0',
+    version='2.2.0',
     description='A Python wrapper of libjpeg-turbo for decoding and encoding JPEG image.',
     author='Lilo Huang',
     author_email='kuso.cc@gmail.com',

{pyturbojpeg-2.1.0 → pyturbojpeg-2.2.0}/tests/test_turbojpeg.py

@@ -30,7 +30,8 @@ from turbojpeg import (
     TJSAMP_444, TJSAMP_422, TJSAMP_420, TJSAMP_GRAY, TJSAMP_440, TJSAMP_411,
     TJCS_RGB, TJCS_YCbCr, TJCS_GRAY,
     TJFLAG_PROGRESSIVE, TJFLAG_FASTUPSAMPLE, TJFLAG_FASTDCT,
-    TJPRECISION_8, TJPRECISION_12, TJPRECISION_16
+    TJPRECISION_8, TJPRECISION_12, TJPRECISION_16,
+    TJPARAM_SAVEMARKERS
 )
 
 
@@ -1802,5 +1803,65 @@ class TestLosslessJPEG:
         assert np.array_equal(img_gray, decoded_gray), "Lossless grayscale should be perfect"
 
 
+import struct
+
+def _make_minimal_srgb_icc():
+    """Build a minimal but structurally valid ICC profile for sRGB."""
+    profile = bytearray(132)
+    struct.pack_into('>I', profile, 0, 132)
+    struct.pack_into('>I', profile, 8, 0x02100000)
+    profile[12:16] = b'mntr'
+    profile[16:20] = b'RGB '
+    profile[20:24] = b'XYZ '
+    profile[36:40] = b'acsp'
+    return bytes(profile)
+
+MINIMAL_SRGB_ICC = _make_minimal_srgb_icc()
+
+
+class TestICCProfile:
+    """Test ICC profile embed/extract functionality (requires TurboJPEG 3.1+)."""
+
+    @pytest.fixture(autouse=True)
+    def require_icc_support(self, jpeg_instance):
+        """Skip the test if the loaded libturbojpeg does not support ICC profiles."""
+        try:
+            jpeg_instance.get_icc_profile(b'\xff\xd8\xff\xd9')
+        except NotImplementedError as e:
+            pytest.skip(str(e))
+        except (OSError, Exception):
+            pass  # Header parse error is fine — the function exists
+
+    def test_get_icc_profile_with_embedded_profile(self, jpeg_instance, sample_bgr_image):
+        """Test that get_icc_profile returns non-empty bytes for a JPEG with ICC profile."""
+        jpeg_with_icc = jpeg_instance.encode(
+            sample_bgr_image, quality=85, icc_profile=MINIMAL_SRGB_ICC)
+        icc = jpeg_instance.get_icc_profile(jpeg_with_icc)
+        assert icc is not None, "Expected ICC profile but got None"
+        assert isinstance(icc, bytes), "ICC profile should be bytes"
+        assert len(icc) > 0, "ICC profile should be non-empty"
+        assert icc == MINIMAL_SRGB_ICC, "Extracted ICC profile should match embedded profile"
+
+    def test_get_icc_profile_without_profile(self, jpeg_instance, sample_bgr_image):
+        """Test that get_icc_profile returns None for a JPEG without ICC profile."""
+        jpeg_without_icc = jpeg_instance.encode(sample_bgr_image, quality=85)
+        icc = jpeg_instance.get_icc_profile(jpeg_without_icc)
+        assert icc is None, \
+            "Expected None for JPEG without ICC profile"
+
+    def test_icc_profile_roundtrip(self, jpeg_instance, sample_bgr_image):
+        """Test ICC profile survives a full encode→decode_header roundtrip."""
+        jpeg_data = jpeg_instance.encode(
+            sample_bgr_image, quality=95,
+            jpeg_subsample=TJSAMP_444,
+            icc_profile=MINIMAL_SRGB_ICC)
+        assert jpeg_data is not None
+        assert len(jpeg_data) > 0
+        extracted_icc = jpeg_instance.get_icc_profile(jpeg_data)
+        assert extracted_icc is not None, "ICC profile missing after roundtrip"
+        assert extracted_icc == MINIMAL_SRGB_ICC, \
+            f"ICC profile mismatch: expected {len(MINIMAL_SRGB_ICC)} bytes, got {len(extracted_icc) if extracted_icc else 0}"
+
+
 if __name__ == '__main__':
     pytest.main([__file__, '-v'])

{pyturbojpeg-2.1.0 → pyturbojpeg-2.2.0}/turbojpeg.py

@@ -23,7 +23,7 @@
 # SOFTWARE.
 
 __author__ = 'Lilo Huang <kuso.cc@gmail.com>'
-__version__ = '2.1.0'
+__version__ = '2.2.0'
 
 from ctypes import *
 from ctypes.util import find_library
@@ -192,6 +192,7 @@ TJPARAM_YDENSITY = 21
 TJPARAM_DENSITYUNITS = 22
 TJPARAM_MAXPIXELS = 23
 TJPARAM_MAXMEMORY = 24
+TJPARAM_SAVEMARKERS = 25
 
 class CroppingRegion(Structure):
     _fields_ = [("x", c_int), ("y", c_int), ("w", c_int), ("h", c_int)]
@@ -328,14 +329,12 @@ def fill_background(coeffs_ptr, arrayRegion, planeRegion, componentID, transform
 
     return 1
 
-
 def split_byte_into_nibbles(value):
     """Split byte int into 2 nibbles (4 bits)."""
     first = value >> 4
     second = value & 0x0F
     return first, second
 
-
 class TurboJPEG(object):
     """A Python wrapper of libjpeg-turbo for decoding and encoding JPEG image."""
     def __init__(self, lib_path=None):
@@ -489,6 +488,17 @@ class TurboJPEG(object):
         self.__decompress16.argtypes = [
             c_void_p, POINTER(c_ubyte), c_size_t, POINTER(c_ushort), c_int, c_int]
         self.__decompress16.restype = c_int
+
+        # tjGetScalingFactors
+        get_scaling_factors = turbo_jpeg.tjGetScalingFactors
+        get_scaling_factors.argtypes = [POINTER(c_int)]
+        get_scaling_factors.restype = POINTER(ScalingFactor)
+        num_scaling_factors = c_int()
+        scaling_factors = get_scaling_factors(byref(num_scaling_factors))
+        self.__scaling_factors = frozenset(
+            (scaling_factors[i].num, scaling_factors[i].denom)
+            for i in range(num_scaling_factors.value)
+        )
         
         # tj3CompressFromYUV16 - compress 16-bit YUV to JPEG (TurboJPEG 3.1+)
         # These functions may not be available in all TurboJPEG 3.x versions
@@ -519,16 +529,21 @@ class TurboJPEG(object):
         except AttributeError:
             self.__decompressToYUVPlanes16 = None
 
-        # tjGetScalingFactors - still the current API in 3.1.x
-        get_scaling_factors = turbo_jpeg.tjGetScalingFactors
-        get_scaling_factors.argtypes = [POINTER(c_int)]
-        get_scaling_factors.restype = POINTER(ScalingFactor)
-        num_scaling_factors = c_int()
-        scaling_factors = get_scaling_factors(byref(num_scaling_factors))
-        self.__scaling_factors = frozenset(
-            (scaling_factors[i].num, scaling_factors[i].denom)
-            for i in range(num_scaling_factors.value)
-        )
+        # tj3GetICCProfile - retrieve ICC profile from decompressor after header parsing (TurboJPEG 3.1+)
+        try:
+            self.__get_icc_profile = turbo_jpeg.tj3GetICCProfile
+            self.__get_icc_profile.argtypes = [c_void_p, POINTER(c_void_p), POINTER(c_size_t)]
+            self.__get_icc_profile.restype = c_int
+        except AttributeError:
+            self.__get_icc_profile = None
+
+        # tj3SetICCProfile - attach ICC profile to compressor before compression (TurboJPEG 3.1+)
+        try:
+            self.__set_icc_profile = turbo_jpeg.tj3SetICCProfile
+            self.__set_icc_profile.argtypes = [c_void_p, c_void_p, c_size_t]
+            self.__set_icc_profile.restype = c_int
+        except AttributeError:
+            self.__set_icc_profile = None
 
     def decode_header(self, jpeg_buf, return_precision=False):
         """decodes JPEG header and returns image properties as a tuple.
@@ -592,6 +607,101 @@ class TurboJPEG(object):
         finally:
             self.__destroy(handle)
 
+    def get_icc_profile(self, jpeg_buf):
+        """Extracts the embedded ICC color profile from a JPEG image.
+
+        Requires TurboJPEG 3.1 or later with tj3GetICCProfile support.
+
+        Parameters
+        ----------
+        jpeg_buf : bytes
+            JPEG image data buffer containing an embedded ICC profile.
+
+        Returns
+        -------
+        bytes or None
+            Raw ICC profile data as a bytes object, or None if no ICC profile
+            is present in the JPEG stream.
+
+        Raises
+        ------
+        OSError
+            If the JPEG header cannot be parsed or a fatal error occurs.
+        NotImplementedError
+            If the loaded libturbojpeg does not export tj3GetICCProfile.
+
+        Examples
+        --------
+        >>> jpeg = TurboJPEG()
+        >>> with open('photo_with_icc.jpg', 'rb') as f:
+        ...     data = f.read()
+        >>> icc = jpeg.get_icc_profile(data)
+        >>> if icc:
+        ...     print(f'ICC profile size: {len(icc)} bytes')
+        """
+        if self.__get_icc_profile is None:
+            raise NotImplementedError(
+                'tj3GetICCProfile is not available in the loaded libturbojpeg. '
+                'Please upgrade to libjpeg-turbo 3.1 or later.')
+        handle = self.__init(TJINIT_DECOMPRESS)
+        try:
+            # Set TJPARAM_SAVEMARKERS to 2 (APP2) so the decompressor
+            # retains ICC profile markers during header parsing.
+            if self.__set(handle, TJPARAM_SAVEMARKERS, 2) != 0:
+                self.__report_error(handle)
+            jpeg_array = np.frombuffer(jpeg_buf, dtype=np.uint8)
+            src_addr = self.__getaddr(jpeg_array)
+            status = self.__decompress_header(handle, src_addr, jpeg_array.size)
+            if status != 0:
+                self.__report_error(handle)
+            icc_buf = c_void_p()
+            icc_size = c_size_t()
+            status = self.__get_icc_profile(handle, byref(icc_buf), byref(icc_size))
+            if status != 0:
+                # A non-fatal return (e.g. no profile present) should return None
+                err_code = self.__get_error_code(handle)
+                if err_code == TJERR_WARNING:
+                    return None
+                self.__report_error(handle)
+            if icc_buf.value is None or icc_size.value == 0:
+                return None
+            result = self.__copy_from_buffer(icc_buf.value, icc_size.value)
+            self.__free(icc_buf)
+            return result
+        finally:
+            self.__destroy(handle)
+
+    def set_icc_profile(self, handle, icc_buf):
+        """Attaches an ICC color profile to an active compressor handle.
+
+        This is a low-level helper intended for use when building custom
+        compression pipelines. In most cases, use encode() with the
+        icc_profile parameter instead.
+
+        Parameters
+        ----------
+        handle : ctypes void pointer
+            An active TurboJPEG compressor handle (TJINIT_COMPRESS).
+        icc_buf : bytes
+            Raw ICC profile data to embed.
+
+        Raises
+        ------
+        OSError
+            If tj3SetICCProfile returns a non-zero status.
+        NotImplementedError
+            If the loaded libturbojpeg does not export tj3SetICCProfile.
+        """
+        if self.__set_icc_profile is None:
+            raise NotImplementedError(
+                'tj3SetICCProfile is not available in the loaded libturbojpeg. '
+                'Please upgrade to libjpeg-turbo 3.1 or later.')
+        icc_array = np.frombuffer(icc_buf, dtype=np.uint8)
+        icc_addr = self.__getaddr(icc_array)
+        status = self.__set_icc_profile(handle, icc_addr, len(icc_buf))
+        if status != 0:
+            self.__report_error(handle)
+
     def decode(self, jpeg_buf, pixel_format=TJPF_BGR, scaling_factor=None, flags=0, dst=None):
         """decodes JPEG memory buffer to numpy array.
         
@@ -707,7 +817,7 @@ class TurboJPEG(object):
         finally:
             self.__destroy(handle)
 
-    def encode(self, img_array, quality=85, pixel_format=TJPF_BGR, jpeg_subsample=TJSAMP_422, flags=0, dst=None, lossless=False):
+    def encode(self, img_array, quality=85, pixel_format=TJPF_BGR, jpeg_subsample=TJSAMP_422, flags=0, dst=None, lossless=False, icc_profile=None):
         """encodes numpy array to JPEG memory buffer.
         
         Parameters
@@ -729,6 +839,9 @@ class TurboJPEG(object):
             When True, provides perfect reconstruction with larger file sizes.
             Note: quality and jpeg_subsample parameters are ignored in lossless mode;
             subsampling is automatically set to 4:4:4 by the library.
+        icc_profile : bytes or None
+            Raw ICC profile data to embed in the JPEG (optional).
+            Requires TurboJPEG 3.1 or later with tj3SetICCProfile support.
             
         Returns
         -------
@@ -763,6 +876,9 @@ class TurboJPEG(object):
             if img_array.dtype != np.uint8:
                 raise ValueError('encode() requires uint8 array (values 0-255); use encode_12bit() for 12-bit images (uint16, 0-4095) or encode_16bit() for 16-bit images (uint16, 0-65535)')
             
+            if icc_profile is not None:
+                self.set_icc_profile(handle, icc_profile)
+            
             if dst is not None and not self.__is_buffer(dst):
                 raise TypeError('\'dst\' argument must support buffer protocol')
             if (dst is not None and