# How can/should I include annotated images?

It's often the case that I'd like to include some graphic in a LaTeX document and overlay it with some text or other annotation, maybe including arrows or other simple graphics. The annotations can be easily handled using TikZ, so obviously if I create the graphic itself in TikZ, I'm all set. But sometimes the graphic is very complex and it's not practical to recreate it with TikZ commands. In these cases, I would like to include the graphic file directly, but still be able to layer my annotations over it. Editing the image to include the annotation is a possibility, but I'd really like to avoid that because the annotations then wouldn't reflect the document's font style and size, and also because it'd be harder to change them.

Is there a preferred way to include an external image and then layer additional content over it? A solution that lets me continue to use TikZ for the annotations is preferred, but not required.

EDIT: All three answers (overpic, a TikZ node, and \pgftext) work fine, but unfortunately I can only accept one, so I'm going with the one recommended in the "official source," the TikZ manual.

-
Related: Drawing on an image with TikZ –  Jake May 2 '12 at 11:48

The pgf/TikZ manual suggests using the command \pgftext to insert external graphics (section 53.3.3 "Inserting Text and Images"). Here's an example taken from this seminar (slides 5 and 6 in the presentation version):

\begin{figure}
\begin{tikzpicture}
\pgftext{%
\includegraphics[width=\textwidth]{Bridge05a}%
}%
\node[fill=black, opacity=.5, text opacity=1] at (0,.5) {\Large \color{yellow} Geometry};
\node[fill=black, opacity=.5, text opacity=1] at (0,-.5) {\Large \color{red} \emph{Manifolds}};
\node[fill=black, opacity=.5, text opacity=1] at (-4,.5) {\Large \color{yellow} Algebra};
\node[fill=black, opacity=.5, text opacity=1] at (4,.5) {\Large \color{yellow} Analysis};
\end{tikzpicture}
\end{figure}


There is also a hint elsewhere in the manual (in 53.3.1) that the command \pgfimage can be used instead of \includegraphics (although still within the \pgftext command); however, searching for \pgfimage in the manual doesn't turn up any further explanation of this command.

The \pgftext command is something of a special command. It "escapes" out of the current picture back to "normal TeX". It is, therefore, somewhat like a \node command. It works by constructing a box which is then put into the picture. By default this box is put at the current origin. A simple way to move it, therefore, is to (temporarily) tell TikZ/PGF to move the origin priori to issuing the \pgftext command.

An alternative way of positioning it is to use the initial optional argument. Thus one can say \pgftext[<positioning information>]{text} where <positioning information> is some set of PGF keys that relocate the box. These are similar to the positioning of a \node, but have a slightly "low level" feel to them. For example, to locate the box at a particular point one would say \pgftext[at={\pgfpoint{1cm}{2cm}}]{text}. Note the \pgfpoint syntax rather than the TikZ coordinate syntax.

In the 2.10-CVS version of the manual, the \pgftext command is documented in Section 77.3.3. There is also some important information about how it interacts with scopes in Section 77.1.2 (note especially item 5 about the ability to put another pgfpicture inside a \pgftext command, something that should never be done with \node!).

In summary, \pgftext is somewhat akin to \node in that it allows you to put "normal TeX" in your picture. However, the two are different in that a \node is considered part of the picture but \pgftext is for things that are meant to be somewhat separate.

-
In the newest CVS versions of the manual, the following statements is present: "To be quite frank, LATEX’s \includegraphics is designed better than pgf’s image mechanism" in section 81.1. The manual goes on to explain that \pgfimage is primarily intended for use with plain TeX which has no "out of the box" support for image inclusion. –  Sharpie Aug 10 '10 at 9:16
@Sharpie: thanks for the clarification. –  Loop Space Aug 10 '10 at 9:43
For the record, I did some hunting and found that \pgfuseimage is part of a pair: first \pgfdeclareimage[options]{name}{filename} to declare the image, then \pgfuseimage{name} to actually include it. Pretty much the same way shadings work. Good to know it's maybe not the optimal method, though. –  David Z Aug 11 '10 at 1:52
One advantage of \pgfdeclareimage...\pgfuseimage over \includegraphics is with beamer: if you have an image on a frame with multiple overlays, the latter will embed the image into the pdf once for each overlay. The former will embed it once and reuse it in later overlays. –  Matthew Leingang Oct 11 '10 at 15:27
@PaulGaborit Using \node is Sharpie's answer so the content of your suggestion is already present in this list of answers. If, as you say (and I'm prepared to believe you), it is the Right Way To Do Things then perhaps you could add a comment to Sharpie's answer explaining why, then others can make an informed choice. It's pretty clear from the edit to the question that all answers work so if you provide some concrete reason to prefer one over another then that will help others decide which one to use. –  Loop Space Mar 8 '13 at 9:34

Using TikZ, you can include the image inside a \node:

\node[anchor=south west, inner sep=0pt, outer sep=0pt]
(image) at (0,0) {\includegraphics{image}};


Then draw away:

\draw (image.south west) -- ++(1,1);

\coordinate[at = 1in of image.west] (pathStart);
\draw (pathStart) -- ++(42,13);

% Etc.


There is a complete example at this site.

If you are creating graphics such as plots, you can use the R programming language along with the tikzDevice package that an associate and I developed. The tikzDevice encodes graphics created by R into TeX commands. We just released a new version, 0.5.0, that includes support for inserting named coordinates into the generated figures so that they may be further annotated by TikZ commands.

-
Just to note: TikZ can also use gnuplot to generate plots: gnuplot figures out the data points and TikZ renders them. –  Loop Space Aug 10 '10 at 7:54
Thanks for the tip, but I don't really have a use for R/tikzDevice. The particular image that prompted me to ask this question was a 5MB PDF so I expect it would be an unreasonably long list of TikZ commands. –  David Z Aug 11 '10 at 1:44

The overpic package sounds to be just what you're after. From the package description:

The overpic environment is a cross between the LaTeX picture environment and the \includegraphics command of graphicx. The resulting picture environment has the same dimensions as the included eps graphic. LaTeX commands can be placed on the graphic at defined positions. A grid for orientation is available.

Note that it is possible to use other graphics formats besides .eps -- anything you'd be able to use with \includegraphics will still work with this package.

-