22.3.1 \includegraphics

Synopsis pour le paquetage graphics :

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

Synopsis pour le paquetage graphicx :

\includegraphics{nomfichier}
\includegraphics[liste-à-clefs-valeurs]{nomfichier}
\includegraphics*{nomfichier}
\includegraphics*[liste-à-clefs-valeurs]{nomfichier}

Inclut un fichier graphique. La forme étoilée \includegraphics* rogne le graphique à la taille spécifiée, alors que pour la forme non-étoilée toute partie du graphique en dehors de la boîte de la taille spécifiée se superpose à ce qui l’entoure.

Dans cet exemple

\usepackage{graphicx}  % dans le préambule
  ...
\begin{center}
  \includegraphics{trace.pdf}
\end{center}

on incorpore dans le document le graphique dans plot.pdf, centré et à sa taille nominale. Vous pouvez aussi donner un chemin au fichier, comme dans \includegraphics{graphiques/trace.pdf}. Pour spécifier une liste de répertoire ou rechercher le fichier, voir \graphicspath.

Si votre nom de fichier comprend des espaces, alors placer le entre guillemets anglais. Par exemple comme dans \includegraphics{"image complementaire.jpg"}.

La commande \includegraphics{nomfichier} décide du type de graphique en segmentant nomfichier sur le premier point (‘.’). Vous pouvez utiliser nomfichier sans extension de nom de fichier, comme dans \includegraphics{turing} et LaTeX essaie une séquence d’extension telle que .png et .pdf jusqu’à ce qu’il trouve un fichier avec cette extension (voir \DeclareGraphicsExtensions).

Si votre fichier comprend des points avant l’extension alors vous pouvez les cacher avec des accolades, comme dans \includegraphics{{plot.2018.03.12.a}.pdf}. Ou, si vous utilisez le paquetage graphicx alors vous pouvez utiliser les options type et ext ; voir plus bas. Ces problèmes de noms de fichiers, et d’autres sont aussi traités par le paquetage grffile.

L’exemple ci-après place un graphique dans un environnement figure de sorte que LaTeX puisse le déplacer sur la page suivante si le faire rentrer dans la page courante rend mal (voir figure).

\begin{figure}
  \centering
  \includegraphics[width=3cm]{rayonxpoumon.jpg}
  \caption{Ça saute aux yeux : vous ne devriez arrêter de fumer}  \label{fig:rayon-x}
\end{figure}

L’exemple suivant place un graphique non flottant, de sorte à garantir qu’il apparaisse à ce point-ci du document même si cela oblige LaTeX à dilater le texte ou à recourir à des zones blanches sur la page. Le graphique est centré est a une légende.

\usepackage{caption}  % dans le préambule
  ...
