matisse

matisse is a JavaScript library for performing colour manipulations with support for CSS color strings. Mutable colour entities allow for implicit conversion between RGB, HSV, HSL, CMYK, and HWB colour spaces. Mixing, toning, tinting, shading, and blending operations are also supported including a variety of different blend modes. matisse contains functionality for performing colour measurements as well as functionality for validating and correcting colours to comply with the WCAG standards for contrast. In addition, this library allows for palette generation for different colour harmonies according to colour theory principles.

This project was originally developed as a team project for McMaster University's SFWRENG 3XA3: Software Project Management course in collaboration with Isra Zahid and Samia Anwar.

Check out matisse-palette which extends matisse to allow for colour palettes to be generated from images using K-means clustering.

Installation

npm install matisse

Usage

import Colour, * as matisse from "matisse";

Constructors

Traditional constructors are available for CSS colour strings and HEX codes as well as static factory contructors for RGB, HSV, HSL, CMYK, and HWB colour models. When the Colour object is initialized using a constructor, all other colour attributes from the other colour spaces are implicitly calculated and stored.

const colour = new Colour("rgba(32, 122, 166, 0.5)");
const colour = new Colour("#207AA680");
const colour = Colour.RGB(32, 122, 166, 0.5);
const colour = Colour.HSV(200, 0.81, 0.65, 0.5);
const colour = Colour.HSL(200, 0.69, 0.39, 0.5);
const colour = Colour.CMYK(0.81, 0.27, 0, 0.35, 0.5);
const colour = Colour.HWB(200, 0.12, 0.35, 0.5);

Getters & Setters

Getters and setters for the Colour class are defined using ES6 get and set properties. The following properties of Colour instances can be accessed and mutated: red, green, blue, hue, saturationv, value, saturationl, light, cyan, magenta, yellow, white, black, alpha. Error handling and useful range constants are also built in to support usability.

const colour = Colour.RGB(18, 64, 188);
console.log(colour.hue);
colour.hue = 69;
colour.hue = Colour.hueMax + 1; // throws an error!

Measurements & Manipulations

matisse contains several static methods for colour measurements, calculations, and operations.

const x = new Colour("#59396E");
const y = new Colour("#A5B828");

const x_inverse = matisse.negate(x); // #A6C691
const y_complement = matisse.rotate(y, 180); // #3C28B8
const x_grayscale = matisse.grayscale(x); // #484848
const y_colourfulness = matisse.colourfulness(y); // 40.75
const x_luminosity = matisse.luminosity(x); // 0.06
const y_temp = matisse.temperature(y); // 2812.14
const contrast = matisse.contrast(x, y); // 4.24

Mixing & Blending

Mixing and blending operations with different blend modes can be perfomed with a given base colour and a blend colour.

const baseColour = Colour.CMYK(0.00, 0.95, 0.86, 0.38); // #9E0816
const blendColour = Colour.HWB(285, 0.32, 0.65); // #58525A

matisse.mix(baseColour, blendColour, 0.69); // #6D3A44
matisse.normal(baseColour, blendColour); // #575159
matisse.multiply(baseColour, blendColour); // #360308
matisse.screen(baseColour, blendColour); // #BF5667
matisse.overlay(baseColour, blendColour); // #7F050F
matisse.darken(baseColour, blendColour); // #570816
matisse.lighten(baseColour, blendColour); // #9E5159
matisse.colourDodge(baseColour, blendColour); // #F00C22
matisse.colourBurn(baseColour, blendColour); // #000000
matisse.hardLight(baseColour, blendColour); // #6C050F
matisse.softLight(baseColour, blendColour); // #8B0510
matisse.difference(baseColour, blendColour); // #474943
matisse.exclusion(baseColour, blendColour); // #895460

Similarly, tones, tints, and shades can be produced from a given base colour.

const baseColour = Colour.HSV(277, 1.00, 0.50); // #4F0080

matisse.tone(baseColour, 0.50); // #684080
matisse.tint(baseColour, 0.50); // #A780C0
matisse.shade(baseColour, 0.50); // #280040

Colour Palettes

Colour palettes can be generated according to various colour harmonies.

const colour = Colour.RGB(235, 64, 52); // #EB4034

matisse.analogous(colour); // [#EB33A1, #EB4034, #EBBA33]
matisse.complementary(colour); // [#EB4034, #33DFEB]
matisse.splitComplementary(colour); // [#EB4034, #33EBBA, #33A1EB]
matisse.triadic(colour); // [#EB4034, #33EB3F, ##3F33EB]
matisse.tetradic(colour); // [#EB4034, #33EB3F, #33DFEB, #3F33EB]
matisse.square(colour); // [#EB4034, #83EB33, #33DFEB, #9B33EB]

Monochromatic colour palettes can also be generated for a given length.

const baseColour = Colour.HSV(277, 1.00, 0.50); // #4F0080

matisse.tones(baseColour, 5); // [#4F0080, #5B2080, #684080, #746080, #808080]
matisse.tints(baseColour, 5); // [#4F0080, #7B40A0, #A780C0, #D3BFDF, #FFFFFF]
matisse.shades(baseColour, 5); // [#4F0080, #3B0060, #280040, #140020, #000000]

You can also generate a palette of random colours.

matisse.randoms(10);

To generate colour palettes from an image, use the matisse-palette library. This extension uses K-means clustering to intelligently extract a colour palette given the image's pixel data.

Accessibility

matisse has the ability to check if a pair of colours have sufficient contrast according to the WCAG standards. It can also be configured to compare enhanced and large text colours.

const textColour = new Colour("#520404");
const backgroundColour = new Colour("#D010EE");

matisse.validateContrast(textColour, backgroundColour); // false
matisse.validateContrast(textColour, backgroundColour, true); // true
matisse.validateContrast(textColour, backgroundColour, false, true); // false
matisse.validateContrast(textColour, backgroundColour, true, true); // false

A colour combination with insufficient contrast can be fixed as well. This works by whitening the lighter colour and blackening the darker colour!

const textColour = new Colour("#FFDD00"); // #FFDD00
const backgroundColour = new Colour("#1F8BFF"); // #1F8BFF

matisse.fixContrast(textColour, backgroundColour); // [#FFE644, #1866BC]

For detailed documentation, refer to the project's Module Interface Specification (MIS).

Sources

matisse was inspired by and makes use of the following:

• Qix-/color
• Qix-/color-string
• coolors