qoi-java's Introduction

qoi-java

A pure Java 8 implementation of Quite OK Image Format.

This library has no runtime dependencies, including Java AWT. ImageIO/BufferedImage support is provided using separate module qoi-java-awt.

Performance

On average, when using qoi-java-awt as an ImageIO plugin, QOI can encode 7 times faster than PNG with default settings and decode 2 times faster, while having 15% less size than PNG.

To get maximum performance, you can skip ImageIO and use pixel data arrays directly.

See full results in BENCHMARK.md.

Before choosing or rejecting QOI for your project, it is recommended to run benchmarks yourself with appropriate sample files. Here is benchmark code used to produce above results.

How to Use

Add as a dependency

This library is available in Maven Central.

Maven

<dependency>
    <groupId>me.saharnooby</groupId>
    <artifactId>qoi-java</artifactId>
    <version>1.2.1</version>
</dependency>
<!-- Also add this, if you want to use QOI with ImageIO -->
<dependency>
    <groupId>me.saharnooby</groupId>
    <artifactId>qoi-java-awt</artifactId>
    <version>1.2.1</version>
</dependency>

Gradle

dependencies {
	implementation 'me.saharnooby:qoi-java:1.2.1'
	// Also add this, if you want to use QOI with ImageIO
	implementation 'me.saharnooby:qoi-java-awt:1.2.1'
}

Other build systems

You can download prebuilt JARs from GitHub releases or build them yourself.

Usage

Use methods in class me.saharnooby.qoi.QOIUtil:

// Read image from a file
QOIImage image = QOIUtil.readFile(new File("image.qoi"));

System.out.println("Image size: " + image.getWidth() + " x " + image.getHeight());

// Access pixel data
System.out.println("Red channel is " + image.getPixelData()[0]);

// Create new 1x1 RGBA image from raw pixel data
byte[] pixelData = {(byte) 255, 127, 0, (byte) 255};

QOIImage orangeImage = QOIUtil.createFromPixelData(pixelData, 1, 1, 4);

// Write image to a file
QOIUtil.writeImage(orangeImage, new File("orange.qoi"));

Usage with `ImageIO`

To use QOI with ImageIO, you need to also add qoi-java-awt dependency. It provides an ImageIO plugin, which installs automatically using service provider mechanism.

To read and write QOI images, use standard ImageIO methods:

// Read QOI image from a file
BufferedImage image = ImageIO.read(new File("image.qoi"));

Objects.requireNonNull(image, "Invalid QOI image");

// Write QOI image into a file
if (!ImageIO.write(image, "QOI", new File("copy.qoi"))) {
	throw new IllegalStateException("Image type is not supported");
}

To convert QOI images into BufferedImages and back, use methods in class me.saharnooby.qoi.QOIUtilAWT:

// Convert PNG to QOI
BufferedImage image = ImageIO.read(new File("image.png"));
QOIImage qoi = QOIUtilAWT.createFromBufferedImage(image);
QOIUtil.writeImage(qoi, new File("image.qoi"));

// Convert QOI to PNG
QOIImage secondImage = QOIUtil.readFile(new File("second-image.qoi"));
BufferedImage convertedImage = QOIUtilAWT.convertToBufferedImage(secondImage);
ImageIO.write(convertedImage, "PNG", new File("second-image.png"));

Building

You will need Git, Maven and JDK 8 or higher.

git clone https://github.com/saharNooby/qoi-java.git
cd qoi-java
mvn clean install

Compatibility

No AWT classes are used, so it should be compatible with Android. Please report compatibility issues, if they arise.

Versioning

This project uses semantic versioning.

qoi-java's People

Contributors

Stargazers

Watchers

qoi-java's Issues

Question: Not worth to use QOI decoding over PNG decoding on Android?

Whether I use QOIUtil.readFile vs BitmapFactory.decodeFile of Android, or I use QOIUtil.readImage vs BitmapFactory.decodeStream , it seems that Android's implementation is faster to parse PNG files over QOI:

From inputStream of the resource (files are within the app) :
QOI took 84 ms
PNG took 25 ms

From a file outside the app:
QOI took 36 ms
PNG took 30 ms

And that's before getting Bitmap instance out of the QOIImage instance, which I don't understand how to do.

Tested on Pixel 4 with Android API 32 on the "wikipedia_008" image files, from here (got from here) :
https://qoiformat.org/qoi_test_images.zip

See attached project:

My Application.zip

How could it be?
Is there anything that can be improved in the implementation?
And how do you convert the output of the function to a working Bitmap instance?

Incorrect alpha handling in the encoder

Hey,

I have noticed that there is a bug in the encoder. Specifically https://github.com/saharNooby/qoi-java/blob/main/src/main/java/me/saharnooby/qoi/QOIEncoder.java#L174 here. The original C implementation is using signed arithmetic in this place https://github.com/phoboslab/qoi/blob/master/qoi.h#L465

This may not seem like a big issue since the encoding and decoding seems to be working fine but if you take a .qoi file, decode and then encode it back with this library then the resulting file will not always be identical to the original .qoi file.

You can verify this by performing a test like this:

Download test files https://qoiformat.org/qoi_test_images.zip
For each test file run a test:
- decode the file
- encode back the decoded file
- compare the resulting file with the original test file byte by byte

Recommend Projects

saharnooby / qoi-java Goto Github PK