Skip to content

Commit

Permalink
Update README.
Browse files Browse the repository at this point in the history
  • Loading branch information
mbostock committed Dec 18, 2015
1 parent c497753 commit e80621c
Show file tree
Hide file tree
Showing 2 changed files with 27 additions and 35 deletions.
60 changes: 26 additions & 34 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,17 +1,17 @@
# d3-color

Even though your browser understands a lot about colors, it doesn’t offer much help in manipulating colors through JavaScript. The d3-color module therefore provides representations for various color spaces, allowing specification, [interpolation](https://github.com/d3/d3-interpolate), conversion and manipulation.
Even though your browser understands a lot about colors, it doesn’t offer much help in manipulating colors through JavaScript. The d3-color module therefore provides representations for various color spaces, allowing specification, conversion and manipulation. (Also see [d3-interpolate](https://github.com/d3/d3-interpolate) for color interpolation.)

For example, take the color named “steelblue”:

```js
color("steelblue"); // {r: 70, g: 130, b: 180}
var c = d3_color.color("steelblue"); // {r: 70, g: 130, b: 180}
```

Let’s try converting it to HSL:

```js
hsl("steelblue"); // {h: 207.27272727272728, s: 0.44, l: 0.4901960784313726}
var c = d3_color.hsl("steelblue"); // {h: 207.27272727272728, s: 0.44, l: 0.4901960784313726}
```

Now rotate the hue by 90°, bump up the saturation, and format as hex:
Expand All @@ -31,11 +31,17 @@ Cubehelix features monotonic lightness, while Lab and HCL are perceptually unifo

## Installing

If you use NPM, `npm install d3-color`. Otherwise, download the [latest release](https://github.com/d3/d3-color/releases/latest).
If you use NPM, `npm install d3-color`. Otherwise, download the [latest release](https://github.com/d3/d3-color/releases/latest). The released bundle supports AMD, CommonJS, and vanilla environments. Create a custom build using [Rollup](https://github.com/rollup/rollup) or your preferred bundler. You can also load directly from [d3js.org](https://d3js.org):

```html
<script src="https://d3js.org/d3-color.v0.3.min.js"></script>
```

In a vanilla environment, a `d3_color` global is exported. [Try d3-color in your browser.](https://tonicdev.com/npm/d3-color)

## API Reference

<a name="color" href="#color">#</a> <b>color</b>(<i>specifier</i>)
<a name="color" href="#color">#</a> d3_color.<b>color</b>(<i>specifier</i>)

Parses the specified [CSS Color Module Level 3](http://www.w3.org/TR/css3-color/#colorunits) *specifier* string, returning an [RGB](#rgb) or [HSL](#hsl) color. If the specifier was not valid, null is returned. Some examples:

Expand Down Expand Up @@ -69,56 +75,42 @@ Returns true if and only if the color is displayable on standard hardware. For e

Returns the RGB hexadecimal string representing this color, such as `"#f7eaba"`. If this color is not displayable, a suitable displayable color is returned instead. For example, RGB channel values greater than 255 are clamped to 255.

<a name="rgb" href="#rgb">#</a> <b>rgb</b>(<i>r</i>, <i>g</i>, <i>b</i>)<br>
<a href="#rgb">#</a> <b>rgb</b>(<i>specifier</i>)<br>
<a href="#rgb">#</a> <b>rgb</b>(<i>color</i>)<br>
<a name="rgb" href="#rgb">#</a> d3_color.<b>rgb</b>(<i>r</i>, <i>g</i>, <i>b</i>)<br>
<a href="#rgb">#</a> d3_color.<b>rgb</b>(<i>specifier</i>)<br>
<a href="#rgb">#</a> d3_color.<b>rgb</b>(<i>color</i>)<br>

Constructs a new [RGB](https://en.wikipedia.org/wiki/RGB_color_model) color. The channel values are exposed as `r`, `g` and `b` properties on the returned instance. Use the [RGB color picker](http://bl.ocks.org/mbostock/78d64ca7ef013b4dcf8f) to explore this color space.

If *r*, *g* and *b* are specified, these represent the channel values of the returned color. If a CSS Color Module Level 3 *specifier* string is specified, it is parsed and then converted to the RGB color space. See [color](#color) for examples. If a [*color*](#color) instance is specified, it is converted to the RGB color space using [*color*.rgb](#color_rgb). Note that unlike [*color*.rgb](#color_rgb) this method *always* returns a new instance, even if *color* is already an RGB color.

<a name="hsl" href="#hsl">#</a> <b>hsl</b>(<i>h</i>, <i>s</i>, <i>l</i>)<br>
<a href="#hsl">#</a> <b>hsl</b>(<i>specifier</i>)<br>
<a href="#hsl">#</a> <b>hsl</b>(<i>color</i>)<br>
<a name="hsl" href="#hsl">#</a> d3_color.<b>hsl</b>(<i>h</i>, <i>s</i>, <i>l</i>)<br>
<a href="#hsl">#</a> d3_color.<b>hsl</b>(<i>specifier</i>)<br>
<a href="#hsl">#</a> d3_color.<b>hsl</b>(<i>color</i>)<br>

Constructs a new [HSL](https://en.wikipedia.org/wiki/HSL_and_HSV) color. The channel values are exposed as `h`, `s` and `l` properties on the returned instance. Use the [HSL color picker](http://bl.ocks.org/mbostock/debaad4fcce9bcee14cf) to explore this color space.

If *h*, *s* and *l* are specified, these represent the channel values of the returned color. If a CSS Color Module Level 3 *specifier* string is specified, it is parsed and then converted to the HSL color space. See [color](#color) for examples. If a [*color*](#color) instance is specified, it is converted to the RGB color space using [*color*.rgb](#color_rgb) and then converted to HSL. (Colors already in the HSL color space skip the conversion to RGB.)

<a name="lab" href="#lab">#</a> <b>lab</b>(<i>l</i>, <i>a</i>, <i>b</i>)<br>
<a href="#lab">#</a> <b>lab</b>(<i>specifier</i>)<br>
<a href="#lab">#</a> <b>lab</b>(<i>color</i>)<br>
<a name="lab" href="#lab">#</a> d3_color.<b>lab</b>(<i>l</i>, <i>a</i>, <i>b</i>)<br>
<a href="#lab">#</a> d3_color.<b>lab</b>(<i>specifier</i>)<br>
<a href="#lab">#</a> d3_color.<b>lab</b>(<i>color</i>)<br>

Constructs a new [Lab](https://en.wikipedia.org/wiki/Lab_color_space#CIELAB) color. The channel values are exposed as `l`, `a` and `b` properties on the returned instance. Use the [Lab color picker](http://bl.ocks.org/mbostock/9f37cc207c0cb166921b) to explore this color space.

If *l*, *a* and *b* are specified, these represent the channel values of the returned color. If a CSS Color Module Level 3 *specifier* string is specified, it is parsed and then converted to the Lab color space. See [color](#color) for examples. If a [*color*](#color) instance is specified, it is converted to the RGB color space using [*color*.rgb](#color_rgb) and then converted to Lab. (Colors already in the Lab color space skip the conversion to RGB, and colors in the HCL color space are converted directly to Lab.)

<a name="hcl" href="#hcl">#</a> <b>hcl</b>(<i>h</i>, <i>c</i>, <i>l</i>)<br>
<a href="#hcl">#</a> <b>hcl</b>(<i>specifier</i>)<br>
<a href="#hcl">#</a> <b>hcl</b>(<i>color</i>)<br>
<a name="hcl" href="#hcl">#</a> d3_color.<b>hcl</b>(<i>h</i>, <i>c</i>, <i>l</i>)<br>
<a href="#hcl">#</a> d3_color.<b>hcl</b>(<i>specifier</i>)<br>
<a href="#hcl">#</a> d3_color.<b>hcl</b>(<i>color</i>)<br>

Constructs a new [HCL](https://en.wikipedia.org/wiki/Lab_color_space#CIELAB) color. The channel values are exposed as `h`, `c` and `l` properties on the returned instance. Use the [HCL color picker](http://bl.ocks.org/mbostock/3e115519a1b495e0bd95) to explore this color space.

If *h*, *c* and *l* are specified, these represent the channel values of the returned color. If a CSS Color Module Level 3 *specifier* string is specified, it is parsed and then converted to the HCL color space. See [color](#color) for examples. If a [*color*](#color) instance is specified, it is converted to the RGB color space using [*color*.rgb](#color_rgb) and then converted to HCL. (Colors already in the HCL color space skip the conversion to RGB, and colors in the Lab color space are converted directly to HCL.)

<a name="cubehelix" href="#cubehelix">#</a> <b>cubehelix</b>(<i>h</i>, <i>s</i>, <i>l</i>)<br>
<a href="#cubehelix">#</a> <b>cubehelix</b>(<i>specifier</i>)<br>
<a href="#cubehelix">#</a> <b>cubehelix</b>(<i>color</i>)<br>
<a name="cubehelix" href="#cubehelix">#</a> d3_color.<b>cubehelix</b>(<i>h</i>, <i>s</i>, <i>l</i>)<br>
<a href="#cubehelix">#</a> d3_color.<b>cubehelix</b>(<i>specifier</i>)<br>
<a href="#cubehelix">#</a> d3_color.<b>cubehelix</b>(<i>color</i>)<br>

Constructs a new [Cubehelix](https://www.mrao.cam.ac.uk/~dag/CUBEHELIX/) color. The channel values are exposed as `h`, `s` and `l` properties on the returned instance. Use the [Cubehelix color picker](http://bl.ocks.org/mbostock/ba8d75e45794c27168b5) to explore this color space.

If *h*, *s* and *l* are specified, these represent the channel values of the returned color. If a CSS Color Module Level 3 *specifier* string is specified, it is parsed and then converted to the Cubehelix color space. See [color](#color) for examples. If a [*color*](#color) instance is specified, it is converted to the RGB color space using [*color*.rgb](#color_rgb) and then converted to Cubehelix. (Colors already in the Cubehelix color space skip the conversion to RGB.)

## Changes from D3 3.x:

* A new [cubehelix](#cubehelix) color space!

* A new [color](#color) method parses the specified string according to the CSS specification and returns the corresponding color in its color space. For HSL color values, this is the HSL color space; for other values, the RGB color space is used. This method correctly parses RGB colors with percentages (e.g., `rgb(30%,40%,50%)`). Decimal values where integers are required are no longer allowed (e.g., `rgb(100.5,0,0)` is not a valid color).

* The [*color*.brighter](#color_brighter) method no longer special-cases behavior for black and very dark channels in RGB; it is now a simple channel multiplier, consistent with [*color*.darker](#color_darker) and other color spaces.

* The *rgb*.hsl method has been removed; use the [hsl constructor](#hsl) to convert to HSL instead.

* All color spaces, including RGB, now support the [*color*.rgb](#color_rgb) method. This method returns a color instance representing the nearest-equivalent color in the RGB color space. Use the [rgb constructor](#rgb) if you want a copy.

* When converting from Lab to HCL, hue and chroma are no longer undefined if the luminance is zero. Thus, the roundtrip from Lab to HCL and back again no longer loses information.
2 changes: 1 addition & 1 deletion package.json
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
{
"name": "d3-color",
"version": "0.3.1",
"version": "0.3.2",
"description": "Color spaces! RGB, HSL, Cubehelix, Lab and HCL (Lch).",
"keywords": [
"d3",
Expand Down

0 comments on commit e80621c

Please sign in to comment.