Graphic...ual::Set(3)

📦 version 2.22, in arch rolling

🎨 NAME

Graphics::Toolkit::Color::Manual::Set — the reference page for all the color set creation methods, bestie. It's giving "everything you need to know to build color families" energy. 💅

Oh and real quick — this lives in the User Contributed Perl Documentation section of the manual, page Graphic...ual::Set(3). Now let's go. ✨

✨ SYNOPSIS ✨

Okay so this page is the most detailed description of the four color set creation methods ever, no cap:

  • complement
  • analogous
  • gradient
  • cluster

Plus a full explanation of every argument they take. 🫶

Every single one of these methods returns a list of GTC objects — unless, bestie, a typo or a data type mismatch happens, in which case you get an error. 🙈 Periodt.

🌈 METHODS 🌈

🎀 complement 🎀

complement computes complementary colors (GTC objects). These are colors that are exactly as colorful (saturated) and bright (lightness) as the original color — that's the invocant, btw — but their hue differs in a way that's optimized for contrast. Iconic.

The method accepts five named and optional arguments: steps, in, target, tilt and skew. The last three extend the described concept greatly — like, they really take it there. 🔥

If you pass no argument at all, you get THE single complementary color, which has the opposite hue of the original. So simple, so slay. And steps is the one you can use as the only positional argument if you're feeling lazy. 💅

  • steps — prescribes the amount of colors produced. Has to be a positive integer, and it 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 (the argument in). The values associated with the axis names will be added to the values of THE complement (the 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're moved toward THE complement (target) if positive, and toward the original color if negative. What's traditionally meant by split-complementary colors? You get that with a tilt factor of around 3.42 with three steps, or 1.585 with 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 results in stronger differences of lightness between the complementary colors. skew expects a floating point number. If that's positive, the right side of the circle (looking toward THE complement) is moved up (toward white), and vice versa. skew defaults to zero. ⭐
Real talk: 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. No shortcuts, bestie. 😭
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 — like a little color conga line. 💃

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? Being able to interpolate from two given colors without having to do much additional computation. Lowkey efficient. ⚡

The method accepts four named arguments: to, steps, in and tilt. Only to is required, and it can be provided as a positional argument if it's the only one. 🫶

  • to — expects a color object or scalar color definition, which will be the color most similar to the starting one (the invocant). It's called the second color here. 💖
  • 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 you 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; when it's 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 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. 📏

Heads up bestie: please note this line might be curved if the color space is cylindrical. Not a bug, just geometry being geometry. 🌀
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 one's required, and it may be provided as a positional argument if it's 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 also provide an ARRAY reference (square braces) with several independently formatted colors for custom gradients — it'll incorporate these colors in the order you inserted them into the ARRAY. Order matters, diva. 👑

  • 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 happens if the floating point tilt value is positive, and the latter if it's 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.
Fr fr note this: the effect of tilt is exponential (it is accelerating). So it sneaks up on you — dramatic on purpose. 😭📈
# 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 sits 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 — it's giving mystery, honestly. 🔮

The method accepts three named arguments: radius, minimal_distance and in, of which the first two are required. And because typing is hard, 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 the 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.
Okay important: please note that cuboctahedral packing (when radius is a single number) does not work in CMYK space. Sorry CMYK girlies. 🙈💀
my @blues = $blue->cluster( radius => 4, minimal_distance => 0.3 );
my @c = $color->cluster( r => [2,2,3], min_d => 0.4, in => 'YUV' );

👑 AUTHOR 👑

Herbert Breunung, <lichtkind@cpan.org> ✨

Copyright 2026 Herbert Breunung. 🎀

🌸 LICENSE 🌸

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. Slay, literally. 💖

That's the whole page, bestie — you ate it up. 🫶✨

Sign-off vibes: this was perl v5.42.2, dated 2026-06-21, from page Graphic...ual::Set(3). Go forth and make pretty color families. 🎨💅🌟

📦 where this page comes from