colorful-gdx

This release mostly changes how SimplePalette.parseDescription() works for all color spaces with a SimplePalette. Now you can specify weights for colors by adding a number after any color name (this can be space-separated as in red 5 blue 2, or can use most punctuation, as in red^5 blue^2). These examples should be exactly equivalent to red red red red red blue blue, but I definitely prefer the way with numbers! Lightness and saturation modifiers also changed how they are evaluated in some places. Lightness changes generally work by lerping towards white or black now, instead of just changing the L component for Oklab and CIELAB, or the I component for IPT_HQ. This seems to produce a meaningful change more often when a color had (in Oklab) an L value that was very close to 1 already, and you wanted to lighten it, such as light yellow. Saturation changes take effect after lightness changes, so even though lightening or darkening makes a color closer to grayscale, you can enrich it to counter that.

The other big change here is that Oklab now calculates lightness extremely closely to how RGB and YCwCm calculate lightness, which had been my goal with the last change to the light adjustment, but I hadn't obtained it until now. It turns out that no complicated formula was needed, and I already essentially had this adjustment done in the Oklab shaders -- now converting to and from Oklab is just equivalent to a Math.pow() call on L (using something like Math.pow(L, 3.0/2.0) to convert to Oklab, or Math.pow(L, 2.0/3.0) to convert from Oklab). In practice, this seems to smooth gradients quite well, and doesn't seem to have much speed difference.

As usual, if you're downloading these via the .JAR files below, you probably shouldn't be, but if you are.... you probably don't need the ones with -pure in the name (plus, those have more dependencies).

This release mostly exists to add four more color adjectives to the four there already are. This brings most of the SimplePalettes here to compatibility with the adjectives TextraTypist was already using on its own, as was SquidSquad. The four adjectives (bright, deep, pale, and weak, plus -er, -est, and -most suffixes to amplify them) just combine two existing adjectives in equal amounts. Perhaps more importantly, the mixing formula for how much adjectives affect colors has changed for some color spaces, to try to match it to the change in lightness for Oklab. This is not at all a "necessary update" for users; it changes more features than it adds. The lightness changes in Oklab's SimplePalette may be useful, at least, as should HSLuv's SimplePalette.

As usual, if you're downloading these via the .JAR files below, you probably shouldn't be, but if you are.... you probably don't need the ones with -pure in the name (plus, those have more dependencies).

This release has taken a while longer, but there's some important changes here. The change that required the most work to implement was for Oklab; it makes pure-gray possible to represent, instead of having gray be always slightly bluish-green. Various other changes range from renamed fields and methods in Shaders (where quite a few names were incorrect or misleading), to fixes for several floatGetHSL() kinds and RGB's toEditedFloat(), to more lightness changes in Oklab. TrigTools now uses current code copied from my digital library, and the old oddly-named methods like sin_() and atan2_() are now called sinTurns() and atan2Turns(). Oklab's ColorTools also has distanceSquared() and distance() methods for comparing the similarity of two colors. That's about all here; it's quite spread-out, but I hope this release is useful!

The colorful-0.8.3 jars are most likely the ones you're after. They require libGDX (any version 1.9.13 or newer; 1.11.0 is currently recommended). You probably don't need the colorful-pure JARs here unless you know you don't want a libGDX dependency (such as for some servers), but if you use them you will also need the JARs for digital, juniper, funderby, and jdkgdxds. Please consider using a project management tool, like Gradle or Maven!

