com.physpics.tools

Class SSColor

java.lang.Object

java.awt.Color

com.physpics.tools.SSColor

All Implemented Interfaces:

java.awt.Paint, java.awt.Transparency, Serializable

public class SSColor
extends java.awt.Color

An SSColor object encapsulates a color value and information about the source string. The value is parsed from a String and is one of the forms described in from(StringScanner).

If the string is invalid, the value is DEFAULT_COLOR. It is almost black, but not black so black itself is valid.

The constructor with a StringScanner argument advances the scanner across the color name.

The arguments to the Color class constructors always list the alpha value last: 'rgba' or 'int r, int g, int b, int a' HOWEVER, when color is an integer, the bytes are ordered a r g b

The list of color names is in an asset called colorlist.csv. At build time, that list is copied from physpics.com/pictools/colorlist.csv. Neither list is expected to change, but if either does, they may diverge. An individual user may install a private, modifiable list in ~/.physpics/assets/com.physpics.tools/colorlist.csv.

SSColor is among the physpics color tools listed in http://physpics.com/Essays/coding/ColorTools.php.

See Also:

Serialized Form

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	SSColor.PopupForTextField Provide a color completion popup menu to augment a JTextField.

Field Summary

Fields

Modifier and Type	Field and Description
static SSColor	DEFAULT_COLOR
protected int[]	hsl
protected java.lang.String	key
java.lang.String	link
protected static int	nNamedColors how many colors come from colorlist.csv + DEFAULT_COLOR
protected static java.util.HashMap<java.lang.Integer,java.util.ArrayList<SSColor>>	registered Map from color value to an ArrayList of SSColors having that color.
protected java.lang.String	source
protected static java.util.HashMap<java.lang.String,java.util.ArrayList<SSColor>>	stemMap Map from name stem to list of colors with that stem.
protected java.lang.String	stemName
protected int	variant

Fields inherited from class java.awt.Color

black, BLACK, blue, BLUE, cyan, CYAN, DARK_GRAY, darkGray, gray, GRAY, green, GREEN, LIGHT_GRAY, lightGray, magenta, MAGENTA, orange, ORANGE, pink, PINK, red, RED, white, WHITE, yellow, YELLOW

Fields inherited from interface java.awt.Transparency

BITMASK, OPAQUE, TRANSLUCENT

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	SSColor(int i, boolean hasAlpha) Construct an SSColor for a given integer, possibly including alpha.

Method Summary

Modifier and Type	Method and Description
SSColor	brighter()
static java.util.ArrayList<SSColor>	colorRegistrees(int avalue)
static java.util.ArrayList<java.lang.String>	continuations(java.lang.String input)
SSColor	darker()
static SSColor	from(java.awt.Color klr) Convert a color value to an SSColor with the same value.
static SSColor	from(int value) Convert a Color to an SSColor with the same value.
static SSColor	from(int value, boolean hasAlpha) Convert a color value with alpha to an SSColor with the same value.
static SSColor	from(int r, int g, int b) Combine three int values into an rgb.
static SSColor	from(java.lang.String klrspec) Parse a string as a color spec and return a corresponding SSColor.
static SSColor	from(StringScanner ss) Parse the String following the selected portion of a StringScanner for a color specification.
static SSColor	from(java.lang.String hashRGB, java.lang.String stem, java.lang.String vrnt) Create or find a color with the given rgb, name, and variant.
java.lang.String	getDisplayName()
int[]	getHsl()
java.lang.String	getKey()
java.lang.String	getLink()
java.lang.String	getName()
java.lang.String	getSource()
static java.util.ArrayList<SSColor>	getVariants(java.lang.String keyName)
static double	grayScale(int r, int g, int b) Compute the gray scale value for this color.
static int[]	hslToRgb(double h, double s, double l) Converts an HSL color value to RGB.
protected static double	hueToRgb(double p, double q, double t) Helper method that converts hue to rgb.
static java.lang.String	intToHex(int klr) Convert an int to hex.
boolean	isRegistered()
static java.lang.String	keyName(java.lang.String name) Produce a key name from a full color name.
static int	mulround(double v, int max) Convert a value in [0,1] to [0,max] by multiplying and rounding.
static int	parseInt(java.lang.String h) Compute the rgb integer for a hex color.
void	register() Register a color for later lookup.
static double[]	rgbToHSL(int pR, int pG, int pB) Converts an RGB color value to HSL.
void	setLink(java.lang.String lnk)
void	setSource(java.lang.String src) Set the parenthesized source segment.
java.lang.String	toAHex() Produce a string of 8 hex digits for this color.
int	toAValue()
java.lang.String	toCSS() Return a css string for this color.
java.lang.String	toHex() Produce the body of a hex string for this color.
java.lang.String	toHSL()
int	toInt() Produce the body of a hex string for this color.
java.lang.String	toString()
void	unregister() Remove registration of a color.

