Color, a color management and manipulation library

Resources Community Resources
#1

:package: Install | :bookmark: Documentation | :notebook: Changelog | :memo: Source Code

Color is a Roblox Luau library for color management and manipulation, inspired by chroma.js.

Installing

The module is available in the library here if you want to install it using the Toolbox. You can also grab a release from GitHub and install it manually.

If you know how to use Rojo, you can build the latest code from the development branch to get the newest features. Keep in mind that this is development code, and things can break or change quickly.

Features

Some of the library’s features includes:

  • Reading colors from many different formats
  • Converting colors to many different formats
  • Color interpolation in different spaces
  • Creating gradients

For a full introduction to the library, you can read the documentation. Some example code of the library’s features is included below:

-- Accessing the modules
local ColorLib = require(...)

local Color = ColorLib.Color
local Gradient = ColorLib.Gradient

-- Constructors
local pink = Color.fromHex("#ff69b4")
local blue = Color.from("HSB", 240, 1, 1)
local yellow = Color.fromLab(0.97139, -0.21554, 0.94478)

local newYeller = Color.fromBrickColor(BrickColor.new("New Yeller"))
local white = Color.new(1, 1, 1) -- or Color.gray(1)

local hotpink = Color.named("hotpink")

-- Conversions
print(blue:toHex()) --> "0000ff"
print(blue:toHSB()) --> 240, 1, 1
print(blue:to("Lab")) --> 0.32297, 0.79188, -1.07860
print(blue:components()) --> 0, 0, 1

-- Interpolation
local red = Color.named("red")
local aqua = Color.named("aqua")

red:mix(aqua, 0.5)
red:mix(aqua, 0.5, "XYZ")
red:mix(aqua, 0.5, "Lab")
red:mix(aqua, 0.5, "Luv")

-- Gradients
local gradient = Gradient.fromColors(
    Color.named("red"),
    Color.named("green"),
    Color.named("blue")
)

print(gradient:color(0.6, "XYZ"):toHex()) --> "00737c"
print(gradient:color(0.6, "HSB", "Increasing"):to("Hex")) --> "00993d"

gradient:colors(50, "XYZ")
gradient:colorSequence(nil, "XYZ")

Another color-related project I have is ColorPane, a plugin that has tools for designing games. Consider checking it out.

16 Likes
#2

v0.2.0

Hello everyone, v0.2.0 is here. You can read the full changelog here, but here are the major updates:

:warning: indicates a breaking change

Added

  • Added alternative from/to functions for the various color types
    • e.g. Color.fromColor3(...) instead of Color.from("Color3", ...)
    • e.g. Color:toColor3() instead of Color:to("Color3")
  • Added Color.gray as a shortcut for creating achromatic colors
  • Added Color.harmonies for generating color harmonies
  • Added Color.deltaE for calculating color differences
  • Added Color.named for referencing CSS colors
  • Added the xyY color type

Removed

  • :warning: lRGB interpolation has been removed, since it can be done in XYZ

Changed

  • :warning: The Color and Gradient modules of the library are now split apart (please read the Module Split section below for more info)
    • You can access the modules using [Module].Color and [Module].Gradient
  • Updated the allowed interpolations for Color.mix
  • Color.isAColor should work for Colors from different versions of the library
  • Color.components now allows you to obtain unclipped components
  • Color.luminance compensates for the error from the equation provided in WCAG 2
  • :warning: Gradient.toColorSequence was renamed to Gradient.colorSequence

Module Split

In v0.1.0, the Color API and Gradient constructors were included directly inside the module.

local Color = require(...)

local aColor = Color.new(1, 1, 1)
local aGradient = Color.gradientFromColors(Color.new(0, 0, 0), Color.new(1, 1, 1)

In v0.2.0, the two modules have been split apart, and you need to access their APIs separately. This was done to reduce redundancy in the library’s code, as well as to allow the Gradient API to be directly accessed by developers, rather than only having its constructors being accessible by proxy.

local ColorLib = require(...)

local Color = ColorLib.Color
local Gradient = ColorLib.Gradient

local aColor = Color.new(1, 1, 1)
local aGradient = Gradient.fromColors(Color.new(0, 0, 0), Color.new(1, 1, 1)

Modifications will need to be made to existing code that uses the library, especially if you use Gradients. Apologies for any inconveniences this will cause.

If you have any features that want included in the library, feel free to let me know in a reply or message.

Thank you for using Color, and happy holidays!

:christmas_tree: :cookie:

#3

It’s kind of like… extremely unreasonable that a library this useful has literally 0 replies and 11 likes. This is an amazing resource and I’ve found many uses for it. Keep up the great work!!

1 Like
#4

I’m surprised how Color3 class API provides very little methods and things to manipulate color value, which apparently “bloats API” according to some people (which is magically fine in something like Unity, Unreal, Godot, etc.)
Safe to say you’re better off using a custom color module like yours for manipulating colors. If I’ll have to do color manipulations in the future, I might give this a try.