anim8-gdx

I've been making lots of small and not-so-small quality adjustments to SCATTER and PATTERN dithers, among others, for the last month or so, and now it's time to formalize them in this release. PATTERN is back to using a 4x4 unskewed block instead of a 4x2 with skew, which slows it down even more but dramatically increases how well it handles gradients and other soft color changes. SCATTER has some unusual changes that try to make it able to handle very high dither strength (higher than 1.0); that can look good but doesn't always work without artifacts, so you may want to stick to a dither strength in the 0.5 to 1.0 range for it. Other changes to SCATTER seem to have improved how well it handles gradients. Mostly, It Is Time to release this because I want to test out how well the new PATTERN works on some procedural planet graphics, and it's been too long without a release anyway.

This release primarily affects the error-diffusion-based dithers DIFFUSION and SCATTER, but also has a significant improvement to PATTERN. For the first two, accrued error was calculated as a float before, but assigned to a byte or int, losing the fractional component. Now it's assigned to a float and only converted to an int (by rounding) when it needs to be used to get a color from the palette. This sometimes works very well at softening banding, especially when there's a smooth gradient and there aren't quite enough colors in the palette to handle it perfectly. As for PATTERN, this release gets rid of the (apparently redundant and problematic) gamma handling that was only used for that dither type. Gamma was already handled in the Oklab lightness calculations, so handling gamma again in PATTERN (and only PATTERN) probably caused the strange lightness fluctuations as dither strength went up or down.

If you're generating GIFs, which I'm guessing is the main use case for this library, the dithering used may have changed, but this shouldn't be too noticeable if you use the standard way of analyzing a palette from the given Pixmaps. If you aren't specifying a smaller palette via a PaletteReducer, the changes here shouldn't be very noticeable, although they may make a big enough improvement on gradients that you can see a difference.

There's some rather-significant improvements in how lightness is evaluated in this release, thanks to the transition from using the IPT color space to the newer Oklab color space. IPT is great at gauging how similar two colors' hues are, but isn't as good at comparing lightness (or colorfulness, also called chroma). Oklab, by Björn Ottosson, is much newer and considerably better at how it judges lightness differences. The default SCATTER dither is also a little more aggressive in how much it spreads error, which can help on gradients but may cause artifacts with some (typically very small) palettes; lower the dither strength to 0.8 or less if you want the previous behavior. All of the API should be the same here, except for the addition of the possibly-useful OKLAB array in PaletteReducer (it supplants IPT, in the same file where it was), but a lot of output will be different because of the more-accurate lightness calculations.

This is another release I've had to push with minimal changes other than a bugfix for a Java 9+ backwards-incompatibility that affects NIO Buffers. This only affects AnimatedPNG here, so if you don't write full-color animated PNGs, you can stay on 0.2.5 with equivalent features, if you want. I still recommend updating, in case someone needs AnimatedPNG later and doesn't want a crash in the process. This bug only showed up if you compiled with Java 8 and depended on anim8-gdx 0.2.5, since that release used backwards-incompatible (but only a little) Java 15 to build. If you used Java 9 or higher throughout, you wouldn't notice the bug. Maven Central is up-to-date (or will be soon after this release becomes public), so you can use that to download with a dependency management tool like Gradle.

This release only has a few changes, but it has some good things. It fixes a mistake in AnimatedGif for PATTERN dither that may have just slowed it down, or may have caused visual problems. The default-if-unspecified HALTONIC palette now doesn't bias bright white toward a yellowish off-white, nor does it bias black towards blue-violet. A possible breaking change, if you used internals of this library, is that PaletteReducer.barronSpline(), PaletteReducer.BiasGain, PNG8.probit(), and PNG8.centralize() are moved to a new OtherMath class; centralize() also changed its output slightly but is now documented. Documentation is updated in several other places, too. That's about it!

Color gradients are even smoother now, with less hue distortion accompanying banding! The PATTERN dither algorithm is faster! The default palette is... probably about the same in practice, but technically distributed a little better into saturated colors! It's version 0.2.4! The color gradients are smoother because the color space is still IPT (it still has the Intensity, Protan, and Tritan channels), but now it is roughly-correctly gamma-corrected when comparing colors, and it uses the useful steps in the IPT paper by Ebner and Fairchild (which are a little slower to calculate the first time, but make the measurement of colors much more accurate). PATTERN uses a 4x2 instead of 4x4 grid of lookups per pixel, which doesn't have much effect on quality because of the skew, but does do better than halve the number of operations needed per pixel. The default palette isn't DawnBringer's Aurora palette anymore; it's "Haltonic" instead. This has the same number of colors (255 plus transparent), but it's distributed in line with a Halton sequence, which means taking a sub-range of the palette is usually distributed about as well across the palette, down to as few as maybe 48 colors.

