Merge branch 'v0.0.5'

README.md

@@ -1,15 +1,18 @@
 [![Version](http://img.shields.io/npm/v/lwip.svg)](https://www.npmjs.org/package/lwip)
 [![Build Status](https://api.travis-ci.org/EyalAr/lwip.svg?branch=master)](https://travis-ci.org/EyalAr/lwip)
-[![Coverage Status](https://img.shields.io/coveralls/EyalAr/lwip.svg)](https://coveralls.io/r/EyalAr/lwip)
+[![Coverage Status](https://img.shields.io/coveralls/EyalAr/lwip/master.svg)](https://coveralls.io/r/EyalAr/lwip)
 
 # Light-weight image processor for NodeJS
 
 0. [Overview](#overview)
   0. [Installation](#installation)
   0. [Usage](#usage)
   0. [Supported formats](#supported-formats)
+  0. [Colors specification](#colors-specification)
+  0. [Note on transparent images](#note-on-transparent-images)
 0. [API](#api)
   0. [Open an image from file or buffer](#open-an-image)
+  0. [Create a new blank image](#create-a-new-image)
   0. [Image operations](#image-operations)
     0. [Resize](#resize)
     0. [Scale](#scale)
@@ -24,9 +27,14 @@
     0. [Adjust saturation](#saturate)
     0. Adjust lightness: [lighten](#lighten) / [darken](#darken)
     0. [Adjust hue](#hue)
+    0. [Fade (adjust transparency)](#fade)
+    0. [Opacify](#opacify)
+    0. [Paste](#paste)
   0. [Getters](#getters)
     0. [Width](#width)
     0. [Height](#height)
+    0. [Clone](#clone)
+    0. [Extract / Copy](#extract)
     0. [Get as a Buffer](#get-as-a-buffer)
       0. [JPEG](#jpeg)
       0. [PNG](#png)
@@ -120,26 +128,68 @@ lwip.open('image.jpg', function(err, image){
 **Decoding (reading):**
 
 - JPEG, 1 & 3 channels (grayscale & RGB).
-- PNG, 1 & 3 channels (grayscale & RGB). Alpha channel (transperancy) is not
-  currently supported.
+- PNG, 1 & 3 channels (grayscale & RGB) + alpha (transparency) channel.
 
 **Encoding (writing):**
 
 - JPEG, 3 channels (RGB).
-- PNG (lossless), 3 channels (RGB).
+- PNG (lossless), 3 channels (RGB) or 4 channels (RGBA).
 
 Other formats may also be supported in the future, but are probably less urgent.
 Check the issues to see [which formats are planned to be supported](https://github.com/EyalAr/lwip/issues?labels=format+request&page=1&state=open).
 Open an issue if you need support for a format which is not already listed.
 
+### Colors specification
+
+In LWIP colors are coded as RGBA values (red, green, blue and an alpha channel).
+
+Colors are specified in one of three ways:
+
+- As a string. possible values:
+
+  ```Javascript
+  "black"    // {r: 0, g: 0, b: 0, a: 100}
+  "white"    // {r: 255, g: 255, b: 255, a: 100}
+  "gray"     // {r: 128, g: 128, b: 128, a: 100}
+  "red"      // {r: 255, g: 0, b: 0, a: 100}
+  "green"    // {r: 0, g: 255, b: 0, a: 100}
+  "blue"     // {r: 0, g: 0, b: 255, a: 100}
+  "yellow"   // {r: 255, g: 255, b: 0, a: 100}
+  "cyan"     // {r: 0, g: 255, b: 255, a: 100}
+  "magenta"  // {r: 255, g: 0, b: 255, a: 100} 
+  ```
+
+- As an array `[R, G, B, A]` where `R`, `G` and `B` are integers between 0 and
+  255 and `A` is an integer between 0 and 100.
+- As an object `{r: R, g: G, b: B, a: A}` where `R`, `G` and `B` are integers
+  between 0 and 255 and `A` is an integer between 0 and 100.
+
+**Note**: The `A` value (alpha channel) is always optional and defaults to
+100 (completely opaque).
+
+### Note on transparent images
+
+0. Transparency is supported through an alpha channel which ranges between 0
+   and 100. 0 is completely transparent and 100 is completely opaque.
+0. Not all formats support transparency. If an image with an alpha channel is
+   encoded with a format which does not support transparency, the alpha channel
+   will be ignored (effectively setting it to 100% for all pixels).
+
 ## API
 
-All operations are done on an `image` object. An `image` object is obtained with
-the `open` method.
+All operations are done on an `image` object. An `image` object can be obtained
+by:
+
+0. Openning an existing image file or buffer with the [`open`](#open-an-image)
+   method.
+0. Creating a new image object with the [`create`](#create-a-new-image) method.
+0. Cloning an existing image object with the [`image.clone`](#clone) method.
+0. Extracting a sub-image from an existing image object with the
+   [`image.extract`](#extract) method.
 
 ### Open an image
 
-`open(source, type, callback)`
+`lwip.open(source, type, callback)`
 
 0. `source {String/Buffer}`: The path to the image on disk or an image buffer.
 0. `type {String}`: **Optional** type of the image. If omitted, the type will be
@@ -172,6 +222,28 @@ fs.readFile('path/to/image.png', function(err, buffer){
 });
 ```
 
+### Create a new image
+
+`lwip.create(width, height, color, callback)`
+
+0. `width {Integer>0}`: The width of the new image.
+0. `height {Integer>0}`: The height of the new image.
+0. `color {String / Array / Object}`: **Optional** Color of the canvas. See
+   [colors specification](#colors-specification). Defaults to a transparent
+   canvas `{r:0, g:0, b:0, a:0}`.
+0. `callback {Function(err, image)}`
+
+**Example**:
+
+```Javascript
+var lwip = require('lwip');
+
+lwip.create(500, 500, 'yellow', function(err, image){
+  // check err
+  // 'image' is a 500X500 solid yellow canvas.
+});
+```
+
 ### Image operations
 
 #### Resize
@@ -213,13 +285,8 @@ fs.readFile('path/to/image.png', function(err, buffer){
 `image.rotate(degs, color, callback)`
 
 0. `degs {Float}`: Clockwise rotation degrees.
-0. `color {String / Array / Object}`: **Optional** Color of the canvas.
-  - As a string, possible values: `"black"`, `"white"`, `"gray"`, `"blue"`,
-    `"red"`, `"green"`, `"yellow"`, `"cyan"`, `"magenta"`.
-  - As an array `[R, G, B]` where `R`, `G` and `B` are integers between 0 and
-    255.
-  - As an object `{r: R, g: G, b: B}` where `R`, `G` and `B` are integers
-    between 0 and 255.
+0. `color {String / Array / Object}`: **Optional** Color of the canvas. See
+   [colors specification](#colors-specification).
 0. `callback {Function(err, image)}`
 
 #### Crop
@@ -277,13 +344,8 @@ Add a colored border to the image.
 `image.border(width, color, callback)`
 
 0. `width {Integer}`: Border width in pixels.
-0. `color {String / Array / Object}`: **Optional** Color of the border.
-  - As a string, possible values: `"black"`, `"white"`, `"gray"`, `"blue"`,
-    `"red"`, `"green"`, `"yellow"`, `"cyan"`, `"magenta"`.
-  - As an array `[R, G, B]` where `R`, `G` and `B` are integers between 0 and
-    255.
-  - As an object `{r: R, g: G, b: B}` where `R`, `G` and `B` are integers
-    between 0 and 255.
+0. `color {String / Array / Object}`: **Optional** Color of the border. See
+   [colors specification](#colors-specification).
 0. `callback {Function(err, image)}`
 
 #### Pad
@@ -293,13 +355,8 @@ Pad image edges with colored pixels.
 `image.pad(left, top, right, bottom, color, callback)`
 
 0. `left, top, right, bottom {Integer}`: Number of pixels to add to each edge.
-0. `color {String / Array / Object}`: **Optional** Color of the padding.
-  - As a string, possible values: `"black"`, `"white"`, `"gray"`, `"blue"`,
-    `"red"`, `"green"`, `"yellow"`, `"cyan"`, `"magenta"`.
-  - As an array `[R, G, B]` where `R`, `G` and `B` are integers between 0 and
-    255.
-  - As an object `{r: R, g: G, b: B}` where `R`, `G` and `B` are integers
-    between 0 and 255.
+0. `color {String / Array / Object}`: **Optional** Color of the padding. See
+   [colors specification](#colors-specification).
 0. `callback {Function(err, image)}`
 
 #### Saturate
@@ -359,6 +416,53 @@ Adjust image hue.
 **Note:** The hue is shifted in a circular manner in the range [0,360] for each
 pixel individually.
 
+#### Fade
+
+Adjust image transperancy.
+
+`image.fade(delta, callback)`
+
+0. `delta {Float}`: By how much to increase / decrease the transperancy.
+0. `callback {Function(err, image)}`
+
+**Note:** The transparency is adjusted independently for each pixel.
+
+**Examples**:
+
+0. `image.fade(0, ...)` will have no effect on the image.
+0. `image.fade(0.5, ...)` will increase the transparency by 50%.
+0. `image.fade(1, ...)` will make the image completely transparent.
+
+#### Opacify
+
+Make image completely opaque.
+
+`image.opacify(callback)`
+
+0. `callback {Function(err, image)}`
+
+#### Paste
+
+Paste an image on top of this image.
+
+`image.paste(left, top, img, callback)`
+
+0. `left, top {Integer}`: Coordinates of the top-left corner of the pasted
+   image.
+0. `img {Image object}`: The image to paste.
+0. `callback {Function(err, image)}`
+
+**Notes:**
+
+0. If the pasted image exceeds the bounds of the base image, an exception
+   is thrown.
+0. `img` is pasted in the state it was at the time `image.paste( ... )` was
+   called, eventhough `callback` is called asynchronously.
+0. For transparent images, alpha blending is done according to the equations
+   described [here](http://en.wikipedia.org/wiki/Alpha_compositing#Alpha_blending).
+0. Extra caution is required when using this method in batch mode, as the images
+   may change by the time this operation is called.
+
 ### Getters
 
 #### Width
@@ -369,6 +473,44 @@ pixel individually.
 
 `image.height()` returns the image's height in pixels.
 
+#### Clone
+
+Clone the image into a new image object.
+
+`image.clone(callback)`
+
+0. `callback {Function(err, newImage)}`
+
+**Example**: See [`examples/clone.js`](examples/clone.js)
+
+**Note**: The image is cloned to the state it was at the time
+`image.clone( ... )` was called, eventhough `callback` is called asynchronously.
+
+```Javascript
+image.width(); // 500
+image.clone(function(err, clone){
+    clone.width(); // 500
+});
+image.resize(100, 100, function(err, image){
+    image.width(); //100
+});
+```
+
+#### Extract
+
+Copy an area of the image into a new image object.
+
+`image.extract(left, top, right, bottom, callback)`
+
+0. `left, top, right, bottom {Integer}`: Coordinates of the area to copy.
+0. `callback {Function(err, newImage)}`
+
+**Example**: See [`examples/extract.js`](examples/extract.js)
+
+**Note**: The sub-image is extracted from the original image in the state it was
+at the time `image.extract( ... )` was called, eventhough `callback` is called
+asynchronously.
+
 #### Get as a Buffer
 
 Get encoded binary image data as a NodeJS
@@ -395,6 +537,8 @@ The `params` object should have the following fields:
 
 - `quality {Integer}`: Defaults to `100`.
 
+Note that when encoding to JPEG the alpha channel is discarded.
+
 ##### PNG
 
 The `params` object should have the following fields:
@@ -404,6 +548,10 @@ The `params` object should have the following fields:
   - `"fast"` - Basic compression. Fast.
   - `"high"` - High compression. Slowest.
 - `interlaced {Boolean}`: Defaults to `false`.
+- `transparency {true/false/'auto'}`: Preserve transparency? Defaults to
+  `'auto'`. Determines if the encoded image will have 3 or 4 channels. If
+  `'auto'`, the image will be encoded with 4 channels if it has transparent
+  components, and 3 channels otherwise.
 
 #### Write to file
 
@@ -529,13 +677,13 @@ The native part of this module is compiled from source which uses the following:
 
 - Independent JPEG Group's free JPEG software:
   - [Website](http://www.ijg.org/)
-  - [Readme](https://github.com/EyalAr/lwip/blob/master/lib/jpeg/README)
+  - [Readme](https://github.com/EyalAr/lwip/blob/master/src/lib/jpeg/README)
 - libpng:
   - [Website](http://www.libpng.org/)
-  - [Readme](https://github.com/EyalAr/lwip/blob/master/lib/png/README)
+  - [Readme](https://github.com/EyalAr/lwip/blob/master/src/lib/png/README)
 - zlib:
   - [Website](http://www.zlib.net/)
-  - [Readme](https://github.com/EyalAr/lwip/blob/master/lib/zlib/README)
+  - [Readme](https://github.com/EyalAr/lwip/blob/master/src/lib/zlib/README)
 - The CImg Library
   - [Website](http://cimg.sourceforge.net/)
-  - [Readme](https://github.com/EyalAr/lwip/blob/master/lib/cimg/README.txt)
+  - [Readme](https://github.com/EyalAr/lwip/blob/master/src/lib/cimg/README.txt)