Couchmagick runs ImageMagicks convert on CouchDB documents. Reliable.
JavaScript
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
lib
.gitignore
README.md
index.js
package.json

README.md

Couchmagick

Run ImageMagicks convert on CouchDB documents.

Couchmagick runs as an os_daemon, which means that CouchDB manages the process and you can configure it using CouchDBs configuration mechanism, which is both a huge win.

Versions and commandline arguments which are passed to convert are defined in design documents under a couchmagick section.

Couchmagicks couch-daemon stream based implementation provides low memory footprint.

Installation

The installation of Couchmagick is dead simple.

Make sure you have ImageMagick installed, eg on Debian:
apt-get install imagemagick

Install Couchmagick via npm:
npm install couchmagick -g

Commandline Client

You can run Couchmagick from the commandline:

couchmagick

The options explained above can be given as commandline parameters (prefixed with --) or environment variables (UPPERCASED).

couchmagick --username bernd --password secure --whitelist projects --concurrency 8 --timeout 1000

Daemon Configuration

Add Couchmagick to os_daemons config section (eg. in local.ini):

[os_daemons]
couchmagick = couchmagick

Now CouchDB takes care of the Couchmagick process.

[couchmagick]
; Optional username and password, used by the workers to access the database.
; Default is null.
username = bernd
password = secure
; Concurrency level (number of simultanous convert processes per stream). Default is 1.
; this should be set to the number of cores of your cpu for optimum performance, but
; it really depends on the number of databases and their usage patterns.
concurrency = 1
; Timeout for a convert process in ms. Default is 60000 (1min). This should be plenty
; for the usual image resizes, increase it if you deal with really large images and complex
; imagemagick processing.
timeout = 60000
; Only documents in the databases below are processed (separate with comma).
; Regular expressions are allowed:
;whitelist = mydb,otherdb,/^special-.*/
; Ignore the following databases (again comma separated list)
; Regular expressions are again allowed:
blacklist = /^_/
; Only attachments which match any of the mime types below are processed (separate with comma).
; Default is /^image\// Regular expressions are allowed:
;source_content_types = /^image\//,application/postscript

Imagemagick Configuration

Add a couchmagick property to a design document. Couchmagick will process all databases which have such a design document.

Minimal Example

{
  "_id": "_design/minimal-couchmagick-config",
  "_rev": "1-a653b27246b01cf9204fa9f5dee7cc64",
  "couchmagick": {
    "versions": {
      "thumbnail": {
        "args": [
          "-resize", "x100"
        ]
      }
    }
  }
}

filter

There are two kinds of filters which you can define: one operates on doc level and one on version level.

Document Filter

This filter is called with one argument: document.

Version Filter

This filter is called with two arguments, document and attachment name.

content_type

Content-Type of the resulting attachment. Default is image/jpeg.

id

The document id where the version is stored. Defaults to {id}/{version}.

Can have the following strformat placeholders:

  • id - the original doc id
  • parts - array of the id splitted at /
  • docuri - docuri parsed id object:
    • docuri.type - index part of docuri
    • docuri.id - id part of docuri
    • docuri.subtype - subtype part of docuri
    • docuri.version - version part of docuri
    • docuri.index - index part of docuri
  • version - name of the version

name

The attachment name of the version. Default is {basename}-{version}{extname}.

Can have placeholders:

  • id - the original doc id
  • parts - array of the id splitted at /
  • docuri - docuri parsed id object:
    • docuri.type - index part of docuri
    • docuri.id - id part of docuri
    • docuri.subtype - subtype part of docuri
    • docuri.version - version part of docuri
    • docuri.index - index part of docuri
  • version - name of the version
  • name - original attachment name, eg this/is/my-image.jpg
  • extname - file extenstion of the original attachment name, eg .jpg
  • basename - basename without extension, eg my-image
  • dirname - directory name, eg this/is
  • version - name of the version

args

Array of argument strings for ImageMagicks convert.

The default is ['-', 'jpg:-'], which means that ImageMagick converts the image to jpg. You can see that we use convert with pipes for in- and output.

See ImageMagick Convert Command-line Tool for a comprehensive list of options.

Advanced Example

{
  "_id": "_design/advanced-couchmagick-config",
  "_rev": "1-0b42e71d7b179c7e44a436704e4fd8e3",
  "couchmagick": {
    "filter": "function(doc) { return doc.type === 'post'; }",
    "versions": {
      "medium": {
        "id": "{id}-{version}",
        "name": "{basename}/{version}{extname}",
        "args": [
          "-resize", "800x600",
          "-quality", "75",
          "-colorspace", "sRGB",
          "-strip"
        ]
      },
      "large": {
        "filter": "function(doc, name) { return name.match(/^header/); }",
        "id": "{id}-header",
        "name": "header/large.jpg",
        "args": [
          "-quality", "75",
          "-unsharp", "0",
          "-colorspace", "sRGB",
          "-interlace", "Plane",
          "-strip",
          "-density", "72",
          "-resize", "960x320^",
          "-gravity", "center",
          "-crop", "960x320+0+0", "+repage"
        ]
      }
    }
  }
}

License

Copyright (c) 2012-2014 Johannes J. Schmidt, null2 GmbH
Licensed under the MIT license.