dhyanb / open-imaging

Tools and libraries that deal with the creation and processing of images.

Open Imaging

Welcome to Open Imaging. Currently, this project only contains a GIF decoder. At a later point, other tools and libraries that deal with the creation and processing of images may be added.

GIF Decoder

A decoder capable of processing a GIF data stream to render the graphics contained in it. This implementation follows the official GIF specification.

Example Usage

void example(final byte[] data) throws Exception {
	final GifImage gif = GifDecoder.read(data);
	final int width = gif.getWidth();
	final int height = gif.getHeight();
	final int background = gif.getBackgroundColor();
	final int frameCount = gif.getFrameCount();
	for (int i = 0; i < frameCount; i++) {
		final BufferedImage img = gif.getFrame(i);
		final int delay = gif.getDelay(i);
		ImageIO.write(img, "png", new File(OUT_FOLDER + "frame_" + i + ".png"));
	}
}

You can also read from an input stream, though it will be converted to a byte array internally:

	final FileInputStream data = new FileInputStream(IN_FOLDER + "some.gif");
	final GifImage gif = GifDecoder.read(data);

Compatibility

• Support for GIF87a, GIF89a, animation, transparency and interlacing.
• Independent of third party libraries. Just download GifDecoder.java and the LICENSE file.
• Some GIF images cause an ArrayIndexOutOfBoundsException: 4096 when using Java's official ImageIO.read method or the decoder used in Apache Imaging. Kevin Weiner's decoder will either throw the same exception or render the frames of these images incorrectly. This decoder does not suffer from this bug.
• Requires Java 8.
• Should support Java 11 and Java 17 (untested).

Performance

This decoder has been frequently benchmarked against Kevin Weiner's decoder, which is well crafted and delivers high performance. Recent results indicate that both decoders perform on the same level:

Benchmark results from GifDecoderOpenImagingTest.benchmark()
    Image files: 33
    Warmups: 10
    Runs: 100
    Average runtime (ms): 1174

Benchmark results from GifDecoderKevinWeinerTest.benchmark()
    Image files: 33
    Warmups: 10
    Runs: 100
    Average runtime (ms): 1095

However, performance heavily depends on the set of images used for testing and the main motivation behind this decoder was correctness rather than speed.

Feel free to run your own tests (see next section), any feedback is highly appreciated.

Running the tests and benchmarks

You'll need a JDK, gradle and make. Run make to list available commands. You'll see something like this:

Usage: make [target]

Targets:
help               Show this help message.
b                  Build.
t                  Run all tests with default parameters.
cb                 Clean and build.
cbt                Clean, build and test.
bench              Benchmark using 1 warmup and 1 run.
bench w=i r=j      Benchmark using i warmups and j runs.
bench-kw           Benchmark Kevin Weiner's GifDecoder using 1 warmup and 1 run.
bench-kw w=i r=j   Benchmark Kevin Weiner's GifDecoder using i warmups and j runs.

One of the tests run by make t loops through all test images and decodes and writes their individual frames to src/test/resources/output-frames/. This is a test I frequently run after changing the code to ensure correctness.

Test data

The test data (see /src/test/resources/input-images/) consists of more than 30 different GIF images featuring:

• File sizes ranging from 69 bytes (sample.gif) up to 5 MB (space.gif)
• Around 1.400 individual frames (~30 MB)
• Different image dimensions
• Animated GIFs
• Static GIfs
• GIFs with transparent backgrounds
• GIFs that have optimized frames with smaller dimensions than the base canvas
• GIFs with a high frame-count (255 frames in bubble.gif)
• GIFs that use interlacing (e.g. hand.gif)
• GIFs that cause the mentioned ArrayOutOfBoundsException in various other decoders
• fish.gif, which has no trailer byte
• c64.gif, which has a truncated end of information code at the end of the second frame
• train.gif, which has a truncated image data sub-block at the end of the last frame
• science.gif, which has about 5% worth of corrupted, unrecoverable trailing data

Quirks

Background color: If a GIF frame requires the next frame to be drawn on the background, a decoder would have to clear the canvas and restore the background color that is specified in the GIF's logical screen descriptor. Many GIFs that look like they should actually have a transparent background would then have an opaque background. Therefore this decoder only sets the canvas to the background color, if the next frame has no transparent color defined. Otherwise, a transparent background will be used to draw upon. Testing indicates that this approach works fine. However, you can still ask the decoder for the background color of the first frame and use it to set the background of buffered images on your own.

Additional resources

• https://www.w3.org/Graphics/GIF/spec-gif89a.txt
• http://www.theimage.com/animation/pages/disposal.html
• https://docstore.mik.ua/orelly/web2/wdesign/ch23_05.htm#wdnut2-CHP-23-FIG-1

open-imaging's Issues

jdk 8 support?

hi，jdk8 support? I see readme only support jdk1.7

Broken gif

It looks like some gifs are being decoded incorrectly.
For example this gif from giphy - https://media.giphy.com/media/26DN81TqLPIzBlksw/giphy.gif
I got broken frames starting from 11-th frame:


Can you please take a look?

Not all GIFs start with a clear code

While debugging some gifs that even Paint Shop Pro fails to render (but Windows, Firefox and Microsoft GIF Animator do read correctly) I found all of them had no clear code as the first code in each frame.

Removing line 202 fixed it.

bits.read(); // Skip leading clear code

However this breaks all other GIFs because now their clear code is interpreted as a color code. Need to investigate.

Returned frames expose inner state

GifImage.getFrame(int) returns an internal representation of the animation.

This has two consequences:

• Internal state is exposed to the user, akin to returning arrays or modifiable collections or exporting public fields in the API. Very bad practice in general.
• There's no easy way to obtain the animation as a sequence of separate images.

This behavior is undocumented, and lead to a bug in my application, where I saw an animation of only the last frame.

Fortunately the API doesn't have to change in order to fix this, keeping backwards compatibility.

	public BufferedImage getFrame(int index) {
		if (img == null || index < prevIndex) { // (Re)Init
			img = new BufferedImage(width, height, 2); // 2 = ARGB
			prevImg = new BufferedImage(width, height, 2);
			prevIndex = -1;
			prevDisposal = 2;
		}
		// Draw current frame on top of previous frames
		for (int i = prevIndex + 1; i <= index; i++) {
			GifFrame fr = frames.get(i);
			drawFrame(fr);
			prevIndex = i;
			prevDisposal = fr.disposalMethod;
		}

		BufferedImage copy = new BufferedImage(width, height, BufferedImage.TYPE_INT_ARGB);
		Graphics      g    = copy.createGraphics();
		try {
			g.drawImage(img, 0, 0, null);
		} finally {
			g.dispose();
		}
		return copy;
	}