picsee

##Description
Express-Compatible middleware that offers support for uploading photos, setting custom sizes, and storing them locally or remotely. API includes mechanism for cropping and resizing photos as well.

##Goals

• Provide a RESTFul interface that allows for photos to be uploaded safely to your app
• Be as lightweight as possible, so that you can use whatever ORM/DB/Store you want
• Offer a way to easily set desired sizes for your photo uploads through the conf.
• [[Soon]] Offer support for Amazon S3 Storage
• [[Soon]] Offer an API for managing your photos in a gallery, including sorting, and CRUD for photos in a gallery.

##How it Works Picsee allows you to define where and how you want to save your photos. Using the GD library, Picsee resizes your photo and saves it according to your specifications.

###Typical Use Case: Profile Photo If you are creating a form where your user is uploading a profile photo, you are most-likely going to want 3 versions of the photo:

• Small
• Medium
• Large

You name them, thmb, med, and lrg and your team/company/UI/UX/etc determines that:

• thmb = 32x32
• med = 200x[whatever]
• lrg = 800x[whatever]

So, your thmb will be scaled and saved to 32*32, and your med will be rescaled so that it is 200 pixels wide by whatever height is proportional to the original.

Your photos are saved according to whatever naming conventions you provide:

• date: 1365215413_thmb.jpg, 1365215413_med.jpg, 1365215413_lrg.jpg
• original: GradPhotos-0001-05-03-1977_thmb.jpg, etc
• custom: Coming Soon

Don't like underscores? Change the separator option.

Before your photos are saved, the original is moved to a staging directory, which you define. Here the Mime type is checked, and it is rejected if it is not a "jpg", "png", or "gif".

Directories Directories option "single" will place all images inside the uploaded folder. Directories option "version" will place all images in corresponding subdirectories that must be corrected under the upload directory. For example, given /upload directory and thmb, med, lrg options defined, the user shall need to create /upload/thmb /upload/med /upload/lrg At which point all cropped images will save as /upload/thmb/filename.filetype instead of separating by _thmb that part is done with the sub directories.

renameOrigImage Boolean option Use with date naming convention. that instead of just passing the original filename through the normalizer will append the date at the end. The dates for all cropped files will then match up with the original to allow for file tracking. Example: uploading myimage.jpg will generate myimage_12345.jpg All subsequent images will then start with 12345

Install

npm install picsee

Prerequisite: GD

Picsee currently only supports GD.

You will need to have GD installed so that node-gd (a dependency) can compile. Please have GD installed first.

GD on Mac

1. Get HomeBrew
2. brew install gd

GD on Ubuntu

apt-get install libgd2-xpm-dev

###App Setup

var picsee = require('picsee');

####Define Options

Option	Description
docRoot	root path to your images, ie /path/app/public/images/
urlRoot	base URL to view your images when they are uploaded
stagingDir	sandboxed (temporary) directory for uploading photos
processDir	directory to save processed photo(s)
uploadDir	permanent directory for saved photo(s)
originalDir	location of where the original is stored, if this option is omitted, or set to false, then originals will not be stored
versions	versions of photos with width and height option * Format: { "version name": { w: 200, h: 200 } }.
separator	character to use when concatenating file names, ie filename_thumb where filename is the original filename, and thumb is the name of the version. - or _ should work.
directories	Convention for storing files, i.e., use one directory and name files with versions attached, or store each file in a different directory named after the version? * single * version
namingConvention	how to name files? * date * original * custom
maxSize	Max Size (in KB) allowed
jpgQlty	Quality of Jpg (Up to 100, 100 being Highest)
gifQlty	Quality of Gif (Up to 100, 100 being Highest)
pngQlty	Quality of Png (Up to 10, 10 being Highest)
inputFields	Given a form with multiple inputs, which input(s) contain a photo? Ex: <input type="file" name="profile_photo" /> will require that you add profile_photo to the array of input fields. You can add as many as you want, and Picsee will process them all.
renameOrigImage	Use with date naming convention, boolean to append date at the end of the file. This will allow mapping to the created images
relativePath	Optional to set an needed prefix to a relative path that is generated for processing image
gifTransparency	Boolean. Whether or not to support GIF transparency, false by default. No transparency provides a much higher quality image result.

NOTE: JPEG/JPG, PNG (transparent and non-transparent), and GIFS (see gifTransparency option) are now fullly functional. #####Example Usage

var docroot = '/var/www/myproject/';
var options = {
  stagingDir: '/full/path/outside/of/project',
  processDir: docroot + 'public/photos/,
  versions: [  
    { "thmb": { w: 32, h: 32 } },   
    { "profile": { w: 200, h: null } },  
    { "full": { w: null, h: null } }  
  ],
  separator: '_',  
  directories: 'single',
  namingConvention: 'date',
  renameOrigImage: false,
  inputFields: ['profPhoto', 'other']
}

NOTE: For security purposes, where you put the stagingDir is important. It is in the staging directory that the file is being validated as a real file, and its mime-type is checked. If it does not pass validation, it won't make it into your application's photo location.

####Configure app.configure(function (){ // Set up your options first app.use(picsee.initialize(options)); app.use(app.router); });

####Create Directories Picsee requires that any directory you are uploading to exists and is writeable by Node or whatever user is running the app.

####Usage with Express

See: pisee-looksee. Note: For JCROP set up, if you do not set the JCROP background color to transparent, a background color will apear through any transparent images. (http://deepliquid.com/content/Jcrop_Manual.html)

##Testing

Requires mocha: npm install mocha -g.

To run:

npm test

##License The MIT License (MIT)

Copyright (c) 2013 Daniel Lochrie

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.