# Identicon
[](http://opensource.org/licenses/BSD-3-Clause)
[](https://hackage.haskell.org/package/identicon)
[](http://stackage.org/nightly/package/identicon)
[](http://stackage.org/lts/package/identicon)
The package implements a flexible framework for generation of identicons on
top of [Juicy Pixels](https://hackage.haskell.org/package/JuicyPixels).
## Quick start
To use the package you usually need the following imports and language
extensions:
```haskell
{-# LANGUAGE DataKinds #-}
{-# LANGUAGE TypeOperators #-}
import Codec.Picture -- JuicyPixels
import Data.ByteString (ByteString) -- we use strict byte strings
import Data.Proxy
import Data.Word (Word8)
import Graphics.Identicon -- core definitions
import Graphics.Identicon.Primitive -- some visual primitives
```
You first write a type that represents the total number of bytes your
identicon consumes and the number of distinct visual components it has (they
are called “layers” in the terminology of the package):
```haskell
type MyIcon = Identicon 12 :+ Consumer 4 :+ Consumer 4 :+ Consumer 4
```
Here we have an identicon that needs 12 bytes to be generated. It has three
consumers that take 4 bytes each and generate layers, i.e. visual objects
(circles, squares, etc.).
The second step is to write implementation of every layer. We can use the
primitives available out-of-the-box, they live in the
`Graphics.Identicon.Primitive` module:
```haskell
myImpl :: Implementation MyIcon
myImpl = Identicon :+ a :+ a :+ a
where
a :: Word8 -> Word8 -> Word8 -> Word8 -> Layer
a r g b n =
rsym $ onGrid 3 3 n $
gradientXY (edge . mid) black (PixelRGB8 r g b)
```
Every byte is available to the layer-generating function as a distinct
`Word8` argument. The type system makes sure that:
* you consume exactly as many bytes as you promised in the type of your
identicon;
* you have as many layers as you have described in the type of your
identicon;
* every function in your implementation has a correct signature (i.e. it
takes as many `Word8`s as promised and produces a `Layer` in the end).
Mixing of layers and generation is handled by the library like this:
```haskell
-- | Here is the function that generates your identicons. It's usually
-- convenient to wrap the 'renderIdenticon' function that comes with the
-- library.
genMyIdenticon ::
-- | Identicon width
Int ->
-- | Identicon height
Int ->
-- | Input (some sort of hash or something)
ByteString ->
-- | Identicon, unless 'ByteString' is too short
Maybe (Image PixelRGB8)
genMyIdenticon = renderIdenticon (Proxy :: Proxy MyIcon) myImpl
```
For more information head straight to the Haddocks. BTW, I have
written
[a blog post](https://markkarpov.com/post/the-identicon-package.html) about
the package where I demonstrate some pictures generated with it.
## Related packages
The following packages are designed to be used with `identicon`:
* [`identicon-style-squares`](https://hackage.haskell.org/package/identicon-style-squares)
## Contribution
Issues, bugs, and questions may be reported in [the GitHub issue tracker for
this project](https://github.com/mrkkrp/identicon/issues).
Pull requests are also welcome.
## License
Copyright © 2016–present Mark Karpov
Distributed under BSD 3 clause license.