1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
|
% Copyright 2003 by Till Tantau <tantau@cs.tu-berlin.de>.
%
% This program can be redistributed and/or modified under the terms
% of the LaTeX Project Public License Distributed from CTAN
% archives in directory macros/latex/base/lppl.txt.
\section{Declaring and Using Images}
\label{section-images}
This section describes the |pgfbaseimage| package.
\begin{package}{pgfbaseimage}
This package offers an abstraction of the image inclusion
process. It is loaded automatically by |pgf|, but you can load it
manually if you have only included |pgfcore|.
\end{package}
\subsection{Overview}
To be quite frank, \LaTeX's |\includegraphics| is designed better than
|pgfbaseimage|. 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 ``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}{pgf-tu-logo}
\pgfdeclareimage[interpolate=true,width=1cm,height=1cm]{image2}{pgf-tu-logo}
\pgfdeclareimage[interpolate=true,height=1cm]{image3}{pgf-tu-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 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
names \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.
\begin{codeexample}[]
\pgfdeclareimage[interpolate=true,width=1cm,height=1cm]{image1}{pgf-tu-logo}
\pgfdeclareimage[interpolate=true,width=1cm]{image2}{pgf-tu-logo}
\pgfdeclareimage[interpolate=true,height=1cm]{image3}{pgf-tu-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 color mixin environment.
\begin{codeexample}[]
\pgfdeclareimage[interpolate=true,width=1cm,height=1cm]
{image1.!25!white}{pgf-tu-logo.25}
\pgfdeclareimage[interpolate=true,width=1cm]
{image2.25!white}{pgf-tu-logo.25}
\pgfdeclareimage[interpolate=true,height=1cm]
{image3.white}{pgf-tu-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]{pgf-tu-logo}}
\pgftext[at=\pgfpoint{1cm}{3cm},left,base]
{\pgfimage[interpolate=true,width=1cm]{pgf-tu-logo}}
\pgftext[at=\pgfpoint{1cm}{1cm},left,base]
{\pgfimage[interpolate=true,height=1cm]{pgf-tu-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]{pgf-apple}\hskip1cm
\pgfimage[height=4cm]{pgf-apple.mask}\hskip1cm
\pgfdeclaremask{mymask}{pgf-apple.mask}
\pgfimage[mask=mymask,height=4cm,interpolate=true]{pgf-apple}}
\end{codeexample}
\end{command}
%%% Local Variables:
%%% mode: latex
%%% TeX-master: "pgfmanual"
%%% End:
|
