Plugins

Color Spaces

Color Space Plugins are dead simple (for now). Here's the XYZ plugin in it's entirty. This also happens to be the bare minimum needed to have a valid color space plugin.

alchemist.use({ name: 'xyz', to: {} })

This obviously isn't going to get you very far, as it doesn't define any relationships with any other color spaces. Let's create our own version of RGB that has a 0:1 scale rather than 0:255.

alchemist.use({
  name: 'myrgb',
    to: {
    'rgb': function (mR, mG, mB) {
      var R = mR * 255
      var G = mG * 255
      var B = mB * 255
      return [R, G, B]
    }
  }
})

That's it! Now just include alchemist-rgb and let's try it out.

  var rgb = require('alchemist-rgb')
  alchemist.use(rgb())

  alchemist.myrgb(0, .5, 1).rgb() // => [0, 127.5, 255]

Nice! What happens when we try to convert from rgb to myrgb?

  alchemist.rgb(255, 255, 255).myrgb() // Error! Alchemist does not know how to convert from rgb to myrgb

Error?? Looks like we need to shout at the alchemist-rgb guys becuase they haven't implemented a conversion to the best color space in the world!

...or

Again, we can define our own conversion.

  alchemist.use({
  name: 'myrgb',
  to: {
    'rgb': function (mR, mG, mB) {
      var R = mR * 255
      var G = mG * 255
      var B = mB * 255
      return [R, G, B]
    }
  },
  from: {
    'rgb': function (R, G, B) {
      var mR = R / 255
      var mG = G / 255
      var mB = B / 255
      return [mR, mG, mB]
    }
  }
})

alchemist.rgb(255, 255, 255).myrgb() // [1, 1, 1]

If you ever need to know things like "what reference white are we using?" you can pass .use() a function that returns your plugin instead. This will expose Alchemist and all of it's properties as the first argument of the passed function.

alchemist.use(function (alchemist) {
  alchemist.white //=> { X: 0.9505, Y: 1, Z: 1.089}

  return {
    name: 'rgb',
    to: {
      //...
    }
  }
})

Color Methods

Color Methods are a recent addition to alchemist plugins. More documentation is coming later, but to get you started, here is an example method. This method will set the lighteness of a color when used as a method of that color (e.g. color.lightness(50)), and will measure the lightness when used as a global (e.g. alchemist.lightness(color))

alchemist.use({
  name: 'lightness',
  methods: {
    // is attached to each color
    color: function (amount) {
      var lab = color.as('lab')
      lab[0] = amount
      return lab
    },
    // is attached to alchemist itself
    global: function (color) {
      return color.as('lab')[0]
    }
  }
})