# Poline

"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.

The tome of "Poline" documentation is a comprehensive guide to the arcane arts of color generation, you will gain an understanding of how this tool creates its mystical and captivating palettes through the following sections.

## Summoning

The 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.

On 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."

## Points

The 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.

As shown in the illustration, increasing 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.

The 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.

Steps

## Anchors

At 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].

The 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.

## Updating Anchors

With 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.

The ability to update existing <string>anchors</string> 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.

## Position Functions

The position functions in "Poline" play a crucial role in determining the distribution of colors between the anchors. They work similar to easing functions and can be imported from the "Poline" module.

A position function is a mathematical function that maps a value between 0 and 1 to another value between 0 and 1. By defining the position functions for each axis, you can control the distribution of colors along each axis (positionFunctionX, positionFunctionY, positionFunctionZ) and create a diverse range of color palettes, using the same anchor positions.

Alternatively, you can use a single position function for all axes (positionFunction) if you prefer a unified approach.

Position fn X(Hue / Light)
Position fn Y(Hue / Light)
Position fn Z (Saturation)

## Looping Palette

By 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.

It is also possible to close the loop after the fact by setting poline.closedLoop = true|false.

Closed Loop

## Hue Shifting

"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.

The amount is a int or float between -Infinity and Infinity. It will permanently shift the hue of all colors in the palette.

## Closest Anchor

In 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.

    poline.getClosestAnchorPoint(
      {xyz: [x, y, null], maxDistance: .1}
    )

The maxDistance argument is optional and will return null if the closest anchor is further away than the maxDistance.

Any of the xyz or hsl components can be null. If they are null, they will be ignored.

## Color List

The 'poline' instance returns all colors as an array of hsl arrays or alternatively as an array of CSS strings.

    poline.colors
    poline.colorsCSS

Colors as HSL

## Remove Anchors

To remove an anchor, you can use the removeAnchorPoint method. It either takes an anchor reference or an index as an argument.

## Color Model

To 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.

Color Model

## Export Colors