toxi.color
Class ColorRange

java.lang.Object
  extended by toxi.color.ColorRange

public class ColorRange
extends java.lang.Object

A ColorRange is a set of contraints to specify possible ranges for hue, saturation, brightness and alpha independently and use these as creation rules for new TColors or ColorLists. The class comes with 11 preset ranges reflecting common demands and color characters. You can also construct new ranges and manually add additional constraints. Unless the constraints in a range are very narrow the class will always create random variations within the constraints. Please see the examples for further details. ColorRanges are a key ingredient for defining ColorThemes but can also be used individually.


Field Summary
static ColorRange BRIGHT
          Shade definition: saturation 80-100%, brightness: 80-100%
static ColorRange COOL
          Shade definition: saturation 5-20%, brightness: 90-100%
static ColorRange DARK
          Shade definition: saturation 70-100%, brightness: 15-40%
static float DEFAULT_VARIANCE
          Default hue variance for getColor(ReadonlyTColor, float)
static ColorRange FRESH
          Shade definition: saturation 40-80%, brightness: 80-100%
static ColorRange HARD
          Shade definition: saturation 90-100%, brightness: 40-100%
static ColorRange INTENSE
          Shade definition: saturation 90-100%, brightness: 20-35% or 80-100%
static ColorRange LIGHT
          Shade definition: saturation 30-70%, brightness: 90-100%
static ColorRange NEUTRAL
          Shade definition: saturation 25-35%, brightness: 30-70%
static java.util.HashMap<java.lang.String,ColorRange> PRESETS
          List of ColorRange presets.
static ColorRange SOFT
          Shade definition: saturation 20-30%, brightness: 60-90%
static ColorRange WARM
          Shade definition: saturation 60-90%, brightness: 40-90%
static ColorRange WEAK
          Shade definition: saturation 15-30%, brightness: 70-100%
 
Constructor Summary
ColorRange(ColorList list)
          Constructs a new range using the given colors as HSV constraints.
