README

Convert colors between RGB and CMYK using real ICC profiles — not just math formulas.

This library is useful when screen colors and print colors should match as closely as possible. It also returns a perception preview (what the color may look like after a print roundtrip), a color name, and optional color schemes.

Input types: rgb, cmyk, hex.

Use cases

1. Turn a screen color into print-ready CMYK

You have an RGB color from a website or design tool. You need CMYK values for a print workflow.

use wwaz\ColorBridge\Color\RGB;
use wwaz\ColorBridge\Bridge\Bridge;

$bridge = new Bridge(new RGB('255,0,0'));

$result = $bridge->profiled(
    rgbProfile: 'sRGB_v4_ICC_preference',
    cmykProfile: 'ISOcoated_v2_300_eci',
);

echo $result->cmyk();           // e.g. "0,100,100,0"
echo $result->hexPerception();  // how it may look on screen after conversion

2. Convert a print color back to RGB for the screen

A designer gives you CMYK values from a print proof. You want to show them on a website.

use wwaz\ColorBridge\Color\CMYK;
use wwaz\ColorBridge\Bridge\Bridge;

$bridge = new Bridge(new CMYK('53,0,60,29'));
$bridge->setProfile('rgb', 'sRGB_v4_ICC_preference');
$bridge->setProfile('cmyk', 'ISOcoated_v2_300_eci');

$data = $bridge->convert()->toArray();

echo $data['perception']['hex']; // screen preview
echo $data['name'];              // closest color name

3. Build a color picker API from request strings

You receive color type, value, and profile names from an HTTP request. Pass explicit values, or rely on BridgeConfig defaults.

use wwaz\ColorBridge\BridgeConfig;
use wwaz\ColorBridge\BridgeService;

$config = BridgeConfig::fromArray([
    'workingColorSpaces' => [
        'rgb' => 'sRGB_v4_ICC_preference',
        'cmyk' => 'ISOcoated_v2_300_eci',
    ],
    'defaultIntent' => 'relative',
]);

$service = new BridgeService(
    colortype: 'hex',
    colorvalue: 'f00',
    rgbProfile: 'sRGB_v4_ICC_preference',
    cmykProfile: 'ISOcoated_v2_300_eci',
    intent: 'relative',
    config: $config,
);

$response = $service->convert()->toArray();

Or omit profiles entirely and use library defaults:

$service = new BridgeService(colortype: 'hex', colorvalue: 'f00');

4. Return color schemes for a brand color

Generate complementary, triadic, tint, shade, and other palettes — with ICC-aware values when profiles are set.

use wwaz\ColorBridge\Color\RGB;
use wwaz\ColorBridge\Bridge\Bridge;

$bridge = new Bridge(new RGB('0,158,227'));
$bridge->setProfile('rgb', 'sRGB_v4_ICC_preference');
$bridge->setProfile('cmyk', 'ISOcoated_v2_300_eci');

$bridge->convert();
$schemes = $bridge->schemes(profiled: true);

// $schemes['complementary'], $schemes['triadic'], $schemes['tint'], ...

Or include schemes directly in the convert response:

$data = $bridge->profiled(
    'sRGB_v4_ICC_preference',
    'ISOcoated_v2_300_eci',
    includeSchemes: true,
)->toArray();

5. Low-level ICC conversion only

You only need RGB ↔ CMYK conversion, without names or schemes.

use wwaz\ColorBridge\Color\CMYK;
use wwaz\ColorBridge\Color\RGB;
use wwaz\ColorBridge\Bridge\ProfileConverter;

$converter = new ProfileConverter();
$converter->setProfile('rgb', 'sRGB_v4_ICC_preference');
$converter->setProfile('cmyk', 'ISOcoated_v2_300_eci');

$cmyk = $converter->rgbToCmyk(new RGB('255,0,0'));
$rgb  = $converter->cmykToRgb(new CMYK('0,100,100,0'));

Installation

composer require wwaz/colorbridge-php

Dependencies (all on Packagist):

• wwaz/colorconvert-php
• wwaz/colorprofile-php
• wwaz/colormodel-php
• wwaz/colorname-php

ICC profiles setup

Profile names like sRGB_v4_ICC_preference are resolved through wwaz/colorprofile-php. Before first use, install profiles once:

vendor/bin/colorprofile init
vendor/bin/colorprofile install sRGB_v4_ICC_preference ISOcoated_v2_300_eci

Main classes

Rendering intent

The rendering intent tells the ICC engine how to map colors when the source and target profile cannot represent the same colors. Think of it as a strategy for handling out-of-gamut colors.

Supported values:

• relative (default)
• perceptual
• saturation
• absolute

$bridge->setIntent('perceptual');

Which intent should I use?

Quick decision guide

• Picking a brand color for a flyer or business card? → start with relative
• Converting a product photo for a catalog? → try perceptual
• Building a presentation with strong chart colors? → try saturation
• Checking how a print proof should look on screen? → consider absolute

If the result looks too dull or too aggressive, switch intent and compare the profiled and perception values in the response.

If no ICC profiles are set, the library falls back to simple math conversion and the intent has no effect.

Result structure

BridgeResult::toArray() returns:

Helper methods on BridgeResult:

$result->hex();
$result->cmyk();
$result->name();
$result->givenValue();

Available scheme types: complementary, triadic, analogous, square, tetradic, tint, shade, tone, hue.

Error handling

• Unknown profile name → InvalidArgumentException
• Unknown color type → InvalidArgumentException
• Invalid color values → validated by wwaz/colormodel-php

Important note about concurrency

ProfileConverter uses the global engine state from wwaz/colorconvert-php. For parallel work, use one converter instance per request or workflow.

Tests

composer install
vendor/bin/colorprofile init
vendor/bin/colorprofile install sRGB_v4_ICC_preference ISOcoated_v2_300_eci
composer test

When running inside the cooler monorepo, existing root profiles are picked up automatically.

Laravel

For a ready-made Laravel integration (routes, views, API), see wwaz/cooler.

Cooler merges all bridge-related settings into config/cooler.php and reads them via CoolerSettings. The library itself has no config() or env() calls — pass explicit constructor arguments or an optional BridgeConfig.

License

MIT — see LICENSE.