Bildformate und Einbindung

Wer \includegraphics{plot} schreibt, übergibt LaTeX keinen Dateinamen, sondern einen Namensstamm. Das Paket graphicx hängt daran in fester Reihenfolge Erweiterungen an – .pdf, .png, .jpg und so fort – und nimmt die erste Datei, die existiert. Diese eine Entwurfsentscheidung sorgt dafür, dass dieselbe Quelldatei unter pdfLaTeX, LuaLaTeX und dvipdfmx gleichermaßen übersetzt, und sie ist zugleich der Grund für die häufige Klage „Ich habe das PNG neu erzeugt, aber die Abbildung ändert sich nicht“. Diese Seite behandelt die Optionen von \includegraphics, den Suchpfad über \graphicspath, die Bildformate, die jede Engine tatsächlich liest, und das Lesen der Fehlermeldungen, wenn LaTeX eine Datei nicht findet.

graphicx und \includegraphics: warum die Erweiterung wegbleibt

Das Einbinden von Bildern übernimmt das Standardpaket graphicx: \usepackage{graphicx} deklarieren und dann \includegraphics[Optionen]{Name} schreiben. Die Erweiterung wegzulassen ist üblich, und der Grund liegt offen, sobald man hineinschaut. Die pdfTeX-Treiberdatei pdftex.def nennt die Reihenfolge der zu probierenden Erweiterungen ausdrücklich: .pdf, .png, .jpg, .mps, .jpeg, .jbig2, .jb2. Liegen also plot.pdf und plot.png im selben Ordner, gewinnt immer das PDF. Wenn ein Diagramm neu als PNG exportiert wird und die Abbildung sich trotzdem nicht rührt, liegt meist noch ein altes plot.pdf daneben. Umgekehrt gilt: Gerade weil die Erweiterung fehlt, lässt sich später ein PNG durch ein PDF ersetzen, ohne im Manuskript ein Zeichen zu ändern. graphicx ist die erweiterte Fassung des älteren Pakets graphics; der Unterschied liegt darin, dass Optionen als key=value-Paare übergeben werden. Beide gehören zum Standardbündel latex-graphics, eine zusätzliche Installation entfällt.

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

Die Erweiterung mitzuschreiben schaltet nicht nur die automatische Auswahl ab – es ändert auch den Wortlaut der Fehlermeldung. Findet \includegraphics{plot} nichts, führt der LaTeX-Kern die Suche und meldet ! LaTeX Error: File 'plot' not found. Findet \includegraphics{plot.png} nichts, antwortet stattdessen der Treiber: ! Package pdftex.def Error: File 'plot.png' not found: using draft setting. Das Erste heißt „keine Erweiterung hat gepasst“, das Zweite „genau diese eine Datei fehlt“ – und welche der beiden erscheint, verrät, wo zu suchen ist. Nebenbei: Das Paket mwe aus TeX Live legt example-image.pdf in den TeX-Baum selbst, sodass \includegraphics{example-image} aus jedem Verzeichnis heraus funktioniert. Deshalb taucht dieser Name in jedem Minimalbeispiel auf den Frageportalen auf.

Größe festlegen: width, height, scale, keepaspectratio

In der Praxis wird die Größe fast immer angegeben, und üblich ist eine Angabe relativ zum Satzspiegel, etwa width=0.8\textwidth. Absolute Werte wie 8cm lassen die Abbildung zurück, sobald auf zwei Spalten umgestellt oder das Papierformat gewechselt wird. \textwidth ist die Breite des Textblocks, \linewidth die Breite der gerade gesetzten Zeile – innerhalb einer minipage oder subfigure schrumpft sie auf die Kastenbreite. Steht im Kasten also width=\linewidth, folgt das Bild später automatisch jeder Änderung der Kastenbreite. scale= multipliziert die natürlichen Maße des Bildes, was passt, wenn diese Maße selbst etwas bedeuten; von der Textbreite weiß es nichts und läuft daher leicht über. width= ist normalerweise die sicherere Wahl.

