6. The graphicx Package

It is possible to generate images using LaTeX commands[Drawing with TeX] (See the pgf/tikz package or The LaTeX Graphics Companion [5]) however most people find it easier to create a picture in some other application, and include that file into their LaTeX document.

PDFLaTeX can insert PDF, PNG and JPG image files into your document. If your image file is in a different format, you may be able to find an application to convert it. [Spawning programs from (La)TeX: \write18]Modern TeX -distributions can automatically convert EPS files to PDF during the LaTeX run using the Perl script epstopdf. If your TeX -distribution doesn't support this, you can convert your EPS file using epstopdf explicitly. For example, if you have an EPS image called, say, sample-image.eps, you can convert it to a PDF image called sample-image.pdf, by using the following command in a terminal or command prompt:

epstopdf sample-image.eps

or (full path name may be required)

perl epstopdf sample-image.eps

To insert an image file into your document, you first need to specify that you want to use the graphicx package. So the following must go in the preamble :

\usepackage{graphicx}

The image can then be included in your document using the command

\includegraphics[<key-val options>]{<filename>}

where <filename> is the name of your image file without the file extension[“Modern” graphics file names], and <key-val options> is a comma-separated list of options that can be used to change the way the image is displayed. Note that if you have an image where the file name contain spaces or multiple dots, you need to use the grffile package:

\usepackage{graphicx,grffile}

Example:

Suppose you had a file called shapes.pdf, then to include it in your document you would do:

\includegraphics{shapes}

which would produce:

You can specify a full or relative pathname, but you must use a forward slash / as the directory divider, even if you are using Windows. For example:

\includegraphics{pictures/shapes}

means the file pictures/shapes.pdf on Unix-type systems, and it means the file pictures\shapes.pdf on Windows.^6.1 This is mainly because the backslash character is a LaTeX special character indicating a command, but it also helps portability between platforms.

You can specify the order of the file types to look for with the command

\DeclareGraphicsExtensions{<ext-list>}

where <ext-list> is a comma-separated list of extensions. For example, you might want to search first for PDF files, then for PNG files, then for JPG files and finally for EPS files:

\DeclareGraphicsExtensions{.pdf,.png,.jpg,.eps}

The default for PDFLaTeX is:

.png,.pdf,.jpg,.mps,.jpeg,.jbig2,.jb2,.PNG,.PDF,.JPG,.JPEG,.JBIG2,.JB2,.eps

The optional argument <key-val options> should be a comma-separated list of <key>=<value> pairs. Common options are:

angle=<x>

rotate the image by x degrees anticlockwise.

width=<length>

scale the image so that the width is <length>. (Remember to specify the units.)

height=<length>

scale the image so that the height is <length>. (Remember to specify the units.)

scale=<value>

Scale the image by <value>

trim=<l> <b> <r> <t>

Specifies the amount to remove from each side. For example

\includegraphics[trim=1 2 3 4]{shapes}

crops the image by 1bp from the left, 2bp from the bottom, 3bp from the right and 4bp from the top. (Recall the bp unit from Table 2.1.)

draft

Don't actually print the image, just draw a box of the same size and print the filename inside it.

Example:

This example first rotates the image by 45 degrees anticlockwise, then scales it so that the width is 1 inch.

\includegraphics[angle=45,width=1in]{shapes}

Note that this isn't the same as scaling and then rotating:

\includegraphics[width=1in,angle=45]{shapes}

You can also scale an image relative to the text area using the length registers \textwidth and \textheight. For example, to scale a portrait image so that its height is three-quarters of the text area height, you can do:

\includegraphics[height=0.75\textheight]{shapes}

or to scale a landscape image so that its width is half the text area width, you can do:

\includegraphics[height=0.5\textwidth]{shapes}

Note:

The \includegraphics command is another form of box (see §4.7. Boxes and Mini-Pages), and can be used in the middle of a line of text, just like the tabular environment. See §7.1. Figures to find out how to put the image in a figure with a caption.

Example:

Recall the ex unit of measure from Table 2.1. This can be used to scale an image relative to the font size:

An image can be inserted into a line of text like this: \includegraphics[height=2ex]{shapes}

Footnotes

... Windows.^6.1: Or shapes.png or shapes.jpg or shapes.eps. The example assumes a PDF image file.

⇦

⇧

⇨

This book is also available as A4 PDF or 12.8cm x 9.6cm PDF or paperback (ISBN 978-1-909440-00-5).