\includegraphics (LaTeX2e unofficial reference manual (November 2018))

Next: \rotatebox, Up: Commands for graphics [Contents][Index]

#### 22.3.1 `\includegraphics`

Synopses for `graphics` package:

    \includegraphics{filename}
    \includegraphics[urx,ury]{filename}
    \includegraphics[llx,lly][urx,ury]{filename}
    \includegraphics*{filename}
    \includegraphics*[urx,ury]{filename}
    \includegraphics*[llx,lly][urx,ury]{filename}

Synopses for `graphicx` package:

    \includegraphics{filename}
    \includegraphics[key-value list]{filename}
    \includegraphics*{filename}
    \includegraphics*[key-value list]{filename}

Include a graphics file. The starred form `\includegraphics*` will clip the graphic to the size specified, while for the unstarred form any part of the graphic that is outside the box of the specified size will over-print the surrounding area.

This

    \usepackage{graphicx}  % in preamble
      ...
    \begin{center}
      \includegraphics{plot.pdf}
    \end{center}

will incorporate into the document the graphic in `plot.pdf`, centered and at its nominal size. You can also give a path to the file, as with `\includegraphics{graphics/plot.pdf}`. To specify a list of locations to search for the file, see \graphicspath.

If your filename includes spaces then put it in double quotes. An example is `\includegraphics{"sister picture.jpg"}`.

The `\includegraphics{filename}` command decides on the type of graphic by splitting filename on the first dot. You can use filename with no dot, as in `\includegraphics{turing}` and then LaTeX tries a sequence of extensions such as `.png` and `.pdf` until it finds a file with that extension (see \DeclareGraphicsExtensions).

If your file name contains dots before the extension then you can hide them with curly braces, as in `\includegraphics{{plot.2018.03.12.a}.pdf}`. Or, if you use the `graphicx` package then you can use the options `type` and `ext`; see below. This and other filename issues are also handled with the package `grffile`.

This example puts a graphic in a figure environment so LaTeX can move it to the next page if fitting it on the current page is awkward (see figure).

    \begin{figure}
      \centering
      \includegraphics[width=3cm]{lungxray.jpg}
      \caption{The evidence is overwhelming: don't smoke.}  \label{fig:xray}
    \end{figure}

This places a graphic that will not float, so it is sure to appear at this point in the document even if makes LaTeX stretch the text or resort to blank areas on the page. It will be centered and will have a caption.

    \usepackage{caption}  % in preamble
      ...
    \begin{center}
      \includegraphics{pix/nix.png}
      \captionof{figure}{The spirit of the night} \label{pix:nix} % optional
    \end{center}

This example puts a box with a graphic side by side with one having text, with the two vertically centered.

    \newcommand*{\vcenteredhbox}[1]{\begin{tabular}{@{}c@{}}#1\end{tabular}}
      ...
    \begin{center}
      \vcenteredhbox{\includegraphics[width=0.4\textwidth]{plot}}
      \hspace{1em}
      \vcenteredhbox{\begin{minipage}{0.4\textwidth}
                       \begin{displaymath}
                         f(x)=x\cdot \sin (1/x)
                       \end{displaymath}
                     \end{minipage}}
    \end{center}

If you use the `graphics` package then the only options involve the size of the graphic (but see \rotatebox and \scalebox). When one optional argument is present then it is `[urx,ury]` and it gives the coordinates of the top right corner of the image, as a pair of TeX dimensions (see Units of length). If the units are omitted they default to `bp`. In this case, the lower left corner of the image is assumed to be at (0,0). If two optional arguments are present then the leading one is `[llx,lly]`, specifying the coordinates of the image’s lower left. Thus, `\includegraphics[1in,0.618in]{...}` calls for the graphic to be placed so it is 1 inch wide and 0.618 inches tall and so its origin is at (0,0).

The `graphicx` package gives you many more options. Specify them in a key-value form, as here.

    \begin{center}
      \includegraphics[width=1in,angle=90]{lion}
      \hspace{2em}
      \includegraphics[angle=90,width=1in]{lion}
    \end{center}

The options are read left-to-right. So the first graphic above is made one inch wide and then rotated, while the second is rotated and then made one inch wide. Thus, unless the graphic is perfectly square, the two will end with different widths and heights.

There are many options. The primary ones are listed first.

Note that a graphic is placed by LaTeX into a box, which is traditionally referred to as its bounding box (distinct from the PostScript BoundingBox described below). The graphic’s printed area may go beyond this box, or sit inside this box, but when LaTeX makes up a page it puts together boxes and this is the box allocated for the graphic.

`width`

  The graphic will be shown so its bounding box is this width. An example is `\includegraphics[width=1in]{plot}`. You can use the standard TeX dimensions (see Units of length) and also convenient is `\linewidth`, or in a two-column document, `\columnwidth` (see Page layout parameters). An example is that by using the `calc` package you can make the graphic be 1 cm narrow than the width of the text with `\includegraphics[width=\linewidth-1.0cm]{hefferon.jpg}`.

`height`

  The graphic will be shown so its bounding box is this height. You can use the standard TeX dimensions (see Units of length), and also convenient are `\pageheight` and `\textheight` (see Page layout parameters). For instance, the command `\includegraphics[height=0.25\textheight]{godel}` will make the graphic a quarter of the height of the text area.

`totalheight`

  The graphic will be shown so its bounding box has this height plus depth. This differs from the height if the graphic was rotated. For instance, if it has been rotated by -90 then it will have zero height but a large depth.

`keepaspectratio`

  If set to `true`, or just specified as here

      \includegraphics[...,keepaspectratio,...]{...}

  and you give as options both `width` and `height` (or `totalheight`), then LaTeX will make the graphic is as large as possible without distortion. That is, LaTeX will ensure that neither is the graphic wider than `width` nor taller than `height` (or `totalheight`).

`scale`

  Factor by which to scale the graphic. To make a graphic twice its nominal size, enter `\includegraphics[scale=2.0]{...}`. This number may be any value; a number between 1 and 0 will shrink the graphic and a negative number will reflect it.

`angle`

  Rotate the graphic. The angle is taken in degrees and counterclockwise. The graphic is rotated about its `origin`; see that option. For a complete description of how rotated material is typeset, see \rotatebox.

`origin`

  The point of the graphic about which the rotation happens. Possible values are any string containing one or two of: `l` for left, `r` for right, `b` for bottom, `c` for center, `t` for top, and `B` for baseline. Thus, entering the command `\includegraphics[angle=180,origin=c]{moon}` will turn the picture upside down about that picture’s center, while the command `\includegraphics[angle=180,origin=lB]{LeBateau}` will turn its picture upside down about its left baseline. (The character `c` gives the horizontal center in `bc` or `tc`, but gives the vertical center in `lc` or `rc`.) The default is `lB`.

  To rotate about an arbitrary point, see \rotatebox.

These are lesser-used options.

`viewport`

  Pick out a subregion of the graphic to show. Takes four arguments, separated by spaces and given in TeX dimensions, as with `\includegraphics[.., viewport=0in 0in 1in 0.618in]{...}`. The dimensions default to big points, `bp`. They are taken relative to the origin specified by the bounding box. See also the `trim` option.

`trim`

  Gives parts of the graphic to not show. Takes four arguments, separated by spaces, that are given in TeX dimensions, as with `\includegraphics[.., trim= 0in 0.1in 0.2in 0.3in, ...]{...}`. These give the amounts of the graphic not to show, that is, LaTeX will crop the picture by 0 inches on the left, 0.1 inches on the bottom, 0.2 inches on the right, and 0.3 inches on the top. See also the `viewport` option.

`clip`

  If set to `true`, or just specified as here

      \includegraphics[...,clip,...]{...}

  then the graphic is cropped to the bounding box. This is the same as using the starred form of the command, `\includegraphics*[...]{...}`.

`page`

  Give the page number of a multi-page PDF file. The default is `page=1`.

`pagebox`

  Specifies which bounding box to use for PDF files from among `mediabox`, `cropbox`, `bleedbox`, `trimbox`, or `artbox`. PDF files do not have the BoundingBox that PostScript files have, but may specify up to four predefined rectangles. The MediaBox gives the boundaries of the physical medium. The CropBox is the region to which the contents of the page are to be clipped when displayed. The BleedBox is the region to which the contents of the page should be clipped in production. The TrimBox is the intended dimensions of the finished page. The ArtBox is 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.

`interpolate`

  Enable or disable interpolation of raster images by the viewer. Can be set with `interpolate=true` or just specified as here.

      \includegraphics[...,interpolate,...]{...}

`quiet`

  Do not write information to the log. You can set it with `quiet=true` or just specified it with `\includegraphics[...,quite,...]{...}`,

`draft`

  If you set it with `draft=true` or just specify it with

      \includegraphics[...,draft,...]{...}

  then the graphic will not appear in the document, possibly saving color printer ink. Instead, LaTeX will put an empty box of the correct size with the filename printed in it.

These options address the bounding box for Encapsulated PostScript graphic files, which have a size specified with a line `%%BoundingBox` that appears in the file. It has four values, giving the lower x coordinate, lower y coordinate, upper x coordinate, and upper y coordinate. The units are PostScript points, equivalent to TeX’s big points, 1/72 inch. For example, if an `.eps` file has the line `%%BoundingBox 10 20 40 80` then its natural size is 30/72 inch wide by 60/72 inch tall.

`bb`

  Specify the bounding box of the displayed region. The argument is four dimensions separated by spaces, as with `\includegraphics[.., bb= 0in 0in 1in 0.618in]{...}`. Usually `\includegraphics` reads the BoundingBox numbers from the EPS file automatically, so this option is only useful if the bounding box is missing from that file or if you want to change it.

`bbllx, bblly, bburx, bbury`

  Set the bounding box. These four are obsolete, but are retained for compatibility with old packages.

`natwidth, natheight`

  An alternative for `bb`. Setting

      \includegraphics[...,natwidth=1in,natheight=0.618in,...]{...}

  is the same as setting `bb=0 0 1in 0.618in`.

`hiresbb`

  If set to `true`, or just specified as with

      \includegraphics[...,hiresbb,...]{...}

  then LaTeX will look for `%%HiResBoundingBox` lines instead of `%%BoundingBox` lines. (The `BoundingBox` lines use only natural numbers while the `HiResBoundingBox` lines use decimals; both use units equivalent to TeX’s big points, 1/72 inch.) To override a prior setting of `true`, you can set it to `false`.

These following options allow a user to override LaTeX’s method of choosing the graphic type based on the filename extension. An example is that `\includegraphics[type=png,ext=.xxx,read=.xxx]{lion}` will read the file `lion.xxx` as though it were `lion.png`. For more on these, see \DeclareGraphicsRule.

`type`

  Specify the graphics type.

`ext`

  Specify the graphics extension. Only use this in conjunction with the option `type`.

`read`

  Specify the file extension of the read file. Only use this in conjunction with the option `type`.

`command`

  Specify a command to be applied to this file. Only use this in conjunction with the option `type`. See Command line options for a discussion of enabling the `\write18` functionality to run external commands.

Unofficial LaTeX2e reference manual