toxi.color
Class TColor

java.lang.Object
  extended by toxi.color.TColor
All Implemented Interfaces:
ReadonlyTColor

public class TColor
extends java.lang.Object
implements ReadonlyTColor

Floating point color class with implicit RGB, HSV, CMYK access modes, conversion and color theory utils. Based on the Colors library for NodeBox


Field Summary
 float alpha
           
static ReadonlyTColor BLACK
           
static float BLACK_POINT
          Maximum rgb component value for a color to be classified as black.
static ReadonlyTColor BLUE
           
static ReadonlyTColor CYAN
           
static ReadonlyTColor GREEN
           
static float GREY_THRESHOLD
          Maximum saturations value for a color to be classified as grey
static ReadonlyTColor MAGENTA
           
static ReadonlyTColor RED
           
static ReadonlyTColor WHITE
           
static float WHITE_POINT
          Minimum rgb component value for a color to be classified as white.
static ReadonlyTColor YELLOW
           
 
Constructor Summary
TColor(ReadonlyTColor c)
          Creates a deep copy of the given color.
 
Method Summary
 TColor add(TColor c)
           
 TColor addSelf(TColor c)
           
 ReadonlyTColor adjustConstrast(float amount)
          Changes the brightness of the color by the given amount in the direction towards either the black or white point (depending on if current brightness >= 50%)
 ReadonlyTColor adjustHSV(float h, float s, float v)
          Adds the given HSV values as offsets to the current color.
 ReadonlyTColor adjustRGB(float r, float g, float b)
          Adds the given RGB values as offsets to the current color.
 float alpha()
           
 TColor analog(float theta, float delta)
          Rotates this color by a random amount (not exceeding the one specified) and creates variations in saturation and brightness based on the 2nd parameter.
 TColor analog(int angle, float delta)
           
 float black()
           
 TColor blend(ReadonlyTColor c, float t)
          Blends the color with the given one by the stated amount
 float blue()
           
 float brightness()
           
static float[] cmykToRGB(float c, float m, float y, float k)
          Converts CMYK floats into an RGB array.
static float[] cmykToRGB(float c, float m, float y, float k, float[] rgb)
          Converts CMYK floats into the given RGB array.
 TColor complement()
           
 TColor copy()
           
 float cyan()
           
 TColor darken(float step)
          Reduces the color's brightness by the given amount (e.g 0.1 = 10% darker).
 TColor desaturate(float step)
          Reduced the color's saturation by the given amount.
 TColor differenceTo(TColor c)
           
 float distanceToCMYK(ReadonlyTColor c)
          Calculates the CMYK distance to the given color.
 float distanceToHSV(ReadonlyTColor c)
          Calculates the HSV distance to the given color.
 float distanceToRGB(ReadonlyTColor c)
          Calculates the RGB distance to the given color.
 boolean equals(java.lang.Object o)
           
 TColor getAnalog(float theta, float delta)
           
 TColor getAnalog(int angle, float delta)
           
 TColor getBlended(ReadonlyTColor c, float t)
           
 Hue getClosestHue()
           
 Hue getClosestHue(boolean primaryOnly)
           
 TColor getComplement()
           
 float getComponentValue(AccessCriteria criteria)
           
 TColor getDarkened(float step)
           
 TColor getDesaturated(float step)
           
 TColor getDifferenceTo(TColor c)
           
 TColor getInverted()
           
 TColor getLightened(float step)
           
 TColor getRotatedRYB(float theta)
           
 TColor getRotatedRYB(int angle)
           
 TColor getSaturated(float step)
           
 float green()
           
 int hashCode()
           
static float[] hexToRGB(java.lang.String hexRGB)
          Converts hex string into a RGB array.
static float[] hexToRGB(java.lang.String hexRGB, float[] rgb)
           
static float[] hsvToRGB(float h, float s, float v)
          Converts HSV values into RGB array.
static float[] hsvToRGB(float h, float s, float v, float[] rgb)
           
 float hue()
           
 TColor invert()
          Inverts the color.
 boolean isBlack()
           
 boolean isGrey()
           
 boolean isPrimary()
           
 boolean isWhite()
           
