Erlang Image Manipulation Process

eimp is an Erlang/Elixir application for manipulating graphic images using external C libraries. It supports WebP, JPEG, PNG and GIF.

Requirements

• GNU Make
• GCC
• Erlang/OTP 17 and higher
• libgd
• libwebp
• libpng
• libjpeg

NOTE: It's hard to say which versions of the C libraries are required, but it seems like not too old versions should work well.

Install

$ ./configure
$ make

Note that running the configure script is highly recommended, so you should consider adding it in pre-hooks of your rebar configuration.

If no C libraries are found at compile time, the package will still be compiled. In this case the only usable function would be get_type/1.

Application design

The C code is compiled into external native binary called eimp, which is connected to Erlang VM using an external port. This is done because used C libraries are known not to be extremely stable, thus, if you wrap them into the emulator using a driver or NIF, they can crash the whole emulator.

When being loaded, the application starts a single eimp process per CPU core and uses a round-robin pool to schedule tasks to them. Simple recovery mechanisms are also supported:

• if a request to eimp process has failed, next eimp process in the pool is picked, until the pool is exhausted
• if an eimp process is dead, it will be restarted automatically
• an eimp process is protected against decompression bombs

Usage

Before using the application you should start it with either eimp:start() or application:start(eimp).

API

Current API is simple and supports only a few functions:

convert/2

-spec convert(In :: binary(), Format :: png|jpeg|webp|gif) -> {ok, Out :: binary()} |
                                                              {error, Reason :: error_reason()}.

Shorthand for convert(In, Format, []).

convert/3

-spec convert(In :: binary(), Format :: png|jpeg|webp|gif,
              Options :: [convert_opt() | limit_opt()]) ->
                   {ok, Out :: binary()} |
                   {error, Reason :: error_reason()}.

The function converts incoming data In into format Format. Note that you don't have to pass the format of incoming data, becasue it will be detected automatically using get_type/1 function. In the case of an error you can use Reason to produce a human-readable diagnostic text using format_error/1. The function also accepts a proplist of Options. Currently available options are:

• {scale, {Width, Height}}: scales image to the new Width and Height. No scaling is applied by default.
• {rate_limit, N}: limit the number of calls to N per minute, where N > 0. Must be used only in conjunction with limit_by.
• {limit_by, Term}: apply rate_limit (see above) to the entity associtated with Term. The Term may represent any value, such as an IP address, a username and so on. The Term must not be atom undefined. For example a call to convert(Data, Format, [{limit_by, {192,168,0,1}}, {rate_limit, 10}]) will fail with {error, too_man_requests} if called more than 10 times within a minute.

WARNING: the maximum resolution of an incoming image is hardcoded to be 25Mpx. This is a protection against decompression bombs.

identify/1

-spec identify(Img :: binary()) -> {ok, Info :: info()} | {error, error_reason()}.

Shorthand for identify(Img, []).

identify/2

-spec identify(Img :: binary(), LimitOptions :: [limit_opt()]) ->
                    {ok, Info :: info()} | {error, error_reason()}.

The function returns information about image Img, where Info is represented as:

[{type, Type :: img_type()},
 {width, Width :: non_neg_integer()},
 {height, Height :: non_neg_integer()}]

It is safe to assume that Info always contains all these properties. You can set limiting options in LimitOptions, that is rate_limit and limit_by. The meaning of the limiting options is the same as in convert/3.

NOTE: If you only need to get a type of an image, you're better off using get_type/1 function, because it doesn't involve interaction with eimp process and is, thus, much faster.

format_error/1

-spec format_error(Reason :: error_reason()) -> binary().

Creates diagnostic text from an error generated by convert/2. The Reason can have the following values:

-type error_reason() :: unsupported_format |
                        timeout |
                        disconnected |
                        encode_failure |
                        decode_failure |
			transform_failure |
			too_many_requests |
			image_too_big.

get_type/1

-spec get_type(Data :: binary()) -> png | jpeg | webp | gif | unknown.

Detects image format of Data.

is_supported/1

-spec is_supported(Format :: atom()) -> boolean.

Returns true if Format is known and compiled and false otherwise.

supported_formats/0

-spec supported_formats() -> [png | jpeg | webp | gif].

Returns a list of all known and compiled formats.