{"id":13851945,"url":"https://github.com/berlinonline/converjon","last_synced_at":"2025-07-13T03:32:52.008Z","repository":{"id":4063320,"uuid":"5167128","full_name":"berlinonline/converjon","owner":"berlinonline","description":"An advanced image conversion server and command line tool.","archived":true,"fork":false,"pushed_at":"2023-05-10T13:50:13.000Z","size":7654,"stargazers_count":53,"open_issues_count":0,"forks_count":8,"subscribers_count":13,"default_branch":"master","last_synced_at":"2024-08-05T22:37:07.911Z","etag":null,"topics":["aoi","conversion","convert-images","cropping","imagemagick","javascript","responsive-images"],"latest_commit_sha":null,"homepage":"http://berlinonline.github.io/converjon/","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/berlinonline.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null}},"created_at":"2012-07-24T15:07:52.000Z","updated_at":"2024-02-26T20:19:08.000Z","dependencies_parsed_at":"2023-07-06T13:46:22.018Z","dependency_job_id":null,"html_url":"https://github.com/berlinonline/converjon","commit_stats":{"total_commits":367,"total_committers":14,"mean_commits":"26.214285714285715","dds":"0.38419618528610355","last_synced_commit":"ace8c1b8ff0c3077919b73d3d7604c60a60f37f3"},"previous_names":[],"tags_count":48,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/berlinonline%2Fconverjon","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/berlinonline%2Fconverjon/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/berlinonline%2Fconverjon/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/berlinonline%2Fconverjon/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/berlinonline","download_url":"https://codeload.github.com/berlinonline/converjon/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":225855334,"owners_count":17534962,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["aoi","conversion","convert-images","cropping","imagemagick","javascript","responsive-images"],"created_at":"2024-08-04T22:00:50.058Z","updated_at":"2024-11-22T06:30:44.025Z","avatar_url":"https://github.com/berlinonline.png","language":"JavaScript","readme":"# Converjon\n\n**BEWARE: This repository is no longer maintained. It is archived. Big thank you to all contributors.** \n\n\u003chttp://berlinonline.github.io/converjon\u003e\n\nAn advanced image conversion server and command line tool.\n\n* [Features](#features)\n* [Dependencies](#dependencies)\n* [Installation](#installation)\n* [Running](#running)\n* [Usage](#usage)\n    * [Changing Size](#changing-size)\n    * [Area of Interest](#area-of-interest)\n    * [Cropping Mode](#cropping-mode)\n    * [Padding Color](#padding-color)\n    * [Cropping Mode](#cropping-mode)\n    * [Image format](#image-format)\n    * [Quality](#quality)\n    * [Color Palette](#color-palette)\n    * [Interlaced Images](#interlaced-images)\n    * [Presets](#presets)\n    * [Status Page](#status-page)\n* [Configuration](#configuration)\n    * [Server](#server)\n    * [Aliases](#aliases)\n    * [Downloads](#downloads)\n    * [Authentication](#authentication)\n    * [Cache](#cache)\n    * [Garbage Collector](#garbage-collector)\n    * [Processes](#processes)\n    * [Converter](#converter)\n    * [Cropping](#cropping)\n    * [Constraints](#constraints)\n    * [Logging](#logging)\n* [Testing](#testing)\n* [Contributing](#contributing)\n* [Changelog](#changelog)\n* [Copyright Notes](#copyright-notes)\n\n## Features\n\n* thumbnail generation\n* [responsive images](http://dev.opera.com/articles/responsive-images/)\n* intelligent cropping\n* [art direction use cases](http://usecases.responsiveimages.org/#art-direction)\n* adaptive image quality\n* no need to pre-generate different image sizes or versions\n\n## Dependencies\n\n* [ImageMagick](http://www.imagemagick.org/script/binary-releases.php)\n* [ExifTool](http://www.sno.phy.queensu.ca/%7Ephil/exiftool/install.html) (at least version 9)\n* [node.js and NPM](http://nodejs.org/download/)\n    * The [crypto module](https://nodejs.org/api/crypto.html) must be supported/included in the nodejs build\n\n## Installation\n\nUse NPM: ``npm install [-g] converjon``\n\nIf you want to prevent the fixed dependency versions of the ``npm-shrinkwrap.json`` file to be used on install use ``--no-shrinkwrap`` as a command line argument. See [shrinkwrap docs](https://docs.npmjs.com/cli/shrinkwrap) and [install docs](https://docs.npmjs.com/cli/install) for more information on this.\n\nConverjon follows [Semantic Versioning](http://semver.org/).\n\n## Running\n\nManually on commandline, as a system service or via docker.\n\n### Manually\n\nStart the server with `converjon [--config your_config_file]` or use the command line utility `converjon-cli` to work on local files.\n\n### Docker\n\n```sh\ndocker run -t -p 8000:8000 -v $(pwd)/config/default.yml:/etc/converjon/config.yml berlinonline/converjon:latest\n```\n\nor\n\n```sh\ndocker run -e USE_CONFIG_DIR=true -t -p 8000:8000 -v $(pwd)/config/:/etc/converjon/config berlinonline/converjon:latest\n```\n\n## Usage\n\nLet'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:\n\n    http://localhost/?url=%20http%3A%2F%2Fexample.org%2Fimage.jpg\n\nAnother alternative is to specify a file from the server's file system as the source. Instead of `url`, you can add the\n`file` parameter for this:\n\n    http://localhost/?file=foobar%3Asome%2Fdirectory%2Fimage.jpg\n\nThe `file` parameter is URL-encoded. In plain text it is `foobar:some/directory/image.jpg`.\n\nHere, `foobar` is the name of a filesystem alias followed by a colon and a relative path. See [Configuration: Aliases](#aliases) for more details.\n\nMore options are available as GET parameters. All parameters need to be URL encoded.\n\nSeveral examples are available on the `/demo` page which is enabled when starting Converjon with the [development config file](https://github.com/berlinonline/converjon/blob/master/config/development.yml) via ``converjon --dev``.\n\nIt's recommended to set the server port to `80` in [configuration](#server) and to run Converjon on a separate subdomain of your site or behind a reverse proxy like Nginx or Varnish.\n\nFor information on how to use the command line tool, run `conversion-cli --help`.\n\n### Changing size\n\nYou can either supply a `width`, `height` or both. If you only specify one dimension, the other one will be derived from the original image's aspect ratio.\n\nIf you set both values, the image may be cropped to the new aspect ratio and then resized to the requested pixel dimensions.\n\n### Area of Interest\n\n[Wiki: Area of Interest](https://github.com/berlinonline/converjon/wiki/Area-of-Interest)\n\nBy 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:\n\n    offsetX,offsetY,width,height\n\nThe 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.\n\nBy default, the AOI in the URL parameters has precedence over the one from the image's metadata. To prefer the embedded AOI from the metadata, set the `prefer_embedded_aoi` parameter to any non-empty value.\n\n### Cropping mode\n\nThe `crop` parameter sets the cropping mode. Available modes are:\n\n* `centered`\n* `aoi_coverage`\n* `aoi_emphasis`\n* `aoi_auto`\n\nDetails about the cropping modes can be found [here in the wiki](https://github.com/berlinonline/converjon/wiki/Cropping-Modes). For examples, see the [demo page](http://berlinonline.github.io/converjon/demo/demo.html).\n\nIf an AOI is set, cropping will ensure, that the area is always preserved.\n\n### Padding Color\n\nThe `padding_color` parameter sets the background color of the padding.\n\nThe color should be specified in an HTML URL Encoded format.\n\nIf none specified, the default color set in the configuration will be used.\n[see also Converter config](#converter)\n\n### Image Format\n\nWith the `format` parameter you can change the format of the image. Supported formats are:\n\n* `jpg` or `jpeg`\n* `png`\n* `gif`\n\nIf no specific format is requested, the format of the source image will be used.\n\n### Quality\n\nThe `quality` parameter sets the JPEG quality value. It ranges from `1` to `100`.\n\nThis parameter is ignored, if the requested format is not JPEG.\n\n### Color Palette\n\nThe `colors` parameter sets the number of colors for GIF compression. It ranges from 2 to 256 (integer).\n\n### Interlaced Images\n\nThe `interlace` parameter allows the creation of [interlaced images](http://en.wikipedia.org/wiki/Interlacing_(bitmaps)). Supported types of interlacing scheme are:\n\n* `plane`(try this for JPEGs)\n* `line`\n* `none`\n\nA well-known example of interlaced images are progressive JPEGs. You can use this option with PNGs and GIFs as well.\n\n### Presets\n\nThe `preset` parameter allows the automatic usage of a preset of parameters.\n\nNew presets may be added in the configuration files as follows:\n\n```YAML\npresets:\n  thumbnail:\n      format: \"jpg\"\n      quality: 50\n      width: 100\n      hight: 100\n```\n\nSo instead of specifying all the parameters in the URL:\n\n``?url=...\u0026width=100\u0026height=100\u0026format=jpg\u0026quality=50``\n\nyou can use the preset:\n\n``?url=...\u0026preset=thumbnail``\n\n### Removing Metadata\n\nThe `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.\n\n### Status Page\n\nThe URL `/status` leads to a summary of Converjon's current state and some statistics.\n\nThe status page is available as content type `application/json` via `/status.json`.\n\n## Configuration\n\nWhen 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:\n\n```sh\nconverjon --config conf_file1.yml --config conf_file2.json\n```\n\nTo load a directory containing one or more config file, use the `--config-dir` option. Config files will be added in the order they appear in that directory.\n\n```sh\nconverjon --config-dir /etc/converjon\n```\n\nYou can use the [default.yml](https://github.com/berlinonline/converjon/blob/master/config/default.yml) or [development.yml](https://github.com/berlinonline/converjon/blob/master/config/development.yml) file as an example for writing your own.\n\nThe default configuration format is YAML but you can also use JSON files.\n\nEvery configuration file matches 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. Config files without the `url` setting apply to all images.\n\nSome configuration are automatically converted:\n\n* \"true\" (string) is treated as `true`(bool)\n* \"false\" (string) is treated as `false`(bool)\n\n```yaml\n# this config will only apply to source URLs from localhost or flickr\nurls:\n  - \"http://localhost*\" #this will match URLs on localhost, this is the dev/testing default\n  - \"http://www.flickr.com*\"\n```\n\nConverjon uses [calmcard](https://github.com/lnwdr/calmcard) for string pattern matching. Documentation on how these patterns work can be found there.\n\nThis way you can define different settings depending on the source of the requested images.\n\n### Server\n\n```yaml\nserver:\n  port: 8000\n  instance_name: null\n  timeout: 20000\n  send_timeout: 2000 #time that sending the repsonse data may take.\n  access_log_format: \"combined\"\n  base_url_path: \"/\"\n  enable_load_test: false\n```\n\n* `server.port`: port for the server to listen on\n* `server.instance_name`: the name of this server that will be displayed on the status page\n\nIf not set, a random name will be generated.\n\n* `server.timout`: global timeout for incoming requests\n* `server.send_timeout`: the time streaming a finished image file into the HTTP response may take. This usually shouldn't need to be changed, except when the servers file system is expected to be exceptionally slow.\n* `server.base_url_path`: Normally, Converjon's image URL paths just start with `/`, like in `http://www.example.org/?url=...`\n\nYou can set a base path to have better control over the URLs that Converjon uses. If you want the image URLs too like `http://www.example.org/photos/?url=...` set the `base_url_path` to \"photos/\".\n\n* `server.access_log_format`: the formatting of access logs:\n    * `combined`: Apache Combined Log Format (the default)\n    * `short`: leaves out the date/time information. Use this, if you use other software for log handling that adds timestamps.\n\n### Downloads\n\n**URL whitelists**\n`download.url_whitelist` sets list of URL patterns that are allowed to be requested as image sources.\n\nFor 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.\n\n```yaml\n# this will only allow requests for images from URLs that match these patterns\ndownload:\n  url_whitelist:\n    - \"http://localhost*\"\n    - \"http://example.org/*\n```\n\n[Calmcard](https://github.com/lnwdr/calmcard) patterns are used for matching by default.\n\nYou can also prefix the pattern with ``~`` (like ``~ ^http://(foo|bar)\\.example.org\\/.*``) to use regular expressions. For most cases, this should not be necessary and is discouraged.\n\n**Timeout**\n`download.timeout` sets a timeout after which requests are cancelled, if the source server doesn't respond in time.\n\n**Reject Invalid SSL Certificates**\nSetting `download.rejectInvalidSSL` to `true` (default) will cause sources to be rejected, if their SSL certificates cannot be validated.\n\n### Aliases\n\nTo access the server's local filesystem for source images, you can specify \"aliases\":\n\n```yaml\n#example from the development configuration files:\nalias: dev\n\nbase_file_path: \"test/resources/images\"\n\nfallback_base_file_paths:\n  - \"test/resources/photos\"\n  - \"test/resources/misc\"\n\nheaders:\n  Cache-Control: \"max-age=5\"\n```\n\nWhen an image is requested with a `file` parameter (`\u003calias\u003e:\u003cpath\u003e`) instead of `url`, the `alias` part of that parameter is matched against the configuration files, just like with URLs but only the configs that have that **exact** alias will be used for that request.\n\nThere can only be one alias per config file. If you need multiple aliases, you need to have one config file for each of them. See [here](#configuration) on how to load multiple config files.\n\nIn a config file with an alias you can set a `base_file_path`. This is the directory where your source images are located. It is concatenated with the `path` part of the `file` parameter to point to the actual file. The `base_file_path` can be an absolute path or relative to the working directory of the server.\n\nAdditionally there can be multiple `fallback_base_file_paths`. If the requested file can't be found in the\n`base_file_path`, Converjon will try to find it in the first fallback path, then the second, and so on.\n\nIn addition, you can set HTTP headers that will be sent along with the converted image as if they had come from a source server.\n\n### Authentication\n\nConverjon 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.\n\n```YAML\nauthentication:\n  username: \"testuser\"\n  password: \"testpass\"\n```\n\n### Cache\n\n`cache.basepath` sets the base directory for the local file cache.\n\n```YAML\ncache:\n  base_path: \"/tmp/converjon/cache\"\n```\n\n`cache.copy_source_file` determines, if a source file should be copied, when you're using a local file as source. By\ndefault, files are copied into Converjon's cache directory. Set this to `false` to use the original file's location.\n*You will have to make sure that these files are not changed while Converjon is using them. This could result in corrupted images or failing requests.*\n\nThe cache directory is not automatically cleaned up and may grow over time.\n\n### Garbage Collector\n\nConverjon can clean up the cache directory automatically. By default this is disabled. It can be enabled with the\n`garbage_collector` config directives:\n\n```YAML\ngarbage_collector:\n  enabled: true\n  source: \"cache\"\n  target: \"immediate\"\n  interval: 5000\n```\n\n* `enabled`: turns the garbage collector on or off\n* `source`: determines when source files should be cleaned up. Possible values are:\n    * `cache`: The file will be removed when it's cache lifetime has expired\n    * `immediate`: The file will be removed as soon as it's no longer in use by any pending request.\n    * any other value will disable the cleanup for source files\n* `target`: same as `source` but for the converted target image files\n* `interval`: time between garbage collector runs, in milliseconds.\n\nLocal source files that were not copied into the cache directory will not be removed by the garbage collector.\n\n### Processes\n\n`process.limit` sets the maximum number of child processes that converjon will spawn for converting and analyzing images.\n\nIncreasing this will likely increase memory consumption while providing better usage of multiple CPU cores.\n\n### Converter\n\n* `converter.padding_color` sets the background color that is used, if an image needs padding to fit the requested aspect ratio.\n* `converter.filter` sets the filter, e.g. \"Sinc\"\n* `converter.quality` sets the quality of the resulting resized image (number, e.g. 85)\n\n### Cropping\n\n`cropping.default_mode` sets the default mode for cropping images. Possible options are: `centered`, `aoi_coverage`, `aoi_emphasis` and `aoi_auto`.\n\n[Wiki: Cropping Modes](https://github.com/berlinonline/converjon/wiki/Cropping-Modes)\n\n### Constraints\n\nConstraints can be used to limit the possible request parameters, like width and height of images. Every constraint has a `min` and a `max` value:\n\n```YAML\nconstraints:\n  quality:\n    min: 1\n    max: 100\n  colors:\n    min: 1\n    max: 256\n  width:\n    min: 1\n    max: 10000\n  height:\n    min: 1\n    max: 10000\n```\n\n### Logging\n\nThere are three logging levels: `access`, `error` and `debug`. Each of them can be directed to either STDOUT, STDERR or into a log file.\n\n```YAML\nlogging:\n  error: \"stderr\" # will log errors to STDERR\n  debug: \"stdout\" # will log debug logs to STDOUT\n  access: \"/var/log/access.log\" # will log requests into a log file\n```\n\nTo disable a log level, set it to `false`:\n\n```YAML\nlogging:\n  error: \"stderr\"\n  debug: false # \"false\" as a string will also work\n  access: \"/var/log/access.log\"\n```\n\nLogs are not automatically rotated. Use of a tool like `logrotate` is recommended.\n\n## Testing\n\nExecute tests with `npm test`. Please note, that you need to have all [dependencies](#dependencies) installed.\n\n## Contributing\n\nPlease contribute by [forking](http://help.github.com/forking/) and sending a [pull request](http://help.github.com/pull-requests/). More information can be found in the [`CONTRIBUTING.md`](CONTRIBUTING.md) file.\n\n## Changelog\n\nSee [`CHANGELOG.md`](CHANGELOG.md) for more information about changes.\n\n## Copyright Notes\n\nConverjon is [licensed under the MIT license](LICENSE).\n\nThe \"sparrow\" testing image is © Leon Weidauer, permission to use it for testing is granted.\n","funding_links":[],"categories":["📦 Legacy \u0026 Inactive Projects","JavaScript"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fberlinonline%2Fconverjon","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fberlinonline%2Fconverjon","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fberlinonline%2Fconverjon/lists"}