Color

Ein Farbsystem auf Klassenbasis, mit Umrechnungshelfern für RGB, RGBA, HSL, HSLA, HSB/HSV und hexadezimale Farben. Dabei sind eine reich ausgestattete Klasse Color, unveränderliche Wertklassen (Rgb, Rgba, Hsl, Hsla), der Palettengenerator ColorScheme, ein Satz eigenständiger Umrechnungsfunktionen und FMT, die ANSI-Stiltabelle fürs Terminal.

Die einfacheren Helfer hexToRgb, rgbToHex und randomColor haben eigene Seiten: hexToRgb, rgbToHex, randomColor. Sie werden aus demselben Modul erneut exportiert.

API

Color

Die zentrale Farbklasse. Sie nimmt eine Hex-Zeichenkette, ein Array [r, g, b, a] oder die Kanäle als einzelne Zahlen und berechnet sogleich jede Darstellung (rgb, rgba, hex, hsl, hsla) sowie die direkten Zugriffe auf die einzelnen Kanäle.

Konstruktor

new Color(
  r: string | number | Array<string | number>,
  g?: string | number,
  b?: string | number,
  a?: string | number,
)

Parameter

Properties

Methods

Rgb

Ein RGB-Wertobjekt, aus einem Array gebaut. toString() gibt eine CSS-Zeichenkette rgb(...) zurück.

Konstruktor

new Rgb(col: Array<string | number>) // [r, g, b]

Eigenschaften und Methoden

Rgba

Erweitert Rgb um einen Alphakanal. toString() gibt eine CSS-Zeichenkette rgba(...) zurück.

Konstruktor

new Rgba(col: Array<string | number>) // [r, g, b, a]

Eigenschaften und Methoden

Hsl

Ein HSL-Wertobjekt, aus einem Array gebaut. toString() gibt eine CSS-Zeichenkette hsl(...) zurück.

Konstruktor

new Hsl(col: Array<string | number>) // [h, s, l]

Eigenschaften und Methoden

Hsla

Erweitert Hsl um einen Alphakanal. toString() gibt eine CSS-Zeichenkette hsla(...) zurück.

Konstruktor

new Hsla(col: Array<string | number>) // [h, s, l, a]

Eigenschaften und Methoden

ColorScheme

Erzeugt eine Palette verwandter Color-Objekte – entweder unmittelbar aus einer Liste von Farben oder aus einer Grundfarbe, die um ein Array von Farbtonwinkeln gedreht wird. Statische Fabrikmethoden decken die gängigen Harmonieschemata ab.

Konstruktor

new ColorScheme(colorVal: (string | number)[], angleArray: number[])

Eigenschaften und Methoden

Statische Fabrikmethoden

Jede nimmt eine Grundfarbe und gibt ein ColorScheme mit einem fest vorgegebenen Satz von Farbtonwinkeln zurück.

Umrechnungsfunktionen

Eigenständige Funktionen, die Color intern benutzt; alle sind zum unmittelbaren Gebrauch exportiert. Wo eine Funktion drei Kanäle entgegennimmt, darf das erste Argument auch ein einzelnes Array sein (etwa rgbToHsl([r, g, b])).

componentToHex, rgbToHex und hexToRgb sind die grundlegenden Bausteine; siehe rgbToHex und hexToRgb.

Helfer fürs Alpha

Alpha wird hier von 0 bis 100 angegeben – auf derselben Prozentskala, die das übrige Modul für Sättigung und Helligkeit benutzt, und nicht von 0 bis 1, wie es das CSS-rgba() nimmt.

Helfer für Mischung und Shader-Mathematik

Die Misch- und Farbkorrekturmathematik hinter den Nachbearbeitungsfiltern von ranuts/visual (ColorAdjustFilter und Verwandte), hier exportiert zur Wiederverwendung auf der CPU-Seite (etwa um eine Miniaturvorschau zu berechnen, ohne eine GPU-Strecke hochzufahren). Anders als im übrigen Modul laufen die Kanäle hier von 0 bis 1, nicht von 0 bis 255 oder 0 bis 100 – so, wie es in Shadern üblich ist.

import { blendScreen, brightnessContrast, cosinePalette, srgbToLinear, linearToSrgb } from 'ranuts/utils';

// Zwei Farben von 0 bis 1 im Modus Negativ multiplizieren mischen
const screened = blendScreen([0.8, 0.2, 0.1], [0.1, 0.5, 0.9]);

// Kontrast anheben und Helligkeit etwas senken
const graded = brightnessContrast([0.6, 0.6, 0.6], -0.05, 1.2);

// Eine prozedural erzeugte Verlaufspalette bei t=0.35 abtasten
const swatch = cosinePalette(0.35, [0.5, 0.5, 0.5], [0.5, 0.5, 0.5], [1, 1, 1], [0, 0.33, 0.67]);

