Home

Awesome

Pheasant.js

Build Status

Pheasant.js makes colors manipulations easy.

Install

Server-side (Node)

npm install pheasant

Then use:

var Pheasant = require( 'pheasant' );

Client-side

Include the build/pheasant.min.js file in your page. There’s no dependency, only 15ko of pure JavaScript (4.5ko gzip’d). Pheasant can also be used as an AMD module.

Usage

Pheasant exposes one object, Pheasant. It has the following methods:

.parse

This function returns a Pheasant.Color object of the parsed string, or null if it can’t be parsed (see the support table below for the supported formats).

Pheasant.parse( 'red' ); // red
Pheasant.parse( '#0F0' ); // green
Pheasant.parse( '#0000FF' ); // blue
Pheasant.parse( 'rgb(128, 128, 128)' ); // gray
Pheasant.parse( 'rgb(10%, 10%, 10%, 0.3)' ); // transparent gray
Pheasant.parse( 'rgba(255, 192, 203, 0.5)' ); // transparent pink
Pheasant.parse( 'hsl(240, 100%, 50%)' ); // blue
Pheasant.parse( 'hsla(120, 100%, 25%, 1)' ); // green

.convert

This function takes two arguments, the first is the string to parse and the second is the identifier of the format to convert to.

Pheasant.parse( 'pink' ).toString( 'rgba' ); // 'rgba(255,192,203,1)'
Pheasant.convert( 'pink', 'rgba' ); // 'rgba(255,192,203,1)'

.guessFormat

This function takes one argument, a string, and return the first identifier of its format, if it’s a supported one. It returns null if it can’t guess the format.

Pheasant.guessFormat( '#ccc' ); // 'hex3'
Pheasant.guessFormat( '#cccbbb' ); // 'hex6'
Pheasant.guessFormat( '#cccb' ); // null

.range

This function takes an object as its argument, and return a range of colors. The object must have the following properties:

Additionally, the object can have the following optional properties:

This function returns an empty array if from and/or to are missing, and/or if the length is lesser or equal to zero, and/or if the type attribute is not valid, and/or the format attribute is not valid, and/or from (or to) is a string which cannot be parsed. Some values in the range may be null if you choose the colorName format, since some values don’t have a name (e.g. rgba(1, 1, 1)).

// [ '#fff', '#fff', '#fff' ]
Pheasant.range({ from: '#fff', to: '#fff', length: 3 });

// ["#abc", "#89a", "#568", "#345", "#123"]
Pheasant.range({ from: '#ABC', to: '#123', length: 5 });

// ["#40bf40", "#3ca13c", "#378337", "#336633", "#2e482e", "#2a2a2a"]
Pheasant.range({
    from: 'hsl(120, 50%, 50%)',
    to: 'rgb(42, 42, 42)',
    length: 6,
    format: 'hex6'
});

Color objects

You can create a Color object using the following constructor:

var color = new Pheasant.Color( red, green, blue, alpha );

alpha is optional (default to 1), and red, green and blue should be integers between 0 and 255.

Color objects has four attributes, .red, .green, .blue and .alpha. They also have two convenient methods: .getRGB() and .getRGBA(), which return an array of .red, .green and .blue properties, plus the .alpha one for .getRGBA().

Pheasant.parse( 'navy' ).blue; // 128

.toString

You can use the .toString() method to convert colors to the format you want. Without argument, it convert the color to the default format (#ABCDEF). You can specify the format you want as a string. See the format identifiers below.

Pheasant.parse( 'red' ).toString(); // '#f00'
Pheasant.parse( '#00F' ).toString( 'colorName' ); // 'blue'
var c = Pheasant.parse( 'rgb(245, 245, 220)' );
c.toString( 'colorName' ); // 'beige'
c.toString( 'hsl' ); // 'hsl(60,56%,91%)'

Since it may be painful to write Pheasant.parse( 'foo' ).toString( 'bar' ) for a one-time conversion, Pheasant has a method for that: .convert.

.getRGB

This method returns an array of red, green and blue values.

Pheasant.parse( 'red' ).getRGB(); // [ 255, 0, 0 ]

.getRGBA

This method returns an array of red, green, blue, and opacity values.

Pheasant.parse( 'red' ).getRGBA();                  // [ 255,   0,   0, 1   ]
Pheasant.parse( 'hsla(42,12%,99%,0.5)' ).getRGBA(); // [ 253, 253, 252, 0.5 ]

.getHSL

This method returns the equivalent HSL values of the color (hue, saturation, lightness).

Pheasant.parse( 'red' ).getHSL();  // [  0, 100, 50 ]
Pheasant.parse( '#ffe' ).getHSL(); // [ 60, 100, 97 ]

.getHSV

This method returns the equivalent HSV values of the color (hue, saturation, value). HSV is also called HSB (“value” being replaced by “brightness”), so an alias method called .getHSB is also available (this is exactly the same).

Pheasant.parse( 'green' ).getHSV(); // [ 120, 100, 50 ]

.negative

This method returns a new object representing the negative of the current color. It preserves the alpha channel.

var c1 = new Pheasant.color( 42, 42, 42 ),
    c2 = c1.negative();

c2.getRGB(); // [ 213, 213, 213 ]

Pheasant.parse( 'white' ).negative().toString( 'colorName' ); // 'black'

.brightness

This method returns the brightness index of the color. This is an integer between 0 (dark) and 255 (white). It can be used to mesure the contrast between two colors.

Pheasant.parse( '#fff' ).brightness(); // 255
Pheasant.parse( 'rgb(42, 10, 134)' ).brightness(); // 34

.isDarkerThan

This method tests if the color is darker than another color. You can pass it a Color object or a string.

Pheasant.parse( '#fff' ).isDarkerThan( '#eee' ); // false
Pheasant.parse( 'red' ).isDarkerThan( '#FAFAFA' ); // true

.isLighterThan

This method tests if the color is lighter than another color. You can pass it a Color object or a string.

Pheasant.parse( '#fff' ).isLighterThan( '#eee' ); // true
Pheasant.parse( 'red' ).isLighterThan( '#FAFAFA' ); // false

.eq

This method tests the equality between this color and another. You can pass it a Color object or a string.

Pheasant.parse( '#000' ).eq( 'rgba( 0, 0, 0)' ); // true

.brightnessContrast

This method returns the brightness contrast between the current color and another. It’s an integer between 0 and 255.

Pheasant.parse( 'blue' ).brightnessContrast( 'yellow' ) // true
Pheasant.parse( 'blue' ).brightnessContrast( 'darkblue' ); // false

.hueContrast

This method returns the hue contrast between the current color and another. It’s an integer between 0 and 765. For the best readability, the brightness contrast between the text color and the background color should be higher than 125, and the hue contrast higher than 500.

Color Formats

Built-in Support

All standard CSS/SVG colors formats are supported.

FormatParsingStringifyingIdentifiers
#ABC✔✔hex3, hexa3
#ABCDEF✔✔hex6, hexa4
color names✔✔colorName, colourName
hsl()✔✔hsl
hsla()✔✔hsla
rgb()*✔✔rgb
rgba()*✔✔rgba

Format identifiers are case-insensitive.

(*): The rgb() and rgba() formats also support percentages values, like rgb(20%, 10%, 45%) and rgba(35%, 0%, 100%, 0.2). If you want to force percentages in the output, append % to each identifier: rgb% and rgba%.

Setting the default output format

The default ouput format (for toString) is hex6. You can change it with Pheasant.setDefaultStringFormat():

Pheasant.parse( 'lightgreen' ).toString(); // '#90ee90'
Pheasant.setDefaultStringFormat( 'rgb' );
Pheasant.parse( 'lightgreen' ).toString(); // 'rgb(144,238,144)'

Adding a format

You can add a new format with Pheasant.addFormat(). This method takes one argument, an object with the following properties:

The object must provide the parse and/or stringify attributes, and must provide the name attribute.

When a string is passed to Pheasant.parse, it tries to parse it with every available format. If no format can parse it (i.e. they all return null), it returns null.

The Pheasant.addFormat() method return either:

This means that if you try to register a new format with the identifier hex3 (already taken), it won’t be registered and the call will return null. If you try with HEX3, that’s the same since format identifiers are case-insensitive. If your format has two names, hex3 and hex_3, it will only be bound to hex_3, since hex3 is not available.

If you want to clear all the available formats, use the Pheasant.formats object:

Pheasant.formats = {};

Example

Say you want to add a custom color format, which represent colors like that: custom:<blue>/<red>/<green>. It doesn’t support the alpha channel, and blue/red/green values are integer between 0 and 255. Here is how you can add this format:

Pheasant.addFormat((function() {

    // this regex match your format
    var custom_re = /custom:(\d{1,3})\/(\d{1,3})\/(\d{1,3})/;

    return {

        name: 'custom', // the name
        test: custom_re, // this is used to test if a string is valid in your format
        parse: function( s ) {
            // parse the string

            custom_re.lastIndex = 0;

            var brg = custom_re.exec( s );

            return { blue: +brg[1], red: +brg[2], green: +brg[3] };

        },

        stringify: function( c ) {
            // stringify a Color object

            return 'custom:' + c.blue + '/' + c.red + '/' + c.green;

        }

    };

})());

You can now try your format:

Pheasant.guessFormat( 'custom:42/18/255' ); // 'custom'
Pheasant.parse( 'custom:1/2/3' ).getRGB(); // [ 2, 3, 1 ]
Pheasant.convert( '#ABC', 'custom' ); // "custom:204/170/187"

Tests

Clone this repo, and then run make test-all:

git clone https://github.com/bfontaine/Pheasant.js.git
cd Pheasant
make test-all

You have to install the dependencies if they’re not already installed:

npm -g install mocha chai uglify-js mocha-phantomjs
# install Node-JSCoverage
git clone https://github.com/visionmedia/node-jscoverage.git
cd node-jscoverage
./configure && make && make install

You also need PhantomJS.

License

See the LICENSE file (MIT).

Changelog

Date format is DD/MM/YYYY.

v0.2.2 (08/10/2013)

v0.2.1 (10/09/2013)

v0.2.0 (12/03/2013)

v0.1.1 (10/03/2013)

v0.1.0 (09/03/2013)

First version.