Erlang Image Manipulation Process
=================================

`eimp` is an Erlang/Elixir application for manipulating graphic images using
external C libraries. Currently it supports convertation between WebP, JPEG and PNG.

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

# 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
```erl
-spec convert(In :: binary(), Format :: png|jpeg|webp) -> {ok, Out :: binary()} |
                                                          {error, Reason :: error_reason()}.
```

Shorthand for `convert(In, Format, 30000)` (that is, the default timeout is
30 seconds).

### convert/3
```erl
-spec convert(In :: binary(), Format :: png|jpeg|webp, Timeout :: non_neg_integer()) ->
                   {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 `Timeout` should be provided in _milliseconds_. Also note, that you cannot
use `infinity` or `unlimited` as a value for `Timeout`.
**WARNING**: the maximum resolution of an incoming image is hardcoded to be 25Mpx.
This is a protection against decompression bombs.

### format_error/1
```erl
-spec format_error(Reason :: error_reason()) -> binary().
```
Creates diagnostic text from an error generated by `convert/2`.
The `Reason` can have the following values:
```erl
-type error_reason() :: unsupported_format |
                        timeout |
                        disconnected |
                        encode_failure |
                        decode_failure.
```

### get_type/1
```erl
-spec get_type(Data :: binary()) -> png | jpeg | webp | unknown.
```
Detects image format of `Data`.