Class: Unmagic::Color

Inherits:
Object
  • Object
show all
Defined in:
lib/unmagic/color.rb,
lib/unmagic/color/hsl.rb,
lib/unmagic/color/rgb.rb,
lib/unmagic/color/oklch.rb,
lib/unmagic/color/rgb/hex.rb,
lib/unmagic/color/rgb/named.rb,
lib/unmagic/color/string/hash_function.rb

Overview

Base class for working with colors in different color spaces.

## Understanding Colors

A color is simply a way to describe what we see. Just like you can describe a location using different coordinate systems (street address, latitude/longitude, etc.), you can describe colors using different “color spaces.”

This library supports three main color spaces:

  • RGB: Describes colors as a mix of Red, Green, and Blue light (like your screen)

  • HSL: Describes colors using Hue (color wheel position), Saturation (intensity), and Lightness (brightness)

  • OKLCH: A modern color space that matches how humans perceive color differences

## Basic Usage

Parse a color from a string:

color = Unmagic::Color.parse("#FF5733")
color = Unmagic::Color["rgb(255, 87, 51)"]
color = Unmagic::Color.parse("hsl(9, 100%, 60%)")

Convert between color spaces:

rgb = Unmagic::Color.parse("#FF5733")
hsl = rgb.to_hsl
oklch = rgb.to_oklch

Manipulate colors:

lighter = color.lighten(0.2)
darker = color.darken(0.1)
mixed = color.blend(other_color, 0.5)

Direct Known Subclasses

HSL, OKLCH, RGB

Defined Under Namespace

Classes: Chroma, Component, Error, HSL, Hue, Lightness, OKLCH, ParseError, RGB, Saturation, String

Constant Summary collapse

Red =

Type alias for red component

Component
Green =

Type alias for green component

Component
Blue =

Type alias for blue component

Component

Class Method Summary collapse

Instance Method Summary collapse

Class Method Details

.[](value) ⇒ RGB, ...

Parse a color string using bracket notation.

This is a convenient alias for parse.

Examples:

Unmagic::Color["#FF5733"]
Unmagic::Color["hsl(9, 100%, 60%)"]

Parameters:

Returns:

  • (RGB, HSL, OKLCH) —

    A color object in the appropriate color space

Raises:



113
114
115
 
# File 'lib/unmagic/color.rb', line 113

def [](value)
  parse(value)
end

.parse(input) ⇒ RGB, ...

Parse a color string into the appropriate color space object.

This method automatically detects the format and returns the correct color type. Supported formats include hex colors, RGB, HSL, OKLCH, and named colors.

Examples:

Parse a hex color

Unmagic::Color.parse("#FF5733")

Parse an RGB color

Unmagic::Color.parse("rgb(255, 87, 51)")

Parse an HSL color

Unmagic::Color.parse("hsl(9, 100%, 60%)")

Parse an OKLCH color

Unmagic::Color.parse("oklch(0.65 0.15 30)")

Parse a named color

Unmagic::Color.parse("goldenrod")

Pass through an existing color

color = Unmagic::Color.parse("#FF5733")
Unmagic::Color.parse(color)

Parameters:

  • input (String, Color) —

    The color string to parse, or an existing Color object

Returns:

  • (RGB, HSL, OKLCH) —

    A color object in the appropriate color space

Raises:

  • (ParseError) —

    If the input is nil, empty, or in an unrecognized format



81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
 
# File 'lib/unmagic/color.rb', line 81

def parse(input)
  return input if input.is_a?(self)
  raise ParseError, "Can't pass nil as a color" if input.nil?

  input = input.strip
  raise ParseError, "Can't parse empty string" if input == ""

  # Try hex or RGB format
  if input.start_with?("#") || input.match?(/\A[0-9A-Fa-f]{3,6}\z/) || input.start_with?("rgb")
    RGB.parse(input)
  elsif input.start_with?("hsl")
    HSL.parse(input)
  elsif input.start_with?("oklch")
    OKLCH.parse(input)
  elsif RGB::Named.valid?(input)
    RGB::Named.parse(input)
  else
    raise ParseError, "Unknown color #{input.inspect}"
  end
end

Instance Method Details

#blend(other, amount = 0.5) ⇒ Color

Blend this color with another color.

Creates a new color by mixing this color with another. The amount parameter controls how much of the other color to mix in.

Examples:

Mix two colors equally

