Merge pull request #29 from EyalAr/v0.0.2

Version 0.0.2
EyalAr · Sep 4, 2014 · d26a618 · d26a618
2 parents 7e4ccd4 + aec9d8a
commit d26a618
Show file tree

Hide file tree

Showing 100 changed files with 52,473 additions and 303 deletions.
diff --git a/.gitignore b/.gitignore
@@ -1,3 +1,4 @@
 build
 node_modules
 npm-debug.log
+tests/results
diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md
@@ -0,0 +1,53 @@
+# Development Notes
+
+An image is just a matrix of pixels. Pixels have channels. Grayscale images have
+one channel, color images have 3 or more channels (RGB. CMYK, etc.) and
+transparent images have 4 or more channels (RGBA, etc.), one of which we call
+an "alpha" channel; which defines how transparent the respective pixel is.
+
+Pixel color can be represented in various ways. It can be broken down to base
+color components such as in RGB and CMYK. It can be encoded as an indexed color
+palette, where the palette itself can be RGB or CMYK.
+
+Storing the image's pixels as they are is wasteful. There are methods to encode
+and compress the pixels such that the image takes less space. Some of those
+methods loose data in the process of compression ("lossy compressions"), and
+thus the quality of the image is reduced. Some methods don't loose data in the
+compressions process ("lossless compression"), and thus the quality of the image
+is preserved. We call those methods "image formats".
+
+For example:
+
+- JPEG does lossy compression (first it discards image data, then it compresses
+  it).
+- PNG does lossless compression (just compresses the data, without loosing any
+  of it).
+
+Different formats support different color representations and compressions
+methods.
+
+## Opening an image
+
+Images exist in the wild in various formats with various color representations.
+Before working on an image we need to obtain the decoded and uncompressed pixels
+data. Each format has its own methods of decoding and decompression.
+
+By "opening an image", we mean - going through the process of having the pixels
+in memory. Once we have that, we can start manipulating the image.
+
+We need to decide how to represent uncompressed pixels data in memory.
+
+- What if we open a grayscale image?
+- What if we open a 3 channels colored image?
+- What if we open a 4 channels colored image?
+- What if we open an image with an alpha channel?
+
+In order to reduce complexity, we will always represent pixels as 3 channels
+RGB values. If the image is originally grayscale, we will convert it to RGB
+when opening it, etc.
+
+In order to decode an image, we have to identify its format. Once we do that,
+we can use the appropriate library.
+
+Images are constructed as `CImg<unsigned char>`. Notice the type of a pixel
+channel is `unsigned char`, which makes our images 8bit.
diff --git a/README.md b/README.md
@@ -1,4 +1,4 @@
-[![Build Status](https://travis-ci.org/EyalAr/lwip.svg?branch=master)](https://travis-ci.org/EyalAr/lwip)
+[![Build Status](https://api.travis-ci.org/EyalAr/lwip.svg?branch=master)](https://travis-ci.org/EyalAr/lwip)
 [![Stories in Ready](https://badge.waffle.io/eyalar/lwip.png?label=ready&title=Ready)](https://waffle.io/eyalar/lwip)
 [![Stories in Ready](https://badge.waffle.io/eyalar/lwip.png?label=in+progress&title=In+Progress)](https://waffle.io/eyalar/lwip)
 
@@ -16,11 +16,16 @@
     0. [Rotate](#rotate)
     0. [Crop](#crop)
     0. [Blur](#blur)
+    0. [Mirror](#mirror)
+    0. [Flip](#flip)
+    0. [Border](#border)
+    0. [Pad](#pad)
   0. [Getters](#getters)
     0. [Width](#width)
     0. [Height](#height)
     0. [Get as a Buffer](#get-as-a-buffer)
       0. [JPEG](#jpeg)
+      0. [PNG](#png)
     0. [Write to file](#write-to-file)
   0. [Batch operations](#batch-operations)
 0. [Copyrights](#copyrights)
@@ -106,11 +111,18 @@ lwip.open('image.jpg', function(err, image){
 
 ### Supported formats
 
-Currently only JPEG is supported. I plan to add support for PNG soon (part of
-the [milestone for v0.0.2](https://github.com/EyalAr/lwip/issues?milestone=2&page=1&state=open)).
+**Decoding (reading):**
 
-Other formats may also be supported in the future, but are probably less urgent.
+- JPEG, 1 & 3 channels (grayscale & RGB).
+- PNG, 1 & 3 channels (grayscale & RGB). Alpha channel (transperancy) is not
+  currently supported.
+
+**Encoding (writing):**
+
+- JPEG, 3 channels (RGB).
+- PNG (lossless), 3 channels (RGB).
 
+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.
 
@@ -213,6 +225,51 @@ Gaussian blur.
 0. `sigma {Float}`: Standard deviation of the Gaussian filter.
 0. `callback {Function(err, image)}`
 
+#### Mirror
+
+Mirror an image along the 'x' axis, 'y' axis or both.
+
+`image.mirror(axes, callback)`
+
+0. `axes {String}`: `'x'`, `'y'` or `'xy'`.
+0. `callback {Function(err, image)}`
+
+#### Flip
+
+Alias of [`mirror`](#mirror).
+
+#### Border
+
+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. `callback {Function(err, image)}`
+
+#### Pad
+
+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. `callback {Function(err, image)}`
+
 ### Getters
 
 #### Width
@@ -237,6 +294,7 @@ encoded data as a NodeJS Buffer object.
 
 0. `format {String}`: Encoding format. Possible values:
   - `"jpg"`
+  - `"png"`
 0. `params {Object}`: **Optional** Format-specific parameters (See below).
 0. `callback {Function(err, buffer)}`
 
@@ -248,6 +306,16 @@ The `params` object should have the following fields:
 
 - `quality {Integer}`: Defaults to `100`.
 
+##### PNG
+
+The `params` object should have the following fields:
+
+- `compression {String}`: Defaults to `"fast"`. Possible values:
+  - `"none"` - No compression. Fastest.
+  - `"fast"` - Basic compression. Fast.
+  - `"high"` - High compression. Slowest.
+- `interlaced {Boolean}`: Defaults to `false`.
+
 #### Write to file
 
 Write encoded binary image data directly to a file.
@@ -373,6 +441,12 @@ 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)
+- libpng:
+  - [Website](http://www.libpng.org/)
+  - [Readme](https://github.com/EyalAr/lwip/blob/master/lib/png/README)
+- zlib:
+  - [Website](http://www.zlib.net/)
+  - [Readme](https://github.com/EyalAr/lwip/blob/master/lib/zlib/README)
 - The CImg Library
   - [Website](http://cimg.sourceforge.net/)
   - [Readme](https://github.com/EyalAr/lwip/blob/master/lib/cimg/README.txt)
diff --git a/binding.gyp b/binding.gyp
@@ -2,8 +2,12 @@
     "targets": [{
         "target_name": "lwip",
         "sources": [
+            # LWIP: 
+            #######
             "src/lwip.cpp",
             "src/LwipImage.cpp",
+            # LIB JPEG:
+            ###########
             "lib/jpeg/jmemnobs.c",
             "lib/jpeg/jcapimin.c",
             "lib/jpeg/jcapistd.c",
@@ -47,9 +51,43 @@
             "lib/jpeg/jquant1.c",
             "lib/jpeg/jquant2.c",
             "lib/jpeg/jdmerge.c",
-            "lib/jpeg/jaricom.c"
+            "lib/jpeg/jaricom.c",
+            # LIB PNG:
+            ##########
+            "lib/png/png.c",
+            "lib/png/pngset.c",
+            "lib/png/pngget.c",
+            "lib/png/pngrutil.c",
+            "lib/png/pngtrans.c",
+            "lib/png/pngwutil.c",
+            "lib/png/pngread.c",
+            "lib/png/pngrio.c",
+            "lib/png/pngwio.c",
+            "lib/png/pngwrite.c",
+            "lib/png/pngrtran.c",
+            "lib/png/pngwtran.c",
+            "lib/png/pngmem.c",
+            "lib/png/pngerror.c",
+            "lib/png/pngpread.c",
+            # ZLIB:
+            #######
+            "lib/zlib/adler32.c",
+            "lib/zlib/compress.c",
+            "lib/zlib/crc32.c",
+            "lib/zlib/deflate.c",
+            "lib/zlib/gzclose.c",
+            "lib/zlib/gzlib.c",
+            "lib/zlib/gzread.c",
+            "lib/zlib/gzwrite.c",
+            "lib/zlib/infback.c",
+            "lib/zlib/inflate.c",
+            "lib/zlib/inftrees.c",
+            "lib/zlib/inffast.c",
+            "lib/zlib/trees.c",
+            "lib/zlib/uncompr.c",
+            "lib/zlib/zutil.c"
         ],
-        'include_dirs': ['lib/jpeg', 'lib/cimg'],
+        'include_dirs': ['lib/zlib', 'lib/jpeg', 'lib/cimg', 'lib/png'],
         'conditions': [
             ['OS=="linux"', {
                 'cflags!': ['-fno-exceptions'],