Add docs, Raise error when loading non existing paths

docs/_config.yml

@@ -0,0 +1 @@
+theme: jekyll-theme-cayman

docs/api.md

@@ -0,0 +1,71 @@
+# Lycon API
+
+## Core Functions
+
+### `lycon.load(path, mode=Decode.UNCHANGED)`
+
+Loads and returns the image at the given path as a numpy ndarray.
+
+
+### `lycon.save(path, image, options=None)`
+
+Saves the given image (a numpy ndarray) at the given path.
+The image format is inferred from the extension.
+
+The options argument, if provided, should be a dictionary where the keys are constants from the Encode enum and the values are integers.
+
+### `lycon.resize(image, width, height, interpolation=Interpolation.LINEAR, output=None)`
+
+Resize the image to the given dimensions, resampled using the given interpolation method.
+
+If an output ndarray is provided, it must be the same type as the input and have the
+dimensions of the resized image.
+
+### `lycon.get_supported_extensions`
+
+Returns a list of supported image extensions.
+
+## Enums
+
+### `Interpolation`:
+
+- `lycon.Interpolation.NEAREST`: Nearest Neighbor interpolation
+- `lycon.Interpolation.LINEAR`: Bilinear interpolation
+- `lycon.Interpolation.CUBIC`: Bicubic interpolation
+- `lycon.Interpolation.AREA`: Resampling using pixel area relation. It may be a preferred method for image decimation, as it gives moire free results. When the image is zoomed, it is similar to nearest neighborhood interpolation.
+- `lycon.Interpolation.LANCZOS` Lanczos interpolation over 8x8 neighborhood.
+
+### `Decode`:
+
+- `lycon.Decode.UNCHANGED`: Load either a grayscale or color image (including alpha channel), 8-bit format
+- `lycon.Decode.GRAYSCALE`: Load as a grayscale 8-bit image. Color images will be converted to grayscale.
+- `lycon.Decode.COLOR`: Load as a three-channeled 8-bit image. Grayscale images will be converted. Any alpha channels will be discarded.
+- `lycon.Decode.ANY_DEPTH`: If set, 16-bit and 32-bit images are returned as such. Otherwise, an 8-bit image is returned.
+
+### `Encode`:
+
+See `lycon.save`.
+
+*Keys*:
+
+- `lycon.Encode.JPEG_QUALITY`
+- `lycon.Encode.JPEG_PROGRESSIVE`
+- `lycon.Encode.JPEG_OPTIMIZE`
+- `lycon.Encode.JPEG_RST_INTERVAL`
+- `lycon.Encode.JPEG_LUMA_QUALITY`
+- `lycon.Encode.JPEG_CHROMA_QUALITY`
+
+*Values*: An integer from 0 to 100 (the higher is the better). The default value is 95.
+
+*Keys:*
+
+- `lycon.Encode.PNG_COMPRESSION`
+- `lycon.Encode.PNG_STRATEGY`
+- `lycon.Encode.PNG_BILEVEL`
+- `lycon.Encode.PNG_STRATEGY_DEFAULT`
+- `lycon.Encode.PNG_STRATEGY_FILTERED`
+- `lycon.Encode.PNG_STRATEGY_HUFFMAN_ONLY`
+- `lycon.Encode.PNG_STRATEGY_RLE`
+- `lycon.Encode.PNG_STRATEGY_FIXED`
+
+*Values*: An integer from 0 to 9. A higher value means a smaller size and longer compression time. Default value is 3.

docs/index.md

