added color.clipped

docs/src/index.md

@@ -499,7 +499,7 @@ chroma('skyblue').lch()
 
 ### color.hcl
 
-Essentially an alias of [lch](#color-lch), but with the components in reverse order.
+Alias of [lch](#color-lch), but with the components in reverse order.
 
 ```js
 chroma('skyblue').hcl()
@@ -521,10 +521,31 @@ chroma('#b3ccff').temperature();
 
 ### color.gl
 
+Like RGB, but in the channel range of `[0..1]` instead of `[0..255]`
+
 ```js
 chroma('33cc00').gl();
 ```
 
+### color.clipped
+
+When converting colors from CIELab color spaces to RGB the color channels get clipped to the range of `[0..255]`. Colors outside that range may exist in nature but are not displayable on RGB monitors (such as ultraviolet). you can use color.clipped to test if a color has been clipped or not.
+
+```js
+[c = chroma.hcl(50, 40, 20), c.clipped()];
+[c = chroma.hcl(50, 40, 40), c.clipped()];
+[c = chroma.hcl(50, 40, 60), c.clipped()];
+[c = chroma.hcl(50, 40, 80), c.clipped()];
+[c = chroma.hcl(50, 40, 100), c.clipped()];
+```
+
+As a bonus feature you can access the unclipped RGB components using `color._rgb._unclipped`.
+
+```js
+chroma.hcl(50, 40, 100).rgb();
+chroma.hcl(50, 40, 100)._rgb._unclipped;
+```
+
 ## color scales
 
 ### chroma.scale

src/converter/in/hcg2rgb.coffee

@@ -25,7 +25,4 @@ hcg2rgb = () ->
             when 3 then [r,g,b] = [p, q, v]
             when 4 then [r,g,b] = [t, p, v]
             when 5 then [r,g,b] = [v, p, q]
-    r = round r
-    g = round g
-    b = round b
     [r, g, b, if args.length > 3 then args[3] else 1]

src/converter/in/hsv2rgb.coffee

@@ -22,7 +22,4 @@ hsv2rgb = () ->
             when 3 then [r,g,b] = [p, q, v]
             when 4 then [r,g,b] = [t, p, v]
             when 5 then [r,g,b] = [v, p, q]
-    r = round r
-    g = round g
-    b = round b
     [r, g, b, if args.length > 3 then args[3] else 1]

src/converter/in/lab2rgb.coffee

@@ -16,10 +16,6 @@ lab2rgb = () ->
     g = xyz_rgb -0.9692660 * x + 1.8760108 * y + 0.0415560 * z
     b = xyz_rgb 0.0556434 * x - 0.2040259 * y + 1.0572252 * z
 
-    r = limit r,0,255
-    g = limit g,0,255
-    b = limit b,0,255
-
     [r,g,b,if args.length > 3 then args[3] else 1]
 
 

src/converter/in/lch2rgb.coffee

@@ -5,4 +5,4 @@ lch2rgb = () ->
     [l,c,h] = args
     [L,a,b] = lch2lab l,c,h
     [r,g,b] = lab2rgb L,a,b
-    [limit(r,0,255), limit(g,0,255), limit(b,0,255), if args.length > 3 then args[3] else 1]
+    [r, g, b, if args.length > 3 then args[3] else 1]

src/converter/in/temperature2rgb.coffee

@@ -15,4 +15,4 @@ temperature2rgb = (kelvin) ->
         r = 351.97690566805693 + 0.114206453784165 * (r = temp-55) - 40.25366309332127 * log(r)
         g = 325.4494125711974 + 0.07943456536662342 * (g = temp-50) - 28.0852963507957 * log(g)
         b = 255
-    clip_rgb [r,g,b]
+    [r,g,b]

src/index.coffee

@@ -24,6 +24,7 @@
     delta-e
 
     get set
+    clipped
 
     alpha darken saturate premultiply blend    
 

src/io/rgb.coffee

@@ -10,7 +10,7 @@ Color::rgb = (round=true) ->
     if round then @_rgb.map(Math.round).slice 0,3 else @_rgb.slice 0,3
 
 Color::rgba = (round=true) ->
-    return @_rgb if not round
+    return @_rgb.slice(0) if not round
     return [Math.round(@_rgb[0]), Math.round(@_rgb[1]), Math.round(@_rgb[2]), @_rgb[3]]
 
 _guess_formats.push

src/ops/clipped.coffee

@@ -0,0 +1,4 @@
+# @require color
+
+Color::clipped = () ->
+    @_rgb._clipped or false

src/utils.coffee

@@ -25,13 +25,17 @@ unpack = (args) ->
         args[0]
 
 clip_rgb = (rgb) ->
-    for i of rgb
+    rgb._clipped = false
+    rgb._unclipped = rgb.slice(0)
+    for i in [0...3]
         if i < 3
+            rgb._clipped = true if rgb[i] < 0 or rgb[i] > 255
             rgb[i] = 0 if rgb[i] < 0
             rgb[i] = 255 if rgb[i] > 255
         else if i == 3
             rgb[i] = 0 if rgb[i] < 0
             rgb[i] = 1 if rgb[i] > 1
+    delete rgb._unclipped if not rgb._clipped
     rgb
 
 {PI, round, cos, floor, pow, log, sin, sqrt, atan2, max, abs} = Math

test/lch-test.coffee

@@ -25,4 +25,12 @@ vows
             'blue-ish': (t) -> assert.equal chroma.lch(t[4]).hex(), '#008cde'
             'purple-ish': (t) -> assert.equal chroma.lch(t[5]).hex(), '#6f67df'
 
+        'clipping':
+            topic: (chroma.hcl(50, 40, l) for l in [20,40,60,80,100])
+            '20-clipped': (t) -> assert.equal t[0].clipped(), true
+            '40-not clipped': (t) -> assert.equal t[1].clipped(), false
+            '60-not clipped': (t) -> assert.equal t[2].clipped(), false
+            '80-clipped': (t) -> assert.equal t[3].clipped(), true
+            '100-clipped': (t) -> assert.equal t[4].clipped(), true
+
     .export(module)