\subsection{\tikzname\ Interoperability}
\label{pgfplots:tikz:interoperability}

\PGFPlots\ is built on top of \Tikz/\pgfname, and it inherits most of power to visualize plots. However, their coordinate systems do not match up -- for good reason: \PGFPlots\ operates on logical (data) coordinates whereas \Tikz\ operates on image coordinates. 

Occasionally, one may want to synchronize both in order to generate a graphic -- and the question arises how to match the coordinates from \Tikz\ to \PGFPlots\ and vice--versa. This section explains how to match coordinates and it discusses the necessary restrictions.

There are a couple of keys in \PGFPlots\ which control the mapping of coordinates. The purpose of these keys is to implement visualization techniques, but they do things different than \Tikz\ (and they should). To match coordinates with \Tikz, one needs the following aspects:
\begin{enumerate}
	\item Restrict your visualization type: a logarithmic axis simply may not fit into \Tikz\ (to be more precise: it may fit, but a \Tikz\ unit will correspond to a log--unit in \PGFPlots).

	\item Configure matching unit vectors by means of the |x| and |y| keys. The default configuration of \Tikz\ is to use |x=1cm,y=1cm,z={(0,0)}|. Note that these settings are usually overridden by \PGFPlots\ in order to respect |width| and |height| (and |view| for three--dimensional axes).
	\item Disable the data scaling by means of |disabledatascaling|: \PGFPlots\ will internally apply linear coordinate transformations in order to provide the data range required for floating point arithmetics (using approximately floating point precision). Disabling the data scaling means to restrict yourself to the (small) data range supported by \Tikz---but that's probably what you want in that case.
	\item Define |anchor| and position of the |axis|, probably using |anchor=origin,at={(0,0)}|. The |at={(0,0)}| configures \PGFPlots\ to place the axis at the \Tikz\ position |(0,0)| whereas |anchor=origin| means that \PGFPlots\ will place its data origin $(0,0,0)$ at the place designated by |at| (see Section~\ref{pgfplots:sec:align} for details).

	\item Make sure that the \PGFPlots\ axis contains the data origin $(0,0,0)$ in the displayed data range (i.e.\ configure |xmin|, |xmax|, |ymin|, and |ymax| appropriately).

	Without this, the |anchor=origin| key required in the previous item will be truncated to the next coordinate which is part of the displayed range.
\end{enumerate}

\noindent Here is a simple example, first with \Tikz:
\begin{codeexample}[]
\begin{tikzpicture}
\coordinate (Point) at (1,2);

\draw [gray] (-1,-1) grid (3,3);
\draw [blue,fill] (Point) circle (2pt)
	node [right] {(1,2)};
\end{tikzpicture}
\end{codeexample}
\noindent it displays a grid with $x,y\in[-1,3]$ and shows a node inside of it.
Now, we apply the keys discussed above to match this setting in \PGFPlots:
\begin{codeexample}[]
\begin{tikzpicture}
    \coordinate (Point) at (1,2);

\begin{axis}[
	% tell pgfplots to "grab" the axis at its 
	% internal (0,0) coord:
    anchor=origin,      
	% tell pgfplots to place its anchor at (0,0):
	% (This is actually the default and can
	% be omitted)
    at={(0pt,0pt)},
	% tell pgfplots to use the "natural" dimensions:
    disabledatascaling,
	% tell pgfplots to use the same unit vectors
	% as tikz:
    x=1cm,y=1cm,
    %
    % this is just as usual in pgfplots. I guess 
	% it is only useful if (0,0) is part of the 
	% range... try it out.
    xmin=-1,xmax=3, ymin=-1,ymax=3,grid=both] 
% this uses the point defined OUTSIDE of the axis
\draw [blue,fill] (Point) circle (2pt) 
	node [right] {(1,2)};

% this uses a TIKZ coordinate (2,0) in the axis:
\draw [blue,fill] (2,0) circle (2pt) 
	node [right] {(2,0)};

% this here will always work inside of an axis:
\draw [blue,fill] (axis cs:-1,0) circle (2pt) 
	node [right] {(-1,0)};
\end{axis}
\end{tikzpicture}
\end{codeexample}
	\noindent The example demonstrates several things: first, it defines a coordinate in the enclosing |tikzpicture| and uses it inside of the |axis| (at the correct position). Second, it uses the standard \Tikz\ coordinate |(2,0)| inside of the |axis|, and it is placed at the expected position. Third, it uses the approach provided by \PGFPlots\ by using the |axis cs| to designate a coordinate (this last approach does also work without the coordinate matching).

Here is an example which inserts a \PGFPlots\ graphics correctly into a |tikzpicture|:
% \usepgfplotslibrary{patchplots}
\begin{codeexample}[]
% requires \usepgfplotslibrary{patchplots}
\begin{tikzpicture}
\begin{axis}[
	% tell pgfplots to "grab" the axis at its internal (0,0) coord:
    anchor=origin,      
	% tell pgfplots to place its anchor at (0,0):
	% (This is actually the default and can be omitted)
    at={(0pt,0pt)},
	% tell pgfplots to use the "natural" dimensions:
    disabledatascaling,
	% tell pgfplots to use the same unit vectors as tikz:
    x=1cm,y=1cm,
	%
	hide axis,
]
\addplot[patch,patch type=coons,
	shader=interp,point meta=explicit] 
coordinates {
	(0,0)   [0] % first corner
	(1,-1)  [0] % bezier control point between (0) and (3)
	(4,0.7) [0] % bezier control point between (0) and (3)
	%
	(3,2)   [1] % second corner
	(4,3.5) [1] % bezier control point between (3) and (6)
	(7,2)   [1] % bezier control point between (3) and (6)
	%
	(7,1)      [2] % third corner
	(6,0.6)    [2] % bezier control point between (6) and (9)
	(4.5,-0.5) [2] % bezier control point between (6) and (9)
	%
	(5,-2)   [3] % fourth corner
	(4,-2.5) [3] % bezier control point between (9) and (0)
	(-1,-2)  [3] % bezier control point between (9) and (0)
};
\end{axis}

% this requires pgf 2.10 
\begin{scope}[every node/.style={circle,inner sep=2pt,fill=black}]
\node[pin=140:first] at (0,0) {};
\node[pin=second]    at (3,2) {};
\node[pin=45:third]  at (7,1) {};
\node[pin=0:fourth]  at (5,-2) {};
\end{scope}
\end{tikzpicture}
\end{codeexample}
\noindent The example employs one of the |patch| plots of the |patchplots| library. Since these graphical elements typically require depth information (|z buffer|ing) and color data (|point meta|), they are only available inside of \PGFPlots. However, the configuration above ensures that coordinates match one-to-one between \PGFPlots\ and \Tikz. The |hide axis| flag disables anything of \PGFPlots, so only the visualized |patch| plot remains\footnote{Note that the $(0,0,0)$ coordinate of \PGFPlots\ is part of the data range here.}.


