<commit_before>Open Imaging
============

Currently this project only contains a GIF decoder. At a later point, it may contain other tools and libraries that deal with the creation and processing of images.

## GIF Decoder

A decoder capable of processing a GIF data stream to render the graphics contained in it. This implementation follows the official <A HREF="http://www.w3.org/Graphics/GIF/spec-gif89a.txt">GIF specification</A>.

### Example Usage
```
void example(final byte[] data) throws Exception {
	final GifDecoder decoder = new GifDecoder();
	final GifImage gif = decoder.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(OUTPATH + "frame_" + i + ".png"));
	}
}
```

### Compatibility

Some GIF images cause a <a href="http://stackoverflow.com/questions/22259714/arrayindexoutofboundsexception-4096-while-reading-gif-file">ArrayIndexOutOfBoundsException: 4096</a> when using Java's `ImageIO.read` method. The decoder used in Apache Imaging and the well known decoder from <a href="http://www.fmsware.com/stuff/gif.html">Kevin Weiner</a> also show this bug.

This decoder does <i>not<i> suffer from this bug.

### Performance

During development, I frequently compared the performance of this decoder with the one from <NAME>iner, which is very well craftet and shows an impressive speed. I worked hard to deliver a <b>similar level of performance</b> and testing indicates that my decoder is around 9% faster than Kevin Weiner's. However, this heavily depends on the set of images used for testing (see next paragraph) and the main reason for creating another GIF decoder was to avoid the bug aforementioned. So I do not persist on being faster, but I think this decoder delivers reasonable performance. Feel free to do your own tests and share your experiences!

### Images used during testing

My testing set includes 22 different GIF images of various file sizes and image dimensions. The biggest one is about 5 MB, the smallest one is only 69 bytes, all together sum up to 22 MB. All but three are animated GIFs. Some have transparent backgrounds, some have optimized frames that are have smaller dimensions than the base canvas. One of the bigger files consists of 255 frames. Some images use interlacing. Three images cause an ArrayOutOfBoundsException in various other decoders.<commit_msg>moar readme<commit_after>Open Imaging
============

Currently this project only contains a GIF decoder. At a later point, it may contain other tools and libraries that deal with the creation and processing of images.

## GIF Decoder

A decoder capable of processing a GIF data stream to render the graphics contained in it. This implementation follows the official <A HREF="http://www.w3.org/Graphics/GIF/spec-gif89a.txt">GIF specification</A>.

### Example Usage
```
void example(final byte[] data) throws Exception {
	final GifDecoder decoder = new GifDecoder();
	final GifImage gif = decoder.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(OUTPATH + "frame_" + i + ".png"));
	}
}
```

### Compatibility

Some GIF images cause an <a href="http://stackoverflow.com/questions/22259714/arrayindexoutofboundsexception-4096-while-reading-gif-file">ArrayIndexOutOfBoundsException: 4096</a> when using Java's official `ImageIO.read` method. The decoder used in Apache Imaging and the one from <a href="http://www.fmsware.com/stuff/gif.html"><NAME></a> also show that behavior.

This decoder does <i>not<i> suffer from this bug.

### Performance

During development, I frequently compared the performance of this decoder with the one from <NAME>, which is very well crafted and shows an impressive performance. I worked hard to deliver <i>comparable speed</i> and current testing indicates that my decoder is around 9% faster than <NAME>'s. However, this heavily depends on the set of images used for testing (see next paragraph) and the main reason for creating this GIF decoder was to avoid the bug aforementioned. So I do not persist on being faster, but I think this decoder delivers reasonable performance. So feel free to run your own tests! Any feedback is highly appreciated.

### Images used during testing

My testing set includes 22 different GIF images of various file sizes and image dimensions. The biggest one is about 5 MB, the smallest one is only 69 bytes, all together sum up to 22 MB. All but three are animated GIFs. Some have transparent backgrounds, some have optimized frames with smaller dimensions than the base canvas. One of the bigger files consists of 255 frames. Some images use interlacing. Three images cause an ArrayOutOfBoundsException in various other decoders.
{'fraction_non_alphanumeric': 0.08167599922765012, 'fraction_numerical': 0.011971423054643753, 'mean_word_length': 4.7555555555555555, 'pattern_counts': {'":': 0, '<': 29, '<?xml version=': 0, '>': 27, 'https://': 0, 'lorem ipsum': 0, 'www.': 4, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '2384004', 'n_tokens_mistral': 1456, 'n_tokens_neox': 1338, 'n_words': 681}