h2non / node-imaginary

Minimalist node.js command-line & programmatic API client for imaginary

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.

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

• operations json|array - List of operations to run. See imaginary documentation for further details.

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

node-imaginary's Issues

You published to NPM without building.

There's no src folder in the node module, and there's no postinstall script. Since this was a patch release, this crashed our production environment.

Chaining operations

imaginary('image.jpg')
  .chain()
  .crop({ width: 100, height: 100 })
  .rotate(90)
  .on('error', function () { ... })
  .pipe('out.jpg')

Support API key

Unsupported Media Type

Hi!

I've been using this library with the imaginary server and for some images I get "415 Unsupported Media Type". If I make the call directly to the imaginary server everything works just fine.

If you want to test this behavior:

• imaginary server url: https://images.balloonas.com
• image url: https://s3.eu-central-1.amazonaws.com/dev.balloonas.images/gifts/birthday-gift/Süße-Sorgenfresser-Schlüsselanhänger-238656107506.jpg
• call that is made to node.js server: https://dev.balloonas.org/images/gifts/birthday-gift/SüßeSorgenfresser-Schlüsselanhänger/238656107506?size=600x600

Passing parameters to request

I would like to pass parameters to request such as timeout. Is this currently possible? I've had a few tries but can't seem to figure out how to do it.

Simple imaginary pool server balancing

Retry support

With configurable back-off logic

Support pipeline endpoint

Update to ES6 class syntax

How do you feel about this?

It would certainly improve readability.

Block-scoped declarations unsupported outside of strict mode

Hey there!

We run ES6 on our server, but let/const/function/class are not yet supported outside of strict mode on our node version (4.4.6, newest available for AWS Elastic Beanstalk). The most recent update broke our build when we updated to it.

Simple fix should be to add 'use strict'; to the top of the updated ES6 files.

Can't convert TIFF

Hi,

I deployed imaginary to a small heroku instance here: https://dan-test5.herokuapp.com

I can use it to convert JPEG, PNG, etc., fine, but have trouble with TIFF images. I'm just using the sample scripts from the README, so my code is just:

var fs = require('fs')
var imaginary = require('imaginary')
var serverUrl = 'https://dan-test5.herokuapp.com'

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

This produces a 415 from the server. Am I missing something obvious? Does the server need to be compiled with extra binaries for TIFF support? Thanks for any info.

Memory doesn't get reallocated on docker

hey guys,
after firing a simple request through the node client to thumbnail a 10 mb image on a docker container that runs imaginary, memory usage never gets reallocated.

my script:

for (let i=0; i<20; i++) {
    imaginary('img.jpg')
        .server(serverUrl)
        .thumbnail({ width: 1200 })
        .on('error', (err) => {
          console.error(`resizing image failed because of ${err}`)
    });
}

Dockerfile:

FROM h2non/imaginary

CMD ["imaginary", "-concurrency" , "1", "-http-cache-ttl", "0"]

versions:
imaginary: 1.0.15
bimg: 1.0.18
libvips: 8.6.3"
Docker: 18.06.1-ce

EDIT:
added for loop

Support for local images

Is it possible to send a request to process an image from a mount local to imaginary via this js client?

Can't execute versions 0.1.14 and 0.1.13

This version is not working. The latest working version is 0.1.12.

NodeJS Versions: 9.2.0 and 8.9.2

How to reproduce: npm i -g [email protected] && imaginary

Error output:

module.js:544
    throw err;
    ^

Error: Cannot find module '..'
    at Function.Module._resolveFilename (module.js:542:15)
    at Function.Module._load (module.js:472:25)
    at Module.require (module.js:585:17)
    at require (internal/module.js:11:18)
    at Object.<anonymous> (/home/victor/.nvm/versions/node/v9.2.0/lib/node_modules/imaginary/bin/imaginary:6:19)
    at Module._compile (module.js:641:30)
    at Object.Module._extensions..js (module.js:652:10)
    at Module.load (module.js:560:32)
    at tryModuleLoad (module.js:503:12)
    at Function.Module._load (module.js:495:3)

If you need any other information, I can provide, just ask :)