1NAME 2 `Convert::Color' - color space conversions and named lookups 3 4SYNOPSIS 5 use Convert::Color; 6 7 my $color = Convert::Color->new( 'hsv:76,0.43,0.89' ); 8 9 my ( $red, $green, $blue ) = $color->rgb; 10 11 # GTK uses 16-bit values 12 my $gtk_col = Gtk2::Gdk::Color->new( $color->as_rgb16->rgb16 ); 13 14 # HTML uses #rrggbb in hex 15 my $html = '<td bgcolor="#' . $color->as_rgb8->hex . '">'; 16 17DESCRIPTION 18 This module provides conversions between commonly used ways to express 19 colors. It provides conversions between color spaces such as RGB and 20 HSV, and it provides ways to look up colors by a name. 21 22 This class provides a base for subclasses which represent particular 23 color values in particular spaces. The base class provides methods to 24 represent the color in a few convenient forms, though subclasses may 25 provide more specific details for the space in question. 26 27 For more detail, read the documentation on these classes; namely: 28 29 * Convert::Color::RGB - red/green/blue as floats between 0 and 1 30 31 * Convert::Color::RGB8 - red/green/blue as 8-bit integers 32 33 * Convert::Color::RGB16 - red/green/blue as 16-bit integers 34 35 * Convert::Color::HSV - hue/saturation/value 36 37 * Convert::Color::HSL - hue/saturation/lightness 38 39 * Convert::Color::CMY - cyan/magenta/yellow 40 41 * Convert::Color::CMYK - cyan/magenta/yellow/key (blackness) 42 43 The following classes are subclasses of one of the above, which provide 44 a way to access predefined colors by names: 45 46 * Convert::Color::VGA - named lookup for the basic VGA colors 47 48 * Convert::Color::X11 - named lookup of colors from X11's rgb.txt 49 50CONSTRUCTOR 51 $color = Convert::Color->new( STRING ) 52 Return a new value to represent the color specified by the string. This 53 string should be prefixed by the name of the color space to which it 54 applies. For example 55 56 rgb:RED,GREEN,BLUE 57 rgb8:RRGGBB 58 rgb16:RRRRGGGGBBBB 59 hsv:HUE,SAT,VAL 60 hsl:HUE,SAT,LUM 61 cmy:CYAN,MAGENTA,YELLOW 62 cmyk:CYAN,MAGENTA,YELLOW,KEY 63 64 vga:NAME 65 vga:INDEX 66 67 x11:NAME 68 69 For more detail, see the constructor of the color space subclass in 70 question. 71 72METHODS 73 ( $red, $green, $blue ) = $color->rgb 74 Returns the individual red, green and blue color components of the color 75 value. For RGB values, this is done directly. For values in other 76 spaces, this is done by first converting them to an RGB value using 77 their `to_rgb()' method. 78 79COLOR SPACE CONVERSIONS 80 Cross-conversion between color spaces is provided by the `convert_to()' 81 method, assisted by helper methods in the two color space classes 82 involved. 83 84 When converting `$color' from color space SRC to color space DEST, the 85 following operations are attemped, in this order. SRC and DEST refer to 86 the names of the color spaces, e.g. `rgb'. 87 88 1. If SRC and DEST are equal, return `$color' as it stands. 89 90 2. If the SRC space's class provides a `convert_to_DEST' method, use 91 it. 92 93 3. If the DEST space's class provides a `new_from_SRC' constructor, 94 call it and pass `$color'. 95 96 4. If the DEST space's class provides a `new_rgb' constructor, convert 97 `$color' to red/green/blue components then call it. 98 99 5. If none of these operations worked, then throw an exception. 100 101 These functions may be called in the following ways: 102 103 $other = $color->convert_to_DEST() 104 $other = Dest::Class->new_from_SRC( $color ) 105 $other = Dest::Class->new_rgb( $color->rgb ) 106 107 $other = $color->convert_to( $space ) 108 Attempt to convert the color into its representation in the given space. 109 See above for the various ways this may be achieved. 110 111 If the relevant subclass has already been loaded (either explicitly, or 112 implicitly by either the `new' or `convert_to' methods), then a specific 113 conversion method will be installed in the class. 114 115 $other = $color->as_$space 116 117 Methods of this form are currently `AUTOLOAD'ed if they do not yet 118 exist, but this feature should not be relied upon - see below. 119 120AUTOLOADED CONVERSION METHODS 121 This class provides `AUTOLOAD' and `can' behaviour which automatically 122 constructs conversion methods. The following method calls are identical: 123 124 $color->convert_to('rgb') 125 $color->as_rgb 126 127 The generated method will be stored in the package, so that future calls 128 will not have the AUTOLOAD overhead. 129 130 This feature is deprecated and should not be relied upon, due to the 131 delicate nature of `AUTOLOAD'. 132 133OTHER METHODS 134 As well as the above, it is likely the subclass will provide accessors 135 to directly obtain the components of its representation in the specific 136 space. For more detail, see the documentation for the specific subclass 137 in question. 138 139SUBCLASS METHODS 140 This base class is intended to be subclassed to provide more color 141 spaces. 142 143 $class->register_color_space( $space ) 144 A subclass should call this method to register itself as a named color 145 space. 146 147 $class->register_palette( %args ) 148 A subclass that provides a fixed set of color values should call this 149 method, to set up automatic conversions that look for the closest match 150 within the set. This conversion process is controlled by the `%args': 151 152 enumerate => STRING or CODE 153 A method name or anonymous CODE reference which will be used to 154 generate the list of color values. 155 156 enumerate_once => STRING or CODE 157 As per `enumerate', but will be called only once and the results 158 cached. 159 160 This method creates a new class method on the calling package, called 161 `closest_to'. 162 163 $color = $pkg->closest_to( $orig, $space ) 164 Returns the color in the space closest to the given value. The distance 165 is measured in the named space; defaulting to `rgb' if this is not 166 provided. 167 168 In the case of a tie, where two or more colors have the same distance 169 from the target, the first one will be chosen. 170 171AUTHOR 172 Paul Evans <leonerd@leonerd.org.uk> 173 174