From 1dcb23f7c851181b57eec734a3c5e8a7c844fcf3 Mon Sep 17 00:00:00 2001 From: Sasank Chilamkurthy Date: Fri, 29 Dec 2017 22:41:16 +0530 Subject: [PATCH 1/3] Raise error in load if file not found --- lycon/core.py | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/lycon/core.py b/lycon/core.py index 9712b72..90e8556 100644 --- a/lycon/core.py +++ b/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): From 023f1bc1aae6b3f696c5170edb97e2df9b6b9877 Mon Sep 17 00:00:00 2001 From: Sasank Chilamkurthy Date: Fri, 29 Dec 2017 23:09:43 +0530 Subject: [PATCH 2/3] Docs (#1) * Add docs * Small correct --- docs/api.md | 71 +++++++++++++++++++++++++++++ docs/index.md | 123 ++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 194 insertions(+) create mode 100644 docs/api.md create mode 100644 docs/index.md diff --git a/docs/api.md b/docs/api.md new file mode 100644 index 0000000..0d564c5 --- /dev/null +++ b/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. \ No newline at end of file diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 0000000..cc6a0a4 --- /dev/null +++ b/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. From 4ac4777ac9d5d0cdf000db09c0e0816135ec0329 Mon Sep 17 00:00:00 2001 From: Sasank Chilamkurthy Date: Fri, 29 Dec 2017 23:12:40 +0530 Subject: [PATCH 3/3] Set theme jekyll-theme-cayman --- docs/_config.yml | 1 + 1 file changed, 1 insertion(+) create mode 100644 docs/_config.yml diff --git a/docs/_config.yml b/docs/_config.yml new file mode 100644 index 0000000..c419263 --- /dev/null +++ b/docs/_config.yml @@ -0,0 +1 @@ +theme: jekyll-theme-cayman \ No newline at end of file