summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/latex/pgfplots/pgfplots.libs.polar.tex
blob: cded9ba07af0288a99c0260833c648aa75fe4604 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
\subsection{Polar Axes}
{
\tikzset{external/figure name/.add={}{polar_}}%

\begin{pgfplotslibrary}{polar}
	A library to draw polar axes and plot types relying on polar coordinates, represented by angle (in degrees or, optionally, in radians) and radius.
\end{pgfplotslibrary}

\subsubsection{Polar Axes}
\begin{environment}{{polaraxis}}
	The |polar| library provides the |polaraxis| environment.
	 Inside of such an environment, all coordinates are expected to be given in polar representation of the form $(\meta{angle},\meta{radius})$, i.e.\ the $x$ coordinate is always the angle and the $y$ coordinate the radius:
\end{environment}
\begin{codeexample}[]
\begin{tikzpicture}
	\begin{polaraxis}
	\addplot coordinates {(0,1) (90,1) 
		(180,1) (270,1)};
	\end{polaraxis}
\end{tikzpicture}
\end{codeexample}

\begin{codeexample}[]
\begin{tikzpicture}
	\begin{polaraxis}
	\addplot+[domain=0:3] (360*x,x); % (angle,radius)
	\end{polaraxis}
\end{tikzpicture}
\end{codeexample}

\begin{codeexample}[]
\begin{tikzpicture}
	\begin{polaraxis}
	\addplot+[mark=none,domain=0:720,samples=600] 
		{sin(2*x)*cos(2*x)}; 
	% equivalent to (x,{sin(..)cos(..)}), i.e.
	% the expression is the RADIUS
	\end{polaraxis}
\end{tikzpicture}
\end{codeexample}

Polar axes support most of the \PGFPlots\ user interface, i.e.\ |legend entries|, any axis descriptions, |xtick|/|ytick| and so on:
\begin{codeexample}[]
\begin{tikzpicture}
	\begin{polaraxis}[
		xtick={0,90,180,270},
		title=A polar axis]
	
	\addplot coordinates {(0,1) (45,1)};
	\addlegendentry{First}

	\addplot coordinates {(180,0.5) (0,0)};
	\addlegendentry{Second}
	\end{polaraxis}
\end{tikzpicture}
\end{codeexample}
\noindent Furthermore, you can use all of the supported input coordinate methods (like \verbpdfref{\addplot coordinates}, \verbpdfref{\addplot table}, \verbpdfref{\addplot expression}). The only difference is that polar axes interpret the (first two) input coordinates as polar coordinates of the form $(\meta{angle in degrees},\meta{radius})$.

It is also possible to provide \verbpdfref{\addplot3}; in this case, the third coordinate will be ignored (although it can be used as color data using |point meta=z|). An example can be found below in Section~\ref{sec:polar:cart}.


\subsubsection{Using Radians instead of Degrees}
The initial configuration uses degrees for the angle ($x$ component of every input coordinate). \PGFPlots\ also supports to provide the angle in radians using the |data cs=polarrad| switch:
\begin{codeexample}[]
\begin{tikzpicture}
	\begin{polaraxis}[title={Degrees and/or Radians}]
	\addplot 
		coordinates {(0,1) (90,1) (180,1) (270,1)};
	\addlegendentry{Deg}

	\addplot+[data cs=polarrad] 
		coordinates {(0,1.5) (pi/2,1.5) 
		  (pi,1.5) (pi*3/2,1.5)};
	\addlegendentry{Rad}
	\end{polaraxis}
\end{tikzpicture}
\end{codeexample}
The |data cs| key is described in all detail on page~\pageref{key:data:cs}; it tells \PGFPlots\ the coordinate system of input data. \PGFPlots\ will then take steps to automatically transform each coordinate into the required coordinate system (in our case, this is |data cs=polar|).

\subsubsection{Mixing With Cartesian Coordinates}
\label{sec:polar:cart}
Similarly to the procedure described above, you can also provide Cartesian coordinates inside of a polar axis: simply tell \PGFPlots\ that it should automatically transform them to polar representation by means of |data cs=cart|:
\begin{codeexample}[]
\begin{tikzpicture}
	\begin{polaraxis}[title=Cartesian Input]
	\addplot+[data cs=cart]
		coordinates {(1,0) (0,1) (-1,0) (0,-1)};
	\end{polaraxis}
\end{tikzpicture}
\end{codeexample}
\noindent More details about the |data cs| key can be found on page~\pageref{key:data:cs}.

This does also allow more involved visualization techniques which may operate on Cartesian coordinates. The following example uses \verbpdfref{\addplot3} to sample a function $f\colon \R^2 \to \R$, computes |contour| lines (with the help of |gnuplot|) and displays the result in a |polaraxis|:
\pgfplotsexpensiveexample
\begin{codeexample}[]
\begin{tikzpicture}
	\begin{polaraxis}
	\addplot3[contour gnuplot,domain=-3:3,
	  data cs=cart]
		{exp(-x^2-y^2)};
	\end{polaraxis}
\end{tikzpicture}
\end{codeexample}
\noindent What happens is that $z=\exp(-x^2-y^2)$ is sampled for $x,y \in [-3,3]$, then contour lines are computed on $(x,y,z)$, then the resulting triples $(x,y,z)$ are transformed to polar coordinates $(\alpha,r,z)$ (leaving $z$ intact). Finally, the $z$ coordinate is used as |point meta| to determine the color.

Note that \verbpdfref{\addplot3} allows to process three--dimensional input types, but the result will always be two--dimensional (the $z$ coordinate is ignored for point placement in |polaraxis|). However, the $z$ coordinate can be used to determine point colors (using |point meta=z|).

\subsubsection{Special Polar Plot Types}
\begin{plottype}{polar comb}
	The |polar comb| plot handler is provided by \Tikz; it draws paths from the origin to the designated position and places |mark|s at the positions (similar to the |comb| plot handler). Since the paths always start at the origin, it is particularly suited for |polaraxis|:
\begin{codeexample}[]
\begin{tikzpicture}
	\begin{polaraxis}
	\addplot+[polar comb] 
		coordinates {(300,1) (20,0.3) (40,0.5) 
			(120,1) (200,0.4)};
	\end{polaraxis}
\end{tikzpicture}
\end{codeexample}
\end{plottype}

\subsubsection{Partial Polar Axes}
The |polar| library also supports partial axes. If you provide |xmin|/|xmax|, you can restrict the angles used for the axis:
\begin{codeexample}[]
\begin{tikzpicture}
	\begin{polaraxis}[xmin=45,xmax=360]
	\addplot coordinates {(0,1) (90,1) (180,1) (270,1)};
	\end{polaraxis}
\end{tikzpicture}
\end{codeexample}

Currently, the first angle must be lower than the second one. But you can employ the periodicity to get pies as follows:
\begin{codeexample}[]
\begin{tikzpicture}
	\begin{polaraxis}[xmin=270,xmax=420]
	\addplot coordinates {(0,1) (90,1) (180,1) (270,1)};
	\end{polaraxis}
\end{tikzpicture}
\end{codeexample}
\noindent Similarly, an explicitly provided value for |ymin| allows to reduce the displayed range away from $0$:
\begin{codeexample}[]
\begin{tikzpicture}
	\begin{polaraxis}[ymin=0.3]
	\addplot coordinates {(0,1) (90,1) 
	  (180,1) (270,1)};
	\end{polaraxis}
\end{tikzpicture}
\end{codeexample}

\noindent Modifying |xmin| and |xmax| manually can also be used to move the $y$ axis line (the line with |ytick| and |yticklabels|):
\begin{codeexample}[]
\begin{tikzpicture}
	\begin{polaraxis}[xmin=45,xmax=405]
	\addplot coordinates {(0,1) (90,1) (180,1) (270,1)};
	\end{polaraxis}
\end{tikzpicture}
\end{codeexample}
}