Formats d’image et inclusion

Quand on écrit \includegraphics{plot}, on ne donne pas un nom de fichier à LaTeX : on lui donne un radical. Le package graphicx y accole ensuite des extensions dans un ordre fixe — .pdf, .png, .jpg, etc. — et retient le premier fichier existant. C'est ce choix de conception qui permet à une même source de se compiler avec pdfLaTeX, LuaLaTeX ou dvipdfmx, et c'est aussi lui qui explique la plainte classique : « j'ai régénéré le PNG mais la figure n'a pas changé ». Cette page traite des options de \includegraphics, du chemin de recherche défini par \graphicspath, des formats que chaque moteur lit réellement, et de la façon de lire les erreurs quand LaTeX annonce qu'un fichier est introuvable.

graphicx et \includegraphics : pourquoi omettre l'extension

L'inclusion d'images revient au package standard graphicx : on déclare \usepackage{graphicx} puis on écrit \includegraphics[options]{nom}. Omettre l'extension est l'usage, et la raison saute aux yeux dès qu'on regarde à l'intérieur. Le fichier pilote pdftex.def énonce l'ordre des extensions essayées : .pdf, .png, .jpg, .mps, .jpeg, .jbig2, .jb2. Si plot.pdf et plot.png cohabitent dans le dossier, c'est toujours le PDF qui l'emporte. Lorsqu'un graphique réexporté en PNG refuse de changer, un vieux plot.pdf traîne presque toujours à côté. Vu autrement : c'est justement parce que l'extension est absente qu'on peut plus tard remplacer un PNG par un PDF sans modifier une seule lettre du manuscrit. graphicx est la version étendue de l'ancien package graphics, la différence tenant au passage des options sous forme key=value ; tous deux font partie du bundle standard latex-graphics, rien de plus à installer.

\documentclass{article}
\usepackage{graphicx}
\begin{document}
% no extension: graphicx tries .pdf, .png, .jpg ... in that order
\includegraphics[width=0.6\textwidth]{plot}
\end{document}

Écrire l'extension ne fait pas que désactiver le choix automatique : cela change aussi le libellé de l'erreur. Si \includegraphics{plot} ne trouve rien, c'est le noyau LaTeX qui mène la recherche et qui annonce ! LaTeX Error: File 'plot' not found. Si \includegraphics{plot.png} ne trouve rien, c'est le pilote qui répond : ! Package pdftex.def Error: File 'plot.png' not found: using draft setting. Le premier signifie « aucune extension n'a correspondu », le second « ce fichier-là manque » — et savoir lequel s'affiche indique où chercher. À noter : le package mwe de TeX Live installe example-image.pdf dans l'arborescence TeX elle-même, si bien que \includegraphics{example-image} fonctionne depuis n'importe quel répertoire. D'où la présence de ce nom dans tous les exemples minimaux des sites de questions.

Régler la taille : width, height, scale, keepaspectratio

En pratique, on précise presque toujours la taille, et l'usage est de la donner relativement à la page, comme width=0.8\textwidth. Des valeurs absolues telles que 8cm laissent la figure en arrière dès qu'on passe en deux colonnes ou qu'on change de format de papier. \textwidth est la largeur du bloc de texte ; \linewidth est la largeur de la ligne en cours de composition, qui se réduit à la largeur de la boîte à l'intérieur d'une minipage ou d'une subfigure. Écrire width=\linewidth dans une boîte fait donc suivre l'image automatiquement si l'on modifie ensuite cette boîte. scale= multiplie les dimensions naturelles de l'image, ce qui convient quand ces dimensions ont elles-mêmes un sens, mais il ignore tout de la largeur du texte et déborde facilement ; width= reste le choix le plus sûr.

Donnez à la fois width= et height= et graphicx obéit docilement aux deux : le rapport d'aspect se rompt et l'image se déforme. keepaspectratio l'empêche : les deux valeurs définissent alors un cadre, et l'image y est agrandie autant que possible en conservant ses proportions. Pour couler des photographies dans des emplacements de taille fixe, on la veut presque toujours. Une autre option utile pour les vérifications est draft : elle ne lit pas l'image du tout, elle compose un cadre aux bonnes dimensions avec le nom du fichier à l'intérieur, ce qui accélère spectaculairement les compilations d'essai d'un document comptant des centaines de figures. \usepackage[draft]{graphicx} l'active pour tout le document.

Tourner et rogner : angle, trim, clip, viewport

angle= reçoit une rotation en degrés, mesurée dans le sens antihoraire. angle=90 fait pivoter l'image d'un quart de tour vers la gauche, le geste classique pour poser un graphique en largeur sur une page en hauteur. Ce qui mérite attention, c'est l'ordre dans lequel on écrit angle= et width=, car graphicx applique les clés dans l'ordre donné. [angle=90,width=6cm] signifie « tourner, puis ajuster le résultat à 6 cm de large » ; [width=6cm,angle=90] signifie « mettre à 6 cm de large, puis tourner » — et les dimensions finales diffèrent. La rotation se fait par défaut autour du coin inférieur gauche ; origin=c déplace le pivot au centre et origin=tr en haut à droite.

