|
| 1 | + |
| 2 | + |
| 3 | +# QOI - The “Quite OK Image Format” for fast, lossless image compression |
| 4 | + |
| 5 | +Single-file MIT licensed library for C/C++ |
| 6 | + |
| 7 | +See [qoi.h](https://github.com/phoboslab/qoi/blob/master/qoi.h) for |
| 8 | +the documentation and format specification. |
| 9 | + |
| 10 | +More info at https://qoiformat.org |
| 11 | + |
| 12 | + |
| 13 | +## Why? |
| 14 | + |
| 15 | +QOI offers sweet-spot of compression ratio and throughput for lossless |
| 16 | +image encoding. QOI's compression is roughly comparable to PNG (usually worse than |
| 17 | +[libPNG](https://github.com/pnggroup/libpng), but better than [stb_image_write.h](https://github.com/nothings/stb/blob/master/stb_image_write.h)), while throughput is a lot higher. |
| 18 | + |
| 19 | +Benchmark results on a few thousand images can be found here: https://qoiformat.org/benchmark/ |
| 20 | + |
| 21 | +The QOI format is also extremely simple, which helps a lot when porting to other languages. |
| 22 | + |
| 23 | + |
| 24 | +## Example Usage |
| 25 | + |
| 26 | +- [qoiconv.c](https://github.com/phoboslab/qoi/blob/master/qoiconv.c) |
| 27 | +converts between png <> qoi |
| 28 | + - [qoibench.c](https://github.com/phoboslab/qoi/blob/master/qoibench.c) |
| 29 | +a simple wrapper to benchmark stbi, libpng and qoi |
| 30 | + |
| 31 | + |
| 32 | +## MIME Type, File Extension |
| 33 | + |
| 34 | +The recommended MIME type for QOI images is `image/qoi`. While QOI is not yet |
| 35 | +officially registered with IANA, I believe QOI has found enough adoption to |
| 36 | +prevent any future image format from choosing the same name, thus making a |
| 37 | +MIME type collision highly unlikely ([see #167](https://github.com/phoboslab/qoi/issues/167)). |
| 38 | + |
| 39 | +The recommended file extension for QOI images is `.qoi` |
| 40 | + |
| 41 | + |
| 42 | +## Limitations |
| 43 | + |
| 44 | +The QOI file format allows for huge images with up to 18 exa-pixels. A streaming |
| 45 | +en-/decoder can handle these with minimal RAM requirements, assuming there is |
| 46 | +enough storage space. |
| 47 | + |
| 48 | +This particular implementation of QOI however is limited to images with a |
| 49 | +maximum size of 400 million pixels. It will safely refuse to en-/decode anything |
| 50 | +larger than that. This is not a streaming en-/decoder. It loads the whole image |
| 51 | +file into RAM before doing any work and is not extensively optimized for |
| 52 | +performance (but it's still very fast). |
| 53 | + |
| 54 | +If this is a limitation for your use case, please look into any of the other |
| 55 | +implementations listed below. |
| 56 | + |
| 57 | + |
| 58 | +## Improvements, New Versions and Contributing |
| 59 | + |
| 60 | +The QOI format has been finalized. It was a conscious decision to **not** have a |
| 61 | +version number in the file header. If you have a working QOI implementation today, |
| 62 | +you can rest assured that it will be compatible with all QOI files tomorrow. |
| 63 | + |
| 64 | +There are a lot of interesting ideas for a successor of QOI, but none of these will |
| 65 | +be implemented here. That doesn't mean you shouldn't experiment with QOI, but please |
| 66 | +be aware that pull requests that change the format will not be accepted. |
| 67 | + |
| 68 | +Likewise, pull requests for performance improvements will probably not be accepted |
| 69 | +either, as this "reference implementation" tries to be as easy to read as possible. |
| 70 | + |
| 71 | + |
| 72 | +## Tools |
| 73 | + |
| 74 | +- [floooh/qoiview](https://github.com/floooh/qoiview) - native QOI viewer |
| 75 | +- [pfusik/qoi-fu](https://github.com/pfusik/qoi-fu/releases) - QOI Plugin installer for Windows Explorer, Finder, GNOME, GIMP 2, Paint.NET and XnView |
| 76 | +- [iOrange/QoiFileTypeNet](https://github.com/iOrange/QoiFileTypeNet/releases) - QOI Plugin for Paint.NET |
| 77 | +- [iOrange/QOIThumbnailProvider](https://github.com/iOrange/QOIThumbnailProvider) - Add thumbnails for QOI images in Windows Explorer |
| 78 | +- [Tom94/tev](https://github.com/Tom94/tev) - another native QOI viewer (allows pixel peeping and comparison with other image formats) |
| 79 | +- [wkjarosz/hdrview](https://github.com/wkjarosz/hdrview) - research-oriented HDR/LDR image viewer with QOI read/write support; runs natively or in-browser |
| 80 | +- [qoiconverterx](https://apps.apple.com/br/app/qoiconverterx/id1602159820) QOI <=> PNG converter available on the Mac App Store |
| 81 | +- [kaetemi/qoi-ma](https://github.com/kaetemi/qoi-max) - QOI Bitmap I/O Plugin for 3ds Max |
| 82 | +- [rtexviewer](https://raylibtech.itch.io/rtexviewer) - texture viewer, supports QOI |
| 83 | +- [rtexpacker](https://raylibtech.itch.io/rtexpacker) - texture packer, supports QOI |
| 84 | +- [DmitriySalnikov/godot_qoi](https://github.com/DmitriySalnikov/godot_qoi) - QOI GDNative Addon for Godot Engine |
| 85 | +- [dan9er/farbfeld-convert-qoi](https://gitlab.com/dan9er/farbfeld-convert-qoi) - QOI <=> farbfeld converter |
| 86 | +- [LTMX/Unity.QOI](https://github.com/LTMX/Unity.QOI) - QOI Importer and Exporter for the Unity3D Game Engine |
| 87 | +- [Ben1138/unity-qoi](https://github.com/Ben1138/unity-qoi) - QOI Importer(only) support for the Unity3D Game Engine |
| 88 | +- [xiaozhuai/jetbrains-qo](https://github.com/xiaozhuai/jetbrains-qoi) - [QOI Support](https://plugins.jetbrains.com/plugin/19352-qoi-support) for Jetbrains' IDE. |
| 89 | +- [serge-ivamov/QOIql](https://github.com/serge-ivamov/QOIql) - MacOS QuickLook plugin for QOI |
| 90 | +- [tobozo/kde-thumbnailer-qoi](https://github.com/tobozo/kde-thumbnailer-qoi) - QOI Thumbnailer for KDE |
| 91 | +- [walksanatora/qoi-thumbnailer-nemo](https://github.com/walksanatora/qoi-thumbnailer-nemo) - QOI Thumbnailer for Nemo |
| 92 | +- [hzeller/timg](https://github.com/hzeller/timg) - a terminal image viewer with QOI support |
| 93 | +- [LuisAlfredo92/Super-QOI-converter](https://github.com/LuisAlfredo92/Super-QOI-converter "LuisAlfredo92/Super-QOI-converter") - A program to convert JPG, JPEG, BMP, and PNG to QOI |
| 94 | + - [Console version](https://github.com/LuisAlfredo92/Super-QOI-converter-Console- "Console version"): Available for Linux, OSX and Windows |
| 95 | + - [GUI version](https://github.com/LuisAlfredo92/Super-QOI-converter-GUI- "GUI version"): Available only for windows |
| 96 | +- [tacent view](https://github.com/bluescan/tacentview) - Image and texture viewer, supports QOI |
| 97 | +- [colemanrgb/qoi2spr](https://github.com/colemanrgb/qoi2spr) - A variety of applications for decoding and encoding of QOI images on [RISC OS](https://www.riscosopen.org/) |
| 98 | +- [Muppetsg2/UnrealQOI](https://github.com/Muppetsg2/UnrealQOI) - QOI Format Import/Export plugin for Unreal Engine 5 |
| 99 | + |
| 100 | +## Implementations & Bindings of QOI |
| 101 | + |
| 102 | +- [pfusik/qoi-fu](https://github.com/pfusik/qoi-fu) - Fusion, transpiling to C, C++, C#, D, Java, JavaScript, Python, Swift and TypeScript |
| 103 | +- [kodonnell/qoi](https://github.com/kodonnell/qoi) - Python |
| 104 | +- [JaffaKetchup/dqoi](https://github.com/JaffaKetchup/dqoi) - Dart, with Flutter support |
| 105 | +- [Cr4xy/lua-qoi](https://github.com/Cr4xy/lua-qoi) - Lua |
| 106 | +- [superzazu/SDL_QOI](https://github.com/superzazu/SDL_QOI) - C, SDL2 bindings |
| 107 | +- [saharNooby/qoi-java](https://github.com/saharNooby/qoi-java) - Java |
| 108 | +- [MasterQ32/zig-qoi](https://github.com/MasterQ32/zig-qoi) - Zig |
| 109 | +- [rbino/qoix](https://github.com/rbino/qoix) - Elixir |
| 110 | +- [NUlliiON/QoiSharp](https://github.com/NUlliiON/QoiSharp) - C# |
| 111 | +- [aldanor/qoi-rust](https://github.com/aldanor/qoi-rust) - Rust |
| 112 | +- [zakarumych/rapid-qoi](https://github.com/zakarumych/rapid-qoi) - Rust |
| 113 | +- [takeyourhatoff/qoi](https://github.com/takeyourhatoff/qoi) - Go |
| 114 | +- [DosWorld/pasqoi](https://github.com/DosWorld/pasqoi) - Pascal |
| 115 | +- [elihwyma/Swift-QOI](https://github.com/elihwyma/Swift-QOI) - Swift |
| 116 | +- [xfmoulet/qoi](https://github.com/xfmoulet/qoi) - Go |
| 117 | +- [erratique.ch/qoic](https://erratique.ch/software/qoic) - OCaml |
| 118 | +- [arian/go-qoi](https://github.com/arian/go-qoi) - Go |
| 119 | +- [kchapelier/qoijs](https://github.com/kchapelier/qoijs) - JavaScript |
| 120 | +- [KristofferC/QOI.jl](https://github.com/KristofferC/QOI.jl) - Julia |
| 121 | +- [shadowMitia/libqoi](https://github.com/shadowMitia/libqoi) - C++ |
| 122 | +- [MKCG/php-qoi](https://github.com/MKCG/php-qoi) - PHP |
| 123 | +- [LightHouseSoftware/qoiformats](https://github.com/LightHouseSoftware/qoiformats) - D |
| 124 | +- [mhoward540/qoi-nim](https://github.com/mhoward540/qoi-nim) - Nim |
| 125 | +- [wx257osn2/qoixx](https://github.com/wx257osn2/qoixx) - C++ |
| 126 | +- [Tiefseetauchner/lr-paint](https://github.com/Tiefseetauchner/lr-paint) - Processing |
| 127 | +- [amstan/qoi-fpga](https://github.com/amstan/qoi-fpga) - FPGA: verilog |
| 128 | +- [musabkilic/qoi-decoder](https://github.com/musabkilic/qoi-decoder) - Python |
| 129 | +- [mathpn/py-qoi](https://github.com/mathpn/py-qoi) - Python |
| 130 | +- [Joshix/qoi-rs-python](https://codeberg.org/Joshix/qoi-rs-python/) - Python |
| 131 | +- [JohannesFriedrich/qoi4R](https://github.com/JohannesFriedrich/qoi4R) - R |
| 132 | +- [shraiwi/mini-qoi](https://github.com/shraiwi/mini-qoi) - C, streaming decoder |
| 133 | +- [10maurycy10/libqoi/](https://github.com/10maurycy10/libqoi/) - Rust |
| 134 | +- [0xd34df00d/hsqoi](https://github.com/0xd34df00d/hsqoi) - Haskell |
| 135 | +- [418Coffee/qoi-v](https://github.com/418Coffee/qoi-v) - V |
| 136 | +- [Imagine-Programming/QoiImagePlugin](https://github.com/Imagine-Programming/QoiImagePlugin) - PureBasic |
| 137 | +- [Fabien-Chouteau/qoi-spark](https://github.com/Fabien-Chouteau/qoi-spark) - Ada/SPARK formally proven |
| 138 | +- [mzgreen/qoi-kotlin](https://github.com/mzgreen/qoi-kotlin) - Kotlin Multiplatform |
| 139 | +- [Aftersol/Simplified-QOI-Codec](https://github.com/Aftersol/Simplified-QOI-Codec) - C99, encoder and decoder, freestanding |
| 140 | +- [AuburnSounds/gamut](https://github.com/AuburnSounds/gamut) - D |
| 141 | +- [AngusJohnson/TQoiImage](https://github.com/AngusJohnson/TQoiImage) - Delphi |
| 142 | +- [MarkJeronimus/qoi-java-spi](https://github.com/MarkJeronimus/qoi-java-spi) - Java SPI |
| 143 | +- [aumouvantsillage/qoi-racket](https://github.com/aumouvantsillage/qoi-racket) - Racket |
| 144 | +- [rubikscraft/qoi-stream](https://github.com/rubikscraft/qoi-stream) - C99, one byte at a time streaming encoder and decoder |
| 145 | +- [rubikscraft/qoi-img](https://github.com/rubikscraft/qoi-img) - NodeJS typescript, bindings to both [QOIxx](https://github.com/wx257osn2/qoixx) and [qoi-stream](https://github.com/rubikscraft/qoi-stream) |
| 146 | +- [grego/hare-qoi](https://git.sr.ht/~grego/hare-qoi) - Hare |
| 147 | +- [MrNocole/ZTQOI](https://github.com/MrNocole/ZTQOI) - Objective-C |
| 148 | +- [bpanthi977/qoi](https://github.com/bpanthi977/qoi) - Common Lisp |
| 149 | +- [Floessie/pam2qoi](https://github.com/Floessie/pam2qoi) - C++ |
| 150 | +- [SpeckyYT/spwn-qoi](https://github.com/SpeckyYT/spwn-qoi) - SPWN |
| 151 | +- [n00bmind/qoi](https://github.com/n00bmind/qoi) - Jai |
| 152 | +- [SixLabors/ImageSharp](https://github.com/SixLabors/ImageSharp) - C# image proccesing library |
| 153 | +- [zertovitch/gid](https://github.com/zertovitch/gid) - Ada |
| 154 | +- [nazrin/lil](https://codeberg.org/nazrin/lil) - Lua image library |
| 155 | +- [Hema2-official/qoi-c3](https://github.com/Hema2-official/qoi-c3) - C3 |
| 156 | +- [kwon-young/qoi-prolog](https://github.com/kwon-young/qoi-prolog) - Prolog |
| 157 | +- [google/wuffs](https://github.com/google/wuffs) - Wuffs |
| 158 | +- [dokutan/qoi-bf](https://github.com/dokutan/qoi-bf) - Brainfuck |
| 159 | +- [alex-s168/uiua-qoi](https://github.com/alex-s168/uiua-qoi) - Uiua |
| 160 | +- [hchargois/qoi](https://github.com/hchargois/qoi) - Go |
| 161 | +- [coralpink/qoi.cr](https://codeberg.org/coralpink/qoi.cr) - Crystal |
| 162 | +- [Pivok7/zqoi](https://github.com/Pivok7/zqoi) - Zig |
| 163 | +- [Muppetsg2/koi](https://github.com/Muppetsg2/koi) - stb-like single-file, public domain (or MIT-licensed) image processing libraries for C/C++ |
| 164 | + |
| 165 | +## QOI Support in Other Software |
| 166 | + |
| 167 | +- [Amiga OS QOI datatype](https://github.com/dgaw/qoi-datatype) - adds support for decoding QOI images to the Amiga operating system. |
| 168 | +- [SerenityOS](https://github.com/SerenityOS/serenity) - supports decoding QOI system wide through a custom [cpp implementation in LibGfx](https://github.com/SerenityOS/serenity/blob/master/Userland/Libraries/LibGfx/ImageFormats/QOILoader.h) |
| 169 | +- [Raylib](https://github.com/raysan5/raylib) - supports decoding and encoding QOI textures through its [rtextures module](https://github.com/raysan5/raylib/blob/master/src/rtextures.c) |
| 170 | +- [Rebol3](https://github.com/Oldes/Rebol3/issues/39) - supports decoding and encoding QOI using a native codec |
| 171 | +- [c-ray](https://github.com/vkoskiv/c-ray) - supports QOI natively |
| 172 | +- [SAIL](https://sail.software) - image decoding library, supports decoding and encoding QOI images |
| 173 | +- [Orx](https://github.com/orx/orx) - 2D game engine, supports QOI natively |
| 174 | +- [IrfanView](https://www.irfanview.com) - supports decoding and encoding QOI through its Formats plugin |
| 175 | +- [ImageMagick](https://github.com/ImageMagick/ImageMagick) - supports decoding and encoding QOI, since 7.1.0-20 |
| 176 | +- [barebox](https://barebox.org) - bootloader, supports decoding QOI images for splash logo, since v2022.03.0 |
| 177 | +- [KorGE](https://korge.org) - & KorIM Kotlin 2D game engine and imaging library, supports decoding and encoding QOI natively since 2.7.0 |
| 178 | +- [DOjS](https://github.com/SuperIlu/DOjS) - DOS JavaScript Canvas implementation supports loading QOI files |
| 179 | +- [XnView MP](https://www.xnview.com/en/xnviewmp/) - supports decoding QOI since 1.00 |
| 180 | +- [ffmpeg](https://ffmpeg.org/) - supports decoding and encoding QOI since 5.1 |
| 181 | +- [JPEGView](https://github.com/sylikc/jpegview) - lightweight Windows image viewer, supports decoding and encoding of QOI natively, since 1.1.44 |
| 182 | +- [darktable](https://github.com/darktable-org/darktable) - photography workflow application and raw developer, supports decoding since 4.4.0 |
| 183 | +- [KDE](https://kde.org) - supports decoding and encoding QOI images. Implemented in [KImageFormats](https://invent.kde.org/frameworks/kimageformats) |
| 184 | +- [EFL](https://www.enlightenment.org) - supports decoding and encoding QOI images since 1.27. |
| 185 | +- [Swingland](https://git.sr.ht/~phlash/swingland) - supports QOI decoding/loading via the `ImageIO` API of this Java Swing reimplemenation for Wayland |
| 186 | +- [Imagine](https://www.nyam.pe.kr/dev/imagine/) - supports decoding and encoding QOI images since 1.3.9 |
| 187 | +- [Uiua](https://uiua.org) - supports decoding and encoding QOI images since 0.8.0 |
| 188 | +- [Google Earth Pro](https://www.google.com/intl/en_uk/earth/about/versions/#download-pro) - supports Movie Maker export as sequence of QOI images since 7.3.6 |
| 189 | +- [GIMP](https://www.gimp.org) - supports decoding and encoding QOI images since 3.0 |
| 190 | + |
| 191 | +## Packages |
| 192 | + |
| 193 | +- [AUR](https://aur.archlinux.org/pkgbase/qoi-git/) - system-wide qoi.h, qoiconv and qoibench install as split packages. |
| 194 | +- [Debian](https://packages.debian.org/bookworm/source/qoi) - packages for binaries and qoi.h |
| 195 | +- [Ubuntu](https://launchpad.net/ubuntu/+source/qoi) - packages for binaries and qoi.h |
| 196 | +- [Fedora](https://packages.fedoraproject.org/pkgs/qoi) - packages for binaries and qoi.h |
| 197 | + |
| 198 | +Packages for other systems [tracked at Repology](https://repology.org/project/qoi/versions). |
0 commit comments