red = Unmagic::Color.parse("#FF0000")
blue = Unmagic::Color.parse("#0000FF")
red.blend(blue, 0.5)

Add a hint of another color

base = Unmagic::Color.parse("#336699")
base.blend(Unmagic::Color.parse("#FF0000"), 0.1)

Parameters:

  • other (Color) —

    The color to blend with

  • amount (Float) (defaults to: 0.5) —

    How much of the other color to use (0.0 to 1.0)

Returns:

  • (Color) —

    A new color that is a blend of the two colors

Raises:

  • (NotImplementedError) 


342
343
344
 
# File 'lib/unmagic/color.rb', line 342

def blend(other, amount = 0.5)
  raise NotImplementedError
end

#dark? ⇒ Boolean

Check if this is a dark color.

A color is considered dark if its luminance is 0.5 or less. This is the opposite of #light?.

Returns:

  • (Boolean) —

    true if the color is dark, false otherwise



398
399
400
 
# File 'lib/unmagic/color.rb', line 398

def dark?
  !light?
end

#darken(amount = 0.1) ⇒ Color

Create a darker version of this color.

Returns a new color that is darker than the original. The exact implementation depends on the color space.

Examples:

Make a color 10% darker

bright = Unmagic::Color.parse("#FF9966")
bright.darken(0.1)

Parameters:

  • amount (Float) (defaults to: 0.1) —

    How much to darken (0.0 to 1.0)

Returns:

  • (Color) —

    A new, darker color

Raises:

  • (NotImplementedError) 


372
373
374
 
# File 'lib/unmagic/color.rb', line 372

def darken(amount = 0.1)
  raise NotImplementedError
end

#light? ⇒ Boolean

Check if this is a light color.

A color is considered light if its luminance is greater than 0.5. This is useful for determining whether to use dark or light text on a colored background.

Examples:

Choose text color based on background

bg = Unmagic::Color.parse("#FFFF00")  # Yellow
text_color = bg.light? ? "#000000" : "#FFFFFF"
# => "#000000"

Returns:

  • (Boolean) —

    true if the color is light, false otherwise



388
389
390
 
# File 'lib/unmagic/color.rb', line 388

def light?
  luminance > 0.5
end

#lighten(amount = 0.1) ⇒ Color

Create a lighter version of this color.

Returns a new color that is lighter than the original. The exact implementation depends on the color space.

Examples:

Make a color 20% lighter

dark = Unmagic::Color.parse("#336699")
dark.lighten(0.2)

Parameters:

  • amount (Float) (defaults to: 0.1) —

    How much to lighten (0.0 to 1.0)

Returns:

  • (Color) —

    A new, lighter color

Raises:

  • (NotImplementedError) 


357
358
359
 
# File 'lib/unmagic/color.rb', line 357

def lighten(amount = 0.1)
  raise NotImplementedError
end

#luminance ⇒ Float

Calculate the perceptual luminance of this color.

Luminance represents how bright the color appears to the human eye, accounting for the fact that we perceive green as brighter than red, and red as brighter than blue.

Returns:

  • (Float) —

    The luminance value from 0.0 (black) to 1.0 (white)

Raises:

  • (NotImplementedError) 


321
322
323
 
# File 'lib/unmagic/color.rb', line 321

def luminance
  raise NotImplementedError
end

#to_hsl ⇒ HSL

Convert this color to HSL color space.

HSL represents colors using Hue (0-360°), Saturation (0-100%), and Lightness (0-100%).

Returns:

  • (HSL) —

    The color in HSL color space

Raises:

  • (NotImplementedError) 


300
301
302
 
# File 'lib/unmagic/color.rb', line 300

def to_hsl
  raise NotImplementedError
end

#to_oklch ⇒ OKLCH

Convert this color to OKLCH color space.

OKLCH is a perceptually uniform color space that better matches how humans perceive color differences.

Returns:

  • (OKLCH) —

    The color in OKLCH color space

Raises:

  • (NotImplementedError) 


310
311
312
 
# File 'lib/unmagic/color.rb', line 310

def to_oklch
  raise NotImplementedError
end

#to_rgb ⇒ RGB

Convert this color to RGB color space.

RGB represents colors as a combination of Red, Green, and Blue light, with each component ranging from 0-255.

Returns:

  • (RGB) —

    The color in RGB color space

Raises:

  • (NotImplementedError) 


290
291
292
 
# File 'lib/unmagic/color.rb', line 290

def to_rgb
  raise NotImplementedError
end