summaryrefslogtreecommitdiff
path: root/macros/latex-dev/required/graphics/grfguide.tex
blob: 8df07c5a6a614c8f00766b8609bf852a3893e84c (plain)
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
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
%% grfguide.tex Copyright (C) 1994 1995 1996 1998 1999 David Carlisle
%%              Copyright (C) 2005-2020 David Carlisle, LaTeX3 Project
%%
%% This file is part of the Standard LaTeX `Graphics Bundle'.
%% It may be distributed under the terms of the LaTeX Project Public
%% License, as described in lppl.txt in the base LaTeX distribution.
%% Either version 1.3c or, at your option, any later version.
%%
%% This file has the LPPL maintenance status "maintained".

\begin{filecontents*}{a.eps}
%!PS-Adobe-2.0 EPSF-2.0
%%BoundingBox: 0 0 72 72
0 0 moveto
72 72 rlineto
72 neg 0 rlineto
72 72 neg rlineto
stroke
newpath
0 0 moveto
20 40 lineto
40 0 lineto
10 20 moveto
30 20 lineto
stroke
%%EOF
\end{filecontents*}
\documentclass{ltxguide}

%%% No driver option specified
%%% set up the files color.cfg and graphics.cfg for your site.
%%% for example:
%%%
%%% \ExecuteOptions{dvips}
%%%
\usepackage{color,graphicx,shortvrb}

%% Just as an example, and to make sure, in case some
%% driver option has not declared a default rule for
%% .ps files:
%\DeclareGraphicsRule{.ps}{eps}{.ps}{}
%\DeclareGraphicsExtensions{.pdf,.ps}
%% Which means:
%% .ps files are (to be treated as) EncapsulatedPostScript
%% files. The .ps file is to be read for the BoundingBox.
%% No `special' commands need to be applied by the driver.


\renewcommand\star{{\ttfamily*}}

\let\package\textsf

\newlength{\gxlen}
\settowidth{\gxlen}{\package{graphicx}: }
\newcommand\gs{\makebox[\gxlen][l]{\package{graphics}:}}
\newcommand\gx{\makebox[\gxlen][l]{\package{graphicx}:}}

\MakeShortVerb{\|}