static float[] labToRGB(float l, float a, float b)
           
static float[] labToRGB(float l, float a, float b, float[] rgb)
          Converts CIE Lab to RGB components.
 TColor lighten(float step)
          Lightens the color by stated amount.
 float luminance()
          Computes the color's luminance using this formula: lum=0.299*red + 0.587*green + 0.114 *blue
 float magenta()
           
static TColor newARGB(int argb)
          Factory method.
static TColor newCMYK(float c, float m, float y, float k)
          Factory method.
static TColor newCMYKA(float c, float m, float y, float k, float a)
          Factory method.
static TColor newGray(float gray)
          Factory method.
static TColor newGrayAlpha(float gray, float alpha)
           
static TColor newHex(java.lang.String hexRGB)
          Factory method.
static TColor newHSV(float h, float s, float v)
          Factory method.
static ReadonlyTColor newHSV(Hue h, float s, float v)
           
static TColor newHSVA(float h, float s, float v, float a)
           
static TColor newRandom()
          Factory method.
static TColor newRGB(float r, float g, float b)
          Factory method.
static TColor newRGBA(float r, float g, float b, float a)
           
 float red()
           
static float[] rgbToCMYK(float r, float g, float b)
          Converts the RGB values into a CMYK array.
static float[] rgbToCMYK(float r, float g, float b, float[] cmyk)
           
static java.lang.String rgbToHex(float r, float g, float b)
          Formats the RGB float values into hex integers.
static float[] rgbToHSV(float r, float g, float b)
          Converts the RGB values into an HSV array.
static float[] rgbToHSV(float r, float g, float b, float[] hsv)
           
 TColor rotateRYB(float theta)
           
 TColor rotateRYB(int theta)
          Rotates the color by x degrees along the RYB color wheel
 TColor saturate(float step)
          Adds the given value to the current saturation component.
 float saturation()
           
 TColor setAlpha(float alpha)
           
 TColor setARGB(int argb)
          Sets all color components to new values interpreted from the given packed ARGB 32bit color value.
 TColor setBlack(float val)
           
 TColor setBlue(float blue)
           
 TColor setBrightness(float brightness)
           
 TColor setCMYK(float[] newCMYK)
           
 TColor setCMYK(float c, float m, float y, float k)
           
 TColor setComponent(AccessCriteria criteria, float val)
          Sets a color component by name.
 TColor setCyan(float val)
           
 TColor setGreen(float green)
           
 TColor setHSV(float[] newHSV)
           
 TColor setHSV(float h, float s, float v)
           
 void setHue(float hue)
           
 TColor setMagenta(float val)
           
 TColor setRed(float red)
           
 TColor setRGB(float[] newRGB)
           
 TColor setRGB(float r, float g, float b)
           
 TColor setSaturation(float saturation)
           
 TColor setYellow(float val)
           
 TColor sub(TColor c)
           
 TColor subSelf(TColor c)
           
 int toARGB()
          Converts the color into a packed ARGB int.
 float[] toCMYKAArray(float[] cmyka)
          Copies the current CMYKA values into the given array (or constucts a new one with these values).
 java.lang.String toHex()
          Converts the color into a 6 digit hex string.
 float[] toHSVAArray(float[] hsva)
           
 float[] toRGBAArray(float[] rgba)
          Copies the current RGBA value into the given array (or constucts a new one with these values).
 float[] toRGBAArray(float[] rgba, int offset)
          Copies the current RGBA value into the given array starting the given offset.
 java.lang.String toString()
           
 float yellow()
           
 
Methods inherited from class java.lang.Object
getClass, notify, notifyAll, wait, wait, wait
 

Field Detail

BLACK_POINT

public static float BLACK_POINT
Maximum rgb component value for a color to be classified as black.

See Also:
isBlack()

WHITE_POINT

public static float WHITE_POINT
Minimum rgb component value for a color to be classified as white.

