{smcl}
{* 19May2006}{...}
{cmd:help hsl}
{hline}

{title:Title}

{col 5}{hi:hsl} {hline 2} Convert color values from HSL to RGB
 
{title:Syntax}

{p 8 16 2}
{cmd:hsl} {it:hue} [{it:saturation} [{it:lightness}]], [{opt rgb(macroname)}  {opt p:alette} {cmd:path(fup}|{cmd:fdown}|{cmd:long)}]

{p 4 4 2} where:

{p 8 16 2}{it:hue} is of the form {it:c}, {it:cc}, or {it:cc#}, where: 

{p 12 16 2}{it:c} is the first letter of any of the color words: red, orange, yellow, green, cyan, blue, purple

{p 12 16 2}{it:#} is a number between 0 and 100.

{p 8 16 2}{it:saturation} is a number between 0 and 100

{p 8 16 2}{it:lightness} is a number between -100 and 100

{title:Description}

{p 4 4 2}{cmd:hsl} allows colors to be specified in the psychologically friendly {bf:HSL} system, and provides translated {bf:RGB} values that can be used as input in other commands.

{p 4 4 2}{it:Saturation} is specified as a percent, i.e., 100 equals full saturation. If saturation is not specified, it defaults to 100%.

{p 4 4 2}{it:Lightness} ranges from -100, for black, to 100, for white, with {it:lightness}=0 (the default) allowing the most saturated colors.

{p 4 4 2}{it:hue} can be specified as a single hue, or as a percent distance between two anchor hues. For example, {bf:r} specifies red, and {bf:bg50} specifies the hue halfway between blue and green. 

{p 4 4 2}In general, {it:xyz} specifies the color {it:z}-percent of the way from {it:x} to {it:y}. So {bf:bg25} (a quarter of the way from blue to green) is the color halfway between {bf:blue} and blue-green, while {bf:gb25}
(a quarter of the way from green to blue) is the color halfway between {bf:green} and blue-green. 
If the distance is omitted, 50% is assumed - so {bf:ry} is equivalent to {bf:o}, orange. 

{title:Options}

{p 4 8 2}If {cmd:rgb()} is specifed, quote-enclosed {bf:RGB} values will be returned in the local macro {it:macroname}; otherwise, the values will be displayed in the results window.

{p 4 8 2}{cmdab:p:alette} runs Stata's {help palette} command for the color specified.

{p 4 8 2}{cmd:path()} specifies how the color wheel is traversed in going from one anchor hue to the other. This is only relevant when choosing a series of colors programatically.

{p 8 8 2}If {cmd:path()} is not specified, {cmd:hsl} chooses the "shortest" path from one hue to another. E.g, {cmd:hsl ry25} (a quarter of the way from red to yellow) results in red-orange, while {cmd:hsl ry25, path(long)}
(a quarter of the way from red to yellow, "the long way round") results in red-purple.

{p 8 8 2}Similarly, the path can be specified as {cmd:fup}: in the direction of increasing frequency (ie, red to green to blue back to red), or as {cmd:fdown}: in the direction of decreasing frequency.
When neither {cmd:fup} nor {cmd:fdown} is specified and the anchor hues are exactly opposite on the color wheel, the direction of increasing frequency is used.

{title:Examples}

{p 4 8 2}{cmd:. hsl p, rgb(purplemacro)}

{p 4 8 2}{cmd:. hsl oy}
 
{p 4 8 2}{cmd:. hsl bg8.5, palette}

{p 4 8 2}{cmd:. hsl ro10, path(long)}

{title:Also see}

{pstd}Online: help for {help colorstyle}, {help palette}

{pstd}Contact: {browse "mailto:elliott.lowy@va.gov":Elliott Lowy}