Werden width= und height= beide angegeben, befolgt graphicx brav beides – das Seitenverhältnis bricht und das Bild wird verzerrt. keepaspectratio verhindert das: Die beiden Werte spannen dann einen Rahmen auf, und das Bild wird darin unter Wahrung seiner Proportionen so groß wie möglich gesetzt. Beim Einfüllen von Fotos in feste Plätze will man das fast immer. Eine weitere nützliche Option für Probeläufe ist draft: Sie liest das Bild gar nicht ein, sondern setzt nur einen maßhaltigen leeren Rahmen mit dem Dateinamen darin – bei Dokumenten mit Hunderten Abbildungen wird der Testlauf dadurch drastisch schneller. \usepackage[draft]{graphicx} schaltet sie für das ganze Dokument ein.

Drehen und beschneiden: angle, trim, clip, viewport

angle= nimmt einen Drehwinkel in Grad entgegen, gegen den Uhrzeigersinn gemessen. angle=90 dreht das Bild eine Vierteldrehung nach links – der Standardgriff, um ein querformatiges Diagramm auf eine Hochformatseite zu bringen. Beachtenswert ist die Reihenfolge von angle= und width=, denn graphicx wendet die Schlüssel in der notierten Reihenfolge an. [angle=90,width=6cm] heißt „drehen, dann das Ergebnis auf 6 cm Breite bringen“; [width=6cm,angle=90] heißt „auf 6 cm Breite bringen, dann drehen“ – die Endmaße unterscheiden sich. Gedreht wird standardmäßig um die linke untere Ecke; origin=c verlegt den Drehpunkt in die Mitte, origin=tr nach rechts oben.

Zum Beschneiden der Bildränder gehören trim= und clip zusammen. trim nimmt vier Werte in der Reihenfolge links, unten, rechts, oben – eine Reihenfolge, die vom PostScript-Koordinatensystem mit Ursprung links unten stammt und deshalb keiner Intuition entspricht. Die Standardeinheit ist bp (big point, ein Zweiundsiebzigstel Zoll). Und clip gehört immer dazu: Fehlt es, verschwindet der abgeschnittene Teil nicht, sondern ragt über den umgebenden Text. Negative Werte bewirken das Gegenteil und fügen Rand hinzu – ein eleganter Weg, Luft um eine Abbildung zu schaffen. Wer den Ausschnitt lieber als absolutes Rechteck angibt statt als vier abzutragende Beträge, nimmt viewport=, ebenfalls zusammen mit 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}

Mit \graphicspath auf einen Bilderordner zeigen

Liegen die Bilder in einem eigenen Ordner, ergänzt \graphicspath den Suchpfad. Jedes Verzeichnis kommt in ein eigenes Klammerpaar – auch wenn es nur eines ist – und endet mit einem Schrägstrich /, unter Windows ebenfalls mit /. Die Suchreihenfolge lässt sich im Versuch bestätigen: Ein gleichnamiges Bild im aktuellen Verzeichnis gewinnt ohne Weiteres, sonst werden die Verzeichnisse in der notierten Reihenfolge durchprobiert, der erste Treffer zählt. \graphicspath{{figures/}{old-figures/}} ergibt damit eine praktische Anordnung: Eine neue Fassung in figures/ verdeckt automatisch die alte, und nur die noch nicht überarbeiteten Abbildungen stammen aus old-figures/. Ein Pfad mit Leerzeichen gehört in Anführungszeichen, etwa {"my figures/"}. Soll die Liste der Erweiterungen selbst geändert werden, dient \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 oder PNG: Vektor oder Raster wählen

