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 t