RampenSau

Depending on your module system (ESM or CJS) or environment (Node.js or Browser), use the appropriate import method.

ES Modules (Individual methods):

import { generateColorRamp } from "rampensau";

ES Modules (Direct MJS path):

import { generateColorRamp } from "rampensau/dist/index.mjs";

CommonJS:

let generateColorRamp = require("rampensau");

Browser (UMD/CDN):

<script src="https://cdn.jsdelivr.net/npm/rampensau/dist/index.js"></script>

Browser (ESM via esm.sh):

<script type="module">
  import { generateColorRamp } from "https://esm.sh/rampensau/";
</script>

Install the rampensau package using your preferred package manager.

npm install rampensau

The generateColorRamp function builds a color sequence by interpolating three independent channels: Hue, Saturation, and Lightness.

1. Hue: Calculated using hStart, hCycles, and hEasing. It determines the color's position on the color wheel.
2. Saturation: Interpolates between sRange[0] and sRange[1] using the sEasing function.
3. Lightness: Interpolates between lRange[0] and lRange[1] using the lEasing function.

If a hueList is provided, the hue channel is overridden by the values in the list, but saturation and lightness interpolation still applies to each element in the list. The transformFn is applied to the resulting [h, s, l] values to produce the final output type T.

If you provide a hueList option, all other hue-related options (total, hStart, hCycles, etc.) are ignored. hueList expects an array of hues [0…360].

You can combine this with colorUtils.uniqueRandomHues to generate a ramp from a set of non-overlapping random colors.

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

const { uniqueRandomHues } = colorUtils;

// Generates a ramp of 4 colors with at least 90° between each hue
generateColorRamp({
  hueList: uniqueRandomHues({
    startHue: Math.random() * 360, 
    total: 4, 
    minHueDiffAngle: 90,
  })
});

The harveyHue(h) utility transforms a hue to create a more evenly distributed spectrum. This helps avoid the over-abundance of green and ultramarine found in standard HSL/HSV color wheels.

Parameters:

• h (float 0…360): The hue value to transform, normalized to the 0-360 range.

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

const transformedHue = harveyHue(120); // 120° (green) -> redistributed hue

generateColorRamp(Options{}) is the core function. It returns an array of colors in a polar format (typically HSL/HSV), where each color is an array: [Hue, Saturation, Lightness].

• Hue: 0–360 degrees.
• Saturation: Normalized 0–1.
• Lightness: Normalized 0–1.

Note: While the output is structured like HSL, these values can be mapped to other models like LCH or OKLCH. Use the colorToCSS utility to handle conversions to CSS strings automatically.

import { generateColorRamp } from 'rampensau';

const hslColorValues = generateColorRamp({
  total: 9,
  hStart: Math.random() * 360,
  hCycles: 1,
  hStartCenter: 0.5,
  hEasing: (x, fr) => x,
  sRange: [0.4, 0.35],
  sEasing: (x, fr) => Math.pow(x, 2),
  lRange: [Math.random() * 0.1, 0.9],
  lEasing: (x, fr) => Math.pow(x, 1.5),
  transformFn: (color, i) => color;
}); // => [[0…360,0…1,0…1], …]

RampenSau generates colors in the format [hue, saturation, lightness] (e.g., [0…360, 0…1, 0…1]). To use these in CSS or Canvas, use colorToCSS(color, mode).

Parameters:

• color (array): The color array [0…360, 0…1, 0…1].
• mode (string): The color mode. Supported values: hsl, hsv, lch, or oklch. Defaults to oklch.

Note on Gamuts:

• hsl is clamped to the sRGB gamut.
• lch and oklch utilize the full gamut supported by the target device/monitor.

import {
  colorUtils
} from "rampensau";

const { colorToCSS } = colorUtils;

// Assuming generateColorRamp() is available
console.log( 
  generateColorRamp().map(color => colorToCSS(color, 'oklch')) 
); // ['oklch(5.57% 40% 348.39)', ...]

Use uniqueRandomHues(Options{}) to return an array of unique random hues. This is particularly useful for populating the hueList option in generateColorRamp. While you can use a random easing function directly in generateColorRamp, uniqueRandomHues guarantees that the base hues are distinct.

Options:

• startHue (float 0…360): The starting point of the hue ramp (e.g., 0 for Red, 180 for Teal). If omitted, a random hue is picked using rndFn.
• total (int 3…∞): The number of base colors to generate.
• minHueDiffAngle (float 0…360): The minimum angle required between hues.
• rndFn (function): The random function to use. Defaults to Math.random.

// Example usage is implied as a provider for hueList
// generateColorRamp({ hueList: uniqueRandomHues({ total: 5 }) })

The lerpHue(amt, from, to) function interpolates between two hues (in degrees) along the shortest arc around the color wheel. This ensures that the interpolation wraps correctly across the 0/360 boundary, preventing the 'long way around' sweep that standard linear interpolation (lerp) causes.

import { utils } from 'rampensau';
const { lerpHue } = utils;

// Interpolates between 350 and 10 via the 0/360 seam
const hue = lerpHue(0.5, 350, 10);

The utils object provides several helper functions for array manipulation and curve calculations:

• shuffleArray(array, rndFn): Returns a new shuffled array. rndFn defaults to Math.random.
• lerp(amt, from, to): Standard linear interpolation between two values.
• pointOnCurve(curveMethod, curveAccent): Returns a function that calculates the point on a curve at a given t value.
• makeCurveEasings(curveMethod, curveAccent): Generates saturation and lightness easing functions based on a curve method.

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