\begin{document}
\title{Packages in the `graphics' bundle}
\author{D. P. Carlisle \and The \LaTeX3 Project}
\date{2020-08-21}

\maketitle

\tableofcontents

\section{Introduction}
This document serves as a user-manual for the packages \package{color},
\package{graphics}, and \package{graphicx}. Further documentation may be
obtained by processing the  source (|dtx|) files of the individual
packages.

\section{Driver support}\label{drivers}
All these packages rely on features that are not in \TeX\ itself.
These features must be supplied by the `driver' used to print the
|dvi| file. Unfortunately not all drivers support the same features, and
even the internal method of accessing these extensions varies between
drivers. Consequently all these packages take options such as
`|dvips|' to specify which driver is being used.

Normally you should \emph{not} specify the driver option explicitly
in the document, but allow it to be defaulted automatically.
This allows the document to be portable between different systems.

Your \TeX\ distribution should have included |graphics.cfg| and
|color.cfg| configuration files to specify these defaults.
Standard versions of the configuration files are maintained by the
\LaTeX\ Project and distributed in the CTAN |graphics-cfg| collection.

For special requirements you may edit a copy of these |cfg| files
to set up a site default for these options. Suppose that you wish
the \package{color} package to always default to use specials for the
PostScript driver, |dvisvgm|. In that case, create a file |color.cfg|
containing the line:\\
|\ExecuteOptions{dvisvgm}|\\
Normally you will want an identical file |graphics.cfg| to set a similar
default for the graphics packages.

The following driver options are declared in the packages.
The matching definition files (\emph{driver}|.def|)
are now also maintained by the \LaTeX\ project,
but distributed separately, in the CTAN |graphics-def| collection.
\begin{quote}\raggedright
  |dvipdfmx|, |dvips|, |dvisvgm|, |luatex|, |pdftex|, |xetex|
\end{quote}


The following two options are also supported, they do not correspond
to separate definition files, but are essentially aliases for the
|dvips| option (and |monochrome| in the case of |xdvi|).
\begin{quote}\raggedright
 |xdvi|,  |oztex|
\end{quote}

The following set of options are supported by these packages
with associated driver files extracted from the |drivers.dtx|
documented source in this bundle. These are now, mainly of historic
interest but the documented sources do contain some useful code
and advice if you need to produce a new definition file for a new
driver or \TeX\ system. |drivers.dtx| also contains documented
sources for older driver files that are no longer extracted.
\begin{quote}\raggedright
 |dvipdf|, |dvipdfm|, |dviwin|, |dvipsone|,
 |emtex|, |pctexps|, |pctexwin|,  |pctexhp|, |pctex32|,
 |truetex|, |tcidvi|, |vtex|
\end{quote}

The final driver option is an alias for |dvipsone|.
\begin{quote}\raggedright
  |dviwindo|
\end{quote}


\section[Colour]{Colour\footnote{%
The basic \package{color} package functionality described here
will be enough for many uses, however a much extended version
is available in the contributed \package{xcolor} package, distributed
and maintained separately. All the color commands described here are
also available if you specify \package{xcolor} in your document.}%
}
The colour support is built around the idea of a system of
\emph{Colour Models}. The Colour models supported by a driver vary,
but typically include
\begin{description}
\item[rgb] Red Green Blue: A comma separated list of three numbers
  between~0 and~1, giving the components of the colour.
\item[cmyk] Cyan Magenta Yellow [K]Black:  A comma separated list of
  four numbers between~0 and~1, giving the components of the colour
  according to the additive model used in most printers.
\item[gray] Grey scale: a single number between~0 and~1.
\item[named] Colours accessed by name, e.g.\ `JungleGreen'. Not all
  drivers support this model. The names must either be `known' to the
  driver or added using commands described in |color.dtx|. Some drivers
  support an extended form of the named model in which an `intensity' of
  the colour may also be specified, so `\mbox{JungleGreen, 0.5}' would
  denote that colour at half strength.
\end{description}
Note that the \textbf{named} model is really just given as an example
of a colour model that takes names rather than a numeric specification.
Other options may be provided locally that provide different colour
models, eg \textbf{pantone} (An industry standard set of colours),
\textbf{x11} (Colour names from the X Window System), etc. The
standard distribution does not currently have such models, but the
\textbf{named} model could be used as an example of how to define a new
colour model. The names used in the \textbf{named} model are those
suggested by Jim Hafner in his \textsf{colordvi} and \textsf{foiltex}
packages, and implemented originally in the |color.pro| header file for
the \texttt{dvips} driver.

\subsection{Package Options}
Most of the options to the \package{color} package just specify a
driver, e.g., \ |dvips|, as discussed in section~\ref{drivers}.

One special option for the \package{color} package
that is of interest is |monochrome.|
If this option is selected the colour commands are all
disabled so that they do not generate errors, but do not generate colour
either. This is useful if previewing with a previewer that can not
produce colour.

Three other package options control the use of the \textbf{named} model.
The |dvips| driver (by default) pre-defines 68 colour names. The |dvips|
option normally makes these names available in the \textbf{named} colour
model. If you do not want these names to be declared in  this model
(Saving \TeX\ some memory) you may give the |nodvipsnames|
option. Conversely, if you are using another driver, you may wish to
add these names to the named model for that driver (especially if you
are processing a document originally produced on |dvips|). In this case
you could use the |dvipsnames| option. Lastly the |usenames| option
makes all names in the \textbf{named} model directly available, as
described below.

\subsection{Defining Colours}

The colours |black|, |white|, |red|, |green|, |blue|, |cyan|,
|magenta|, |yellow| should be predefined, but should you wish to mix
your own colours use the |\definecolor| command.

\begin{decl}
|\definecolor|\arg{name}\arg{model}\arg{colour specification}
\end{decl}


This defines \m{name} as a colour which can be used in later colour
commands. For example
\begin{verbatim}
\definecolor{light-blue}{rgb}{0.8,0.85,1}
\definecolor{mygrey}{gray}{0.75}
\end{verbatim}
\definecolor{light-blue}{rgb}{0.8,0.85,1}
\definecolor{mygrey}{gray}{0.75}

Now |light-blue| and |mygrey| may be used in addition to the
predefined colours above.

\subsection{Using Colours}

\subsubsection{Using predefined colours}
The syntax for colour changes is designed to mimic font changes.
The basic syntax is:

\begin{decl}
|\color|\arg{name}
\end{decl}

This is a \emph{declaration}, like |\bfseries| It changes the current
colour to \m{name} until the end of the current group or
environment.

An alternative command syntax is to use a \emph{command} form that
takes the text to be coloured as an \emph{argument}. This is similar
to the font commands such as |\textbf|:

\begin{decl}
|\textcolor|\arg{name}\arg{text}
\end{decl}


So the above is essentially equivalent to
|{\color|\arg{name}\emph{text}|}|.

\subsubsection{Using colour specifications directly}


\begin{decl}
|\color|\oarg{model}\arg{specification}\\
|\textcolor|\oarg{model}\arg{specification}\arg{text}
\end{decl}

Normally one would predeclare all the colours used in a package, or in
the document preamble, but sometimes it is convenient to directly use
a colour without naming it first. To achieve this |\color| (and all
the other colour commands) take an optional argument specifying the
model. If this is used then the mandatory argument takes a
\m{colour specification} instead of a \m{name}. For example:\\
|\color[rgb]{1,0.2,0.3}|\\
would directly select that colour.

This is particularly useful for accessing the \textbf{named} model:\\
|\color[named]{BrickRed}| selects the |dvips| colour BrickRed.

Rather than repeatedly use |[named]| you may use |\definecolor| to
provide convenient aliases:\\
|\definecolor{myred}{named}{WildStrawberry}|
     \ldots\ |\color{myred}|\ \ldots

Alternatively if you are happy to use the existing names from the
\textbf{named} model, you may use the |usenames| package option, which
effectively calls |\definecolor| on every colour in the \textbf{named}
model, thus allowing |\color{WildStrawberry}| in addition to
|\color[named]{WildStrawbery}|.

\subsection{Named Colours}
Using the \textbf{named} colour model has certain advantages over
using other colour models.

Firstly as the |dvi| file contains a request
for a colour by \emph{name}, the actual mix of primary colours used to
obtain the requested colour can be tuned to the characteristics of a
particular printer. In the |dvips| driver the meanings of the colour
names are defined in the header file |color.pro|. Users are encouraged
to produce different versions of this file for any printers they use. By
this means the same dvi file should produce colours of similar
appearance when printed on printers with different colour
characteristics.

Secondly, apart from the so called `process colours' that are produced
by mixing primary colours during the print process, one may want to use
`spot' or `custom' colours. Here a particular colour name does not
refer to a mix of primaries, but to a particular ink. The parts of the
document using this colour will be printed separately using this named
ink colour.

\subsection{Page Colour}


\begin{decl}
|\pagecolor|\arg{name}\\
|\pagecolor|\oarg{model}\arg{specification}\\
|\nopagecolor|
\end{decl}

The background colour of the whole page can be set using
|\pagecolor|. This takes the same argument forms as |\color| but sets
the background colour for the current and all subsequent pages. It is
a global declaration, so you need to  use
|\nopagecolor|\NEWfeature{2014/04/23}\ to `get back to normal'.
If that is not supported, you may use |\pagecolor{white}| although that
will make a white background rather than the default transparent background.

\subsection{Box Backgrounds}
Two commands similar to |\fbox| produce boxes with the backgrounds
shaded an appropriate colour.

\begin{decl}
|\colorbox|\arg{name}\arg{text}\\
|\colorbox|\oarg{model}\arg{specification}\arg{text}\\
|\fcolorbox|\arg{name1}\arg{name2}\arg{text}\\
|\fcolorbox|\oarg{model}%
            \arg{specification1}\arg{specification2}\arg{text}
\end{decl}


The former produces a box coloured with \emph{name}
\colorbox{mygrey}{like this}. The latter is similar but puts a frame of
colour \emph{name1} around the box coloured \emph{name2}.

These commands use the |\fbox| parameters |\fboxrule| and |\fboxsep|
to determine the thickness of the rule, and the size of the shaded area.

\subsection{Possible Problems}

\TeX\ was not designed with colour in mind, and producing colours
requires a lot of help from the driver program. Thus, depending on the
driver, some or all features of the \package{color} package may not be
available.

Some drivers do not maintain a special `colour stack'. These drivers are
likely to get confused if you nest colour changes, or use colours in
floating environments.

Some drivers do not maintain colours over a page break, so that if the
page breaks in the middle of a coloured paragraph, the last part of the
text will incorrectly be printed in black.

There is a different type of problem that will occur for all drivers.
Due to certain technical difficulties\footnote{At least two causes:
1) The presence of a \texttt{\char`\\special} \m{whatsit} prevents
\texttt{\char`\\addvspace} `seeing' space on the current vertical list,
so causing it to incorrectly add extra vertical space. 2) A
\m{whatsit} as the first item in a \texttt{\char`\\vtop} moves the
reference point of the box.}%
, it is possible that at points
where the colour changes, the \emph{spacing} is affected. For this
reason the |monochrome| option does not completely disable the colour
commands, it redefines them to write to the log file. This will have the
same effects on spacing, so you can produce monochrome drafts of your
document, at least knowing that the final spacing is being shown.
\section{The Graphics packages}
There are two graphics packages:
\begin{description}
\item[\package{graphics}] The `standard' graphics package.
\item[\package{graphicx}] The `extended' or `enhanced' graphics
  package.
\end{description}
The two differ only in the format of optional arguments for the
commands defined. The command names, and the mandatory arguments are
the same for the two packages.

\subsection{Package Options}
As discussed in section~\ref{drivers}, the graphics packages share the
same `driver' options as the \package{color} package. As for colour
you should set up a site-default in a file,
|graphics.cfg|, containing the line (for |dvips|):\\
|\ExecuteOptions{dvips}|

The graphics packages have some other options for controlling how many
of the features to enable:
\begin{description}
\item[draft] suppress all the `special' features. In particular
  graphics files are not included (but they are still read for size
  info) just the filename is printed in a box of the correct size.
\item[final] The opposite of |draft|. Useful to over-ride a global
  |draft| option specified in the |\documentclass| command.
\item[hiderotate] Do not show rotated text (presumably because the
  previewer can not rotate).
\item[hidescale] Do not show scaled text (presumably because the
  previewer can not scale).
\item[hiresbb] Look for size specifications in |%%HiResBoundingBox|
  lines rather than standard |%%BoundingBox| lines.%
  \NEWfeature{1996/10/29}
\item[demo] Instead of inserting an image file |\includegraphics|
  draws a 150\,pt by 100\,pt rectangle unless other dimensions are
  specified manually.\NEWfeature{2006/02/20}
\end{description}
\subsection{Rotation}

\begin{decl}
\gs |\rotatebox|\arg{angle}\arg{text}\\
\gx |\rotatebox|\oarg{key val list}\arg{angle}\arg{text}
\end{decl}

This puts \emph{text} in a box, like |\mbox|, but rotates the box
through \emph{angle} degrees, \rotatebox{15}{like this}.

The standard version always rotates around the reference point of the
box, but the \package{keyval} version takes the following keys:

\begin{decl}
|origin|=\m{label}\\
|x|=\m{dimen}\\
|y|=\m{dimen}\\
|units|=\m{number}
\end{decl}

So you may specify both |x| and |y|, which give the coordinate of
the centre of rotation relative to the reference point of the box, eg
|[x=2mm, y=5mm]|. Alternatively, for the most common points, one may use
|origin| with a \emph{label} containing one or two of the following:
|lrctbB| (|B| denotes the baseline, as for \package{PSTricks}). For
example, compare a default rotation of $180^\circ$
\ldots\rotatebox{180}{Like This}\ldots\ to the effects gained by using
the |origin| key:\\
|[origin = c]| rotates about the centre of the box,\ldots
         \rotatebox[origin=c]{180}{Like This}\ldots\\
|[origin = tr]| rotates about the top right hand corner\ldots
                   \rotatebox[origin=tr]{180}{Like This}\ldots

The |units| key allows a change from the default units of degrees
anti-clockwise. Give the number of units in one full anti-clockwise
rotation. For example:\\
|[units = -360]| specifies degrees clockwise.\\
|[units= 6.283185]| specifies radians.

\subsection{Scaling}

\subsubsection{Scaling by scale factor}

\begin{decl}
|\scalebox|\arg{h-scale}\oarg{v-scale}\arg{text}
\end{decl}

Again this is basically like |\mbox| but scales the \emph{text}.
If \emph{v-scale} is not specified it defaults to \emph{h-scale}.
If it is specified the text is distorted as the horizontal and
vertical stretches are different, \scalebox{3}[.7]{Like This}.


\begin{decl}
|\reflectbox|\arg{text}
\end{decl}

An abbreviation for |\scalebox{-1}[1]|\arg{text}.

\subsubsection{Scaling to a requested size}

\begin{decl}
|\resizebox|\star\arg{h-length}\arg{v-length}\arg{text}
\end{decl}

 Scale \emph{text} so that the width is \emph{h-length}.
 If |!| is used as either length argument, the other argument is used
 to determine a scale factor that is used in both directions.
 Normally \emph{v-length} refers to the height of the box, but in the
 star form, it refers to the `height +  depth'.
 As normal for \LaTeXe\ box length arguments, |\height|,
 |\width|, |\totalheight|, |\depth| may be used to refer to the
 original size of the box.

|\resizebox{1in}{\height}{Some text}|:
\resizebox{1in}{\height}{Some text}

|\resizebox{1in}{!}{Some text}|:
\resizebox{1in}{!}{Some text}

\subsection{Including Graphics Files}
The functions for graphics inclusion try to give the same user syntax
for including any kind of graphics file that can be understood by the
driver. This relies on the file having an extension that identifies
the file type. The `driver options' will define a collection of file
extensions that the driver can handle, although this list may be
extended using the declarations described below.

If the file's extension is unknown to the driver, the system may try a
default file type. The PostScript driver files set this default to be
|eps| (PostScript), but this behaviour may be customised if other
defaults are required.

\begin{decl}
\gs |\includegraphics|\star\oarg{llx,lly}\oarg{urx,ury}\arg{file}\\
\gx |\includegraphics|\star\oarg{key val list}\arg{file}
\end{decl}
 Include a graphics file.

 If \star\ is present, then the graphic is `clipped' to the size
 specified. If \star\ is omitted, then any part  of the graphic that is
 outside the specified `bounding box' will  over-print the surrounding
 text.

 If the optional arguments are omitted, then the size of the graphic
 will be determined by reading an external file as described below.

\paragraph{\package{graphics} version}
 If \oarg{urx,ury} is present, then it should specify the coordinates
 of the top right corner of the image, as a pair of \TeX\ dimensions.
 If the units are omitted they default to |bp|. So |[1in,1in]| and
 |[72,72]| are equivalent. If only one optional argument appears, the
 lower left corner of the image is assumed to be at |[0,0]|. Otherwise
 \oarg{llx,lly} may be used to specify the coordinates of this point.

\paragraph{\package{graphicx} version}
Here the star form is just for compatibility with the standard
version. It just adds |clip| to the list of keys specified.
(Also, for increased compatibility, if \emph{two} optional arguments are
used, the `standard' version of |\includegraphics| is always used, even
if the \package{graphicx} package is loaded.)

The allowed keys are listed below.
\begin{description}
\item[bb] The argument should be four dimensions, separated by spaces.
  These denote the `Bounding Box' of the printed region within
  the file.
\item[bbllx,bblly,bburx,bbury] Set the bounding box. Mainly for
 compatibility with older packages.
 Specifying |bbllx=a,bblly=b,bburx=c,bbury=d|
 is equivalent to specifying |bb = a b c d|.
\item[natwidth,natheight] Again an alternative to |bb|.
 |natheight=h,natwidth=w| is equivalent to |bb = 0 0 h w|.
\item[hiresbb]\NEWfeature{1996/10/29}
 Boolean valued key. If set to |true| (just specifying |hiresbb|
 is equivalent to |hiresbb=true|) then \TeX\ will look for
 |%%HiResBoundingBox| lines rather than |%%BoundingBox|. It may be set
 to |false| to overrule a default setting of |true| set by the
 |hiresbb| package option.
\item[pagebox]\NEWfeature{2017/06/01}
PDF files do not have BoundingBox but may specify up to four predefined
rectangles.

|MediaBox|: the boundaries of the physical medium.
|CropBox|: the region to which the contents of the page are to be
  clipped when displayed.
|BleedBox|: the region to which the contents of the
 page should be clipped in production.
|TrimBox|: the intended dimensions of the finished page.
|ArtBox|: the extent of the page's meaningful content.

The driver will set the image size based on |CropBox| if present,
otherwise it will not use one of the others,
with a driver-defined order of preference.
|MediaBox| is always present.

The |pagebox| key may be used to specify which bounding box specification to use,
The value should be one of
|mediabox|, |cropbox|, |bleedbox|, |trimbox|, |artbox|.
\item[viewport]\NEWfeature{1995/06/01}
 The |viewport| key takes four arguments, just like
 |bb|. However in this case the values are taken relative to the
 origin specified by the bounding box in the file. So to `view' the
 1in square in the bottom left hand corner of the area specified by
 the bounding box, use the argument |viewport=0 0 72 72|.
\item[trim]\NEWfeature{1995/06/01}
 Similar to viewport, but here the four lengths specify the
 amount to remove or add to each side. |trim= 1 2 3 4| `crops' the
 picture by 1bp at the left, 2bp at the bottom, 3bp on the right and
 4bp at the top.
\item[angle] Rotation angle.
\item[origin]\NEWfeature{1995/09/28}
 Origin for rotation. See the documentation of |\rotatebox|.
\item[width] Required width. The
  graphic is scaled to this width.
\item[height] Required height. The
  graphic is scaled to this height.
\item[totalheight]\NEWfeature{1995/06/01}
 Specify the total height (height $+$ depth) of the figure.
 This will differ from the `height' if rotation has occurred.
 In particular if the figure has been rotated by $-90^\circ$
 then it will have zero height but large depth.
\item[keepaspectratio]\NEWfeature{1995/09/27}
 Boolean valued key like `clip'.
 If set to true then specifying both `width' and `height' (or
 `totalheight') does not distort the figure but scales such that
  neither of the specified dimensions is \emph{exceeded}.
\item[scale] Scale factor.
\item[clip] Either `true' or `false' (or no value, which is equivalent
  to `true'). Clip the graphic to the bounding box.
\item[draft] a boolean valued key, like `clip'. Locally switches to
  draft mode.
\item[type] Specify the graphics type.
\item[ext]  Specify the file extension. This should \emph{only} be
 used in conjunction with |type|.
\item[read] Specify the file extension of the `read file'. This
 should \emph{only} be used in conjunction with |type|.
\item[command] Specify any command to be applied to the file.  This
 should \emph{only} be used in conjunction with |type|.
\item[quiet]\NEWfeature{2017/06/01}
 Skip writing information to the log.
\item[page]\NEWfeature{2017/06/01}
Page of a multi-page PDF file. (by default the first page will be used.)
\item[interpolate]\NEWfeature{2017/06/01}
Enable/disable interpolation of bitmap images by the viewer.
\end{description}

For the keys specifying the original size (i.e,, the bounding box,
trim and viewport keys) the units can be omitted, in
which case bp (i.e., PostScript points) are assumed.

The first seven keys specify the original size of the image. This size
needs to be specified in the case that the file can not be read by
\TeX, or it contains an incorrect size `BoundingBox' specification.

|bbllx|\ldots\ |\bbury| are mainly for compatibility for older
packages.\\
|bbllx=a, bblly=b, bburx=c, bbury=d|\\
is equivalent to\\
|bb = a b c d|.

|natheight| and |natwidth| are just shorthands for setting the lower
left coordinate to 0 0 and the upper right coordinate to the specified
width and height.

The next few keys specify any scaling or rotation to be applied to the
image. To get these effects using the standard package, the
|\includegraphics| call must be placed inside the argument of a
|\rotatebox| or |\scalebox| command.

The keys are read left-to-right, so |[angle=90, height=1in]| means
rotate by 90 degrees, and then scale to a height of 1in.
|[height=1in, angle=90]| would result in a final \emph{width} of 1in.

If the \textsf{calc} package is also loaded the lengths may use
\textsf{calc} syntax, for instance to specify a width of 2\,cm
less than the text width: |[width=\textwidth-2cm]|.

\TeX\ leaves the space specified either in the file, or in
the optional arguments. If any part of the image is actually outside
this area, it will by default overprint the surrounding text.
If the star form is used, or |clip| specified, any part of the image
outside this area will not be printed.

The last four keys suppress the parsing of the filename. If they are
used, the main \emph{file} argument should not have the file
extension. They correspond to the arguments of |\DeclareGraphicsRule|
described below.

To see the effect that the various options have consider the file
|a.ps|. This file contains the bounding box specification
\begin{verbatim}
%%BoundingBox:0 0 72 72
\end{verbatim}
That is, the printed region consists of a one-inch square, in
the bottom left hand  corner of the paper.

In all the following examples the input will be of the form
\begin{verbatim}
left---\fbox{\includegraphics{a}}---right
\end{verbatim}
With different options supplied to |\includegraphics|.

No optional argument.\\
left---\fbox{\includegraphics{a.eps}}---right

\gs |\scalebox{0.5}{\includegraphics{a}}|\\
\gx |\includegraphics[scale=.5]{a}|\\
left---\fbox{\includegraphics[scale=.5]{a.eps}}---right

\gs |\includegraphics[15,10][35,45]{a}}|\\
\gx |\includegraphics[viewport= 15 10 35 45]{a}|\\
left---\fbox{\includegraphics[viewport= 15 10 35 45]{a.eps}}---right

\gs |\includegraphics*[15,10][35,45]{a}}|\\
\gx |\includegraphics[viewport= 15 10 35 45,clip]{a}|\\
left---\fbox{\includegraphics[viewport= 15 10 35 45,clip]{a.eps}}---right

\gs |\scalebox{0.5}{\includegraphics{a}}|
                   and |draft| option.\\
\gx |\includegraphics[scale=.5, draft]{a}|\\
left---\fbox{\includegraphics[scale=.5, draft]{a.eps}}---right

\subsection{Other commands in the \package{graphics} package}

\begin{decl}
|\graphicspath|\arg{dir-list}
\end{decl}
This optional declaration may be used to specify a list of directories
in which to search for graphics files. The format is the same as for
the \LaTeXe\ primitive |\input@path|. A list of directories, each in a
|{}| group (even if there is only one in the list). For example:\\
  |\graphicspath{{eps/}{tiff/}}|\\
 would cause the system to look in the subdirectories |eps| and |tiff|
 of the current directory. (All modern \TeX{} systems use |/|
 as the directory separator, even on Windows.)

 The default setting of this path is
 |\input@path| that is: graphics files will be found wherever \TeX\
 files are found.

\begin{decl}
|\DeclareGraphicsExtensions|\arg{ext-list}
\end{decl}
 \NEWdescription{1994/12/01}
 This specifies the behaviour of the system when no file extension
 is specified in the argument to |\includegraphics|.
 \arg{ext-list} should be a comma separated list of file extensions.
 (White space is ignored between the entries.)
 A file name is produced by appending one extension from the list.
 If a file is found, the system acts as if that extension had been
 specified. If not, the next extension in \emph{ext-list} is tried.


