# illumwhite

Estimate illuminant using White Patch Retinex algorithm

## Syntax

``illuminant = illumwhite(A)``
``illuminant = illumwhite(A,topPercentile)``
``illuminant = illumwhite(___,'Mask',mask)``

## Description

````illuminant = illumwhite(A)` estimates the scene illumination in RGB image `A` by assuming that the top 1% brightest red, green, and blue values represent the color white.```

example

````illuminant = illumwhite(A,topPercentile)` estimates the illumination using the `topPercentile` percentage brightest red, green, and blue values.```
````illuminant = illumwhite(___,'Mask',mask)` estimates the illumination using only the pixels within the ROI defined by a binary mask.```

## Examples

collapse all

Open an image and display it. Specify an optional magnification to shrink the size of the displayed image.

```A = imread('foosball.jpg'); figure imshow(A,'InitialMagnification',25) title('Original Image')```

The JPEG file format saves images in the gamma-corrected sRGB color space. Undo the gamma correction by using the `rgb2lin` function.

`A_lin = rgb2lin(A);`

Estimate the scene illumination from the top 5% brightest pixels. Because the input image has been linearized, the `illumwhite` function returns the illuminant in the linear RGB color space.

```topPercentile = 5; illuminant = illumwhite(A,topPercentile)```
```illuminant = 1×3 0.7333 0.8314 1.0000 ```

The third coefficient of `illuminant` is the largest, which is consistent with the blue tint of the image.

Correct colors by providing the estimated illuminant to the `chromadapt` function.

`B_lin = chromadapt(A_lin,illuminant,'ColorSpace','linear-rgb');`

To display the white-balanced image correctly on the screen, apply gamma correction by using the `lin2rgb` function.

`B = lin2rgb(B_lin);`

Display the corrected image, setting the optional magnification.

```figure imshow(B,'InitialMagnification',25) title(['White-Balanced Image using White Patch with topPercentile=' ... num2str(topPercentile)])```

## Input Arguments

collapse all

RGB image, specified as an m-by-n-by-3 numeric array.

Data Types: `single` | `double` | `uint8` | `uint16`

Percentile of brightest colors to use for illuminant estimation, specified as a numeric scalar in the range [0, 100). To return the maximum red, green, and blue values, set `topPercentile` to 0.

The image indicates the red, green, and blue value that is selected to estimate the illuminant. The selection is separate for each color channel.

Data Types: `single` | `double` | `int8` | `int16` | `int32` | `int64` | `uint8` | `uint16` | `uint32` | `uint64`

Image mask, specified as an m-by-n logical or numeric matrix. The mask indicates which pixels of the input image `A` to use when estimating the illuminant. The computation excludes pixels in `A` that correspond to a mask value of 0. By default, the mask has all 1s, and all pixels in `A` are included in the estimation.

Data Types: `single` | `double` | `int8` | `int16` | `int32` | `int64` | `uint8` | `uint16` | `uint32` | `uint64` | `logical`

## Output Arguments

collapse all

Estimate of scene illumination, returned as a 3-element numeric row vector. The three elements correspond to the red, green, and blue values of the illuminant.

Data Types: `double`

## References

[1] Ebner, Marc. "White Patch Retinex." Color Constancy. Chichester, West Sussex: John Wiley & Sons, 2007.

## Version History

Introduced in R2017b