iccdev 0.1.0__cp313-cp313-win_amd64.whl

iccdev/__init__.py

@@ -0,0 +1,110 @@
+# iccdev - Python bindings for RefIccMAX / iccDEV
+#
+# Copyright (c) International Color Consortium.
+# BSD 3-Clause License. See LICENSE.md for details.
+
+"""
+Python bindings for the RefIccMAX (iccDEV) ICC color profile library.
+
+Provides Pythonic access to ICC profile reading, color management,
+and color space transformations via Cython wrappers around IccProfLib.
+
+Quick start::
+
+    import iccdev
+
+    # Read a profile
+    profile = iccdev.IccProfile("sRGB.icc")
+    header = profile.header
+    print(header.version_string)
+
+    # Apply a color transform
+    cmm = iccdev.IccCmm()
+    cmm.attach("input.icc", intent=iccdev.Intent.Perceptual)
+    cmm.attach("output.icc")
+    cmm.begin()
+    result = cmm.apply([0.5, 0.3, 0.1])
+"""
+
+__version__ = "0.1.0"
+
+from iccdev._iccdev import (
+    # Classes
+    IccProfile,
+    IccCmm,
+    IccApply,
+    IccProfileHeader,
+    ValidationResult,
+    # Exceptions
+    IccError,
+    IccProfileError,
+    IccCmmError,
+    # Enums
+    ColorSpace,
+    ProfileClass,
+    RenderingIntent,
+    Interpolation,
+    LutType,
+    CmmStatus,
+    ValidationStatus,
+    # Convenience functions
+    sig_to_str,
+    open_profile,
+    read_profile,
+    validate_profile,
+    validate_profile_file,
+)
+from iccdev.cli import (
+    IccToolError,
+    available_tools,
+    dump_profile,
+    find_tool,
+    heif_dump,
+    icc_from_json,
+    icc_from_xml,
+    icc_to_json,
+    icc_to_xml,
+    round_trip,
+)
+
+# Short alias for RenderingIntent
+Intent = RenderingIntent
+
+__all__ = [
+    # Classes
+    "IccProfile",
+    "IccCmm",
+    "IccApply",
+    "IccProfileHeader",
+    "ValidationResult",
+    # Exceptions
+    "IccError",
+    "IccProfileError",
+    "IccCmmError",
+    # Enums
+    "ColorSpace",
+    "ProfileClass",
+    "RenderingIntent",
+    "Intent",
+    "Interpolation",
+    "LutType",
+    "CmmStatus",
+    "ValidationStatus",
+    # Functions
+    "sig_to_str",
+    "open_profile",
+    "read_profile",
+    "validate_profile",
+    "validate_profile_file",
+    # CLI-backed helpers
+    "IccToolError",
+    "available_tools",
+    "find_tool",
+    "heif_dump",
+    "icc_to_xml",
+    "icc_from_xml",
+    "icc_to_json",
+    "icc_from_json",
+    "dump_profile",
+    "round_trip",
+]

iccdev/_iccdev.pyi

