Debian Codegraph @

texmf-dist/doc/generic/pgf/pgfmanual-en-base-images.tex

raw
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: