{"id":17970244,"url":"https://github.com/meodai/rampensau","last_synced_at":"2025-04-06T01:07:22.310Z","repository":{"id":40254801,"uuid":"493286040","full_name":"meodai/rampensau","owner":"meodai","description":"Color palette generation function using hue cycling and simple easing functions.","archived":false,"fork":false,"pushed_at":"2024-11-25T16:14:32.000Z","size":9655,"stargazers_count":77,"open_issues_count":0,"forks_count":2,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-03-30T00:09:02.675Z","etag":null,"topics":["color","color-scheme","colors","colour","colours","generative","generative-art","palette-generation"],"latest_commit_sha":null,"homepage":"https://meodai.github.io/rampensau/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/meodai.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-05-17T14:27:23.000Z","updated_at":"2025-03-21T00:25:01.000Z","dependencies_parsed_at":"2024-05-02T22:52:18.342Z","dependency_job_id":"6aaa7df7-5578-4595-955b-50c3219ae766","html_url":"https://github.com/meodai/rampensau","commit_stats":{"total_commits":55,"total_committers":2,"mean_commits":27.5,"dds":"0.018181818181818188","last_synced_commit":"7ccbaefcfaa39ba99fdc06d1416e47d9a241a7e8"},"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/meodai%2Frampensau","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/meodai%2Frampensau/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/meodai%2Frampensau/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/meodai%2Frampensau/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/meodai","download_url":"https://codeload.github.com/meodai/rampensau/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247419860,"owners_count":20936012,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["color","color-scheme","colors","colour","colours","generative","generative-art","palette-generation"],"created_at":"2024-10-29T15:02:24.803Z","updated_at":"2025-04-06T01:07:22.265Z","avatar_url":"https://github.com/meodai.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# RampenSau 🎢🐷\n\n**RampenSau** is a color palette generation function that utilizes **hue cycling** and\n**easing functions** to generate color ramps. It can generate a sequence of hues, or use a list of hues to generate a color ramp.\n\nPerfect for generating color palettes for data visualizations, visual design, generative art, or just for fun.\n\n![generated RampenSau color palettes Animation](./rampensau.gif)\n\n## Demos\n\n- [Official Docs \u0026 Demo](https://meodai.github.io/rampensau/)\n  Interactive Documentation with example function calls\n- [Two Random Color Ramps](https://codepen.io/meodai/pen/yLvgxQK?editors=0010)\n  Simple set of ramps with random easing\n- [Color Ratios](https://codepen.io/meodai/full/vYbwbym)\n  Simple generative rectangles\n- [Mini HDR Posters](https://codepen.io/meodai/pen/zYeXEyw)\n  Generative posters using lCH (p3+ gamut)\n- [1000 Generative Samples](https://codepen.io/meodai/pen/ExQWwar?editors=0010)\n  Simple example generating a 1000 palettes using similar settings in with lch\n- [Farbvelo Color Generator](https://farbvelo.elastiq.ch/).\n  Project this code is based on\n\n## Installation\n\n**Rampensau** is bundled as both UMD and ES on npm. Install it using your package manager of choice:\n\n```js\nnpm install rampensau\n```\n\nYou can then import RampenSau into your project:\n\n```js\n// ES style: import individual methods\nimport { generateColorRamp } from \"rampensau\";\n\n// Depending on your setup, you might need to import the MJS version directly\nimport { generateColorRamp } from \"rampensau/dist/index.mjs\";\n\n// CJS style\nlet generateColorRamp = require(\"rampensau\");\n```\n\nOr include it directly in your HTML:\n\n```html\n\u003cscript src=\"https://cdn.jsdelivr.net/npm/rampensau/dist/index.js\"\u003e\u003c/script\u003e\n\u003c!-- or --\u003e\n\u003cscript type=\"module\"\u003e\n  import { generateColorRamp } from \"https://esm.sh/rampensau/\";\n\u003c/script\u003e\n```\n\n## Basic Usage\n\n```js\nimport { generateColorRamp } from 'rampensau';\n\nconst hslColorValues = generateColorRamp({\n  // hue generation options\n  total   : 9,                           // number of colors in the ramp\n  hStart  : Math.random() * 360,         // hue at the start of the ramp\n  hCycles : 1,                           // number of full hue cycles \n                                         // (.5 = 180°, 1 = 360°, 2 = 720°, etc.)\n  hStartCenter : 0.5,                    // where in the ramp the hue should be centered\n  hEasing : (x, fr) =\u003e x,                // hue easing function x is a value between 0 and 1 \n                                         // fr is the size of each fraction of the ramp: (1 / total)\n\n  // if you want to use a specific list of hues, you can pass an array of hues to the hueList option\n  // all other hue options will be ignored\n\n  // hueList : […],                      // list of hues to use\n\n  // saturation\n  sRange  : [0.4, 0.35],                 // saturation range\n  sEasing : (x, fr) =\u003e Math.pow(x, 2),   // saturation easing function\n\n  // lightness\n  lRange  : [Math.random() * 0.1, 0.9],  // lightness range\n  lEasing : (x, fr) =\u003e Math.pow(x, 1.5), // lightness easing function\n}); // =\u003e [[0…360,0…1,0…1], …]\n```\n\n### generateColorRamp(Options{})\n\n**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](https://en.wikipedia.org/wiki/HSL_and_HSV) or to play with the interactive [Demo / Documentation](https://meodai.github.io/rampensau/).\n\nThe function returns an array of colors in HXX format (`[0…360,0…1,0…1]`). (HXX because you can use HSL, HSV, LCH, OKLCH et...) The first value is the hue, the second the saturation and the third the lightness. The hue is a value between 0 and 360, the saturation and lightness are values between 0 and 1. Typically you would convert the values to a polar color model like HSL, lCH or okLCh before using them. `hsl(${color[0]} ${color[1] * 100}% ${color[2]*100}%)` / `oklch(${color[2]*100}% ${color[1]*100}% color[0])` is a good choice for CSS. (See [colorToCSS](#colortocsscolor) helper function).\n\n#### Options\n\nEvery single option has a default value, so you can just call the function without any arguments.\nIt will generate a color ramp with 9 colors, starting at a random hue, with a single hue cycle.\n\nWhile 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.\n\n##### Hue sequence generation\n\nIf you want to generate a sequence of hues, you can use the following options:\n\n- `total` int 3…∞           → Amount of colors the function will generate.\n- `hStart` float 0…360      → Starting point of the hue ramp. 0 Red, 180 Teal etc..\n- `hStartCenter`: float 0…1 → Center the hue in the color ramp. 0 = start, 0.5 = middle, 1 = end.\n- `hCycles` float -∞…0…+∞   → Number of hue cycles. (.5 = 180°, 1 = 360°, 2 = 720°, etc.)\n- `hEasing` function(x)     → Hue easing function\n\nThe `hStart` sets the starting point of the hue ramp. The `hStartCenter` sets where in the hue in the ramp the  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. Thats is way the default value for `hStartCenter` is `0.5`. (In the center of a given ramp).\n\nThe `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.\n\nThe `hCycles` option sets the number of hue cycles. A value of `1` will generate a ramp with a single hue cycle. 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.\n\nThe `hEasing` option sets the easing function for the hue. The function takes an input value `x` and returns a value between 0 and 1. The default value is `(x) =\u003e x` which will generate a linear ramp.\n\n##### Hue List\n\nIf 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:\n\n- `hueList` array [0…360]   → List of hues to use. All other hue options will be ignored.\n\n**Example:**\n\n```js\nimport {\n  generateColorRamp,\n  uniqueRandomHues,\n} from \"rampensau\";\n\ngenerateColorRamp({\n  hueList: uniqueRandomHues({\n    startHue: Math.random() * 360, \n    total: 5, \n    minDistance: 90,\n  })\n})\n```\n\nThe `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.\n\n##### Saturation \u0026 Lightness\n\n- `sRange` array [0…1,0…1]  → Saturation Range\n- `lRange` array [0…1,0…1]  → Lightness Range\n\n##### Easing Functions\n\nEach of the color dimensions can be eased using a custom function.\nThe takes an input value `x` and returns a value between 0 and 1.:\n\n- `hEasing` function(x)     → Hue easing function\n- `sEasing` function(x)     → Saturation easing function\n- `lEasing` function(x)     → Saturation easing function\n\n## Hue Generation Functions\n\n### uniqueRandomHues(Options{})\n\nFunction returns an array of unique random hues. Mostly useful for generating a list of hues to use with `hueList`. Alternatively you can use `(x) =\u003e Math.random()` as the `hEasing` function in `generateColorRamp` but this will not guarantee unique hues.\n\n- `startHue` float 0…360        → Starting point of the hue ramp. 0 Red, 180 Teal etc..\n- `total` int 3…∞               → Amount of base colors.\n- `minHueDiffAngle` float 0…360 → Minimum angle between hues.\n- `rndFn` function()            → Random function. Defaults to `Math.random`.\n\n### colorHarmonies.colorHarmony(Options{})\n\nFunction returns an array of colors in HSL format (`[0…360,0…1,0…1]`).\n\n- `colorHarmony` string → Color harmony to use. One of `complementary`, `analogous`, `triadic`, `tetradic`, `splitComplementary`, `square`, `rectangle`, `monochromatic`.\n- `hStart` float 0…360 → Starting point of the hue ramp. 0 Red, 180 Teal etc..\n\nExample:\n\n```js\nimport {\n  generateColorRamp,\n  colorHarmonies,\n} from \"rampensau\";\n\ngenerateColorRamp({\n  hueList: colorHarmonies.splitComplementary({\n    hStart: Math.random() * 360,\n  }),\n  sRange: [0.4, 0.35],\n  lRange: [Math.random() * 0.1, 0.9],\n});\n```\n\n## Helper Function\n\n### colorToCSS(color)\n\nIn 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 color format generated from **generateColorRamp** (`[0…360,0…1,0…1]`) and scales the chroma value to the [adequate range](https://culorijs.org/color-spaces/) for the given color model.\n\n- `color` array [0…360,0…1,0…1] → Color in color format generated from **generateColorRamp** (`[0…360,0…1,0…1]`).\n- `mode` string → Color mode to use. One of `hsl`, `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.)\n\n**Example**:\n  \n  ```js\n  import {\n    generateColorRamp,\n    colorToCSS,\n  } from \"rampensau\";\n\n  console.log( \n    generateColorRamp().map(color =\u003e colorToCSS(color, 'oklch')) \n  ); // ['oklch(0.0557 0.4 348.3975)', 'oklch(0.1459 0.3872 314.7438)', …]\n  ```\n\n## Using RampenSau with a color library\n\nIf you are already using a color library like [culori](https://culorijs.org/api/) you can use its\n`formatCSS` function instead. Just don't forget to scale the chroma value to the [adequate range](https://culorijs.org/color-spaces/).\n\n```js\nculori.formatCss({ mode: 'oklch', {\n  l: color[2],\n  c: color[1] * 0.4,\n  h: color[0],\n})\n\nculori.formatCss({ mode: 'lch', {\n  l: color[2] * 100,\n  c: color[1] * 150,\n  h: color[0],\n});\n```\n\n## License\n\nRampensau is distributed under the [MIT License](./LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmeodai%2Frampensau","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmeodai%2Frampensau","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmeodai%2Frampensau/lists"}