This release mostly concerns the recently-added HSLuv code, particularly its ColorfulBatch, and makes its shader act correctly (it didn't before). This took a lot of time and frustration to get right, so I really, really hope it works without any strange graphical glitches. There's also a GWT bug fixed in the rgb, oklab, and cielab packages, with the ColorTools.toEditedFloat() method and affecting alpha.

The colorful-pure JARs now depend on jdkgdxds 1.0.2, juniper 0.0.2, and digital 0.0.2, all available at repos under the same user as colorful-gdx (tommyettinger).

Less than an hour after the (official, GitHub) release of 0.8.0, here's 0.8.1, with a simple fix for the lightness used by color constants in HSLuv's Palette and SimplePalette classes. The need for a fix was clear; in the comparison demo, HSLuv almost always displayed a lighter color than any of the other color spaces. The implementation of the fix was even more clear; I only needed to re-generate the large blocks of color constants from the source data using PaletteCodeGenerator (a tool in the tests) and update those two palette classes. This significantly improves the accuracy of the color descriptions in SimplePalette, and makes the actual colors match their docs.

For more info on the new HSLuv color space, see the README.md or the release notes for 0.8.0 (where they are summarized briefly). This also includes the lightness changes that were applied in 0.8.0 to Oklab, so updating from 0.7.0 would see Oklab colors change as well as the new option for HSLuv.

As before, you probably want colorful and not colorful-pure if getting the JARs below. If you don't use libGDX, then colorful-pure is potentially a good option. The colorful JARs depend on libGDX 1.9.13 or higher; the colorful-pure JARs depend on jdkgdxds 0.2.8 or higher.

This is a fairly major release, adding the HSLuv color space and adjusting Oklab's lightness again (though less significantly). HSLuv is a nice color space for user-defined colors, since just about any combination of Hue, Saturation, and Lightness is valid (only saturated white and saturated black are somewhat invalid, but even those can be handled). It tends to have a much more even lightness estimate than standard HSL, and internally it has a computable gamut rather than a large table (saving some memory and code size). I acknowledge that the HSLuv lightness estimate is still probably off in this release, and 0.8.1 should follow soon when I figure out how to better handle this. Oklab's lightness estimate, on the other hand, seems extremely close now to the one used for RGB colors.

As before, there are colorful-0.8.0 JARs below and also colorful-pure-0.8.0 JARs; you probably want the colorful-0.8.0 ones. The only time you would probably want colorful-pure is on a headless application (often a server) that doesn't depend on libGDX (1.9.13 or higher), but can depend on jdkgdxds (0.2.8 or higher).

This is in some ways a more substantial release than the previous one, even though 0.7.0 doesn't add a new color space and 0.6.1 did. Why would that be? There's just been a lot of work here. There is a GradientTools class for each color space, allowing easier generation of gradients of packed float colors between 2 or more specified colors. Critically, Oklab's lightness has been adjusted, so 50% gray (in RGBA, 0x808080FF) actually is at almost exactly 50% L, instead of 63% where it was before. This wound up being part of a massive set of debugging and repeated back-and-forth changes that found earlier issues in the Oklab gamut -- and this time, they seem to be fixed. In several earlier releases, ColorTools.oklabSaturation(), which is defined as returning a fraction of the maximum possible chroma a color can have with the same hue and lightness, would sometimes return higher numbers than 1, like 1.4 for blue. Naturally, using unexpectedly-out-of-range values would have caused problems. This was related to other gamut issues, but the cause mostly boiled down to hue() being used in some places (which uses HSL's hue algorithm) and oklabHue() used in others (which would be correct in this case, and gives the actual angle in turns to get the needed A and B channels).

I'm less than enthusiastic about CIELAB now that Oklab looks a fair bit better than before. CIELAB turns out not to have its black color positioned at the center of A and B (it's off to higher A and slightly higher B than it should be), and gradients with CIELAB seem to often have strange color changes in the middle. Hats off to Björn Ottosson, for creating a color space that beats CIELAB after it has been the go-to for many years.

The docs are all updated, the preview images are also updated, and there's a fresh coat of paint on everything. I hope you enjoy.

This release adds support for the CIELAB color space (specifically, the 1976 CIE L*A*B* color space), which this takes pains not to approximate in most key aspects. As a result, it tends to be slower to do some operations than Oklab, and because the two color spaces are otherwise rather similar, Oklab is currently recommended. There is some small but significant optimization to Oklab-related code here, so there's a reason to update even if you don't use CIELAB.

