Getting Channels

Every color in Negarity Color consists of channels that represent the color's values in its color space. This guide shows you how to access these channel values.

Clamping and Value Modes

Negarity Color supports two modes for handling channel values:

• Non-Strict Mode (Default): Original values are preserved internally, but clamped values are returned when accessing channels. This allows out-of-gamut colors to exist for advanced operations.
• Strict Mode: Values are clamped immediately when assigned. This ensures all stored values are always within valid ranges.

You can access both clamped and raw (original) values using different methods.

Using getChannel()

The getChannel() method allows you to access any channel by name. This method always returns clamped values (values within the valid range for that channel):

use Negarity\Color\Color;

$color = Color::rgb(255, 100, 50);

echo $color->getChannel('r'); // 255
echo $color->getChannel('g'); // 100
echo $color->getChannel('b'); // 50

Getting Raw (Original) Values

In non-strict mode, you can access the original (unclamped) values using getChannelRaw():

// In non-strict mode, out-of-range values are allowed
$color = Color::rgb(300, -10, 50);

echo $color->getChannel('r');    // 255 (clamped)
echo $color->getChannelRaw('r'); // 300 (original)

echo $color->getChannel('g');    // 0 (clamped)
echo $color->getChannelRaw('g'); // -10 (original)

This is useful when you need to work with out-of-gamut colors or preserve precision in calculations.

This works for any color space:

$hsl = Color::hsl(210, 50, 40);

echo $hsl->getChannel('h'); // 210
echo $hsl->getChannel('s'); // 50
echo $hsl->getChannel('l'); // 40

Using Getter Methods

For convenience, you can use dedicated getter methods for each channel. These methods are dynamically available based on the color space. These methods return clamped values (same as getChannel()).

You can also access raw values using get{Channel}Raw() methods:

RGB/RGBA Channels

$color = Color::rgb(255, 100, 50);

echo $color->getR(); // 255 (clamped)
echo $color->getG(); // 100 (clamped)
echo $color->getB(); // 50 (clamped)

// Access raw values
echo $color->getRRaw(); // Original value (may be out of range in non-strict mode)

// For RGBA
$rgba = Color::rgba(255, 100, 50, 128);
echo $rgba->getA(); // 128 (clamped)
echo $rgba->getARaw(); // Original alpha value

HSL/HSLA Channels

$hsl = Color::hsl(210, 50, 40);

echo $hsl->getH(); // 210 (Hue)
echo $hsl->getS(); // 50 (Saturation)
echo $hsl->getL(); // 40 (Lightness)

HSV Channels

$hsv = Color::hsv(210, 50, 40);

echo $hsv->getH(); // 210
echo $hsv->getS(); // 50
echo $hsv->getV(); // 40 (Value)

CMYK Channels

$cmyk = Color::cmyk(0, 50, 100, 0);

echo $cmyk->getC(); // 0 (Cyan)
echo $cmyk->getM(); // 50 (Magenta)
echo $cmyk->getY(); // 100 (Yellow)
echo $cmyk->getK(); // 0 (Key/Black)

Lab Channels

$lab = Color::lab(50, 20, -30);

echo $lab->getL(); // 50 (Lightness)
echo $lab->getA(); // 20
echo $lab->getB(); // -30

LCh Channels

$lch = Color::lch(50, 30, 210);

echo $lch->getL(); // 50 (Lightness)
echo $lch->getC(); // 30 (Chroma)
echo $lch->getH(); // 210 (Hue)

XYZ Channels

$xyz = Color::xyz(20, 30, 40);

echo $xyz->getX(); // 20
echo $xyz->getY(); // 30
echo $xyz->getZ(); // 40

YCbCr Channels

$ycbcr = Color::ycbcr(78, 100, -100);

echo $ycbcr->getY(); // 78
echo $ycbcr->getCb(); // 100
echo $ycbcr->getCr(); // -100

Getting All Channels

Using getChannels()

Get all channel names for the current color space:

$color = Color::rgb(255, 100, 50);
$channels = $color->getChannels();
// Returns: ['r', 'g', 'b']

Using toArray()

Get all channel values as an associative array:

$color = Color::rgb(255, 100, 50);
$array = $color->toArray();
// Returns: [
//     'color-space' => 'rgb',
//     'values' => ['r' => 255, 'g' => 100, 'b' => 50]
// ]

JSON Serialization

Colors implement JsonSerializable, so you can easily serialize them:

$color = Color::rgb(255, 100, 50);
$json = json_encode($color);
// Returns: {"color-space":"rgb","values":{"r":255,"g":100,"b":50}}

Getting Color Space Information

Color Space Name

Get the human-readable name of the color space:

$color = Color::rgb(255, 100, 50);
echo $color->getColorSpaceName(); // "rgb"

Color Space Class

Get the class name of the color space:

$color = Color::rgb(255, 100, 50);
echo $color->getColorSpace(); // "Negarity\Color\ColorSpace\RGB"

Practical Examples

Iterating Over Channels

$color = Color::rgb(255, 100, 50);

foreach ($color->getChannels() as $channel) {
    echo "$channel: " . $color->getChannel($channel) . "\n";
}
// Output:
// r: 255
// g: 100
// b: 50

Accessing Channels After Conversion

$rgb = Color::rgb(255, 100, 50);
$hsl = $rgb->toHSL();

// Access HSL channels
echo "Hue: " . $hsl->getH() . "°\n";
echo "Saturation: " . $hsl->getS() . "%\n";
echo "Lightness: " . $hsl->getL() . "%\n";

Working with Alpha Channels

$rgba = Color::rgba(255, 100, 50, 128);

// Check if color has transparency
if ($rgba->getA() < 255) {
    $opacity = ($rgba->getA() / 255) * 100;
    echo "Color is " . $opacity . "% opaque\n";
}

Clamping Behavior

Non-Strict Mode (Default)

In non-strict mode, out-of-range values are allowed when creating colors:

// This works in non-strict mode (default)
$color = Color::rgb(300, -10, 50);

// getChannel() returns clamped values
echo $color->getR(); // 255 (clamped from 300)
echo $color->getG(); // 0 (clamped from -10)

// getChannelRaw() returns original values
echo $color->getRRaw(); // 300
echo $color->getGRaw(); // -10

// String representation uses clamped values
echo $color; // "rgb(255, 0, 50)"

Strict Mode

In strict mode, values are clamped immediately when assigned. To enable strict mode, you need to override the STRICT_CLAMPING constant in a custom class (this is an advanced feature).

Error Handling

If you try to access a channel that doesn't exist in the current color space, an exception will be thrown:

$rgb = Color::rgb(255, 100, 50);

try {
    echo $rgb->getChannel('h'); // Throws InvalidArgumentException
} catch (\InvalidArgumentException $e) {
    echo "Channel 'h' doesn't exist in RGB color space\n";
}

Next Steps

Now that you can access channel values, learn about:

• Modifying colors
• Converting between color spaces