{"id":13810864,"url":"https://meodai.github.io/poline/","last_synced_at":"2025-05-14T15:31:18.443Z","repository":{"id":65247372,"uuid":"585602940","full_name":"meodai/poline","owner":"meodai","description":"Esoteric Palette Generator Mico-Lib Interpolating HSL Color in cartesian space","archived":false,"fork":false,"pushed_at":"2025-05-07T16:54:18.000Z","size":2729,"stargazers_count":748,"open_issues_count":10,"forks_count":38,"subscribers_count":8,"default_branch":"main","last_synced_at":"2025-05-07T17:46:28.868Z","etag":null,"topics":["art","color","color-palette","colors","colour","hsl","palette"],"latest_commit_sha":null,"homepage":"https://meodai.github.io/poline/","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":".github/FUNDING.yml","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,"zenodo":null},"funding":{"github":["meodai"],"ko_fi":"colorparrot"}},"created_at":"2023-01-05T15:38:11.000Z","updated_at":"2025-05-07T16:54:21.000Z","dependencies_parsed_at":"2024-01-16T09:53:20.511Z","dependency_job_id":"b7419d53-b35f-4b59-9b7d-45cc6aad4452","html_url":"https://github.com/meodai/poline","commit_stats":{"total_commits":145,"total_committers":2,"mean_commits":72.5,"dds":0.006896551724137945,"last_synced_commit":"fb33f781c62c5b7db48b7e1cf543fa9c3fcd2629"},"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/meodai%2Fpoline","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/meodai%2Fpoline/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/meodai%2Fpoline/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/meodai%2Fpoline/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/meodai","download_url":"https://codeload.github.com/meodai/poline/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254171764,"owners_count":22026511,"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":["art","color","color-palette","colors","colour","hsl","palette"],"created_at":"2024-08-04T03:00:30.028Z","updated_at":"2025-05-14T15:31:13.423Z","avatar_url":"https://github.com/meodai.png","language":"TypeScript","funding_links":["https://github.com/sponsors/meodai","https://ko-fi.com/colorparrot"],"categories":["Tools for Picking Colors","Art, Design \u0026 Visual Storytelling"],"sub_categories":["Color Theory \u0026 Tools"],"readme":"\u003ch1\u003e\u003ca href=\"https://meodai.github.io/poline/\"\u003e\u003cimg width=\"200\" src=\"https://meodai.github.io/poline/poline-logo.png\" alt=\"poline\" /\u003e\u003c/a\u003e\u003c/h1\u003e\n\n## Esoteric Color palette Generator Mico-Lib\n\n\"**poline**\" is an enigmatic color palette generator, that harnesses the mystical witchcraft of polar coordinates. Its methodology, defying conventional color science, is steeped in the esoteric knowledge of the early 20th century. This magical technology defies explanation, drawing lines between anchors to produce visually striking and otherworldly palettes. It is an indispensable tool for the modern generative sorcerer, and a delight for the eye.\n\n![Poline DEMO UI](./dist/poline-wheel.png)\n\n\n## Summoning\nThe use of \"**Poline**\" begins with the invocation of its command, which can be performed with or without arguments. If called without, the tool will generate a mesmerizing palette featuring two randomly selected **anchors.**\nOn the other hand, one can choose to provide their own **anchor** points, represented as a list of **hsl** values, for a more personal touch. The power to shape and mold the colors lies in your hands.\"\n\n```js\nnew Poline({\n  anchorColors: [\n    [309, 0.72, 0.80],\n    [67, 0.32, 0.08],\n    //...\n  ],\n});\n```\n\n## Points\nThe magic of \"**Poline**\" is revealed through its technique of drawing lines between anchor points. The richness of the palette is determined by the number of **points**, with each connection producing a unique color.\n\nIncreasing the number of **points** will yield an even greater array of colors. By default, four points are used, but this can easily be adjusted through the 'numPoints' property on your Poline instance, as demonstrated in the code example.\n\n```js\nnew Poline({\n  numPoints: 6,\n});\n```\n\nThe resulting palette is a product of points multiplied by the number of anchor pairs. It can be changed after initialization by setting the **numPoints** property on your \"**Poline**\" instance.\n\n## Anchors\n\nAt the heart of \"**Poline**\" lies the concept of **anchors**, the fixed points that serve as the foundation for the creation of color palettes. **Anchors** are represented as a **list of hsl** values, which consist of three components: **hue** \\[0…360\\], **saturation** \\[0…1\\], and **lightness** \\[0…1\\].\n\nThe choice is yours, whether to provide your own anchor points during initialization or to allow \"**Poline**\" to generate a random selection for you by omitting the 'anchorColors' argument. The versatility of Poline extends \"**Poline**\" its initial setup, as you can also add anchors to your palette at any time using the '**addAnchor**' method. This method accepts either a **color** as HSL array values or an array of **X, Y, Z** coordinates, further expanding the possibilities of your color creation.\n\n```js\npoline.addAnchorPoint({\n  color: [100, 0.91, 0.80]\n});\n\n// or\n\npoline.addAnchorPoint({\n  xyz: [0.43, 0.89, 0.91]\n});\n```\n\n## Updating Anchors\n\nWith this feature, you have the power to fine-tune your palette and make adjustments as your creative vision evolves. So whether you are looking to make subtle changes or bold alterations, \"**Poline**\" is always ready to help you achieve your desired result.\n\nThe ability to update existing anchors is made possible through the '**updateAnchorPoint**' method. This method accepts the **reference to the anchor** you wish to modify and either a color in the form of **HSL** representation or an **XYZ** position array.\n\n```js\npoline.updateAnchorPoint({\n  point: poline.anchorPoints[0],\n  color: [286, 0.22, 0.22]\n});\n```\n\n## Position Function\n\nThe **position function** in \"**Poline**\" plays a crucial role in determining the **distribution of colors between the anchors**. It works similar to easing functions and can be imported from the \"**Poline**\" module.\n\nA position function is a mathematical function that maps a value **between 0 and 1** to another value between 0 and 1. By definition the same position function for all axes \"**Poline**\" will draw a straight line between the anchors. The chosen function will determine the distribution of colors between the anchors.\n\n```js\nimport {\nPoline, positionFunctions\n} from 'poline';\n\nnew Poline({\n  positionFunction: \n    positionFunctions.linearPosition,\n});\n```\n\nIf none is provided, \"**Poline**\" will use the default function, which is a sinusoidal function.\nThe following position functions are available and can be included by importing the **positionFunctions** object from the \"**Poline**\" module:\n\n- linearPosition\n- exponentialPosition\n- quadraticPosition\n- cubicPosition\n- quarticPosition\n- sinusoidalPosition **(default)**\n- asinusoidalPosition\n- arcPosition\n\n## Arcs\nBy defining **different position functions for each axis**, you can control the distribution of colors along each axis (**positionFunctionX**, **positionFunctionY**, **positionFunctionZ**). This will draw different arcs and create a diverse range of color palettes.\n\n```js\nnew Poline({\n  positionFunctionX: \n    positionFunctions.sinusoidalPosition,\n  positionFunctionY: \n    positionFunctions.quadraticPosition,\n  positionFunctionZ: \n    positionFunctions.linearPosition,\n});\n```\n\n## Palette\n\n\nBy default, the palette is not a closed loop. This means that the last color generated is not the same as the first color. If you want the palette to be a closed loop, you can set the **closedLoop** argument to true.\n\n```js\npoline.closedLoop = true;\n\n```\n\nIt is also possible to close the loop after the fact by setting **poline.closedLoop = true|false**.\n\n## Hue Shifting\n\nWith the power of hue shifting, \"**Poline**\" provides yet another level of customization. This feature allows you to **shift the hue** of the colors generated by a certain amount, giving you the ability to animate your palette or create similar color combinations with different hues.\"\n\n\"**poline**\" supports hue shifting. This means that the hue of the colors will be shifted by a certain amount. This can be useful if you want to animate the palette or generate a palette that looks similar to your current palette but using different hues.\n\n```js\npoline.shiftHue(1);\n```\nThe amount is a int or float between -Infinity and Infinity. It will permanently shift the hue of all colors in the palette.\n\n## Closest Anchor\n\nIn some situations, you might want to know which anchor is closest to a certain position or color. This method is used in the visualizer to highlight to select the closest anchor on click.\n\n```js\npoline.getClosestAnchorPoint(\n  {xyz: [x, y, null], maxDistance: .1}\n)\n```\n\nThe **maxDistance** argument is optional and will return null if the closest anchor is further away than the maxDistance.\nAny of the **xyz** or **hsl** components can be null. If they are **null**, they will be ignored.\n\n## Color List\n\nThe '**poline**' instance returns all colors as an array of **hsl** arrays or alternatively as an array of **CSS** strings.\n```js\npoline.colors\npoline.colorsCSS\n```\n\n## Remove Anchors\n\nTo remove an anchor, you can use the **removeAnchorPoint** method. It either takes an **anchor** reference or an **index** as an argument.\n```js\npoline.removeAnchorPoint({\n  point: poline.anchorPoints[\n    poline.anchorPoints.length - 1\n  ]\n});\n  // or\npoline.removeAnchorPoint({\n  index: poline.anchorPoints.length - 1\n});\n```\n\n## Color Model\n\nTo keep the library as lightweight as possible, \"**poline**\" only supports the **hsl** color model out of the box. However, it is easily possible to use other color models by using a library like [culori](https://culorijs.org/api/).\n\n```js\nimport {Poline} from \"poline\";\nimport {formatHex} from \"culori\";\nconst poline = new Poline(/** options */);\n\nconst OKHslColors = [...poline.colors].map(\n  c =\u003e formatHex({ \n    mode: 'okhsl', \n    {\n      h: c.hsl[0], \n      s: c.hsl[1], \n      l: c.hsl[2]}\n  })\n);\nconst LCHColors = [...poline.colors].map(\n  c =\u003e formatHex({ \n    mode: 'lch', \n    { \n      h: hsl[0],\n      c: hsl[1] * 51.484,\n      l: hsl[2] * 100,  \n    }\n  })\n);\n```\n\n## Installation\n\n\"**poline**\" is available as an [npm package](https://www.npmjs.com/package/poline). Alternatively you can clone it on [GitHub](https://github.com/meodai/poline).\n\n```js\nnpm install poline\n```\nYou can also use the [unpkg CDN](https://unpkg.com/poline) to include the library in your project.\nI recommend using the **mjs** version of the library. This will allow you to use the **import** syntax. But you can also use the **umd** version if you prefer to use the **script** tag.\n\n```html\nimport { \n  Poline \n} from 'https://unpkg.com/poline?module'\n```\n\n## License\n\nAnd thus, the tome of \"**poline**\" has been written. Its mystical powers, steeped in the arcane knowledge of the ancients, now reside within these pages. May this compendium serve you in your quest for the ultimate color palette.\n\nThe project is [MIT licensed](https://github.com/meodai/poline/blob/main/LICENSE) and open source. If you find any bugs or have any suggestions please open an issue on [GitHub]().\n\nInspired and created with the blessing of [Anatoly Zenkov](https://anatolyzenkov.com/)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/meodai.github.io%2Fpoline%2F","html_url":"https://awesome.ecosyste.ms/projects/meodai.github.io%2Fpoline%2F","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/meodai.github.io%2Fpoline%2F/lists"}