ph_luminance PowerHome formula function
Description
Returns the perceived luminance (brightness) of an RGB color value 
Syntax
ph_luminance ( ai_type, al_color )
Argument Description
ai_type Integer. A flags parameter that control how the luminance calculations are performed. See Usage below
al_color Long. A standard RGB color value to determine the luminance of
Return value
Integer. Returns the perceived luminance of the RGB color value in the range of 0 to 255 with 255 being the brightest or highest luminance 
Usage
Use this function to determine the luminance of an RGB color value. Useful for determining the perceived brightness of a color 

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 perceived luminance/brightness 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 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_luminance(12,rgb(255,255,255)) - Returns a luminance value of 255. The function rgb(255,255,255) is pure white and would have the highest luminance 
    • ph_luminance(12,rgb(255,0,0)) - Returns a luminance value of 127. The function rgb(255,0,0) is pure red 
    • ph_luminance(12,rgb(0,0,255)) - Returns a luminance value of 76. The function rgb(0,0,255) is pure blue and indicates that pure red (127) will be perceived as brighter than pure blue (76)