- Notifications
You must be signed in to change notification settings - Fork40
An OO-based JavaScript color parser/computation toolkit with support for RGB, HSV, HSL, CMYK, and alpha channels. Conversion between color spaces occurs implicitly, and all methods return new objects rather than mutating existing instances. Works in the browser and node.js.
License
One-com/one-color
Folders and files
| Name | Name | Last commit message | Last commit date | |
|---|---|---|---|---|
Repository files navigation
JavaScript color calculation toolkit for node.js and the browser.
Features:
- RGB, HSV, HSL, and CMYK colorspace support (experimental implementations of LAB and XYZ)
- 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(...), orrgba(...).
Module support:
- CommonJS / Node
- AMD / RequireJS
- Vanilla JS (installs itself on one.color)
Package managers:
- npm:
npm install onecolor - bower:
bower install color
Small sizes:
- one-color.js
(Basic RGB, HSV, HSL)
- one-color-all.js
(Full RGB, HSV, HSL, CMYK, XYZ, LAB, named colors,helper functions)
In the browser (changeone-color.js toone-color-all.js to gainnamed color support):
<scriptsrc="one-color.js"></script><script>alert('Hello, '+one.color('#650042').lightness(0.3).green(0.4).hex()+' world!');</script>
In the browser, the parser is exposed as a global namedonecolor.In node.js, it is returned directly with a require of the module(afternpm install onecolor):
varcolor=require('onecolor');console.warn(color('rgba(100%, 0%, 0%, .5)').alpha(0.4).cssa());
rgba(255,0,0,0.4)All of the above return color instances in the relevant color spacewith the channel values (0..1) as instance variables:
varmyColor=color('#a9d91d');myColorinstanceofcolor.RGB;// truemyColor.red();// 0.6627450980392157
You can also parse named CSS colors (works out of the box in node.js,but the requires the slightly biggerone-color-all.js build in thebrowser):
color('maroon').lightness(0.3).hex();// '#990000'
To turn a color instance back into a string, use thehex(),css(),andcssa() methods:
color('rgb(124, 96, 200)').hex();// '#7c60c8'color('#bb7b81').cssa();// 'rgba(187,123,129,1)'
Color instances have getters/setters for all channels in all supportedcolorspaces (red(),green(),blue(),hue(),saturation(),lightness(),value(),alpha(), etc.). Thus you don't need to think about which colorspaceyou're in. All the necessary conversions happen automatically:
color('#ff0000')// Red in RGB.green(1)// Set green to the max value, producing yellow (still RGB).hue(0.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 ofthe channel (0..1):
color('#09ffdd').green();// 1color('#09ffdd').saturation();// 0.9647058823529412
When called with a single numerical argument (0..1), a new colorobject is returned with that channel replaced:
varmyColor=color('#00ddff');myColor.red(0.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) andtrue asthe second argument, a new value is returned with that channeladjusted:
color('#ff0000')// Red.red(-0.1,true)// Adjust red channel by -0.1.hex();// '#e60000'
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:
color('rgba(10, 20, 30, .8)').green(0.4).saturation(0.2).alpha();// 0.8
If you need to know whether two colors represent the same 8 bit color, regardlessof colorspace, compare theirhex() values:
color('#f00').hex()===color('#e00').red(1).hex();// true
Use theequals method to compare two color instances within a certainepsilon (defaults to1e-9).
color('#e00').lightness(0.00001,true).equals(color('#e00'),1e-5);// falsecolor('#e00').lightness(0.000001,true).equals(color('#e00'),1e-5);// true
Before comparing theequals method converts the other color to the right colorspace,so you don't need to convert explicitly in this case either:
color('#e00').hsv().equals(color('#e00'));// true
Color parser function, the recommended way to create a color instance:
color('#a9d91d');// Regular hex syntaxcolor('a9d91d');// hex syntax, # is optionalcolor('#eee');// Short hex syntaxcolor('rgb(124, 96, 200)');// CSS rgb syntaxcolor('rgb(99%, 40%, 0%)');// CSS rgb syntax with percentagescolor('rgba(124, 96, 200, .4)');// CSS rgba syntaxcolor('hsl(120, 75%, 75%)');// CSS hsl syntaxcolor('hsla(120, 75%, 75%, .1)');// CSS hsla syntaxcolor('hsv(220, 47%, 12%)');// CSS hsv syntax (non-standard)color('hsva(120, 75%, 75%, 0)');// CSS hsva syntax (non-standard)color([0,4,255,120]);// CanvasPixelArray entry, RGBAcolor(['RGB',0.5,0.1,0.6,0.9]);// The output format of color.toJSON()
The slightly biggerone-color-all.js build adds support forthe standard suite of named CSS colors:
color('maroon');color('darkolivegreen');
Existing onecolor instances pass through unchanged, which is usefulin APIs where you want to accept either a string or a color instance:
color(color('#fff'));// Same as color('#fff')
Serialization methods:
varmyColor=color('#bda65b');myColor.hex();// 6-digit hex string: '#bda65b'myColor.css();// CSS rgb syntax: 'rgb(10,128,220)'myColor.cssa();// CSS rgba syntax: 'rgba(10,128,220,0.8)'myColor.toString();// For debugging: '[onecolor.RGB: Red=0.3 Green=0.8 Blue=0 Alpha=1]'myColor.toJSON();// ["RGB"|"HSV"|"HSL", <number>, <number>, <number>, <number>]
Getters -- return the value of the channel (converts to other colorspaces as needed):
varmyColor=color('#bda65b');myColor.red();myColor.green();myColor.blue();myColor.hue();myColor.saturation();myColor.value();myColor.lightness();myColor.alpha();myColor.cyan();// one-color-all.js and node.js onlymyColor.magenta();// one-color-all.js and node.js onlymyColor.yellow();// one-color-all.js and node.js onlymyColor.black();// one-color-all.js and node.js only
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>)color.cyan(<number>) // one-color-all.js and node.js onlycolor.magenta(<number>) // one-color-all.js and node.js onlycolor.yellow(<number>) // one-color-all.js and node.js onlycolor.black(<number>) // one-color-all.js and node.js only
Adjusters -- return new color instances with the channel adjusted bythe 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)color.cyan(<number>, true) // one-color-all.js and node.js onlycolor.magenta(<number>, true) // one-color-all.js and node.js onlycolor.yellow(<number>, true) // one-color-all.js and node.js onlycolor.black(<number>, true) // one-color-all.js and node.js only
Comparison with other color objects, returnstrue orfalse (epsilon defaults to1e-9):
color.equals(otherColor[,<epsilon>])
"Low level" constructors, accept 3 or 4 numerical arguments (0..1):
newonecolor.RGB(<red>,<green>,<blue>[,<alpha>])new onecolor.HSL(<hue>,<saturation>,<lightness>[,<alpha>])new onecolor.HSV(<hue>,<saturation>,<value>[,<alpha>])
Theone-color-all.js build includes CMYK support:
newonecolor.CMYK(<cyan>,<magenta>,<yellow>,<black>[,<alpha>])
All color instances havergb(),hsv(), andhsl() methods forexplicitly converting to another color space. Like the setter andadjuster methods they return a new color object representing the samecolor in another color space.
If for some reason you need to get all the channel values in aspecific colorspace, do an explicit conversion first to cut down onthe number of implicit conversions:
varmyColor=color('#0620ff').lightness(+0.3).rgb();console.log(myColor.red()+' '+myColor.green()+' '+myColor.blue());
0 0.06265060240963878 0.5999999999999999git clone https://github.com/One-com/one-color.gitcd one-colornpm installnpm run buildIf you aren't up for a complete installation, there are pre-builtpackages in the repository as well as the npm package:
- Basic library:one-color.js
- Full library including named color support:one-color-all.js
onecolor is licensed under a standard 2-clause BSD license -- see theLICENSE file for details.
About
An OO-based JavaScript color parser/computation toolkit with support for RGB, HSV, HSL, CMYK, and alpha channels. Conversion between color spaces occurs implicitly, and all methods return new objects rather than mutating existing instances. Works in the browser and node.js.