See Also:
isWhite()

GREY_THRESHOLD

public static float GREY_THRESHOLD
Maximum saturations value for a color to be classified as grey

See Also:
isGrey()

RED

public static final ReadonlyTColor RED

GREEN

public static final ReadonlyTColor GREEN

BLUE

public static final ReadonlyTColor BLUE

CYAN

public static final ReadonlyTColor CYAN

MAGENTA

public static final ReadonlyTColor MAGENTA

YELLOW

public static final ReadonlyTColor YELLOW

BLACK

public static final ReadonlyTColor BLACK

WHITE

public static final ReadonlyTColor WHITE

alpha

public float alpha
Constructor Detail

TColor

public TColor(ReadonlyTColor c)
Creates a deep copy of the given color.

Parameters:
c -
Method Detail

cmykToRGB

public static final float[] cmykToRGB(float c,
                                      float m,
                                      float y,
                                      float k)
Converts CMYK floats into an RGB array.

Parameters:
c -
m -
y -
k -
Returns:
rgb array

cmykToRGB

public static final float[] cmykToRGB(float c,
                                      float m,
                                      float y,
                                      float k,
                                      float[] rgb)
Converts CMYK floats into the given RGB array.

Parameters:
c -
m -
y -
k -
rgb -
Returns:
rgb array

hexToRGB

public static final float[] hexToRGB(java.lang.String hexRGB)
Converts hex string into a RGB array.

Parameters:
hexRGB -
Returns:
rgb array

hexToRGB

public static final float[] hexToRGB(java.lang.String hexRGB,
                                     float[] rgb)

hsvToRGB

public static final float[] hsvToRGB(float h,
                                     float s,
                                     float v)
Converts HSV values into RGB array.

Parameters:
h -
s -
v -
Returns:
rgb array

hsvToRGB

public static final float[] hsvToRGB(float h,
                                     float s,
                                     float v,
                                     float[] rgb)

labToRGB

public static final float[] labToRGB(float l,
                                     float a,
                                     float b)

labToRGB

public static final float[] labToRGB(float l,
                                     float a,
                                     float b,
                                     float[] rgb)
Converts CIE Lab to RGB components. First we have to convert to XYZ color space. Conversion involves using a white point, in this case D65 which represents daylight illumination. Algorithm adopted from: http://www.easyrgb.com/math.php

Parameters:
l -
a -
b -
rgb -
Returns:
rgb array

newARGB

public static final TColor newARGB(int argb)
Factory method. Creates new color from ARGB int.

Parameters:
argb -
Returns:
new color

newCMYK

public static final TColor newCMYK(float c,
                                   float m,
                                   float y,
                                   float k)
Factory method. Creates new color from CMYK values.

Parameters:
c -
m -
y -
k -
Returns:
new color

newCMYKA

public static final TColor newCMYKA(float c,
                                    float m,
                                    float y,
                                    float k,
                                    float a)
Factory method. Creates new color from CMYK + alpha values.

Parameters:
c -
m -
y -
k -
a -
Returns:
new color

newGray

public static final TColor newGray(float gray)
Factory method. Creates a new shade of gray + alpha.

Parameters:
gray -
Returns:
new color.

newGrayAlpha

public static final TColor newGrayAlpha(float gray,
                                        float alpha)

newHex

public static final TColor newHex(java.lang.String hexRGB)
Factory method. New color from hex string.

Parameters:
hexRGB -
Returns:
new color

newHSV

public static final TColor newHSV(float h,
                                  float s,
                                  float v)
Factory method. New color from hsv values.

Parameters:
h -
s -
v -
Returns:
new color

newHSV

public static ReadonlyTColor newHSV(Hue h,
                                    float s,
                                    float v)

newHSVA

public static final TColor newHSVA(float h,
                                   float s,
                                   float v,
                                   float a)

newRandom

public static final TColor newRandom()
Factory method. Creates new random color. Alpha is always 1.0.

Returns:
random color

newRGB

public static final TColor newRGB(float r,
                                  float g,
                                  float b)
Factory method. Creates new color from RGB values. Alpha is set to 1.0.

Parameters:
r -
g -
b -
Returns:
new color

newRGBA

public static final TColor newRGBA(float r,
                                   float g,
                                   float b,
                                   float a)

rgbToCMYK

public static final float[] rgbToCMYK(float r,
                                      float g,
                                      float b)
Converts the RGB values into a CMYK array.

Parameters:
r -
g -
b -
Returns:
cmyk array

rgbToCMYK

public static final float[] rgbToCMYK(float r,
                                      float g,
                                      float b,
                                      float[] cmyk)

rgbToHex

public static final java.lang.String rgbToHex(float r,
                                              float g,
                                              float b)
Formats the RGB float values into hex integers.

Parameters:
r -
g -
b -
Returns:
hex string

rgbToHSV

public static final float[] rgbToHSV(float r,
                                     float g,
                                     float b)
Converts the RGB values into an HSV array.

Parameters:
r -
g -
b -
Returns:
hsv array

rgbToHSV

public static final float[] rgbToHSV(float r,
                                     float g,
                                     float b,
                                     float[] hsv)

add

public TColor add(TColor c)

addSelf

public TColor addSelf(TColor c)

adjustConstrast

public ReadonlyTColor adjustConstrast(float amount)
Changes the brightness of the color by the given amount in the direction towards either the black or white point (depending on if current brightness >= 50%)

Parameters:
amount -
Returns:
itself

adjustHSV

public ReadonlyTColor adjustHSV(float h,
                                float s,
                                float v)
Adds the given HSV values as offsets to the current color. Hue will automatically wrap.

Parameters:
h -
s -
v -
Returns:
itself

adjustRGB

public ReadonlyTColor adjustRGB(float r,
                                float g,
                                float b)
Adds the given RGB values as offsets to the current color. TColor will clip at black or white.

Parameters:
r -
g -
b -
Returns:
itself

alpha

public float alpha()
Specified by:
alpha in interface ReadonlyTColor
Returns:
the color's alpha component

analog

public TColor analog(float theta,
                     float delta)
Rotates this color by a random amount (not exceeding the one specified) and creates variations in saturation and brightness based on the 2nd parameter.

Parameters:
theta - max. rotation angle (in radians)
delta - max. sat/bri variance
Returns:
itself

analog

public TColor analog(int angle,
                     float delta)

black

public float black()
Specified by:
black in interface ReadonlyTColor
Returns:
the color's black component

blend

public TColor blend(ReadonlyTColor c,
                    float t)
Blends the color with the given one by the stated amount

Parameters:
c - target color
t - interpolation factor
Returns:
itself

blue

public float blue()
Specified by:
blue in interface ReadonlyTColor
Returns:
the color's blue component

brightness

public float brightness()
Specified by:
brightness in interface ReadonlyTColor
Returns:
color HSV brightness (not luminance!)

complement

public TColor complement()
Returns:
ifself, as complementary color

copy

public TColor copy()
Specified by:
copy in interface ReadonlyTColor
Returns:
a mutable copy of the current color

cyan

public float cyan()
Specified by:
cyan in interface ReadonlyTColor
Returns:
the color's cyan component

darken

public TColor darken(float step)
Reduces the color's brightness by the given amount (e.g 0.1 = 10% darker).

Parameters:
step -
Returns:
itself

desaturate

public TColor desaturate(float step)
Reduced the color's saturation by the given amount.

Parameters:
step -
Returns:
itself

differenceTo

public TColor differenceTo(TColor c)

distanceToCMYK

public float distanceToCMYK(ReadonlyTColor c)
Description copied from interface: ReadonlyTColor
Calculates the CMYK distance to the given color.

Specified by:
distanceToCMYK in interface ReadonlyTColor
Parameters:
c - target color
Returns:
distance

distanceToHSV

public float distanceToHSV(ReadonlyTColor c)
Description copied from interface: ReadonlyTColor
Calculates the HSV distance to the given color.