// Gammarichtige Rechnung (Mischen, Beleuchtung) gehört in den linearen Raum
const linear = srgbToLinear(0.5);
const backToSrgb = linearToSrgb(linear); // ≈ 0.5

Formatmuster

Reguläre Ausdrücke zum Prüfen von Farbzeichenketten. RGB_REGEX und RGBA_REGEX dulden keine Leerzeichen; entferne sie vorher (value.replace(/\s+/g, '')).

FMT

Eine Sammlung von ANSI-Escape-Paaren fürs Terminal, mit denen sich Text gestalten und einfärben lässt. Jeder Eintrag ist ein Tupel [öffnen, schließen], das du um eine Zeichenkette legst, um die Ausgabe zu gestalten.

const FMT: Record<string, Array<string>>;

Verfügbare Schlüssel: bold, dim, reset, italic, underline, inverse, hidden, strikethrough, black, red, green, yellow, blue, magenta, cyan, white, gray sowie die Hintergrundvarianten bgBlack, bgRed, bgGreen, bgYellow, bgBlue, bgMagenta, bgCyan, bgWhite.

Beispiel

Eine Color erzeugen

import { Color } from 'ranuts';

// Aus einer Hex-Zeichenkette (kurze oder lange Form, # wahlweise)
const red = new Color('#ff0000');
console.log(red.hex); // '#ff0000'
console.log(red.rgb.toString()); // 'rgb(255,0,0)'
console.log(red.hsl.toString()); // 'hsl(0,100%,50%)'

// Aus einzelnen Kanälen
const green = new Color(0, 255, 0);
console.log(green.hex); // '#00ff00'

// Aus einem Array (mit Alpha)
const blue = new Color([0, 0, 255, 0.5]);
console.log(blue.rgba.toString()); // 'rgba(0,0,255,0.5)'

Eine Color über HSL verändern

import { Color } from 'ranuts';

const color = new Color('#ff0000');

color.setHue(120); // den Farbton bis ins Grüne drehen
console.log(color.rgb.toString()); // 'rgb(0,255,0)'

color.setLum(25); // dunkler
color.setSat(50); // Sättigung herausnehmen
color.setAlpha(0.4);
console.log(color.rgba.toString()); // 'rgba(...,0.4)'

Mit ColorScheme eine Palette bauen

import { ColorScheme } from 'ranuts';

// Komplementärpaar aus einer Grundfarbe
const compl = ColorScheme.Compl('#3498db');
console.log(compl.palette.map((c) => c.hex));

// Triadisches Schema (die Grundfarbe und zwei Farben im Abstand von 120°)
const triad = ColorScheme.Triad('#3498db');
console.log(triad.palette.length); // 3

// Unmittelbar aus einer Liste von Farben
const custom = new ColorScheme(['#ff0000', '#00ff00', '#0000ff']);
console.log(custom.palette.map((c) => c.hsl.toString()));

Die Umrechnungsfunktionen benutzen

import { rgbToHsl, hslToRgb, rgbToHsb, hsbToRgb, componentToHex } from 'ranuts';

console.log(rgbToHsl(255, 0, 0)); // [0, 100, 50]
console.log(hslToRgb(0, 100, 50)); // [255, 0, 0]
console.log(rgbToHsb(255, 0, 0)); // [0, 100, 100]
console.log(hsbToRgb(0, 100, 100)); // [255, 0, 0]
console.log(componentToHex(255)); // 'ff'

// Wo es beschrieben ist, wird auch ein Array als Eingabe angenommen
console.log(rgbToHsl([0, 128, 255])); // [h, s, l]

Terminalausgabe mit FMT gestalten

import { FMT } from 'ranuts';

const [open, close] = FMT.green;
console.log(`${open}success${close}`); // im Terminal steht "success" in Grün

const bold = FMT.bold;
console.log(`${bold[0]}important${bold[1]}`);

Hinweise

1. Alles wird sofort berechnet: Eine Color berechnet im Konstruktor sämtliche Darstellungen, hex, rgb, rgba, hsl und hsla stimmen also vom Augenblick der Erzeugung an überein.
2. Die HSL-Setter berechnen RGB neu: setHue, setSat und setLum ändern das HSL und leiten dann über updateFromHsl RGB und Hex neu her. setAlpha rührt nur an rgba und hsla.
3. Eingabe als Array oder als Kanäle: Mehrere Umrechnungsfunktionen (rgbToHex, rgbToHsl, hslToRgb) nehmen entweder drei einzelne Kanäle oder ein einzelnes Array als erstes Argument.
4. HSV und HSB: hsvToRgb ist ein anderer Name für hsbToRgb, und hsvToHsl einer für die Umrechnung von HSB nach HSL. HSV und HSB meinen hier dasselbe Modell.
5. FMT gilt nur fürs Terminal: Die ANSI-Escape-Folgen erscheinen nur in einem Terminal als Gestaltung, das sie versteht; in der Browserkonsole stehen sie als rohe Steuerzeichen da.