ColourUtils - A colour manipulation library

Resources Community Resources
, , ,
#1

Source Code Itch.io NPM

Releases NPM Wally

:floppy_disk: Source Code | :open_book: Documentation

ColourUtils is a utility library for Roblox Studio that provides a number of functions for working with colours.

The library contains methods to manipulate standard Color3s, as well as convert them back and forth between formats; such as Hex and Integer (great for Discord!).

ColourUtils can also generate colour palettes, blend colours together, and even simulate colour blindness. In combination with the built-in accessibility-focused “submodules,” ColourUtils can be used to find and generate the perfect and most accessible colours for your project.

Documentation

Documentation is available at ColourUtils.

Quick Start

ColourUtils is available in Lua and TypeScript (via roblox-ts). It’s available from the wally and npm registries, Roblox Library and via Itch.io.

Wally

# wally.toml

[dependencies]
ColourUtils = "csqrl/colour-utils@^1.1.0"

$ wally install

TypeScript

Install the @rbxts/colour-utils package using npm or yarn.

$ npm i @rbxts/colour-utils
$ yarn add @rbxts/colour-utils

Manual Installation

Grab a copy from the Roblox Library (Toolbox), or download the latest .rbxm file from the releases page and drop it into Studio.

35 Likes
#2

It would be cool if you included Color3 operations (add, multiply…)
Otherwise great module

2 Likes
#3

Blending operations? Great idea! I’ll add it to the “todo list”

3 Likes
#4

You could make a “universal” color pallete!

ColorUtils.save(pallete, color, reference)
ColorUtils.get(pallete, reference, language)

ColorUtils.save(myPallete, Color3.fromRGB(255, 255, 255), "white")
ColorUtils.get(myPallete, "white", "Hex") --> "#FFFFFF"
ColorUtils.get(myPallete, "white", "RGB") --> "255, 255, 255"
ColorUtils.get(myPallete, "white", "Color3") --> "1, 1, 1"
I’m not a programmer, so forgive me for this ugly code haha

I’ts just a cool feature I guess.

2 Likes
#5

the module is part of a larger project that I decided to open source as a standalone library. watch this space! :eyes:

1 Like
#6

Thanks for your suggestion, @IlyasTawawe! Blending operations are now available in v1.0.3 via the ColourUtils.Blend “submodule”; this includes:

  • Burn
  • Dodge
  • Multiply
  • Overlay
  • Screen

Additionally, a .Rotate method has been added to allow for rotating the hue of Color3s.

3 Likes
#7

v1.1.0

Full Changelog: 1.0.3…1.1.0

  • Added a .GetPerceivedBrightness method to return a value representing colour visibility

There is now a submodule designed for colour harmony and theming. These methods include:

  • Analogous - Generates an analogous colour palette
  • Complementary - Generates a complementary colour palette (essentially .Invert() or .Rotate(..., 180))
  • Monochromatic - Generates a monochromatic colour palette
  • SplitComplementary - Generates a split complementary colour palette
  • Tetradic - Generates a tetradic colour palette
  • Triadic - Generates a triadic colour palette
  • Vibrant - Determines the most vibrant colour when passed an array of colours
3 Likes
#8

Oops! Looks like I completely neglected this thread! Here’s the backlog:

v1.1.1

What’s Changed

  • Added GetContrastingColour to adjust a foreground colour to meet the minimum contrast ratio on a background colour

Full Changelog: 1.1.0...1.1.1

v1.2.0

What’s Changed

Added

  • WCAG submodule to house the current .GetContrastRatio and .GetContrastingColour methods.
  • APCA submodule, which contains an updated version of .GetContrastRatio.
  • Implemented colour blindness simulation under the Blind submodule.
    • Supports the Trichroma-, Protan-, Deutan-, Tritan- and Achroma- groups.
    • Includes friendly “Enums” for non-scientists.
  • Documentation site using moonwave.
  • TypeScript alias for .GetContrastingColour in root namespace (previously only Luau).

Changed

  • .GetContrastRatio and .GetContrastingColour now redirect to the WCAG submodule.
  • Updated toolchain to use rojo 7; fixed other dependencies to an exact version.

Removed

  • Removed rotriever.toml to drop support for kayak and other rotriever-based package managers.

Full Changelog: 1.1.1...1.2.0

3 Likes
#9

v1.3.0

Here’s a preview of the new Tailwind-style palettes that can be generated using the palettes API:
> Original Tweet

What’s Changed

Added

  • Implemented colour space conversions.
    • HSL (.fromHSL, .toHSL).
    • LAB (.fromLAB, .toLAB) (:test_tube: experimental).
    • LCH (.fromLCH, .toLCH) (:test_tube: experimental).
  • Saturation methods to either saturate or desaturate a colour.
  • Tailwind CSS-style palette generator - Generates 10 swatches, given a base colour, and returns a TailwindPalette object (see the docs for more details).

Changed

  • Updated the docs for Hex and Int. The converter methods were previously documented in PascalCase, but they should have been documented in camelCase.
  • The Palette.Monochromatic method now accepts an optional second parameter, swatches, which defaults to 3. This is to allow for more control over the number of swatches generated.
    • :warning: Warning: The behaviour of monochromatic has been changed to allow for more control over the number of swatches generated.
    • The new behaviour will return X amount of swatches, including the base colour. The results do not necessarily include a single lighter and darker swatch, and the resulting array is now sorted from darkest to lightest (most vibrant).

Full Changelog: 1.2.0...1.3.0

1 Like
#10

v1.3.1

What’s Changed

Added

  • Blend.Transparency - Applies “transparency” to a Color3, where the resulting colour simulates the process of overlaying a colour with transparency to a given background.
  • Hex.fromHexRGBA - Converts a hex code with an alpha channel to a Color3. You must pass a background colour to this method if your background is not black (Color3.new(0, 0, 0))!

Full Changelog: 1.3.0...1.3.1

#11

How would you lerp LCH values?

#12

it’s not built into the library. the lch methods just convert an lch table to color3 and back; however, I found this site that seems to implement a way of lerping lch values

if lerping in other colour spaces is something you’d like, I can add it to the to-do list :relaxed:

1 Like
#13

Yes! I would highly appreciate it if you added lerping in other colour spaces since lerping in regular RGB space creates some weird colours on the in-betweens.

1 Like