An advanced image conversion server and command line tool.
An advanced image conversion server and command line tool.
IMPORTANT: Converjon 2.0.0 has been released. For documentation on the previous version 1.8.x see here.
npm install [-g] converjon
Conversion follows Semantic Versioning.
Start the server with
converjon [--config your_config_file] or use the command line utility
converjon-cli to work on local files.
Let's say you have an image at
http://example.org/image.jpg. 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 examples are available on the
/demo page which is enabled when starting Converjon with the development config file via
It's recommended to set the server port to
80 in configuration and to run Converjon on a separate subdomain of your site or behind a reverse proxy like Nginx or Varnish.
You can either supply a
height or both. If you only specify one dimension, the other one will be derived from the original image's aspect ratio.
If you set both values, the image may be cropped to the new aspect ratio and then resized to the requested pixel dimensions.
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 following format:
The AOI can also be embedded in the original image's metadata via EXIF or IPTC. The name of this metadata field can be configured and defaults to
aoi. The request parameter overrides the AOI value from the image's metadata.
crop parameter sets the cropping mode. Available modes are:
If an AOI is set, cropping will ensure, that the area is always preserved.
padding_color parameter sets the background color of the padding.
The color should be specified in an HTML URL Encoded format.
If none specified, the default color set in the configuration will be used. see also Converter config
format parameter you can change the format of the image. Supported formats are:
If no specific format is requested, the format of the source image will be used.
quality parameter sets the JPEG quality value. It ranges from
This parameter is ignored, if the requested format is not JPG.
colors parameter sets the number of colors for GIF compression. It ranges from 2 to 256 (integer).
interlace parameter allows the creation of interlaced images. Supported types of interlacing scheme are:
plane(try this for JPEGs)
A well-known example of interlaced images are progressive JPEGs. You can use this option with PNGs and GIFs as well.
preset parameter allows the automatic usage of a preset of parameters.
New presets may be added in the configuration files as follows:
presets:thumbnail:format: "jpg"quality: 50width: 100hight: 100
strip_metadata option removes all metadata (e.g. EXIF, IPTC) from the converted images. This option has no value, it just needs to be present in the URL query parameters.
/status leads to a summary of Converjon's current state and some statistics.
The status page is available as content type
When launching converjon, you can specify one or more configuration files with the
--config option which can be set
multiple times to load multiple config files.
The default configuration format is YAML but you can also use JSON files.
Every configuration file can be matched only to certain image source URLs. If a config file contains a
urls setting, that configuration will only apply to URLs that match at least one of the patterns from that list:
# this config will only apply to source URLs from localhost or flickrurls:- "*" #this will match URLs on localhost, this is the dev/testing default- "*"
Converjon uses calmcard for string pattern matching. Documentation on how these patterns work can be found there.
This way you can define different setting depending on the source of the requested images.
server.port: port for the server to listen on
server.instance_name: the name of this server that will be displayed on the status page
server.timout: global timeout for incoming requests
If not set, a random name will be generated.
server.access_log_format: the formatting of access logs:
combined: Apache Combined Log Format (the default)
short: leaves out the date/time information. Use this, if you use other software for log handling that adds timestamps.
download.url_whitelist sets list of URL patterns that allowed to be requested as image sources.
For example, if you host your source images on
http://myimages.com/images/... you should set the whitelist pattern to
http://myimages.com/images/ to make sure other sources are not allowed.
# this will only allow requests for images from URLs that match these patternsdownload:url_whitelist:- "*"- "*
Calmcard patterns are used for matching by default.
You can also prefix the pattern with
~ ^http://(foo|bar)\.example.org\/.*) to use regular expressions. For most cases, this should not be necessary and is discouraged.
download.timeout sets a timeout after which requests are cancelled, if the source server doesn't respond in time.
Reject Invalid SSL Certificates
true will cause sources to be rejected, if their SSL certificates can nnot be validated.
Converjon supports HTTP basic authentication for image sources. If you include authentication credentials in a URL specific configuration file, they will be sent along with every request to URLs that match the URL pattern of that configuration file.
authentication:username: "testuser"password: "testpass"
cache.basepath sets the base directory for the local file cache.
The cache directory is not automatically cleaned up and may grow over time.
process.limit sets the maximum number of child processes that converjon will spawn for converting and analyzing images.
converter.padding_color sets the background color that is used, if an image needs padding to fit the requested aspect ratio.
cropping.default_mode sets the default mode for cropping images. Possible options are:
Constraints can be used to limit the possible request parameters, like width and height of images. Every constraint has a
min and a
constraints:quality:min: 1max: 100colors:min: 1max: 256width:min: 1max: 10000height:min: 1max: 10000
There are three logging levels:
debug. Each of them can be directed to either STDOUT, STDERR or into a log file.
logging:error: "stderr" # will log errors to STDERRdebug: "stdout" # will log debug logs to STDOUTaccess: "/var/log/access.log" # will log requests into a log file
To disable a log level, set it to
Logs are not automatically rotated. Use of a tool like
logrotate is recommended.
Execute tests with
npm test. Please note, that you need to have all dependencies installed and must have run
npm install first.
CHANGELOG.md for more information about changes.
Converjon is licensed under the MIT license.
The "sparrow" testing image is © Leon Weidauer, permission to use it for testing is granted.