{
    "mode": "perldoc",
    "parameter": "Graphics::Toolkit::Color::Values",
    "section": "",
    "url": "https://www.chedong.com/phpMan.php/perldoc/Graphics%3A%3AToolkit%3A%3AColor%3A%3AValues/json",
    "generated": "2026-10-07T10:49:34Z",
    "synopsis": "Readonly object that holds values of a color. It provides methods to get the values back in\ndifferent formats, to measure difference to other colors or to create value objects of related\ncolors.\nuse Graphics::Toolkit::Color::Value;\nmy $blue = Graphics::Toolkit::Color::Value->new( 'hsl(220,50,60)' );\nmy @rgb = $blue->get();\nmy $purple = $blue->set({red => 220});",
    "sections": {
        "NAME": {
            "content": "Graphics::Toolkit::Color::Value - single color related high level methods\n",
            "subsections": []
        },
        "SYNOPSIS": {
            "content": "Readonly object that holds values of a color. It provides methods to get the values back in\ndifferent formats, to measure difference to other colors or to create value objects of related\ncolors.\n\nuse Graphics::Toolkit::Color::Value;\n\nmy $blue = Graphics::Toolkit::Color::Value->new( 'hsl(220,50,60)' );\nmy @rgb = $blue->get();\nmy $purple = $blue->set({red => 220});\n",
            "subsections": []
        },
        "DESCRIPTION": {
            "content": "The object that holds the normalized values of the original color definition (getter argument)\nand the normalized RGB tripled, if the color was not defined in RGB values. This way we omit\nconversion and rounding errors as much as possible.\n\nThis package is a mediation layer between Graphics::Toolkit::Color::Space::Hub below, where its\njust about number crunching of value vectors and the user API above in Graphics::Toolkit::Color,\nwhere it's mainly about producing sets of colors and handling the arguments. This module is not\nmeant to be used as an public API since it has much less comfort than\n*Graphics::Toolkit::Color*.\n",
            "subsections": []
        },
        "METHODS": {
            "content": "new\nThe constructor takes only one required argument, a scalar that completely and numerically\ndefines a color. Inside color definitions are color space names case insensitive. Some possible\nformats are\n\n[ 1, 2, 3 ]                  # RGB triplet\n[ HSL => 220, 100, 3 ]       # named HSL vector\n{ h => 220, s =>100, l => 3} # char hash\n{ cyan => 1, magenta => 0.5, yellow => 0} # hash\n'hwb: 20, 60, 30'            # string\n'hwb(20,60,30)'              # cssstring\n'#2211FF'                    # rgb hex string\n\nget\nUniversal getter method -almost reverse function to new: It can return the colors values in all\nsupported color spaces (first argument) (see: \"COLOR-SPACES\" in\nGraphics::Toolkit::Color::Space::Hub) and all mentioned formats above (second argument).\nAdditionally a third arguments can convert the numerical values into different ranges. The\ndefault name space is RGB, default format is a list and every color space has its default range.\n\nmy @rgb = $valobject->get();\nmy @cmyk = $valobject->get('CMYK', 'list', 255);\nmy $YIQ = $valobject->get('YIQ', 'string');\n\nset\nConstructs a new \"Graphics::Toolkit::Color::Value\" object by absolutely changing some values of\nthe current object and keeping others. (*add* changes some values relatively.) The only and\nrequired argument is a *HASH* reference which has keys that match only one of the supported\ncolor spaces (see: \"COLOR-SPACES\" in Graphics::Toolkit::Color::Space::Hub). Values outside of\nthe defined limits will be clamped to an acceptable value (or rotated in case of circular\ndimensions).\n\nmy $moreblendcolor = $valobject->set( {saturation => 40} );\nmy $brightcolor = $valobject->set( {saturation => 2240} ); #saturation will be 100\n\nadd\nThis method takes also a HASH reference as input and also produces a related color object as\nprevious *set*. Only difference is: the hash values will be added to the current. If they go\noutside of the defined limits, they will be clamped (or rotated in case of circular dimensions).\n\nmy $darkercolor = $valobject->set( {lightness => -10} );\n\nblend\nCreates a color value object by mixing two colors. First and only required argument is the\nsecond color value object. Second argument is the mixing ratio. Zero would result in the\noriginal color and one to the second color. Default value is 0.5 (1:1 mix). Values outside the\n0..1 rande are possible and values will be clamped if they leave the defined bounds of the\nrequired color space.\n\nThird optional argument is the name of the color space the mix will be calculated in - it\ndefaults to *'HSL'*.\n\nmy $green = Graphics::Toolkit::Color::Values->new( '#00ff00' );\nmy $cyan = $blue->blend( $green, 0.6, 'YIQ' );\n\ndistance\nComputes a real number which designates the (Euclidean) distance between two points in a color\nspace (a.k.a. colors).\n\nThe first and only required argument is the second color as an *Graphics::Toolkit::Color::Value*\nobject. Second and optional argument is the name of the color space, where the distance is\ncalculated in (default is *'HSL'*). Third argument is the metric, which currently is just the\nsubset of dimension in the chosen space that should be observed. One can also mention the\nshortcut name of a dimension several times to increase their weight in the calculation. Fourth\noptional argument are the numeric ranges of the dimensions. If none are given, the method only\nuses normalised (range: 0..1) values.\n\nmy $blue = Graphics::Toolkit::Color::Values->new( '#0000ff' );\nmy $green = Graphics::Toolkit::Color::Values->new( '#00ff00' );\nmy $d = $blue->distance( $green, 'HSV', 's', 255); # 0 : both have same saturation\n",
            "subsections": []
        },
        "SEE ALSO": {
            "content": "*   Convert::Color\n\nCOPYRIGHT & LICENSE\nCopyright 2023 Herbert Breunung.\n\nThis program is free software; you can redistribute it and/or modify it under same terms as Perl\nitself.\n",
            "subsections": []
        },
        "AUTHOR": {
            "content": "Herbert Breunung, <lichtkind@cpan.org>\n",
            "subsections": []
        }
    },
    "summary": "Graphics::Toolkit::Color::Value - single color related high level methods",
    "flags": [],
    "examples": [],
    "see_also": []
}