.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "Graphics::Toolkit::Color::Space::Hub 3pm" .TH Graphics::Toolkit::Color::Space::Hub 3pm "2023-11-03" "perl v5.36.0" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Graphics::Toolkit::Color::Space::Hub \- convert, format and measure color values .SH "SYNOPSIS" .IX Header "SYNOPSIS" Central hub for all color value related math. Can handle vectors of all spaces mentioned in next paragraph and translates also into and from different formats such as \fI\s-1RGB\s0\fR \fIhex\fR ('#AABBCC'). .PP .Vb 1 \& use Graphics::Toolkit::Color::Space::Hub; \& \& my $true = Graphics::Toolkit::Color::Space::Hub::is_space( \*(AqHSL\*(Aq ); \& my $HSL = Graphics::Toolkit::Color::Space::Hub::get_space( \*(AqHSL\*(Aq); \& my $RGB = Graphics::Toolkit::Color::Space::Hub::base_space(); \& Graphics::Toolkit::Color::Space::Hub::space_names(); # all space names \& \& $HSL\->normalize([240,100, 0]); # 2/3, 1, 0 \& $HSL\->convert([240, 100, 0], \*(AqRGB\*(Aq); # 0, 0, 1 \& $HSL\->deconvert([0, 0, 1], \*(AqRGB\*(Aq); # 2/3, 1, 0 \& $RGB\->denormalize([0, 0, 1]); # 0, 0, 255 \& $RGB\->format([0, 0, 255], \*(Aqhex\*(Aq); # \*(Aq#0000ff\*(Aq \& \& my ($values, $space_name) = Graphics::Toolkit::Color::Space::Hub::deformat( \*(Aq#0000ff\*(Aq ); \& # [0, 0, 255] , \*(AqRGB\*(Aq .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" This module is supposed to be used by Graphics::Toolkit::Color and not directly, thus it exports no symbols and has a much less \s-1DWIM API\s0 then the main module. .SH "COLOR SPACES" .IX Header "COLOR SPACES" Color space names can be written in any combination of upper and lower case. .SS "\s-1RGB\s0" .IX Subsection "RGB" has three integer values: \fBred\fR (0 .. 255), \fBgreen\fR (0 .. 255) and \&\fBblue\fR (0 .. 255). All are scaling from no (0) to very much (255) light of that color, so that (0,0,0) is black, (255,255,255) is white and (0,0,255) is blue. .SS "\s-1CMY\s0" .IX Subsection "CMY" is the inverse of \s-1RGB\s0 but with the range: 0 .. 1. \fBcyan\fR is the inverse value of \fIred\fR, \fBmagenta\fR is inverse green and \fByellow\fR is inverse of \&\fIblue\fR. Inverse meaning when a color has the maximal \fIred\fR value, it has to have the minimal \fIcyan\fR value. .SS "\s-1CMYK\s0" .IX Subsection "CMYK" is an extension of \s-1CMY\s0 with a fourth value named \fBkey\fR (also 0 .. 1), which is basically the amount of black mixed into the \s-1CMY\s0 color. .SS "\s-1HSL\s0" .IX Subsection "HSL" has three integer values: \fBhue\fR (0 .. 359), \fBsaturation\fR (0 .. 100) and \fBlightness\fR (0 .. 100). Hue stands for a color on a rainbow: 0 = red, 15 approximates orange, 60 \- yellow 120 \- green, 180 \- cyan, 240 \- blue, 270 \- violet, 300 \- magenta, 330 \- pink. 0 and 360 point to the same coordinate. This module only outputs 0, even if accepting 360 as input. \&\fIsaturation\fR ranges from 0 = gray to 100 \- clearest color set by hue. \&\fIlightness\fR ranges from 0 = black to 50 (hue or gray) to 100 = white. .SS "\s-1HSV\s0" .IX Subsection "HSV" Similar to \s-1HSL\s0 we have \fBhue\fR and \fBsaturation\fR, but the third value in named \fBvalue\fR. In \s-1HSL\s0 the color white is always achieved when \fIlightness\fR = 100. In \s-1HSV\s0 additionally \fIsaturation\fR has to be zero to get white. When in \s-1HSV\s0 \fIvalue\fR is 100 and \fIsaturation\fR is also 100, than we have the brightest clearest color of whatever \fIhue\fR sets. .SS "\s-1HSB\s0" .IX Subsection "HSB" It is an alias to \s-1HSV,\s0 just value being renamed with \fBbrightness\fR. .SS "\s-1HWB\s0" .IX Subsection "HWB" An inverted \s-1HSV,\s0 where the clean colors are inside of the cylinder. It still has the circular \fBhue\fR dimension, as described in \f(CW\*(C`HSL\*(C'\fR. The other two, linear dimensions (also 0 .. 100 [percent]) are \&\fBwhiteness\fR and \fBblackness\fR, desribing how much white or black are mixed in. If both are zero, than we have a pure color. \fIwhiteness\fR of 100 always leads to pure white and \fIblackness\fR of 100 always leads to pure black. .SS "\s-1YIQ\s0" .IX Subsection "YIQ" Has the linear dimensions \fIluminance\fR (sort of brightness, range 0..1), \&\fIin-phase\fR (cyan \- orange \- balance, range \-0.5959 .. 0.5959) and \fIquadrature\fR (magenta \- green \- balance, range: \-0.5227 .. 0.5227). .SH "FORMATS" .IX Header "FORMATS" These formats are available in all color spaces. .SS "string" .IX Subsection "string" .Vb 1 \& \*(AqRGB: 10, 20, 30\*(Aq .Ve .SS "css_string" .IX Subsection "css_string" .Vb 1 \& \*(Aqrgb(10, 20, 30)\*(Aq .Ve .SS "array" .IX Subsection "array" .Vb 1 \& [RGB, 10, 20, 30] .Ve .SS "hash" .IX Subsection "hash" .Vb 1 \& { red => 10, green => 20, blue => 30 } .Ve .SS "char_hash" .IX Subsection "char_hash" .Vb 1 \& { r => 10, g => 20, b => 30 } .Ve .SH "ROUTINES" .IX Header "ROUTINES" This package provides two sets of routines. Thes first is just a lookup of what color space objects are available. The second set consists of three pairs or routines about 3 essential operations of number values and their reversal. The full pipeline for the translation of color values is: .PP .Vb 5 \& 1. deformat (into a value list) \& 2. normalize (into 0..1 range) \& 3. convert/deconvert (into target color space) \& 4. denormalize (into target range) \& 5. format (into target format) .Ve .SS "space_names" .IX Subsection "space_names" Returns a list of string values, which are the names of all available color space. See \*(L"COLOR-SPACES\*(R". .SS "is_space" .IX Subsection "is_space" Needs one argument, that supposed to be a color space name. If it is, the result is an 1, otherwise 0 (perlish pseudo boolean). .SS "get_space" .IX Subsection "get_space" Needs one argument, that supposed to be a color space name. If it is, the result is the according color space object, otherwise undef. .SS "base_space" .IX Subsection "base_space" Return the color space object of (currently) \s-1RGB\s0 name space. This name space is special since every color space object provides converters from and to \s-1RGB,\s0 but the \s-1RGB\s0 itself has no converter. .SS "normalize" .IX Subsection "normalize" Normal in a mathematical sense means the range of acceptable values are between zero and one. Normalization means there for altering the values of numbers to fit in that range. For instance standard \s-1RGB\s0 values are integers between zero and 255. Normalizing them essentially means just dividing them with 255. .PP .Vb 1 \& my @rgb = Graphics::Toolkit::Color::Space::Hub::normalize( [0,10,255], \*(AqRGB\*(Aq ); .Ve .PP It has one required and two optional arguments. The first is an \s-1ARRAY\s0 ref with the vector or values of a color. The seond argument is name of a color space. This is in most cases necessary, since all color space know their standard value ranges (being e.g. 3 x 0 .. 255 for \s-1RGB\s0). If you want to normalize from special ranges like \s-1RGB16\s0 you have use the third argument, which has to be a valid value range definition. .PP .Vb 3 \& my @rgb = Graphics::Toolkit::Color::Space::Hub::normalize( [0, 1000, 34000], \*(AqRGB\*(Aq, 2**16 ); \& # which is the same as: \& my @rgb = Graphics::Toolkit::Color::Space::Hub::normalize( [0, 1000, 34000], \*(AqRGB\*(Aq, [[0,65536].[0,65536].[0,65536]] ); .Ve .SS "denormalize" .IX Subsection "denormalize" Reverse function of \fInormalize\fR, taking the same arguments. If result has to be an integer (range maximum above 1), it will be rounded. .PP .Vb 2 \& my @rgb = Graphics::Toolkit::Color::Space::Hub::denormalize( [0,0.1,1], \*(AqRGB\*(Aq ); \& my @rgb = Graphics::Toolkit::Color::Space::Hub::denormalize( [0,0.1,1], \*(AqRGB\*(Aq, 2**16 ); .Ve .SS "convert" .IX Subsection "convert" Converts a value vector (first argument) from base space (\s-1RGB\s0) into any space mentioned space (second argument \- see \*(L"COLOR-SPACES\*(R"). The values have to be normalized (inside 0..1). If there are outside the acceptable range, there will be clamped, so that the result will also normal. .PP .Vb 2 \& # convert from RGB to HSL \& my @hsl = Graphics::Toolkit::Color::Space::Hub::convert( [0.1, 0.5, .7], \*(AqHSL\*(Aq ); .Ve .SS "deconvert" .IX Subsection "deconvert" Converts a value tuple (vector \- firs argument) of any color space (second argument) into the base space (\s-1RGB\s0). .PP .Vb 2 \& # convert from HSL to RGB \& my @rgb = Graphics::Toolkit::Color::Space::Hub::deconvert( [0.9, 0.5, 0.5], \*(AqHSL\*(Aq ); .Ve .SS "format" .IX Subsection "format" Putting a list of values (inside an \s-1ARRAY\s0 ref \- first argument) from any supported color space (second argument) into another data format (third argument, see \fI/FORMATS\fR). .PP .Vb 2 \& my $hex = Graphics::Toolkit::Color::Space::Hub::format( [255, 0, 10], \*(Aqhex\*(Aq ); # \*(Aqff00a0\*(Aq \& my $string = Graphics::Toolkit::Color::Space::Hub::format( [255, 0, 10], \*(Aqstring\*(Aq ); # \*(AqRGB: 255, 0, 10\*(Aq .Ve .SS "deformat" .IX Subsection "deformat" Reverse function of \fIformat\fR, but also guesses the color space. That's why it takes only one argument, a scalar that can be a string, \s-1ARRAY\s0 ref or \s-1HASH\s0 ref. The result will be two values. The first is a \s-1ARRAY\s0 with all the unaltered, not clamped and not normalized values. The second is the name of the recognized color name space. .PP .Vb 3 \& my ($values, $space) = Graphics::Toolkit::Color::Space::Hub::deformat( \*(Aqff00a0\*(Aq ); \& # [255, 10 , 0], \*(AqRGB\*(Aq \& ($values, $space) = Graphics::Toolkit::Color::Space::Hub::deformat( [255, 10 , 0] ); # same result .Ve .SS "partial_hash_deformat" .IX Subsection "partial_hash_deformat" This is a special case \fIdeformat\fR routine for the \fIhash\fR and \fIchar_hash\fR format (see \fI/FORMATS\fR). It can tolerate missing values. The The result will also be a hash .SH "SEE ALSO" .IX Header "SEE ALSO" .IP "\(bu" 4 Convert::Color .SH "COPYRIGHT & LICENSE" .IX Header "COPYRIGHT & LICENSE" Copyright 2023 Herbert Breunung. .PP This program is free software; you can redistribute it and/or modify it under same terms as Perl itself. .SH "AUTHOR" .IX Header "AUTHOR" Herbert Breunung,