Pour rogner les bords d'une image, trim= va de pair avec clip. trim prend quatre valeurs dans l'ordre gauche, bas, droite, haut — un ordre hérité du système de coordonnées PostScript, dont l'origine est en bas à gauche, et qui ne correspond donc à l'intuition de personne. L'unité par défaut est le bp (big point, un soixante-douzième de pouce). Et il faut toujours ajouter clip : sans lui, la partie censée disparaître n'est pas supprimée mais déborde sur le texte alentour. Des valeurs négatives font l'inverse et ajoutent de la marge, façon élégante de dégager de l'air autour d'une figure. Si l'on préfère décrire la découpe comme un rectangle en coordonnées absolues plutôt que comme quatre retraits, on emploie viewport=, là encore avec clip.

% half the text width
\includegraphics[width=0.5\textwidth]{photo}

% fit inside 8cm x 5cm without distortion
\includegraphics[width=8cm,height=5cm,keepaspectratio]{photo}

% rotate a quarter turn to the left, then scale the result
\includegraphics[angle=90,width=6cm]{diagram}

% shave 20bp left, 20bp bottom, 30bp right, 10bp top -- clip is mandatory
\includegraphics[trim=20 20 30 10,clip,width=6cm]{scan}

% page 3 of a multi-page PDF
\includegraphics[page=3,width=\linewidth]{report}

Désigner un dossier de figures avec \graphicspath

Si les images vivent dans un dossier à part, on complète le chemin de recherche avec \graphicspath. Chaque répertoire va dans sa propre paire d'accolades — même s'il n'y en a qu'un — et se termine par une barre oblique /, y compris sous Windows. L'ordre de recherche se vérifie facilement : une image de même nom dans le répertoire courant l'emporte d'emblée ; à défaut, les répertoires sont essayés dans l'ordre écrit, le premier trouvé gagne. Écrire \graphicspath{{figures/}{old-figures/}} donne ainsi un montage commode : une nouvelle version dans figures/ masque automatiquement l'ancienne, et seules les figures non encore refaites viennent de old-figures/. Un chemin contenant des espaces se met entre guillemets, comme {"my figures/"}. Pour modifier la liste des extensions elle-même, on emploie \DeclareGraphicsExtensions.

\usepackage{graphicx}
% braces around each directory, trailing slash on each, searched in this order
\graphicspath{ {figures/} {../shared-figures/} }

% narrow or reorder the list of extensions graphicx will try
\DeclareGraphicsExtensions{.pdf,.png,.jpg}

PDF ou PNG : choisir entre vectoriel et matriciel

Il n'y a au fond qu'un critère : ce qui est fait de traits et de texte doit être vectoriel, ce qui présente des tons continus doit être matriciel. Les images vectorielles (PDF, EPS, SVG) décrivent points, droites et courbes par des coordonnées ; les contours sont recalculés à tout agrandissement et la résolution d'impression n'entre jamais en jeu. Graphiques, schémas de circuits et dessins portant des formules relèvent de cette catégorie. Les images matricielles (PNG, JPEG) sont une grille de pixels colorés ; les agrandir ne fait que grossir les pixels. Photographies et captures d'écran relèvent de celle-ci, et pour l'impression il faut des données sources à 300 dpi ou plus. Vectoriser une photo n'apporte rien et ne fait qu'alourdir le fichier. Lorsqu'une figure est produite dans LaTeX même — TikZ, pgfplots —, la sortie est vectorielle dès le départ.

Au sein des formats matriciels, la règle tient en peu de mots : JPEG pour les photographies, PNG pour tout le reste. JPEG compresse avec perte et gère bien les dégradés photographiques, mais il souille le bord des traits et des lettres de ce qu'on appelle le bruit de moustique — d'où l'aspect sale autour du texte d'une capture d'écran enregistrée en JPEG. PNG est sans perte, gère la transparence et convient aux graphiques en aplats et aux captures. Quant au SVG, aucun moteur ne le lit directement. Le package svg permet d'écrire \includesvg{file}, mais il appelle en coulisse la ligne de commande d'Inkscape pour convertir en PDF (ou en EPS pour une sortie DVI) et exporte le texte du SVG dans un fichier séparé que LaTeX recompose. Il faut donc Inkscape installé et une compilation avec --shell-escape. Pour plus de fiabilité, exportez d'abord en PDF avec Inkscape ou un outil équivalent. Dans l'autre sens, pour obtenir du SVG à partir d'une sortie TeX, l'outil est dvisvgm.

Quels formats lit chaque moteur — et EPS échoue-t-il vraiment