Es gibt im Grunde ein Kriterium: Was aus Linien und Text besteht, gehört als Vektor ins Dokument, was kontinuierliche Tonwerte hat, als Raster. Vektorbilder (PDF, EPS, SVG) beschreiben Punkte, Linien und Kurven als Koordinaten; die Konturen werden bei jeder Vergrößerung neu berechnet, und die Druckauflösung spielt keinerlei Rolle. Diagramme, Schaltbilder und Zeichnungen mit Formeln gehören hierher. Rasterbilder (PNG, JPEG) sind ein Gitter farbiger Pixel; beim Vergrößern werden die Pixel schlicht größer. Fotos und Screenshots gehören hierher, und für den Druck sollten die Ausgangsdaten 300 dpi oder mehr haben. Ein Foto zu vektorisieren bringt nichts und bläht nur die Datei auf. Wird eine Abbildung in LaTeX selbst erzeugt – TikZ, pgfplots –, ist die Ausgabe von vornherein vektorbasiert.

Innerhalb der Rasterformate genügt eine kurze Faustregel: JPEG für Fotos, PNG für alles andere. JPEG komprimiert verlustbehaftet und kommt mit fotografischen Tonwerten gut zurecht, verschmiert aber die Kanten von Linien und Buchstaben mit dem sogenannten Moskitorauschen – genau deshalb wirkt ein als JPEG gespeicherter Screenshot rund um den Text schmuddelig. PNG arbeitet verlustfrei, kennt Transparenz und passt zu flächigen Grafiken und Screenshots. SVG liest dagegen keine Engine direkt. Das Paket svg erlaubt zwar \includesvg{file}, ruft dahinter aber die Kommandozeile von Inkscape auf, um nach PDF (bei DVI-Ausgabe nach EPS) zu wandeln, und schreibt den Text aus dem SVG in eine eigene Datei, die LaTeX neu setzt. Nötig sind ein installiertes Inkscape und ein Lauf mit --shell-escape. Wer Verlässlichkeit will, exportiert vorab mit Inkscape oder Ähnlichem nach PDF. In der Gegenrichtung, wenn SVG aus TeX-Ausgabe entstehen soll, ist dvisvgm das Werkzeug.

Welche Formate welche Engine liest – und ob EPS wirklich scheitert

Über die akzeptierten Formate entscheidet nicht die Engine, sondern die dahinterliegende Treiberdatei. Beim Start ermittelt graphics.cfg, welche Engine läuft, und lädt pdftex.def für pdfTeX, xetex.def für XeTeX, dvips.def bei DVI-Ausgabe; die dort deklarierte Erweiterungsliste ist genau die Menge der unterstützten Formate. Daraus folgen zwei Korrekturen an der üblichen Darstellung. Erstens: XeLaTeX und dvipdfmx verarbeiten EPS und PS direkt. Die Listen in xetex.def und dvipdfmx.def enthalten .eps und .ps und darüber hinaus .ai, .bmp und .jp2. Zweitens: Auch pdfLaTeX und LuaLaTeX lesen EPS – praktisch gesehen.

Wie pdfLaTeX EPS durchbekommt, steht in pdftex.def. Bei \begin{document} hängt diese Datei, sofern Shell-Escape aktiv ist, selbst .eps an die Erweiterungsliste und lädt epstopdf-base. Und das in TeX Live voreingestellte eingeschränkte Shell-Escape genügt – --shell-escape ist nicht nötig. Im eingeschränkten Modus wird der sichere Zwilling repstopdf aufgerufen; erst mit --shell-escape wird auf epstopdf selbst umgeschaltet. Das Ergebnis landet neben der Quelle unter dem Namen myfig-eps-converted-to.pdf. pdftex.def gibt allerdings selbst einen Warnhinweis: Ist nicht das EPS, sondern das PDF das eigentliche Original, kann diese automatische Umwandlung ein falsches Ergebnis liefern. Abschalten lässt sie sich mit \newcommand{\DoNotLoadEpstopdf}{} noch vor der Zeile \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}