ColorRange(toxi.util.datatypes.FloatRange hue, toxi.util.datatypes.FloatRange sat, toxi.util.datatypes.FloatRange bri, toxi.util.datatypes.FloatRange alpha, toxi.util.datatypes.FloatRange black, toxi.util.datatypes.FloatRange white, java.lang.String name)
          Constructs a new range with the supplied constraints (if an HSV argument is null, a range of 0.0 ...
ColorRange(toxi.util.datatypes.FloatRange hue, toxi.util.datatypes.FloatRange sat, toxi.util.datatypes.FloatRange bri, toxi.util.datatypes.FloatRange alpha, java.lang.String name)
          Constructs a new range with the supplied constraints (if an argument is null, a range of 0.0 ...
ColorRange(toxi.util.datatypes.FloatRange hue, toxi.util.datatypes.FloatRange sat, toxi.util.datatypes.FloatRange bri, java.lang.String name)
          Constructs a new range with the supplied constraints (if an argument is null, a range of 0.0 ...
ColorRange(Hue hue)
          Constructs a new range using the given hue as constraint, but saturation and brightness are fully flexible.
ColorRange(ReadonlyTColor c)
          Constructs a new range using the hue of the given color as hue constraint, but saturation and brightness are fully flexible.
 
Method Summary
 ColorRange add(ColorRange range)
          Adds the contraints of the given range to this range and forms unions for the black and white point ranges.
 ColorRange add(ReadonlyTColor c)
          Adds the HSV color components as constraints.
 ColorRange addAlphaRange(float min, float max)
          Adds the range between min-max as possible alpha values for this range.
 ColorRange addAlphaRange(toxi.util.datatypes.FloatRange alpha)
          Adds an additional alpha constraint.
 ColorRange addBrightnessRange(float min, float max)
          Adds the range between min-max as possible brightness values for this range.
 ColorRange addBrightnessRange(toxi.util.datatypes.FloatRange bri)
          Adds an additional brightness constraint.
 ColorRange addHue(Hue hue)
          Add the given hue as hue constraint.
 ColorRange addHueRange(float min, float max)
          Adds the range between min-max as possible hue values for this range.
 ColorRange addHueRange(toxi.util.datatypes.FloatRange hue)
          Adds an additional hue constraint.
 ColorRange addSaturationRange(float min, float max)
          Adds the range between min-max as possible saturation values for this range.
 ColorRange addSaturationRange(toxi.util.datatypes.FloatRange sat)
          Adds an additional saturation constraint.
 boolean contains(ReadonlyTColor c)
          Checks if all HSVA components of the given color are within the constraints defined for this range.
 ColorRange copy()
          Creates a shallow copy of the range.
 ColorRange copy(ReadonlyTColor c, float variance)
          Creates a copy of the range but overrides the hue and alpha constraints taken from the given color (if specified).
 TColor getColor()
          Creates a new color based on the flexible constraints of the range.
 TColor getColor(Hue hue)
          Creates a new shade of the given hue based on the other constraints of the range.
 TColor getColor(ReadonlyTColor c, float variance)
          Creates a new color based on the constraints defined in the range.
 ColorList getColors(int num)
          Creates a new ColorList of colors based on the constraints of this range.
 ColorList getColors(ReadonlyTColor c, int num, float variance)
          Creates a new ColorList of shades of the given TColor based on the other constraints of the range.
 TColor getGrayscale(float brightness, float variance)
          Creates a new shade of gray based on the input brightness and the black and white constraints of the range.
 java.lang.String getName()
           
static ColorRange getPresetForName(java.lang.String name)
          Retrieves one of the predefined ranges by name.
 ColorRange getSum(ColorRange range)
          Creates a copy of the current range and adds the given one to it.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

DEFAULT_VARIANCE

public static final float DEFAULT_VARIANCE
Default hue variance for getColor(ReadonlyTColor, float)

See Also:
Constant Field Values

LIGHT

public static final ColorRange LIGHT
Shade definition: saturation 30-70%, brightness: 90-100%


DARK

public static final ColorRange DARK
Shade definition: saturation 70-100%, brightness: 15-40%


BRIGHT

public static final ColorRange BRIGHT
Shade definition: saturation 80-100%, brightness: 80-100%


WEAK

public static final ColorRange WEAK
Shade definition: saturation 15-30%, brightness: 70-100%


NEUTRAL

public static final ColorRange NEUTRAL
Shade definition: saturation 25-35%, brightness: 30-70%


FRESH

public static final ColorRange FRESH
Shade definition: saturation 40-80%, brightness: 80-100%


SOFT

public static final ColorRange SOFT
Shade definition: saturation 20-30%, brightness: 60-90%


HARD

public static final ColorRange HARD
Shade definition: saturation 90-100%, brightness: 40-100%


WARM

public static final ColorRange WARM
Shade definition: saturation 60-90%, brightness: 40-90%


COOL

public static final ColorRange COOL
Shade definition: saturation 5-20%, brightness: 90-100%


INTENSE

public static final ColorRange INTENSE
Shade definition: saturation 90-100%, brightness: 20-35% or 80-100%


PRESETS

public static final java.util.HashMap<java.lang.String,ColorRange> PRESETS
List of ColorRange presets.

Constructor Detail

ColorRange

public ColorRange(ColorList list)
Constructs a new range using the given colors as HSV constraints.

Parameters:
list - list base colors

ColorRange

public ColorRange(toxi.util.datatypes.FloatRange hue,
                  toxi.util.datatypes.FloatRange sat,
                  toxi.util.datatypes.FloatRange bri,
                  toxi.util.datatypes.FloatRange alpha,
                  toxi.util.datatypes.FloatRange black,
                  toxi.util.datatypes.FloatRange white,
                  java.lang.String name)
Constructs a new range with the supplied constraints (if an HSV argument is null, a range of 0.0 ... 1.0 is created automatically for that constraint). If alpha is left undefined, it'll be initialized to fully opaque only. You can also specify ranges for possible black and white points which are used if the range is later applied to a grayscale color. The default black point is at 0.0 and white at 1.0.

Parameters:
hue -
sat -
bri -
alpha -
black -
white -
name -

ColorRange

public ColorRange(toxi.util.datatypes.FloatRange hue,
                  toxi.util.datatypes.FloatRange sat,
                  toxi.util.datatypes.FloatRange bri,
                  toxi.util.datatypes.FloatRange alpha,
                  java.lang.String name)
Constructs a new range with the supplied constraints (if an argument is null, a range of 0.0 ... 1.0 is created automatically for that constraint).

Parameters:
hue - min/max hue range
sat - min/max saturation range
bri - min/max brightness range
alpha - min/max alpha range (if null, initialized to 100% only)
name -

ColorRange

public ColorRange(toxi.util.datatypes.FloatRange hue,
                  toxi.util.datatypes.FloatRange sat,
                  toxi.util.datatypes.FloatRange bri,
                  java.lang.String name)
Constructs a new range with the supplied constraints (if an argument is null, a range of 0.0 ... 1.0 is created automatically for that constraint). Alpha constraint will be set to 100%.

Parameters:
hue - min/max hue range
sat - min/max saturation range
bri - min/max brightness range
name -

ColorRange

public ColorRange(Hue hue)
Constructs a new range using the given hue as constraint, but saturation and brightness are fully flexible. The resulting range will produce any shade of the given hue.

Parameters:
hue - base hue

ColorRange

public ColorRange(ReadonlyTColor c)
Constructs a new range using the hue of the given color as hue constraint, but saturation and brightness are fully flexible. The resulting range will produce any shade of the given color.

Parameters:
c - base color
Method Detail

getPresetForName

public static ColorRange getPresetForName(java.lang.String name)
Retrieves one of the predefined ranges by name.

Parameters:
name -
Returns:
color range or null if name not registered

add

public ColorRange add(ColorRange range)
Adds the contraints of the given range to this range and forms unions for the black and white point ranges.

Parameters:
range - color range to add
Returns:
itself

add

public ColorRange add(ReadonlyTColor c)
Adds the HSV color components as constraints.

Parameters:
c - color to use as constraint
Returns:
itself

addAlphaRange

public ColorRange addAlphaRange(float min,
                                float max)
Adds the range between min-max as possible alpha values for this range.

Parameters:
min -
max -
Returns:
itself

addAlphaRange

public ColorRange addAlphaRange(toxi.util.datatypes.FloatRange alpha)
Adds an additional alpha constraint.

Parameters:
alpha - min/max alpha values
Returns:
itself

addBrightnessRange

public ColorRange addBrightnessRange(float min,
                                     float max)
Adds the range between min-max as possible brightness values for this range.

Parameters:
min -
max -
Returns:
itself

addBrightnessRange

public ColorRange addBrightnessRange(toxi.util.datatypes.FloatRange bri)
Adds an additional brightness constraint.

Parameters:
bri - min/max brightness values
Returns:
itself

addHue

public ColorRange addHue(Hue hue)
Add the given hue as hue constraint.

Parameters:
hue -
Returns:
itself

addHueRange

public ColorRange addHueRange(float min,
                              float max)
Adds the range between min-max as possible hue values for this range. If max < min then two intervals are added: {min ... 1.0} and {0.0 ... max}

Parameters:
min -
max -
Returns:
itself

addHueRange

public ColorRange addHueRange(toxi.util.datatypes.FloatRange hue)
Adds an additional hue constraint.

Parameters:
hue - min/max hue values
Returns:
itself

addSaturationRange

public ColorRange addSaturationRange(float min,
                                     float max)
Adds the range between min-max as possible saturation values for this range.

Parameters:
min -
max -
Returns:
itself

addSaturationRange

public ColorRange addSaturationRange(toxi.util.datatypes.FloatRange sat)
Adds an additional saturation constraint.

Parameters:
sat - min/max saturation values
Returns:
itself

contains

public boolean contains(ReadonlyTColor c)
Checks if all HSVA components of the given color are within the constraints defined for this range.

Parameters:
c - color to check
Returns:
true, if color is contained

copy

public ColorRange copy()
Creates a shallow copy of the range.

Returns:
copy

copy

public ColorRange copy(ReadonlyTColor c,
                       float variance)
Creates a copy of the range but overrides the hue and alpha constraints taken from the given color (if specified).

Parameters:
c - color, if the new range is to be used to create specific shades of that color only
variance - hue variance (use DEFAULT_VARIANCE for default)
Returns:
copy

getColor

public TColor getColor()
Creates a new color based on the flexible constraints of the range.

Returns:
color

getColor

public TColor getColor(Hue hue)
Creates a new shade of the given hue based on the other constraints of the range.

Parameters:
hue -
Returns:
color

getColor

public TColor getColor(ReadonlyTColor c,
                       float variance)
Creates a new color based on the constraints defined in the range. If an input color is specified, the method will use the hue of that color and the given variance to create a shade of a hue within the tolerance.

Parameters:
c -
variance -
Returns:
color

getColors

public ColorList getColors(int num)
Creates a new ColorList of colors based on the constraints of this range.

Parameters:
num - number of colors to create
Returns:
color list
See Also:
getColor()

getColors

public ColorList getColors(ReadonlyTColor c,
                           int num,
                           float variance)
Creates a new ColorList of shades of the given TColor based on the other constraints of the range.

Parameters:
c - base color
num - number of colors to create
variance - hue variance
Returns:
color list
See Also:
getColor(ReadonlyTColor, float)

getGrayscale

public TColor getGrayscale(float brightness,
                           float variance)
Creates a new shade of gray based on the input brightness and the black and white constraints of the range.

Parameters:
brightness - input brightness
variance - hue variance (this might seem irrevelant, but might be important if the created color is being saturated later on)
Returns:
color/shade of gray

getName

public java.lang.String getName()
Returns:
name of the range

getSum

public ColorRange getSum(ColorRange range)
Creates a copy of the current range and adds the given one to it.

Parameters:
range - range to add
Returns:
summed copy
See Also:
add(ColorRange)