% Copyright 2006 by Till Tantau
%
% This file may be distributed and/or modified
%
% 1. under the LaTeX Project Public License and/or
% 2. under the GNU Free Documentation License.
%
% See the file doc/generic/pgf/licenses/LICENSE for more details.


\section{Declaring and Using Images}
\label{section-images}


This section describes the commands for creating images.


\subsection{Overview}

To be quite frank, \LaTeX's |\includegraphics| is designed better than
\pgfname's image mechanism. For this reason, \emph{I recommend that you use the
  standard image inclusion mechanism of your format}. Thus, \LaTeX\
users are encouraged to use |\includegraphics| to include images.

However, there are reasons why you might need to use the image
inclusion facilities of \pgfname:
\begin{itemize}
\item
  There is no standard image inclusion mechanism in your format. For
  example, plain \TeX\ does not have one, so \pgfname's inclusion
  mechanism is ``better than nothing.''

  However, this applies only to the |pdftex| backend. For all other
  backends, \pgfname\ currently maps its commands back to the |graphicx|
  package. Thus, in plain \TeX, this does not really help. It might be
  a good idea to fix this in the future such that \pgfname\ becomes
  independent of \LaTeX, thereby providing a uniform image abstraction
  for all formats.
\item
  You wish to use masking. This is a feature that is only supported by
  \pgfname, though I hope that someone will implement this also for
  the graphics package in \LaTeX\ in the future.
\end{itemize}

Whatever your choice, you can still use the usual image inclusion
facilities of the |graphics| package.

The general approach taken by \pgfname\ to including an image is the
following: First, |\pgfdeclareimage| declares the
image. This must be done prior to the first use of the image. Once you
have declared an image, you can insert it into the text using
|\pgfuseimage|. The advantage of this two-phase approach is that, at
least for \textsc{pdf}, the image data will only be included once in the
file. This can drastically reduce the file size if you use an image
repeatedly, for example in an overlay. However, there is also a
command called |\pgfimage| that declares and then immediately uses the
image.

To speedup the compilation, you may wish to use the following class
option:
\begin{packageoption}{draft}
  In draft mode boxes showing the image name replace the
  images. It is checked whether the image files exist, but they are
  not read. If either height or width is not given, 1cm is used
  instead.
\end{packageoption}

\subsection{Declaring an Image}

\begin{command}{\pgfdeclareimage\oarg{options}\marg{image
      name}\marg{filename}}
  Declares an image, but does not paint anything. To draw the image,
  use |\pgfuseimage{|\meta{image name}|}|. The \meta{filename} may not
  have an extension.  For \textsc{pdf}, the extensions |.pdf|, |.jpg|,
  and |.png| will automatically tried. For PostScript, the extensions
  |.eps|, |.epsi|, and |.ps| will be tried.

  The following options are possible:
  \begin{itemize}
  \item
    \declare{|height=|\meta{dimension}} sets the height of the
    image. If the width is not specified simultaneously, the aspect
    ratio of the image is kept.
  \item
    \declare{|width=|\meta{dimension}} sets the width of the
    image. If the height is not specified simultaneously, the aspect
    ratio of the image is kept.
  \item
    \declare{|page=|\meta{page number}} selects a given page number
    from a multipage document. Specifying this option will have the
    following effect: first, \pgfname\ tries to find a file named
    \begin{quote}
      \meta{filename}|.page|\meta{page number}|.|\meta{extension}
    \end{quote}
    If such a file is found, it will be used instead of the originally
    specified filename. If not, \pgfname\ inserts the image stored in
    \meta{filename}|.|\meta{extension} and if a recent version of
    |pdflatex| is used, only the selected page is inserted. For older
    versions of |pdflatex| and for |dvips| the complete document is
    inserted and a warning is printed.
  \item
    \declare{|interpolate=|\meta{true or false}} selects whether the
    image should be ``smoothed'' when zoomed. False by default.
  \item
    \declare{|mask=|\meta{mask name}} selects a transparency mask. The
    mask must previously be declared using |\pgfdeclaremask| (see
    below). This option only has an effect for |pdf|. Not all viewers
    support masking.
  \end{itemize}

