Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/seriyps/ecaptcha

Zero-dependency Erlang library that generates captcha images
https://github.com/seriyps/ecaptcha

captcha erlang gif png

Last synced: 8 days ago
JSON representation

Zero-dependency Erlang library that generates captcha images

Awesome Lists containing this project

README 

        
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.



Flexible additional effects, multiple fonts, arbitrary colors, latin alphanumerics set of characters.



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:



```erlang

{Phrase, PNGImage} = ecaptcha:png(

    5,

    #{effects => [line, blur, filter, dots, reverse_dots],

      color => black,

      alphabet => latin_uppercase,

      font => <<"dejavusans">>}

).

```



`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.



`effects` option defines 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).



`color` option defines 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`.



`alphabet` defines the set of characters that can be printed on the image. It can be one of the

predefined sets: `numbers` for 0-9, `latin_lowercase` for a-z, `latin_uppercase` for A-Z or it

can be a binary containing all the allowed characters (duplicates are ok), eg `<<"1234abcd">>`.



`font` binary name of one of the supported fonts. Function `fonts/0` can be used to get the list of

available fonts. Fonts are pre-rendered at NIF compile-time, see the `c_src/fonts.h` and

`FONTS` parameter in `c_src/Makefile`.



All the options are optional.



```erlang

ecaptcha:gif/2

```



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



```erlang

{Phrase, Pixels} = ecaptcha:pixels(5, #{font => <<"ubuntu-r">>, alphabet => numbers}).

```

`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 `` etc. Options are the same as for `gif/2` or `png/2`, but `color` key

is obviously ignored.



```erlang

ecaptcha:fonts()

```



Returns a list of tuples containing information about each available font. Currently it's a 2-tuple

where 1st element is binary font name and 2nd element is binary containing all the characters of

the alphabet available for this font.



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.