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

Get HomeBrew
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)

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.

dlochrie/picsee

picsee

Install

Prerequisite: GD

GD on Mac

GD on Ubuntu