\begin{codeexample}[code only]
\pgfdeclareimage[interpolate=true,height=1cm]{image1}{brave-gnu-world-logo}
\pgfdeclareimage[interpolate=true,width=1cm,height=1cm]{image2}{brave-gnu-world-logo}
\pgfdeclareimage[interpolate=true,height=1cm]{image3}{brave-gnu-world-logo}
\end{codeexample}
\end{command}


\begin{command}{\pgfaliasimage\marg{new image name}\marg{existing image name}}
  The \marg{existing image name} is ``cloned'' and the \marg{new image
    name} can now be used whenever the original image is used. This
  command is useful for creating aliases for alternate extensions
  and for accessing the last image inserted using |\pgfimage|.

  \example |\pgfaliasimage{image.!30!white}{image.!25!white}|
\end{command}


\subsection{Using an Image}

\begin{command}{\pgfuseimage\marg{image name}}
  Inserts a previously declared image into the \emph{normal text}. If
  you wish to use it in a |{pgfpicture}| environment, you must put a
  |\pgftext| around it.

  If the macro |\pgfalternateextension| expands to some nonempty
  \meta{alternate extension}, \pgfname\ will first try to use the image
  named \meta{image name}|.|\meta{alternate extension}. If this
  image is not defined, \pgfname\ will next check whether \meta{alternate
    extension} contains a |!| character. If so, everything up to this
  exclamation mark and including it is deleted from \meta{alternate
    extension} and the \pgfname\ again tries to use the image \meta{image
    name}|.|\meta{alternate extension}. This is repeated until
  \meta{alternate extension} no longer contains a~|!|. Then the
  original image is used.

  The |xxcolor| package sets the alternate extension to the current
  color mixin.          % TODOsp: `color mixin': meant `color mixing' or the `colormixin' environment?

\begin{codeexample}[]
\pgfdeclareimage[interpolate=true,width=1cm,height=1cm]
  {image1}{brave-gnu-world-logo}
\pgfdeclareimage[interpolate=true,width=1cm]{image2}{brave-gnu-world-logo}
\pgfdeclareimage[interpolate=true,height=1cm]{image3}{brave-gnu-world-logo}
\begin{pgfpicture}
  \pgftext[at=\pgfpoint{1cm}{5cm},left,base]{\pgfuseimage{image1}}
  \pgftext[at=\pgfpoint{1cm}{3cm},left,base]{\pgfuseimage{image2}}
  \pgftext[at=\pgfpoint{1cm}{1cm},left,base]{\pgfuseimage{image3}}

  \pgfpathrectangle{\pgfpoint{1cm}{5cm}}{\pgfpoint{1cm}{1cm}}
  \pgfpathrectangle{\pgfpoint{1cm}{3cm}}{\pgfpoint{1cm}{1cm}}
  \pgfpathrectangle{\pgfpoint{1cm}{1cm}}{\pgfpoint{1cm}{1cm}}
  \pgfusepath{stroke}
\end{pgfpicture}
\end{codeexample}

  The following example demonstrates the effect of using
  |\pgfuseimage| inside a colormixin environment.

\begin{codeexample}[]
\pgfdeclareimage[interpolate=true,width=1cm,height=1cm]
  {image1.!25!white}{brave-gnu-world-logo.25}
\pgfdeclareimage[interpolate=true,width=1cm]
  {image2.25!white}{brave-gnu-world-logo.25}
\pgfdeclareimage[interpolate=true,height=1cm]
  {image3.white}{brave-gnu-world-logo.25}
\begin{colormixin}{25!white}
\begin{pgfpicture}
  \pgftext[at=\pgfpoint{1cm}{5cm},left,base]{\pgfuseimage{image1}}
  \pgftext[at=\pgfpoint{1cm}{3cm},left,base]{\pgfuseimage{image2}}
  \pgftext[at=\pgfpoint{1cm}{1cm},left,base]{\pgfuseimage{image3}}

  \pgfpathrectangle{\pgfpoint{1cm}{5cm}}{\pgfpoint{1cm}{1cm}}
  \pgfpathrectangle{\pgfpoint{1cm}{3cm}}{\pgfpoint{1cm}{1cm}}
  \pgfpathrectangle{\pgfpoint{1cm}{1cm}}{\pgfpoint{1cm}{1cm}}
  \pgfusepath{stroke}
