Simplify API and introduce automatic routing between models

README.md

@@ -6,11 +6,10 @@ Color-convert is a color conversion library for JavaScript and node.
 It converts all ways between `rgb`, `hsl`, `hsv`, `hwb`, `cmyk`, `ansi`, `ansi16`, `hex` strings, and CSS `keyword`s:
 
 ```js
-var converter = require("color-convert")();
+var convert = require('color-convert');
 
-converter.rgb(140, 200, 100).hsl()   // [96, 48, 59]
-
-converter.keyword("blue").rgb()      // [0, 0, 255]
+convert.rgb.hsl(140, 200, 100);   // [96, 48, 59]
+convert.keyword.rgb('blue');      // [0, 0, 255]
 ```
 
 # Install
@@ -21,41 +20,43 @@ $ npm install color-convert
 
 # API
 
-Color-convert exports a converter object with getter/setter methods for each color space. It caches conversions:
+Simply get the property of the _from_ and _to_ conversion that you're looking for.
+
+All functions have a rounded and unrounded variant. By default, return values are rounded. To get the unrounded (raw) results, simply tack on `.raw` to the function.
 
 ```js
-var converter = require("color-convert")();
+var convert = require('color-convert');
 
-converter.rgb(140, 200, 100).hsl()   // [96, 48, 59]
+// Hex to LAB
+convert.hex.lab('DEADBF');         // [ 76, 21, -2 ]
+convert.hex.lab.raw('DEADBF');     // [ 75.56213190997677, 20.653827952644754, -2.290532499330533 ]
 
-converter.rgb([140, 200, 100])       // args can be an array
+// RGB to CMYK
+convert.rgb.cmyk(167, 255, 4);     // [ 35, 0, 98, 0 ]
+convert.rgb.cmyk.raw(167, 255, 4); // [ 34.509803921568626, 0, 98.43137254901961, 0 ]
 ```
 
-### Plain functions
-Get direct conversion functions with no fancy objects:
-
-```js
-require("color-convert").rgb2hsl([140, 200, 100]);   // [96, 48, 59]
-```
+### Arrays
+All functions that accept multiple arguments also support passing an array.
 
-### Unrounded
-To get the unrounded conversion, append `Raw` to the function name:
+Not that this does **not** apply to functions that convert from a color that only requires one value (e.g. `keyword`, `ansi256`, `hex`, etc.)
 
 ```js
-convert.rgb2hslRaw([140, 200, 100]);   // [95.99999999999999, 47.619047619047606, 58.82352941176471]
-```
-
-### Hash
-There's also a hash of the conversion functions keyed first by the "from" color space, then by the "to" color space:
+var convert = require('color-convert');
 
-```js
-convert["hsl"]["hsv"]([160, 0, 20]) == convert.hsl2hsv([160, 0, 20])
+convert.rgb.hex(123, 45, 67);      // '7B2D43'
+convert.rgb.hex([123, 45, 67]);    // '7B2D43'
 ```
 
-### Other spaces
+## Routing
 
-There are some conversions from rgb (sRGB) to XYZ and LAB too, available as `rgb2xyz()`, `rgb2lab()`, `xyz2rgb()`, and `xyz2lab()`.
+Conversions that don't have an _explicitly_ defined conversion (in [conversions.js](conversions.js)), but can be converted by means of sub-conversions (e.g. XYZ -> **RGB** -> CMYK), are automatically routed together. This allows just about any color model supported by `color-convert` to be converted to any other model, so long as a sub-conversion path exists. This is also true for conversions requiring more than one step in between (e.g. LCH -> **LAB** -> **XYZ** -> **RGB** -> Hex).
+
+Keep in mind that extensive conversions _may_ result in a loss of precision, and exist only to be complete. For a list of "direct" (single-step) conversions, see [conversions.js](conversions.js).
 
 # Contribute
 
-Please fork, add conversions, figure out color profile stuff for XYZ, LAB, etc. This is meant to be a basic library that can be used by other libraries to wrap color calculations in some cool way.
+If there is a new model you would like to support, or want to add a direct conversion between two existing models, please send us a pull request.
+
+# License
+Copyright © 2011-2016, Heather Arthur and Josh Junon. Licensed under the [MIT License](LICENSE).