Hoppa till huvudinnehåll

Creating Colors

Negarity Color provides multiple ways to create color instances. This guide covers all the available methods.

Prerequisites: Registering Color Spaces​

Before using color spaces, you need to register them. For built-in color spaces, use:

use Negarity\Color\Registry\ColorSpaceRegistry;

// Register all built-in color spaces (RGB, HSL, CMYK, Lab, etc.)
ColorSpaceRegistry::registerBuiltIn();

This is typically done once at the start of your application. Custom color spaces can be registered individually (see Extending the Library).

Using Static Factory Methods​

The easiest way to create colors is using the static factory methods on the Color class. These methods work dynamically through the color space registry for all registered color spaces.

RGB Colors​

Create colors using Red, Green, and Blue values (0-255):

use Negarity\Color\Color;

$red = Color::rgb(255, 0, 0);
$green = Color::rgb(0, 255, 0);
$blue = Color::rgb(0, 0, 255);
$custom = Color::rgb(255, 100, 50);

RGBA Colors​

Create colors with an alpha channel for transparency (0-255, where 255 is fully opaque):

$opaque = Color::rgba(255, 100, 50, 255);
$semiTransparent = Color::rgba(255, 100, 50, 128);
$transparent = Color::rgba(255, 100, 50, 0);

HSL Colors​

Create colors using Hue (0-360), Saturation (0-100), and Lightness (0-100):

$hsl = Color::hsl(210, 50, 40);
// Hue: 210° (blue), Saturation: 50%, Lightness: 40%

HSLA Colors​

HSL with alpha channel:

$hsla = Color::hsla(210, 50, 40, 100);
// Hue: 210°, Saturation: 50%, Lightness: 40%, Alpha: 100%

HSV Colors​

Create colors using Hue (0-360), Saturation (0-100), and Value (0-100):

$hsv = Color::hsv(210, 50, 40);
// Hue: 210°, Saturation: 50%, Value: 40%

CMYK Colors​

Create colors for print using Cyan, Magenta, Yellow, and Key (black) values (0-100):

$cmyk = Color::cmyk(0, 50, 100, 0);
// Cyan: 0%, Magenta: 50%, Yellow: 100%, Black: 0%

Lab Colors​

Create colors in the CIELAB color space (Lightness: 0-100, a: -128 to 127, b: -128 to 127):

$lab = Color::lab(50.0, 20.0, -30.0);
// Note: All channel values are floats for precision

LCh Colors​

Create colors using Lightness (0-100), Chroma (0-100), and Hue (0-360):

$lch = Color::lch(50.0, 30.0, 210.0);
// Note: All channel values are floats for precision

XYZ Colors​

Create colors in the CIE XYZ color space:

$xyz = Color::xyz(20.0, 30.0, 40.0);
// Note: All channel values are floats for precision

YCbCr Colors​

Create colors in the YCbCr color space (used in video and digital photography):

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

Creating from Hex Strings​

You can create colors from hexadecimal color codes, which is common in web development:

// 6-digit hex (RGB)
$color1 = Color::hex('#FF6432');
$color2 = Color::hex('FF6432'); // Hash is optional

// 3-digit hex (RGB shorthand)
$color3 = Color::hex('#F64'); // Equivalent to #FF6644

// 8-digit hex (RGBA)
$color4 = Color::hex('#FF643280'); // With alpha channel

// 4-digit hex (RGBA shorthand)
$color5 = Color::hex('#F648'); // With alpha channel

You can also specify the desired color space when creating from hex:

$hslFromHex = Color::hex('#FF6432', \Negarity\Color\ColorSpace\HSL::class);
$cmykFromHex = Color::hex('#FF6432', \Negarity\Color\ColorSpace\CMYK::class);

Using the Constructor​

You can also create colors directly using the constructor with a color space class and channel values:

use Negarity\Color\Color;
use Negarity\Color\ColorSpace\RGB;
use Negarity\Color\ColorSpace\HSL;

// RGB color
$color1 = new Color(RGB::class, ['r' => 255, 'g' => 100, 'b' => 50]);

// HSL color
$color2 = new Color(HSL::class, ['h' => 210, 's' => 50, 'l' => 40]);

This approach is useful when you need to create colors dynamically or when working with color spaces that don't have a dedicated factory method.

Channel Value Types​

All channel values in Negarity Color are floats for maximum precision. Even when you pass integers, they are stored and returned as floats:

$color = Color::rgb(255, 100, 50);
echo gettype($color->getR()); // "double" (float)
echo $color->getR(); // 255.0 (displayed as 255)

This ensures precision is maintained throughout conversions and calculations.

String Representation​

Colors automatically convert to a readable string format:

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

$hsl = Color::hsl(210, 50, 40);
echo $hsl; // Outputs: "hsl(210, 50, 40)"

Converting to Hex​

You can convert any color to a hex string:

$color = Color::rgb(255, 100, 50);
echo $color->toHex(); // Outputs: "#FF6432"

$rgba = Color::rgba(255, 100, 50, 128);
echo $rgba->toHex(); // Outputs: "#FF643280"

Value Clamping and Out-of-Range Values​

By default, Negarity Color operates in non-strict mode, which allows out-of-range values to be stored internally. This is useful for:

  • Working with out-of-gamut colors
  • Preserving precision in calculations
  • Advanced color science operations

Non-Strict Mode (Default)​

In non-strict mode, you can create colors with out-of-range values:

// These work in non-strict mode (default)
$color = Color::rgb(300, -10, 50);  // R > 255, G < 0

// Values are clamped when accessed
echo $color->getR();     // 255 (clamped)
echo $color->getRRaw();  // 300 (original)
echo $color->getG();     // 0 (clamped)
echo $color->getGRaw();  // -10 (original)

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

Strict Mode​

In strict mode, values are clamped immediately when assigned. This ensures all stored values are always within valid ranges. Strict mode is an advanced feature that requires overriding the STRICT_CLAMPING constant.

Next Steps​

Now that you know how to create colors, learn about: