RampenSau 🎢🐷🎨

RampenSau is a color palette generation library that utilizes hue cycling and easing functions to generate color ramps. It can generate a sequence of hues, or use a list of hues to generate a color ramp.

Perfect for generating color palettes for data visualizations, visual design, generative art, or just for fun.

Demos

• Official Docs & Demo Interactive Documentation with example function calls
• 1000 Generative Samples Generating a 1000 palettes using similar settings in with lch
• p5.js Example 3d example using p5.js's color() function
• Syntax Highlighting Generative syntax highlighting themes using RampenSau
• Mini HDR Posters Generative posters using lCH (p3+ gamut)
• Color Ratios Generative rectangles
• p5.js Stamps Fork of a sketch originally made by Okazz.
• Farbvelo Color Generator. Project this code is based on

Installation

Rampensau is bundled as both UMD and ES on npm. Install it using your package manager of choice:

npm install rampensau

You can then import RampenSau into your project:

// ES style: import individual methods
import { generateColorRamp } from "rampensau";

// Depending on your setup, you might need to import the MJS version directly
import { generateColorRamp } from "rampensau/dist/index.mjs";

// CJS style
let generateColorRamp = require("rampensau");

Or include it directly in your HTML:

<script src="https://cdn.jsdelivr.net/npm/rampensau/dist/index.js"></script>
<!-- or -->
<script type="module">
  import { generateColorRamp } from "https://esm.sh/rampensau/";
</script>

Basic Usage

import { generateColorRamp } from 'rampensau';

const hslColorValues = generateColorRamp({
  // hue generation options
  total: 9,                           // number of colors in the ramp
  hStart: Math.random() * 360,         // hue at the start of the ramp
  hCycles: 1,                           // number of full hue cycles 
                                       // (.5 = 180°, 1 = 360°, 2 = 720°, etc.)
  hStartCenter: 0.5,                    // where in the ramp the hue should be centered
  hEasing: (x, fr) => x,                // hue easing function x is a value between 0 and 1 
                                       // fr is the size of each fraction of the ramp: (1 / total)

  // if you want to use a specific list of hues, you can pass an array of hues to the hueList option
  // all other hue options will be ignored

  // hueList: [...],                      // list of hues to use

  // saturation
  sRange: [0.4, 0.35],                 // saturation range
  sEasing: (x, fr) => Math.pow(x, 2),   // saturation easing function

  // lightness
  lRange: [Math.random() * 0.1, 0.9],  // lightness range
  lEasing: (x, fr) => Math.pow(x, 1.5), // lightness easing function

  transformFn: (color, i) => color; // function to adjust/convert the color after generation
}); // => [[0…360,0…1,0…1], …]

generateColorRamp(Options{})

generateColorRamp is the core function of RampenSau. It returns an array of colors in HSL format ([0…360, 0…1, 0…1]). To get a better understanding of the options, it might be helpful to familiarize yourself with the HSL color model or to play with the interactive Demo / Documentation.

The function returns an array of colors, each represented as an array of three values: [Hue, Saturation, Lightness]. Hue is in degrees (0-360), while Saturation and Lightness are normalized values between 0 and 1. We use the term "HXX" loosely because while the structure is similar to HSL, these base values can be mapped to various polar color models like HSL, HSV, LCH, or OKLCH.

Important: When converting to a specific model, map these values appropriately. For HSL, Saturation and Lightness map directly (usually scaled to percentages). For models like LCH or OKLCH, the library's Saturation value needs to be mapped and potentially scaled to represent Chroma, and Lightness maps to the corresponding Lightness component. The examples using CSS (hsl(), oklch()) and the Culori library demonstrate this mapping and scaling. The provided colorToCSS helper function handles this conversion automatically for common CSS formats.

Options

Every single option has a default value, so you can just call the function without any arguments. It will generate a color ramp with 9 colors, starting at a random hue, with a single hue cycle.

While the function always generates some sort of color ramp, there are two main ways to generate hues independently of saturation and lightness: Let the function generate a sequence of hues, or pass a list of hues to use.

Hue sequence generation

If you want to generate a sequence of hues, you can use the following options:

• total int 3…∞ → Amount of colors the function will generate.
• hStart float 0…360 → Starting point of the hue ramp. 0 Red, 180 Teal etc..
• hStartCenter: float 0…1 → Center the hue in the color ramp. 0 = start, 0.5 = middle, 1 = end.
• hCycles float -∞…0…+∞ → Number of hue cycles. (.5 = 180°, 1 = 360°, 2 = 720°, etc.)
• hEasing function(x) → Hue easing function

The hStart sets the starting point of the hue ramp. The hStartCenter sets where in the ramp the hue should be centered. If your ramp starts with a high or low lightness, you might want to center the hue in the middle of the ramp. That is why the default value for hStartCenter is 0.5. (In the center of a given ramp).

The hStartCenter option tells the function where the start hue should be in your ramp. A value of 0 will generate a ramp that starts with the hue at the beginning of the ramp. A value of 0.5 will generate a ramp that starts with the hue in the middle of the ramp. A value of 1 will generate a ramp that starts with the hue at the end of the ramp.

The hCycles option sets the number of hue cycles. A value of 1 will generate a ramp with a single hue cycle. Meaning they will go around the color wheel once. A value of 0.5 will generate a ramp with 180° hue cycle (starting from hStart to its complementary hue). A value of 2 will rotate around the color wheel twice. A value of -1 will generate a ramp with a reversed hue cycle. A value of -0.5 will generate a ramp with a reversed 180° hue cycle. A value of -2 will generate a ramp with a reversed 720° hue cycle.

Note: The further away hCycles is from 0, the more hue variation you will get in the ramp.

Hue List

If you want to use a specific list of hues, you can pass an array of hues to the hueList option. All other hue options will be ignored. For example, if you want to generate a ramp with 3 colors, but you want to use random unique hues, you can do this:

• hueList array [0…360] → List of hues to use. All other hue options will be ignored.

Example:

import {
  generateColorRamp,
  colorUtils,
} from "rampensau";

const { uniqueRandomHues } = colorUtils;


generateColorRamp({
  hueList: uniqueRandomHues({
    startHue: Math.random() * 360, 
    total: 5, 
    minHueDiffAngle: 90,
  })
})

The uniqueRandomHues function will generate a list of unique hues with a minimum distance of 90° between each hue. This list is then passed to the hueList option of generateColorRamp. uniqueRandomHues is also exported by RampenSau, so you can use it directly.

Saturation & Lightness

• sRange array [0…1,0…1] → Saturation Range
• lRange array [0…1,0…1] → Lightness Range

Easing Functions

Each of the color dimensions can be eased using a custom function. The function takes an input value x and returns a value between 0 and 1:

• hEasing function(x) → Hue easing function
• sEasing function(x) → Saturation easing function
• lEasing function(x) → Lightness easing function

Transform Function

• transformFn function(color, i) → Function to adjust/transform or convert the color after generation. The function takes the generated color and its index as arguments. You can use this function to apply any adjustments you want to the generated colors.

Example:

const hslColorValues = generateColorRamp({
  transformFn: ([h, s, l], i) => {
    // Adjust the color to be more saturated
    return [h, s, .2 + l * .8];
  }
});

It could also be used to get a CSS String instead of the array. Just use the colorToCSS function from the color utility functions:

const hslColorValues = generateColorRamp({
  transformFn: ([h, s, l]) => colorToCSS(color, 'oklch')
});

TypeScript Node transformFn is typed as (color: number[], i: number) => number[] | string. If you need to return anything else, you can use a type assertion to cast the return value to whatever you need.

generateColorRampWithCurve(Options{})

generateColorRampWithCurve is a convenience function that uses pre-defined curve methods for easing functions. It accepts all the same options as generateColorRamp plus two additional options:

• curveMethod string → The curve method to use for easing. One of 'lamé', 'sine', 'power', or 'linear'.
• curveAccent float 0…5 → The accent of the curve, affecting how pronounced the curve's effect is.

Note: It is recommended to use HSV as the color space for the curveMethod option. It produces nicer looking ramps and is easier to work with, because the lightness and saturation are both 100% at the upper right corner of the the HSV slice.

Example:

import { generateColorRampWithCurve } from 'rampensau';

const hslColorValues = generateColorRampWithCurve({
  total: 9,
  hStart: 180,
  curveMethod: 'lamé',
  curveAccent: 0.5,
  sRange: [0.4, 0.8],
  lRange: [0.2, 0.8],
}); // => [[0…360,0…1,0…1], …]

Hue Generation Functions

uniqueRandomHues(Options{})

Function returns an array of unique random hues. Mostly useful for generating a list of hues to use with hueList. Alternatively you can use (x) => Math.random() as the hEasing function in generateColorRamp but this will not guarantee unique hues.

• startHue float 0…360 → Starting point of the hue ramp. 0 Red, 180 Teal etc..
• total int 3…∞ → Amount of base colors.
• minHueDiffAngle float 0…360 → Minimum angle between hues.
• rndFn function() → Random function. Defaults to Math.random.

colorHarmonies.colorHarmony(Options{})

Function returns an array of hues based on color harmony theory.

Available harmonies:

• complementary - Base hue and its complement (180° opposite)
• splitComplementary - Base hue and two hues on either side of its complement
• triadic - Three hues evenly spaced around the color wheel
• tetradic - Four hues evenly spaced around the color wheel
• monochromatic - Just the base hue
• doubleComplementary - Two complementary pairs
• compound - A mix of complementary and analogous
• analogous - A series of adjacent hues

Example:

import {
  generateColorRamp,
  colorUtils,
} from "rampensau";

const { colorHarmonies } = colorUtils;

generateColorRamp({
  hueList: colorHarmonies.splitComplementary(Math.random() * 360),
  sRange: [0.4, 0.35],
  lRange: [Math.random() * 0.1, 0.9],
});

Color Utility Functions

To keep the library small, RampenSau does not include any color conversion functions. However, it does provide a few utility functions to help you work with RampenSau or its generated colors.

colorToCSS(color, mode)

In order to use the colors generated by RampenSau in CSS or Canvas, you need to convert them to a CSS color format. This helper function does just that. It returns a CSS string from a color in the format generated from generateColorRamp ([0…360,0…1,0…1]).

• color array [0…360,0…1,0…1] → Color in format generated from generateColorRamp ([0…360,0…1,0…1]).
• mode string → Color mode to use. One of hsl, hsv, lch or oklch. Defaults to oklch. (Note that hsl is clamped to the sRGB gamut, while lch and oklch will make use of the full gamut supported by the target monitor / device.)

Example:

import {
  colorUtils
} from "rampensau";

const { colorToCSS } = colorUtils;

console.log( 
  generateColorRamp().map(color => colorToCSS(color, 'oklch')) 
); // ['oklch(5.57% 40% 348.39)', 'oklch(14.59% 38.72% 314.74)', …]

harveyHue(h)

Transforms a hue to create a more evenly distributed spectrum without the over-abundance of green and ultramarine in the standard HSL/HSV color wheel. Originally written by @harvey and adapted for use in RampenSau.

• h float 0…360 → Hue value to transform, normalized to 0-360 range.

Example:

import { colorUtils } from "rampensau";
const { harveyHue } = colorUtils;

const transformedHue = harveyHue(0.5); // Returns a transformed hue value

Using RampenSau with a color library

If you are already using a color library like culori you can use its formatCSS function instead. Just don't forget to scale the chroma value to the adequate range.

culori.formatCss({ mode: 'oklch', 
  l: color[2],
  c: color[1] * 0.4,
  h: color[0],
})

culori.formatCss({ mode: 'lch', 
  l: color[2] * 100,
  c: color[1] * 150,
  h: color[0],
});

Other Utility Functions

RampenSau also provides several utility functions for working with arrays and curves:

Usage

import { utils } from 'rampensau';
const { shuffleArray, scaleSpreadArray, lerp, pointOnCurve, makeCurveEasings } = utils;

shuffleArray(array, rndFn)

Returns a new shuffled array based on the input array.

• array array → The array to shuffle
• rndFn function() → Random function. Defaults to Math.random

scaleSpreadArray(valuesToFill, targetSize, padding, fillFunction)

Scales and spreads an array to the target size using interpolation. In the context of RampenSau, this is used to create a smooth transition between colors. Let's say you have an array of 3 colors and you want to create a ramp of 10 colors. You can use this function to fill the gaps between the colors and create a smooth transition.

• valuesToFill array → Initial array of values
• targetSize int → Desired size of the resulting array
• padding float 0…1 → Optional padding value (defaults to 0)
• fillFunction function → Interpolation function (defaults to lerp)

lerp(amt, from, to)

Linearly interpolates between two values. Mainly used for the fillFunction in scaleSpreadArray.

• amt float 0…1 → The interpolation amount
• from number → The starting value
• to number → The ending value

pointOnCurve(curveMethod, curveAccent)

Returns a function that calculates the point on a curve at a given t value.

• curveMethod string or function → The curve method to use
• curveAccent float → The accent of the curve

makeCurveEasings(curveMethod, curveAccent)

Generates saturation and lightness easing functions based on a curve method.

• curveMethod string or function → The curve method to use
• curveAccent float → The accent of the curve

About the Name

For non-German speakers, "Rampe" in German means both a ramp (or gradient) and a theatrical stage. A "RampenSau" (literally "stage-sow/pig") is a German expression for someone who thrives in the spotlight - a natural performer. The name playfully combines this concept with the library's purpose of creating color ramps and gradients.

License

Rampensau is distributed under the MIT License. Feel free to use it in your projects, but please give credit where it's due. If you find this library useful, consider starring the repository on GitHub or sharing it with your friends and colleagues.