\section{WINLEV Image Window-Level Function}

\subsection{Usage}

Adjusts the data range used to map the current image to the current
colormap.  The general syntax for its use is
\begin{verbatim}
  winlev(window,level)
\end{verbatim}
where \verb|window| is the new window, and \verb|level| is the new level, or
\begin{verbatim}
  winlev
\end{verbatim}
in which case it returns a vector containing the current window
and level for the active image.
\subsection{Function Internals}

FreeMat deals with scalar images on the range of \verb|[0,1]|, and must
therefor map an arbitrary image \verb|x| to this range before it can
be displayed.  By default, the \verb|image| command chooses 
\[
  \mathrm{window} = \max x - \min x,
\]
and
\[
  \mathrm{level} = \frac{\mathrm{window}}{2}
\]
This ensures that the entire range of image values in \verb|x| are 
mapped to the screen.  With the \verb|winlev| function, you can change
the range of values mapped.  In general, before display, a pixel \verb|x|
is mapped to \verb|[0,1]| via:
\[
   \max\left(0,\min\left(1,\frac{x - \mathrm{level}}{\mathrm{window}}
   \right)\right)
\]
\subsection{Examples}

The window level function is fairly easy to demonstrate.  Consider
the following image, which is a Gaussian pulse image that is very 
narrow:
\begin{verbatim}
--> t = linspace(-1,1,256);
--> xmat = ones(256,1)*t; ymat = xmat';
--> A = exp(-(xmat.^2 + ymat.^2)*100);
--> image(A);

\end{verbatim}
The data range of \verb|A| is \verb|[0,1]|, as we can verify numerically:
\begin{verbatim}
--> min(A(:))
ans = 
  <double>  - size: [1 1]
 1.3838965267367376e-87  
--> max(A(:))
ans = 
  <double>  - size: [1 1]
 0.9969289851428387  

\end{verbatim}
To see the tail behavior, we use the \verb|winlev| command to force FreeMat
to map a smaller range of \verb|A| to the colormap.
\begin{verbatim}
--> image(A);
--> winlev(1e-4,0.5e-4)

\end{verbatim}
The result is a look at more of the tail behavior of \verb|A|.
We can also use the winlev function to find out what the
window and level are once set, as in the following example.
\begin{verbatim}
--> image(A);
--> winlev(1e-4,0.5e-4)
--> winlev
ans = 
  <double>  - size: [1 1]
 0.0001  

\end{verbatim}