Specified by:
distanceToHSV in interface ReadonlyTColor
Parameters:
c - target color
Returns:
distance

distanceToRGB

public float distanceToRGB(ReadonlyTColor c)
Description copied from interface: ReadonlyTColor
Calculates the RGB distance to the given color.

Specified by:
distanceToRGB in interface ReadonlyTColor
Parameters:
c - target color
Returns:
distance

equals

public boolean equals(java.lang.Object o)
Overrides:
equals in class java.lang.Object

getAnalog

public TColor getAnalog(float theta,
                        float delta)
Specified by:
getAnalog in interface ReadonlyTColor

getAnalog

public TColor getAnalog(int angle,
                        float delta)
Specified by:
getAnalog in interface ReadonlyTColor

getBlended

public TColor getBlended(ReadonlyTColor c,
                         float t)
Specified by:
getBlended in interface ReadonlyTColor

getClosestHue

public Hue getClosestHue()
Specified by:
getClosestHue in interface ReadonlyTColor
Returns:
an instance of the closest named hue to this color.

getClosestHue

public Hue getClosestHue(boolean primaryOnly)
Specified by:
getClosestHue in interface ReadonlyTColor
Parameters:
primaryOnly - if true, only primary color hues are considered
Returns:
an instance of the closest named (primary) hue to this color.

getComplement

public TColor getComplement()
Specified by:
getComplement in interface ReadonlyTColor

getComponentValue

public float getComponentValue(AccessCriteria criteria)
Specified by:
getComponentValue in interface ReadonlyTColor

getDarkened

public TColor getDarkened(float step)
Specified by:
getDarkened in interface ReadonlyTColor
Returns:
a darkened copy

getDesaturated

public TColor getDesaturated(float step)
Specified by:
getDesaturated in interface ReadonlyTColor
Returns:
a desaturated copy

getDifferenceTo

public TColor getDifferenceTo(TColor c)

getInverted

public TColor getInverted()
Specified by:
getInverted in interface ReadonlyTColor
Returns:
an inverted copy

getLightened

public TColor getLightened(float step)
Specified by:
getLightened in interface ReadonlyTColor
Returns:
a lightened copy

getRotatedRYB

public TColor getRotatedRYB(float theta)
Specified by:
getRotatedRYB in interface ReadonlyTColor
Parameters:
theta - rotation angle in radians
Returns:
a RYB rotated copy

getRotatedRYB

public TColor getRotatedRYB(int angle)
Specified by:
getRotatedRYB in interface ReadonlyTColor
Parameters:
angle - rotation angle in degrees
Returns:
a RYB rotated copy

getSaturated

public TColor getSaturated(float step)
Specified by:
getSaturated in interface ReadonlyTColor
Returns:
a saturated copy

green

public float green()
Specified by:
green in interface ReadonlyTColor
Returns:
the color's green component

hashCode

public int hashCode()
Overrides:
hashCode in class java.lang.Object

hue

public float hue()
Specified by:
hue in interface ReadonlyTColor
Returns:
the color's hue

invert

public TColor invert()
Inverts the color.

Returns:
itself

isBlack

public boolean isBlack()
Specified by:
isBlack in interface ReadonlyTColor
Returns:
true, if all rgb component values are equal and less than BLACK_POINT

isGrey

public boolean isGrey()
Specified by:
isGrey in interface ReadonlyTColor
Returns:
true, if the saturation component value is less than GREY_THRESHOLD

isPrimary

public boolean isPrimary()
Specified by:
isPrimary in interface ReadonlyTColor
Returns:
true, if this colors hue is matching one of the 7 defined primary hues.

isWhite

public boolean isWhite()
Specified by:
isWhite in interface ReadonlyTColor
Returns:
true, if all rgb component values are equal and greater than WHITE_POINT

lighten

public TColor lighten(float step)
Lightens the color by stated amount.

Parameters:
step - lighten amount
Returns:
itself

luminance

public float luminance()
Description copied from interface: ReadonlyTColor
Computes the color's luminance using this formula: lum=0.299*red + 0.587*green + 0.114 *blue

