A simpler wrapper around qoi (https://github.com/phoboslab/qoi)

These details have not been verified by PyPI

Project links

Project description

QOI

A simple Python wrapper around qoi, the "Quite OK Image" image format. It's

Lossless with comparable compression to PNG.
Fast! It encodes 10x faster and decodes around 5x faster than PNG in OpenCV or PIL. It's still a whole lot faster than JPEG, even though that's lossy.

Install

pip install qoi

Example

import numpy as np
import qoi

# Get your image as a numpy array (OpenCV, Pillow, etc. but here we just create a bunch of noise)
rgb = np.random.randint(low=0, high=255, size=(224, 244, 3)).astype(np.uint8)

# Write it:
_ = qoi.write("/tmp/img.qoi", rgb)

# Read it and check it matches (it should, as we're lossless)
rgb_read = qoi.read("/tmp/img.qoi")
assert np.array_equal(rgb, rgb_read)

# Likewise for encode/decode to/from bytes:
bites = qoi.encode(rgb)
rgb_decoded = qoi.decode(bites)
assert np.array_equal(rgb, rgb_decoded)

# Benchmarking
from qoi.benchmark import benchmark
benchmark()  # Check out the arguments if you're interested

Benchmarks

If we consider lossless, then we're generally comparing with PNG. Yup, there are others, but they're not as common. Benchmarks:

Test image	Method	Format	Input (kb)	Encode (ms)	Encode (kb)	Decode (ms)
all black ('best' case)	PIL	png	6075.0	35.54	6.0	14.94
all black ('best' case)	opencv	png	6075.0	19.93	7.7	15.18
all black ('best' case)	qoi	qoi	6075.0	3.93	32.7	2.41
random noise (worst case)	PIL	png	6075.0	272.33	6084.5	42.28
random noise (worst case)	opencv	png	6075.0	58.33	6086.9	12.93
random noise (worst case)	qoi	qoi	6075.0	15.71	8096.1	8.04

So qoi isn't far off PNG in terms of compression, but 4x-20x faster to encode and 1.5x-6x faster to decode.

NB:

There's additional overhead here with PIL images being converted back to an array as the return type, to be consistent. In some sense, this isn't fair, as PIL will be faster if you're dealing with PIL images. On the other hand, if your common use case involves arrays (e.g. for computer vision) then it's reasonable.

Produced with qoi.benchmark.benchmark(jpg=False) on an i7-9750H. Not going to the point of optimised OpenCV/PIL (e.g. SIMD, or pillow-simd) as the results are clear enough for this 'normal' scenario. If you want to dig further, go for it! You can easily run these tests yourself.

If we consider lossy compression, again, JPEG is usually what we're comparing with. This isn't really a far comparison as QOI is lossless and JPEG is lossy, but let's see.

Test image	Method	Format	Input (kb)	Encode (ms)	Encode (kb)	Decode (ms)
all black ('best' case)	PIL	jpg	6075.0	30.33	32.5	18.44
all black ('best' case)	opencv	jpg	6075.0	21.52	32.5	14.31
all black ('best' case)	qoi	qoi	6075.0	4.29	32.7	2.60
random noise (worst case)	PIL	jpg	6075.0	97.80	1217.3	45.55
random noise (worst case)	opencv	jpg	6075.0	39.62	2376.2	38.31
random noise (worst case)	qoi	qoi	6075.0	19.34	8096.1	7.90

Here we see that qoi is losing out considerably in compression, as expected for lossy vs lossless. Nonetheless, qoi is still 2x-6x faster to encode, and 5x-7x faster to decode. So, there are definitely use cases where qoi may still make sense over JPEG ... especially if you want lossless.

NB:

See above re additional PIL overhead.

Produced with qoi.benchmark.benchmark(png=False) on an i7-9750H. Not going to the point of optimised OpenCV/PIL (e.g. SIMD, or pillow-simd, libjpeg-turbo, different JPEG qualities, etc.) as the results are clear enough for this 'normal' scenario. If you want to dig further, go for it! You can easily run these tests yourself.

Developing

git clone --recursive https://github.com/kodonnell/qoi/
USE_CYTHON=1 pip install -e .[dev]
pytest .

We use cibuildwheel to build all the wheels, which runs in a Github action. If you want to check this succeeds locally, you can try (untested):

cibuildwheel --platform linux .

Finally, when you're happy, submit a PR.

Publishing

When you're on main on your local, git tag vX.X.X then git push origin vX.X.X. This pushes the tag which triggers the full GitHub Action and:

Builds source distribution and wheels (for various platforms)
Pushes to PyPI
Creates a new release with the appropriate artifacts attached.

TODO:

Get cp310-win32 building ...
Create a qoi CLI
Benchmarks - add real images, and also compare performance with QOI to see overhead of python wrapper.
setuptools_scm_git_archive?
Code completion?
Investigate a simple 'lossy' compression with QOI - halve the image size and compress, and on decode, just upscale. It'll likely be very visually similar, but also much smaller, but should compare with JPEG.

Discussion

Wrap or rewrite?

For now, this is just a simple wrapper. We'll leave the original project to do all the hard work on performance etc., and also maintaining (or not) compatibility or adding new features etc. We make no claims to do any more than that - we're basically just porting that C functionality to (C)Python.

On the name

For now, let's rock with qoi because

We're already in python, and the py in pyqoi seems redundant. For what it's worth, 3 < 5.
pyqoi seems like a good name for a python-only version of QOI (useful for pypy etc.), which this isn't.
qoi is generally new so let's not overthink it for now. We can always rename later if needed.

What's up with `./src`?!

See here and here. I didn't read all of it, but yeh, import qoi is annoying when there's also a folder called qoi.

`USE_CTYHON=1`?

See here. Fair point.

Project details

These details have not been verified by PyPI

Project links

Release history Release notifications | RSS feed

0.7.0

Jun 23, 2024

0.6.0

Apr 20, 2024

0.5.0

Dec 13, 2023

0.4.0

Dec 11, 2023

0.3.1

Mar 31, 2023

0.3.0

Mar 17, 2023

0.2.0

Jul 21, 2022

0.1.2

Jun 29, 2022

0.1.1

Jun 5, 2022

This version

0.0.9

Dec 30, 2021

0.0.8

Dec 29, 2021

0.0.6

Dec 21, 2021

0.0.5

Dec 20, 2021

0.0.4

Dec 6, 2021

0.0.3

Dec 6, 2021

0.0.2

Dec 6, 2021

0.0.1

Dec 5, 2021

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

qoi-0.0.9.tar.gz (73.2 kB view details)

Uploaded Dec 30, 2021 Source

Built Distributions

qoi-0.0.9-cp310-cp310-win_amd64.whl (37.2 kB view details)

Uploaded Dec 30, 2021 CPython 3.10 Windows x86-64

qoi-0.0.9-cp310-cp310-manylinux_2_5_x86_64.manylinux1_x86_64.manylinux_2_17_x86_64.manylinux2014_x86_64.whl (152.4 kB view details)

Uploaded Dec 30, 2021 CPython 3.10 manylinux: glibc 2.17+ x86-64 manylinux: glibc 2.5+ x86-64

qoi-0.0.9-cp310-cp310-manylinux_2_5_i686.manylinux1_i686.manylinux_2_17_i686.manylinux2014_i686.whl (146.1 kB view details)

Uploaded Dec 30, 2021 CPython 3.10 manylinux: glibc 2.17+ i686 manylinux: glibc 2.5+ i686

qoi-0.0.9-cp310-cp310-macosx_10_9_x86_64.whl (36.8 kB view details)

Uploaded Dec 30, 2021 CPython 3.10 macOS 10.9+ x86-64

qoi-0.0.9-cp39-cp39-win_amd64.whl (37.2 kB view details)

Uploaded Dec 30, 2021 CPython 3.9 Windows x86-64

qoi-0.0.9-cp39-cp39-win32.whl (32.4 kB view details)

Uploaded Dec 30, 2021 CPython 3.9 Windows x86

qoi-0.0.9-cp39-cp39-manylinux_2_5_x86_64.manylinux1_x86_64.manylinux_2_17_x86_64.manylinux2014_x86_64.whl (151.7 kB view details)

Uploaded Dec 30, 2021 CPython 3.9 manylinux: glibc 2.17+ x86-64 manylinux: glibc 2.5+ x86-64

qoi-0.0.9-cp39-cp39-manylinux_2_5_i686.manylinux1_i686.manylinux_2_17_i686.manylinux2014_i686.whl (145.3 kB view details)

Uploaded Dec 30, 2021 CPython 3.9 manylinux: glibc 2.17+ i686 manylinux: glibc 2.5+ i686

qoi-0.0.9-cp39-cp39-macosx_10_9_x86_64.whl (36.8 kB view details)

Uploaded Dec 30, 2021 CPython 3.9 macOS 10.9+ x86-64

qoi-0.0.9-cp38-cp38-win_amd64.whl (37.2 kB view details)

Uploaded Dec 30, 2021 CPython 3.8 Windows x86-64

qoi-0.0.9-cp38-cp38-win32.whl (32.4 kB view details)

Uploaded Dec 30, 2021 CPython 3.8 Windows x86

qoi-0.0.9-cp38-cp38-manylinux_2_5_x86_64.manylinux1_x86_64.manylinux_2_17_x86_64.manylinux2014_x86_64.whl (157.5 kB view details)

Uploaded Dec 30, 2021 CPython 3.8 manylinux: glibc 2.17+ x86-64 manylinux: glibc 2.5+ x86-64

qoi-0.0.9-cp38-cp38-manylinux_2_5_i686.manylinux1_i686.manylinux_2_17_i686.manylinux2014_i686.whl (152.3 kB view details)

Uploaded Dec 30, 2021 CPython 3.8 manylinux: glibc 2.17+ i686 manylinux: glibc 2.5+ i686

qoi-0.0.9-cp38-cp38-macosx_10_9_x86_64.whl (36.0 kB view details)

Uploaded Dec 30, 2021 CPython 3.8 macOS 10.9+ x86-64

qoi-0.0.9-cp37-cp37m-win_amd64.whl (36.8 kB view details)

Uploaded Dec 30, 2021 CPython 3.7m Windows x86-64

qoi-0.0.9-cp37-cp37m-win32.whl (32.1 kB view details)

Uploaded Dec 30, 2021 CPython 3.7m Windows x86

qoi-0.0.9-cp37-cp37m-manylinux_2_5_x86_64.manylinux1_x86_64.manylinux_2_17_x86_64.manylinux2014_x86_64.whl (146.0 kB view details)

Uploaded Dec 30, 2021 CPython 3.7m manylinux: glibc 2.17+ x86-64 manylinux: glibc 2.5+ x86-64

qoi-0.0.9-cp37-cp37m-manylinux_2_5_i686.manylinux1_i686.manylinux_2_17_i686.manylinux2014_i686.whl (139.6 kB view details)

Uploaded Dec 30, 2021 CPython 3.7m manylinux: glibc 2.17+ i686 manylinux: glibc 2.5+ i686

qoi-0.0.9-cp37-cp37m-macosx_10_9_x86_64.whl (35.6 kB view details)

Uploaded Dec 30, 2021 CPython 3.7m macOS 10.9+ x86-64

File details

Details for the file qoi-0.0.9.tar.gz.

File metadata

Download URL: qoi-0.0.9.tar.gz
Upload date: Dec 30, 2021
Size: 73.2 kB
Tags: Source
Uploaded using Trusted Publishing? No
Uploaded via: twine/3.7.1 importlib_metadata/4.10.0 pkginfo/1.8.2 requests/2.26.0 requests-toolbelt/0.9.1 tqdm/4.62.3 CPython/3.9.9

File hashes

Hashes for qoi-0.0.9.tar.gz
Algorithm	Hash digest
SHA256	`5c99b0966f1b6bd0f257372c3b118de6271c27e5d2d5a9b289ea4b8f2fbb8321`
MD5	`d78535f74ed3bf75aeef311f8688ec54`
BLAKE2b-256	`04f896cf8d289eaf9074aa02726e91eee4ff20295f52c40177f3e9a4250fb674`

Algorithm	Hash digest
SHA256	`8df3a7f7f07a96c96a2b4449cf8b088f0ab89ac6121078dc481ae27e2026aa94`
MD5	`6bc405832f11c65ca29fa81592afe169`
BLAKE2b-256	`0116508485d6db9528acf9315fb1517f0f311fa55849315faa48cd35d42e066a`

Algorithm	Hash digest
SHA256	`455d5e15e913cfd067aab6b7417fed9e85651e2fd90e2b9685c2b143a9d785f8`
MD5	`af88134d67b3bd69ca0844375c1c7d45`
BLAKE2b-256	`e108c0dfaa781c5d456a4fa51c5d6981a0861438fefbd9041d065c042912c614`

Algorithm	Hash digest
SHA256	`0e97a2bb12a42576849ce28a17c2b74dbff5722ed85237259a9a7c5e4612197a`
MD5	`db59cc90054892bad95c2568c33df116`
BLAKE2b-256	`70cf9b5dd4db9c9bea07cc3724335964f82fd7cbedbe0fd495764bd66d7033f2`

Algorithm	Hash digest
SHA256	`67a544f3ebafd8c065b3f14b5d2c43385e37a7d9b0a6b5ea884ade2f9ca18f4e`
MD5	`b2c535260a4a44251944397f5974b027`
BLAKE2b-256	`6126aa88e3001bfce318a3548ef97949db64df396329c9b7a3a6855b64b2a1cb`

Algorithm	Hash digest
SHA256	`1838f849d1e2d3a4e146c8562546756c643a4083aa03e0a40d34ebb4c629a6ac`
MD5	`f85408b15cb232d3c4da5830b7191a1a`
BLAKE2b-256	`d193f388fa5ed90d5c29575146641b7eef6be2de40f3bfc8c068561dca8355ca`

Algorithm	Hash digest
SHA256	`b122e768f9682ac22d48a276c42a2438c879177d5ebb5a0ea6e11848caf22498`
MD5	`7bf639f2c5c785e7f2d084484029a82c`
BLAKE2b-256	`3db79730846a5b1aaa9eefa7a2858048ff506b545a0e733b6cbc79e6c236e39e`

Algorithm	Hash digest
SHA256	`b219bbf53e2ae50a48e729270869e468d80e07fb6c5703e2e7cb44762cc35896`
MD5	`59ebcee5b2d66e3db8ee0a2c1ae544e4`
BLAKE2b-256	`e1d5dc2239d1f812b065cd306c35bccb28f3f249e2daaf56a1914f508c1e27be`

Algorithm	Hash digest
SHA256	`3d87dcdf08b43d9334d4a1cafd5b89668b3b6bf1da47b5157ad52912b39806ae`
MD5	`1b894f32f406a14e308730de5f5431ac`
BLAKE2b-256	`1c39c1add508f5609ab5a96c08685dc17a3c55d92e2275e7e4f03d56cfe88c90`

Algorithm	Hash digest
SHA256	`5b8ae6ecbd07f4f6009124387604969cbed9d1c7766acef44073273121893de9`
MD5	`21096559760958d5cb9c018fbb8a7a5d`
BLAKE2b-256	`44652810a238965f40be412ca92b9005c89d7e8f36a27abd97c77cbe1f95f06c`

Algorithm	Hash digest
SHA256	`44c020ddd23833404607a197967124ecaceb76ca77e641257f77adf861496b79`
MD5	`f4d3d4bb54537d27496dd2db43f130a4`
BLAKE2b-256	`69ee22475abb69bd8568d3af7e933ae5bb92d4036a3a001e9f0790b022744a14`

Algorithm	Hash digest
SHA256	`48009821c44b1e438f7079c311e081199372eb7ad7995d507130188ecef7ab18`
MD5	`8dfe5a0ab2e1510179f789ed9dd34bbd`
BLAKE2b-256	`c593ec2a82ecf65a953cfa8010a2927377f6704e576150f0d8c7a6853606eda9`

Algorithm	Hash digest
SHA256	`3057fc9374b3977c7610d31dce3ecd4f269054b391ae61b51e7f6fb37012f15d`
MD5	`a6a0e43ec17329737b2a929a7899deef`
BLAKE2b-256	`96d8dbfe1d7aabf0daddc73fcf7ea759a25e1edf8daedd38f313d782ae2476cd`

Algorithm	Hash digest
SHA256	`2489b0a5f188cdb4c981c3f049dded5e47e90a2037538a87953e59f4ead3fe9d`
MD5	`050760786a5e4d863bc85007fea1c998`
BLAKE2b-256	`bf9453e96ac4f7c3631157f3dd6a4c851b2f7037b1adc499b37a2e78d2a7833b`

Algorithm	Hash digest
SHA256	`d6ad8e33558b8eeab6d09b576f39bdffb0e03859312f2a22a4e21e6785ad01b4`
MD5	`79c003cc43f8c848462a7a3d0e83b495`
BLAKE2b-256	`e5ae0f783eba511deabba5b694d4ae39d8af999dcb99f91f1bbda5120f20d168`

Algorithm	Hash digest
SHA256	`54d5e923c9834193ee490986e856ee5d1656534c9ba1c89551885443f49131b3`
MD5	`cd6dd51e01fba6b14c74339fd4510136`
BLAKE2b-256	`bba2755c3af8b13ee18acd03be92c9a72494c8db9c4a47da16c2ce7dfff58401`

Algorithm	Hash digest
SHA256	`119aaabb08126169d3f1c0ca3328f761dc3063d809838bcdc106b1e90d083fd8`
MD5	`0719f4afae4de8bbc09485cbb600c0a5`
BLAKE2b-256	`83f10ef8d7a29af1de043455b2a8027c2d66b661373e494ec77cd637b0dab0b9`

Algorithm	Hash digest
SHA256	`f19140cca1052aac2766dabeb627ec27dcfa397cffee9fba1bb8409eca1b2744`
MD5	`1935d12ad4d18f03f135713e34f2ae19`
BLAKE2b-256	`413219347fc60e529c9ddad5ec9059c889f771a2cc8b7e07d52db89701eed824`

Algorithm	Hash digest
SHA256	`4f450d86b7769fb42d824ae4b15d441732c10e631538038e4ce89164dd5b7de5`
MD5	`1d6eb85fbb06d2e587be23faff8e2ad8`
BLAKE2b-256	`81a85232fd6324f3829acf2e591778fa75768d36225d3d1917d83f26598be6d3`

Algorithm	Hash digest
SHA256	`e2bf7fc5d004eb13f245cd2a021da8a334caad746c5525a227622f37ac520d32`
MD5	`da3f94a5045cdc4df2de2bcec30375d9`
BLAKE2b-256	`f042212150647d6d356bfdf82ec440932fe38f7a721f8e94dcbb4f9f293248b8`

qoi 0.0.9

Navigation

Verified details

Maintainers

Unverified details

Project links

Meta

Classifiers

Project description

QOI

Install

Example

Benchmarks

Developing

Publishing

TODO:

Discussion

Wrap or rewrite?

On the name

What's up with ./src?!

USE_CTYHON=1?

Project details

Verified details

Maintainers

Unverified details

Project links

Meta

Classifiers

Release history Release notifications | RSS feed

Download files

Source Distribution

Built Distributions

File details

File metadata

File hashes

File details

File metadata

File hashes

File details

File metadata

File hashes

File details

File metadata

File hashes

File details

File metadata

File hashes

File details

File metadata

File hashes

File details

File metadata

File hashes

File details

File metadata

File hashes

File details

File metadata

File hashes

File details

File metadata

File hashes

File details

File metadata

File hashes

File details

File metadata

File hashes

File details

File metadata

File hashes

File details

File metadata

File hashes

File details

File metadata

File hashes

File details

File metadata

File hashes

What's up with `./src`?!

`USE_CTYHON=1`?