8.1 LaTeX’s image loading support

Since the introduction of LaTEX 2ε in 1994, LaTEX has offered a uniform syntax for including every kind of graphics file that can be handled by the different drivers. In addition, all kinds of graphic operations (such as resizing and rotating) as well as color support are available.

These features are not part of the LaTEX kernel but rather are provided by the standard, fully supported color, graphics, and graphicx extension packages. As the TEX program does not have any direct methods for graphic manipulation, the packages have to rely on features supplied by the “driver” used to print the Device Independent File Format (DVI) file or by the features of the extended engines pdfTEX, X TE EX, or LuaTEX that can produce PDF output directly. Unfortunately, not all drivers or PDF engines support the same features, and even the internal method of accessing these extensions varies among them. Consequently, all of these packages take options such as dvips or pdftex to specify which external driver or engine is being used. Through this method, any unavoidable device-dependent information is localized in a single place, the preamble of the document. However, each TEX distribution when installed sets up suitable detection methods and defaults (e.g., if the program pdflatex is used, then most likely the correct driver option is pdftex), so in practice most documents compile correctly without the need to specify any such option.

The packages graphics and graphicx can both be used to scale, rotate, and reflect LaTEX material or to include graphics files prepared with other programs. The difference between the two is that graphics uses a combination of macros with a “standard” or TEX-like syntax, while the “extended” or “enhanced” graphicx package presents a key/ value type of interface for specifying optional parameters to the \includegraphics and commands.

8.1.1 Options for graphics and graphicx

When using LaTEX’s graphics packages, the necessary space for the typeset material after performing a file inclusion or applying some geometric transformation is reserved on the output page. It is, however, the task of the device driver (e.g., dvips, dvipdfmx, pdftex, etc.) to perform the actual inclusion or transformation in question and to show the correct result. Because different drivers require different code to carry out an action like rotation, one has to specify the target driver as an option to the graphics packages — for example, option dvips if you use one of the graphics packages with Tom Rokicki’s dvips program, or option pdftex if the graphics packages are used with the pdfTEX engine.

Fortunately, however, the package is usually capable of figuring out the correct driver automatically, in particular when generating a PDF with pdfTEX, X TE EX, or LuaTEX. In all other cases it assumes dvips, which is often, but not always, correct. Only in the latter case does one need to explicitly provide a driver option. The full list of supported drivers (and their restrictions, if any) is listed in the graphics package documentation if you ever run into a case where the default does not work.

In addition to the driver options, the packages support some options controlling which features are enabled (or disabled):

draft Suppress all “special” features, such as including external graphics files in the final output. The layout of the page is not affected, because LaTEX still reads the size information concerning the bounding box of the external material. This option is of particular interest when a document is under development and you do not want to download the (often huge) graphics files each time you work on it. When draft mode is activated, the picture is replaced by a box of the correct size containing the name of the external file.

final The opposite of draft. This option can be useful when, for instance, “draft” mode was specified as a global option with the \documentclass command (e.g., for showing overfull boxes), but you do not want to suppress the graphics as well.

hiresbb In PostScript graphics look for bounding box comments that are of the form %%HiResBoundingBox (which typically have real values) instead of the standard %%BoundingBox (which must have integer values).

Of lesser importance these days are options that disable features because of restrictions in the output driver. With hiderotate you prevent showing rotated material (for instance, when the previewer cannot rotate material and produces error messages), and hidescale does the same for scaled material.

With the graphicx package, these options are also available locally as keys for individual \includegraphics commands.

8.1.2 The includegraphics syntax in the graphics package

With the graphics package, an image file can be included by using the following command:

8.1.3 The includegraphics syntax in the graphicx package

The extended graphics package graphicx also implements \includegraphics but offers a syntax for including external graphics files that is somewhat more transparent and user-friendly. With today’s TEX implementations, the resultant processing overhead is negligible, so we suggest using this interface.

8.1.4 Setting default key values for the graphicx package

Instead of specifying the same set of key/value pairs over and over again on individual \includegraphics commands, you can specify global default values for keys associated with such commands. To do so, you use the declaration provided by the keyval package, which is automatically included when graphicx is used.

8.1.5 Declarations guiding the inclusion of images

While key/value pairs can be set only when the graphicx package is used, the declarations described in this section can be used with both the graphics and the graphicx packages.

By default, LaTEX looks for graphics files in the same directories where it looks for other files. But for larger projects it might be preferable to keep the image

files together in a single directory or in a set of directories. A list of directories where LaTEX should search for graphics files can be specified through the command \graphicspath, whose argument is a list of directories, each inside a pair of braces {} (even if the list contains only one directory). For example,