Debian Codegraph @

texmf-dist/doc/latex/graphics/grfguide.tex

raw
1 %% grfguide.tex Copyright (C) 1994-1999 David Carlisle
2 %% Copyright (C) 2005-2024
3 %% The LaTeX Project and any individual authors listed elsewhere
4 %% in this file.
5 %%
6 %% This file is part of the Standard LaTeX `Graphics Bundle'.
7 %% It may be distributed under the terms of the LaTeX Project Public
8 %% License, as described in lppl.txt in the base LaTeX distribution.
9 %% Either version 1.3c or, at your option, any later version.
10 %%
11 %% This file has the LPPL maintenance status "maintained".
12
13 \begin{filecontents*}{a.eps}
14 %!PS-Adobe-2.0 EPSF-2.0
15 %%BoundingBox: 0 0 72 72
16 0 0 moveto
17 72 72 rlineto
18 72 neg 0 rlineto
19 72 72 neg rlineto
20 stroke
21 newpath
22 0 0 moveto
23 20 40 lineto
24 40 0 lineto
25 10 20 moveto
26 30 20 lineto
27 stroke
28 %%EOF
29 \end{filecontents*}
30 \documentclass{ltxguide}
31
32 %%% No driver option specified
33 %%% set up the files color.cfg and graphics.cfg for your site.
34 %%% for example:
35 %%%
36 %%% \ExecuteOptions{dvips}
37 %%%
38 \usepackage{color,graphicx,shortvrb}
39
40 %% Just as an example, and to make sure, in case some
41 %% driver option has not declared a default rule for
42 %% .ps files:
43 %\DeclareGraphicsRule{.ps}{eps}{.ps}{}
44 %\DeclareGraphicsExtensions{.pdf,.ps}
45 %% Which means:
46 %% .ps files are (to be treated as) EncapsulatedPostScript
47 %% files. The .ps file is to be read for the BoundingBox.
48 %% No `special' commands need to be applied by the driver.
49
50
51 \renewcommand\star{{\ttfamily*}}
52
53 \let\package\textsf
54
55 \newlength{\gxlen}
56 \settowidth{\gxlen}{\package{graphicx}: }
57 \newcommand\gs{\makebox[\gxlen][l]{\package{graphics}:}}
58 \newcommand\gx{\makebox[\gxlen][l]{\package{graphicx}:}}
59
60 \MakeShortVerb{\|}
61
62 \begin{document}
63 \title{Packages in the `graphics' bundle}
64 \author{D. P. Carlisle \and The \LaTeX\ Project}
65
66 \date{2025-02-26}
67
68 \maketitle
69
70 \tableofcontents
71
72 \section{Introduction}
73 This document serves as a user-manual for the packages \package{color},
74 \package{graphics}, and \package{graphicx}. Further documentation may be
75 obtained by processing the source (|dtx|) files of the individual
76 packages.
77
78 \section{Driver support}\label{drivers}
79 All these packages rely on features that are not in \TeX\ itself.
80 These features must be supplied by the `driver' used to print the
81 |dvi| file. Unfortunately not all drivers support the same features, and
82 even the internal method of accessing these extensions varies between
83 drivers. Consequently all these packages take options such as
84 `|dvips|' to specify which driver is being used.
85
86 Normally you should \emph{not} specify the driver option explicitly
87 in the document, but allow it to be defaulted automatically.
88 This allows the document to be portable between different systems.
89
90 Your \TeX\ distribution should have included |graphics.cfg| and
91 |color.cfg| configuration files to specify these defaults.
92 Standard versions of the configuration files are maintained by the
93 \LaTeX\ Project and distributed in the CTAN |graphics-cfg| collection.
94
95 For special requirements you may edit a copy of these |cfg| files
96 to set up a site default for these options. Suppose that you wish
97 the \package{color} package to always default to use specials for the
98 PostScript driver, |dvisvgm|. In that case, create a file |color.cfg|
99 containing the line:
100 \begin{quote}
101 |\ExecuteOptions{dvisvgm}|
102 \end{quote}
103 Normally you will want an identical file |graphics.cfg| to set a similar
104 default for the graphics packages.
105
106 The following driver options are declared in the packages.
107 The matching definition files (\emph{driver}|.def|)
108 are now also maintained by the \LaTeX\ project,
109 but distributed separately, in the CTAN |graphics-def| collection.
110 \begin{quote}\raggedright
111 |dvipdfmx|, |dvips|, |dvisvgm|, |luatex|, |pdftex|, |xetex|
112 \end{quote}
113
114
115 The following two options are also supported, they do not correspond
116 to separate definition files, but are essentially aliases for the
117 |dvips| option (and |monochrome| in the case of |xdvi|).
118 \begin{quote}\raggedright
119 |xdvi|, |oztex|
120 \end{quote}
121
122 The following set of options are supported by these packages
123 with associated driver files extracted from the |drivers.dtx|
124 documented source in this bundle. These are now mainly of historic
125 interest but the documented sources do contain some useful code
126 and advice if you need to produce a new definition file for a new
127 driver or \TeX\ system. |drivers.dtx| also contains documented
128 sources for older driver files that are no longer extracted.
129 \begin{quote}\raggedright
130 |dvipdf|, |dvipdfm|, |dviwin|, |dvipsone|,
131 |emtex|, |pctexps|, |pctexwin|, |pctexhp|, |pctex32|,
132 |truetex|, |tcidvi|, |vtex|
133 \end{quote}
134
135 The final driver option is an alias for |dvipsone|.
136 \begin{quote}\raggedright
137 |dviwindo|
138 \end{quote}
139
140
141 \section[Colour]{Colour\footnote{%
142 The basic \package{color} package functionality described here
143 will be enough for many uses, however a much extended version
144 is available in the contributed \package{xcolor} package, distributed
145 and maintained separately. All the color commands described here are
146 also available if you specify \package{xcolor} in your document.}%
147 }
148 The colour support is built around the idea of a system of
149 \emph{Colour Models}. The Colour models supported by a driver vary,
150 but typically include
151 \begin{description}
152 \item[rgb] Red Green Blue: A comma separated list of three numbers
153 between~0 and~1, giving the components of the colour.
154 \item[cmyk] Cyan Magenta Yellow [K]Black: A comma separated list of
155 four numbers between~0 and~1, giving the components of the colour
156 according to the additive model used in most printers.
157 \item[gray] Grey scale: a single number between~0 and~1.
158 \item[named] Colours accessed by name, e.g.\ `JungleGreen'. Not all
159 drivers support this model. The names must either be `known' to the
160 driver or added using commands described in |color.dtx|. Some drivers
161 support an extended form of the named model in which an `intensity' of
162 the colour may also be specified, so `\mbox{JungleGreen, 0.5}' would
163 denote that colour at half strength.
164 \end{description}
165 Note that the \textbf{named} model is really just given as an example
166 of a colour model that takes names rather than a numeric specification.
167 Other options may be provided locally that provide different colour
168 models, eg \textbf{pantone} (An industry standard set of colours),
169 \textbf{x11} (Colour names from the X Window System), etc. The
170 standard distribution does not currently have such models, but the
171 \textbf{named} model could be used as an example of how to define a new
172 colour model. The names used in the \textbf{named} model are those
173 suggested by Jim Hafner in his \textsf{colordvi} and \textsf{foiltex}
174 packages, and implemented originally in the |color.pro| header file for
175 the \texttt{dvips} driver.
176
177 \subsection{Package Options}
178 Most of the options to the \package{color} package just specify a
179 driver, e.g., \ |dvips|, as discussed in section~\ref{drivers}.
180
181 One special option for the \package{color} package
182 that is of interest is |monochrome.|
183 If this option is selected the colour commands are all
184 disabled so that they do not generate errors, but do not generate colour
185 either. This is useful if previewing with a previewer that can not
186 produce colour.
187
188 Three other package options control the use of the \textbf{named} model.
189 The |dvips| driver (by default) pre-defines 68 colour names. The |dvips|
190 option normally makes these names available in the \textbf{named} colour
191 model. If you do not want these names to be declared in this model
192 (Saving \TeX\ some memory) you may give the |nodvipsnames|
193 option. Conversely, if you are using another driver, you may wish to
194 add these names to the named model for that driver (especially if you
195 are processing a document originally produced on |dvips|). In this case
196 you could use the |dvipsnames| option. Lastly the |usenames| option
197 makes all names in the \textbf{named} model directly available, as
198 described below.
199
200 \subsection{Defining Colours}
201
202 The colours |black|, |white|, |red|, |green|, |blue|, |cyan|,
203 |magenta|, |yellow| should be predefined, but should you wish to mix
204 your own colours use the |\definecolor| command.
205
206 \begin{decl}
207 |\definecolor|\arg{name}\arg{model}\arg{colour specification}
208 \end{decl}
209
210
211 This defines \m{name} as a colour which can be used in later colour
212 commands. For example:
213 \begin{quote}
214 |\definecolor{light-blue}{rgb}{0.8,0.85,1}| \\
215 |\definecolor{mygrey}{gray}{0.75}|
216 \end{quote}
217 \definecolor{light-blue}{rgb}{0.8,0.85,1}
218 \definecolor{mygrey}{gray}{0.75}
219
220 Now |light-blue| and |mygrey| may be used in addition to the
221 predefined colours above.
222
223 \subsection{Using Colours}
224
225 \subsubsection{Using predefined colours}
226 The syntax for colour changes is designed to mimic font changes.
227 The basic syntax is:
228
229 \begin{decl}
230 |\color|\arg{name}
231 \end{decl}
232
233 This is a \emph{declaration}, like |\bfseries|. It changes the current
234 colour to \m{name} until the end of the current group, or
235 environment. It does not automatically start horizontal mode so typically at
236 the start of a paragraph it should be used in combination with a |\leavevmode|.
237
238 An alternative command syntax is to use a \emph{command} form that
239 takes the text to be coloured as an \emph{argument}. This is similar
240 to the font commands such as |\textbf|:
241
242 \begin{decl}
243 |\textcolor|\arg{name}\arg{text}
244 \end{decl}
245
246 The command switches to horizontal mode,
247 so the above is essentially equivalent to
248 |{\leavevmode\color|\arg{name}\emph{text}|}|. In contrast to |\textbf|,
249 the command gobbles spaces at the start of its argument, so |Hello\textcolor{red}{ World}| will output Hello\textcolor{red}{ World}.
250
251 \subsection{Using Colours in math formulas}
252
253 While |\color| and to some extent |\textcolor| can be used in
254 formulas, this is cumbersome, may lead to bad spacing, and in some
255 situations is simply not possible. For this reason we also introduce
256 |\mathcolor| which will help in this respect. The basic syntax is:
257
258 \begin{decl}
259 |\mathcolor|\arg{name}\arg{math}
260 \end{decl}
261
262 See \texttt{mathcolor.pdf} for details on this command.
263
264
265 \subsubsection{Using colour specifications directly}
266
267 \begin{decl}
268 |\color|\oarg{model}\arg{specification}\\
269 |\textcolor|\oarg{model}\arg{specification}\arg{text}\\
270 |\mathcolor|\oarg{model}\arg{specification}\arg{math}
271 \end{decl}
272
273 Normally one would predeclare all the colours used in a package, or in
274 the document preamble, but sometimes it is convenient to directly use
275 a colour without naming it first. To achieve this |\color| (and all
276 the other colour commands) take an optional argument specifying the
277 model. If this is used then the mandatory argument takes a
278 \m{colour specification} instead of a \m{name}. For example:
279 \begin{quote}
280 |\color[rgb]{1,0.2,0.3}|
281 \end{quote}
282 would directly select that colour.
283
284 This is particularly useful for accessing the \textbf{named} model:
285 \begin{quote}
286 |\color[named]{BrickRed}|
287 \end{quote}
288 selects the |dvips| colour BrickRed.
289
290 Rather than repeatedly use |[named]| you may use |\definecolor| to
291 provide convenient aliases:
292 \begin{quote}
293 |\definecolor{myred}{named}{WildStrawberry}|\ldots |\color{myred}|\kern-10pt
294 \end{quote}
295 Alternatively if you are happy to use the existing names from the
296 \textbf{named} model, you may use the |usenames| package option, which
297 effectively calls |\definecolor| on every colour in the \textbf{named}
298 model, thus allowing |\color{WildStrawberry}| in addition to
299 |\color[named]{WildStrawbery}|.
300
301 \subsection{Named Colours}
302 Using the \textbf{named} colour model has certain advantages over
303 using other colour models.
304
305 Firstly as the |dvi| file contains a request
306 for a colour by \emph{name}, the actual mix of primary colours used to
307 obtain the requested colour can be tuned to the characteristics of a
308 particular printer. In the |dvips| driver the meanings of the colour
309 names are defined in the header file |color.pro|. Users are encouraged
310 to produce different versions of this file for any printers they use. By
311 this means the same dvi file should produce colours of similar
312 appearance when printed on printers with different colour
313 characteristics.
314
315 Secondly, apart from the so called `process colours' that are produced
316 by mixing primary colours during the print process, one may want to use
317 `spot' or `custom' colours. Here a particular colour name does not
318 refer to a mix of primaries, but to a particular ink. The parts of the
319 document using this colour will be printed separately using this named
320 ink colour.
321
322 \subsection{Page Colour}
323
324
325 \begin{decl}
326 |\pagecolor|\arg{name}\\
327 |\pagecolor|\oarg{model}\arg{specification}\\
328 |\nopagecolor|
329 \end{decl}
330
331 The background colour of the whole page can be set using
332 |\pagecolor|. This takes the same argument forms as |\color| but sets
333 the background colour for the current and all subsequent pages. It is
334 a global declaration, so you need to use
335 |\nopagecolor|\NEWfeature{2014/04/23}\ to `get back to normal'.
336 If that is not supported, you may use |\pagecolor{white}| although that
337 will make a white background rather than the default transparent background.
338
339 \subsection{Box Backgrounds}
340 Two commands similar to |\fbox| produce boxes with the backgrounds
341 shaded an appropriate colour.
342
343 \begin{decl}
344 |\colorbox|\arg{name}\arg{text}\\
345 |\colorbox|\oarg{model}\arg{specification}\arg{text}\\
346 |\fcolorbox|\arg{name1}\arg{name2}\arg{text}\\
347 |\fcolorbox|\oarg{model}%
348 \arg{specification1}\arg{specification2}\arg{text}
349 \end{decl}
350
351
352 The former produces a box coloured with \emph{name}
353 \colorbox{mygrey}{like this}. The latter is similar but puts a frame of
354 colour \emph{name1} around the box coloured \emph{name2}.
355
356 These commands use the |\fbox| parameters |\fboxrule| and |\fboxsep|
357 to determine the thickness of the rule, and the size of the shaded area.
358
359 \subsection{Possible Problems}
360
361 \TeX\ was not designed with colour in mind, and producing colours
362 requires a lot of help from the driver program. Thus, depending on the
363 driver, some or all features of the \package{color} package may not be
364 available.
365
366 Some drivers do not maintain a special `colour stack'. These drivers are
367 likely to get confused if you nest colour changes, or use colours in
368 floating environments.
369
370 Some drivers do not maintain colours over a page break, so that if the
371 page breaks in the middle of a coloured paragraph, the last part of the
372 text will incorrectly be printed in black.
373
374 There is a different type of problem that will occur for all drivers.
375 Due to certain technical difficulties\footnote{At least two causes:
376 1) The presence of a \texttt{\char`\\special} \m{whatsit} prevents
377 \texttt{\char`\\addvspace} `seeing' space on the current vertical list,
378 so causing it to incorrectly add extra vertical space. 2) A
379 \m{whatsit} as the first item in a \texttt{\char`\\vtop} moves the
380 reference point of the box.}%
381 , it is possible that at points
382 where the colour changes, the \emph{spacing} is affected. For this
383 reason the |monochrome| option does not completely disable the colour
384 commands, it redefines them to write to the log file. This will have the
385 same effects on spacing, so you can produce monochrome drafts of your
386 document, at least knowing that the final spacing is being shown.
387 \section{The Graphics packages}
388 There are two graphics packages:
389 \begin{description}
390 \item[\package{graphics}] The `standard' graphics package.
391 \item[\package{graphicx}] The `extended' or `enhanced' graphics
392 package.
393 \end{description}
394 The two differ only in the format of optional arguments for the
395 commands defined. The command names, and the mandatory arguments are
396 the same for the two packages.
397
398 \subsection{Package Options}
399 As discussed in section~\ref{drivers}, the graphics packages share the
400 same `driver' options as the \package{color} package. As for colour
401 you should set up a site-default in a file,
402 |graphics.cfg|, containing the line (for |dvips|):\\
403 |\ExecuteOptions{dvips}|
404
405 The graphics packages have some other options for controlling how many
406 of the features to enable:
407 \begin{description}
408 \item[draft] Suppress all the `special' features. In particular
409 graphics files are not included (but they are still read for size
410 info) just the filename is printed in a box of the correct size.
411 \item[final] The opposite of |draft|. Useful to over-ride a global
412 |draft| option specified in the |\documentclass| command.
413 \item[hiderotate] Do not show rotated text (presumably because the
414 previewer can not rotate).
415 \item[hidescale] Do not show scaled text (presumably because the
416 previewer can not scale).
417 \item[hiresbb] Look for size specifications in |%%HiResBoundingBox|
418 lines rather than standard |%%BoundingBox| lines.%
419 \NEWfeature{1996/10/29}
420 \item[demo] Instead of inserting an image file |\includegraphics|
421 draws a 150\,pt by 100\,pt rectangle unless other dimensions are
422 specified manually.\NEWfeature{2006/02/20}
423 \end{description}
424 \subsection{Rotation}
425
426 \begin{decl}
427 \gs |\rotatebox|\arg{angle}\arg{text}\\
428 \gx |\rotatebox|\oarg{key val list}\arg{angle}\arg{text}
429 \end{decl}
430
431 This puts \emph{text} in a box, like |\mbox|, but rotates the box
432 through \emph{angle} degrees, \rotatebox{15}{like this}.
433
434 The standard version always rotates around the reference point of the
435 box, but the \package{keyval} version takes the following keys:
436
437 \begin{decl}
438 |origin|=\m{label}\\
439 |x|=\m{dimen}\\
440 |y|=\m{dimen}\\
441 |units|=\m{number}
442 \end{decl}
443
444 So you may specify both |x| and |y|, which give the coordinate of
445 the centre of rotation relative to the reference point of the box, eg
446 |[x=2mm, y=5mm]|. Alternatively, for the most common points, one may use
447 |origin| with a \emph{label} containing one or two of the following:
448 |lrctbB| (|B| denotes the baseline, as for \package{PSTricks}). For
449 example, compare a default rotation of $180^\circ$
450 \ldots\rotatebox{180}{Like This}\ldots\ to the effects gained by using
451 the |origin| key:\\
452 |[origin = c]| rotates about the centre of the box,\ldots
453 \rotatebox[origin=c]{180}{Like This}\ldots\\
454 |[origin = tr]| rotates about the top right hand corner\ldots
455 \rotatebox[origin=tr]{180}{Like This}\ldots
456
457 The |units| key allows a change from the default units of degrees
458 anti-clockwise. Give the number of units in one full anti-clockwise
459 rotation. For example:\\
460 |[units = -360]| specifies degrees clockwise.\\
461 |[units= 6.283185]| specifies radians.
462
463 \subsection{Scaling}
464
465 \subsubsection{Scaling by scale factor}
466
467 \begin{decl}
468 |\scalebox|\arg{h-scale}\oarg{v-scale}\arg{text}
469 \end{decl}
470
471 Again this is basically like |\mbox| but scales the \emph{text}.
472 If \emph{v-scale} is not specified it defaults to \emph{h-scale}.
473 If it is specified the text is distorted as the horizontal and
474 vertical stretches are different, \scalebox{3}[.7]{Like This}.
475
476
477 \begin{decl}
478 |\reflectbox|\arg{text}
479 \end{decl}
480
481 An abbreviation for |\scalebox{-1}[1]|\arg{text}.
482
483 \subsubsection{Scaling to a requested size}
484
485 \begin{decl}
486 |\resizebox|\star\arg{h-length}\arg{v-length}\arg{text}
487 \end{decl}
488
489 Scale \emph{text} so that the width is \emph{h-length}.
490 If |!| is used as either length argument, the other argument is used
491 to determine a scale factor that is used in both directions.
492
493 As normal for \LaTeXe\ box length arguments, |\height|,
494 |\width|, |\totalheight|, |\depth| may be used to refer to the
495 original size of the box.
496
497 Normally \emph{v-length} refers to the height of the box, but in the
498 star form, |\resizebox*|, it refers to the `height + depth'.
499
500 |\resizebox{1in}{\height}{Some text}|:
501 \resizebox{1in}{\height}{Some text}
502
503 |\resizebox{1in}{!}{Some text}|:
504 \resizebox{1in}{!}{Some text}
505
506 |\resizebox{!}{20pt}{Q} \resizebox*{!}{20pt}{Q}|:
507 \resizebox{!}{20pt}{Q} \resizebox*{!}{20pt}{Q}
508
509 \subsection{Including Graphics Files}
510 The functions for graphics inclusion try to give the same user syntax
511 for including any kind of graphics file that can be understood by the
512 driver. This relies on the file having an extension that identifies
513 the file type. The `driver options' will define a collection of file
514 extensions that the driver can handle, although this list may be
515 extended using the declarations described below.
516
517 If the file's extension is unknown to the driver, the system may try a
518 default file type. The PostScript driver files set this default to be
519 |eps| (PostScript), but this behaviour may be customised if other
520 defaults are required.
521
522 \begin{decl}
523 \gs |\includegraphics|\star\oarg{llx,lly}\oarg{urx,ury}\arg{file}\\
524 \gx |\includegraphics|\star\oarg{key val list}\arg{file}
525 \end{decl}
526 Include a graphics file.
527
528 If \star\ is present, then the graphic is `clipped' to the size
529 specified. If \star\ is omitted, then any part of the graphic that is
530 outside the specified `bounding box' will over-print the surrounding
531 text.
532
533 If the optional arguments are omitted, then the size of the graphic
534 will be determined by reading an external file as described below.
535
536 \paragraph{\package{graphics} version}
537 If \oarg{urx,ury} is present, then it should specify the coordinates
538 of the top right corner of the image, as a pair of \TeX\ dimensions.
539 If the units are omitted they default to |bp|. So |[1in,1in]| and
540 |[72,72]| are equivalent. If only one optional argument appears, the
541 lower left corner of the image is assumed to be at |[0,0]|. Otherwise
542 \oarg{llx,lly} may be used to specify the coordinates of this point.
543
544 \paragraph{\package{graphicx} version}
545 Here the star form is just for compatibility with the standard
546 version. It just adds |clip| to the list of keys specified.
547 (Also, for increased compatibility, if \emph{two} optional arguments are
548 used, the `standard' version of |\includegraphics| is always used, even
549 if the \package{graphicx} package is loaded.)
550
551 The allowed keys are listed below.
552 \begin{description}
553 \item[bb] The argument should be four dimensions, separated by spaces.
554 These denote the `Bounding Box' of the printed region within
555 the file.
556 \item[bbllx,bblly,bburx,bbury] Set the bounding box. Mainly for
557 compatibility with older packages.
558 Specifying |bbllx=a,bblly=b,bburx=c,bbury=d|
559 is equivalent to specifying |bb = a b c d|.
560 \item[natwidth,natheight] Again an alternative to |bb|.
561 |natheight=h,natwidth=w| is equivalent to |bb = 0 0 h w|.
562 \item[hiresbb]\NEWfeature{1996/10/29}
563 Boolean valued key. If set to |true| (just specifying |hiresbb|
564 is equivalent to |hiresbb=true|) then \TeX\ will look for
565 |%%HiResBoundingBox| lines rather than |%%BoundingBox|. It may be set
566 to |false| to overrule a default setting of |true| set by the
567 |hiresbb| package option.
568 \item[pagebox]\NEWfeature{2017/06/01}
569 PDF files do not have BoundingBox but may specify up to four predefined
570 rectangles.
571
572 |MediaBox|: the boundaries of the physical medium.
573 |CropBox|: the region to which the contents of the page are to be
574 clipped when displayed.
575 |BleedBox|: the region to which the contents of the
576 page should be clipped in production.
577 |TrimBox|: the intended dimensions of the finished page.
578 |ArtBox|: the extent of the page's meaningful content.
579
580 The driver will set the image size based on |CropBox| if present,
581 otherwise it will not use one of the others,
582 with a driver-defined order of preference.
583 |MediaBox| is always present.
584
585 The |pagebox| key may be used to specify which bounding box specification to use.
586 The value should be one of
587 |mediabox|, |cropbox|, |bleedbox|, |trimbox|, |artbox|.
588 \item[viewport]\NEWfeature{1995/06/01}
589 The |viewport| key takes four arguments, just like
590 |bb|. However in this case the values are taken relative to the
591 origin specified by the bounding box in the file. So to `view' the
592 1in square in the bottom left hand corner of the area specified by
593 the bounding box, use the argument |viewport=0 0 72 72|.
594 \item[trim]\NEWfeature{1995/06/01}
595 Similar to viewport, but here the four lengths specify the
596 amount to remove or add to each side. |trim= 1 2 3 4| `crops' the
597 picture by 1bp at the left, 2bp at the bottom, 3bp on the right and
598 4bp at the top.
599 \item[angle] Rotation angle.
600 \item[origin]\NEWfeature{1995/09/28}
601 Origin for rotation. See the documentation of |\rotatebox|.
602 \item[width] Required width. The
603 graphic is scaled to this width. The special value |!| can be used
604 to (re)set the width to the natural width.
605 \item[height] Required height. The
606 graphic is scaled to this height. The special value |!| can be used
607 to (re)set the height to the natural height.
608 \item[totalheight]\NEWfeature{1995/06/01}
609 Specify the total height (height $+$ depth) of the figure.
610 This will differ from the `height' if rotation has occurred.
611 In particular if the figure has been rotated by $-90^\circ$
612 then it will have zero height but large depth. The special value |!| can be used
613 to (re)set the totalheight to the natural totalheight.
614 \item[keepaspectratio]\NEWfeature{1995/09/27}
615 Boolean valued key like `clip'.
616 If set to true then specifying both `width' and `height' (or
617 `totalheight') does not distort the figure but scales such that
618 neither of the specified dimensions is \emph{exceeded}.
619 \item[scale] Scale factor.
620 \item[clip] Either `true' or `false' (or no value, which is equivalent
621 to `true'). Clip the graphic to the bounding box.
622 \item[draft] A boolean valued key, like `clip'. Locally switches to
623 draft mode.
624 \item[type] Specify the graphics type.
625 \item[ext] Specify the file extension. This should \emph{only} be
626 used in conjunction with |type|.
627 \item[read] Specify the file extension of the `read file'. This
628 should \emph{only} be used in conjunction with |type|.
629 \item[command] Specify any command to be applied to the file. This
630 should \emph{only} be used in conjunction with |type|.
631 \item[quiet]\NEWfeature{2017/06/01}
632 Skip writing information to the log.
633 \item[page]\NEWfeature{2017/06/01}
634 Page of a multi-page PDF file. (By default the first page will be used.)
635 \item[interpolate]\NEWfeature{2017/06/01}
636 Enable/disable interpolation of bitmap images by the viewer.
637 \item[alt]\NEWfeature{2021/09/16}
638 Alternative text for accessibility uses. By default this key is not used
639 but users are encouraged to add descriptive text here that may be used in
640 tagged PDF or as the |alt| attribute in conversions to HTML.
641 \item[actualtext]\NEWfeature{2024/12/31}
642 ActualText text for accessibility uses. By default this key is not used
643 but users are encouraged to add text here that may be used in
644 tagged PDF or as the text to use in formats that do not use the image.
645 \item[artifact]\NEWfeature{2024/12/31}
646 Boolean to mark the graphic as an artifact for accessibility uses. By default this key is not used
647 but users are encouraged to flag decorative or other non structural images as an artifact for
648 tagged PDF.
649 \end{description}
650
651 For the keys specifying the original size (i.e., the bounding box,
652 trim and viewport keys) the units can be omitted, in
653 which case bp (i.e., PostScript points) are assumed.
654
655 The first seven keys specify the original size of the image. This size
656 needs to be specified in the case that the file can not be read by
657 \TeX, or it contains an incorrect size `BoundingBox' specification.
658
659 |bbllx|\ldots\ |\bbury| are mainly for compatibility for older
660 packages.\\
661 |bbllx=a, bblly=b, bburx=c, bbury=d|\\
662 is equivalent to\\
663 |bb = a b c d|.
664
665 |natheight| and |natwidth| are just shorthands for setting the lower
666 left coordinate to 0 0 and the upper right coordinate to the specified
667 width and height.
668
669 The next few keys specify any scaling or rotation to be applied to the
670 image. To get these effects using the standard package, the
671 |\includegraphics| call must be placed inside the argument of a
672 |\rotatebox| or |\scalebox| command.
673
674 The keys are read left-to-right, so |[angle=90, height=1in]| means
675 rotate by 90 degrees, and then scale to a height of 1in.
676 |[height=1in, angle=90]| would result in a final \emph{width} of 1in.
677
678 If the \textsf{calc} package is also loaded the lengths may use
679 \textsf{calc} syntax, for instance to specify a width of 2\,cm
680 less than the text width: |[width=\textwidth-2cm]|.
681
682 \TeX\ leaves the space specified either in the file, or in
683 the optional arguments. If any part of the image is actually outside
684 this area, it will by default overprint the surrounding text.
685 If the star form is used, or |clip| specified, any part of the image
686 outside this area will not be printed.
687
688 The last four keys suppress the parsing of the filename. If they are
689 used, the main \emph{file} argument should not have the file
690 extension. They correspond to the arguments of |\DeclareGraphicsRule|
691 described below.
692
693 To see the effect that the various options have consider the file
694 |a.ps|. This file contains the bounding box specification
695 \begin{verbatim}
696 %%BoundingBox:0 0 72 72
697 \end{verbatim}
698 That is, the printed region consists of a one-inch square, in
699 the bottom left hand corner of the paper.
700
701 In all the following examples the input will be of the form
702 \begin{verbatim}
703 left---\fbox{\includegraphics{a}}---right
704 \end{verbatim}
705 With different options supplied to |\includegraphics|.
706
707 No optional argument.\\
708 left---\fbox{\includegraphics{a.eps}}---right
709
710 \gs |\scalebox{0.5}{\includegraphics{a}}|\\
711 \gx |\includegraphics[scale=.5]{a}|\\
712 left---\fbox{\includegraphics[scale=.5]{a.eps}}---right
713
714 \gs |\includegraphics[15,10][35,45]{a}}|\\
715 \gx |\includegraphics[viewport= 15 10 35 45]{a}|\\
716 left---\fbox{\includegraphics[viewport= 15 10 35 45]{a.eps}}---right
717
718 \gs |\includegraphics*[15,10][35,45]{a}}|\\
719 \gx |\includegraphics[viewport= 15 10 35 45,clip]{a}|\\
720 left---\fbox{\includegraphics[viewport= 15 10 35 45,clip]{a.eps}}---right
721
722 \gs |\scalebox{0.5}{\includegraphics{a}}|
723 and |draft| option.\\
724 \gx |\includegraphics[scale=.5, draft]{a}|\\
725 left---\fbox{\includegraphics[scale=.5, draft]{a.eps}}---right
726
727 \subsection{Other commands in the \package{graphics} package}
728
729 \begin{decl}
730 |\graphicspath|\arg{dir-list}
731 \end{decl}
732 This optional declaration may be used to specify a list of directories
733 in which to search for graphics files. The format is the same as for
734 the \LaTeXe\ primitive |\input@path|. A list of directories, each in a
735 |{}| group (even if there is only one in the list). For example:\\
736 |\graphicspath{{eps/}{tiff/}}|\\
737 would cause the system to look in the subdirectories |eps| and |tiff|
738 of the current directory. (All modern \TeX{} systems use |/|
739 as the directory separator, even on Windows.)
740
741 The default setting of this path is
742 |\input@path|, so that graphics files will be found wherever \TeX\
743 files are found.
744
745 \begin{decl}
746 |\DeclareGraphicsExtensions|\arg{ext-list}
747 \end{decl}
748 \NEWdescription{1994/12/01}
749 This specifies the behaviour of the system when no file extension
750 is specified in the argument to |\includegraphics|.
751 \arg{ext-list} should be a comma separated list of file extensions.
752 (White space is ignored between the entries.)
753 A file name is produced by appending one extension from the list.
754 If a file is found, the system acts as if that extension had been
755 specified. If not, the next extension in \emph{ext-list} is tried.
756
757
758 Note that if the extension is not specified in the |\includegraphics|
759 command, the graphics file must exist at the time \LaTeX\ is run, as
760 the existence of the file is used to determine which extension from
761 the list to choose. However if a file extension \emph{is} specified,
762 e.g.\ |\includegraphics{a.eps}| instead of |\includegraphics{a}|, then
763 the graphics file need not exist at the time \LaTeX\ is used. (In
764 particular it may be created on the fly by the \m{command}
765 specified in the |\DeclareGraphicsRule| command described below.)
766 \LaTeX\ does however need to be able to determine the size of the
767 image so this size must be specified in arguments, or the `read file'
768 must exist at the time \LaTeX\ is used.
769
770 \begin{decl}
771 |\DeclareGraphicsRule|\arg{ext}\arg{type}\arg{read-file}\arg{command}
772 \end{decl}
773 Any number of these declarations can be made. They determine how the
774 system behaves when a file with extension \emph{ext} is specified.
775 (The extension may be specified explicitly or, if the argument to
776 |\includegraphics| does not have an extension, it may be a default
777 extension from the \emph{ext-list} specified with
778 |\DeclareGraphicsExtensions|.)
779
780 \emph{ext} is the file extension for which this rule applies. As a special
781 case, \emph{ext} may be given as |*| to denote the default behaviour for
782 all undeclared extensions (see the example below).
783
784 \emph{type} is the `type' of file involved. All files of the same type
785 will be input with the same internal command (which must be defined in
786 a `driver file'). For example files with extensions |ps|, |eps|,
787 |ps.gz| may all be classed as type |eps|.
788
789 \emph{read-file} determines the extension of the file that should be
790 read to determine size information. It may be the same as \emph{ext}
791 but it may be different, for example |.ps.gz| files are not readable
792 easily by \TeX, so you may want to put the bounding box information in
793 a separate file with extension |.ps.bb|. If \emph{read-file} is empty,
794 |{}|, then the system will not try to locate an external file for size
795 info, and the size must be specified in the arguments of
796 |\includegraphics|. If the driver file specifies a procedure for
797 reading size files for \emph{type}, that will be used, otherwise the
798 procedure for reading |eps| files will be used. Thus the size of
799 bitmap files may be specified in a file with a PostScript style
800 |%%BoundingBox| line, if no other specific format is available.
801
802 As a special case |*| may be used to denote the
803 same extension as the graphic file. This is mainly of use in
804 conjunction with using |*| as the extension, as in that case the
805 particular graphic extension is not known. For example
806 \begin{verbatim}
807 \DeclareGraphicsRule{*}{eps}{*}{}
808 \end{verbatim}
809 This would declare a default rule, such that all unknown extensions
810 would be treated as EPS files, and the graphic file would be read for
811 a BoundingBox comment.
812
813 \emph{command} is usually empty, but if non empty it may hold \TeX{} code
814 to modify the name of the file as passed to the back end file inclusion
815 commands. Within this argument, |#1| may be
816 used to denote the original filename. Very early releases of the |dvips| code
817 used this mechanism to support compressed EPS files, however for some years
818 dvips has directly supported uncompression.
819
820 \subsection{Global setting of keys}
821
822 Most of the \package{keyval} keys used in the \package{graphicx} package
823 may also be set using the command |\setkeys| provided by the
824 \package{keyval} package.%
825 \footnote{\texttt{clip}, \texttt{scale} and \texttt{angle} may not be set via
826 \texttt{\string\setkeys} prior to calling
827 \texttt{\string\includegraphics}.}
828
829 For instance, suppose you wanted all the files to be included in the
830 current document to be scaled to 75\% of the width of the lines of text,
831 then one could issue the following command:\\
832 |\setkeys{Gin}{width=0.75\textwidth}|\\
833 Here `|Gin|' is the name used for the \package{keyval} keys associated
834 with `Graphics inclusion'. All following
835 |\includegraphics| commands (within the same group or environment) will
836 act as if |[width=0.75\textwidth]| had been specified, in addition to
837 any other key settings actually given in the optional argument.
838
839 Similarly to make all |\rotatebox| arguments take an argument in
840 radians, one just needs to specify:\\
841 |\setkeys{Grot}{units=6.28318}|
842
843 \subsection{Compatibility between \package{graphics} and
844 \package{graphicx}}
845
846 For a document author, there are not really any problems of
847 compatibility between the two packages. You just choose the interface
848 that you personally prefer, and then use the appropriate package.
849
850 For a package or class writer the situation is slightly
851 different. Suppose that you are writing a letter class that needs to
852 print a company logo as part of the letterhead.
853
854 As the author of the class you may want to give the users the
855 possibility of using either interface in their letters (should they
856 need to include any further graphics into the letter body).
857 In this case the class should load the \package{graphics} package (not
858 \package{graphicx}, as this would commit any users of the class to the
859 \package{keyval} interface). The logo should be included with
860 |\includegraphics| either with \emph{no} optional argument (if the
861 correct size information is in the file) or \emph{both} optional
862 arguments otherwise.
863 Do not use the \emph{one} optional argument form, as the meaning of this
864 argument would change (and generate errors) if the user were to load
865 \package{graphicx} as well as your class.
866
867 \section{Remaining packages in the graphics bundle}
868
869 \subsection{Epsfig}
870 This is a small package, essentially a `wrapper' around the
871 \package{graphicx} package, defining a command |\psfig| which has the
872 syntax\\
873 |\psfig{file=xxx,...}| rather than |\includegraphics[...]{xxx}|.\\
874 It also has a few more commands to make it slightly more compatible with
875 the old \LaTeX~2.09 style of the same name.
876
877 \subsection{Rotating}
878 An extension package to \package{graphicx}, mainly used for providing
879 rotated float environments.
880
881 \subsection{Trig}
882 The trig package is not intended to be used directly in documents. It
883 calculates sine, cosine and tangent trigonometric functions. These
884 are used to calculate the space taken up by a rotated box. This
885 package is also used by the |fontinst| program which converts
886 PostScript files to a form usable by \TeX.
887
888 As well as being used as a \LaTeX\ package, the macros may be extracted
889 with the \package{docstrip} options \texttt{plain,package}. In this case
890 the \LaTeX\ package declarations are omitted from the file, and the
891 macros may be directly used as part of another macro file (they work
892 with any format based on plain \TeX).
893
894 \subsection{Keyval}
895 The \package{keyval} package is intended to be used by other
896 packages. It provides a generic way of setting `keys' as used by the
897 \package{graphicx} package, and splitting up the comma separated lists
898 of \m{key}~=~\m{value} pairs.
899
900 Like the \package{trig} package, these macros may be extracted and used
901 as part of another macro file, based on plain \TeX, as well as the
902 standard use as a \LaTeX\ package.
903
904 By default an undeclared key will generate an error.
905 If however the option \texttt{unknownkeysallowed} is used, then
906 unknown keys will be silently ignored (leaving a message in the log
907 file). This option is also accepted by the \textsf{graphicx} package.
908
909 \iffalse
910
911 \subsection{Pstcol}
912 \package{PSTricks}, by Timothy Van Zandt is an immensely powerful
913 package that enables a very full featured interface between PostScript
914 and \TeX. Unfortunately the colour support in \package{PSTricks} is
915 slightly incompatible with the colour mechanism defined in the
916 \package{color} package. The \package{pstcol} package is a (hopefully
917 temporary) package that modifies a very small number of internal
918 PSTricks functions, to remove this incompatibility. If
919 \package{pstricks} is loaded via this package, you may use any colours
920 defined by \package{color} package commands within \package{pstricks}
921 commands, and vice versa.
922
923 \fi
924
925 \subsection{Lscape}
926 The \package{lscape} package requires and takes the same options
927 as the \package{graphics} package. It defines a |landscape| environment
928 within which page bodies are rotated through 90 degrees. The page head
929 and foot are not affected, they appear in the standard (portrait)
930 position.
931 \end{document}