@@ -0,0 +1,299 @@
+"""Type stubs for iccdev._iccdev (Cython extension)."""
+
+from __future__ import annotations
+
+import enum
+import os
+from collections.abc import Sequence
+from typing import NamedTuple, Optional, Union
+
+# NumPy is optional
+try:
+    import numpy as np
+    import numpy.typing as npt
+except ImportError:
+    np = None  # type: ignore[assignment]
+    npt = None  # type: ignore[assignment]
+
+
+# ---------------------------------------------------------------------------
+# Enums
+# ---------------------------------------------------------------------------
+
+class ColorSpace(enum.IntEnum):
+    XYZ = ...
+    Lab = ...
+    Luv = ...
+    YCbCr = ...
+    Yxy = ...
+    RGB = ...
+    Gray = ...
+    HSV = ...
+    HLS = ...
+    CMYK = ...
+    CMY = ...
+    CLR1 = ...
+    CLR2 = ...
+    CLR3 = ...
+    CLR4 = ...
+    CLR5 = ...
+    CLR6 = ...
+    CLR7 = ...
+    CLR8 = ...
+    CLR9 = ...
+    CLR10 = ...
+    CLR11 = ...
+    CLR12 = ...
+    CLR13 = ...
+    CLR14 = ...
+    CLR15 = ...
+    Named = ...
+    NChannel = ...
+    DevLab = ...
+    DevXYZ = ...
+    Gamut = ...
+    Unknown = ...
+
+    @classmethod
+    def from_sig(cls, sig: int) -> ColorSpace: ...
+
+class ProfileClass(enum.IntEnum):
+    Input = ...
+    Display = ...
+    Output = ...
+    Link = ...
+    Abstract = ...
+    ColorSpace = ...
+    NamedColor = ...
+    ColorEncoding = ...
+    MaterialID = ...
+    MaterialLink = ...
+    MaterialVis = ...
+
+class RenderingIntent(enum.IntEnum):
+    Perceptual = ...
+    RelativeColorimetric = ...
+    Saturation = ...
+    AbsoluteColorimetric = ...
+
+Intent = RenderingIntent
+
+class Interpolation(enum.IntEnum):
+    Linear = ...
+    Tetrahedral = ...
+
+class LutType(enum.IntEnum):
+    Color = ...
+    NamedColor = ...
+    Preview = ...
+    Gamut = ...
+    BPC = ...
+    BRDFParam = ...
+    BRDFDirect = ...
+    BRDFMcsParam = ...
+    MCS = ...
+    Colorimetric = ...
+    Spectral = ...
+
+class CmmStatus(enum.IntEnum):
+    Bad = ...
+    Ok = ...
+    CantOpenProfile = ...
+    BadSpaceLink = ...
+    InvalidProfile = ...
+    BadXform = ...
+    InvalidLut = ...
+    ProfileMissingTag = ...
+    ColorNotFound = ...
+    IncorrectApply = ...
+    BadColorEncoding = ...
+    AllocErr = ...
+    BadLutType = ...
+    IdentityXform = ...
+    UnsupportedPcsLink = ...
+    BadConnection = ...
+    BadTintXform = ...
+    TooManySamples = ...
+    BadMCSLink = ...
+    Unsupported = ...
+    UnsupportedProfileClass = ...
+    CantAdjustPcs = ...
+
+class ValidationStatus(enum.IntEnum):
+    OK = ...
+    WARNING = ...
+    NON_COMPLIANT = ...
+    CRITICAL_ERROR = ...
+    INVALID_ARGUMENT = ...
+    INTERNAL_ERROR = ...
+
+class ValidationResult(NamedTuple):
+    status: ValidationStatus
+    report: str
+
+
+# ---------------------------------------------------------------------------
+# Exceptions
+# ---------------------------------------------------------------------------
+
+class IccError(Exception):
+    status: int
+    status_code: int  # backward compat alias
+    status_name: str
+    def __init__(self, message: str, status: int = -1) -> None: ...
+
+class IccProfileError(IccError): ...
+class IccCmmError(IccError): ...
+
+
+# ---------------------------------------------------------------------------
+# IccProfileHeader (named tuple)
+# ---------------------------------------------------------------------------
+
+class IccProfileHeader(NamedTuple):
+    size: int
+    cmm_id: int
+    version: int
+    device_class: int
+    color_space: int
+    pcs: int
+    date: dict[str, int]
+    magic: int
+    platform: int
+    flags: int
+    manufacturer: int
+    model: int
+    attributes: int
+    rendering_intent: int
+    illuminant: dict[str, float]
+    creator: int
+    profile_id: bytes
+    spectral_pcs: int
+    spectral_range: dict[str, int]
+    bi_spectral_range: dict[str, int]
+    mcs: int
+    device_sub_class: int
+
+    @property
+    def version_string(self) -> str: ...
+    @property
+    def color_space_name(self) -> str: ...
+    @property
+    def pcs_name(self) -> str: ...
+    @property
+    def device_class_name(self) -> str: ...
+    @property
+    def rendering_intent_name(self) -> str: ...
+    @property
+    def platform_name(self) -> str: ...
+
+
+# ---------------------------------------------------------------------------
+# IccProfile
+# ---------------------------------------------------------------------------
+
+class IccProfile:
+    def __init__(self, path: Optional[Union[str, bytes, os.PathLike[str], os.PathLike[bytes]]] = None, *, lazy: bool = True) -> None: ...
+    def close(self) -> None: ...
+    def __enter__(self) -> IccProfile: ...
+    def __exit__(self, exc_type: object, exc_val: object, exc_tb: object) -> bool: ...
+    def __bool__(self) -> bool: ...
+
+    @property
+    def is_valid(self) -> bool: ...
+    @property
+    def header(self) -> IccProfileHeader: ...
+    @property
+    def color_space(self) -> ColorSpace: ...
+    @property
+    def pcs(self) -> ColorSpace: ...
+    @property
+    def device_class(self) -> Union[ProfileClass, int]: ...
+    @property
+    def version_string(self) -> str: ...
+    @property
+    def is_v5(self) -> bool: ...
+
+
+# ---------------------------------------------------------------------------
+# IccApply
+# ---------------------------------------------------------------------------
+
+class IccApply:
+    def close(self) -> None: ...
+    def __enter__(self) -> IccApply: ...
+    def __exit__(self, exc_type: object, exc_val: object, exc_tb: object) -> bool: ...
+    def __bool__(self) -> bool: ...
+
+    def apply(self, pixel: Sequence[float]) -> list[float]: ...
+    def apply_multi(self, pixels: Sequence[Sequence[float]]) -> list[list[float]]: ...
+    def apply_ndarray(self, pixels: np.ndarray) -> np.ndarray: ...
+
+    @property
+    def src_channels(self) -> int: ...
+    @property
+    def dst_channels(self) -> int: ...
+
+
+# ---------------------------------------------------------------------------
+# IccCmm
+# ---------------------------------------------------------------------------
+
+class IccCmm:
+    def __init__(
+        self,
+        src_space: Union[ColorSpace, int] = ...,
+        dst_space: Union[ColorSpace, int] = ...,
+        first_is_input: bool = True,
+    ) -> None: ...
+
+    def close(self) -> None: ...
+    def __enter__(self) -> IccCmm: ...
+    def __exit__(self, exc_type: object, exc_val: object, exc_tb: object) -> bool: ...
+    def __bool__(self) -> bool: ...
+
+    def attach(
+        self,
+        path: Union[str, bytes, os.PathLike[str], os.PathLike[bytes]],
+        *,
+        intent: Union[RenderingIntent, int] = ...,
+        interp: Union[Interpolation, int] = ...,
+        lut_type: Union[LutType, int] = ...,
+        use_d2b: bool = True,
+        use_bpc: bool = False,
+    ) -> None: ...
+
+    def attach_profile(
+        self,
+        path: Union[str, bytes, os.PathLike[str], os.PathLike[bytes]],
+        **kwargs: object,
+    ) -> None: ...
+
+    def begin(self) -> None: ...
+    def get_apply(self) -> IccApply: ...
+
+    def apply(self, pixel: Sequence[float]) -> list[float]: ...
+    def apply_multi(self, pixels: Sequence[Sequence[float]]) -> list[list[float]]: ...
+    def apply_ndarray(self, pixels: np.ndarray) -> np.ndarray: ...
+
+    @property
+    def src_space(self) -> ColorSpace: ...
+    @property
+    def dst_space(self) -> ColorSpace: ...
+    @property
+    def src_channels(self) -> int: ...
+    @property
+    def dst_channels(self) -> int: ...
+    @property
+    def is_ready(self) -> bool: ...
+
+
+# ---------------------------------------------------------------------------
+# Module-level functions
+# ---------------------------------------------------------------------------
+
+def sig_to_str(sig: int) -> str: ...
+def open_profile(path: Union[str, bytes, os.PathLike[str], os.PathLike[bytes]], *, lazy: bool = True) -> IccProfile: ...
+def read_profile(path: Union[str, bytes, os.PathLike[str], os.PathLike[bytes]]) -> IccProfile: ...
+def validate_profile(profile: Union[bytes, bytearray, memoryview]) -> ValidationResult: ...
+def validate_profile_file(path: Union[str, bytes, os.PathLike[str], os.PathLike[bytes]]) -> ValidationResult: ...