Specified by:
luminance in interface ReadonlyTColor
Returns:
luminance

magenta

public float magenta()
Specified by:
magenta in interface ReadonlyTColor
Returns:
the color's magenta component

red

public float red()
Specified by:
red in interface ReadonlyTColor
Returns:
the color's red component

rotateRYB

public TColor rotateRYB(float theta)

rotateRYB

public TColor rotateRYB(int theta)
Rotates the color by x degrees along the RYB color wheel

Parameters:
theta -
Returns:
itself

saturate

public TColor saturate(float step)
Adds the given value to the current saturation component.

Parameters:
step -
Returns:
itself

saturation

public float saturation()
Specified by:
saturation in interface ReadonlyTColor
Returns:
the color's saturation

setAlpha

public TColor setAlpha(float alpha)

setARGB

public TColor setARGB(int argb)
Sets all color components to new values interpreted from the given packed ARGB 32bit color value.

Parameters:
argb -
Returns:
itself

setBlack

public TColor setBlack(float val)

setBlue

public TColor setBlue(float blue)

setBrightness

public TColor setBrightness(float brightness)

setCMYK

public TColor setCMYK(float c,
                      float m,
                      float y,
                      float k)

setCMYK

public TColor setCMYK(float[] newCMYK)

setComponent

public TColor setComponent(AccessCriteria criteria,
                           float val)
Sets a color component by name.

Parameters:
criteria -
val -
Returns:
itself
See Also:
AccessCriteria

setCyan

public TColor setCyan(float val)

setGreen

public TColor setGreen(float green)

setHSV

public TColor setHSV(float h,
                     float s,
                     float v)

setHSV

public TColor setHSV(float[] newHSV)

setHue

public void setHue(float hue)

setMagenta

public TColor setMagenta(float val)

setRed

public TColor setRed(float red)

setRGB

public TColor setRGB(float r,
                     float g,
                     float b)

setRGB

public TColor setRGB(float[] newRGB)

setSaturation

public TColor setSaturation(float saturation)

setYellow

public TColor setYellow(float val)

sub

public TColor sub(TColor c)

subSelf

public TColor subSelf(TColor c)

toARGB

public int toARGB()
Description copied from interface: ReadonlyTColor
Converts the color into a packed ARGB int.

Specified by:
toARGB in interface ReadonlyTColor
Returns:
color as int

toCMYKAArray

public float[] toCMYKAArray(float[] cmyka)
Description copied from interface: ReadonlyTColor
Copies the current CMYKA values into the given array (or constucts a new one with these values).

Specified by:
toCMYKAArray in interface ReadonlyTColor
Parameters:
cmyka - result array (or null)
Returns:
array in this order: c,m,y,k,a

toHex

public java.lang.String toHex()
Converts the color into a 6 digit hex string.

Returns:
color as hex

toHSVAArray

public float[] toHSVAArray(float[] hsva)
Specified by:
toHSVAArray in interface ReadonlyTColor
Parameters:
hsva - result array (or null)
Returns:
Copies the the current HSV values into the given array (or constucts a new one with these values).

toRGBAArray

public float[] toRGBAArray(float[] rgba)
Description copied from interface: ReadonlyTColor
Copies the current RGBA value into the given array (or constucts a new one with these values).

Specified by:
toRGBAArray in interface ReadonlyTColor
Parameters:
rgba - result array (or null)
Returns:
array in this order: r,g,b,a (OpenGL format)

toRGBAArray

public float[] toRGBAArray(float[] rgba,
                           int offset)
Description copied from interface: ReadonlyTColor
Copies the current RGBA value into the given array starting the given offset. If the array is null, the method constucts a new one with these values and the offset value is ignored (set to zero).

Specified by:
toRGBAArray in interface ReadonlyTColor
Returns:
float array

toString

public java.lang.String toString()
Overrides:
toString in class java.lang.Object

yellow

public float yellow()
Specified by:
yellow in interface ReadonlyTColor
Returns:
the color's yellow component