| 1 |
% Copyright 2019 by Till Tantau |
| 2 |
% |
| 3 |
% This file may be distributed and/or modified |
| 4 |
% |
| 5 |
% 1. under the LaTeX Project Public License and/or |
| 6 |
% 2. under the GNU Free Documentation License. |
| 7 |
% |
| 8 |
% See the file doc/generic/pgf/licenses/LICENSE for more details. |
| 9 |
|
| 10 |
|
| 11 |
\section{Declaring and Using Images} |
| 12 |
\label{section-images} |
| 13 |
|
| 14 |
This section describes the commands for creating images. |
| 15 |
|
| 16 |
|
| 17 |
\subsection{Overview} |
| 18 |
|
| 19 |
To be quite frank, \LaTeX's |\includegraphics| is designed better than |
| 20 |
\pgfname's image mechanism. For this reason, \emph{I recommend that you use the |
| 21 |
standard image inclusion mechanism of your format}. Thus, \LaTeX\ users are |
| 22 |
encouraged to use |\includegraphics| to include images. |
| 23 |
|
| 24 |
However, there are reasons why you might need to use the image inclusion |
| 25 |
facilities of \pgfname: |
| 26 |
% |
| 27 |
\begin{itemize} |
| 28 |
\item There is no standard image inclusion mechanism in your format. For |
| 29 |
example, plain \TeX\ does not have one, so \pgfname's inclusion |
| 30 |
mechanism is ``better than nothing''. |
| 31 |
|
| 32 |
However, this applies only to the |pdftex| backend. For all other |
| 33 |
backends, \pgfname\ currently maps its commands back to the |graphicx| |
| 34 |
package. Thus, in plain \TeX, this does not really help. It might be a |
| 35 |
good idea to fix this in the future such that \pgfname\ becomes |
| 36 |
independent of \LaTeX, thereby providing a uniform image abstraction |
| 37 |
for all formats. |
| 38 |
\item You wish to use masking. This is a feature that is only supported by |
| 39 |
\pgfname, though I hope that someone will implement this also for the |
| 40 |
graphics package in \LaTeX\ in the future. |
| 41 |
\end{itemize} |
| 42 |
|
| 43 |
Whatever your choice, you can still use the usual image inclusion facilities of |
| 44 |
the |graphics| package. |
| 45 |
|
| 46 |
The general approach taken by \pgfname\ to including an image is the following: |
| 47 |
First, |\pgfdeclareimage| declares the image. This must be done prior to the |
| 48 |
first use of the image. Once you have declared an image, you can insert it into |
| 49 |
the text using |\pgfuseimage|. The advantage of this two-phase approach is |
| 50 |
that, at least for \textsc{pdf}, the image data will only be included once in |
| 51 |
the file. This can drastically reduce the file size if you use an image |
| 52 |
repeatedly, for example in an overlay. However, there is also a command called |
| 53 |
|\pgfimage| that declares and then immediately uses the image. |
| 54 |
|
| 55 |
To speedup the compilation, you may wish to use the following class option: |
| 56 |
% |
| 57 |
\begin{packageoption}{draft} |
| 58 |
In draft mode boxes showing the image name replace the images. It is |
| 59 |
checked whether the image files exist, but they are not read. If either |
| 60 |
height or width is not given, 1cm is used instead. |
| 61 |
\end{packageoption} |
| 62 |
|
| 63 |
|
| 64 |
\subsection{Declaring an Image} |
| 65 |
|
| 66 |
\begin{command}{\pgfdeclareimage\oarg{options}\marg{image name}\marg{filename}} |
| 67 |
Declares an image, but does not paint anything. To draw the image, use |
| 68 |
|\pgfuseimage{|\meta{image name}|}|. The \meta{filename} may not have an |
| 69 |
extension. For \textsc{pdf}, the extensions |.pdf|, |.jpg|, and |.png| |
| 70 |
will automatically tried. For PostScript, the extensions |.eps|, |.epsi|, |
| 71 |
and |.ps| will be tried. |
| 72 |
|
| 73 |
The following options are possible: |
| 74 |
% |
| 75 |
\begin{itemize} |
| 76 |
\item \declare{|height=|\meta{dimension}} sets the height of the image. |
| 77 |
If the width is not specified simultaneously, the aspect ratio of |
| 78 |
the image is kept. |
| 79 |
\item \declare{|width=|\meta{dimension}} sets the width of the image. |
| 80 |
If the height is not specified simultaneously, the aspect ratio of |
| 81 |
the image is kept. |
| 82 |
\item \declare{|page=|\meta{page number}} selects a given page number |
| 83 |
from a multipage document. Specifying this option will have the |
| 84 |
following effect: first, \pgfname\ tries to find a file named |
| 85 |
% |
| 86 |
\begin{quote} |
| 87 |
\meta{filename}|.page|\meta{page number}|.|\meta{extension} |
| 88 |
\end{quote} |
| 89 |
% |
| 90 |
If such a file is found, it will be used instead of the originally |
| 91 |
specified filename. If not, \pgfname\ inserts the image stored in |
| 92 |
\meta{filename}|.|\meta{extension} and if a recent version of |
| 93 |
|pdflatex| is used, only the selected page is inserted. For older |
| 94 |
versions of |pdflatex| and for |dvips| the complete document is |
| 95 |
inserted and a warning is printed. |
| 96 |
\item \declare{|interpolate=|\meta{true or false}} selects whether the |
| 97 |
image should be ``smoothed'' when zoomed. False by default. |
| 98 |
\item \declare{|mask=|\meta{mask name}} selects a transparency mask. |
| 99 |
The mask must previously be declared using |\pgfdeclaremask| (see |
| 100 |
below). This option only has an effect for |pdf|. Not all viewers |
| 101 |
support masking. |
| 102 |
\end{itemize} |
| 103 |
% |
| 104 |
\begin{codeexample}[code only] |
| 105 |
\pgfdeclareimage[interpolate=true,height=1cm]{image1}{brave-gnu-world-logo} |
| 106 |
\pgfdeclareimage[interpolate=true,width=1cm,height=1cm]{image2}{brave-gnu-world-logo} |
| 107 |
\pgfdeclareimage[interpolate=true,height=1cm]{image3}{brave-gnu-world-logo} |
| 108 |
\end{codeexample} |
| 109 |
% |
| 110 |
\end{command} |
| 111 |
|
| 112 |
\begin{command}{\pgfaliasimage\marg{new image name}\marg{existing image name}} |
| 113 |
The \marg{existing image name} is ``cloned'' and the \marg{new image name} |
| 114 |
can now be used whenever the original image is used. This command is useful |
| 115 |
for creating aliases for alternate extensions and for accessing the last |
| 116 |
image inserted using |\pgfimage|. |
| 117 |
|
| 118 |
\example |\pgfaliasimage{image.!30!white}{image.!25!white}| |
| 119 |
\end{command} |
| 120 |
|
| 121 |
|
| 122 |
\subsection{Using an Image} |
| 123 |
|
| 124 |
\begin{command}{\pgfuseimage\marg{image name}} |
| 125 |
Inserts a previously declared image into the \emph{normal text}. If you |
| 126 |
wish to use it in a |{pgfpicture}| environment, you must put a |\pgftext| |
| 127 |
around it. |
| 128 |
|
| 129 |
If the macro |\pgfalternateextension| expands to some nonempty |
| 130 |
\meta{alternate extension}, \pgfname\ will first try to use the image named |
| 131 |
\meta{image name}|.|\meta{alternate extension}. If this image is not |
| 132 |
defined, \pgfname\ will next check whether \meta{alternate extension} |
| 133 |
contains a |!| character. If so, everything up to this exclamation mark and |
| 134 |
including it is deleted from \meta{alternate extension} and the \pgfname\ |
| 135 |
again tries to use the image \meta{image name}|.|\meta{alternate |
| 136 |
extension}. This is repeated until \meta{alternate extension} no longer |
| 137 |
contains a~|!|. Then the original image is used. |
| 138 |
|
| 139 |
The |xxcolor| package sets the alternate extension to the current color |
| 140 |
mixin. |
| 141 |
% |
| 142 |
\begin{codeexample}[] |
| 143 |
\pgfdeclareimage[interpolate=true,width=1cm,height=1cm] |
| 144 |
{image1}{brave-gnu-world-logo} |
| 145 |
\pgfdeclareimage[interpolate=true,width=1cm]{image2}{brave-gnu-world-logo} |
| 146 |
\pgfdeclareimage[interpolate=true,height=1cm]{image3}{brave-gnu-world-logo} |
| 147 |
\begin{pgfpicture} |
| 148 |
\pgftext[at=\pgfpoint{1cm}{5cm},left,base]{\pgfuseimage{image1}} |
| 149 |
\pgftext[at=\pgfpoint{1cm}{3cm},left,base]{\pgfuseimage{image2}} |
| 150 |
\pgftext[at=\pgfpoint{1cm}{1cm},left,base]{\pgfuseimage{image3}} |
| 151 |
|
| 152 |
\pgfpathrectangle{\pgfpoint{1cm}{5cm}}{\pgfpoint{1cm}{1cm}} |
| 153 |
\pgfpathrectangle{\pgfpoint{1cm}{3cm}}{\pgfpoint{1cm}{1cm}} |
| 154 |
\pgfpathrectangle{\pgfpoint{1cm}{1cm}}{\pgfpoint{1cm}{1cm}} |
| 155 |
\pgfusepath{stroke} |
| 156 |
\end{pgfpicture} |
| 157 |
\end{codeexample} |
| 158 |
|
| 159 |
The following example demonstrates the effect of using |\pgfuseimage| |
| 160 |
inside a colormixin environment. |
| 161 |
% |
| 162 |
\begin{codeexample}[preamble={\usepackage{xxcolor}}] |
| 163 |
\pgfdeclareimage[interpolate=true,width=1cm,height=1cm] |
| 164 |
{image1.!25!white}{brave-gnu-world-logo.25} |
| 165 |
\pgfdeclareimage[interpolate=true,width=1cm] |
| 166 |
{image2.25!white}{brave-gnu-world-logo.25} |
| 167 |
\pgfdeclareimage[interpolate=true,height=1cm] |
| 168 |
{image3.white}{brave-gnu-world-logo.25} |
| 169 |
\begin{colormixin}{25!white} |
| 170 |
\begin{pgfpicture} |
| 171 |
\pgftext[at=\pgfpoint{1cm}{5cm},left,base]{\pgfuseimage{image1}} |
| 172 |
\pgftext[at=\pgfpoint{1cm}{3cm},left,base]{\pgfuseimage{image2}} |
| 173 |
\pgftext[at=\pgfpoint{1cm}{1cm},left,base]{\pgfuseimage{image3}} |
| 174 |
|
| 175 |
\pgfpathrectangle{\pgfpoint{1cm}{5cm}}{\pgfpoint{1cm}{1cm}} |
| 176 |
\pgfpathrectangle{\pgfpoint{1cm}{3cm}}{\pgfpoint{1cm}{1cm}} |
| 177 |
\pgfpathrectangle{\pgfpoint{1cm}{1cm}}{\pgfpoint{1cm}{1cm}} |
| 178 |
\pgfusepath{stroke} |
| 179 |
\end{pgfpicture} |
| 180 |
\end{colormixin} |
| 181 |
\end{codeexample} |
| 182 |
% |
| 183 |
\end{command} |
| 184 |
|
| 185 |
\begin{command}{\pgfalternateextension} |
| 186 |
You should redefine this command to install a different alternate |
| 187 |
extension. |
| 188 |
|
| 189 |
\example |\def\pgfalternateextension{!25!white}| |
| 190 |
\end{command} |
| 191 |
|
| 192 |
\begin{command}{\pgfimage\oarg{options}\marg{filename}} |
| 193 |
Declares the image under the name |pgflastimage| and immediately uses it. |
| 194 |
You can ``save'' the image for later usage by invoking |\pgfaliasimage| on |
| 195 |
|pgflastimage|. |
| 196 |
% |
| 197 |
\begin{codeexample}[preamble={\usepackage{xxcolor}}] |
| 198 |
\begin{colormixin}{25!white} |
| 199 |
\begin{pgfpicture} |
| 200 |
\pgftext[at=\pgfpoint{1cm}{5cm},left,base] |
| 201 |
{\pgfimage[interpolate=true,width=1cm,height=1cm]{brave-gnu-world-logo}} |
| 202 |
\pgftext[at=\pgfpoint{1cm}{3cm},left,base] |
| 203 |
{\pgfimage[interpolate=true,width=1cm]{brave-gnu-world-logo}} |
| 204 |
\pgftext[at=\pgfpoint{1cm}{1cm},left,base] |
| 205 |
{\pgfimage[interpolate=true,height=1cm]{brave-gnu-world-logo}} |
| 206 |
|
| 207 |
\pgfpathrectangle{\pgfpoint{1cm}{5cm}}{\pgfpoint{1cm}{1cm}} |
| 208 |
\pgfpathrectangle{\pgfpoint{1cm}{3cm}}{\pgfpoint{1cm}{1cm}} |
| 209 |
\pgfpathrectangle{\pgfpoint{1cm}{1cm}}{\pgfpoint{1cm}{1cm}} |
| 210 |
\pgfusepath{stroke} |
| 211 |
\end{pgfpicture} |
| 212 |
\end{colormixin} |
| 213 |
\end{codeexample} |
| 214 |
% |
| 215 |
\end{command} |
| 216 |
|
| 217 |
|
| 218 |
\subsection{Masking an Image} |
| 219 |
|
| 220 |
\begin{command}{\pgfdeclaremask\oarg{options}\marg{mask name}\marg{filename}} |
| 221 |
Declares a transparency mask named \meta{mask name} (called a \emph{soft |
| 222 |
mask} in the \textsc{pdf} specification). This mask is read from the file |
| 223 |
\meta{filename}. This file should contain a grayscale image that is as |
| 224 |
large as the actual image. A white pixel in the mask will correspond to |
| 225 |
``transparent'', a black pixel to ``solid'', and gray values correspond to |
| 226 |
intermediate values. The mask must have a single ``color channel''. This |
| 227 |
means that the mask must be a ``real'' grayscale image, not an |
| 228 |
\textsc{rgb}-image in which all \textsc{rgb}-triples happen to have the |
| 229 |
same components. |
| 230 |
|
| 231 |
You can only mask images that are in a ``pixel format''. For drivers with |
| 232 |
\textsc{pdf} output, these are |.jpg| and |.png| image files; you cannot |
| 233 |
mask |.pdf| images in this way. Pixel images for the |dvips|+|ps2pdf| |
| 234 |
workflow must be provided as |.eps| or |.ps| files. Also, again, the mask |
| 235 |
file and the image file must have the same size. |
| 236 |
|
| 237 |
The following options may be given: |
| 238 |
% |
| 239 |
\begin{itemize} |
| 240 |
\item |matte=|\marg{color components} sets the so-called \emph{matte} |
| 241 |
of the actual image (strangely, this has to be specified together |
| 242 |
with the mask, not with the image itself). The matte is the color |
| 243 |
that has been used to preblend the image. For example, if the image |
| 244 |
has been preblended with a red background, then \meta{color |
| 245 |
components} should be set to |{1 0 0}|. The default is |{1 1 1}|, |
| 246 |
which is white in the rgb model. |
| 247 |
|
| 248 |
The matte is specified in terms of the parent's image color space. |
| 249 |
Thus, if the parent is a grayscale image, the matte has to be set |
| 250 |
to |{1}|. |
| 251 |
\end{itemize} |
| 252 |
% |
| 253 |
\example |
| 254 |
% |
| 255 |
\begin{codeexample}[] |
| 256 |
%% Draw a large colorful background |
| 257 |
\pgfdeclarehorizontalshading{colorful}{5cm}{color(0cm)=(red); |
| 258 |
color(2cm)=(green); color(4cm)=(blue); color(6cm)=(red); |
| 259 |
color(8cm)=(green); color(10cm)=(blue); color(12cm)=(red); |
| 260 |
color(14cm)=(green)} |
| 261 |
\hbox{\pgfuseshading{colorful}\hskip-14cm\hskip1cm |
| 262 |
\pgfimage[height=4cm]{brave-gnu-world-logo}\hskip1cm |
| 263 |
\pgfimage[height=4cm]{brave-gnu-world-logo-mask}\hskip1cm |
| 264 |
\pgfdeclaremask{mymask}{brave-gnu-world-logo-mask} |
| 265 |
\pgfimage[mask=mymask,height=4cm,interpolate=true]{brave-gnu-world-logo}} |
| 266 |
\end{codeexample} |
| 267 |
% |
| 268 |
\end{command} |
| 269 |
|
| 270 |
|
| 271 |
%%% Local Variables: |
| 272 |
%%% mode: latex |
| 273 |
%%% TeX-master: "pgfmanual" |
| 274 |
%%% End: |