\end{pgfpicture}
\end{colormixin}
\end{codeexample}
\end{command}

\begin{command}{\pgfalternateextension}
  You should redefine this command to install a different alternate
  extension.

  \example |\def\pgfalternateextension{!25!white}|
\end{command}


\begin{command}{\pgfimage\oarg{options}\marg{filename}}
  Declares the image under the name |pgflastimage| and
  immediately uses it. You can ``save'' the image for later usage by
  invoking |\pgfaliasimage| on |pgflastimage|.

\begin{codeexample}[]
\begin{colormixin}{25!white}
\begin{pgfpicture}
  \pgftext[at=\pgfpoint{1cm}{5cm},left,base]
    {\pgfimage[interpolate=true,width=1cm,height=1cm]{brave-gnu-world-logo}}
  \pgftext[at=\pgfpoint{1cm}{3cm},left,base]
    {\pgfimage[interpolate=true,width=1cm]{brave-gnu-world-logo}}
  \pgftext[at=\pgfpoint{1cm}{1cm},left,base]
    {\pgfimage[interpolate=true,height=1cm]{brave-gnu-world-logo}}

  \pgfpathrectangle{\pgfpoint{1cm}{5cm}}{\pgfpoint{1cm}{1cm}}
  \pgfpathrectangle{\pgfpoint{1cm}{3cm}}{\pgfpoint{1cm}{1cm}}
  \pgfpathrectangle{\pgfpoint{1cm}{1cm}}{\pgfpoint{1cm}{1cm}}
  \pgfusepath{stroke}
\end{pgfpicture}
\end{colormixin}
\end{codeexample}
\end{command}



\subsection{Masking an Image}


\begin{command}{\pgfdeclaremask\oarg{options}\marg{mask  name}\marg{filename}}
  Declares a transparency mask named \meta{mask name} (called a
  \emph{soft mask} in the \textsc{pdf} specification). This mask is
  read from the file \meta{filename}. This file should contain a
  grayscale image that is as large as the actual image. A white
  pixel in the mask will correspond to ``transparent,'' a black pixel
  to ``solid,'' and gray values correspond to intermediate values. The
  mask must have a single ``color channel.'' This means that the
  mask must be a ``real'' grayscale image, not an \textsc{rgb}-image
  in which all \textsc{rgb}-triples happen to have the same
  components.

  You can only mask images the are in a ``pixel format.'' These are
  |.jpg| and |.png|.  You cannot mask |.pdf| images in this way. Also,
  again, the mask file and the image file must have the same size.

  The following options may be given:
  \begin{itemize}
  \item |matte=|\marg{color components} sets the so-called
    \emph{matte} of the actual image (strangely, this has to be
    specified together with the mask, not with the image itself). The
    matte is the color that has been used to preblend the image. For
    example, if the image has been preblended with a red background,
    then \meta{color components} should be set to |{1 0 0}|. The
    default is |{1 1 1}|, which is white in the rgb model.

    The matte is specified in terms of the parent's image color
    space. Thus, if the parent is a grayscale image, the matte has to
    be set to |{1}|.
  \end{itemize}
  \example
\begin{codeexample}[]
%% Draw a large colorful background
\pgfdeclarehorizontalshading{colorful}{5cm}{color(0cm)=(red);
color(2cm)=(green); color(4cm)=(blue); color(6cm)=(red);
color(8cm)=(green); color(10cm)=(blue); color(12cm)=(red);
color(14cm)=(green)}
\hbox{\pgfuseshading{colorful}\hskip-14cm\hskip1cm
\pgfimage[height=4cm]{brave-gnu-world-logo}\hskip1cm
\pgfimage[height=4cm]{brave-gnu-world-logo-mask}\hskip1cm
\pgfdeclaremask{mymask}{brave-gnu-world-logo-mask}
\pgfimage[mask=mymask,height=4cm,interpolate=true]{brave-gnu-world-logo}}
\end{codeexample}
\end{command}

%%% Local Variables:
%%% mode: latex
%%% TeX-master: "pgfmanual"
%%% End:
