# redpil
[](https://pypi.python.org/pypi/redpil)
[](https://redpil.readthedocs.io/en/latest/?badge=latest)
Join the wonderland of python, and decode all your images in a numpy compatible
way.
Pillow is a great library for image manipulation. However, many operations fall
outside what Pillow can do. As such, many scientific applications require the
image to be available as a numpy array. [imageio](
https://github.com/imageio/imageio) has created an efficient bridge between
numpy and Pillow (see benchmarks below).
For large images, having to understand the details of both Pillow and numpy is a serious bottleneck.
The goal of the library it to read and write images in a manner natural to numpy
users. Images are presented as the values they hold (not indices in a color
table) allowing for direct data analysis.
To avoid the need for an other C dependency, this library aims at creating a pure
python image decoder for many of the image formats supported by Pillow that depends
on other popular libraries such as numpy and scipy to do the heavy lifting in terms of
computation. We start with the simple BMP file format. The pure python nature of this
library means that we can quickly try to implement encoding and decoding into different
image formats.
## Bitmap images
Generally, this library will not load memory in a C-contiguous array. Rather
the memory order will mostly match what was saved on disk.
Bitmap images will be stored in an order similar to how they arranged in
RAM.
## Supported file formats
Reading BMP is almost fully supported. Writing is still limited.
* BMP: 1, 4, or 8bit per pixel. [Wikipedia](https://en.wikipedia.org/wiki/BMP_file_format)
## Future file formats
* BMP: more coverage
* JPEG, JPEG2000
* GIF
* PNG
* SVG
* TIFF
## Benchmarks
I don't have a fancy benchmarking service like scikit-image or dask has, but
here are the benchmarks results compared to a PIL backend. This is running
on my SSD, a Samsung 960 Pro which claims it can write at 1.8GB/s. This is
pretty close to what `redpil` achieves.
### 8 bit BMP grayscale images
Saving images:
```
================ ============ ============ ============
-- mode
---------------- --------------------------------------
shape redpil pillow imageio
================ ============ ============ ============
(128, 128) 93.4±1μs 254±30μs 369±20μs
(1024, 1024) 720±30μs 936±50μs 1.60±0.3ms
(2048, 4096) 5.25±0.7ms 5.20±0.1ms 10.4±2ms
(32768, 32768) 480±10ms 489±5ms 1.34±0.09s
================ ============ ============ ============
```
Reading image
```
================ ============= ============ =============
-- mode
---------------- ----------------------------------------
shape redpil pillow imageio
================ ============= ============ =============
(128, 128) 131±5μs 293±10μs 130±2μs
(1024, 1024) 194±10μs 1.03±0.1ms 192±5μs
(2048, 4096) 1.69±0.05ms 8.55±1ms 1.67±0.03ms
(32768, 32768) 350±3ms 230±5μs 354±10ms
================ ============= ============ =============
```
Note, Pillow refuses to read the 1GB image because it thinks it is a fork bomb.
#### Patched up imageio
As it can be seen, the team at imageio/scikit-image are much better at reading
the pillow documentation and understanding how to use it effectively. Their
reading speeds actually match the reading speeds of redpil, even though they
use pillow as a backend. They even handle what pillow thinks is a forkbomb.
Through writing this module, two bugs were found in imageio that affect
the speed of saving images [imageio PR #398](
https://github.com/imageio/imageio/pull/398), and how images were being read
[imageio PR #399](
https://github.com/imageio/imageio/pull/399#issuecomment-433992314)
With PR 398, the saving speed of imageio+pillow now matches that of redpil.
Note I'm always using the computer when running benchmarks, so take the exact
numbers with a grain of salt.
Saving
```
================ ============ ============ ============
-- mode
---------------- --------------------------------------
shape redpil pillow imageio
================ ============ ============ ============
(128, 128) 98.3±4μs 245±7μs 350±4μs
(1024, 1024) 714±20μs 921±30μs 997±20μs
(2048, 4096) 4.83±0.3ms 5.30±0.4ms 5.26±0.2ms
(32768, 32768) 520±40ms 516±30ms 489±9ms
================ ============ ============ ============
```
Reading
```
================ ============= ============ =============
-- mode
---------------- ----------------------------------------
shape redpil pillow imageio
================ ============= ============ =============
(128, 128) 129±0.7μs 284±2μs 129±0.7μs
(1024, 1024) 191±2μs 1.12±0.1ms 190±0.9μs
(2048, 4096) 1.62±0.03ms 8.88±1ms 1.63±0.02ms
(32768, 32768) 357±9ms 223±4μs 361±8ms
================ ============= ============ =============
```
# History
## 0.0.1 (2018-09-22)
* First release on PyPI.
Raw data
{
"_id": null,
"home_page": "https://github.com/hmaarrfk/redpil",
"name": "redpil",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "redpil",
"author": "Mark Harfouche",
"author_email": "mark.harfouche@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/aa/81/c187a25d7a1f7325289ce716e53815adb300d7da37750b0f03b182fe22ec/redpil-0.2.1.tar.gz",
"platform": null,
"description": "# redpil\n\n[](https://pypi.python.org/pypi/redpil)\n[](https://redpil.readthedocs.io/en/latest/?badge=latest)\n\n\nJoin the wonderland of python, and decode all your images in a numpy compatible\nway.\n\nPillow is a great library for image manipulation. However, many operations fall\noutside what Pillow can do. As such, many scientific applications require the\nimage to be available as a numpy array. [imageio](\nhttps://github.com/imageio/imageio) has created an efficient bridge between\nnumpy and Pillow (see benchmarks below).\n\nFor large images, having to understand the details of both Pillow and numpy is a serious bottleneck.\nThe goal of the library it to read and write images in a manner natural to numpy\nusers. Images are presented as the values they hold (not indices in a color\ntable) allowing for direct data analysis.\n\nTo avoid the need for an other C dependency, this library aims at creating a pure \npython image decoder for many of the image formats supported by Pillow that depends\non other popular libraries such as numpy and scipy to do the heavy lifting in terms of\ncomputation. We start with the simple BMP file format. The pure python nature of this\nlibrary means that we can quickly try to implement encoding and decoding into different \nimage formats.\n\n\n## Bitmap images\nGenerally, this library will not load memory in a C-contiguous array. Rather\nthe memory order will mostly match what was saved on disk.\n\nBitmap images will be stored in an order similar to how they arranged in\nRAM.\n\n## Supported file formats\n\nReading BMP is almost fully supported. Writing is still limited.\n\n* BMP: 1, 4, or 8bit per pixel. [Wikipedia](https://en.wikipedia.org/wiki/BMP_file_format)\n\n## Future file formats\n\n* BMP: more coverage\n* JPEG, JPEG2000\n* GIF\n* PNG\n* SVG\n* TIFF\n\n## Benchmarks\n\nI don't have a fancy benchmarking service like scikit-image or dask has, but\nhere are the benchmarks results compared to a PIL backend. This is running\non my SSD, a Samsung 960 Pro which claims it can write at 1.8GB/s. This is\npretty close to what `redpil` achieves.\n\n\n### 8 bit BMP grayscale images\n\nSaving images:\n```\n================ ============ ============ ============\n-- mode \n---------------- --------------------------------------\n shape redpil pillow imageio \n================ ============ ============ ============\n (128, 128) 93.4\u00b11\u03bcs 254\u00b130\u03bcs 369\u00b120\u03bcs \n (1024, 1024) 720\u00b130\u03bcs 936\u00b150\u03bcs 1.60\u00b10.3ms\n (2048, 4096) 5.25\u00b10.7ms 5.20\u00b10.1ms 10.4\u00b12ms \n (32768, 32768) 480\u00b110ms 489\u00b15ms 1.34\u00b10.09s\n================ ============ ============ ============\n```\n\nReading image\n```\n================ ============= ============ =============\n-- mode \n---------------- ----------------------------------------\n shape redpil pillow imageio \n================ ============= ============ =============\n (128, 128) 131\u00b15\u03bcs 293\u00b110\u03bcs 130\u00b12\u03bcs \n (1024, 1024) 194\u00b110\u03bcs 1.03\u00b10.1ms 192\u00b15\u03bcs \n (2048, 4096) 1.69\u00b10.05ms 8.55\u00b11ms 1.67\u00b10.03ms\n (32768, 32768) 350\u00b13ms 230\u00b15\u03bcs 354\u00b110ms \n================ ============= ============ =============\n```\n\nNote, Pillow refuses to read the 1GB image because it thinks it is a fork bomb.\n\n#### Patched up imageio\n\nAs it can be seen, the team at imageio/scikit-image are much better at reading\nthe pillow documentation and understanding how to use it effectively. Their\nreading speeds actually match the reading speeds of redpil, even though they\nuse pillow as a backend. They even handle what pillow thinks is a forkbomb.\n\nThrough writing this module, two bugs were found in imageio that affect\nthe speed of saving images [imageio PR #398](\nhttps://github.com/imageio/imageio/pull/398), and how images were being read\n[imageio PR #399](\nhttps://github.com/imageio/imageio/pull/399#issuecomment-433992314)\n\nWith PR 398, the saving speed of imageio+pillow now matches that of redpil.\nNote I'm always using the computer when running benchmarks, so take the exact\nnumbers with a grain of salt.\n\nSaving\n```\n================ ============ ============ ============\n-- mode \n---------------- --------------------------------------\n shape redpil pillow imageio \n================ ============ ============ ============\n (128, 128) 98.3\u00b14\u03bcs 245\u00b17\u03bcs 350\u00b14\u03bcs \n (1024, 1024) 714\u00b120\u03bcs 921\u00b130\u03bcs 997\u00b120\u03bcs \n (2048, 4096) 4.83\u00b10.3ms 5.30\u00b10.4ms 5.26\u00b10.2ms\n (32768, 32768) 520\u00b140ms 516\u00b130ms 489\u00b19ms \n================ ============ ============ ============\n```\n\nReading\n```\n================ ============= ============ =============\n-- mode \n---------------- ----------------------------------------\n shape redpil pillow imageio \n================ ============= ============ =============\n (128, 128) 129\u00b10.7\u03bcs 284\u00b12\u03bcs 129\u00b10.7\u03bcs \n (1024, 1024) 191\u00b12\u03bcs 1.12\u00b10.1ms 190\u00b10.9\u03bcs \n (2048, 4096) 1.62\u00b10.03ms 8.88\u00b11ms 1.63\u00b10.02ms\n (32768, 32768) 357\u00b19ms 223\u00b14\u03bcs 361\u00b18ms \n================ ============= ============ =============\n```\n\n\n# History\n\n## 0.0.1 (2018-09-22)\n\n* First release on PyPI.\n",
"bugtrack_url": null,
"license": "MIT license",
"summary": "Join the wonderland of python, and decode all your images in a numpy compatible way",
"version": "0.2.1",
"project_urls": {
"Homepage": "https://github.com/hmaarrfk/redpil"
},
"split_keywords": [
"redpil"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "5147fbc985b8e6f6501e2d0a9e53031a19656768b25d8a0236dbc090c44c45ae",
"md5": "bbb60ae00a1900dc6d6e31ad0125d087",
"sha256": "7538e4eac35366354264005ae3ce834b35bb4a531eafc070a39e9223b7219ab3"
},
"downloads": -1,
"filename": "redpil-0.2.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "bbb60ae00a1900dc6d6e31ad0125d087",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 13155,
"upload_time": "2024-10-06T17:15:39",
"upload_time_iso_8601": "2024-10-06T17:15:39.840066Z",
"url": "https://files.pythonhosted.org/packages/51/47/fbc985b8e6f6501e2d0a9e53031a19656768b25d8a0236dbc090c44c45ae/redpil-0.2.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "aa81c187a25d7a1f7325289ce716e53815adb300d7da37750b0f03b182fe22ec",
"md5": "357ee39c9e10bb3797c4045b4e723187",
"sha256": "fba8a5330bcfd3b8e64f916b3dff323690c2ae341f009d679acc1830cbb7d932"
},
"downloads": -1,
"filename": "redpil-0.2.1.tar.gz",
"has_sig": false,
"md5_digest": "357ee39c9e10bb3797c4045b4e723187",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 20640,
"upload_time": "2024-10-06T17:15:41",
"upload_time_iso_8601": "2024-10-06T17:15:41.047190Z",
"url": "https://files.pythonhosted.org/packages/aa/81/c187a25d7a1f7325289ce716e53815adb300d7da37750b0f03b182fe22ec/redpil-0.2.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-10-06 17:15:41",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "hmaarrfk",
"github_project": "redpil",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"tox": true,
"lcname": "redpil"
}
JSON
