https://github.com/stevinz/iris
Color library with support for RGB, RYB, HSL color models and RYB hue shifting.
https://github.com/stevinz/iris
color-conversion color-scheme color-wheel colors hsl hue-shift javascript-library rgb rgb-to-hex ryb
Last synced: about 2 months ago
JSON representation
Color library with support for RGB, RYB, HSL color models and RYB hue shifting.
- Host: GitHub
- URL: https://github.com/stevinz/iris
- Owner: stevinz
- License: mit
- Created: 2022-01-26T02:29:56.000Z (over 3 years ago)
- Default Branch: main
- Last Pushed: 2024-05-09T23:24:25.000Z (about 1 year ago)
- Last Synced: 2025-03-27T22:07:23.420Z (2 months ago)
- Topics: color-conversion, color-scheme, color-wheel, colors, hsl, hue-shift, javascript-library, rgb, rgb-to-hex, ryb
- Language: JavaScript
- Homepage: https://stevinz.github.io/iris/
- Size: 86.9 KB
- Stars: 8
- Watchers: 1
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# 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](https://stevinz.github.io/iris/).
- Works alongside other popular frameworks, such as [Three.js](https://threejs.org/). See [example](#Three-Example) below of passing data between `Iris` and `THREE.Color`.
## Installation
- Option 1: Copy file `Iris.js` to project, import from file...
```javascript
import { Iris } from 'Iris.js';
```
- Option 2: Install from [npm](https://www.npmjs.com/package/@scidian/iris), import from '@scidian/iris'...
```
npm install @scidian/iris
```
```javascript
import { Iris } from '@scidian/iris';
```
- Option 3: Import directly from CDN...
```javascript
import { Iris } from 'https://unpkg.com/@scidian/iris/build/iris.module.js';
```
#### Iris can be initialized in the following ways
```javascript
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
```
#### Color alterations support chaining
```javascript
const color = new Iris(0xff0000);
console.log(color.rybRotateHue(270).darken(0.5).hexString().toUpperCase());
```
* _output_
> #2E007F
#### Hue Shifting
```javascript
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);
```
#### Example usage alongside [Three.js](https://threejs.org/)
```javascript
// 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);
```
# 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.
# 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.
# 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](http://www.w3.org/TR/css3-color/#svg-color) 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](http://www.w3.org/TR/css3-color/#svg-color) ('darkred') strings.
# 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.
# 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.
# 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.
# 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 lightness value is 0.6 (between 0.0 and 1.0), an **amount** of 0.5 will increase the lightness value to 0.6 + ((1.0 - 0.6) * 0.5) = 0.8, an **amount** value of 1.0 will always bring lightness value up to 1.0 (100%).
### **.[darken]()** ( amount : Float ) : this
Decreases the lightness of this Iris Object by **amount**. A value of 0.5 (default) will decrease lightness by 50%, a value of 2.0 will double lightness.
### **.[grayscale]()** ( percent : Float, type : String ) : this
Changes color into grayscale by **percent** ranging from 0.0 to 1.0. This can be done by type 'average' which takes an average of the red, green, blue values. Or by default type of 'luminosity' which scales red, green, blue values according to how human eyes see color (see [details at GIMP](https://docs.gimp.org/2.6/en/gimp-tool-desaturate.html)).
### **.[hslOffset]()** ( h : Integer, s : Float, l : Float ) : this
Change the HSL values of this Iris object by **h** (-360 to 360), **s** (-1.0 to 1.0), and **l** (-1.0 to 1.0).
### **.[mix]()** ( mixColor : Iris, percent : Float ) : this
Mixes in another Iris Object's color value to this Iris Object by **percent** (default of 0.5, i.e. 50%).
### **.[multiply]()** ( color : Iris ) : this
Multiplies another Iris Object's RGB values to this Iris Object's RGB values.
### **.[multiplyScalar]()** ( scalar : Float ) : this
Multiplies this Iris Object's RGB values by **scalar**. There is no range for **scalar**, however, color values will be clamped between 0.0 and 1.0 after multiplication.
### **.[rgbComplementary]()** ( ) : this
Adjusts this color to be 180 degress (opposite) of the current color on the RGB color wheel.
### **.[rgbRotateHue]()** ( degrees : Integer ) : this
Adjusts this color to be **degress** of the current color on the RGB color wheel, range from -360 to 360.
### **.[rybAdjust]()** ( ) : this
Adjusts the RGB values to fit in the RYB spectrum as best as possible.
### **.[rybComplementary]()** ( ) : this
Adjusts this color to be 180 degress (opposite) of the current color on the RYB color wheel.
### **.[rybRotateHue]()** ( degrees : Integer ) : this
Adjusts this color to be **degress** of the current color on the RYB color wheel, range from -360 to 360.
### **.[subtract]()** ( color : Iris ) : this
Subtracts the red, green, blue values from **color** to this Iris Object's values.
# Comparison
### **.[equals]()** ( color : Iris ) : Boolean
Returns true if the RGB values of **color** are the same as those of this Object.
### **.[isDark]()** ( color : Iris ) : Boolean
Returns true if this Iris Object's color value would be considered "dark", helpful for determining whether of not to use black or white text with this color as a background.
### **.[isLight]()** ( color : Iris ) : Boolean
Returns true if this Iris Object's color value would be considered "light", helpful for determining whether of not to use black or white text with this color as a background.