README

PHP library for profiled conversion between CMYK and RGB using ICC profiles. Transformation is performed by a native helper (LittleCMS / lcms2); this library invokes it and integrates the WWAZ packages for color models and profiles.

Requirements

• PHP 8.0+ (union types in the public API)
• Composer dependencies:
  • wwaz/colorprofile-php – ICC profiles and resolution by name
  • wwaz/colormodel-php – CMYK, CMYKInt, RGB, HEX, …
• A matching helper binary under bin/ (see below) or an override via the COLORCONVERT_BINARY environment variable (path to the colorconvert executable).

Helper binary and system libraries

• macOS: The bundled bin/colorconvert-macos is typically linked dynamically against Little CMS. A binary committed to the repository may contain a fixed load path (e.g. Apple Silicon/Homebrew); for distribution or other machines, rebuild locally (see bin/info.md, brew install little-cms2).
• Linux (x86_64 / aarch64): Prebuilt bin/colorconvert-linux-* files are included in the repository (dynamic linking against Little CMS 2 / liblcms2, built with a Debian Bookworm Docker image). The target system needs liblcms2-2 (e.g. Debian/Ubuntu: apt-get install liblcms2-2). To refresh the binaries, see bin/build.sh and .github/workflows/linux-binaries.yml.
• For build details, see bin/info.md.

Installation

composer require wwaz/colorconvert-php

For local development, repositories may be registered in composer.json via VCS (dev-main).

Optional: custom path to the binary (e.g. without a bundled file):

export COLORCONVERT_BINARY=/usr/local/bin/colorconvert

Setting ICC profiles

use wwaz\Colorconvert\Convert;

Convert::setCMYKProfile('CoatedFOGRA39');
Convert::setRGBProfile('sRGB2014');
Convert::setIntent('perceptual'); // optional: perceptual, relative (default), saturation, absolute

Available profile names depend on the configuration of wwaz/colorprofile-php and the ICC files provided.

Usage

CMYK → RGB

use wwaz\Colorconvert\Convert;
use wwaz\Colormodel\Model\CMYKInt;

$rgb = Convert::toRGB(100, 0, 0, 0);
$rgb = Convert::toRGB([100, 0, 0, 0]);
$rgb = Convert::toRGB(new CMYKInt([100, 0, 0, 0]));

Return type: wwaz\Colormodel\Model\RGB.

RGB / HEX → CMYK

use wwaz\Colorconvert\Convert;

$cmyk = Convert::toCMYK(255, 0, 0);
$cmyk = Convert::toCMYK([255, 0, 0]);
$cmyk = Convert::toCMYK(new \wwaz\Colormodel\Model\Hex('f00'));

Return type: wwaz\Colormodel\Model\CMYKInt.

Errors

On failed conversion, wwaz\Colorconvert\Exceptions\ColorconversionException is thrown.

Technical notes

• Rendering intent: configurable via Convert::setIntent() (perceptual, relative, saturation, absolute); default is relative.
• Platform: Depending on OS/architecture, one of colorconvert-macos, colorconvert-linux-x86_64, colorconvert-linux-arm64, or colorconvert is chosen (see src/Convert.php).

Building the binary

See bin/info.md, bin/build.sh, and bin/Dockerfile.

Tests

composer test

License and third-party content

This documentation is not a substitute for individual legal advice.

• PHP/project license: MIT (LICENSE; see also composer.json).
• Little CMS 2 (LGPL 2.1) and further notes on ICC profiles and Composer packages: THIRD_PARTY_NOTICES.md.
• LGPL 2.1 license text (reference copy): licenses/lgpl-2.1.txt.