\begin{center}
  \includegraphics{sans/images.png}
  \captionof{figure}{L'esprit de la nuit} \label{sans:images} % optionnel
\end{center}

L’exemple suivant place une boîte avec un graphique le long d’une autre boîte contenant du texte, les deux boîtes étant verticalement centrées :

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

Si vous utilisez le paquetage graphics alors les seules options disponibles concernent la taille du graphique (mais voir \rotatebox et \scalebox). Quand un argument optionnel est présent alors c’est [urx,ury] et il donne les coordonnées du coin en haut à droite de l’image, comme une paire de dimensions TeX (voir Units of length). Si les unités sont omises, alors par défaut l’unité considérée est le bp. Dans ce cas, le coin en bas à gauche de l’image est supposé être à (0,0). Si deux arguments optionnels sont présents alors le premier est [llx,lly], et il spécifie les coordonnées du coin en bas à gauche de l’image. Ainsi, \includegraphics[1in,0.618in]{...} demande que le graphique soit placé de sorte a avoir 1 pouce de largeur et 0,618 pouces de hauteur et donc son origine est à (0,0).

Le paquetage graphicx vous offre beaucoup plus d’options. Spécifiez les sous la forme de paires clef-valeur, comme ci-après :

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

Les options sont lues de gauche à droite. Ainsi le premier graphique ci-dessus est dilaté à une largeur de 3cm, et ensuite subit une rotation de 90degrés, alors que le second subit la rotation en premier et ensuite est dilaté à 3cm de largeur. Ainsi, à moins que le graphique soit parfaitement carré, à la fin les deux n’ont pas les mêmes largeurs et hauteurs.

Il y a beaucoup d’options. Les principales sont listées en premier.

Notez qu’un graphique est placé par LaTeX dans une boîte, qu’on désigne traditionnellement comme sa boîte englobante (distincte de la BoundingBox PostScript décrite plus bas). La zone sur laquelle le graphique s’imprime peut aller au delà de cette boîte, ou s’inscrire dans cette boîte, mais quand LaTeX fabrique une page il assemble des boîtes, et celle-ci est la boîte allouée pour le graphique.

width

Le graphique est affiché de sorte que sa boîte englobante ait cette largeur. Un exemple est \includegraphics[width=2.5cm]{trace}. Vous pouvez utiliser les unités de longueur standardes de TeX (voir Units of length) et également il est commode d’utiliser \linewidth, ou, dans un document recto-verso, \columnwidth (voir Page layout parameters). Un exemple est qu’en utilisant le paquetage calc vous pouvez rendre le graphique 1cm plus étroit que la largeur du texte avec \includegraphics[width=\linewidth-1.0cm]{hefferon.jpg}.

height

Le graphique est affiché de sorte que sa boîte englobante est de cette hauteur. Vous pouvez utiliser les unités de longueur standardes de TeX (voir Units of length), et également il est commode d’utiliser \pageheight et \textheight (voir Page layout parameters). Par exemple, la commande \includegraphics[height=0.25\textheight]{godel} rend le graphique d’une hauteur d’un quart de celle de la zone de texte.

totalheight

Le graphique est affiché de sorte que sa boîte englobante ait cette hauteur plus profondeur. Ceci diffère de la hauteur si le graphique a subi une rotation. Par exemple, s’il a subi une rotation de -90 degrés alors il a une hauteur nulle mais une grande profondeur.

keepaspectratio

Si réglé à true, ou juste spécifié comme ci-dessous

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

et que vous donnez en option à la fois width et height (ou totalheight), alors LaTeX rendra le graphique aussi grand que possible sans le déformer. C’est à dire que LaTeX assure que le graphique n’est ni plus large que width ni plus haut que height (ou totalheight).

scale

Facteur par lequel dilater/contracter le graphique. On peut rendre graphique à deux fois sa taille nominale avec \includegraphics[scale=2.0]{...}. Ce nombre peut prendre n’importe quelle valeur ; un nombre entre 0 et 1 contracte le graphique et un nombre négatif lui applique une réflexion.

angle

Applique une rotation au graphique. L’angle est exprimé en degrés et dans le sens antihoraire. La rotation est effectuée autour de l’origine donnée par l’option origin ; s’y référer. Pour une description complète de la composition de matière ayant subi une rotation, voir \rotatebox.

origin

Le point du graphique autour duquel la rotation s’effectue. Les valeurs possibles sont toute chaîne contenant un ou deux caractères parmi : l pour gauche (left), r pour droite (right), b pour bas, c pour centré, t pour haut (top), et B pour ligne de base. Ainsi, saisir la commande \includegraphics[angle=180,origin=c]{moon} a pour effet de mettre la figure tête en bas en tournant autour du centre de l’image, alors que la commande \includegraphics[angle=180,origin=lB]{LeBateau} fait la rotation autour du point gauche de la ligne de base. (Le caractère c désigne le centre horizontal dans bc ou tc, mais le centre vertical dans lc rc). Le réglage par défaut est lB.

Pour faire une rotation autour d’un point arbitraire, voir \rotatebox.

Voici maintenant des options moins usuelles.

viewport

Désigne une sous-région du graphique à afficher. Prend quatre arguments, séparés par des espaces et exprimés comme des dimensions TeX, comme dans \includegraphics[.., viewport=0in 0in 1in 0.618in]{...}. Quand l’unité est omise, les dimensions sont par défaut en big points, bp. Elle sont prises relativement à l’origine spécifiée par la boîte englobante. Voir aussi l’option trim.

trim

Désigne les parties du graphique à ne pas afficher. Prend quatre arguments, séparés par des espaces, et exprimés comme des dimensions TeX dimensions, comme dans \includegraphics[.., trim= 0in 0.1in 0.2in 0.3in, ...]{...}. Ceci donne la quantité du graphique à ne pas afficher, c.-à-d. que LaTeX rogne l’image de 0 pouce sur la gauche left, 0.1 pouce sur la bas, 0.2 pouce sur la droite, et 0.3 pouce sur le haut. Voir aussi l’option viewport.

clip

Si réglé à true, ou juste spécifié comme ci-dessous

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

alors le graphique est rogné à sa boîte englobante. Ceci revient au même que d’utiliser la forme étoilée de la commande, \includegraphics*[...]{...}.

page

Donne le numéro de page pour un fichier PDF multi-page. La valeur par défaut est page=1.

pagebox

Spécifie quelle boîte englobante utiliser pour les fichiers PDF parmi les suivantes mediabox, cropbox, bleedbox, trimbox, ou artbox. Les fichiers PDF n’ont pas la BoundingBox que les fichiers PostScript ont, mais peuvent spécifier jusqu’à quatre rectangles prédéfinis. La boîte mediabox donne les frontières du médium physique. La boîte cropbox est la région à laquelle le contenu de la page devrait être épinglé quand il est affiché. La boite bleedbox la région à laquelle le contenu de la page devrait être épinglé en production. La boîte trimbox est correspond aux dimensions désirées de la page finie. La boîte artbox est de l’étendue du contenu de la page ayant du sens. Le pilote règle la taille de l’image en se basant sur la cropbox si elle est présente, sinon il n’utilise pas les autres, avec un ordre de préférence propre au pilote. La boîte mediabox est toujours présente.

interpolate

Active ou désactive l’interpolation des images matricielles par la visionneuse. On peut régler l’option avec interpolate=true ou juste comme ci-dessous :

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

quiet

N’écrit pas d’information dans le journal. On peut régler l’option avec quiet=true ou juste en la spécifiant avec \includegraphics[...,quiet,...]{...},

draft

Lorsqu’on règle l’option avec draft=true ou juste ainsi

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

alors le graphique n’apparaît pas dans le document, ce qui permet éventuellement d’économiser l’imprimante couleur. À la place LaTeX place une boîte vide de la bonne taille avec le nom du fichier imprimé dedans.

Les options suivantes traitent de la boîte englobante pour les fichiers graphique de type PostScript Encapsulé, leur taille est spécifié avec une ligne %%BoundingBox qui apparaît dans le fichier. Elle a quatre valeurs donnant la coordonnée x inférieure, la coordonnée y inférieure, la coordonnée x supérieure, et la coordonnée y supérieure. L’unité est le point PostScript, équivalent au big point de TeX, à savoir 1/72 de pouce. Par exemple, si un fichier .eps a la ligne %%BoundingBox 10 20 40 80 alors sa taille naturelle est 30/72 de pouce de large pour 60/72 de pouce de haut.

bb

Spécifie la boîte englobante de la région affichée. L’argument est constitué de quatre dimensions séparées par des espaces, comme dans \includegraphics[.., bb= 0in 0in 1in 0.618in]{...}. D’ordinaire \includegraphics lit les ces nombre BoundingBox dans le fichier EPS automatiquement, de sorte que cette option n’est utile que si la définition de la boîte englobante est absente du fichier ou si vous désirez la changer.

bbllx, bblly, bburx, bbury

Règle la boîte englobante. Ces quatre options là sont obsolètes, mais existent encore pour maintenir la rétrocompatibilité avec des paquetages anciens.

natwidth, natheight

Une alternative à bb. Régler

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

revient au même que régler bb=0 0 1in 0.618in.

hiresbb

Si réglé à true, ou juste spécifié comme dans

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

alors LaTeX recherche la ligne %%HiResBoundingBox plutôt que la ligne %%BoundingBox. (La ligne BoundingBox n’utilise que des nombres entiers naturels alors que la ligne HiResBoundingBox utilise des décimaux ; les deux utilisent une unité équivalente au big point de TeX, 1/72 de pouce). Pour l’emporter sur un réglage précédent à true, on peut la régler à false.

Les options suivantes permettent à l’utilisateur de l’emporter sur la méthode par laquelle LaTeX choisit le type d’un graphique en fonction de son extension de nom de fichier. Par exemple avec \includegraphics[type=png,ext=.xxx,read=.xxx]{lion} le fichier lion.xxx est lu comme s’il s’agissait de lion.png. Pour plus ample information, voir \DeclareGraphicsRule.

type

Spécifie le type de graphique.

ext

Spécifie l’extension du graphique. À n’utiliser qu’en conjonction avec l’option type.

read

Spécifie l’extension du fichier lu. À n’utiliser qu’en conjonction avec l’option type.

command

Spécifie une commande à appliquer à ce fichier. À n’utiliser qu’en conjonction avec l’option type. Voir Command line options, pour une discussion sur l’activation de la fonctionnalité \write18 pour exécuter des commandes externes.