\HeaderA{channel}{Color and image color mode conversions}{channel}
\aliasA{channel,ANY,character-method}{channel}{channel,ANY,character.Rdash.method}
\aliasA{channel,Image,character-method}{channel}{channel,Image,character.Rdash.method}
\aliasA{channelMix}{channel}{channelMix}
\aliasA{rgbImage}{channel}{rgbImage}
\keyword{file}{channel}
\begin{Description}\relax
\code{channel} allows to convert colors of images and color values given in 
vectors, arrays or matrices from one mode to another. The supported source and
target modes are TrueColor (data of type: \code{\LinkA{integer}{integer}}) and
Grayscale (\code{\LinkA{numeric}{numeric}}) and X11 strings (\code{\LinkA{character}{character}}).

The mode of the argument is determined automatically from its type.
\end{Description}
\begin{Usage}
\begin{verbatim} 
  ## S4 methods for signatures 'x=Image,mode=character'
  ## and 'x=ANY,mode=character'
  channel(x, mode, ...)
  
  rgbImage(r, g, b)
  channelMix(r, g, b)
\end{verbatim}
\end{Usage}
\begin{Arguments}
\begin{ldescription}
\item[\code{x}] Either an object of \code{\LinkA{Image}{Image.Rdash.class}} or a vector of 
\code{numeric}, \code{integer} or \code{character}. 
\item[\code{mode}] A character value specifying the target mode for conversion. 
See 'Conversion Modes' below. 
\item[\code{...}] Reserved. 
\item[\code{r,g,b}] Objects of class \code{\LinkA{Image}{Image.Rdash.class}}. 
\end{ldescription}
\end{Arguments}
\begin{Details}\relax
Conversion modes:

\describe{

\item[\code{rgb}] The result is a true color representation of the input.
Its class is or includes \code{integer}, i.e. an integer array or a 
\code{\LinkA{TrueColor}{TrueColor}} integer-based image. 

\item[\code{gray}] The result is a gray scale representation of the
input. Its class is or includes \code{numeric}. Synonym: \code{grey} 

\item[\code{red, green, blue }] The result is a gray scale representation 
of the input from only the red, the green or the blue channel was extracted,
correspondingly. The result's class is \code{numeric}-based. As synonyms
single letters \code{r, g, b} can be used correspondingly.

\item[\code{asred, asgreen, asblue}] The result is a true color with all
the data in one channel only, the red, green or blue, correspondingly. The
result's class is \code{integer}-based. As synonyms \code{2r, 2g, 2b} can
be used. 

\item[\code{x11}] The result is a \code{character}, which elements represent
the input colors as X11 strings, i.e. RGB hex codes starting with a sharp
sign. 

}

Conversion modes are case insensitive!

If the input is a \code{character} vector, its values may contain color names
instead of color hex codes, like \code{red, purple, white} etc. However,
the result of the \code{X11} mode will always contain hex codes.

\code{channelMix} uses the following formula to calculate the mix:
\code{mix = sqrt(r\textasciicircum{}2+g\textasciicircum{}+b\textasciicircum{}2)}. Any of the values can be missing.
\end{Details}
\begin{Value}
For an argument of \code{\LinkA{Image}{Image.Rdash.class}} the function returns a new object 
of \code{\LinkA{Image}{Image.Rdash.class}} in all modes except \code{'X11'}. In case of
\code{'X11'} it returns a \code{character} vector of the same length as the image.

For vectors the function returns a \code{vector} of the same size in the target
mode.

\code{rgbImage} generated a TrueColor image using \code{r}, \code{g} and \code{b}
as values for red, green and blue channels correspondingly.

\code{channelMix} generates a grayscale image as if the image was converted from
a TrueColor one that was composed using \code{r}, \code{g} and \code{b}.
\end{Value}
\begin{Author}\relax
Oleg Sklyar, \email{osklyar@ebi.ac.uk}
\end{Author}
\begin{SeeAlso}\relax
\code{
    \LinkA{Image}{Image.Rdash.class}, \LinkA{Image}{Image.Rdash.class}, \LinkA{Image}{Image.Rdash.class}
  }
\end{SeeAlso}
\begin{Examples}
\begin{ExampleCode}
  cl <- channel("pink", "rgb")
  r <- channel( channel(cl, "red"), "asred")
  g <- channel( channel("pink", "green"), "asgreen")
  b <- channel( channel(cl, "blue"), "asblue")
  rgb <- r + g + b
  print( rgb == cl )
  clg <- channel(cl, "gray")
  print( channel(cl, "x11"))
  
  ## further example in 'paintObjects'
\end{ExampleCode}
\end{Examples}