Methods inherited from class java.awt.Color

createContext, decode, equals, getAlpha, getBlue, getColor, getColor, getColor, getColorComponents, getColorComponents, getColorSpace, getComponents, getComponents, getGreen, getHSBColor, getRed, getRGB, getRGBColorComponents, getRGBComponents, getTransparency, hashCode, HSBtoRGB, RGBtoHSB

Methods inherited from class java.lang.Object

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

Field Detail

DEFAULT_COLOR

public static final SSColor DEFAULT_COLOR

registered

protected static java.util.HashMap<java.lang.Integer,java.util.ArrayList<SSColor>> registered

Map from color value to an ArrayList of SSColors having that color. Named colors precede unnamed.

stemMap

protected static final java.util.HashMap<java.lang.String,java.util.ArrayList<SSColor>> stemMap

Map from name stem to list of colors with that stem. Example: The stem name "Orange" returns a list of 7 variants, called Orange0, Orange1, ... Orange 6.

nNamedColors

protected static int nNamedColors

how many colors come from colorlist.csv + DEFAULT_COLOR

stemName

protected java.lang.String stemName

variant

protected int variant

source

protected java.lang.String source

link

public java.lang.String link

key

protected java.lang.String key

hsl

protected int[] hsl

Constructor Detail

SSColor

protected SSColor(int i,
                  boolean hasAlpha)

Construct an SSColor for a given integer, possibly including alpha.

Parameters:

i - The color. Eight bits per value: alpha, red, green, blue.

hasAlpha - If true, the integer has alpha in its leading eight bits. Alpha ranges from 0 to 255; that is, from transparent to opaque.

Method Detail

getDisplayName

public java.lang.String getDisplayName()

Returns:

the display name. This comprises stemName, optional dash-digit variant indicator, and optional parenthesized segment.

getName

public java.lang.String getName()

Returns:

the name. May be null, not "".

getKey

public java.lang.String getKey()

Returns:

the lookup key (name reduced to lower case letters).

getSource

public java.lang.String getSource()

Returns:

the parenthesized source segment. may be null

setSource

public void setSource(java.lang.String src)

Set the parenthesized source segment.

Parameters:

src - the new parentheses segment String. May be null.

getLink

public java.lang.String getLink()

Returns:

the link. May be null.

setLink

public void setLink(java.lang.String lnk)

Parameters:

lnk - the link to set. May be null to remove link.

brighter

public SSColor brighter()

Overrides:

brighter in class java.awt.Color

darker

public SSColor darker()

Overrides:

darker in class java.awt.Color

keyName

public static java.lang.String keyName(java.lang.String name)

Produce a key name from a full color name. A stemName may have capital letters, spaces, accented characters, and a dash-digits variant, parenthesized discriminator, and more. This method expands entities, strips accents, lowers case, and retains only letters a-z.

Parameters:

name - A full color name.

Returns:

The color name without the parenthesized segment and reduced to lower case letters. (thus no variant indicator)

getHsl

public int[] getHsl()

Returns:

the hsl as three ints: [0,359], [0,100], [0,100]

getVariants

public static java.util.ArrayList<SSColor> getVariants(java.lang.String keyName)

Parameters:

keyName - the stemName of the requested SSColors

Returns:

the variants; a list of all colors having the same keyName. (The keyName ignores the variant indicator and parenthesized segments.) The list is ordered by variant value, with un-varianted colors having variant -1. Incoming colors have been added after existing colors with same variant. For a plain color name, it may be reasonable to report the color at the head of the list. Modifying the list is a nono.

register

public void register()

Register a color for later lookup.

isRegistered

public boolean isRegistered()

Returns:

True iff this color is registered.

unregister

public void unregister()

Remove registration of a color.

colorRegistrees

public static java.util.ArrayList<SSColor> colorRegistrees(int avalue)

Parameters:

avalue - an integer argb color value. That is, the value from getAValue.

Returns:

an ArrayList of all SSColors registered for the given color value. May be null. Modifying the list itself is a nono.

from

public static SSColor from(int value,
                           boolean hasAlpha)

Convert a color value with alpha to an SSColor with the same value.

