Color Ruby Library

Color is a Ruby library designed for mathematical color space manipulation. It supports RGB, CMYK, HSL, and other color spaces. It is intended for applications requiring color theory-based math rather than device-specific color profile management (like sRGB or Adobe RGB).

Key features include:

• Manipulation of RGB, CMYK, HSL, and absolute color spaces like CIE LAB and CIE XYZ.
• Support for named RGB colors (commonly used in HTML, SVG, and X11).
• Reference white values (D65 and D50) provided in Color::XYZ for conversions between absolute and relative color spaces.

If migrating from versions prior to 2.0, be aware of the following breaking changes:

• Immutability: Color classes are now Data objects and are immutable. You cannot modify an existing color object; you must create new ones.
• Explicit Named Colors: Named RGB colors must be explicitly required via require "color/rgb/colors".
• Removed Features: Color palettes, Color::CSS, and Color::CSS#[] have been removed.
• Ruby Version: Support for Ruby versions prior to 3.2 has been dropped.

In Color 2.2+, named RGB colors are not loaded by default to optimize startup. If you need to use named colors (e.g., colors used in HTML or SVG), you must explicitly require the color definitions:

require "color/rgb/colors"

Since Color::Grayscale is a Data class, you can use Ruby's pattern matching for deconstruction:

• Array deconstruction: Uses [gray] (where gray is the percentage).
• Hash deconstruction: Uses {g:, gray:} (where g is the fraction and gray is the percentage).

color = Color::Grayscale.from_fraction(0.5)

# Array deconstruction
[gray_pct] = color

# Hash deconstruction
{g: fraction, gray: pct} = color

Because Color::YIQ is an immutable Data class, you can easily extract its components using Ruby's deconstruction patterns.

• Array deconstruction: Returns [y, i, q].
• Hash deconstruction: Returns {y:, i:, q:}.
• Attributes: You can access individual components via #y, #i, and #q (or #brightness for y).

color = Color::YIQ.from_fraction(0.5, 0.2, 0.1)

# Array deconstruction
y, i, q = color

# Hash deconstruction
{y:, i:, q:} = color

# Attribute access
puts color.y
puts color.brightness

The CIE 1931 XYZ color space is a device-independent color space.

• Y: Represents luminance (brightness). In fractional representation, it ranges from 0.0 to 1.0. In native representation, it is conventionally clamped to 0..100.
• X and Z: Represent two axes of chromaticity.
• Clamping: When initialized with fractional values, X is clamped to 0.0..2.2 and Z is clamped to 0.0..2.8 (assuming Y is scaled to 1.0).

To express the gamut in relation to a reference white (like D65), the xyY color space is often used, where:

• x = X / (X + Y + Z)
• y = Y / (X + Y + Z)
• Y = Y

A Color::XYZ object is an immutable Data class instance that supports deconstruction:

• Array deconstruction: Returns values scaled to 100 (e.g., [x * 100, y * 100, z * 100]).
• Hash deconstruction: Returns the fractional components {x:, y:, z:}.

xyz = Color::XYZ.from_fraction(0.95, 1.0, 1.08)

# Array deconstruction (scaled to 100)
x_val, y_val, z_val = xyz

# Hash deconstruction (fractional)
{x: x_f, y: y_f, z: z_f} = xyz

Color is a Ruby library for mathematical color space manipulation (RGB, CMYK, HSL, etc.).

Important Version Notes (v2.x):

• Requires Ruby 3.2+.
• Color classes are immutable Data objects.
• Named RGB colors (e.g., Color::RGB::Wheat) are not loaded by default. To use them, you must explicitly require the colors file:

  require "color"
  require "color/rgb/colors"

require "color"
require "color/rgb/colors"

# Now you can use named colors
rgb = Color::RGB::Wheat

To adjust the lightness of an RGB color without unintentionally changing its hue or saturation, convert the color to the CIE LAB color space, modify the lightness component (l), and then convert it back to RGB. This avoids the issues caused by directly adjusting RGB curves.

c = Color::RGB.from_values(r, g, b).to_lab

if (t = c.l / 50.0) < 1
  c.l = 50 * ((1.0 - t) * Math.sqrt(t) + t**2)
end

c.to_rgb

Use the #css method to represent the color as a CSS hsl() function string. You can optionally provide an alpha value.

# Without alpha
hsl = Color::HSL.from_values(145, 30, 50)
puts hsl.css             # => "hsl(145deg 30% 50%)"

# With alpha
puts hsl.css(alpha: 0.5) # => "hsl(145deg 30% 50% / 0.50)"

# Present the color as a CSS `hsl` function with optional `alpha`.
# hsl = Color::HSL.from_values(145, 30, 50)
# hsl.css             # => hsl(145deg 30% 50%)
# hsl.css(alpha: 0.5) # => hsl(145deg 30% 50% / 0.50)

You can create Color::Grayscale objects using fractional values (0.0 to 1.0) or percentage values (0.0 to 100.0).

• From fraction (0.0..1.0): Use Color::Grayscale.from_fraction(value), Color::Grayscale.new(g: value), or the shorthand Color::Grayscale[g: value].
• From percentage (0.0..100.0): Use Color::Grayscale.from_percentage(value) or Color::Grayscale.from_values(value).

Color::Grayscale objects are immutable Data class instances.

# Using fractions (0.0 to 1.0)
Color::Grayscale.from_fraction(0.5)
Color::Grayscale.new(g: 0.5)
Color::Grayscale[g: 0.5]

# Using percentages (0.0 to 100.0)
Color::Grayscale.from_percentage(50)
Color::Grayscale.from_values(50)