diff options
author | Norbert Preining <norbert@preining.info> | 2023-01-16 03:03:27 +0000 |
---|---|---|
committer | Norbert Preining <norbert@preining.info> | 2023-01-16 03:03:27 +0000 |
commit | 6f9e1680085e7bb4d258f6f8116369d122e196e1 (patch) | |
tree | 9ac0ecb239240d1d672b188f29c1479de215074b /graphics/pgf/base/doc/pgfmanual-en-base-images.tex | |
parent | b8345f39630408bb198e7636381ce4240154ca9b (diff) |
CTAN sync 202301160303
Diffstat (limited to 'graphics/pgf/base/doc/pgfmanual-en-base-images.tex')
-rw-r--r-- | graphics/pgf/base/doc/pgfmanual-en-base-images.tex | 274 |
1 files changed, 274 insertions, 0 deletions
diff --git a/graphics/pgf/base/doc/pgfmanual-en-base-images.tex b/graphics/pgf/base/doc/pgfmanual-en-base-images.tex new file mode 100644 index 0000000000..d5ea0b5d2e --- /dev/null +++ b/graphics/pgf/base/doc/pgfmanual-en-base-images.tex @@ -0,0 +1,274 @@ +% Copyright 2019 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. + % +\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}[preamble={\usepackage{xxcolor}}] +\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}[preamble={\usepackage{xxcolor}}] +\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 that are in a ``pixel format''. For drivers with + \textsc{pdf} output, these are |.jpg| and |.png| image files; you cannot + mask |.pdf| images in this way. Pixel images for the |dvips|+|ps2pdf| + workflow must be provided as |.eps| or |.ps| files. 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: |