summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/latex/pgfplots/pgfplots.reference.axis-addplot.tex
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-dist/doc/latex/pgfplots/pgfplots.reference.axis-addplot.tex')
-rw-r--r--Master/texmf-dist/doc/latex/pgfplots/pgfplots.reference.axis-addplot.tex335
1 files changed, 304 insertions, 31 deletions
diff --git a/Master/texmf-dist/doc/latex/pgfplots/pgfplots.reference.axis-addplot.tex b/Master/texmf-dist/doc/latex/pgfplots/pgfplots.reference.axis-addplot.tex
index 2f4884e4cff..7aa6b11237c 100644
--- a/Master/texmf-dist/doc/latex/pgfplots/pgfplots.reference.axis-addplot.tex
+++ b/Master/texmf-dist/doc/latex/pgfplots/pgfplots.reference.axis-addplot.tex
@@ -30,7 +30,7 @@ Use
\end{codeexample}
to install styles specifically for the case with |xmode=log|, |ymode=normal|.
-The logarithmic scaling means to apply the natural logarithm (base $e$) to each $x$ coordinate. Furthermore, ticks will be typeset as $10^{\text{\meta{exponent}}}$, see section~\ref{sec:number:printing} for more details.
+The logarithmic scaling means to apply the natural logarithm (base $e$) to each $x$ coordinate. Furthermore, ticks will be typeset as $10^{\text{\meta{exponent}}}$, see Section~\ref{sec:number:printing} for more details.
\end{environment}
\begin{environment}{{semilogyaxis}\oarg{options}}
@@ -42,7 +42,7 @@ The same remarks as for |semilogxaxis| apply here as well.
\end{environment}
\begin{environment}{{loglogaxis}\oarg{options}}
-The axis environment for logarithmic scaling of both, $x$~and~$y$ axes,
+The axis environment for logarithmic scaling of both, $x$~and~$y$ axes.
As for the other axis possibilities, there is a style `|every loglog axis|' which is installed at the environment's beginning.
The same remarks as for |semilogxaxis| apply here as well.
@@ -61,6 +61,8 @@ They are all equivalent to
with properly set variables `|xmode|' and `|ymode|' (see below).
\subsection{The \protect\texttt{\protect\textbackslash addplot} Command: Coordinate Input}
+{
+\tikzset{external/figure name/.add={}{addplot_}}%
\label{sec:addplot}%
\begin{codeexample}[]
\begin{tikzpicture}
@@ -137,11 +139,11 @@ Inside of an axis environment, the |\addplot| command is the main user interface
\begin{command}{\addplot\oarg{options} \meta{input data} \meta{trailing path commands};}
\label{cmd:pgfplots:addplot}
-This is the main plotting command, available within each axis environment. It can be used one or more times within an axis to add plots to the current axis. There is also an \verbpdfref{\addplot3} command which is described in section~\ref{sec:3d}.
+This is the main plotting command, available within each axis environment. It can be used one or more times within an axis to add plots to the current axis. There is also an \verbpdfref{\addplot3} command which is described in Section~\ref{sec:3d}.
It reads point coordinates from one of the available input sources specified by \meta{input data}, updates limits, remembers \meta{options} for use in a legend (if any) and applies any necessary coordinate transformations (or logarithms).
-The \meta{options} can be omitted in which case the next entry from the |cycle list| will be inserted as \meta{options}. These keys characterize the plot's type like linear interpolation, smooth plot, constant interpolation, bar plot, mesh plots, surface plots or whatever and define colors, markers and line specifications\footnote{In version 1.2.2 and earlier, there was an explicit distinction between ``behaviour'' options like error bars, domain, number of samples etc.\ and ``style options'' like color, line width, markers etc. This distinction is obsolete now, simply collect everything into \meta{options}.}\index{Behavior Options}\index{Options!Distinction Behavior, Style Options}. Plot variants like error bars, the number of samples or a sample domain can also be configured in \meta{options}.
+The \meta{options} can be omitted in which case the next entry from the |cycle list| will be inserted as \meta{options}. These keys characterize the plot's type like linear interpolation with |sharp plot|, |smooth| plot, constant interpolation with |const plot|, |bar| plot, |mesh| plots, |surf|ace plots or whatever and define |color|s, |mark|ers and line specifications\footnote{In version 1.2.2 and earlier, there was an explicit distinction between ``behaviour'' options like error bars, domain, number of samples etc.\ and ``style options'' like color, line width, markers etc. This distinction is obsolete now, simply collect everything into \meta{options}.}\index{Behavior Options}\index{Options!Distinction Behavior, Style Options}. Plot variants like error bars, the number of |samples| or a sample |domain| can also be configured in \meta{options}.
The \meta{input data} is one of several coordinate input tools which are described in more detail below. Finally, if |\addplot| successfully processed all coordinates from \meta{input data}, it generates \Tikz\ paths to realize the drawing operations. Any \meta{trailing path commands} are appended to the final drawing command, allowing to continue the \Tikz\ path (from the last plot coordinate).
@@ -158,7 +160,7 @@ Some more details:
\end{codeexample}
to modify options for the plot with number~$3$ only. The first plot in an axis has number~$0$.
\item The \meta{options} are remembered for the legend. They are available as `\declareandlabel{current plot style}' as long as the path is not yet finished or in associated error bars.
- \item See subsection~\ref{sec:markers} for a list of available markers and line styles.
+ \item See Subsection~\ref{sec:markers} for a list of available markers and line styles.
\item For log plots, \PGFPlots\ will compute the natural logarithm $\log(\cdot)$ numerically using a floating point unit developed for this purpose\footnote{This floating point unit is available as \Tikz\ library as part of \Tikz.}. For example, the following numbers are valid input to |\addplot|.
\begin{codeexample}[]
\begin{tikzpicture}
@@ -189,7 +191,7 @@ Some more details:
\item Some of the coordinate input routines use the powerful |\pgfmathparse| feature of \pgfname\ to read their coordinates, among them |plot coordinates|, |plot expression| and |plot table|. This allows to use mathematical expressions as coordinates which will be evaluated using the floating point routines (this applies to logarithmic and linear scales).
- \item If you did not specify axis limits manually, |\addplot| will compute them automatically.
+ \item \PGFPlots\ automatically computes missing axis limits.
The automatic computation of axis limits works as follows:
\begin{enumerate}
\item Every coordinate will be checked. Care has been taken to avoid \TeX's limited numerical capabilities.
@@ -216,6 +218,8 @@ Thus, you can combine |cycle list| and \meta{options}.
\end{axis}
\end{tikzpicture}
\end{codeexample}
+
+The distinction is as follows: |\addplot ...| (without options) lets \PGFPlots\ select colors, markers and linestyles automatically (using |cycle list|). The variant |\addplot+|\oarg{option}| ...| will use the same automatically determined styles, but in addition it uses \meta{options}. Finally, |\addplot|\oarg{options} (without the |+|) uses only the manually provided \meta{options}.
\end{addplot+}
\subsubsection{Coordinate Lists}
@@ -259,7 +263,7 @@ or
(4000,7e-8) +- (0.1,0.01)
};
\end{codeexample}
-These error coordinates are only used in case of error bars, see section~\ref{sec:errorbars}. You will also need to configure whether these values denote absolute or relative errors.
+These error coordinates are only used in case of error bars, see Section~\ref{sec:errorbars}. You will also need to configure whether these values denote absolute or relative errors.
The coordinates as such can be numbers as |+5|, |-1.2345e3|, |35.0e2|, |0.00000123| or |1e2345e-8|. They are not limited to \TeX's precision.
@@ -292,7 +296,7 @@ Please refer to the documentation of |point meta| on page~\pageref{pgfplots:poin
\begin{codeexample}[code only]
\addplot file {datafile.dat};
\end{codeexample}
-where \marg{name} is a text file with at least two columns which will be used as $x$ and $y$ coordinates. Lines starting with `|%|' or `|#|' are ignored. Such files are often generated by \textsc{gnuplot}:
+where \meta{name} is a text file with at least two columns which will be used as $x$ and $y$ coordinates. Lines starting with `|%|' or `|#|' are ignored. Such files are often generated by \textsc{gnuplot}:
\begin{codeexample}[code only]
#Curve 0, 20 points
#x y type
@@ -394,7 +398,7 @@ It is also possible to provide the data inline, i.e.\ directly as argument in cu
\end{codeexample}
\noindent Inline table may be convenient together with `|\\|' and |row sep=\\|, see below for more information.
-Alternatively, you can load the table \emph{once} into an internal structure and use it \emph{multiple} times:
+Alternatively, you can load the table \emph{once} into an internal structure and use it \emph{multiple} times\footnote{In earlier versions, there was an addition keyword `from' before the argument like \texttt{\textbackslash addplot table from \{\textbackslash loadedtable\}}. This keyword is still accepted, but no longer required.}:
\begin{codeexample}[code only]
\pgfplotstableread{datafile.dat}\loadedtable % use any custom name in place of `\loadedtable'
...
@@ -422,7 +426,7 @@ Summary and remarks:
\item Use |\addplot table[||x index||=|\marg{column index}|,||y index||=|\marg{column index}|]| to access column indices. Indexing starts with~$0$. You may also use an index for~$x$ and a column name for~$y$.
\item Use |\addplot table[||x expr=\coordindex,y=|\marg{column name}|]| to plot the coordinate index versus some $y$ data.
\item Use |\addplot table[||header||=false] |\marg{file name} if your input file has no column names. Otherwise, the first non-comment line is checked for column names: if all entries are numbers, they are treated as numerical data; if one of them is not a number, all are treated as column names.
- \item It is possible to read error coordinates from tables as well. Simply add options `|x error|', `|y error|' or `|x error index|'/`|y error index|' to \marg{source columns}. See section~\ref{sec:errorbars} for details about error bars.
+ \item It is possible to read error coordinates from tables as well. Simply add options `|x error|', `|y error|' or `|x error index|'/`|y error index|' to \meta{source columns}. See Section~\ref{sec:errorbars} for details about error bars.
\item It is possible to read per point meta data (usable in |scatter src|, see page~\pageref{pgfplots:scatter:src}) as has been discussed for |plot coordinates| and |plot file| above. The meta data column can be provided using the |meta| key (or the |meta index| key).
\item Use |\addplot table[|\meta{source columns}|] |\marg{\textbackslash macro} to use a pre--read table. Tables can be read using
\begin{codeexample}[code only]
@@ -442,7 +446,7 @@ Summary and remarks:
\declare{col sep}\pgfmanualpdflabel{/pgfplots/table/col sep}{}|=|\mchoice{space,tab,comma,colon,semicolon,braces,\&,ampersand}
- option which is documented in all detail in the manual for \PGFPlotstable\ which is part of \PGFPlots.
+ option documented in all detail in the manual for \PGFPlotstable\ which is part of \PGFPlots.
\item Any line starting with `\#' or `\%' is ignored.
\item The first line will be checked if it contains numerical data. If there is a column in the first line which is \emph{no} number, the complete line is considered to be a header which contains column names. Otherwise it belongs to the numerical data and you need to access column indices instead of names.
@@ -453,7 +457,7 @@ Summary and remarks:
\index{Unbalanced Columns}%
\index{table@\textcolor {gray}{\texttt {plot}}\texttt { table}!Unbalanced Columns}%
\end{itemize}
- \item It is also possible to use \textbf{mathematical expressions} together with `|plot table|'. This is documented in all detail in section~\ref{pgfplots:addplot:table:expr}, but the key idea is to use one of |x expr|, |y expr|, |z expr| or |meta expr| as in `|plot table[||x expr=\thisrow{maxlevel}+3,y=L2]|'.
+ \item It is also possible to use \textbf{mathematical expressions} together with `|plot table|'. This is documented in all detail in Section~\ref{pgfplots:addplot:table:expr}, but the key idea is to use one of |x expr|, |y expr|, |z expr| or |meta expr| as in `|plot table[||x expr=\thisrow{maxlevel}+3,y=L2]|'.
\item The \PGFPlotstable\ package coming with \PGFPlots\ has a the feature ``Postprocessing Data in New Columns'' (see its manual).
This allows to compute new columns based on existing data. One of these features is |create col/linear regression| (described in Section~\ref{sec:linefitting}).
@@ -478,17 +482,17 @@ The following list of keys allow different methods to select input data or diffe
\end{pgfplotskey}
\begin{pgfplotsxykeylist}{table/\x=\marg{column name},
table/\x\ index=\marg{column index}}
- These keys define the sources for |plot table|. If both, column names and column indices are given, column names are preferred. Column indexing starts with~$0$. The initial setting is to use |x index=0| and |y index=1|.
+ These keys define the sources for |plot table|. If both column names and column indices are given, column names are preferred. Column indexing starts with~$0$. The initial setting is to use |x index=0| and |y index=1|.
Please note that column \emph{aliases} will be considered if unknown column names are used. Please refer to the manual of \PGFPlotstable\ which comes with this package.
\end{pgfplotsxykeylist}
\begin{pgfplotsxykeylist}{table/\x\ expr=\marg{expression},table/meta expr=\marg{expression}}
- These keys allow to combine the mathematical expression parser with file input. They are listed here to complete the list of table keys, but they are described in all detail in section~\ref{pgfplots:addplot:table:expr}.
+ These keys allow to combine the mathematical expression parser with file input. They are listed here to complete the list of table keys, but they are described in all detail in Section~\ref{pgfplots:addplot:table:expr}.
The key idea is to provide an \meta{expression} which depends on table data (possibly on all columns in one row). Only data within the same row can be used where columns are referenced with |\thisrow|\marg{column name} or |\thisrowno|\marg{column index}.
- Please refer to section~\ref{pgfplots:addplot:table:expr} for details.
+ Please refer to Section~\ref{pgfplots:addplot:table:expr} for details.
\end{pgfplotsxykeylist}
@@ -500,7 +504,7 @@ The following list of keys allow different methods to select input data or diffe
The |x error| method provides an input column name (or alias), the |x error index| method provides input column \emph{indices} and |x error expr| works just as |table/x expr|: it allows arbitrary mathematical expressions which may depend on any number of table columns using |\thisrow|\marg{col name}.
- Please see section~\ref{sec:errorbars} for details about the usage of error bars.
+ Please see Section~\ref{sec:errorbars} for details about the usage of error bars.
\end{pgfplotsxykeylist}
\begin{pgfplotsxykeylist}{%
table/meta=\marg{column name},
@@ -551,6 +555,20 @@ The following list of keys allow different methods to select input data or diffe
This setting applies to |\addplot file| as well.
\end{key}
+\begin{key}{/pgfplots/table/comment chars=\marg{comma-separated-list} (initially empty)}
+ Allows to add one or more \emph{additional} comment characters. Each of these characters has a similar effect as the |#| character, i.e.\ all following characters of that particular input line are skipped.
+
+ For example, |comment chars=!| uses `|!|' as additional comment character (which allows to parse Touchstone files).
+
+ Please refer to the manual of \PGFPlotstable\ for details.
+\end{key}
+
+\begin{key}{/pgfplots/table/skip first n=\marg{integer} (initially 0)}
+ Allows to skip the first \meta{integer} lines of an input file. The lines will not be processed.
+
+ Please refer to the manual of \PGFPlotstable\ for details.
+\end{key}
+
\subsubsection{Computing Coordinates with Mathematical Expressions}
@@ -649,7 +667,7 @@ Please note that \PGF's math parser uses degrees for trigonometric functions:
\end{addplotoperation}
\begin{addplotoperation}[]{(\meta{$x$ expression},\meta{$y$ expression})}{}
- A variant of \verbpdfref{\addplot expression} which allows to provide different coordinate expressions for the $x$ and $y$ coordinates. This can be used to generate parameterized plots.
+ A variant of \verbpdfref{\addplot expression} which allows to provide different coordinate expressions for the $x$ and $y$ coordinates. This can be used to generate parametrized plots.
Please note that |\addplot (x,x^2)| is equivalent to |\addplot expression {x^2}|.
@@ -690,7 +708,7 @@ Please note that \PGF's math parser uses degrees for trigonometric functions:
\begin{pgfplotskey}{samples at=\marg{coordinate list}}
Sets the $x$ coordinates for |plot expression| explicitly. This overrides |domain| and |samples|.
- The \marg{coordinate list} is a |\foreach| expression, that means it can contain a simple list of coordinates (comma--separated) but also complex |...| expressions like\footnote{Unfortunately, the \texttt{...} is somewhat restrictive when it comes to extended accuracy. So, if you have particularly small or large numbers (or a small distance), you have to provide a comma--separated list (or use the \texttt{domain} key).}
+ The \meta{coordinate list} is a |\foreach| expression, that means it can contain a simple list of coordinates (comma--separated), but also complex |...| expressions like\footnote{Unfortunately, the \texttt{...} is somewhat restrictive when it comes to extended accuracy. So, if you have particularly small or large numbers (or a small distance), you have to provide a comma--separated list (or use the \texttt{domain} key).}
\begin{codeexample}[code only]
\pgfplotsset{samples at={5e-5,7e-5,10e-5,12e-5}}
\pgfplotsset{samples at={-5,-4.5,...,5}}
@@ -699,7 +717,7 @@ Please note that \PGF's math parser uses degrees for trigonometric functions:
The same special treatment of |/tikz/samples at| and |/pgfplots/samples at| as for the |domain| key applies here. See above for details.
- \paragraph{Attention:} |samples at| overrides |domain|, even if |domain| has been set \emph{after} |samples at|! Use |samples at={}| to clear \marg{coordinate list} and re-activate |domain|.
+ \paragraph{Attention:} |samples at| overrides |domain|, even if |domain| has been set \emph{after} |samples at|! Use |samples at={}| to clear \meta{coordinate list} and re-activate |domain|.
\end{pgfplotskey}
\begin{pgfplotskeylist}{%
@@ -713,11 +731,11 @@ Please note that \PGF's math parser uses degrees for trigonometric functions:
\end{pgfplotskeylist}
\subsubsection{Mathematical Expressions And File Data}
-\PGFPlots\ allows to combine `|plot table|' and `|plot expression|' to get both, file input and modifications by means of mathematical expressions.
+\PGFPlots\ allows to combine `|plot table|' and `|plot expression|' to get both file input and modifications by means of mathematical expressions.
\begin{addplotoperation}[]{table}{\oarg{column selection and expressions}\marg{file}}
\label{pgfplots:addplot:table:expr}
- Besides the already discussed possibility to provide a column selection by means of column names (|x||=|\meta{name} or |x index||=|\meta{index}, see section~\ref{pgfplots:addplot:table}), it is also possible to provide mathematical expressions as arguments.
+ Besides the already discussed possibility to provide a column selection by means of column names (|x||=|\meta{name} or |x index||=|\meta{index}, see Section~\ref{pgfplots:addplot:table}), it is also possible to provide mathematical expressions as arguments.
Mathematical expressions are specified with |x expr||=|\meta{expression} inside of \meta{column selection and expressions}. They can depend on zero, one or more columns of the input file. A column is referenced using the special command `|\thisrow|\marg{column name}' within \meta{expression} (or |\thisrowno|\meta{column index}).
@@ -741,14 +759,14 @@ Please note that \PGF's math parser uses degrees for trigonometric functions:
Inside of \meta{expression}, the following macros can be used to access numerical data cells inside of the input file:
\begin{command}{\thisrow\marg{column name}}
- Yields the value of the column designated by \marg{column name}. There is no limit on the number of columns which can be part of a mathematical expression, but only values inside of the currently processed \emph{table row} can be used.
+ Yields the value of the column designated by \meta{column name}. There is no limit on the number of columns which can be part of a mathematical expression, but only values inside of the currently processed \emph{table row} can be used.
- It is possible to provide column aliases for \marg{column name} as described in the manual of \PGFPlotstable.
+ It is possible to provide column aliases for \meta{column name} as described in the manual of \PGFPlotstable.
The argument \meta{column name} has to denote either an existing column or one for which a column alias exists (see the manual of \PGFPlotstable). If it can't be resolved, the math parser yields an ``Unknown function'' error message.
\end{command}
\begin{command}{\thisrowno\marg{column index}}
- Similar to |\thisrow|, this command yields the value of the column with index \marg{column index} (starting with $0$).
+ Similar to |\thisrow|, this command yields the value of the column with index \meta{column index} (starting with $0$).
\end{command}
\begin{command}{\coordindex}
Yields the current index of the table row (starting with $0$). This does \emph{not} count header or comment lines.
@@ -765,13 +783,13 @@ Please note that \PGF's math parser uses degrees for trigonometric functions:
This allows to access the cell values identified by |x| or |x index| using the ``pointer'' |\columnx|. I am not sure if this yields any advantage, but it is possible nevertheless. If in doubt, prefer using |\thisrow|\marg{column name}.
\end{enumerate}
- \paragraph{Attention:} If your table has less rows than two, you may need to set |x index={},y index={}| explicitly. This is a consequence of the fact that column name/index access is still applied even if an expression is provided.
+ \paragraph{Attention:} If your table has less than two rows, you may need to set |x index={},y index={}| explicitly. This is a consequence of the fact that column name/index access is still applied even if an expression is provided.
\end{addplotoperation}
\subsubsection{Computing Coordinates with Mathematical Expressions (gnuplot)}
\begin{addplotoperation}[]{gnuplot}{\oarg{further options}\marg{gnuplot code}}
-In contrast to |plot expression|, the |plot gnuplot| command\footnote{Note that |plot gnuplot| is actually a re-implementation of the |plot function| method known from \PGF. It also invokes \PGF\ basic layer commands.} employs the external program |gnuplot| to compute coordinates. The resulting coordinates are written to a text file which will be plotted with |plot file|. \PGF\ checks whether coordinates need to be re-generated and calls |gnuplot| whenever necessary (this is usually the case if you change the number of samples, the argument to |plot gnuplot| or the plotted domain\footnote{Please note that \PGFPlots\ produces slightly different files than \Tikz\ when used with \texttt{plot gnuplot} (it configures high precision output). You should use different \texttt{id} for \PGFPlots\ and \Tikz\ to avoid conflicts in such a case.}).
+In contrast to |plot expression|, the |plot gnuplot| command\footnote{Note that \texttt{plot gnuplot} is actually a re-implementation of the |plot function| method known from \PGF. It also invokes \PGF\ basic layer commands.} employs the external program |gnuplot| to compute coordinates. The resulting coordinates are written to a text file which will be plotted with |plot file|. \PGF\ checks whether coordinates need to be re-generated and calls |gnuplot| whenever necessary (this is usually the case if you change the number of samples, the argument to |plot gnuplot| or the plotted domain\footnote{Please note that \PGFPlots\ produces slightly different files than \Tikz\ when used with \texttt{plot gnuplot} (it configures high precision output). You should use different \texttt{id} for \PGFPlots\ and \Tikz\ to avoid conflicts in such a case.}).
The differences between |plot expression| and |plot gnuplot| are:
\begin{itemize}
@@ -811,7 +829,7 @@ The \meta{options} determine the appearance of the plotted function; these param
Some remarks:
\begin{itemize}
- \item The independent variable for one dimensional plots can be change with the |variable| option, just as for |plot expression|. Similarly, the second variable for two dimensional plots can be changed with |variable y|.
+ \item The independent variable for one-dimensional plots can be changed with the |variable| option, just as for |plot expression|. Similarly, the second variable for two dimensional plots can be changed with |variable y|.
For |parametric| plots, the variable names need to be adjusted with |parametric/var 1d| and |parametric/var 2d| (since gnuplot uses |t| and |u,v| as initial values for |parametric| plots).
\item
@@ -915,10 +933,11 @@ The \meta{options} determine the appearance of the plotted function; these param
\end{key}
\subsubsection{Using External Graphics as Plot Sources}
+{
+\pgfkeys{/pdflinks/search key prefixes in/.add={/pgfplots/plot graphics/,}{}}
\begin{addplotoperation}[]{graphics}{\marg{file name}}
-\pgfkeys{/pdflinks/search key prefixes in/.add={/pgfplots/plot graphics/,}{}}
- This plot type allows to extend the plotting capabilities of \PGFPlots\ beyond its own limitations. The idea is to generate the graphics as such (for example, a contour plot, a complicated shaded surface\footnote{See also section~\ref{sec:pgfplots:surfplots} for an overview of \PGFPlots\ methods to draw shaded surfaces.} or a large point cluster) with an external program like Matlab (tm) or |gnuplot|. The graphics, however, should \emph{not} contain an axis or descriptions. Then, we use |\includegraphics| and an \PGFPlots\ axis which fits exactly on top of the imported graphics.
+ This plot type allows to extend the plotting capabilities of \PGFPlots\ beyond its own limitations. The idea is to generate the graphics as such (for example, a contour plot, a complicated shaded surface\footnote{See also Section~\ref{sec:pgfplots:surfplots} for an overview of \PGFPlots\ methods to draw shaded surfaces.} or a large point cluster) with an external program like Matlab (tm) or |gnuplot|. The graphics, however, should \emph{not} contain an axis or descriptions. Then, we use |\includegraphics| and a \PGFPlots\ axis which fits exactly on top of the imported graphics.
Of course, one could do this manually by providing proper scales and such. The operation |plot graphics| is intended so simplify this process. However the \emph{main difficulty} is to get images with correct bounding box. Typically, you will have to adjust bounding boxes manually.
@@ -946,7 +965,7 @@ print -dpng external1
\end{codeexample}
\noindent to load the graphics\footnote{Please note that I don't have a Matlab license, so I used \texttt{gnuplot} to produce an equivalent replacement graphics.} just as if we would have drawn it with \PGFPlots. The |axis on top| simply tells \PGFPlots\ to draw the axis on top of any plots (see its description).
-Please note that \PGFPlots\ offers support for smaller surface plots as well which might be an option -- unless the number of samples is too large. See section~\ref{sec:pgfplots:surfplots} for details.
+Please note that \PGFPlots\ offers support for smaller surface plots as well which might be an option -- unless the number of samples is too large. See Section~\ref{sec:pgfplots:surfplots} for details.
\noindent However, external programs have the following advantages here: they are faster, allow more complexity and provide real $z$ buffering which is currently only simulated by \PGFPlots. Thus, it may help to consider |plot graphics| for complicated surface plots.
@@ -1034,6 +1053,7 @@ Using |gv|, I determined that the bounding box needs to be shifted |12| units to
\end{axis}
\end{tikzpicture}
\end{codeexample}
+
\end{addplotoperation}
\subsubsection*{Keys To Configure Plot Graphics}
@@ -1042,9 +1062,35 @@ The following list of keys configure |\addplot graphics|. Note that the common p
\begin{pgfplotsxykeylist}{
plot graphics/\x min=\marg{coordinate},
plot graphics/\x max=\marg{coordinate}}
- These keys are required for |plot graphics| and provide information about the external data range. The graphics will be squeezed between these coordinates. The arguments are axis coordinates.
+ These keys are required for |plot graphics| and provide information about the external data range. The graphics will be squeezed between these coordinates. The arguments are axis coordinates; they are only useful if you provide each of them.
+
+ Alternatively, you can also use the |plot graphics/points| feature to provide the external data range, see below.
\end{pgfplotsxykeylist}
+\begin{pgfplotskey}{plot graphics/points=\marg{list of coordinates} (initially empty)}
+ This key also allows to provide the external data range. It constitutes an alternative to |plot graphics/xmin| (and its variants): simply provide at least two coordinates in \meta{list of coordinates}. Their bounding box is used to determine the external data range, and the graphics is squeezed between these coordinates.
+
+ The example from above can be written equivalently as
+\begin{codeexample}[]
+\begin{tikzpicture}
+ \begin{axis}[axis on top,title=Graphics Import]
+ \addplot graphics
+ % instead of the min/max things:
+ [points={(0,1) (1,0)},
+ % trim=left bottom right top
+ includegraphics={trim=12 9 12 8,clip}]
+ {external2};
+ \addplot coordinates {(0,0) (1,1)};
+ \end{axis}
+\end{tikzpicture}
+\end{codeexample}
+ \noindent The \meta{list of coordinates} is a sequence of the form |(x,y)| for two--dimensional plots and \texttt{(x,y,z)} for three--dimensional ones, the ordering is irrelevant. The single elements are separated by white space.
+
+ It is possible to mix |plot graphics/xmin| and variants with |plot graphics/points|.
+
+ The |plot graphics/points| key has further functionality for inclusion of three--dimensional graphics which is discussed at the end of this section (on page~\pageref{sec:plotgraphics3d}). Here is a short reference on the accepted syntax for three--dimensional plot graphics: in addition to the |(x,y,z)| syntax, you can provide arguments of the form |(x,y,z) => (X,Y)|. Here, the first (three--dimensional) coordinate is a logical coordinate and the second (two--dimensional) coordinate denotes the coordinates of the very same point, but inside of the included image (relative to the lower left corner of the image). Applications and examples for this syntax can be found in the section for three--dimensional plot graphics (see page~\pageref{sec:plotgraphics3d}).
+\end{pgfplotskey}
+
\begin{pgfplotskey}{plot graphics/includegraphics=\marg{options}}
A list of options which will be passed as--is to |\includegraphics|. Interesting options include the \declareandlabel{trim}|=|\meta{left} \meta{bottom} \meta{right} \meta{top} key which reduces the bounding box and \pgfmanualpdflabel{/pgfplots/plot graphics/clip}{\declaretext{clip}} which discards everything outside of the bounding box. The scaling options won't have any effect, they will be overwritten by \PGFPlots.
\end{pgfplotskey}
@@ -1088,3 +1134,230 @@ The following list of keys configure |\addplot graphics|. Note that the common p
|plot graphics/lowlevel draw/.code 2 args=|\marg{code which depends on \texttt{\#1} and \texttt{\#2}}.
\end{pgfplotskey}
+\subsubsection*{Support for External Three-Dimensional Graphics}
+\label{sec:plotgraphics3d}
+\PGFPlots\ offers several visualization techniques for three dimensional graphics. Nevertheless, complex visualizations or specialized applications are beyond the scope of \PGFPlots\ and you might want to use other tools to generate such figures.
+
+The |plot graphics| tool of \PGFPlots\ allows to include three--dimensional external graphics: it generates a three--dimensional axis on its own. The idea is to provide a graphics (without descriptions) and use \PGFPlots\ to overlay a three--dimensional axis automatically. This allows to maintain document consistency (making it unnecessary to use different programs within the same document).
+
+You are probably guessing how this is possible. Well, it needs more user input than two--dimensional external graphics. The cost to include external three dimensional images into \PGFPlots\ is essentially control of a graphics program like |gimp|: you need to identify the 3D coordinates of a couple of points in your image. \PGFPlots\ will then squeeze the graphics correctly, and it reconfigures the axis to ensure a correct display of the result.
+
+\paragraph{Warning:} The feature is only 95\% stable yet and may need some more testing. Use at your own risk.
+
+Let's start with two examples. Suppose you generate a surface plot with Matlab and want to include it in \PGFPlots. We have the matlab script
+\begin{codeexample}[code only]
+[x,y]=meshgrid(linspace(0,1,120));
+surf(x,y,sin(8*pi*x).* exp(-20*(y-0.5).^2) + exp(-(x-0.5).^2*30 - (y-0.25).^2 - (x-0.5).*(y-0.25)))
+xlabel('x'), ylabel('y')
+axis off
+print -dpng plotgraphics3dsurf
+\end{codeexample}
+\noindent which generates the figure in question.
+
+After automatically computing a tight bounding box for |plotgraphics3dsurf.png| (I used |gimp|'s Image$\gg$Autocrop feature), and making the background color transparent (|gimp|: select the outer white space with the magic wand, then use\footnote{I have a german version, I am not sure if the translation is correct.} Layer$\gg$Transparency$\gg$Color to Transparency) we get:
+
+{\setlength{\fboxsep}{0pt}%
+\centering
+\fbox{\includegraphics[width=6cm]{plotdata/plotgraphics3dsurf.png}}%
+
+}%
+
+The key idea is now to identify several points in the image, and assign \emph{both} their logical three--dimensional coordinates \emph{and} the corresponding two--dimensional canvas coordinates in image coordinates. How? Well, the three--dimensional coordinates are known to Matlab, it can display them for you if you click somewhere into the image, compare Figure~\ref{fig:plotgraphics3d} (left).
+
+\begin{figure}
+\noindent
+\hbox to \linewidth{\hfill
+ \includegraphics{plotdata/plotgraphics3dsurfmatlab.png}%
+ \hfill
+ \begin{minipage}[b][4cm][c]{2.6cm}%
+ \includegraphics[width=\linewidth]{plotdata/plotgraphics_gimpmeasure.png}%
+ \end{minipage}
+ \hfill
+}%
+
+
+\caption{Using Matlab to extract image coordinates (left) and Gimp to measure distances (right).}
+\label{fig:plotgraphics3d}
+\end{figure}
+
+The two--dimensional canvas coordinates need work; they need to be provided relative to the \emph{lower left corner} of the image. I used |gimp| and activated ``Points'' as units (lower left corner). The lower left corner now displays the image coordinates in |pt| which is compatible with \PGFPlots. An alternative to pointing onto coordinates is a measurement tool; compare Figure~\ref{fig:plotgraphics3d} (right) for the ``Measure'' tool in |gimp| which allows to compute the length of a line (in our case, the length of the lower left corner to the point of interest).
+
+I selected four points in the graphics and noted their 2d image coordinates and their 3d logical coordinates as follows:
+\begin{codeexample}[]
+\begin{tikzpicture}
+\begin{axis}[
+ grid=both,minor tick num=1,
+ xlabel=$x$,ylabel=$y$,
+ ]
+\addplot3 graphics[
+ points={% important
+ (0,1,0) => (0,207-112)
+ (1,0,0) => (446,207-133)
+ (0.5546,0.5042,1.825) => (236,207)
+ (0,0,0) => (194,207-202)
+ }] {plotdata/plotgraphics3dsurf.png};
+\end{axis}
+\end{tikzpicture}
+\end{codeexample}
+Here, the |points| key gets our collected coordinates as argument. It accepts a sequence of maps of the form \meta{3d logical coordinate} | => | \meta{2d canvas coordinate}. In our case, |(0,1,0)| has been found in the |.png| file at |(0,207-112)|. Note that I introduced the difference since |gimp| counts from the upper left, but \PGFPlots\ counts from the lower left.
+
+Once these four point coordinates are gathered, we find Matlab's surface plot in a \PGFPlots\ axis. You can modify any appearance options, including different axis limits or further |\addplot| commands:
+\begin{codeexample}[]
+\begin{tikzpicture}
+\begin{axis}[
+ xmax=1.5,% extra limits
+ grid=both,minor tick num=1,
+ xlabel=$x$,ylabel=$y$,
+ ]
+\addplot3[surf] % 'surf' is only used for the legend.
+ graphics[
+ points={
+ (0,1,0) => (0,207-112)
+ (1,0,0) => (446,207-133)
+ (0.5546,0.5042,1.825) => (236,207)
+ (0,0,0) => (194,207-202)
+ }]
+ {plotdata/plotgraphics3dsurf.png};
+\addlegendentry{Graphics}
+
+\addplot3+[only marks] coordinates {
+ (0,1,0) (1,0,0)
+ (0.5546,0.5042,1.825) (0,0,0)
+};
+\addlegendentry{Scatter}
+\end{axis}
+\end{tikzpicture}
+\end{codeexample}
+\noindent \PGFPlots\ uses the four input points to compute appropriate |x|, |y| and |z| unit vectors (and the origin in graphics coordinates). These four vectors (with two components each) can be computed as a result of a linear system of size $8\times 8$, that is why you need to provide four input points (each has two coordinates). \PGFPlots\ computes the unit vectors of the imported graphics, and afterwards it rescales the result such that it fits into the specified |width| and |height|. This rescaling respects the |unit vector ratio| (more precisely, it uses |scale mode=scale uniformly| instead of |scale mode=stretch to fill|). Consequently, the freedom to change the view of a three--dimensional axis which contains a projected graphics is considerably smaller than before. Surprisingly, you can still change axis limits and |width| and |height| -- \PGFPlots\ will take care of a correct display of your imported graphics.
+
+Here is a further example. Suppose we are given the three--dimensional visualization
+
+{\setlength{\fboxsep}{0pt}%
+\centering
+\fbox{\includegraphics[width=6cm]{plotdata/risingdrop3d}}%
+
+}%
+
+It has been generated by matlab (I only added transparency to the background with |gimp|). Besides advanced visualization techniques, it uses |axis equal|, i.e.\ |unit vector ratio=1 1 1|. As before, we need to identify four points, each with its 3d logical coordinates (from matlab) and the associated 2d canvas coordinates relative to the lower left corner of the graphics (note that there is a lot of white space around the graphics). Here is the output of \PGFPlots\ when you import the resulting graphics:
+
+\begin{codeexample}[]
+\begin{tikzpicture}
+\begin{axis}[
+ grid=both,minor tick num=1,
+ xlabel=$x$,ylabel=$y$,
+ title={\centering
+ Geometry provided by Sven Gro\ss, Bonn\\
+ \url{http://www.igpm.rwth-aachen.de/DROPS}\\},
+ title style={text width=6cm,font=\tiny},
+]
+ \addplot3 graphics[
+ points={
+ (-0.002625,0.002625,0) => (140,234)
+ (0,0.00263,0.00263) => (230,364)
+ (0,-0.00263,-0.00263) => (366,81)
+ (0,-0.00263,0.00263) => (366,276)
+ (0.002625,0.002625,0.002625)
+ }
+ ]
+ {plotdata/risingdrop3d.png};
+\end{axis}
+\end{tikzpicture}
+\end{codeexample}
+\noindent Note that I provided \emph{five} three--dimensional coordinates here, but the last entry has no |=>| mapping to two--dimensional canvas coordinates. Thus, it is only used to update the bounding box (see the reference manual for the |points| key for details).
+
+The example above is clipped because \PGFPlots\ could not rescale the graphics automatically. Changing the ratio between |width| and |height| improves the display:
+
+\begin{codeexample}[]
+\begin{tikzpicture}
+\begin{axis}[
+ height=8cm,width=7cm,% improve scaling manually
+ grid=both,minor tick num=1,
+ xlabel=$x$,ylabel=$y$,
+ title={\centering
+ Geometry provided by Sven Gro\ss, Bonn\\
+ \url{http://www.igpm.rwth-aachen.de/DROPS}\\},
+ title style={text width=6cm,font=\tiny},
+]
+ \addplot3 graphics[
+ points={
+ (-0.002625,0.002625,0) => (140,234)
+ (0,0.00263,0.00263) => (230,364)
+ (0,-0.00263,-0.00263) => (366,81)
+ (0,-0.00263,0.00263) => (366,276)
+ (0.002625,0.002625,0.002625)
+ }
+ ]
+ {plotdata/risingdrop3d.png};
+\end{axis}
+\end{tikzpicture}
+\end{codeexample}
+\noindent What happens is that \PGFPlots\ \emph{only} rescales the $z$ axis. This has the effect that the axes are all scaled by a single scaling factor (using |scale mode=scale uniformly|), skewing is avoided. In this approach, you can only modify |width| and |height| to provide more freedom.
+
+We consider a third example which has been generated by the Matlab code
+\begin{codeexample}[code only]
+clear all
+close all
+seed = sum(clock)
+rand('seed',seed);
+X = rand(10,10,10);
+data = smooth3(X,'box',5);
+p1 = patch(isosurface(data,.5), ...
+ 'FaceColor','blue','EdgeColor','none');
+p2 = patch(isocaps(data,.5), ...
+ 'FaceColor','interp','EdgeColor','none');
+isonormals(data,p1)
+daspect([1 2 2])
+view(3); axis vis3d tight
+camlight; lighting phong
+% print -dpng plotgraphics3withaxis
+axis off
+print -dpng plotgraphics3
+save plotgraphics3.seed seed -ASCII % to reproduce the result
+\end{codeexample}
+\noindent I only added background transparency with |gimp| and got the following graphics:
+
+{\setlength{\fboxsep}{0pt}%
+\centering
+\fbox{\includegraphics[width=6cm]{plotdata/plotgraphics3.png}}%
+
+}%
+
+We proceed as before and collect four points, each with 3d logical coordinates (by clicking into the matlab figure) and their associated 2d canvas (graphics) coordinates using the measure tool of gimp. The result is shown in the code example below.
+\begin{codeexample}[]
+\begin{tikzpicture}
+\begin{axis}[
+ grid=both,minor tick num=1,
+ xlabel=$x$,ylabel=$y$,
+ 3d box,
+]
+ \addplot3 graphics[
+ points={
+ (1,1,1) => (205,48)
+ (10,1,10) => (503,324)
+ (1,1,4.044)=> (206,102)
+ (10,10,10) => (390,398)
+ }
+ ]
+ {plotdata/plotgraphics3.png};
+\end{axis}
+\end{tikzpicture}
+\end{codeexample}
+
+\paragraph{Technical points:} the following issues might arise while working with \verbpdfref{\addplot3} |graphics|:
+\begin{itemize}
+ \item It must be possible to deduce the origin and the three (two--dimensional) unit vectors from the four provide |points|; otherwise the algorithm will fail.
+
+ The algorithm should detect any deficiancies. However, if you encounter strange ``Dimension too large'' messages here, you can try other arguments in |points|. Take a look into your log file, it will probably indicate the source of problems (or use the |debug| key).
+
+ \item \PGFPlots\ uses the first two points to squeeze the graphics into the desired coordinates (which implies that they should not have the same canvas $X$ or $Y$ coordinates). It verifies that the remaining |points| arguments are projected correctly.
+ \item The resulting scaling by means of |scale mode=scale uniformly| will only rescale the $z$ axis. You may need to adjust |width| and |height| (both of them) if the result is unsatisfactory (see the example above).
+ \item There is a |debug| key to investigate what the algorithm is doing:
+\begin{pgfplotskey}{plot graphics/debug=\marg{true,false} (initially false)}
+ If you provide |\addplot3 graphics[debug,points={...}]|, \PGFPlots\ will provide debug information onto your terminal and into the logfile. It will also generate extra files containing the determined unit vectors and the linear system used to derive them (one such file for every |\addplot3 graphics| statement, the filename will be the graphics file name and |.dat| appended).
+
+ Without the |debug| key, only the log file will contain brief information what \PGFPlots\ is doing behind the scenes.
+\end{pgfplotskey}
+\end{itemize}
+}
+
+}%