Inkspot

A small Clojure/ClojureScript library for creating colour swatches and converting between colorspaces.

Pre-requisites

You will need Leiningen 2.4.2 or above installed.

Building

To build and install the library locally, run:

$ lein test
$ lein install

Including in your project

There is version hosted at Clojars. For leiningen include a dependency:

[rm-hull/inkspot "0.2.1"]

For maven-based projects, add the following to your pom.xml:

<dependency>
  <groupId>rm-hull</groupId>
  <artifactId>inkspot</artifactId>
  <version>0.2.1</version>
</dependency>

Basic Usage

See the API Documentation.

A cross-platform IColor protocol has been overlaid on several common color representations. For example, in Clojure:

(color/coerce 0xFF0000)
=> #<Color java.awt.Color[r=255,g=0,b=0]>

(color/coerce "#00FF00")
=> #<Color java.awt.Color[r=0,g=255,b=0]>

(color/coerce "rgb(0,0,255)")
=> #<Color java.awt.Color[r=0,g=0,b=255]>

(color/coerce java.awt.Color/MAGENTA)
=> #<Color java.awt.Color[r=255,g=0,b=255]>

(color/coerce [255 255 0])
=> #<Color java.awt.Color[r=255,g=255,b=0]>

Specifying the color by keyword is also possible, with unknown colors returning nil as might be expected. The full list of supported color names can be found in the lindsay and X11 files. Notes: (1) The lindsay list is checked first, and if the color name is not present, it is then checked for in the X11 list. (2) the coerce lookup is case insensitive.

(color/coerce :bisque)
=> #<Color java.awt.Color[r=255,g=228,b=196]>

(color/coerce :BISQUE)
=> #<Color java.awt.Color[r=255,g=228,b=196]>

(color/coerce :none-existent-color)
=> nil

For ClojureScript, the same calls would instead yield a string representation, thus:

(color/coerce :bisque)
=> "rgba(255,228,196,1.0)"

Built-in color swatches

There are a number of built-in swatches which can be used,

Distinct Color swatches

Function	Color Palette
color-chart/web-safe-colors
color-chart.lindsay/swatch
color-chart.x11/swatch

Interpolated Color swatches

Function	Color Palette
color-chart/spectrum
color-chart/rainbow
color-chart/hue
color-chart/gradient :orange :blue 216
color-chart/gradient :red :snow 216
color-chart/heatmap 216
color-chart/cube-helix 216

These palettes were generated with the following example:

(ns inkspot.examples
  (require [clojure.java.io :as io]
           [inkspot.color :as color]
           [inkspot.color-chart :as cc]
           [inkspot.palette :as palette]
           [inkspot.color-chart.lindsay :as lindsay]
           [inkspot.color-chart.x11 :as x11])
  (import [javax.imageio ImageIO]))

;; Distinct Color Swatches
(doseq [[k v] {:web-safe-colors (map color/coerce cc/web-safe-colors)
               :lindsay         (map color/coerce (vals lindsay/swatch))
               :x11             (map color/coerce (vals x11/swatch))}
        :let [f (io/file (str "example/palette/" (name k) ".png"))]]
  (ImageIO/write (palette/draw v :g2d-target palette/bitmap) "png" f))

;; Interpolated Color Swatches
(doseq [[k v] {:spectrum   (cc/spectrum 216)
               :rainbow    (cc/rainbow 216)
               :gradient1  (cc/gradient :orange :blue 216)
               :gradient2  (cc/gradient :red :snow 216)
               :heatmap    (cc/heatmap 216)
               :cube-helix (cc/cube-helix 216)}
        :let [f (io/file (str "example/palette/" (name k) ".png"))]]
  (ImageIO/write (palette/draw v :g2d-target palette/bitmap
                                 :cell-width 2 :cell-height 50
                                 :cells-per-row 216 :border 0) "png" f))

uiGradients

The gradients.json from uiGradients is loaded in (via a macro in clojurescript), and interpolated color swatches can be generated by specifying the color name. For example:

; Names can be specified as the named strings or kebab-case
(cc/ui-gradient :sea-blizz 240)
=> (#<Color java.awt.Color[r=28,g=216,b=210]> #<Color java.awt.Color[r=28,g=216,b=209]> ...

(cc/ui-gradient "Sea Blizz" 240)
=> (#<Color java.awt.Color[r=28,g=216,b=210]> #<Color java.awt.Color[r=28,g=216,b=209]> ...

Name	Color Palette
:a-lost-memory
:almost
:amethyst
:aqua-marine
:aqualicious
:army
:ash
:aubergine
:autumn
:behongo
:bloody-mary
:blurry-beach
:bora-bora
:bourbon
:calm-darya
:candy
:cheer-up-emo-kid
:cherry
:cherryblossoms
:clouds
:dance-to-forget
:day-tripper
:dirty-fog
:dracula
:earthly
:electric-violet
:emerald-water
:facebook-messenger
:forever-lost
:frozen
:horizon
:influenza
:jonquil
:juicy-orange
:kashmir
:kyoto
:lemon-twist
:man-of-steel
:mango-pulp
:mantle
:miaka
:midnight-city
:mirage
:misty-meadow
:mojito
:moonrise
:moor
:moss
:mystic
:namn
:neon-life
:opa
:parklife
:peach
:petrichor
:pinky
:pinot-noir
:purple-paradise
:red-mist
:reef
:rose-water
:sea-blizz
:sea-weed
:shadow-night
:shore
:shrimpy
:shroom-haze
:sirius-tamed
:soundcloud
:starfall
:steel-gray
:stellar
:sunrise
:teal-love
:the-strain
:titanium
:vasily
:venice-blue
:virgin
:winter

The JSON file is packaged into the inkspot jar, but the uiGradients project is referenced as a git submodule and the intention is to keep it mostly up-to-date as new inkspot releases are published.

Mixing Colors

TODO

Cycling Colors

TODO

Linear mapping across numeric ranges

A color swatch can be mapped to a specific range of numbers (integer or floating point), where for each given input in the range, the nearest color is selected. For example,

(use 'inkspot.color-chart)

(def colors
  (color-mapper
    (spectrum 48)
    100 250))

(colors 100) ; lower bound is inclusive
=> #<Color java.awt.Color[r=224,g=0,b=0]>

(colors 249.99)
=> #<Color java.awt.Color[r=110,g=0,b=180]>

(colors 250) ; upper bound is exclusive
=> nil

(colors 43) ; outside range
=> nil

Converting IColor instances to other colorspaces and back

The inkspot.converter namespace supports the following conversions to/from IColor instances. In all cases the non-RGB colorspace results are always returned as vector of 3 elements.

• HSV (Hue, Saturation, Value)
• HSL (Hue, Saturation, Luminosity)
• Y'UV (Luma, Chrominance as used in PAL video standards)

(use 'inkspot.converter)

(rgb->hsv :yellow)
=> [60.0 1.0 1.0]

(hsv->rgb [60.0 1.0 1.0])
=> #<Color java.awt.Color[r=255,g=255,b=0]>

TODO

• Web-safe colors
• Spectral colors
• IColor protocol
• Color mapper function - given a numerical range and a color swatch, maps numerical input to the range of colors
• Color averaging/mixing
• Create PNG & SVG swatch palette representations (& add custome height, width, border options)
• Logarithmic color mapper function
• Import LUT maps
• Gradient interpolation: Use HSV values rather than RGB interpolation? not necessary
• RGB, HSV, HSL, YUV, YIQ colorspace conversions
• X11 Color names
• Monochrome/triadic/tetradic schemes
• CubeHelix schemes
• Embed uiGradients

Known Bugs

• CLJS files not generating properly

References

• http://catless.ncl.ac.uk/Lindsay/swatch0.html
• http://www.lynda.com/resources/hexpalette/hue.html
• https://github.com/xav/Grapefruit
• http://www.mcfedries.com/books/cightml/x11color.htm
• http://www.mrao.cam.ac.uk/~dag/CUBEHELIX/
• https://github.com/Ghosh/uiGradients

Attribution

This repo incorporates gradients.json from uiGradients.

License

The MIT License (MIT)

Copyright (c) 2016 Richard Hull

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.