node-imaginary
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.
this
imaginary#key(key) -> Define the API key required by the imaginary server (optional).
this
imaginary#server(url [, httpOptions]) -> Define the imaginary server URL.
this
imaginary#balance(urls [, httpOptions]) -> Define a list of imaginary server URLs to balance load.
this
imaginary#httpParams(options) -> Optionally declare request HTTP client options to be used.
this
imaginary#image(image) -> Pass the image path, image URL or ReadableStream
to the image file
this
imaginary#imageUrl(url) -> 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
this
imaginary#params(params, [ callback ]) -> Defines shared global URL query params used across imaginary
HTTP API calls.
Promise
imaginary#crop(params, [ callback ]) -> Crop an image in order to fit the given width
, height
or both.
Promise
imaginary#smartcrop(params, [ callback ]) -> 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
.
Promise
imaginary#resize(params, [ callback ]) -> Resize an image by width, height or both.
Promise
imaginary#enlarge(params, [ callback ]) -> Enlarge an image by width and/or height
Promise
imaginary#extract(params, [ callback ]) -> Extract image area by top/left and width/height pixels
Promise
imaginary#expand(params, [ callback ]) -> Resize any image to a given height in pixels.
Promise
imaginary#zoom(params, [ callback ]) -> Zoom an image by the given height in pixels.
Promise
imaginary#rotate(params, [ callback ]) -> Rotate an image to a given degrees (must be multiple of 90)
Promise
imaginary#flip(params, [ callback ]) -> Flip an image
Promise
imaginary#flop(params, [ callback ]) -> Flop an image
Promise
imaginary#watermark(params, [ callback ]) -> Add a watermark to an image
Promise
imaginary#thumbnail(params, [ callback ]) -> Thumbnail an image with a given width or height
Promise
imaginary#pipeline(operations, [ params, callback ]) -> 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
- operations
json|array
- List of operations to run. See imaginary documentation for further details.
Promise
imaginary#info([ callback ]) -> Get the metadata info of the image as JSON
Promise
imaginary#health([ callback ]) -> Retrieve server health status
Promise
imaginary#versions([ callback ]) -> Retrieve imaginary, bimg and libvips versions
imaginary.VERSION
Get the current module version
License
MIT ยฉ Tomas Aparicio