Graphic...rgument(3)

💖 NAME 💖

Graphics::Toolkit::Color::Manual::Argument — the shape, content and meaning of recurring method arguments. Header shorthand: Graphic...rgument(3), from User Contributed Perl Documentation. This is the page where GTC explains all the argument names that show up in at least two methods, and honestly? It's giving “API family reunion” energy. 💅

---

✨ SYNOPSIS ✨

Okay so bestie, as explained on the philosophy page, GTC tries to reuse argument names as much as possible to lower the cognitive footprint of the API. On this page of the Manual are the most comprehensive explanations of all the arguments that are shared by at least two methods. All the remaining Arguments are explained in the context of their method. See a condensed overview of the here presented argument names on the cheat sheet.

Please note that you do not have to wrap the named args in curly braces (HASH ref) but you may if you prefer to do so. All GTC methods take named arguments, but also almost all methods have a default argument that can be used as a positional if it is the only argument. 🫶

---

💅 ARGUMENTS 💅

🎀 in

in selects a color space in which the operation will be calculated or in which the result will be delivered. The argument expects a string with the name of a color space. The options are currently: RGB, LinearRGB, CMY, CMYK, HSL, HSV, HSB, HWB, NCol, YIQ, YUV, CIEXYZ, CIELAB, HunterLAB, CIELUV, CIELCHab, CIELCHuv, CIERGB, AdobeRGB, AppleRGB, ProPhotoRGB, WideGamutRGB, DisplayP3, DisplayP3Linear, DCIP3, DCIP3Linear, Rec709, Rec2020, OKLAB, OKLCH, OKHSL, OKHSV, OKHWB. These spaces have alias names that are also acceptable: SRGB, LinRGB, YPbPr, XYZ, LAB, LUV, LCH, LCHuv, opRGB, ROMMRGB, P3, LinearDisplayP3, SMPTEP3, LinearDCIP3, BT709, BT2020. Please note that there is a great degree of freedom with which a color space name can be written. The user is free to use upper and lower case characters or to insert special characters for better readability, such as whitespace ' ', underscore '_', dash '-' and dot '.'.

The default color space for input and output is RGB, but most calculating methods default to OKLAB or OKHSL if a cylindrical option is needed (complement).

in is understood by all methods except name and closest_name: new, is_in_gamut, values, distance, lighten, darken, saturate, desaturate, tint, tone, shade, apply, set_value, add_value, mix, invert, complement, analogous, gradient, cluster. The values method also expects in as a positional argument if it is the only one, since conversion into that space is the main purpose of that method.

🦋 by

by expects a number, which has to be a floating point number between zero and one. The meaning of the value depends on the method, but zero means this operation is not carried out and one means it is carried out to the maximum. by is mostly used for the rather simple methods of the high level (designer) API: lighten, darken, saturate, desaturate, tint, tone, shade, mix. The value may also be provided as a positional argument if it is the only one in all the methods except mix. There you can also use the alias amount instead of by.

🌸 to

to expects a color since it is used for methods that calculate a relation between that color and the one held by the object. Other methods that accept to calculate color(s) that are the result of those two. The value of this argument can be provided as a GTC object or a color definition (color name or values). (See formats page on how to write a color definition.) Please note that only scalar color definitions can work in this context. The following methods accept the to argument: distance, mix, analogous, gradient.

mix and gradient can handle also an ARRAY that contains any number of colors, which can be formatted independently.

🍓 color

color is the pendant to the argument to and receives the same input. It only uses a different word to communicate the different role of the color in question. Whereas to implies a “target”, “the other”, “that color”, just color implies “this color”, “here”. Because GTC tries to have an API that speaks in plain English, that difference is not reducible. This argument is currently used in new and is_in_gamut.

💜 range

range sets the minimal and maximal value limits on each axis. Those are normally prescribed by the color space the color was defined in or the color space the operation is performed in (see argument in). But those limits can be overruled with a custom range definition that is provided via the range argument, which is especially handy if reading a color definition via new or is_in_gamut that uses non-standard ranges, so it can be interpreted as intended.

A range definition can have many forms since there are two mechanisms in place to shorten them. But for clarity let's look at a full-fledged range definition first:

range => [[0, 100], [0, 100], [0, 100]],

This range definition is for a space with three axes. On each axis the minimum limit will be set to zero and the maximum to 100. Please note that the axes have a fixed order. In RGB for instance, red is the axis number one, green is number two and blue is three. Thus the first [0, 100] would set the red axis and so forth. But since in this example every axis is set to the same limits, the user is free to shorten range definition to [0, 100]. And because a minimum of zero is default, the range definition can be further shortened just to 100 or 'percent' which is an alias to [0, 100], same as 'normal' is an alias to [0, 1]. There are only those two aliases at the moment. So in order to read a RGB16 color definition that uses ranges of 0 .. 65535 instead of 0 .. 255 one might use the argument range => 65535 or range => 2**16-1 or range => (2**16)-1. Alternatively there is a HASH syntax too, using long or short axes names:

range => {r => 'percent', g => [-1,1], b => 500},

Please note that a valid range definition has to cover the minimum and maximum of each axis of the current color space. The following methods accept the range argument: new, values, is_in_gamut, distance.

🎀 raw

raw expects a perlish pseudo boolean (0 or 1). When set to true, GTC will not change the color values even if they are out of range. Values on angular axes might still get put into range, because a rotation of 360 degrees is no change in mathematical-geometric meaning.

raw is set off (false) by default for IO methods, because this is usually the expected behaviour by the user and by the calculation methods. They might create unexpected results when getting fed out of gamut colors as input. Here it is mostly useful in debugging scenarios.

raw is set on (true) by default at the is_in_gamut method, because in most cases it does not make sense to clamp a color into gamut and then ask if it is in gamut, which would be always true. However - it can be useful to set it there to false in combination with the in argument. It can be a valid question to ask if a color, that got clamped into range in its original space, gets out of gamut when converted into another space.

The raw argument can be used in: new, values.

✨ steps

steps is an argument of color set producing methods that defines how many colors will be produced. It expects a positive integer value. The following methods accept steps: complement, analogous, gradient. The method analogous might produce fewer than the required amount of colors, if a resulting color would be out of range.

🌀 tilt

tilt is another argument of color set producing methods that influences all colors except the first and last one. All methods that employ tilt compute colors that are located along a line or curve, however that curve may be shaped. The tilt factor moves the colors along this curve toward one end. Because in case of the complement method the curve is a circle, the mentioned ends are the starting color and its opposite, THE complement. tilt expects a floating point number. If it is positive, the computed colors will congregate toward the target color and if it is negative they congregate toward the start color. The greater the absolute tilt value, the greater the effect. Due to the nature of the analogous algorithm that projects the curve in the direction of the target color and draws it far beyond, a positive tilt will increase the drive in that direction and a negative tilt will let it decrease. The following methods accept tilt: complement, analogous, gradient.

👑 only

only will limit the scope of the operation to selected axes. It expects one or several (in an ARRAY ref) axis names (long or short). The following methods accept only: distance, invert. The distance method uses also the alias select, which has the same meaning as only.

🌈 from

from selects a color scheme which is a set of color names with associated SRGB values. from expects a name of a color scheme which is usually the name of a standard like HTML, SVG or others. Read all about them on this page. Every color scheme is provided by a Graphics::ColorNames module. The easiest way is to install them all via Bundle::Graphics::ColorNames. The following methods accept from: name and closest_name.

---

💖 AUTHOR 💖

Herbert Breunung, <lichtkind@cpan.org>

© COPYRIGHT ©

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.

---

Catch you later, bestie — this page is from perl v5.42.2, dated 2026-06-21, and the footer tags it Graphic...rgument(3). Slay and stay in gamut 💅✨