search

Schlipak / IdentiHeart

Identicon generator
http://schlipak.github.io/IdentiHeart/
Apache License 2.0
20 stars 4 forks source link

readme

IdentiHeart

Identicons are images typically generated from a user's id or hashed username, to create a default, unique image. IdentiHeart is a vanilla JavaScript library, that generates procedural, canvas-based, fun identicons! Oh, and it's also pretty fast, as in instant.

See it in action

Installation

Download or clone the IdentiHeart repository.

git clone https://github.com/Schlipak/IdentiHeart.git

You will get a folder, called dist, in which you can find the minified and unminified JavaScript source. Create an HTML document, include the script, and create a canvas element the size you want.

<!DOCTYPE html>
<html>
<head>
    <title>Hello IdentiHeart</title>
    <script type="text/javascript" src="https://github.com/Schlipak/IdentiHeart/raw/master/path/to/IdentiHeart/dist/identiheart.min.js"></script>
</head>
<body>
    <canvas id="myCanvas" height="500" width="500"></canvas>
</body>
</html>

Note: For a better render, you should use a 500*500 canvas element, then scale it to the desired size with CSS. Smaller size, typically lower than 300, may render the icon improperly. When using a different base canvas size, be sure to update the margin, scaling and stroke weight accordingly.

Usage

IdentiHeart gives you access to a class called IdentiHeart. The use is pretty simple and straight-forward.

var c = document.getElementById("myCanvas");
var ctx = c.getContext("2d");

var username = "Example";

var h = new IdentiHeart(c, ctx);
h.setUsername(username);
h.init();
h.draw();

This will generate the following image, inside the myCanvas element.

Methods

Constructor
IdentiHeart(canvas, [context, margin, scale])
Parameters
Return value

Constructs a new IdentiHeart object attached to the given canvas. Margins and scale factor can be optionally set to tweak the output.

setUsername
setUsername(string)
Parameters
Return value

Sets the value of the username or string to use while generating the IdentiHeart. The string is hashed automatically.

setPalette
setPalette(palette)
Parameters
Return value

Replaces the default palette used by the generator to color the IdentiHeart. The array must contain at least two colors. Colors can be represented as hex, rgb or html name.

setHasStroke
setHasStroke(b)
Parameters
Return value

Sets if the icon should be draw with a stroke. Optional, default true.

Example: setHasStroke(false);

setStrokeWeight
setStrokeWeight(weight)
Parameters
Return value

Sets the weight of the stroke. The value does not represent the final pixel size of the stroke but is merely a multiplication factor. Optional, default 500.

Example: setStrokeWeight(200);

setStrokeColor
setStrokeColor(color)
Parameters
Return value

Sets the color of the stroke. The value can be an HTML color name, or hex/rgb color value. Optional, default #000000.

Example: setStrokeColor('red');

setCompositeOperation
setCompositeOperation(operation)
Parameters
Return value

Sets the composite operation that will be used by the renderer to draw the icon. Optional, default multiply.
Valid values:

'source-over', 'source-in', 'source-out', 'source-atop', 'destination-over',
'destination-in', 'destination-out', 'destination-atop', 'lighter', 'copy',
'xor', 'multiply', 'screen', 'overlay', 'darken', 'lighten', 'color-dodge',
'color-burn', 'hard-light', 'soft-light', 'difference', 'exclusion', 'hue',
'saturation', 'color', 'luminosity'

Example: The IdentiHeart for the string Composite, rendered with the default composite operation and with color-burn.

Note: Strokes are excluded from the composite operations to avoid weird renders.

Note: Some of the composite operations are not implemented in all browsers. The default multiply operation, for example, does not work as of today in IE/Edge. This will result in IdentiHearts rendering differently depending on the user's browser.
To be exact, almost nothing will work as of today in IE/Edge. Come on, Microsoft!

setCanvas
setCanvas(canvas)
Parameters
Return value

Sets a new canvas on which the IdentiHeart will be drawn. The canvas context will be updated as well. This can be particularly useful when generating a great amount of different IdentiHearts on different target canvases, by allowing you to generate and draw them all using he same object, thus saving resources.

init
init()
Parameters

none

Return value

Initializes the IdentiHeart object and clears the canvas.

Note: Be sure to always call this function before drawing or refreshing the IdentiHeart. Without it, some parts of the icon might overlap the previously generated one.

draw
draw()
Parameters

none

Return value

Renders the computed IdentiHeart onto the attached canvas.