This is something of a big release, because it's just been a while since the last one and I've been coding away here... Many bugs have been fixed and many small features have been added. Some weird issues with the Oklab and RGB ColorfulBatches are fixed. The gamut, mostly for Oklab, has been tinkered with a lot and I think it works well now. There's many more methods in Oklab's ColorTools for dealing with colorfulness, such as oklabSaturation(), chroma(), and chromaLimit(). All of the color spaces have some editQuux() methods, replacing Quux with the current color space. This allows you to edit the RGBA channels of a color with editRGB() just as you can edit the L, A, B, and alpha channels of an Oklab color with editOklab(). SimplePalette has been brought over to the RGB color space, and all of the SimplePalettes and Palettes allow you to convert the existing colors in libGDX's Colors to the current color space, or append the SimplePalette or Palette entries to Colors. In general this should be a worthwhile update, if only for the several key bug fixes.

colorful depends on libGDX 1.9.13 or higher, and colorful-pure depends instead on jdkgdxds 0.1.2 or higher. colorful is probably what you want here.

This release has various small improvements, but more significant changes to Oklab. Before, A and B were compressed so their -1 to 1 range would fit in the 0 to 1 space each channel gets. However, because Oklab's A and B channels are so narrow, compression isn't necessary, and so they are allowed to be their actual width now (which is smaller than -0.5 to 0.5, so fitting that in the 0 to 1 range just needs an offset). This means when comparing the difference between two Oklab colors, you should now use the normal Euclidean distance, Math.sqrt(L * L + A * A + B * B). Another change involves an optimization to how the gamut is found for Oklab, which also improves the quality when colors are brought back into the gamut from outside of it. A possible breaking change affects the inverseLuma(), inverseIntensity(), and inverseLightness() methods, which are now all called inverseLightness() to make translation between ColorTools versions easier. There are now added differentiateLightness() and offsetLightness() methods that act something like inverseLightness() but don't consider chroma at all; offsetLightness() takes one color parameter, is about the same as differentiateLightness(), which takes two colors, if you called it on the same color for both arguments (offsetLightness() differentiates a color from itself). There's a fix to toEditedFloat() in everywhere that needed it; most implementations used the luma, intensity, or L (as in LAB) in that calculation, but it needs to use the lightness from HSL, as inaccurate as it may be in general, for the HSL edit to work correctly. All in all, this should be a worthwhile release, and I hope I didn't miss any problems.
If I did, the Issues tab is wide open.

This release depends on libGDX 1.9.13 (or higher) for colorful, or jdkgdxds 0.0.5 (or higher) for colorful-pure. You probably want colorful, if you're using the JARs here, and don't need colorful-pure, but there could easily be a case where the opposite is true.

It's been a whole two days since the last release, but this adds a complete new feature: the Oklab color space, recently released by Björn Ottosson. It's similar to IPT and to YCwCm, but should have better smooth gradients between colors and should be easier to measure the perceptual difference between colors. It's also slightly easier to compute than IPT_HQ. It's not without its quirks; like IPT_HQ, 50% gray doesn't have 0.5 lightness/intensity (it's 0.55 for IPT_HQ, and 0.63 for Oklab), and the A and B chromatic channels have a rather small range. That last quirk is really more of a feature because it makes comparing the distance between colors in Oklab easier -- multiply L by 0.5 for each color, then get the Euclidean distance between the two colors (the standard differenceL * differenceL + differenceA * differenceA + differenceB * differenceB, with a square root if you need it to be a valid metric, or no square root if you only care about whether it's more or less than one other distance). IPT takes a lot of fiddling to get its color differences closer to accurate, and the closest I've found multiplies I by 3 instead of L by 0.5, but is otherwise similar (and probably not as good). The same APIs are available for Oklab as IPT_HQ, including a color-description system in SimplePalette. JARs are provided here for colorful, which depends on libGDX 1.9.13, and colorful-pure, which depends on jdkgdxds 0.0.4 or higher. You probably want colorful, if you're here, and don't need colorful-pure unless you know you don't want the libGDX dependency.

This release fixes the one from yesterday, 0.4.1; that previous version had an issue that made its ColorfulBatch classes incompatible with projects using Java 8 to compile. The issue seems to be cleared up for good; the technical part of it is that Java 8 and earlier had compatible APIs for Buffer and ShortBuffer, but Java 9 broke that compatibility, which stayed broken in all later versions. It's easy to fix by casting any ShortBuffers to Buffer when code needs to call Buffer methods on them; this only happens on two lines in each ColorfulBatch, and shouldn't affect user code. A lot of documentation was improved here in this release. One shader in Shaders (the IPT_HQ one) changed slightly, to match the similar shader in the ipt_hq ColorfulBatch class (now I know 50% gray has 0.55 intensity in IPT_HQ, and the ColorfulBatch already used that as the middle point, but the one in Shaders didn't until now). This doesn't include the Oklab color space yet; my implementation of it is still a work in progress, but it should be in the next release.

This release mostly adds small features to SimplePalette's matching, and changes the name of one color so you can actually get a color with the description "brown" instead of calling it "sepia". There's the ability to find the best description to match an IPT_HQ color with a String description, which is useful if any code might handle colors purely as Strings at some point. Importantly for descriptions, you can describe lightening, darkening, dulling, and enriching with adjectives like "light", "lighter", "lightest", and now the new "lightmost" (ignore that it isn't a real word...). Really, the adjectives just check whether there's 2, 3, or 4 letters after "light", "dark", "rich", or "dull", matching those cases to "-er", "-est", or "-most" as the highest level.

There's a few updates to dependencies. Gradle is 6.8, which is generally good to keep up-to-date for point releases. The colorful-pure module depends on jdkgdxds 0.0.4, the latest stable version of those data structures. The colorful module now depends on libGDX 1.9.13, instead of 1.9.12, which removes the need for some of the trig approximations in TrigTools (they're the same in libGDX now). If you used asin(float) or acos(float), use MathUtils instead of TrigTools. If you used sinDegrees(float) or cosDegrees(float), MathUtils already had sinDeg(float) and cosDeg(float) with even higher precision (and probably speed).

This is a somewhat different release, because we now have two groups of jar: colorful, which depends on libGDX 1.9.12 or newer and Java 7 or newer, and colorful-pure, which depends on jdkgdxds (currently 0.0.3, but it's mostly code isolated from libGDX and should be about as stable) and Java 8 or newer. You usually would need only colorful, and only in a project that uses libGDX, but some cases can use color manipulation code that doesn't depend on graphics, which is where colorful-pure is useful. A typical project will only use either colorful or colorful-pure in a given module, but could easily use one on a server and the other on a client.

Feature-wise, there's a SimplePalette in the ipt_hq package, and it allows describing colors by combining color names with a limited set of adjectives. There's also enrich() and dullen() methods in the ipt, ipt_hq, and ycwcm versions of ColorTools, which affect saturation, and more methods for handling the gamut in those ColorTools classes as well.

I think the color description technique should be more useful than the previous named colors in Palette, especially since there's only 50 named colors to think about in SimplePalette as opposed to 256 in Palette.

If you need to get the JARs for jdkgdxds (only needed for colorful-pure), they are here: https://github.com/tommyettinger/jdkgdxds/releases/tag/v0.0.3

If you need to get the JARs for libGDX (only needed for colorful)... I wish you well on your journey, though I think you'd probably have a better time using Gradle.

This release adds a few small convenience methods to most color spaces, but most importantly adds a somewhat-new color space: IPT_HQ. Short for "Intensity-Protan-Tritan, High-Quality," it uses the same 3 channels as the existing IPT color space, but this new one doesn't omit any of the steps in Ebner and Fairchild's paper introducing IPT (the older IPT does omit two key steps that IPT_HQ performs). This means IPT_HQ gamma-corrects RGBA inputs and outputs (with a gamma of 2.0, as a compromise between the common 1.8 and 2.2 that also benefits from a fast square root function when removing the gamma), and it has an exponential step where it raises 3 internal values to the 0.43 power (or to the 1.0/0.43, preserving sign). These steps aren't as lightning-fast as the older, simplified IPT, which actually combines the two matrix multiplications in IPT_HQ into one, but the difference in how IPT and IPT_HQ calculate lightness is significant. If you look for outliers in the simplified IPT color table, where all the early values are supposed to be similarly dark, and then do the same in the IPT_HQ color table, you may notice "Red" and "Blue" in the simplified table stick out as much brighter than their neighbors, but there's nothing but dark colors early on in the HQ table.

IPT_HQ supports all the same operations IPT does, except for the obscure ColorTools.fromHSI() and ColorTools.subrandomColor(); it has a ColorfulBatch and ColorfulSprite class that can be used as stand-ins for IPT. Shaders has been updated to have an IPT_HQ shader, as well. If you currently use IPT, it might make sense to try changing the package you import from com.github.tommyettinger.colorful.ipt to com.github.tommyettinger.colorful.ipt_hq, and see if you notice a difference in performance or quality.

This is a fairly big release! The different color spaces are organized into their own packages now, with almost identical APIs except for the ColorTools class in each. To continue using the previous API, you can use Shaders in the same way, or change to the com.github.tommyettinger.colorful.ycwcm package for ColorfulBatch, ColorfulSprite, Palette, and ColorTools. You can also use com.github.tommyettinger.colorful.ipt or the new com.github.tommyettinger.colorful.rgb to use those color spaces, which are discussed in the README. In practice, YCwCm does surprisingly well considering its simple formulas. Some of the tests used both IPT and YCwCm for generating palettes, with arguably better results using YCwCm. IPT does seem to handle interpolation between colors better, especially if they have comparable intensity/lightness. RGB is more familiar, but doesn't offer much for aesthetic choices in tinting.

This release has mostly shader changes, including several that allow nostalgic hue-rotation effects. I'm starting to add IPT-related code, and I really like the IPT color space now. Some breaking changes are planned for the next release, though they should be limited for the most part to package changes for existing code.

The main new feature of this release is ColorfulBatch and the code that works with it, like ColorfulSprite. Before, you could set a color on a SpriteBatch, which would make additive adjustments to chromatic warmth and chromatic mildness, as well as multiplicative adjustments to luma and alpha. Now with ColorfulBatch, you can also make multiplicative adjustments to warmth and mildness (treating them as centered around 0.0, you can multiply them individually by anywhere from 0.0 to 2.0), additive adjustments to luma, and some different kinds of modification to contrast (either making mid-range colors less distinct with low contrast, or making light colors lighter and dark colors darker with high contrast). The color you can set on a ColorfulBatch now affects the additive luma, warmth, and mildness plus the multiplicative alpha. There's now also a "tweak" you can set on a ColorfulBatch that affects the multiplicative luma, warmth, and mildness, plus the contrast adjustment. Tweaking the warmth and mildness to low values (near 0.0 for both) makes the image grayscale or close to it; tweaking them to high values oversaturates the image. If the warmth and mildness tweaks are both 0.0 and you set a color on the batch as well, then instead of grayscale you can produce a "green-scale" or "purple-scale" image by setting the color to green or purple. ColorfulSprite is like libGDX's Sprite class but allows setting a tweak per-sprite as well as a color.

This release has a small but complete set of color-editing features. It includes shader code in Shaders.java (and convenience methods that make using that code directly unnecessary), predefined packed-float colors in Palette.java, and quite a lot of methods for manipulating those colors as floats in FloatColors.java. Using the Maven Central dependency is recommended, and Gradle and Maven can both depend on this library using that repository.

Gradle dependency:

implementation 'com.github.tommyettinger:colorful:0.1.0'

Gradle dependency if also using GWT to make an HTML application:

implementation 'com.github.tommyettinger:colorful:0.1.0:sources'

And also for GWT, in your application's .gwt.xml file (usually GdxDefinition.gwt.xml)

<inherits name="com.github.tommyettinger.colorful.colorful" />

If you don't use Gradle, here's the Maven dependency:

<dependency>
  <groupId>com.github.tommyettinger</groupId>
  <artifactId>colorful</artifactId>
  <version>0.1.0</version>
</dependency>

If you don't use Gradle or Maven, there are jars for this release here.