Es gibt auch einen Grund, sich nicht auf diese Automatik zu verlassen. Läuft pdflatex -no-shell-escape, tritt .eps der Erweiterungsliste nie bei, und myfig.eps liegt zwar bereit, es kommt aber ! LaTeX Error: File 'myfig' not found. Schlimmer ist der Fall mit ausgeschriebener Erweiterung: \includegraphics{myfig.eps} liefert dann weder Fehler noch Warnung und setzt still einen gerahmten Kasten mit dem Dateinamen statt des Bildes. Wo ein Build-Server oder die Werkzeugkette einer Mitautorin -no-shell-escape verwendet, ist es sicherer, EPS vorab nach PDF zu wandeln und das PDF zu versionieren. Bei pLaTeX / upLaTeX lässt sich der Treiber nicht erkennen, deshalb gehört er hingeschrieben: \usepackage[dvipdfmx]{graphicx}. Werden Maßangaben zu PNG, JPEG oder PDF gebraucht, erzeugt extractbb die .xbb-Datei.

Wenn LaTeX „File not found“ meldet

Fehler rund um Bilder benennen die Ursache im Klartext. Vier davon decken fast jeden Unfall ab. ! LaTeX Error: File 'plot' not found. heißt „unter keiner Erweiterung der Liste hat etwas gepasst“ – Tippfehler, fehlendes \graphicspath oder eine nur als EPS vorliegende Abbildung bei abgeschaltetem Shell-Escape. ! Package pdftex.def Error: File 'plot.png' not found: using draft setting. heißt „genau diese eine Datei fehlt“. ! LaTeX Error: Unknown graphics extension: .tiff. heißt „die Datei ist da, aber dieser Weg kennt das Format nicht“ – so endet die Übergabe eines TIFF oder WebP. In PNG oder PDF umwandeln.

Der vierte hat einen anderen Charakter. ! LaTeX Error: Cannot determine size of graphic in plot.png (no BoundingBox). heißt „die Datei war lesbar, aber ihre Maße sind unbekannt“. Ein EPS ohne BoundingBox-Zeile löst das aus, im Alltag ist der Grund jedoch weit überwiegend, dass latex gestartet wurde, wo pdflatex gemeint war. latex nimmt den DVI-Weg, lädt also dvips.def, und dieses kann die Bytes eines PNG oder JPEG nicht als Maße deuten. Brechen plötzlich alle Abbildungen, gehört der Übersetzungsbefehl zuerst unter Verdacht.

• EPS-BoundingBox: Fehlt die Zeile oder stimmen die Werte nicht, bleibt die Größe unbestimmt. Mit ps2eps oder epstool neu schreiben.
• Mehrseitiges PDF: standardmäßig nur Seite 1. Mit page= eine Seite wählen; für ein ganzes Dokument dient das Paket pdfpages.
• Weißraum im PDF: Große Ränder in einem Abbildungs-PDF lassen die Abbildung klein wirken. Vor dem Einbinden mit pdfcrop beschneiden.
• Leerzeichen und Punkte im Dateinamen: Namen wie my plot.tar.gz erschweren das Abtrennen der Erweiterung. Bei Buchstaben, Ziffern, Bindestrichen und Unterstrichen bleiben.
• Fest codierte Erweiterung: Eine angegebene Erweiterung verhindert späteren Formatwechsel. In der Regel ohne Erweiterung schreiben.

Zum Schluss sei festgehalten: \includegraphics setzt das Bild lediglich an Ort und Stelle – ohne Nummer, ohne Bildunterschrift. Um in einer Arbeit „siehe Abbildung 3“ schreiben zu können, gehört das Bild in eine figure-Umgebung mit \caption und \label. Alles Weitere – wo [htbp] die Abbildung tatsächlich absetzt, wie die Unterschrift gestaltet wird, wie sich (a) und (b) trennen lassen – ist Sache der beiden Schwesterseiten.