Ce qui détermine les formats acceptés n'est pas le moteur mais le fichier pilote qui se trouve derrière. Au démarrage, graphics.cfg reconnaît le moteur en cours et charge pdftex.def pour pdfTeX, xetex.def pour XeTeX, dvips.def en sortie DVI ; la liste d'extensions déclarée dans ce fichier est exactement l'ensemble des formats pris en charge. Deux corrections au récit habituel en découlent. D'abord, XeLaTeX et dvipdfmx traitent EPS et PS directement : les listes de xetex.def et dvipdfmx.def contiennent .eps et .ps, et vont jusqu'à .ai, .bmp et .jp2. Ensuite, pdfLaTeX et LuaLaTeX lisent eux aussi l'EPS, en pratique.

Le mécanisme par lequel pdfLaTeX fait passer l'EPS est écrit dans pdftex.def. À \begin{document}, si le shell escape est actif, ce fichier ajoute lui-même .eps à la liste des extensions et charge epstopdf-base. Et le shell escape restreint activé par défaut dans TeX Live suffit : --shell-escape n'est pas requis. En mode restreint, c'est le jumeau prudent repstopdf qui est appelé ; ce n'est qu'avec --shell-escape qu'on bascule sur epstopdf lui-même. Le fichier converti reste à côté de la source sous le nom myfig-eps-converted-to.pdf. pdftex.def assortit toutefois cela d'un avertissement : lorsque l'original véritable est le PDF et non l'EPS, cette conversion automatique peut donner un résultat erroné. Pour la désactiver, écrivez \newcommand{\DoNotLoadEpstopdf}{} avant même la ligne \documentclass.

% EPS under pdflatex already works; this line only makes it explicit
\usepackage{epstopdf}

% ... and this, placed BEFORE \documentclass, switches the conversion off
% \newcommand{\DoNotLoadEpstopdf}{}

% pLaTeX / upLaTeX: the driver cannot be detected, so name it
% \usepackage[dvipdfmx]{graphicx}

Il y a aussi une raison de ne pas trop se reposer sur cette conversion automatique. Lancez pdflatex -no-shell-escape et .eps ne rejoint jamais la liste des extensions : myfig.eps a beau être là, on obtient ! LaTeX Error: File 'myfig' not found. Pire encore lorsque l'extension est écrite : \includegraphics{myfig.eps} ne produit ni erreur ni avertissement et compose sans bruit un cadre portant le nom du fichier à la place de l'image. Là où un serveur d'intégration ou la chaîne d'un coauteur emploie -no-shell-escape, le plus sûr est de convertir l'EPS en PDF à l'avance et de versionner le PDF. Pour pLaTeX / upLaTeX, dont le pilote ne peut être détecté, écrivez-le : \usepackage[dvipdfmx]{graphicx}. Si les dimensions d'un PNG, JPEG ou PDF manquent, extractbb engendre le fichier .xbb.

Quand LaTeX annonce File not found

Les erreurs liées aux images énoncent la cause en toutes lettres. Quatre d'entre elles couvrent presque tous les accidents. ! LaTeX Error: File 'plot' not found. signifie « rien n'a correspondu, quelle que soit l'extension de la liste » : faute de frappe, \graphicspath manquant, ou figure disponible seulement en EPS avec le shell escape désactivé. ! Package pdftex.def Error: File 'plot.png' not found: using draft setting. signifie « ce fichier-là manque ». ! LaTeX Error: Unknown graphics extension: .tiff. signifie « le fichier existe, mais cette chaîne ignore ce format » — ce qu'on obtient en tendant un TIFF ou un WebP. Convertissez en PNG ou en PDF.

La quatrième est d'une autre nature. ! LaTeX Error: Cannot determine size of graphic in plot.png (no BoundingBox). signifie « le fichier a été lu, mais ses dimensions restent inconnues ». Un EPS privé de sa ligne BoundingBox la déclenche, mais dans le travail quotidien la raison très majoritaire est d'avoir lancé latex alors qu'on voulait pdflatex. latex emprunte la voie DVI et charge donc dvips.def, qui ne sait pas lire les octets d'un PNG ou d'un JPEG comme des dimensions. Si toutes les figures cassent d'un coup, soupçonnez d'abord la commande de compilation.

• BoundingBox de l'EPS : ligne absente ou valeurs fausses, et la taille reste indéterminée. La réécrire avec ps2eps ou epstool.
• PDF multipage : seule la page 1 par défaut. Choisir une page avec page= ; pour insérer un document entier, utiliser le package pdfpages.
• Marges dans un PDF : de larges marges dans un PDF de figure la font paraître petite. Les rogner avec pdfcrop avant l'inclusion.
• Espaces et points dans les noms : un nom comme my plot.tar.gz rend la découpe de l'extension hasardeuse. S'en tenir aux lettres, chiffres, traits d'union et tirets bas.
• Extension écrite en dur : indiquer l'extension empêche de changer de format ensuite. En règle générale, écrire le nom sans extension.

Enfin, retenons que \includegraphics se contente de poser l'image sur place : ni numéro, ni légende. Pour écrire « voir la figure 3 » dans un article, il faut placer l'image dans un environnement figure et lui adjoindre \caption et \label. Tout ce qui suit — où [htbp] dépose réellement la figure, comment habiller la légende, comment la scinder en (a) et (b) — revient aux deux pages sœurs.