Iris

Small, fast, dependency free JavaScript color library with support for the RGB, RYB, and HSL color models and easy interaction with HTML, CSS, and third party frameworks.

Features

• Internal calls don't allocate memory, reducing garbage collector activity.
• Color conversion between color models.
• Support for color mixing and color alteration (mix, add, subtract, brighten, darken, grayscale, etc.)
• Hue shifting around the more traditional artistic RYB (red, yellow, blue) color wheel, creating much more natural complementary colors and intuitive palettes, see online example.
• Works alongside other popular frameworks, such as Three.js. See example below of passing data between Iris and THREE.Color.

<br>

Installation

• Option 1: Copy file Iris.js to project, import from file...

import { Iris } from 'Iris.js';

• Option 2: Install from npm, import from '@scidian/iris'...

npm install @scidian/iris

import { Iris } from '@scidian/iris';

• Option 3: Import directly from CDN...

import { Iris } from 'https://unpkg.com/@scidian/iris/build/iris.module.js';

<br>

Iris can be initialized in the following ways

new Iris();                             // Defaults to white, 0xffffff
new Iris(0xff0000);                     // Hexadecimal (0xff0000, i.e. 16711680)

new Iris(1.0, 0.0, 0.0);                // RGB Values (0.0 to 1.0)

new Iris(255,   0,   0, 'rgb');         // RGB Values (0 to 255)
new Iris(255,   0,   0, 'ryb');         // RYB Values (0 to 255)
new Iris(360, 1.0, 0.5, 'hsl');         // HSL Values (H: 0 to 360, SL: 0.0 to 1.0)

new Iris({ r: 1.0, g: 0.0, b: 0.0 });   // Object, RGB Properties (0.0 to 1.0)
new Iris({ r: 1.0, y: 0.0, b: 0.0 });   // Object, RYB Properties (0.0 to 1.0)
new Iris({ h: 1.0, s: 1.0, l: 0.5 });   // Object, HSL Properties (0.0 to 1.0)

new Iris([ 1.0, 0.0, 0.0 ], offset);    // RGB Array (0.0 to 1.0), optional offset

new Iris('#ff0000');                    // Hex String (also 3 digits: '#f00')
new Iris('rgb(255, 0, 0)');             // CSS Color String
new Iris('red');                        // X11 Color Name

new Iris(myIrisColor);                  // Copy from Iris Color Object
new Iris(myThreeColor);                 // Copy from Three.js Color Object

<br>

Color alterations support chaining

const color = new Iris(0xff0000);

console.log(color.rybRotateHue(270).darken(0.5).hexString().toUpperCase());

• output

  #2E007F

<br>

Hue Shifting

const color = new Iris(0xff0000);

// To find the RYB color wheel complement (opposite) color
const complement = new Iris.set(color).rybComplementary();

// To adjust hue a specific number of degrees (0 to 360) around the RYB color wheel
const tetrad1 = new Iris.set(color).rybRotateHue(90);
const tetrad2 = new Iris.set(color).rybRotateHue(270);

<br>

Example usage alongside Three.js <a name="Three-Example"></a>

// Some possible ways to initialize Iris using THREE.Color
const eyeColor = new Iris(threeColor);
const eyeColor = new Iris(threeColor.getHex());
const eyeColor = new Iris(threeColor.toArray());

// Some possible ways to initialize THREE.Color using Iris
const threeColor = new THREE.Color(eyeColor);
const threeColor = new THREE.Color(eyeColor.hex());
const threeColor = new THREE.Color(eyeColor.hexString());

// Some possible ways to copy the values of the THREE.Color back to Iris
eyeColor.copy(threeColor);
eyeColor.set(threeColor.getHex());
eyeColor.setRGBF(threeColor.r, threeColor.g, threeColor.b);

// Some possible ways to copy the values of the Iris back to THREE.Color
threeColor.copy(eyeColor);
threeColor.setHex(eyeColor.hex());
threeColor.setRGB(eyeColor.r, eyeColor.g, eyeColor.b);

<br>

Properties

.r : Float

Red channel value between 0.0 and 1.0, default is 1.

.g : Float

Green channel value between 0.0 and 1.0, default is 1.

.b : Float

Blue channel value between 0.0 and 1.0, default is 1.

<br>

Copy / Clone

.copy ( colorObject : Iris or THREE.Color ) ( ) : this

Copies the r, g, b properties from colorObject. This Object can be any type as long as it has r, g, b properties containing numeric values ranging from 0.0 to 1.0.

.clone ( ) : Iris

Returns a new Iris Object with the same color value as this Iris Object.

<br>

Assignment

.set ( r: Number or Object or Array or String, g : Number, b : Number, type : String ) : this

