one.color
JavaScript color calculation toolkit for node.js and the browser.
- 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(...)
, 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());
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;
myColor.red()
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()
To turn a color instance back into a string, use the hex()
, css()
,
and cssa()
methods:
one.color('rgb(124, 96, 200)').hex()
one.color('#bb7b81').cssa()
Color instances have getters/setters for all channels in all supported
colorspaces (red()
, green()
, blue()
, hue()
, saturation()
, lightness()
,
value()
, alpha()
, etc.). Thus you don't need to think about which colorspace
you're in. All the necessary conversions happen automatically:
one.color('#ff0000')
.green(1)
.hue(.5, true)
.hex()
When called without any arguments, they return the current value of
the channel (0..1):
one.color('#09ffdd').green()
one.color('#09ffdd').saturation()
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()
myColor.red()
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(-.1, true)
.hex()
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()
Comparing color objects
If you need to know whether two colors represent the same 8 bit color, regardless
of colorspace, compare their hex()
values:
one.color('#f00').hex() === one.color('#e00').red(1).hex()
Use the equals
method to compare two color instances within a certain
epsilon (defaults to 1e-9
).
one.color('#e00').lightness(.00001, true).equals(one.color('#e00'), 1e-5)
one.color('#e00').lightness(.000001, true).equals(one.color('#e00'), 1e-5)
Before comparing the equals
method converts the other color to the right colorspace,
so you don't need to convert explicitly in this case either:
one.color('#e00').hsv().equals(one.color('#e00'))
API overview
Color parser function, the recommended way to create a color instance:
one.color('#a9d91d')
one.color('#eee')
one.color('rgb(124, 96, 200)')
one.color('rgb(99%, 40%, 0%)')
one.color('rgba(124, 96, 200, .4)')
one.color('hsl(120, 75%, 75%)')
one.color('hsla(120, 75%, 75%, .1)')
one.color('hsv(220, 47%, 12%)')
one.color('hsva(120, 75%, 75%, 0)')
one.color([0, 4, 255, 120])
one.color(["RGB", .5, .1, .6, .9])
The slightly bigger one-color-all.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'))
Serialization methods:
color.hex()
color.css()
color.cssa()
color.toString()
color.toJSON()
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()
color.cyan()
color.magenta()
color.yellow()
color.black()
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>)
color.magenta(<number>)
color.yellow(<number>)
color.black(<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)
color.cyan(<number>, true)
color.magenta(<number>, true)
color.yellow(<number>, true)
color.black(<number>, true)
Comparison with other color objects, returns true
or false
(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(<red>, <green>, <blue>[, <alpha>])
new one.color.HSL(<hue>, <saturation>, <lightness>[, <alpha>])
new one.color.HSV(<hue>, <saturation>, <value>[, <alpha>])
The one-color-all.js build includes CMYK support:
new one.color.CMYK(<cyan>, <magenta>, <yellow>, <black>[, <alpha>])
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();
alert(myColor.red() + ' ' + myColor.green() + ' ' + myColor.blue());
Building
git clone https://github.com/One-com/one-color.git
cd one-color
npm install
make
If you aren't up for a complete installation, there are pre-built
packages in the repository as well as the npm package:
License
one.color is licensed under a standard 2-clause BSD license -- see the LICENSE-file for details.