complement

"complement" computes complementary colors (GTC objects). These are colors that are as colorful (saturated) and bright (lightness) as the original color (invocant), but have a difference in hue that is optimized for contrast. The method accepts five named and optional arguments: "steps", "in", "target", "tilt" and "skew". The last three extend the described concept greatly. If no argument is provided, THE single complementary color will be computed, which has the opposite hue as the original. You may use "steps" as the only positional argument.

steps prescribes the amount of colors produced. It has to be a positive integer, which defaults to one. Since "complement" works only in cylindrical spaces of the HSL family, imagine a horizontal circle in HSL space around the middle column. "complement" simply divides this circle into equally sized slices and every point where the circle is cut becomes a complementary color. The color (point) on the opposite side of the original color is THE complement. If you choose two steps (cut the circle in two) you get THE complementary and the original, with three steps you get triadic colors, with four you get tetradic (quadratic) colors and so forth. For values greater than one, the invocant will always be the last color returned.

in sets the color space the "complement" will be computed in, which is OKHSL per default. It has to be a space of the HSL family.

"target" moves THE complement and thus the whole circle of complementary colors. Only the given color stays unaltered and part of the circle. The argument expects a HASH reference which contains some or all axis names (short or long) of the chosen color space (argument "in"). The values associated with the axis names will be added to the values of THE complement (target color) the same way add_value would do.

tilt moves the colors along the described circle of complements. The expected floating point number describes how much they are moved toward THE complement (target) if positive and toward the original color if negative. What is traditionally meant by split-complementary colors you will get with a "tilt" factor of around 3.42 with three "steps" or 1.585 and four "steps" (depending on whether you need THE complement in your set). "tilt" defaults to zero.

"skew" rotates the circle of complementary colors around the axis that pierces through the original color and THE complement. This will result in stronger differences of lightness between the complementary colors. "skew" expects a floating point number. If that is positive, the right side of the circle (looking toward THE complement) is moved up (toward white) and vice versa. "skew" defaults to zero. Please note that "skew" (like "target") expects absolute values, which need to be different from color space to color space to produce the same results.

my @colors = $c->complement( 4 );                          # 'quadratic' colors
my @colors = $c->complement( steps => 4, tilt => 1.585 );  # split-complementary colors
my @colors = $c->complement( steps => 3, tilt => 2, target => { l => -10 } );
my @colors = $c->complement( steps => 3, tilt => 2, target => { h => 20, s=> -5, l => -10 });

analogous

"analogous" computes analogous colors (GTC objects). These are series of colors, where every pair of neighbours differs the same way from each other. This method may be used to produce a "gradient" or complementary colors but it works differently in edge cases and has generally fewer options to shape the result than any of these methods. Its strength comes from being able to interpolate from two given colors without having to do much additional computation. The method accepts four named arguments: "to", "steps", "in" and "tilt". Only "to" is required and can be provided as a positional argument if it is the only one.

to expects a color object or scalar color definition, which will be the color most similar to the starting one (invocant). It will be called here the second color.

steps requires a positive integer, which will be the maximal amount of colors produced. The method stops as soon as the generated color is out of range. "steps" defaults to four.

in sets the color space the "analogous" colors will be computed in, which is OKHSL per default.

tilt helps to differ from the default behavior, where the distance between two neighbouring colors is always the same. If "tilt" is a positive floating point number, this distance will increase and when it is negative it will shrink. "tilt" defaults to zero. The distance between the starting color and the second color is always taken as 100%. If "tilt" is for instance 0.2, the distance between the second and the third color will be 120% or it will be 80% if "tilt" is -0.2. The distance between the third and fourth color will be 1.2 * 120 = 144% or 64% respectively. In any case all four colors will be located on one line. Please note this line might be curved if the color space is cylindrical.

my @colors = $c->analogous( $second_color );             # 4 analogous colors
my @colors = $c->analogous( to => 'black', steps => 6, in => 'OKLCH', tilt => 0.05 );

gradient

"gradient" creates a gradient (a list of color objects that build a transition) between the current color held by the object and a second color, provided by the named argument "to". That is required and may be provided as a positional argument if it is the only one. The optional arguments are: "steps", "in" and "tilt".

to expects a color object or scalar color definition, which will be the end color of the gradient. The calling object represents the starting color. You may provide an ARRAY reference (square braces) with several independently formatted colors for custom gradients that will incorporate these colors in the order you inserted them into the ARRAY.

steps requires a positive integer, which will be the amount of colors produced. "steps" defaults to ten.

in sets the color space the "gradient" colors will be computed in, which is OKLAB per default.

tilt moves the colors of the gradient toward the end color or the starting color. The former will happen if the floating point "tilt" value is positive and the latter if it is negative. The greater the absolute "tilt" value the greater the effect. "tilt" defaults to zero, which results in a gradient of colors with equal distance between them. Please note that the effect of "tilt" is exponential (it is accelerating).

# we turn to grey
my @colors = $c->gradient( to => 'grey50', steps => 5);
# non-linear gradient in HSL space :
@colors = $c1->gradient( to =>[14,10,222], steps => 10, tilt => 1, in => 'HSL' );
@colors = $c1->gradient( to =>['blue', 'brown', {h => 30, s => 44, l => 50}] );

cluster

"cluster" computes a set of colors that are similar but not too similar. The calling object will sit in the center of the cluster and is always part of the result. The amount of resulting colors depends on the arguments and can greatly vary. The method accepts three named arguments: "radius", "minimal_distance" and "in", of which the first two are required. "radius" can be abbreviated as "r" and "minimal_distance" as "min_d".

"radius" determines the size of the cluster, the maximal distance between a color of the cluster and the center. If "radius" is a floating point number, the cluster will be ball-shaped and packed in a cuboctahedral grid. If the "radius" is provided in form of an ARRAY that contains a floating point number for each axis, there will be a cubic packing that extends on each dimension only as far as the given number for this axis allows.

"minimal_distance" requires one floating point number that determines the density of the packing, which is the minimal distance in any direction of two neighbouring colors.

in sets the color space the "cluster" colors will be computed in, which is OKLAB per default. Please note that cuboctahedral packing (radius is a single number) does not work in CMYK space.

my @blues = $blue->cluster( radius => 4, minimal_distance => 0.3 );
my @c = $color->cluster( r => [2,2,3], min_d => 0.4, in => 'YUV' );