Note that if the extension is not specified in the |\includegraphics|
command, the graphics file must exist at the time \LaTeX\ is run, as
the existence of the file is used to determine which extension from
the list to choose. However if a file extension \emph{is} specified,
e.g.\ |\includegraphics{a.eps}| instead of |\includegraphics{a}|, then
the graphics file need not exist at the time \LaTeX\ is used. (In
particular it may be created on the fly by  the \m{command}
specified in the |\DeclareGraphicsRule| command described below.)
\LaTeX\ does however need to be able to determine the size of the
image so this size must be specified in arguments, or the `read file'
must exist at the time \LaTeX\ is used.

\begin{decl}
|\DeclareGraphicsRule|\arg{ext}\arg{type}\arg{read-file}\arg{command}
\end{decl}
 Any number of these declarations can be made. They determine how the
 system behaves when a file with extension \emph{ext} is specified.
 (The extension may be specified explicitly or, if the argument to
 |\includegraphics| does not have an extension, it may be a default
 extension from the \emph{ext-list} specified with
 |\DeclareGraphicsExtensions|.)

\emph{ext} the file extension for which this rule applies. As a special
case, \emph{ext} may be given as |*| to denote the default behaviour for
all undeclared extensions (see the example below).

\emph{type} is the `type' of file involved. All files of the same type
will be input with the same internal command (which must be defined in
a `driver file'). For example files with extensions |ps|, |eps|,
|ps.gz| may all be classed as type |eps|.

\emph{read-file} determines the extension of the file that should be
read to determine size information. It may be the same as \emph{ext}
but it may be different, for example |.ps.gz| files are not readable
easily by \TeX, so you may want to put the bounding box information in
a separate file with extension  |.ps.bb|. If \emph{read-file} is empty,
|{}|, then the system will not try to locate an external file for size
info, and the size must be specified in the arguments of
|\includegraphics|. If the driver file specifies a procedure for
reading size files for \emph{type}, that will be used, otherwise the
procedure for reading |eps| files will be used. Thus the size of
bitmap files may be specified in a file with a PostScript style
|%%BoundingBox| line, if no other specific format is available.

As a special case |*| may be used to denote the
same extension as the graphic file. This is mainly of use in
conjunction with using |*| as the extension, as in that case the
particular graphic extension is not known. For example
\begin{verbatim}
 \DeclareGraphicsRule{*}{eps}{*}{}
\end{verbatim}
This would declare a default rule, such that all unknown extensions
would be treated as EPS files, and the graphic file would be read for
a BoundingBox comment.

\emph{command} is usually empty, but if non empty it is used in place
of the filename in the |\special|. Within this argument, |#1| may be
used to denote the filename. Thus using the dvips driver, one may
use\\
|\DeclareGraphicsRule{.ps.gz}{eps}{.ps.bb}{`zcat #1}|\\
the final argument causes dvips to use the |zcat| command to unzip the
file before inserting it into the PostScript output.

Note that \LaTeX\ will find the graphics file by searching along
TEXINPUTS (and possibly other places, as specified with
|\graphicspath|) however it may be that the command you specify
in this argument can not find such files unless they are in the
current directory. On some systems it may be possible to modify
the command so that it will find any files that \LaTeX\ can find.
For example on newer web2c \TeX\ releases on unix, one may modify the
above command so that the last argument is:\\
|{`zcat `kpsewhich -n latex tex #1`}|\\
which incantation causes the |kpsewhich| program to find the
file, by searching along \LaTeX's path, and then pass the full path
name to the |zcat| program so that it can uncompress the file.
Any such uses are very system dependent, and would best be placed in
a |graphics.cfg| file, thus keeping the document itself portable.

\subsection{Global setting of keys}

Most of the \package{keyval} keys used in the \package{graphicx} package
may also be set using the command |\setkeys| provided by the
\package{keyval} package.%
\footnote{\texttt{clip}, \texttt{scale} and \texttt{angle} may not be set via
\texttt{\string\setkeys} prior to calling
\texttt{\string\includegraphics}.}

For instance, suppose you wanted all the files to be included in the
current document to be scaled to 75\% of the width of the lines of text,
then one could issue the following command:\\
|\setkeys{Gin}{width=0.75\textwidth}|\\
Here `|Gin|' is the name used for the \package{keyval} keys associated
with `Graphics inclusion'. All following
|\includegraphics| commands (within the same group or environment) will
act as if |[width=0.75\textwidth]| had been specified, in addition to
any other key settings actually given in the optional argument.

Similarly to make all |\rotatebox| arguments take an argument in
radians, one just needs to specify:\\
|\setkeys{Grot}{units=6.28318}|

\subsection{Compatibility between \package{graphics} and
  \package{graphicx}}

For a document author, there are not really any problems of
compatibility between the two packages. You just choose the interface
that you personally prefer, and then use the appropriate package.

For a package or class writer the situation is slightly
different. Suppose that you are writing a letter class that needs to
print a company logo as part of the letterhead.

As the author of the class you may want to give the users the
possibility of using  either interface in their letters (should they
need to include any further graphics into the letter body).
In this case the class should load the \package{graphics} package (not
\package{graphicx}, as this would commit any users of the class to the
\package{keyval} interface). The logo should be included with
|\includegraphics| either with \emph{no} optional argument (if the
correct size information is in the file) or \emph{both} optional
arguments otherwise.
Do not use the \emph{one} optional argument form, as the meaning of this
argument would change (and generate errors) if the user were to load
\package{graphicx} as well as your class.

\section{Remaining packages in the graphics bundle}

\subsection{Epsfig}
This is a small package essentially a `wrapper' around the
\package{graphicx} package, defining a command |\psfig| which has the
syntax\\
|\psfig{file=xxx,...}| rather than |\includegraphics[...]{xxx}|.\\
It also has a few more commands to make it slightly more compatible with
the old \LaTeX~2.09 style of the same name.

\subsection{Rotating}
An extension package to \package{graphicx}, mainly used for providing
rotated float environments.

\subsection{Trig}
The trig package is not intended to be used directly in documents. It
calculates sine, cosine and tangent trigonometric functions. These
are used to calculate the space taken up by a rotated box. This
package is also used by the |fontinst| program which converts
PostScript files to a form usable by \TeX.

As well as being used as a \LaTeX\ package, the macros may be extracted
with the \package{docstrip} options \texttt{plain,package}. In this case
the \LaTeX\ package declarations are omitted from the file, and the
macros may be directly used as part of another macro file (they work
with any format based on plain \TeX.)

\subsection{Keyval}
The \package{keyval} package is intended to be used by other
packages. It provides a generic way of setting `keys' as used by the
\package{graphicx} package, and splitting up the comma separated lists
of \m{key}~=~\m{value} pairs.

Like the \package{trig} package, these macros may be extracted and used
as part of another macro file, based on plain \TeX, as well as the
standard use as a \LaTeX\ package.

By default an undeclared key will generate an error.
If however the option  \texttt{unknownkeysallowed} is used, then
unknown keys will be silently ignored (leaving a message in the log
file). This option is also accepted by the \textsf{graphicx} package.

\iffalse

\subsection{Pstcol}
\package{PSTricks}, by Timothy Van Zandt is an immensely powerful
package that enables a very full featured interface between PostScript
and \TeX. Unfortunately the colour support in \package{PSTricks} is
slightly incompatible with the colour mechanism defined in the
\package{color} package. The \package{pstcol} package is a (hopefully
temporary) package that modifies a very small number of internal
PSTricks functions, to remove this incompatibility. If
\package{pstricks} is loaded via this package, you may use any colours
defined by \package{color} package commands within \package{pstricks}
commands, and vice versa.

\fi

\subsection{Lscape}
The \package{lscape} package requires and takes the same options
as the \package{graphics} package. It defines a |landscape| environment
within which page bodies are rotated through 90 degrees. The page head
and foot are not affected, they appear in the standard (portrait)
position.
\end{document}