All arguments are optional. Sets this color based on a wide range of possible inputs, all options are the same as with the constructor.

.setColorName ( style : String ) : this

Sets this color based on a X11 color name.

.setHex ( hexColor : Integer ) : this

Sets this color based on a hexidecimal / decimal value (i.e. 0xff0000 or 16711680).

.setHSL ( h : Integer, s: Float, l: Float ) : this

Sets this color based on hue (0 to 360), saturation (0.0 to 1.0), and lightness (0.0 to 1.0) values.

.setRandom ( ) : this

Sets this color to a random color.

.setRGB ( r : Number, g: Number, b: Number ) : this

Sets this color based on a red, green, and blue values ranging from 0 to 255.

.setRGBF ( r : Float, g: Float, b: Float ) : this

Sets this color based on a red, green, and blue values ranging from 0.0 to 1.0.

.setRYB ( r : Integer, g: Integer, b: : Integer ) : this

Sets this color based on a red, yellow, and blue values ranging from 0 to 255.

.setScalar ( scalar: Integer ) : this

Sets this colors red, green, and blue values all equal to a singular value ranging from 0 to 255.

.setScalarF ( scalar : Float ) : this

Sets this colors red, green, and blue values all equal to a singular value ranging from 0.0 to 1.0.

.setStyle ( style : String ) : this

Sets this color based on CSS ('rgb(255,0,0)' / 'hsl(360,50%,50%)'), Hex ('#FF0000'), or X11 ('darkred') strings.

<br>

Output

.cssString ( alpha : Integer ) : String

Returns string for use with CSS, for example "rgb(255, 0, 0)". Optionally include an alpha value from 0 to 255 to be included with the string, for example "rgba(255, 0, 0, 255)".

.hex ( ) : Integer

Returns value as hexidecimal.

.hexString ( hexColor : Integer ) : String

Returns value as hex string for use in CSS, HTML, etc. Example: "#ff0000". If optional hexColor is supplied, the returned string will be for the supplied color, not the underlying value of the current Iris Object.

.rgbString ( alpha : Integer ) : String

Returns value as inner section of cssString(). For example "255, 0, 0". This allows you to write to CSS variables for use with custom alpha channels in your CSS. Optional alpha value.

.toJSON ( ) : Integer

Returns value as hexidecimal, JSON friendly data.

<br>

Color Data

.getHSL ( target ) : Object

Provide an optional target to copy hue, saturation, lightness values into, they will be in the range 0.0 to 1.0. If no target is provided a new Object with h, s, l properties is returned.

.getRGB ( target ) : Object

Provide an optional target to copy red, green, blue values into, they will be in the range 0.0 to 1.0. If no target is provided a new Object with r, g, b properties is returned.

.getRYB ( target ) : Object

Provide an optional target to copy red, yellow, blue values into, they will be in the range 0.0 to 1.0. If no target is provided a new Object with r, y, b properties is returned.

.toArray ( array : Array, offset : Integer ) : Array

Provide an optional array to copy red, green, blue values into, they will be in the range 0.0 to 1.0. Optionally provide an offset to specify where in the array to write the data. If no array is provided a new Array will be returned.

<br>

Components

.red ( ) : Integer

Returns red value of current Iris object in range 0 to 255.

.green ( ) : Integer

Returns green value of current Iris object in range 0 to 255.

.blue ( ) : Integer

Returns blue value of current Iris object in range 0 to 255.

.redF ( ) : Float

Returns red value of current Iris object in range 0.0 to 1.0.

.greenF ( ) : Float

Returns green value of current Iris object in range 0.0 to 1.0.

.blueF ( ) : Float

Returns blue value of current Iris object in range 0.0 to 1.0.

.hue ( ) : Integer

Returns hue value of current Iris object in range 0 to 360.

.saturation ( ) : Float

Returns saturation value of current Iris object in range 0.0 to 1.0.

.lightness ( ) : Float

Returns lightness value of current Iris object in range 0.0 to 1.0.

.hueF ( ) : Float

Returns hue value of current Iris object in range 0.0 to 1.0.

.hueRYB ( ) : Integer

Returns the RYB adjusted hue value of current Iris object in range 0 to 360.

<br>

Color Adjustment

.add ( color : Iris ) : this

Adds the red, green, blue values from color to this Iris Object's values.

.addScalar ( scalar : Integer ) : this

Adds the value scalar to the red, green, blue of this Iris Object, scalar should be in range -255 to 255.

.addScalarF ( scalar : Float ) : this

Adds the value scalar to the red, green, blue of this Iris Object, scalar should be in range -1.0 to 1.0.

.brighten ( amount : Float ) : this

Increases the lightness of this Iris Object by amount as a percentage of the remainder of 100% lightness less the current lightness. For example, if the current hsl ligh