ph_highestcontrast PowerHome formula function
Description
Given a base RGB color to compare to and two
RGB colors to choose between, returns the RGB color value that has the
highest contrast
Syntax
ph_highestcontrast ( ai_type, al_color1, al_color2, al_backcolor )
| Argument | Description |
| ai_type | Integer. A flags parameter to determine how to
perform the calculation. See Usage below for more info |
| al_color1 | Long. The 1st of 2 RGB color values to check
for highest contrast |
| al_color2 | Long. The 2nd of 2 RGB color values to check
for highest contrast |
| al_backcolor | Long. The base RGB color to compare the above
two RGB color values against |
Return value
Long. Returns either the value in
al_color1 or the value in al_color2. If the RGB color in al_color1
compared to the al_backcolor is a higher contrast than the RGB color in
al_color2 compared to the al_backcolor, then al_color1 will be returned.
Otherwise, al_color2
will be returned
Usage
Use this function to quickly
determine which of two supplied RGB color values will produce a higher
contrast against a base RGB color. This function would typically be used to
decide whether a foreground color of black or a foreground color of white would
provide the best contrast against the supplied background color. In Analog I/O
and Zwave raw to calc formulas, a typical scenario is to adjust the
background color of the calc value based upon it's value. Having done so, this
function will then determine if the foreground color for the calc value would be best as either
black or white. You can use ANY valid RGB colors for the al_color1 and
al_color2 parameters but either Black or White will always provide the
highest possible contrast and
best legibility.
The ai_type parameter is a flags (values added together)
parameter than determines how the calculation of luminance is performed. The proper value for ai_type is obtained by adding each desired value below together to achieve the desired calcuation result which would should end up as either 4, 8, 12, or 16:
4 - Convert gamma corrected RGB values to linear
8 - Add gamma correction to calculated result. (Don't need this for a pure luminance value)
16 - Square RGB values before applying weights and take SQRT of value after applying weights. Approximates 4 and 8 (12) correction for gamma
To the above calculated value (either 4,
8, 12, or 16), add ONLY 1 of the below values to determine which set of
weights to use
0 - Use 1st set of weighted values
1 - Use 2nd set of weighted values
2 - Use 3rd set of weighted values
The weight values are below:
| |
Red |
Green |
Blue |
| Weight 1 |
0.2126 |
0.7152 |
0.0722 |
| Weight 2 |
0.299 |
0.587 |
0.114 |
| Weight 3 |
0.241 |
0.691 |
0.068 |
Best default to determine displayed color contrast would be a type with a value of 12. This converts gamma corrected RGB values to linear values, applies the first
set of weights (most commonly accepted values) and then gamma corrects the result. This gives us a perceived luminance to compare color contrast.
This is also the best default to convert color values to grayscale.
Adding a value of 16 to the type approximates the
conversion from gamma corrected RGB values to linear RGB values (raised to power
of 2.0 vs power of 2.2). When using a type that includes 16, you would most
likely NOT want to include a 4 or 8 in the type value. A type value of 12 or 16
should produce very similar results.
Examples
The following examples demonstrate typical syntax/usage for this function.
• ph_highestcontrast(12,rgb(0,0,0),rgb(255,255,255),rgb(240,170,44))
- Returns 0 which is the rgb value for black or
rgb(0,0,0)
• ph_highestcontrast(12,rgb(0,0,0),rgb(255,255,255),rgb(30,100,44))
- Returns 16777215 which is the rgb value for white or
rgb(255,255,255)