ecaptcha
=====

Simple [Captcha](https://en.wikipedia.org/wiki/CAPTCHA) image generator for Erlang.

Zero dependencies! Pixels are generated by tiny C NIF. GIF and PNG encoders are pure-Erlang.

Covered by property-based tests. No segfaults, no memory-leaks.

Based on [Ivan Tikhonov's captcha library](https://github.com/ITikhonov/captcha).

Usage
-----

Add `ecaptcha` as a dependency to your project's rebar.config:

```erlang
{deps, [ecaptcha]}.
```

Then use one of the API functions to generate the image and short random text:

```
{Phrase, PNGImage} = ecaptcha:png(5, [line, blur, filter, dots, reverse_dots], black).
```

`PNGImage` can be sent to the user with `Content-Type: image/png` and user have to guess
the 5-letter `Phrase` which is printed on the image.

There is a set of different effects which suppose to make it more difficult to recognize the
text with OCR systems:

* `line` - draws a curved horisontal line on top of the text
* `blur` - blurs the image (averages each pixel's color with it's neighbours)
* `filter` - makes letters hollow
* `dots` - draws 100 random 2x2 white dots on top of the image, effectively removing small patches
  from it
* `reverse_dots` - draws 20 random dots of a randomized size from 1 to 3px using a color opposite
  to the current color (so, reversing the color - black becomes white, white becomes black)

The more effects you apply, the more difficult it is to recognize the text on the image (for both
human and OCR).

Last argument is the image's color. It doesn't affect Captcha strength, but can be used to match
your website / app style. You can select from a set of predefined colors: `black`, `red`, `orange`,
`blue`, `pink` or `purple`, or it can be provided as a 3-tuple `{Red, Green, Blue}`, `0..255`.

```erlang
ecaptcha:gif/3
```

Same as `ecaptcha:png/3`, but returns the image encoded in GIF format. `Content-Type: image/gif`.

```erlang
{Phrase, Pixels} = ecaptcha:pixels(5, [line, blur, filter, dots, reverse_dots]).
```
`Phrase` is the same as above, but `Pixels` is a `200x70 = 14000` bytes binary of greyscale
pixels, from top-left to bottom-right, line-by-line. It can be used to, eg, display pixels with
JavaScript on a `<canvas>` etc.

Image encoders
--------------

This library also contains pure-erlang PNG and GIF image format encoders.
See [ecaptcha_gif.erl](src/ecaptcha_gif.erl) and [ecaptcha_png.erl](src/ecaptcha_png.erl).
Their current API is not really a generic-purpose, but the implementation is quite flexible, so,
code can be adopted to encode arbitrary images, not only Captchas.