RYBitten

RYBitten

A color space conversion library for transforming between RGB and RYB (Red-Yellow-Blue) colors.

What is RYBitten?

RYBitten is a lightweight library for translating colors between RGB and a custom RYB (Red-Yellow-Blue) color space. It's designed for developers, generative artists, and designers who want to create harmonious, consistent, or randomized color palettes effortlessly. The library emulates Johannes Itten's chromatic circle using trilinear interpolation and customizable options, making it a versatile tool for creative projects.

"Play becomes joy, joy becomes work, work becomes play." Johannes Itten, Bauhaus

What's new in 1.0

• Stable API. v1.0 locks the public surface; see STABILITY.md for what's covered by semver.
• Fully tested. Vitest suite covering conversion math, HSL helpers, and an algorithmic roundtrip for every historical cube — 215 tests, 95%+ branch coverage.
• Modern tooling. ESLint 9 flat config, typescript-eslint 8, TypeScript 5.9.
• CI-backed. GitHub Actions runs lint, type-check, tests, build, and a tarball smoke test on Node 22 and the current LTS.
• Tighter p5 types. The p5 extension ships with real types instead of a file-wide any suppression.

Features ✨

• Color Conversion: Effortlessly translate between RGB and a custom RYB space.
• Easy Integration: A tiny library with no dependencies.
• Customizable Gamuts: Experiment with historical color spaces or create your own.
• Subtractive Color Model: Emulates subtractive color.

Installation

Install RYBitten with your favorite package manager:

npm install rybitten

Or include it directly in your HTML:

Include RYBitten in your project

// ES6 style
import { ryb2rgb } from "rybitten";

// CommonJS style
const { ryb2rgb } = require("rybitten");

Usage in Browser / p5.js (UMD)

For projects that don't use a bundler (like p5.js sketches), you can use the UMD build. This exposes a global rybitten object.

p5.js Color Mode Extension

RYBitten includes a special p5.js extension that adds native RYB color mode support, just like RGB, HSB, or HSL. The extension automatically initializes when you include the p5-specific UMD build:

Available Color Modes:

• RYB - Red-Yellow-Blue color mode (0-255 range by default)
• RYBHSL - RYB with Hue-Saturation-Lightness (360, 100, 100 range by default)

Using Custom Color Cubes in p5.js:

…

The extension works with both p5.js 1.x and 2.0, and supports both global and instance modes.

Quick Start

All RGB and RYB values are in the range [0, 1].

import { ryb2rgb } from "rybitten";

const rgbColor = ryb2rgb([1, 0, 0.5]);

console.log(rgbColor); // Outputs the RGB equivalent

API Reference

ryb2rgb(coords: ColorCoords, {cube?: ColorCube = RYB_ITTEN, easingFn? = easingSmoothstep}): ColorCoords

Convert RYB to RGB using trilinear interpolation.

• coords: [0…1, 0…1, 0…1] RYB coordinates
• options: (optional) An object with the following properties:
  • cube: (optional): See the note on the color cube below defaults to RYB_ITTEN
  • easingFn: (optional) Custom easing function used for the interpolation, defaults to smoothstep
• @return: [0…1, 0…1, 0…1] RGB coordinates

Note: RYB uses a subtractive color model where black = all colors, white = no colors. white will turn to black, and black will turn to white.

Note: Inputs are not clamped. Values outside [0, 1] are extrapolated through the easing function and the cube, and the result may fall outside [0, 1]. Clamp first if you need in-gamut output.

rybHsl2rgb(hsl: [h: number, s: number, l: number], options?): ColorCoords

Convert HSL to RGB, then apply the RYB space.

• hsl: Array of [hue (0…360), saturation (0…1), lightness (0…1)]
• options: (optional) An object with the following properties:
  • cube: (optional) See the note on the color cube below
  • easingFn: (optional) A custom easing function for the interpolation, defaults to smoothstep
  • invertLightness: (optional) Inverts the lightness value, defaults to true (0 is black, 1 is white), if set to false l:0 is white, l:1 is black
• @return: [0…1, 0…1, 0…1] RGB coordinates

Converts HSL coordinates to RGB, then translates them to the custom RYB color space using ryb2rgb. The HSL coordinates are in the range [0,360], [0, 1], [0, 1]. Lightness is inverted to match the RYB color space.

Interpolation Color Cube ️

The default RYB color cube used for interpolation in RYBitten is tuned to mimic Johannes Itten's chromatic circle. By adjusting the cube, you can achieve different effects and customize the RYB to RGB conversion.

The cube is inverted to match the subtractive color model, where white is the absence of color and black is the presence of all colors.

const RYB_CUBE = [
  // White
  [253 / 255, 246 / 255, 237 / 255],

  // Red
  [227 / 255, 36 / 255, 33 / 255],

  // Yellow
  [243 / 255, 230 / 255, 0],

  // Orange
  [240 / 255, 142 / 255, 28 / 255],

  // Blue
  [22 / 255, 153 / 255, 218 / 255],

  // Violet
  [120 / 255, 34 / 255, 170 / 255],

  // Green
  [0, 142 / 255, 91 / 255],

  // Black
  [29 / 255, 28 / 255, 28 / 255],
];

Custom Gamuts Presets

The library ships with a curated list of color gamuts that you can use to experiment with different color spaces. The default gamut is based on the work of Johannes Itten. But you can access other gamuts by importing the CUBES map.

Each gamut is an object with the following properties:

• title: The name of the color space
• reference: A reference image used to pick the edges of the custom color gamut
• year: The year the color space was introduced
• cube: The color cube used for interpolation

The presets are frozen. To tweak one, copy it first: cube.map(rgb => [...rgb]).

import { rybHsl2rgb } from "rybitten";
import { cubes } from "rybitten/cubes";

const { cube } = cubes.get("munsell");

console.log(cube);
/**
 * [
 *  ...8 ColorCoords entries
 * ]
 */

rybHsl2rgb([0, 1, 0.5], { cube });

TypeScript Support

RYBitten is written in TypeScript and includes type definitions out of the box:

import type { ColorCoords, ColorCube } from "rybitten/cubes";

Available Color Gamuts

The library provides a collection of historical and modern color gamuts through the cubes Map. Import and use them like this:

import { rybHsl2rgb } from "rybitten";
import { cubes } from "rybitten/cubes";

// Access any gamut by its key
const munsellCube = cubes.get("munsell").cube;
const albersCube = cubes.get("albers").cube;

// Use it in color conversion
const rgbColor = rybHsl2rgb([0, 1, 0.5], { cube: munsellCube });

// Get metadata about the color space
const { title, author, year, reference } = cubes.get("munsell");

Historical Color Spaces

Key	Title	Year	Reference
itten	Johannes Itten: Chromatic Circle	1961	reference
itten-normalized	Johannes Itten: Chromatic Circle (Paper-white)	1961	reference
itten-neutral	Nathan Gossett & Baoquan Chen: Paint Inspired Color Compositing	2004	reference
bezold	Wilhelm von Bezold: Farbentafel	1874	reference
boutet	Claude Boutet: Twelve-color color circles	1708	reference
hett	J. A. H. Hett: RGV Color Wheel	1908	reference
schiffermueller	Ignaz Schiffermüller: Versuch eines Farbensystems	1772	reference
harris	Moses Harris: The Natural System of Colours	1766	reference
harrisc82	Moses Harris / C82: The Natural System of Colours	1766	reference
harrisc82alt	Moses Harris / C82: The Natural System of Colours (alt)	1766	reference
goethe	Goethe: Farbenkreis	1809	reference
munsell	Munsell Color System	1905	reference
munsell-alt	Cleland & Munsell: A Grammar of Color	1921	reference
hayter	Charles Hayter: New Practical Treatise on the Three Primitive Colours	1826	reference
bormann	Heinrich-Siegfried Bormann: Gouache tint study for Josef Alber's Preliminary Course"	1931	reference
chevreul	Michel Eugène Chevreul: Chromatic Circle	1839
runge	Philipp Otto Runge: Farbenkugel	1810	reference
maycock	Mark M. Maycock's "Scale of Normal Colors and thei