vona.color

Class Hue

java.lang.Object

vona.color.Hue

public class Hue
extends java.lang.Object

Vona's utils: a color hue, a-la "Color Bytes" by Jean Bourges.

Bourges, Jean. (1997). Color Bytes. Forest Hills, New York: Chromatics Press, Inc.

Jean Bourges is the daughter of Albert R. Bourges (1881-1955), a pioneer in color theory. In "Color Bytes", she documents a practical approach to colors.

The Bourges system first identifies 20 particular "hue"s (see the *Hue constants in this class and getHue(int)) which, when plotted in the CIE 1976 La*b* color space, form an approximate circle around the origin. Thus, the hues form a color wheel, and connecting them in a closed chain imposes a path through color space that is homeomorphic to a circle. Already this is quite useful, as it enables one-parameter interpolation across a color spectrum (see getHue(double) and interpolateHue(vona.color.Hue, vona.color.Hue, double)), and it pre-selects 20 "nice" colors and assigns them intuitive, human-understandable names (see getName()).

A hue defines a basic color, called herein the "maximum tint", or simply "the color" of the hue (see getColor(), but three additional knobs can be turned on a hue to generate associated colors (see getColor(float, float, float)):

• the tint can be varied from MIN_TINT to MAX_TINT, which effectively makes the color "softer" or "louder"
• a mix-in black component can be varied from MIN_BLACK to MAX_BLACK, making the color "lighter" or "darker"
• the alpha component can be varied from MIN_ALPHA to MAX_ALPHA, making the color more or less transparent

Bourges goes further, showing that, given a "primary" hue, one can associate three other hues:

• a "related" hue (see getRelated())
• a "compliment" hue (see getCompliment())
• a "compliment related" hue (getCompliment().getRelated())

such that the quad of all four hues works well together as a ColorScheme.

The first ten hues are "warm" (see isWarm()), the latter ten are "cool" (see isCool()). The compliment of a warm hue is always cool and vice versa, and the related hue of a warm hue is warm and the related hue of a cool hue is cool. So color schemes (quads of 4 hues as described above) always have a nice balance: they always contain two warm and two cool hues.

Copyright (C) 2004 Marsette A. Vona, III

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.

Author:

Marsette (Marty) A. Vona, III

Field Summary

Fields

Modifier and Type	Field and Description
static Hue	amberHue hue from "Color Bytes" by Jean Bourges
static Hue	blueVioletHue hue from "Color Bytes" by Jean Bourges
static Hue	coralHue hue from "Color Bytes" by Jean Bourges
static Hue	crimsonHue hue from "Color Bytes" by Jean Bourges
private static java.lang.String	cvsid CVS id.
static Hue	cyanHue hue from "Color Bytes" by Jean Bourges
static Hue	emraldHue hue from "Color Bytes" by Jean Bourges
static Hue	goldHue hue from "Color Bytes" by Jean Bourges
static double	HUE_SNAP If the where value is closer than this to the from or to values in interpolateHue(Hue, Hue, double) then the corresponding endpoint Hue is returned directly.
protected static Hue[]	hues All 20 hues from "Color Bytes" by Jean Bourges.
int	index The index of this Hue.
static Hue	leafGreenHue hue from "Color Bytes" by Jean Bourges
static Hue	lemonHue hue from "Color Bytes" by Jean Bourges
static Hue	limeHue hue from "Color Bytes" by Jean Bourges
static Hue	magentaHue hue from "Color Bytes" by Jean Bourges
static Hue	mauveHue hue from "Color Bytes" by Jean Bourges
static float	MAX_ALPHA Maximum typical alpha value.
static float	MAX_BLACK Maximum typical black value.
static float	MAX_TINT Maximum typical tint value.
int	maxB The blue component of the maximum Hue color, in the range [0, 255].
int	maxG The green component of the maximum Hue color, in the range [0, 255].
int	maxR The red component of the maximum Hue color, in the range [0, 255].
java.awt.Color	maxTint The Color of this hue at maximum tint (maxR, maxG, maxB).
static float	MIN_ALPHA Minimum typical alpha value.
static float	MIN_BLACK Minimum typical black value.
static float	MIN_TINT Minimum typical tint value.
int	minB The blue component of the minimum Hue color, in the range [0, 255].
int	minG The green component of the minimum Hue color, in the range [0, 255].
int	minR The red component of the minimum Hue color, in the range [0, 255].
java.awt.Color	minTint The Color of this hue at minimum tint (minR, minG, minB).
java.lang.String	name The name of this Hue.
static Hue	orangeHue hue from "Color Bytes" by Jean Bourges
static Hue	posterRedHue hue from "Color Bytes" by Jean Bourges
static Hue	purpleHue hue from "Color Bytes" by Jean Bourges
static Hue	scarletHue hue from "Color Bytes" by Jean Bourges
static Hue	seaGreenHue hue from "Color Bytes" by Jean Bourges
static Hue	skyBlueHue hue from "Color Bytes" by Jean Bourges
static java.awt.color.ColorSpace	sRGBSpace The sRGB ColorSpace from ColorSpace.getInstance(ColorSpace.CS_sRGB).
static Hue	tealHue hue from "Color Bytes" by Jean Bourges
static Hue	ultramarineHue hue from "Color Bytes" by Jean Bourges

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	Hue(int index, java.lang.String name, int maxR, int maxG, int maxB) covers full constructor, uses 255 for min tint components
protected	Hue(int index, java.lang.String name, int maxR, int maxG, int maxB, int minR, int minG, int minB) Create a new Hue.

Method Summary

Methods

Modifier and Type	Method and Description
static java.awt.Color	convertColor(java.awt.Color color, java.awt.color.ColorSpace toSpace) Convert color to toSpace.
static java.awt.Color	convertColor(java.awt.Color color, int toSpace) Same as convertColor(Color, ColorSpace) but gets the target ColorSpace from ColorSpace.getInstance(toSpace).
boolean	equals(java.lang.Object o) Check whether this Hue equals another Object.
java.awt.Color	getColor() Cover of getMaxTint().
java.awt.Color	getColor(java.awt.color.ColorSpace colorSpace, float relTint) Same as getColor(ColorSpace, float, float) but uses 0.0 black.
java.awt.Color	getColor(java.awt.color.ColorSpace colorSpace, float relTint, float relBlack) Same as getColor(ColorSpace, float, float, float) but uses 1.0 alpha.
java.awt.Color	getColor(java.awt.color.ColorSpace colorSpace, float relTint, float relBlack, float relAlpha) Get a Color associated with this Hue by specifying the tint, black and alpha attributes.
java.awt.Color	getColor(float relTint) Same as getColor(ColorSpace, float) but uses default ColorSpace.
java.awt.Color	getColor(float relTint, float relBlack) Same as getColor(ColorSpace, float, float) but uses default ColorSpace.
java.awt.Color	getColor(float relTint, float relBlack, float relAlpha) Same as getColor(ColorSpace, float, float, float) but uses default ColorSpace.
Hue	getCompliment() Get the "complimentary" Hue to this one.
static Hue	getHue(double where) Get an arbitrary Hue.
static Hue	getHue(int index) Get one of the getNumHues() hues by index.
static Hue	getHue(java.lang.String name) Get one of the hues by name.
int	getIndex() Get the index of this Hue.
java.awt.Color	getMaxTint() Get the maximum tint color of this Hue, (maxR, maxG, maxB).
java.awt.Color	getMinTint() Get the minimum tint color of this Hue, (minR, minG, minB).
java.lang.String	getName() Get the name of this Hue.
static int	getNumHues() Get the number of hues available from getHue(int).
Hue	getRelated() Get the "related" Hue to this one.
static float	interpolate(float from, float to, double where) Interpolate between from and to.
static float	interpolate(int from, int to, double where) Interpolate between integer components from and to.
static float	interpolateAlpha(double where) interpolate(int, int, double) between MIN_ALPHA and MAX_ALPHA.
static float	interpolateBlack(double where) interpolate(int, int, double) between MIN_BLACK and MAX_BLACK.
static Hue	interpolateHue(Hue from, Hue to, double where) Interpolate between two Hues.
static int	interpolateRGB(int from, int to, double where) Interpolate an integer RGB component between from and to.
static float	interpolateTint(double where) interpolate(int, int, double) between MIN_TINT and MAX_TINT.
boolean	isCool() Check whether this is a "cool" hue.
static boolean	isValidComponent(double c) Check whether c is a valid double component in the range [0.0, 1.0].
static boolean	isValidComponent(float c) Check whether c is a valid float component in the range [0.0, 1.0].
static boolean	isValidComponent(int c) Check whether c is a valid integer component in the range [0, 255].
static boolean	isValidIndex(int index) Check whether index is a valid Hue index in the range [1, 20].
boolean	isWarm() Check whether this is a "warm" hue.
static float	normalize(int c) Convert an integer component in the range [0, 255] to a float in the range [0.0, 1.0].
static int	percent(double value) Convert a double value in the range [0.0, 1.0] to an integer percent in the range [0, 100].
static int	percentToComponent(int percent) Convert a percent in the range [0, 100] to an integer component in the range [0, 255].
java.lang.String	toString() Return a human-readable description of this Hue.

Methods inherited from class java.lang.Object

clone, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

cvsid

private static final java.lang.String cvsid

CVS id.

See Also:

Constant Field Values

MIN_TINT

public static final float MIN_TINT

Minimum typical tint value.

See Also:

Constant Field Values

MAX_TINT

public static final float MAX_TINT

Maximum typical tint value.

See Also:

Constant Field Values

MIN_BLACK

public static final float MIN_BLACK

Minimum typical black value.

See Also:

Constant Field Values

MAX_BLACK

public static final float MAX_BLACK

Maximum typical black value.

See Also:

Constant Field Values

MIN_ALPHA

public static final float MIN_ALPHA

Minimum typical alpha value.

See Also:

Constant Field Values

MAX_ALPHA

public static final float MAX_ALPHA

Maximum typical alpha value.

See Also:

Constant Field Values

HUE_SNAP

public static final double HUE_SNAP

If the where value is closer than this to the from or to values in interpolateHue(Hue, Hue, double) then the corresponding endpoint Hue is returned directly.

See Also:

Constant Field Values

mauveHue

public static final Hue mauveHue

hue from "Color Bytes" by Jean Bourges

magentaHue

public static final Hue magentaHue

hue from "Color Bytes" by Jean Bourges

crimsonHue

public static final Hue crimsonHue

hue from "Color Bytes" by Jean Bourges

scarletHue

public static final Hue scarletHue

hue from "Color Bytes" by Jean Bourges

posterRedHue

public static final Hue posterRedHue

hue from "Color Bytes" by Jean Bourges

coralHue

public static final Hue coralHue

hue from "Color Bytes" by Jean Bourges

orangeHue

public static final Hue orangeHue

hue from "Color Bytes" by Jean Bourges

amberHue

public static final Hue amberHue

hue from "Color Bytes" by Jean Bourges

goldHue

public static final Hue goldHue

hue from "Color Bytes" by Jean Bourges

lemonHue

public static final Hue lemonHue

hue from "Color Bytes" by Jean Bourges

limeHue

public static final Hue limeHue

hue from "Color Bytes" by Jean Bourges

leafGreenHue

public static final Hue leafGreenHue

hue from "Color Bytes" by Jean Bourges

seaGreenHue

public static final Hue seaGreenHue

hue from "Color Bytes" by Jean Bourges

emraldHue

public static final Hue emraldHue

hue from "Color Bytes" by Jean Bourges

tealHue

public static final Hue tealHue

hue from "Color Bytes" by Jean Bourges

cyanHue

public static final Hue cyanHue

hue from "Color Bytes" by Jean Bourges

skyBlueHue

public static final Hue skyBlueHue

hue from "Color Bytes" by Jean Bourges

ultramarineHue

public static final Hue ultramarineHue

hue from "Color Bytes" by Jean Bourges

blueVioletHue

public static final Hue blueVioletHue

hue from "Color Bytes" by Jean Bourges

purpleHue

public static final Hue purpleHue

hue from "Color Bytes" by Jean Bourges

hues

protected static final Hue[] hues

All 20 hues from "Color Bytes" by Jean Bourges.

sRGBSpace

public static final java.awt.color.ColorSpace sRGBSpace

The sRGB ColorSpace from ColorSpace.getInstance(ColorSpace.CS_sRGB).

index

public final int index

The index of this Hue.

TBD switch this to a double to better handle interpolated hues

name

public final java.lang.String name

The name of this Hue.

maxR

public final int maxR

The red component of the maximum Hue color, in the range [0, 255].

maxG

public final int maxG

The green component of the maximum Hue color, in the range [0, 255].

maxB

public final int maxB

The blue component of the maximum Hue color, in the range [0, 255].

minR

public final int minR

The red component of the minimum Hue color, in the range [0, 255].

minG

public final int minG

The green component of the minimum Hue color, in the range [0, 255].

minB

public final int minB

The blue component of the minimum Hue color, in the range [0, 255].

maxTint

public final java.awt.Color maxTint

The Color of this hue at maximum tint (maxR, maxG, maxB).

minTint

public final java.awt.Color minTint

The Color of this hue at minimum tint (minR, minG, minB).

Constructor Detail

Hue

protected Hue(int index,
   java.lang.String name,
   int maxR,
   int maxG,
   int maxB,
   int minR,
   int minG,
   int minB)

Create a new Hue.

Protected: get Hues from getHue(int), getHue(double), or interpolateHue(vona.color.Hue, vona.color.Hue, double).

Parameters:

index - the index of this hue, 1-based, corresponding to the list of 20 hues from "Color Bytes" by Jean Bourges

name - the name of the Hue

maxR - the red component of the maximum Hue color, in the range [0, 255]

maxG - the green component of the maximum Hue color, in the range [0, 255]

maxB - the blue component of the maximum Hue color, in the range [0, 255]

minR - the red component of the minimum Hue color, in the range [0, 255]

minG - the green component of the minimum Hue color, in the range [0, 255]

minB - the blue component of the maximum Hue color, in the range [0, 255]

Hue

protected Hue(int index,
   java.lang.String name,
   int maxR,
   int maxG,
   int maxB)

covers full constructor, uses 255 for min tint components

Method Detail

convertColor

public static java.awt.Color convertColor(java.awt.Color color,
                          int toSpace)

Same as convertColor(Color, ColorSpace) but gets the target ColorSpace from ColorSpace.getInstance(toSpace).

Parameters:

toSpace - identifies the target ColorSpace

convertColor

public static java.awt.Color convertColor(java.awt.Color color,
                          java.awt.color.ColorSpace toSpace)

Convert color to toSpace.

Parameters:

color - the color to convert, not null

toSpace - the target ColorSpace, if null sRGBSpace is used

Returns:

the a new corresponding Color in toSpace, unless the ColorSpace of the input color was already toSpace, in which case a reference to the input color is returned

isValidIndex

public static boolean isValidIndex(int index)

Check whether index is a valid Hue index in the range [1, 20].

Parameters:

index - the index to check

Returns:

true iff index is a valid Hue index in the range [1, 20]

isValidComponent

public static boolean isValidComponent(int c)

Check whether c is a valid integer component in the range [0, 255].

Parameters:

c - the component to check

Returns:

true iff c is a valid integer component in the range [0, 255]

isValidComponent

public static boolean isValidComponent(float c)

Check whether c is a valid float component in the range [0.0, 1.0].

Parameters:

c - the component to check

Returns:

true iff c is a valid float component in the range [0.0, 1.0]

isValidComponent

public static boolean isValidComponent(double c)

Check whether c is a valid double component in the range [0.0, 1.0].

Parameters:

c - the component to check

Returns:

true iff c is a valid double component in the range [0.0, 1.0]

normalize

public static float normalize(int c)

Convert an integer component in the range [0, 255] to a float in the range [0.0, 1.0].

Parameters:

c - the integer to convert

Returns:

the corresponding normalized float

interpolate

public static float interpolate(int from,
                int to,
                double where)

Interpolate between integer components from and to.

Parameters:

from - the start point of interpolation, in the range [0, 255], will be normalize(int)d

to - the end point of interpolation, in the range [0, 255], will be normalize()d

where - the interpolation point

Returns:

where between from and to

interpolate

public static float interpolate(float from,
                float to,
                double where)

Interpolate between from and to.

Parameters:

from - the start point of interpolation

to - the end point of interpolation

where - the interpolation point

Returns:

where between from and to

interpolateRGB

public static int interpolateRGB(int from,
                 int to,
                 double where)

Interpolate an integer RGB component between from and to.

Parameters:

from - the start point of interpolation

to - the end point of interpolation

where - the interpolation point

Returns:

where between from and to

interpolateTint

public static float interpolateTint(double where)

interpolate(int, int, double) between MIN_TINT and MAX_TINT.

Parameters:

where - the interpolation point

Returns:

where between MIN_TINT and MAX_TINT

interpolateBlack

public static float interpolateBlack(double where)

interpolate(int, int, double) between MIN_BLACK and MAX_BLACK.

Parameters:

where - the interpolation point

Returns:

where between MIN_BLACK and MAX_BLACK

interpolateAlpha

public static float interpolateAlpha(double where)

interpolate(int, int, double) between MIN_ALPHA and MAX_ALPHA.

Parameters:

where - the interpolation point

Returns:

where between MIN_ALPHA and MAX_ALPHA

percent

public static int percent(double value)

Convert a double value in the range [0.0, 1.0] to an integer percent in the range [0, 100].

Parameters:

value - the value to convert

Returns:

the corresponding percent

percentToComponent

public static int percentToComponent(int percent)

Convert a percent in the range [0, 100] to an integer component in the range [0, 255].

Parameters:

percent - the percent to convert

Returns:

the corresponding component value

getHue

public static Hue getHue(int index)

Get one of the getNumHues() hues by index.

The first hue is at index 1 in conformance with the Bourges numbering.

Parameters:

index - the one-based index of the hue in the range [1, getNumHues()]

Returns:

the corresponding hue

getNumHues

public static int getNumHues()

Get the number of hues available from getHue(int).

Returns:

the number of hues available from getHue(int)

getHue

public static Hue getHue(java.lang.String name)

Get one of the hues by name.

Parameters:

name - the name of the hue

Returns:

the hue with the given name, compared case-insensitive, or null if not found

getHue

public static Hue getHue(double where)

Get an arbitrary Hue.

Parameters:

where - a normalized index in the range [0.0, 1.0]

Returns:

if where is closer than HUE_SNAP to one of the 20 hues from "Color Bytes" by Jean Bourges, return a reference to that Hue. Otherwise a new Hue is interpolated, see interpolateHue(vona.color.Hue, vona.color.Hue, double)

interpolateHue

public static Hue interpolateHue(Hue from,
                 Hue to,
                 double where)

Interpolate between two Hues.

Parameters:

from - the bottom hue

to - the top hue

where - the interpolation point

Returns:

a new Hue, with index -1, interpolated between from and to, unless where value is closer than HUE_SNAP to from or to value, in which case the corresponding endpoint Hue is returned directly

getColor

public java.awt.Color getColor(java.awt.color.ColorSpace colorSpace,
                      float relTint,
                      float relBlack,
                      float relAlpha)

Get a Color associated with this Hue by specifying the tint, black and alpha attributes.

Parameters:

colorSpace - the ColorSpace in which to return the color, if null then sRGBSpace

relTint - the relative tint, i.e. between minTint and maxTint, in the range [0.0, 1.0]

relBlack - the relative black, i.e. between MIN_BLACK and MAX_BLACK, in the range [0.0, 1.0]

relAlpha - the relative alpha, i.e. between MIN_ALPHA and MAX_ALPHA, in the range [0.0, 1.0]

getColor

public java.awt.Color getColor(float relTint,
                      float relBlack,
                      float relAlpha)

Same as getColor(ColorSpace, float, float, float) but uses default ColorSpace.

getColor

public java.awt.Color getColor(java.awt.color.ColorSpace colorSpace,
                      float relTint,
                      float relBlack)

Same as getColor(ColorSpace, float, float, float) but uses 1.0 alpha.

getColor

public java.awt.Color getColor(float relTint,
                      float relBlack)

Same as getColor(ColorSpace, float, float) but uses default ColorSpace.

getColor

public java.awt.Color getColor(java.awt.color.ColorSpace colorSpace,
                      float relTint)

Same as getColor(ColorSpace, float, float) but uses 0.0 black.

getColor

public java.awt.Color getColor(float relTint)

Same as getColor(ColorSpace, float) but uses default ColorSpace.

getColor

public java.awt.Color getColor()

Cover of getMaxTint().

getMaxTint

public java.awt.Color getMaxTint()

Get the maximum tint color of this Hue, (maxR, maxG, maxB).

Returns:

the maximum tint color of this hue

getMinTint

public java.awt.Color getMinTint()

Get the minimum tint color of this Hue, (minR, minG, minB).

Returns:

the minimum tint color of this hue

getIndex

public int getIndex()

Get the index of this Hue.

Returns:

the index of this Hue

getName

public java.lang.String getName()

Get the name of this Hue.

Returns:

the name of this Hue

toString

public java.lang.String toString()

Return a human-readable description of this Hue.

Overrides:

toString in class java.lang.Object

Returns:

a human-readable description of this Hue.

isWarm

public boolean isWarm()

Check whether this is a "warm" hue.

Returns:

true iff this is a "warm" hue

isCool

public boolean isCool()

Check whether this is a "cool" hue.

Returns:

true iff this is a "cool" hue

getCompliment

public Hue getCompliment()

Get the "complimentary" Hue to this one.

Works only if this is one of the 20 hues from "Color Bytes" by Jean Bourges (i.e. iff this is not an interpolated Hue).

Returns:

the complimentary hue

getRelated

public Hue getRelated()

Get the "related" Hue to this one.

Works only if this is one of the 20 hues from "Color Bytes" by Jean Bourges (i.e. iff this is not an interpolated Hue).

Returns:

the related hue

equals

public boolean equals(java.lang.Object o)

Check whether this Hue equals another Object.

Overrides:

equals in class java.lang.Object

Parameters:

o - the Object to check

Returns:

true iff o is a Hue with the same maxR, maxG, maxB, and minR, minG, minB