@@ -0,0 +1,123 @@
+# Lycon
+
+A minimal and fast image library for Python and C++.
+
+Lycon is a small subset of optimized image operations derived from [OpenCV](http://opencv.org/).
+
+Current set of features include:
+
+- Reading and writing JPEG and PNG images
+- Fast SIMD optimized image resizing
+- Zero-copy interop with [NumPy](http://www.numpy.org/) whenever possible
+
+Tested on:
+
+- Linux (Ubuntu 14.04) with Python`2.7.6` and `3.5.2`.
+- macOS (Sierra, 10.12) with Python `2.7.11` and `3.5.1`.
+
+
+## API
+
+Check out [API](api.md).
+
+
+## Install
+
+```
+pip install lycon
+```
+
+Native extension dependencies:
+
+- CMake 2.8 or newer
+- C++ toolchain
+- LibJPEG
+- LibPNG
+
+### Ubuntu
+
+Single-line command for installing all dependencies:
+
+```
+sudo apt-get install cmake build-essential libjpeg-dev libpng-dev
+```
+
+### Anaconda
+
+When working within an Anaconda Python distribution, it is recommended to use the latest `cmake` version (`3.6` or newer). Older versions can lead to a mismatch between the `libpng` and `libjpeg` headers used to build Lycon (usually the system headers), and the linked library (which may be preempted by the Anaconda-scoped version). To install the latest `cmake` version:
+
+```
+conda install cmake
+```
+
+## Example
+
+```python
+import lycon
+
+# Load an image as a numpy array
+img = lycon.load('mittens.jpg')
+# Resize the image using bicubic interpolation
+resized = lycon.resize(img, width=256, height=512, interpolation=lycon.Interpolation.CUBIC)
+# Crop the image (like any regular numpy array)
+cropped = resized[:100, :200]
+# Save the image
+lycon.save('cropped-mittens.png', cropped)
+```
+
+## Limitations
+
+Compared to other image processing libraries ([OpenCV](http://opencv.org/), [pillow](https://python-pillow.org/), [scikit-image](http://scikit-image.org/)), Lycon offers a very limited set of operations. Intended usages include data loaders for deep learning, mass image resizing, etc.
+
+## Advantages over OpenCV
+
+- Drastically smaller (at the cost of drastically fewer features)
+- Python module installable via `pip`
+- Images use the more common `RGB` ordering (vs OpenCV's `BGR`)
+
+However, if you already have OpenCV installed, Lycon's advantages are minimal.
+
+## Advantages over PIL(low)
+
+- Faster
+- First-class NumPy support
+- Full support for floating point images
+
+## Advantages over Scikit-Image
+
+- Drastically faster
+
+## Benchmarks
+
+- The table below lists execution time (in seconds), averaged across 10 runs
+- The multiplier next to the time is the relative slowdown compared to Lycon
+
+| Operation            |  Lycon |        OpenCV |             PIL |      Scikit-Image |
+|----------------------|-------:|--------------:|----------------:|------------------:|
+| Upsample: Nearest    | 0.1944 |   0.1948 (1x) |    2.1342 (11x) |  30.8982 (158.9x) |
+| Upsample: Bilinear   | 0.4852 |   0.4940 (1x) |    7.2940 (15x) |   45.9095 (94.6x) |
+| Upsample: Bicubic    | 1.8162 |   1.8182 (1x) |   8.9589 (4.9x) |  120.1645 (66.1x) |
+| Upsample: Lanczos    | 4.5641 |   4.5714 (1x) |  10.7517 (2.3x) |                   |
+| Upsample: Area       | 0.4801 |   0.4931 (1x) |                 |                   |
+| Downsample: Nearest  | 0.0183 |   0.0181 (1x) |  0.4379 (24.2x) |   3.6101 (199.9x) |
+| Downsample: Bilinear | 0.0258 |   0.0257 (1x) |    1.3122 (51x) |   4.8487 (188.4x) |
+| Downsample: Bicubic  | 0.1324 |   0.1329 (1x) |  1.8153 (13.7x) |    9.4905 (71.6x) |
+| Downsample: Lanczos  | 0.3317 |   0.3328 (1x) |   2.4058 (7.2x) |                   |
+| Downsample: Area     | 0.0258 |   0.0259 (1x) |                 |                   |
+| Read: JPG            | 0.3409 | 0.5085 (1.5x) |   1.4081 (4.1x) |     1.4628 (4.3x) |
+| Read: PNG            | 1.2114 | 1.3245 (1.1x) |   1.8274 (1.5x) |     1.8674 (1.5x) |
+| Write: JPG           | 0.4760 | 0.6046 (1.3x) |     2.3823 (5x) |    5.0159 (10.5x) |
+| Write: PNG           | 2.1421 |   2.2370 (1x) |   9.0580 (4.2x) |    11.6060 (5.4x) |
+
+- Blank cells indicate that the operation is not supported by the library
+- All operations performed on a 16k (15360 x 8640) RGB image
+- Tests performed on Ubuntu 14.04 running on an Intel Core i7 (Skylake)
+- OpenCV `3.2+ (master: a85b4b5)`, Pillow `4.0.0`, skimage `0.12.3`, Python `2.7.3`
+- OpenCV can potentially achieve better performance with GPU implementations and proprietary libraries like Intel IPP
+
+## License
+
+- All code derived from the OpenCV project is licensed under the 3-clause BSD License.
+- All Lycon-specific modifications are licensed under the MIT license.
+
+See `LICENSE` for further details.

lycon/core.py

@@ -1,13 +1,18 @@
 import _lycon
 
+import os
 import itertools
 
 from .enum import (Decode, Encode, Interpolation)
 
+
 def load(path, mode=Decode.UNCHANGED):
     """
     Loads and returns the image at the given path as a numpy ndarray.
     """
+    if not os.path.isfile(path):
+        raise FileNotFoundError("No such file: '{}'".format(path))
+
     return _lycon.load(path, mode)
 
 def save(path, image, options=None):