An on-the-fly image conversion service

npm install converjon
2 downloads in the last week
7 downloads in the last month


An on-the-fly image conversion service

Dependencies (apart from node modules) -

  • ImageMagick
    • use the Q8 version to save memory
    • however, Q16 (the default one) is required to support PNG image output
  • ExifTool (at least version 9)
  • node.js
  • NPM (usually included in node.js)

Installation -

  • download or clone the repository
  • change into the directory of the repository
  • npm install -d to install the dependency libs
  • set your environment (production/development/testing) via the NODE_ENV environment variable (defaults to "development")
  • start with npm start

    There are some optional OS specific start/stop scripts under utils/os_helpers/ which you can also use.

Configuration -


  • port: port for the server to listen on


  • errorLog: Absolute path to error log file.
  • accessLog: Absolute path to access log file.
  • error (boolean): wether to log errors at all.
  • debug (boolean): wether to log debug output (this may be A LOT)
  • access (boolean): wether to log client requests (Apache style)


Image requests can be constrained within configurable boundaries. This can be done globally and for regular expressions matching source URLs. If a request exceeds these limits, an HTTP 400 is returned with a notice, what went wrong.

Currently there are 4 possible constraints:

  • width
  • height
  • quality (meaning JPEG quality)
  • color (meaning GIF color depth)

Each of these values can have a max and a min property. Both are optional. You can also specify just one boundary.

Example from config/default.json:

    "constraints": {
        "global": {
            "width": {
                "min": 1,
                "max": 2000
            "height": {
                "min": 1,
                "max": 2000
            "quality": {
                "min": 1,
                "max": 95
            "colors": {
                "min": 2,
                "max": 256
        "url": {
            "^.+:\/\/localhost": {
                "quality": {
                    "max": 100,
                    "min": 20
// ...

This example includes some global contraints that apply to every request and some overridden contraints for request with aource URLs from localhost.

Usage -

Example image URL:

To get the image through Converjon, put the original URL into the request as a URL encoded parameter:


More options are available as GET parameters. All parameters need to be URL encoded.

Several example are available on the /demo page which is enabled in "testing" and "development" environments.

Changing size

You can either supply a width, height or both. If you only supply one dimension, the other one will be derived from the original images aspect ratio.

If you supply both values, the image will be cropped to the new aspect ratio, if necessary, and is then resized to the requested pixel dimensions.

Area of Interest

By default images are cropped from the center of the original. You can specify an "area of interest" with the aoi parameter. The AOI is a rectangle in the folling format:


The AOI can also be embedded in the original images metadata via EXIF or IPTC. The name of this metadata field can be configured and defaults to aoi. If the images metadata specifies an AOI, it is preferre over the AOI in the GET parameter.

If an AOI is set, croppping will ensure, that the area is always preserved.

Image Format

With the mime parameter you can change the format of the image. Supported types are:

  • image/jpeg
  • image/png
  • image/gif


The quality parameter sets the JPEG quality value. It ranges from 1 to 100 (integer).

This parameter is ignored, if the requested mime type is not image/jpeg.

Color Palette

The colors parameter sets the number of colors for GIF compression. It ranges from 2 to 256 (integer).

Testing -

  • Execute tests with npm test

Copyright notes - The "sparrow" testing image is © Leon Weidauer, permission to use it for testing is granted.

npm loves you