This release significantly improves some of the default dither settings, making high-color dithers much smoother by reducing the required threshold for difference between colors (but only when using many colors). It includes the changes from 0.2.2 as well, which wasn't released on GitHub but was on Maven Central; these mostly relate to internally using the IPT color space (which has Intensity between 0 and 1, Protan/green-to-red between -1 and 1, and Tritan/blue-to-yellow between -1 and 1) instead of the somewhat-strange CIELAB color space (which ranges from 0 to 100 for Lightness, but doesn't have a defined limit for A or B and they can range as high as 128 in extreme cases). The unusual bounds for CIELAB made it harder to estimate differences, and IPT seems much better for this purpose. There's also some code to edit palettes in existing PNG8 files.

So... I forgot to release several versions here on GitHub, even though 0.1.7, 0.1.8, 0.1.9, and 0.2.0 are on Maven Central. The README is still up to date, and has been; it covers the current features, like better BLUE_NOISE dither and the addition of CHAOTIC_NOISE and now SCATTER (the current default). 0.2.1 adds SCATTER dither, which combines properties of blue noise and error-diffusion dithers, and generally provides a very good mix of features (including for animations). Various parameters have been adjusted as well; dither now gets less "strong" when it has a lot of colors it can choose from in the palette, and some defaults are at better levels. The color quantization step done by PaletteReducer.analyze() is still not very good; I'm working on it.

This release updates the dependency on libGDX to 1.9.11, just because I think there's substantial improvements in the release and I want it to be adopted; there's no libGDX-1.9.11-specific APIs used here. It also adds a DitherAlgorithm, DIFFUSION, which uses Floyd-Steinberg error-diffusion dithering. This new DitherAlgorithm maintains lightness, unlike PATTERN, and doesn't add much noise in still images, unlike GRADIENT_NOISE, but does have issues when only part of an animation frame is different from the frame before or after it (it tends to make a lot of the dithered result different between frames). It should be useful for the still-image usage of PNG8, or AnimatedGif when it isn't used for an animation.

This release is the only GitHub release for 0.1.3, 0.1.4, and 0.1.5, but there's Maven Central releases for all of those. Notable features added in these 3:

• GWT fixes in 0.1.3
  • Now GWT is actually usable, other than the PNG writing (that needs java.util.zip, which isn't available on GWT)
• The modified Knoll pattern dither (Knoll-Roberts, here) uses a different skew now, which is slightly less apparent, present in 0.1.4
• The color difference metric is simpler and should behave much better when dithering smooth light-to-dark gradients, changed in 0.1.5

But really if you weren't using GWT, you can easily stay using an earlier version; there's nothing too huge here. The gradient improvements in 0.1.5 may make a difference for many images, though, especially if using a small palette.

This release is probably unnecessary for most users, and you're almost certainly fine staying with 0.1.1 if you already use it. I mostly wanted to have this release for some of my older code that still used PaletteReducer's paletteMapping field as public, since it's hard to work around it being private when code already uses it. This does improve the docs a bit, and adds methods to write a PaletteReducer's paletteMapping to a preload file, which could already be loaded, mostly.

Features are otherwise the same as 0.1.1; nothing's been removed. You can use AnimatedGif, AnimatedPNG, and PNG8 with the same methods.

This is the first release I remembered to put on GitHub but the second on Maven Central. Breaking changes here since the 0.1.0 release are mostly that no IOException is thrown by most file-writing code, instead choosing to catch the IOException internally and log with the Exception's message with Gdx.app.error(). This probably isn't a robust way to handle file IO, but forcing user code to handle very rare exceptions seemed... bad... and most code was probably going to handle an IOException by printing it or logging it. Feature changes are mostly that Knoll's pattern dither is now the default, and the original gradient noise dither can be selected or dither eliminated with setDitherAlgorithm(). The classes that write animations now share an interface, AnimationWriter.

I'm hoping that I won't need to revisit this to fix any bugs, though that's entirely possible. Hopefully I'm done, already!