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.