onecolor

What is onecolor?

The onecolor npm package is a versatile color manipulation library that allows you to work with colors in various formats, convert between them, and perform operations like blending and adjusting color properties.

What are onecolor's main functionalities?

Color Creation

You can create a color object from a string representing a color in various formats (hex, RGB, HSL, etc.). The created color object can then be used for further manipulations.

const onecolor = require('onecolor');
const color = onecolor('#3498db');
console.log(color.css()); // Outputs: 'rgb(52, 152, 219)'

Color Conversion

The package allows you to convert colors between different formats such as HEX, RGB, and HSL.

const onecolor = require('onecolor');
const color = onecolor('#3498db');
console.log(color.hex()); // Outputs: '#3498db'
console.log(color.rgb()); // Outputs: 'rgb(52, 152, 219)'
console.log(color.hsl()); // Outputs: 'hsl(204, 0.68, 0.53)'

Color Manipulation

You can manipulate color properties like lightness, saturation, and hue. This example demonstrates adjusting the lightness of a color.

const onecolor = require('onecolor');
const color = onecolor('#3498db').lightness(0.5);
console.log(color.css()); // Outputs: 'rgb(26, 76, 109)'

Color Blending

The package supports blending two colors together. This example shows how to blend two colors with equal weight.

const onecolor = require('onecolor');
const color1 = onecolor('#3498db');
const color2 = onecolor('#e74c3c');
const blendedColor = color1.mix(color2, 0.5);
console.log(blendedColor.css()); // Outputs: 'rgb(153, 101, 123)'

Other packages similar to onecolor

chroma-js

Chroma.js is a powerful and flexible color manipulation library that supports a wide range of color spaces and provides advanced color manipulation features. Compared to onecolor, chroma-js offers more extensive functionality and better performance for complex color operations.

color

The color package is another popular library for color manipulation and conversion. It provides a simple API for working with colors and supports various color models. While it offers similar functionalities to onecolor, it is known for its ease of use and comprehensive documentation.

tinycolor2

TinyColor is a small, fast library for color manipulation and conversion. It is designed to be lightweight and easy to use, making it a good choice for projects where performance and simplicity are important. Compared to onecolor, TinyColor is more focused on providing a minimalistic API with essential color manipulation features.

README

one.color

JavaScript color calculation toolkit for node.js and the browser.

• RGB, HSV, and HSL colorspace support (a CMYK implementation also exists)
• Legal values for all channels are 0..1
• Instances are immutable -- a new object is created for each manipulation
• All internal calculations are done using floating point, so very little precision is lost due to rounding errors when converting between colorspaces
• Alpha channel support
• Extensible architecture -- implement your own colorspaces easily
• Chainable color manipulation
• Seamless conversion between colorspaces
• Outputs as hex, rgb(...), rgba(...) or hsv(...)

Usage

In the browser (change one-color.js to one-color-all.js to gain named color support):

<script src='one-color.js'></script>
<script>
    alert('Hello, ' + one.color('#650042').lightness(.3).green(.4).hex() + ' world!');
</script>

In node.js (after npm install onecolor):

var color = require('onecolor');
console.warn(color('rgba(100%, 0%, 0%, .5)').alpha(.4).cssa()); // 'rgba(255,0,0,0.4)'

one.color is the parser. All of the above return color instances in the relevant color space with the channel values (0..1) as instance variables:

var myColor = one.color('#a9d91d');
myColor instanceof one.color.RGB; // true
myColor.red() // 0.6627450980392157

You can also parse named CSS colors (works out of the box in node.js, but the requires the slightly bigger one-color-all.js build in the browser):

one.color('maroon').lightness(.3).hex() // '#990000'

To turn a color instance back into a string, use the hex(), css(), and cssa() methods:

one.color('rgb(124, 96, 200)').hex() // '#7c60c8'
one.color('#bb7b81').cssa() // 'rgba(187,123,129,1)'

Color instances have getters/setters for all channels in all supported colorspaces (red(), green(), blue(), hue(), saturation(), lightness(), value(), alpha()). Thus you don't need to think about which colorspace you're in. All the necessary conversions happen automatically:

one.color('#ff0000') // Red in RGB
    .green(1) // Set green to the max value, producing yellow (still RGB)
    .hue(.5, true) // Add 180 degrees to the hue, implicitly converting to HSV
    .hex() // Dump as RGB hex syntax: '#2222ff'

When called without any arguments, they return the current value of the channel (0..1):

one.color('#09ffdd').green() // 1
one.color('#09ffdd').saturation() // 0.9647058823529412

When called with a single numerical argument (0..1), a new color object is returned with that channel replaced:

var myColor = one.color('#00ddff');
myColor.red(.5).red() // .5

// ... but as the objects are immutable, the original object retains its value:
myColor.red() // 0

When called with a single numerical argument (0..1) and true as the second argument, a new value is returned with that channel adjusted:

one.color('#ff0000') // Red
    .red(-.1, true) // Adjust red channel by -0.1
    .hex() // '#e60000'

Alpha channel

All color instances have an alpha channel (0..1), defaulting to 1 (opaque). You can simply ignore it if you don't need it.

It's preserved when converting between colorspaces:

one.color('rgba(10, 20, 30, .8)')
    .green(.4)
    .saturation(.2)
    .alpha() // 0.8

API overview

Color parser function, the recommended way to create a color instance:

one.color('#a9d91d') // Regular hex syntax
one.color('#eee') // Short hex syntax
one.color('rgb(124, 96, 200)') // CSS rgb syntax
one.color('rgb(99%, 40%, 0%)') // CSS rgb syntax with percentages
one.color('rgba(124, 96, 200, .4)') // CSS rgba syntax
one.color('hsl(120, 75%, 75%)') // CSS hsl syntax
one.color('hsla(120, 75%, 75%, .1)') // CSS hsla syntax
one.color('hsv(220, 47%, 12%)') // CSS hsv syntax (non-standard)
one.color('hsva(120, 75%, 75%, 0)') // CSS hsva syntax (non-standard)
one.color([0, 4, 255, 120]) // CanvasPixelArray entry, RGBA
one.color(["RGB", .5, .1, .6, .9]) // The output format of color.toJSON()

The slightly bigger one-color-add.js build adds support for the standard suite of named CSS colors:

one.color('maroon')
one.color('darkolivegreen')

Existing one.color instances pass through unchanged, which is useful in APIs where you want to accept either a string or a color instance:

one.color(one.color('#fff')) // Same as one.color('#fff')

Serialization methods:

color.hex() // 6-digit hex string: '#bda65b'
color.css() // CSS rgb syntax: 'rgb(10,128,220)'
color.cssa() // CSS rgba syntax: 'rgba(10,128,220,0.8)'
color.toString() // For debugging: '[one.color.RGB: Red=0.3 Green=0.8 Blue=0 Alpha=1]'
color.toJSON() // ["RGB"|"HSV"|"HSL", <number>, <number>, <number>, <number>]

Getters -- return the value of the channel (converts to other colorspaces as needed):

color.red()
color.green()
color.blue()
color.hue()
color.saturation()
color.value()
color.lightness()
color.alpha()

Setters -- return new color instances with one channel changed:

color.red(<number>)
color.green(<number>)
color.blue(<number>)
color.hue(<number>)
color.saturation(<number>)
color.value(<number>)
color.lightness(<number>)
color.alpha(<number>)

Adjusters -- return new color instances with the channel adjusted by the specified delta (0..1):

color.red(<number>, true)
color.green(<number>, true)
color.blue(<number>, true)
color.hue(<number>, true)
color.saturation(<number>, true)
color.value(<number>, true)
color.lightness(<number>, true)
color.alpha(<number>, true)

Comparison with other color objects (epsilon defaults to 1e-9):

color.equals(otherColor, <epsilon>)

Mostly for internal (and plugin) use:

"Low level" constructors, accept 3 or 4 numerical arguments (0..1):

new one.color.RGB(r, g, b[, a])
new one.color.HSL(h, s, l[, a])
new one.color.HSV(h, s, v[, a])

All color instances have rgb(), hsv(), and hsl() methods for explicitly converting to another color space. Like the setter and adjuster methods they return a new color object representing the same color in another color space.

If for some reason you need to get all the channel values in a specific colorspace, do an explicit conversion first to cut down on the number of implicit conversions:

var myColor = one.color('#0620ff').lightness(+.3).rgb();
// Alerts '0 0.06265060240963878 0.5999999999999999':
alert(myColor.red() + ' ' + myColor.green() + ' ' + myColor.blue());

Adding a colorspace implementation:

one.color.installColorSpace(name, channelNames, {
    // Mandatory: Method for converting from your colorspace to RGB
    rgb: function () {
        return new one.color.RGB(r, g, b, a);
    },

    // Mandatory: Method for converting from RGB to your colorspace
    // (will be installed as a method on RGB color instances)
    fromRgb: function () {
        return new one.color.MyColorSpace(x, y, z, a);
    }
    // Optional: More methods for converting directly to other colorspaces.
    hsv: function () {
        // Method for converting from your colorspace to HSV...
        return new one.color.HSV(h, s, v, a);
    }
});

See HSL.js, HSV.js, and CMYK.js in lib/one/color for examples.

Building

The Makefile uses AssetGraph.

If you aren't up for a complete installation, there are pre-built packages in the repository as well as the npm package:

• Basic library: one-color.js, debuggable version: one-color-debug.js
• Full library including named color support: one-color-all.js, debuggable version: one-color-all-debug.js.

License

one.color is licensed under a standard 3-clause BSD license -- see the LICENSE-file for details.