.\" 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 .\" .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). .\" Fear. Run. Save yourself. No user-serviceable parts. . \" fudge factors for nroff and troff .if n \{\ . ds #H 0 . ds #V .8m . ds #F .3m . ds #[ \f1 . ds #] \fP .\} .if t \{\ . ds #H ((1u-(\\\\n(.fu%2u))*.13m) . ds #V .6m . ds #F 0 . ds #[ \& . ds #] \& .\} . \" simple accents for nroff and troff .if n \{\ . ds ' \& . ds ` \& . ds ^ \& . ds , \& . ds ~ ~ . ds / .\} .if t \{\ . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' .\} . \" troff and (daisy-wheel) nroff accents .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' .ds 8 \h'\*(#H'\(*b\h'-\*(#H' .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] .ds ae a\h'-(\w'a'u*4/10)'e .ds Ae A\h'-(\w'A'u*4/10)'E . \" corrections for vroff .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' . \" for low resolution devices (crt and lpr) .if \n(.H>23 .if \n(.V>19 \ \{\ . ds : e . ds 8 ss . ds o a . ds d- d\h'-1'\(ga . ds D- D\h'-1'\(hy . ds th \o'bp' . ds Th \o'LP' . ds ae ae . ds Ae AE .\} .rm #[ #] #H #V #F C .\" ======================================================================== .\" .IX Title "Convert::Color 3pm" .TH Convert::Color 3pm "2023-06-26" "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" "Convert::Color" \- color space conversions and named lookups .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 1 \& use Convert::Color; \& \& my $color = Convert::Color\->new( \*(Aqhsv:76,0.43,0.89\*(Aq ); \& \& my ( $red, $green, $blue ) = $color\->rgb; \& \& # GTK uses 16\-bit values \& my $gtk_col = Gtk2::Gdk::Color\->new( $color\->as_rgb16\->rgb16 ); \& \& # HTML uses #rrggbb in hex \& my $html = \*(Aq\*(Aq; .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" This module provides conversions between commonly used ways to express colors. It provides conversions between color spaces such as \s-1RGB\s0 and \s-1HSV,\s0 and it provides ways to look up colors by a name. .PP This class provides a base for subclasses which represent particular color values in particular spaces. The base class provides methods to represent the color in a few convenient forms, though subclasses may provide more specific details for the space in question. .PP For more detail, read the documentation on these classes; namely: .IP "\(bu" 4 Convert::Color::RGB \- red/green/blue as floats between 0 and 1 .IP "\(bu" 4 Convert::Color::RGB8 \- red/green/blue as 8\-bit integers .IP "\(bu" 4 Convert::Color::RGB16 \- red/green/blue as 16\-bit integers .IP "\(bu" 4 Convert::Color::HSV \- hue/saturation/value .IP "\(bu" 4 Convert::Color::HSL \- hue/saturation/lightness .IP "\(bu" 4 Convert::Color::CMY \- cyan/magenta/yellow .IP "\(bu" 4 Convert::Color::CMYK \- cyan/magenta/yellow/key (blackness) .PP The following classes are subclasses of one of the above, which provide a way to access predefined colors by names: .IP "\(bu" 4 Convert::Color::VGA \- named lookup for the basic \s-1VGA\s0 colors .IP "\(bu" 4 Convert::Color::X11 \- named lookup of colors from X11's \fIrgb.txt\fR .SH "CONSTRUCTOR" .IX Header "CONSTRUCTOR" .SS "new" .IX Subsection "new" .Vb 1 \& $color = Convert::Color\->new( STRING ) .Ve .PP Return a new value to represent the color specified by the string. This string should be prefixed by the name of the color space to which it applies. For example .PP .Vb 7 \& rgb:RED,GREEN,BLUE \& rgb8:RRGGBB \& rgb16:RRRRGGGGBBBB \& hsv:HUE,SAT,VAL \& hsl:HUE,SAT,LUM \& cmy:CYAN,MAGENTA,YELLOW \& cmyk:CYAN,MAGENTA,YELLOW,KEY \& \& vga:NAME \& vga:INDEX \& \& x11:NAME .Ve .PP For more detail, see the constructor of the color space subclass in question. .SH "METHODS" .IX Header "METHODS" .SS "rgb" .IX Subsection "rgb" .Vb 1 \& ( $red, $green, $blue ) = $color\->rgb .Ve .PP Returns the individual red, green and blue color components of the color value. For \s-1RGB\s0 values, this is done directly. For values in other spaces, this is done by first converting them to an \s-1RGB\s0 value using their \f(CW\*(C`to_rgb()\*(C'\fR method. .SH "COLOR SPACE CONVERSIONS" .IX Header "COLOR SPACE CONVERSIONS" Cross-conversion between color spaces is provided by the \f(CW\*(C`convert_to()\*(C'\fR method, assisted by helper methods in the two color space classes involved. .PP When converting \f(CW$color\fR from color space \s-1SRC\s0 to color space \s-1DEST,\s0 the following operations are attemped, in this order. \s-1SRC\s0 and \s-1DEST\s0 refer to the names of the color spaces, e.g. \f(CW\*(C`rgb\*(C'\fR. .IP "1." 4 If \s-1SRC\s0 and \s-1DEST\s0 are equal, return \f(CW$color\fR as it stands. .IP "2." 4 If the \s-1SRC\s0 space's class provides a \f(CW\*(C`convert_to_DEST\*(C'\fR method, use it. .IP "3." 4 If the \s-1DEST\s0 space's class provides a \f(CW\*(C`new_from_SRC\*(C'\fR constructor, call it and pass \f(CW$color\fR. .IP "4." 4 If the \s-1DEST\s0 space's class provides a \f(CW\*(C`new_rgb\*(C'\fR constructor, convert \f(CW$color\fR to red/green/blue components then call it. .IP "5." 4 If none of these operations worked, then throw an exception. .PP These functions may be called in the following ways: .PP .Vb 3 \& $other = $color\->convert_to_DEST() \& $other = Dest::Class\->new_from_SRC( $color ) \& $other = Dest::Class\->new_rgb( $color\->rgb ) .Ve .SS "convert_to" .IX Subsection "convert_to" .Vb 1 \& $other = $color\->convert_to( $space ) .Ve .PP Attempt to convert the color into its representation in the given space. See above for the various ways this may be achieved. .PP If the relevant subclass has already been loaded (either explicitly, or implicitly by either the \f(CW\*(C`new\*(C'\fR or \f(CW\*(C`convert_to\*(C'\fR methods), then a specific conversion method will be installed in the class. .PP .Vb 1 \& $other = $color\->as_$space .Ve .PP Methods of this form are currently \f(CW\*(C`AUTOLOAD\*(C'\fRed if they do not yet exist, but this feature should not be relied upon \- see below. .SH "AUTOLOADED CONVERSION METHODS" .IX Header "AUTOLOADED CONVERSION METHODS" This class provides \f(CW\*(C`AUTOLOAD\*(C'\fR and \f(CW\*(C`can\*(C'\fR behaviour which automatically constructs conversion methods. The following method calls are identical: .PP .Vb 2 \& $color\->convert_to(\*(Aqrgb\*(Aq) \& $color\->as_rgb .Ve .PP The generated method will be stored in the package, so that future calls will not have the \s-1AUTOLOAD\s0 overhead. .PP This feature is deprecated and should not be relied upon, due to the delicate nature of \f(CW\*(C`AUTOLOAD\*(C'\fR. .SH "OTHER METHODS" .IX Header "OTHER METHODS" As well as the above, it is likely the subclass will provide accessors to directly obtain the components of its representation in the specific space. For more detail, see the documentation for the specific subclass in question. .SH "SUBCLASS METHODS" .IX Header "SUBCLASS METHODS" This base class is intended to be subclassed to provide more color spaces. .SS "register_color_space" .IX Subsection "register_color_space" .Vb 1 \& $class\->register_color_space( $space ) .Ve .PP A subclass should call this method to register itself as a named color space. .SS "register_palette" .IX Subsection "register_palette" .Vb 1 \& $class\->register_palette( %args ) .Ve .PP A subclass that provides a fixed set of color values should call this method, to set up automatic conversions that look for the closest match within the set. This conversion process is controlled by the \f(CW%args\fR: .IP "enumerate => \s-1STRING\s0 or \s-1CODE\s0" 8 .IX Item "enumerate => STRING or CODE" A method name or anonymous \s-1CODE\s0 reference which will be used to generate the list of color values. .IP "enumerate_once => \s-1STRING\s0 or \s-1CODE\s0" 8 .IX Item "enumerate_once => STRING or CODE" As per \f(CW\*(C`enumerate\*(C'\fR, but will be called only once and the results cached. .PP This method creates a new class method on the calling package, called \&\f(CW\*(C`closest_to\*(C'\fR. .SS "closest_to" .IX Subsection "closest_to" .Vb 1 \& $color = $pkg\->closest_to( $orig, $space ) .Ve .PP Returns the color in the space closest to the given value. The distance is measured in the named space; defaulting to \f(CW\*(C`rgb\*(C'\fR if this is not provided. .PP In the case of a tie, where two or more colors have the same distance from the target, the first one will be chosen. .SH "AUTHOR" .IX Header "AUTHOR" Paul Evans