Enhance contrast using histogram equalization

`J = histeq(I,hgram)`

`J = histeq(I,n)`

```
[J,T] =
histeq(I)
```

`newmap = histeq(X,map)`

`newmap = histeq(X,map,hgram)`

```
[newmap,T]
= histeq(X,___)
```

transforms the grayscale image `J`

= histeq(`I`

,`n`

)`I`

, returning in
`J`

an grayscale image with `n`

discrete gray levels. A roughly equal number of pixels is mapped to each of the
`n`

levels in `J`

, so that the
histogram of `J`

is approximately flat. The histogram of
`J`

is flatter when `n`

is much
smaller than the number of discrete levels in `I`

.

transforms the colormap associated with the indexed image `newmap`

= histeq(`X`

,`map`

,`hgram`

)`X`

so that the histogram of the gray component of the indexed image
(`X`

,`newmap`

) approximately matches
the target histogram `hgram`

. The `histeq`

function returns the transformed colormap in `newmap`

.
`length(hgram)`

must be the same as
`size(map,1)`

.

This syntax is not supported on a GPU.

When you supply a desired histogram `hgram`

, `histeq`

chooses
the grayscale transformation *T* to minimize

$$\left|{c}_{1}(T(k))-{c}_{0}(k)\right|,$$

where *c*_{0} is
the cumulative histogram of `A`

, *c*_{1} is
the cumulative sum of `hgram`

for all intensities *k*.
This minimization is subject to the constraints that *T* must
be monotonic and *c*_{1}*(T(a))* cannot
overshoot *c*_{0}*(a)* by
more than half the distance between the histogram counts at *a*. `histeq`

uses
the transformation *b* = *T*(*a*)
to map the gray levels in `X`

(or the colormap)
to their new values.

If you do not specify `hgram`

, then `histeq`

creates a
flat `hgram`

,

hgram = ones(1,n)*prod(size(A))/n;

and then applies the previous algorithm.