Parameters:

value - An int with rgb in lower 24 bits and alpha in the top eight bits.

hasAlpha - indicates whether the alpha value is present; if not, it is set to FF, fully opaque.

Returns:

an appropriate SSColor. Maybe an existing registered SSColor.

See Also:

from(StringScanner)

from

public static SSColor from(int value)

Convert a Color to an SSColor with the same value.

Parameters:

value - An int of rgb in lower 24 bits as a source for the value of the returned SSColor.

Returns:

an appropriate SSColor.

See Also:

from(StringScanner)

from

public static SSColor from(int r,
                           int g,
                           int b)

Combine three int values into an rgb.

Parameters:

r - red [0,255]

g - green [0,255]

b - blue [0,255]

Returns:

an SSColor for the combined value.

from

public static SSColor from(java.awt.Color klr)

Convert a color value to an SSColor with the same value.

Parameters:

klr - A Color object as a source for the value of the returned SSColor.

Returns:

an appropriate SSColor.

See Also:

from(StringScanner)

from

public static SSColor from(java.lang.String klrspec)

Parse a string as a color spec and return a corresponding SSColor.

Parameters:

klrspec - A String expected to describe a color according to one of the forms accepted by from(StringScanner).

Returns:

an appropriate SSColor.

See Also:

from(StringScanner)

from

public static SSColor from(java.lang.String hashRGB,
                           java.lang.String stem,
                           java.lang.String vrnt)

Create or find a color with the given rgb, name, and variant. This interface is used to read to named colors list.

Parameters:

hashRGB - The color value as a #rrggbb string.

stem - Name for the color. May be null. Examples: "Blue", "Forest green"

vrnt - A small integer to distinguish colors with same stem names. May be empty to indicate no variant. May be "*" to assign a new largest variant number.

Returns:

Usually a new SSColor; for an error returns SSColor.DEFAULT_COLOR

from

public static SSColor from(StringScanner ss)

Parse the String following the selected portion of a StringScanner for a color specification. The StringScanner is adjusted to span the spec. All color specifications are case-independent.

 Parameter values can be specified as
            integer [0,255]
            double  [0.0,1.0]
            precent  [0%,100%]   or   [0.0%,100.0%]
        in all cases, if the opacity (or a) is omitted, it defaults to 100% opaque.
 A string color specification ("color spec") is one of:
  -- a color name, see below   (value may have alpha in high order bits)
  -- any form of number. This is interpreted as though
            it were the corresponding six digit hex value. No alpha value.
            A double value is rounded to the nearest integer.  Example: 29, a pale blue.
  -- #hex:  #rgb #rrggbb   (no alpha portion is accepted)
  -- rgb(r,g,b) or rgb(r,g,b,a) 
  -- hsb(h,s,b) or hsb(h,s,b,a) 
  -- rgba(r,g,b,a) 
  -- hsba(h,s,b,a) 
          parameters are parsed by procParam; see that method for the forms 
          r is red, g is green, b is blue, a is opacity (255==opaque)
        
 Any of the above may be optionally followed
            by an asterisk and an opacity procParam. Example: blue*25%
            This overrides an alpha in the value.
 

A color name starts with a letter and continues with letters, digits, and spaces. It may be followed by a dash and a variant number. (At present, the only name with digits in it is "Mordant Red 19".) There are several names with accented letters; these are ignored when looking for the color in the list of named colors.

 Whitespace is allowed between tokens, but
        - not within a color number
        - not between # and the following hex digits
        - not between a number and a following '%'

The parser for each sort of value always produces an argb value. Where no alpha is allowed, the value used is 0xFF (fully opaque, not transparent).

Parameters:

ss - The StringScanner to parse.

Returns:

as appropriate SSColor. If the color had been registered, that prior SSColor is returned. If the color spec does not validly produce a color, the value SSColor.DEFAULT_COLOR is returned.

continuations

public static java.util.ArrayList<java.lang.String> continuations(java.lang.String input)

Parameters:

input - A prefix of a name. The value is keyword-converted so accents and upper-case are converted to lower case ASCII and digits are ignored.

Returns:

A list of color names that begin with a given string.

mulround

public static int mulround(double v,
                           int max)

Convert a value in [0,1] to [0,max] by multiplying and rounding.

Parameters:

v - A value in [0,1]

max - The maximum value to produce.

Returns:

the corresponding value in [0,255]

hslToRgb

public static int[] hslToRgb(double h,
                             double s,
                             double l)

Converts an HSL color value to RGB. Conversion formula adapted from http://en.wikipedia.org/wiki/HSL_color_space. Assumes h, s, and l are contained in the set [0, 1] and returns r, g, and b in the set [0, 255].

Parameters:

h - The hue

s - The saturation

l - The lightness

Returns:

int array, the RGB representation

hueToRgb

protected static double hueToRgb(double p,
                                 double q,
                                 double t)

Helper method that converts hue to rgb.

Parameters:

p - basis of return value

q - correction to return value

t - hue

Returns:

an rgb value

rgbToHSL

public static double[] rgbToHSL(int pR,
                                int pG,
                                int pB)

Converts an RGB color value to HSL. Conversion formula adapted from http://en.wikipedia.org/wiki/HSL_color_space. Assumes pR, pG, and bpBare contained in the set [0, 255] and returns h, s, and l in the set [0, 1].

Parameters:

pR - The red color value

pG - The green color value

pB - The blue color value

Returns:

double array, the HSL representation

parseInt

public static int parseInt(java.lang.String h)

Compute the rgb integer for a hex color. The color may be decimal, #-three-digits, #-six-digits, six-digits, 0x-six-digits, 0-octal-digits The behavior of Color.decode is not well described. Here's the experiment // System.out.println("from 0xrrggbb: "+((Color.decode("0xEEFFFF").getRGB())&0xFFFFFF)); // System.out.println("from #rrggbb: "+((Color.decode("#EEFFFF").getRGB())&0xFFFFFF)); // System.out.println("from #rgb: "+((Color.decode("#EFF").getRGB())&0xFFFFFF)); // as if #FFF101 !!! // System.out.println("from 0ccccccc: "+((Color.decode("073577777").getRGB())&0xFFFFFF)); // System.out.println("from dec: "+((Color.decode("15663103").getRGB())&0xFFFFFF)); // String h = "#EFF"; // char r = h.charAt(1), g = h.charAt(2), b = h.charAt(3); // h = "#"+r+r+g+g+b+b; // System.out.println("#rgb-<#rrggbb: " + h); // //// from 0xrrggbb: 15663103 //// from #rrggbb: 15663103 //// from #rgb: 3839 //// from 0ccccccc: 15663103 //// from dec: 15663103 //// #rgb-<#rrggbb: #EEFFFF

Parameters:

h - The hex string

Returns:

Corresponding integer value

intToHex

public static java.lang.String intToHex(int klr)

Convert an int to hex. Ignores opacity.

Parameters:

klr - the color value

Returns:

a hex string (with NO leading '#') for the klr value

grayScale

public static double grayScale(int r,
                               int g,
                               int b)

Compute the gray scale value for this color. https://en.wikipedia.org/wiki/Grayscale offers various formulas depending on gamma. (Vector times r,g,b) y = .21 .72 .07 y = .30 .59 .11 y = .26 .68 .06 Since we don't know gamma, I've picked a sort of consensus. y = .25 .67 .08

Parameters:

r - red component [0-255]

g - green component [0-255]

b - blue component [0-255]

Returns:

The gray scale value.

toHex

public java.lang.String toHex()

Produce the body of a hex string for this color. There is no leading # or 0x. Alpha is omitted.

Returns:

6 hex digits: rr gg bb

toInt

public int toInt()

Produce the body of a hex string for this color. There is no leading # or 0x. Alpha is omited.

Returns:

6 hex digits: rr gg bb

toAValue

public int toAValue()

Returns:

the color value, including the alpha channel in the upper eight bits.

toAHex

public java.lang.String toAHex()

Produce a string of 8 hex digits for this color. The top two digits are the alpha value. There is no leading # or 0x.

Returns:

8 hex digits: aa rr gg bb

toCSS

public java.lang.String toCSS()

Return a css string for this color. The string will be one of the 17 CSS color names or a '#' followed by 6 hex digits. The upper case digits are used: A, B, C, D, E, F

Returns:

A string for this color in CSS format.

toHSL

public java.lang.String toHSL()

Returns:

An hsl(...) String representing this color. Ideally

             newColor = SSColor.from(origColor.toHSL());
             new2 = SSColor.from(newColor.toHSL();

results in newColor.equals(origColor) but more often the value is slightly off. One might hope that newColor would now be able to survive the transform, but half the time new2.equals(newColor) is also false. All these colors are, however, visually identical.

toString

public java.lang.String toString()

Overrides:

toString in class java.awt.Color

Returns:

either color name or 0Xrrggbb hex string.