LaTeX/Importing Graphics

From Wikibooks, the open-content textbooks collection

Strictly speaking, LaTeX cannot manage pictures directly: in order to introduce graphics within documents, LaTeX just creates a box with the same size of the image you want to include and embeds the picture, without any other processing. This means you will have to take care that the images you want to include are in the right format to be included. This is not such a hard task because LaTeX supports the most common picture formats around.

[edit] The graphicx package

As stated before, LaTeX can't manage pictures directly, so we will need some extra help: we have to load the graphicx package in the preamble of our document:

\usepackage{graphicx}

This package accepts as an argument the external driver to be used to manage pictures; luckily the recent version of this package takes care of everything by itself, changing the driver according to the compiler you are using, so you don't have to worry about anything. Just in case you want to understand better how it works, here are the possible options you can pass to the package:

• dvips (default if compiling with latex), if you are compiling with latex to get a DVI and you want to see your document with a DVI or PS viewer.
• dvipdfm, if you are compiling with latex to get a DVI that you want to convert to PDF using dvipdfm, to see your document with any PDF viewer.
• pdftex (default if compiling with pdflatex), if you are compiling with pdftex to get a PDF that you will see with any PDF viewer.

but, again, you don't need to pass any option to the package because the default settings are fine most of the cases.

In many respects, importing your images into your document using LaTeX is fairly simple... once you have your images in the right format that is! Therefore, I fear for many people the biggest effort will be the process of converting their graphics files. Now we will see which formats we can include and then we will see how to do it.

[edit] Document Options

The graphics and graphicsx packages recognize the "draft" and "final" options given in the \documentclass[...]{...} command at the start of the file. Using "draft" as the option will suppress the inclusion of the image in the output file and will replace the contents with the name of the image file that would have been seen. Using "final" will result in the image being placed in the output file. The default is "draft".

[edit] Supported image formats

As explained before, the image formats you can use depend on the driver that graphicx is using but, since the driver is automatically chosen according to the compiler, then the allowed image formats will depend on the compiler you are using.

[edit] Compiling with latex

The only format you can include while compiling with latex is "Encapsulated PostScript" (EPS).

EPS was defined by Adobe for making it easy for applications to import postscript-based graphics into documents. Because an EPS file declares the size of the image, it makes it easy for systems like LaTeX to arrange the text and the graphics in the best way. EPS is a vector format: this means that it can have very high quality if it is created properly, with programs that are able to manage vector graphics. It is also possible to store bit-map pictures within EPS, but they will need a lot of disk space.

Most decent graphics software has the ability to save images in the EPS format (extension is normally .eps). Obviously, Adobe applications do, since they developed the PS and EPS standards, however there are many other alternatives. Here are some examples:

• Inkscape can save in vector EPS format. It is multi-platform.
• Using GIMP you can convert almost any format in EPS, but you will get bit-map EPS files. It is multi-platform.
• if you want to make mathematical plots, then Gnuplot can save in any format.
• For command-line, convert, part of ImageMagick. It will let you convert to and from any format it understands. It is a command-line program, but is very simple to use. You pass two arguments, the first being the filename of your current image, and the second is the filename you wish to give your converted image. Normally, the only difference is in the extension. By default, convert will deduce the input file format from the contents of the file and the output format from the the file extension you supplied. For example:

   convert graph.jpg graph.eps 
  

  This command takes the JPEG file, graph.jpg, and converts it to an EPS file of the same name. Of course, it would have worked equally well if your original image was a BMP, GIF, PNG, etc.
• imgtops. It usually outperforms convert (see [1]), and is much more lightweight.
• In Windows you can use Paint Shop Pro. Follow the steps:

1. Load up PSP by selecting it from Start/Programs.
2. Select File/Open, or click the open icon.
3. Browse to the location of your image. Select the file and click Open.
4. Once image has loaded, select File/Save As.
5. Choose the location to save the image. Click on the drop-down box that specifies the file-type and select 'Encapsulated Postscript'. It should automatically update the filename to have the '.eps' extension. Feel free to change the filename if you wish.
6. By default, PSP will save EPS files in monochrome. If your image in already in black and white, or if don't need to preserve the color, then do nothing. Otherwise, under 'Options', choose to save in color, but without a preview.
7. Click Save.

There are some tricks to be able to import other formats than EPS into your DVI document, but they're very complicated. On the other hand, converting any image to EPS is very simple, so it's not worth considering them.

[edit] Compiling with pdflatex

If you are compiling with pdflatex to get a PDF, you have a wider choice. You can insert

• JPG, widely used on Internet, digital cameras, etc. They are the best choice if you want to insert photos
• PNG, very common format (even if not as much as JPG), it's a lossless format and it's the best choice for diagrams (if you were not able to generate a vector version)
• PDF, it is widely used for documents but can be used to store images as well. It supports both vector and bit-map images, but if you want to store bit-maps you'd better use JPG or PNG, they need less disk space.

JPG and PNG are supported by any image processing program, so you just have to use the one you prefer. If you want to create high quality vector PDF to embed within your PDF document, you can use Inkscape: it supports many vector formats and so you can use it convert from one to other. You could also create your graphics directly with Inkscape. If you want to make mathematical plots, then Gnuplot can save in any format.

Note, that EPS files can not be used with pdflatex, however they can be converted to PDF using epstopdf, included in most LaTeX distributions. In Windows, multiple files can be converted by placing the following line in a batch file (a text file with a .BAT extension) in the same directory as the images:

for %%f in (*.eps) do epstopdf %%f

which can then be run from the command line.

Images can be saved in multiple formats for different purposes. For example, a directory can have "diagram.pdf" for high-resolution printing, while "diagram.png" can be used for previewing on the monitor. You can specify which image file is to be used by pdflatex through the preamble command:

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

which specified the hierarchy of files to include in the document, if they exist and have the same prefix.

[edit] Including graphics

After we have seen which formats we can include and how we could manage those formats, now it's time to learn how to include them in our document. After you have loaded the graphicx package in your preamble, you can include images with \includegraphics, whose syntax is the following:

\includegraphics[attr1=val1, attr2=val2, ..., attrn=valn]{imagename}

As you should hopefully be aware by now, arguments in square brackets are optional, whereas curly braces are compulsory. The argument of the curly braces is the name of the image, write it without the extension. This way the LaTeX compiler will look for any supported image format in that directory and will take the best one (EPS if the output is DVI; JPEG, PNG or PDF if the output is PDF). The variety of possible attributes that can be set is fairly large, and so I shall cover the most useful:

In order to use more than one option at a time, simply separate with a comma. Included graphics will be inserted just there, where you placed the code, and the compiler will handle them as "big boxes". As we will see in the next section, this may lead to a bad output so you'd better place graphics inside floating objects.

[edit] Examples

OK, it's time to see graphicx in action. Here are some examples:

\includegraphics{chick}

This simply imports the image, without any other processing. However, it is very large (so I won't display it here!). So, let's scale it down:

\includegraphics[scale=0.5]{chick}

This has now reduced by half. If you wish to be more specific and give actual lengths of the image dimensions, this is how to go about it:

\includegraphics[width=2.5cm]{chick}

One can also specify the scale with respect to the width of a line in the local environment (\linewidth), the width of the text on a page (\textwidth) or the height of the text on a page (\textheight) (pictures not shown):

\includegraphics[width=0.5\linewidth]{chick}
 
\includegraphics[width=0.75\textwidth]{chick}
 
\includegraphics[height=0.75\textheight]{chick}

To rotate (I also scaled the image down too):

\includegraphics[scale=0.5, angle=180]{chick}

And finally, an example of how to crop an image should you wish to focus in one particular area of interest:

\includegraphics[trim = 10mm 80mm 20mm 5mm, clip, width=3cm]{chick}

Note the presence of clip, as the trim operation will not work without it.

As you may have noticed, the file name of the picture is always without the extensions: the format of the picture does not matter, LaTeX will take care of getting the right version for us. Consider the following situation: you have added some pictures to your document in JPG and you have successfully compiled it in PDF. Now you want to compile it in DVI, you run latex and you get a lot of errors... because you forgot to provide the EPS versions of the pictures you want to insert. At the beginning of this book, we have stated that the same LaTeX source can be compiled in both DVI and PDF without any change. This is true, as long as you don't use particular packages, and graphicx is one of those. In any case, you can still use both compilers with documents with pictures as well, as long as you always remember to provide the pictures in two formats (EPS and one of JPG, PNG and PDF).

[edit] Borders

It is possible to have LaTeX create a border around your image by using fbox:

\setlength\fboxsep{0pt}
\setlength\fboxrule{0.5pt}
\fbox{\includegraphics{chick}}

You can control the border padding with the \setlength\fboxsep{0pt} command, in this case I set it to 0pt to avoid any padding, so the border will be placed tightly around the image. You can control the thickness of the border by adjusting the \setlength\fboxrule{0.5pt} command.

[edit] Graphics storage

There is a way to tell LaTeX where to look for images: for example, it can be useful if you had stored images centrally for use in many different documents. The answer is in a command \graphicspath which you supply with an argument giving the name of an additional directory path you want searched when a file uses the \includegraphics command, here are some examples:

\graphicspath{{c:\mypict~1\camera}}
\graphicspath{{/var/lib/images/}}
\graphicspath{{./images/}}
\graphicspath{{images_folder/}{other_folder/}{third_folder/}}

please see http://www.ctan.org/tex-archive/macros/latex/required/graphics/grfguide.pdf

As you may have noticed, in the first example I've used the "safe" (MS-DOS) form of the Windows MyPictures folder because it's a bad idea to use directory names containing spaces. Using absolute paths, \graphicspath does make your file less portable, while using relative paths (like the last example), you shouldn't have any problem with portability, but remember not to use spaces in file-names.

[edit] Images as figures

There is one major topic missing from this chapter that is relevant, and that is to do with making that image a figure. For this, you will want a caption, and maybe cross-reference. However, this was deliberate, as it is not only images that are figures. Therefore, this material is to be covered within its own tutorial (see Floats, Figures and Captions).

[edit] Xfig

Vector graphics can be created using Xfig (see Installation), and exported for LaTeX. Once your graphic is saved as an test.fig file you need to export it using the FILE>EXPORT drop down menu from the main Xfix window and then selecting the "Combined PS/Latex (both parts)" in the language drop down list. If you don't change any other settings, two files will be created in the same directory as test.fig file, such as: test.pstex_t and test.pstex. The figure can then be placed in a LaTeX document:

\begin{figure}
  \begin{center}
    \input{./xfig/test.pstex_t}
    \caption{This is the caption of my figure}
    \label{fig:test} 
  \end{center}
\end{figure}