{"id":15439684,"url":"https://github.com/h2non/node-imaginary","last_synced_at":"2025-05-08T21:43:48.909Z","repository":{"id":30270059,"uuid":"33821506","full_name":"h2non/node-imaginary","owner":"h2non","description":"Minimalist node.js command-line \u0026 programmatic API client for imaginary ","archived":false,"fork":false,"pushed_at":"2018-11-18T18:49:03.000Z","size":107,"stargazers_count":109,"open_issues_count":2,"forks_count":11,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-05-08T21:43:43.020Z","etag":null,"topics":["client-library","crop","image-manipulation","image-processing","imaginary","resize","resize-images","watermark-image"],"latest_commit_sha":null,"homepage":"https://github.com/h2non/imaginary","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/h2non.png","metadata":{"files":{"readme":"README.md","changelog":"History.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2015-04-12T15:09:03.000Z","updated_at":"2025-02-19T10:33:14.000Z","dependencies_parsed_at":"2022-07-14T18:00:30.608Z","dependency_job_id":null,"html_url":"https://github.com/h2non/node-imaginary","commit_stats":null,"previous_names":[],"tags_count":16,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/h2non%2Fnode-imaginary","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/h2non%2Fnode-imaginary/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/h2non%2Fnode-imaginary/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/h2non%2Fnode-imaginary/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/h2non","download_url":"https://codeload.github.com/h2non/node-imaginary/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253153888,"owners_count":21862424,"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":["client-library","crop","image-manipulation","image-processing","imaginary","resize","resize-images","watermark-image"],"created_at":"2024-10-01T19:08:42.198Z","updated_at":"2025-05-08T21:43:48.891Z","avatar_url":"https://github.com/h2non.png","language":"JavaScript","readme":"# node-imaginary [![Build Status](https://api.travis-ci.org/h2non/node-imaginary.svg?branch=master)][travis] [![NPM version](https://badge.fury.io/js/imaginary.svg)][npm] [![Code Climate](https://codeclimate.com/github/h2non/node-imaginary/badges/gpa.svg)](https://codeclimate.com/github/h2non/node-imaginary) [![js-standard-style](https://img.shields.io/badge/code%20style-standard-brightgreen.svg)](http://standardjs.com)\n\nMinimalist node.js CLI \u0026 programmatic stream capable interface for [imaginary](https://github.com/h2non/imaginary) server.\n\nSupports 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.\n\nTo get started take a look to the [command-line usage](#cli) and programmatic [API](#api)\n\n## Installation\n\nFor command-line usage, install it as global package:\n```bash\nnpm install -g imaginary\n```\n\nFor programmatic usage, install it in the tree dependency:\n```bash\nnpm install imaginary --save[-dev]\n```\n\n## Command-line interface\n\n```bash\n$ imaginary --help\n```\n\n```bash\nUsage: imaginary [options] [command]\n\nCommands:\n\n  crop [options] [image]       Crop any image in order to fit the given width or height pixels\n  smartcrop [options] [image]  Smart crop any image in order to fit the given width or height pixels. Requires imaginary v1.0.8+\n  resize [options] [image]     Resize the image to the given width or height in pixels\n  embed [options] [image]      Embed the image to the given width or height in pixels\n  enlarge [options] [image]    Enlarge the image to the given width and height in pixels\n  extract [options] [image]    Extract area from an image by top/left and width/height\n  rotate [options] [image]     Rotate the image by degrees\n  flip [options] [image]       Flip an image\n  flop [options] [image]       Flop an image\n  zoom [options] [image]       Zoom the image to the given width or height in pixels\n  watermark [options] [image]  Add a text watermark in the image\n  pipeline [options] [image]   Pipeline processing based on a JSON file transformation. Requires imaginary v1.0.8+\n  info [options] [image]       Retrieve image information as JSON\n\nOptions:\n\n  -h, --help     output usage information\n  -V, --version  output the version number\n\nExamples:\n\n  $ imaginary crop -w 300 -h 260 -o out.jpg image.jpg\n  $ imaginary smartcrop -w 300 -h 260 -o out.jpg image.jpg\n  $ imaginary pipeline -j operations.json -o out.jpg image.jpg\n  $ imaginary resize -w 300 -o out.jpg http://server.net/image.jpg\n  $ imaginary zoom -f 2 -w 300 -o out.jpg http://server.net/image.jpg\n  $ imaginary watermark --text \"copyright\" -o out.jpg http://server.net/image.jpg\n```\n\n## API\n\n### imaginary(image, [imaginaryUrl])\n\nConstructor of the imaginary client\n\nTake an image from disk:\n```js\nvar fs = require('fs')\nvar imaginary = require('imaginary')\nvar serverUrl = 'http://imaginary.company.net'\n\nimaginary('image.jpg')\n  .server(serverUrl)\n  .crop({ width: 200, height: 200 })\n  .on('error', function (err) {\n    console.error('Cannot resize the image:', err)\n  })\n  .pipe(fs.createWriteStream('out.jpg'))\n```\n\nTake an image from remote URL (will stream it from the client to the server):\n```js\nimaginary('http://myhosting.com/image.jpg')\n  .server('http://imaginary.server.net')\n  .crop({ width: 800, height: 600 })\n  .on('error', function (err) {\n    console.error('Cannot resize the image:', err)\n  })\n  .pipe(fs.createWriteStream('out.jpg'))\n```\n\nTake an image as readable stream:\n```js\nimaginary(fs.createReadStream('image.jpg'))\n  .server('http://imaginary.server.net')\n  .rotate({ rotate: 180 })\n  .on('error', function (err) {\n    console.error('Cannot resize the image:', err)\n  })\n  .pipe(fs.createWriteStream('out.jpg'))\n```\n\nResize by URL without streaming it on the client first.\nRequires passing the `-enable-url-source` flag to `imaginary`.\n```js\nimaginary()\n  .server('http://imaginary.server.net')\n  .rotate({ rotate: 180, url: 'http://placehold.it/350x150' })\n  .on('error', function (err) {\n    console.error('Cannot resize the image:', err)\n  })\n  .pipe(fs.createWriteStream('out.jpg'))\n```\n\n### Supported params\n\nSee the full list of supported query params [here](https://github.com/h2non/imaginary#params).\n\nTake a look to each specific endpoint to see which specific params are supported or not.\nImage measures are always in pixels, unless otherwise indicated.\n\n#### imaginary#key(key) -\u003e `this`\n\nDefine the API key required by the imaginary server (optional).\n\n#### imaginary#server(url [, httpOptions]) -\u003e `this`\n\nDefine the imaginary server URL.\n\n#### imaginary#balance(urls [, httpOptions]) -\u003e `this`\n\nDefine a list of imaginary server URLs to balance load.\n\n#### imaginary#httpParams(options) -\u003e `this`\n\nOptionally declare [request HTTP client](https://github.com/request/request#requestoptions-callback) options to be used.\n\n#### imaginary#image(image) -\u003e `this`\n\nPass the image path, image URL or `ReadableStream` to the image file\n\n#### imaginary#imageUrl(url) -\u003e `this`\n\nPass the image URL to process.\n\n**Note**: you must start your imaginary server with the `-enable-url-source` flag in order to use this feature.\n\nBalance between a pool of imaginary server URLs\n\n#### imaginary#params(params, [ callback ]) -\u003e `this`\n\nDefines shared global URL query params used across `imaginary` HTTP API calls.\n\n#### imaginary#crop(params, [ callback ]) -\u003e `Promise`\n\nCrop an image in order to fit the given `width`, `height` or both.\n\n#### imaginary#smartcrop(params, [ callback ]) -\u003e `Promise`\n\n**Note**: requires `imaginary` v1.0.8+.\n\nSmart crop an image in order to fit the given `width`, `height` or both.\n\nUses built-in smart cropping algorithm in `imaginary`.\n\n#### imaginary#resize(params, [ callback ]) -\u003e `Promise`\n\nResize an image by width, height or both.\n\n#### imaginary#enlarge(params, [ callback ]) -\u003e `Promise`\n\nEnlarge an image by width and/or height\n\n#### imaginary#extract(params, [ callback ]) -\u003e `Promise`\n\nExtract image area by top/left and width/height pixels\n\n#### imaginary#expand(params, [ callback ]) -\u003e `Promise`\n\nResize any image to a given height in pixels.\n\n#### imaginary#zoom(params, [ callback ]) -\u003e `Promise`\n\nZoom an image by the given height in pixels.\n\n#### imaginary#rotate(params, [ callback ]) -\u003e `Promise`\n\nRotate an image to a given degrees (must be multiple of 90)\n\n#### imaginary#flip(params, [ callback ]) -\u003e `Promise`\n\nFlip an image\n\n#### imaginary#flop(params, [ callback ]) -\u003e `Promise`\n\nFlop an image\n\n#### imaginary#watermark(params, [ callback ]) -\u003e `Promise`\n\nAdd a watermark to an image\n\n#### imaginary#thumbnail(params, [ callback ]) -\u003e `Promise`\n\nThumbnail an image with a given width or height\n\n#### imaginary#pipeline(operations, [ params, callback ]) -\u003e `Promise`\n\n**Note**: requires `imaginary` v1.0.8+.\n\nPipeline processing a given image performing multiple independent image transformations\nas sort of map-reduce pattern in serie.\n\nYou can see a programmatic usage example [here](examples/pipeline.js).\n\nFor an example JSON of pipeline operations, see [examples/operations.json](examples/operations.json)\n\n##### Required params\n\n- **operations** `json|array` - List of operations to run. See [imaginary documentation]() for further details.\n\n#### imaginary#info([ callback ]) -\u003e `Promise`\n\nGet the metadata info of the image as JSON\n\n#### imaginary#health([ callback ]) -\u003e `Promise`\n\nRetrieve server health status\n\n#### imaginary#versions([ callback ]) -\u003e `Promise`\n\nRetrieve imaginary, bimg and libvips versions\n\n### imaginary.VERSION\n\nGet the current module version\n\n## License\n\n[MIT](http://opensource.org/licenses/MIT) © Tomas Aparicio\n\n[travis]: http://travis-ci.org/h2non/node-imaginary\n[gemnasium]: https://gemnasium.com/h2non/node-imaginary\n[npm]: http://npmjs.org/package/imaginary\n","funding_links":[],"categories":["📦 Legacy \u0026 Inactive Projects"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fh2non%2Fnode-imaginary","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fh2non%2Fnode-imaginary","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fh2non%2Fnode-imaginary/lists"}