Home

Awesome

node-imaginary Build Status NPM version Code Climate js-standard-style

Minimalist node.js CLI & programmatic stream capable interface for imaginary server.

Supports multiple image operations such as resize, crop, zoom, watermark, rotate... and both local and remote URL based image source processing, and additionally provides a simple balancing feature to use multiple imaginary servers.

To get started take a look to the command-line usage and programmatic API

Installation

For command-line usage, install it as global package:

npm install -g imaginary

For programmatic usage, install it in the tree dependency:

npm install imaginary --save[-dev]

Command-line interface

$ imaginary --help

Usage: imaginary [options] [command]

Commands:

  crop [options] [image]       Crop any image in order to fit the given width or height pixels
  smartcrop [options] [image]  Smart crop any image in order to fit the given width or height pixels. Requires imaginary v1.0.8+
  resize [options] [image]     Resize the image to the given width or height in pixels
  embed [options] [image]      Embed the image to the given width or height in pixels
  enlarge [options] [image]    Enlarge the image to the given width and height in pixels
  extract [options] [image]    Extract area from an image by top/left and width/height
  rotate [options] [image]     Rotate the image by degrees
  flip [options] [image]       Flip an image
  flop [options] [image]       Flop an image
  zoom [options] [image]       Zoom the image to the given width or height in pixels
  watermark [options] [image]  Add a text watermark in the image
  pipeline [options] [image]   Pipeline processing based on a JSON file transformation. Requires imaginary v1.0.8+
  info [options] [image]       Retrieve image information as JSON

Options:

  -h, --help     output usage information
  -V, --version  output the version number

Examples:

  $ imaginary crop -w 300 -h 260 -o out.jpg image.jpg
  $ imaginary smartcrop -w 300 -h 260 -o out.jpg image.jpg
  $ imaginary pipeline -j operations.json -o out.jpg image.jpg
  $ imaginary resize -w 300 -o out.jpg http://server.net/image.jpg
  $ imaginary zoom -f 2 -w 300 -o out.jpg http://server.net/image.jpg
  $ imaginary watermark --text "copyright" -o out.jpg http://server.net/image.jpg

API

imaginary(image, [imaginaryUrl])

Constructor of the imaginary client

Take an image from disk:

var fs = require('fs')
var imaginary = require('imaginary')
var serverUrl = 'http://imaginary.company.net'

imaginary('image.jpg')
  .server(serverUrl)
  .crop({ width: 200, height: 200 })
  .on('error', function (err) {
    console.error('Cannot resize the image:', err)
  })
  .pipe(fs.createWriteStream('out.jpg'))

Take an image from remote URL (will stream it from the client to the server):

imaginary('http://myhosting.com/image.jpg')
  .server('http://imaginary.server.net')
  .crop({ width: 800, height: 600 })
  .on('error', function (err) {
    console.error('Cannot resize the image:', err)
  })
  .pipe(fs.createWriteStream('out.jpg'))

Take an image as readable stream:

imaginary(fs.createReadStream('image.jpg'))
  .server('http://imaginary.server.net')
  .rotate({ rotate: 180 })
  .on('error', function (err) {
    console.error('Cannot resize the image:', err)
  })
  .pipe(fs.createWriteStream('out.jpg'))

Resize by URL without streaming it on the client first. Requires passing the -enable-url-source flag to imaginary.

imaginary()
  .server('http://imaginary.server.net')
  .rotate({ rotate: 180, url: 'http://placehold.it/350x150' })
  .on('error', function (err) {
    console.error('Cannot resize the image:', err)
  })
  .pipe(fs.createWriteStream('out.jpg'))

Supported params

See the full list of supported query params here.

Take a look to each specific endpoint to see which specific params are supported or not. Image measures are always in pixels, unless otherwise indicated.

imaginary#key(key) -> this

Define the API key required by the imaginary server (optional).

imaginary#server(url [, httpOptions]) -> this

Define the imaginary server URL.

imaginary#balance(urls [, httpOptions]) -> this

Define a list of imaginary server URLs to balance load.

imaginary#httpParams(options) -> this

Optionally declare request HTTP client options to be used.

imaginary#image(image) -> this

Pass the image path, image URL or ReadableStream to the image file

imaginary#imageUrl(url) -> this

Pass the image URL to process.

Note: you must start your imaginary server with the -enable-url-source flag in order to use this feature.

Balance between a pool of imaginary server URLs

imaginary#params(params, [ callback ]) -> this

Defines shared global URL query params used across imaginary HTTP API calls.

imaginary#crop(params, [ callback ]) -> Promise

Crop an image in order to fit the given width, height or both.

imaginary#smartcrop(params, [ callback ]) -> Promise

Note: requires imaginary v1.0.8+.

Smart crop an image in order to fit the given width, height or both.

Uses built-in smart cropping algorithm in imaginary.

imaginary#resize(params, [ callback ]) -> Promise

Resize an image by width, height or both.

imaginary#enlarge(params, [ callback ]) -> Promise

Enlarge an image by width and/or height

imaginary#extract(params, [ callback ]) -> Promise

Extract image area by top/left and width/height pixels

imaginary#expand(params, [ callback ]) -> Promise

Resize any image to a given height in pixels.

imaginary#zoom(params, [ callback ]) -> Promise

Zoom an image by the given height in pixels.

imaginary#rotate(params, [ callback ]) -> Promise

Rotate an image to a given degrees (must be multiple of 90)

imaginary#flip(params, [ callback ]) -> Promise

Flip an image

imaginary#flop(params, [ callback ]) -> Promise

Flop an image

imaginary#watermark(params, [ callback ]) -> Promise

Add a watermark to an image

imaginary#thumbnail(params, [ callback ]) -> Promise

Thumbnail an image with a given width or height

imaginary#pipeline(operations, [ params, callback ]) -> Promise

Note: requires imaginary v1.0.8+.

Pipeline processing a given image performing multiple independent image transformations as sort of map-reduce pattern in serie.

You can see a programmatic usage example here.

For an example JSON of pipeline operations, see examples/operations.json

Required params

imaginary#info([ callback ]) -> Promise

Get the metadata info of the image as JSON

imaginary#health([ callback ]) -> Promise

Retrieve server health status

imaginary#versions([ callback ]) -> Promise

Retrieve imaginary, bimg and libvips versions

imaginary.VERSION

Get the current module version

License

MIT © Tomas Aparicio