Simple but powerful image uploader with fancy features:
- Upload to the Cloud - Supports Amazon S3, Rackspace, Azure and local harddrive. It's extendable if your favorite cloud isn't supported!
- File name formatting - Pretty file names with support for your own custom formatter.
- Presets - Define filters/sizes once, use everywhere!
- Custom filters - Everything you can do with graphics magic you can do with CloudImager. You can also combine multiple filters.
- Control over output - If you want to include image dimensions or exif data, just define your own outlet.
###Dependencies
####Install with Homebrew
brew install imagemagick
var imager = require('cloud-imager');
var p = imager.processors;
imager.preset({
square: p.smartCrop(100, 100),
sepia: [p.resize(200, 200), p.sepia]
}
imager.process('./test.jpg', function(err, res) {
...
});
This will return something like this:
{
square: '8IP9bwH1alVdaocK_square.jpg',
sepia: '8IP9bwH1alVdaocK_sepia.jpg',
original: '8IP9bwH1alVdaocK.jpg'
}
###With express.js
app.post('/upload', function(req, res) {
if(req.files.image) {
imager.process(req.files.image, function(err, res) {
...
});
}
});
###With multiple presets
imager.preset('article', {
thumbnail: p.smartCrop(50, 50),
wide: p.resize(500)
});
imager.preset('instagram', {
thumbnail: p.smartCrop(50, 50),
large: p.smartCrop(512, 512),
}, {
keepOriginal: false,
fileNameFormat: '{{uid}}/{{variant}}{{mimeExtension}}'
});
imager.process('./test.jpg', 'instagram', function(err, res) {
...
});
Anything listed in the gm documentation should work. Additionally these are provided:
####smartCrop(width, height) Resizes the image to given dimensions, if aspect ratio differs from the image it will be cropped aswell. This is great for generating thumbnails or squares.
###Global Options
Option Name | Description | Default |
---|---|---|
imageManipulator | gm subclass. | ImageMagick |
defaultOutlet | Default outlet if not defined in process() options. | CloudImager.localDirectoryOutlet |
uploadDirectory | Destination folder of processed files. | './' |
fileNameFormat | See File Name Format. | '{{uid}}{{prefixedVariant}}{{mimeExtension}}' |
fileNameFormatter | See Define Custom Formatter. | CloudImager.defaultFileNameFormatter |
###File Name Formatting
####File Name Format
Can be globally defined in imager.fileNameFormat
or passed in your outlet options object.
Available variables:
Variable | Description | Example |
---|---|---|
{{preset}} | Name of the current preset. | default or article |
{{variant}} | Name of the image manipulation variant. | thumbnail or original |
{{prefixedVariant}} | Same as variant but prefixed with underscore. | _thumbnail or empty string |
{{name}} | Original file name. | CATS & Unicorns.jPEg |
{{extension}} | Original file extension. | .jPEg |
{{basename}} | Original file name without extension. | CATS & Unicorns |
{{mimeExtension}} | Associated extension to detected mime type. | .jpg |
{{uid}} | Randomized 16 letter name. | NcNen1efymj0KkCl |
####Note!
Keep in mind that {{name}}
, {{extension}}
and {{basename}}
are not to be trusted if coming from user uploads. Make sure to validate beforehand or use {{uid}}
and {{mimeExtension}}
.
####Define Custom Formatter
var userImageFormatter = function(username) {
return function(format, context) {
return 'public/users/' + username + context.mimeExtension;
};
};
app.post('/profile/image', function(req, res) {
imager.fileNameFormatter = userImageFormatter(req.user.username);
if(req.files.image) {
imager.process(req.files.image, function(err, res) {
...
});
}
});
###Local Storage
Good for development environments. This is default and uploads to public/uploads
. To change this you can either define a new outlet or configure the existing:
imager.uploadDirectory = './uploads'; //Relative to your package root
or define new outlet:
imager.defaultOutlet = imager.localDirectoryOutlet({
uploadDirectory: __dirname +'/public/uploads'
//If return type is url or relative, they will be relative to cwd
cwd: __dirname +'/public',
//Can be absolute, url och relative. Url is like relative but prefixed with /
returnType: 'url'
});
or pass the directory as a parameter:
imager.process('./test.jpg', 'default' 'publicAssets/uploads', function(err, res) {
...
});
For this you would need to add pkgcloud to your dependencies: npm install pkgcloud --save
.
Currently suppports Amazon, Rackspace and Azure.
###Example AWS S3 setup
var pkgcloud = require('pkgcloud');
var storageClient = pkgcloud.storage.createClient({
provider: 'amazon',
accessKey: process.env.AWS_S3_SECRET,
accessKeyId: process.env.AWS_S3_KEY,
});
imager.defaultOutlet = imager.pkgcloudOutlet(storageClient, process.env.AWS_S3_BUCKET);
The following outlet will make filenames web safe and return file path and size of generated images.
var slugify = require('slugify');
function slugifyOutlet(file, context, cb) {
context.slug = slugify(context.name);
var destination = imager.formatFileName('{{slug}}{{mimeExtension}}', context);
//Save file to disc first to be able to read altered sizes
file.write(destination, function(err) {
if(err) return cb(err);
imager.imageManipulator(destination).size(function(err, size) {
cb(err, { file: destination, size: size});
});
});
};
imager.defaultOutlet = slugifyOutlet;
- Unit tests
- Better code commenting
- Instagram like processors
- Support stream input
- (Deleting files based on url)