summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/latex/pgfplots/pgfplots.reference.3dplots.tex
blob: af882182fdc04d8ea2928084e2a1f50165cb770f (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
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287
1288
1289
1290
1291
1292
1293
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
1304
1305
1306
1307
1308
1309
1310
1311
1312
1313
1314
1315
1316
1317
1318
1319
1320
1321
1322
1323
1324
1325
1326
1327
1328
1329
1330
1331
1332
1333
1334
1335
1336
1337
1338
1339
1340
1341
1342
1343
1344
1345
1346
1347
1348
1349
1350
1351
1352
1353
1354
1355
1356
1357
1358
1359
1360
1361
1362
1363
1364
1365
1366
1367
1368
1369
1370
1371
1372
1373
1374
1375
1376
1377
1378
1379
1380
1381
1382
1383
1384
1385
1386
1387
1388
1389
1390
1391
1392
1393
1394
1395
1396
1397
1398
1399
1400
1401
1402
1403
1404
1405
1406
1407
1408
1409
1410
1411
1412
1413
1414
1415
1416
1417
1418
1419
1420
1421
1422
1423
1424
1425
1426
1427
1428
1429
1430
1431
1432
1433
1434
1435
1436
1437
1438
1439
1440
1441
1442
1443
1444
1445
1446
1447
1448
1449
1450
1451
1452
1453
1454
1455
1456
1457
1458
1459
1460
1461
1462
1463
1464
1465
1466
1467
1468
1469
1470
1471
1472
1473
1474
1475
1476
1477
1478
1479
\subsection{Three Dimensional Plot Types}
{
\tikzset{external/figure name/.add={}{threedim_}}%
\label{sec:3d}
\PGFPlots\ provides three dimensional visualizations like scatter, line, mesh or surface plots. This section explains the methods to provide input coordinates and how to use the different plot types.

\subsubsection{Before You Start With 3D}
\label{pgfplots:3d:preliminary}
Before we delve into the capabilities of \PGFPlots\ for three dimensional visualization, let me start with some preliminary remarks. The reason to use \PGFPlots\ for three dimensional plots are similar to those of normal, two dimensional plots: the possibility to get consistent fonts and document consistent styles combined with high--quality output.

While this works very nice for (not too complex) two dimensional plots, it requires considerably more effort than non--graphical documents. This is even more so for three dimensional plots. In other words: \PGFPlots' three dimensional routines are slow. There are reasons for this and some of them may vanish in future versions. But one of these reasons is that \TeX\ has never been designed for complex visualisation techniques. Consider the image externalization routines mentioned in Section~\ref{sec:pgfplots:export}, in particular the |external| library to reduce typesetting time. Besides the speed limitations, three dimensional plots reach memory limits easily. Therefore, the plot complexity of three dimensional plots is limited to relatively coarse resolutions. Section~\ref{sec:pgfplots:export} also discusses methods to extend the initial \TeX\ memory limits.

Another issue which arises in three dimensional visualization is depth. \PGFPlots\ supports $z$ buffering techniques up to a certain extend. It works pretty well for single scatter plots (|z buffer=sort|), mesh or surface plots (|z buffer=auto|) or parametric mesh and surface plots (|z buffer=sort|). However, it can't combine different |\addplot| commands, those will be drawn in the order of appearance.
You may encounter the limitations sometimes. Maybe it will be improved in future versions.

If you decide that you need high complexity, speed and 100\% reliable z buffers (depth information), you should consider using other visualization tools and return to \PGFPlots\ in several years. If you can wait for a complex picture and you don't even see the limitations arising from z buffering limitations, you should use \PGFPlots. Again, consider using the automatic picture externalization with the |external| library discussed in Section~\ref{sec:pgfplots:export}.

Enough for now, let's continue.

\subsubsection{The \texttt{\textbackslash addplot3} Command: Three Dimensional Coordinate Input}
\label{pgfplots:sec:threedim}
\begin{addplot3generic}
	The \verbpdfref{\addplot3} command is the main interface for any three dimensional plot. It works in the same way as its two dimensional variant |\addplot| which has been described in all detail in Section~\ref{cmd:pgfplots:addplot} on page~\pageref{cmd:pgfplots:addplot}.

	The \verbpdfref{\addplot3} command accepts the same input methods as the |\addplot| variant, including expression plotting, coordinates, files and tables. However, a third coordinate is necessary for each of these methods which is usually straight--forward and is explained in all detail in the following.

	Furthermore, \verbpdfref{\addplot3} has a way to decide whether a \emph{line} visualization or a \emph{mesh} visualization has to be done. The first one is a map from one dimension into $\R^3$ and the latter one a map from two dimensions to $\R^3$. Here, the keys |mesh/rows| and |mesh/cols| are used to define mesh sizes (matrix sizes). Usually, you don't have to care about that because the coordinate input routines already allow either one- or two-dimensional structure.
\end{addplot3generic}

\begin{addplot3operation}[]{coordinates}{\marg{coordinate list}}
	The \verbpdfref{\addplot3 coordinates} method works like its two--dimensional variant, \verbpdfref{\addplot coordinates} which is described in all detail on page~\pageref{pgfplots:addplot:coordinates}:

	A long list of coordinates |(|\meta{x}|,|\meta{y}|,|\meta{z}|)| is expected, separated by white spaces. The input list can be either an unordered series of coordinates, for example for scatter or line plots. It can also have matrix structure, in which case an empty input line (which is equivalent to ``|\par|'') marks the end of one matrix row. Matrix structure can also be provided if one of |mesh/rows| or |mesh/cols| is provided explicitly.
	
\long\def\temporarytest{\noexpand\par}
\begin{codeexample}[newline=\temporarytest]
\begin{tikzpicture}
	\begin{axis}
		% this yields a 3x4 matrix:
		\addplot3[surf] coordinates {
			(0,0,0) (1,0,0)   (2,0,0)   (3,0,0)

			(0,1,0) (1,1,0.6) (2,1,0.7) (3,1,0.5)

			(0,2,0) (1,2,0.7) (2,2,0.8) (3,2,0.5)
		};
	\end{axis}
\end{tikzpicture}
\end{codeexample}
	\noindent Here, \verbpdfref{\addplot3} reads a matrix with three rows and four columns. The empty lines separate one row from the following.

	As for the two--dimensional |plot coordinates|, it is possible to provide (constant) mathematical expressions inside of single coordinates. The syntax |(|\meta{x}|,|\meta{y}|,|\meta{z}|) |\oarg{meta} can be used just as for two dimensional |plot coordinates| to provide explicit color data; error bars are also supported.
\end{addplot3operation}

\begin{addplot3operation}[]{file}{\marg{name}}
	The \verbpdfref{\addplot3 file} input method is the same as \verbpdfref{\addplot file} -- it only expects one more coordinate.
	Thus, the input file contains $x_i$ in the first column, $y_i$ in the second column and $z_i$ in the third. 
	
	A further column is read after $z_i$ if |point meta=explicit| has been requested, see the documentation of \verbpdfref{\addplot file} on page~\pageref{pgfplots:addplot:file} for details.
	
	As for \verbpdfref{\addplot3 coordinates}, an empty line in the file marks the end of one matrix row.
\begin{codeexample}[]
\begin{tikzpicture}
	\begin{axis}
		% We have `plotdata/first3d.dat' with
		%---------
		% 0 0 0.8
		% 1 0 0.56
		% 2 0 0.5
		% 3 0 0.75
		%
		% 0 1 0.6
		% 1 1 0.3
		% 2 1 0.21
		% 3 1 0.3
		%
		% 0 2 0.68
		% 1 2 0.22
		% 2 2 0.25
		% 3 2 0.4
		%
		% 0 3 0.7
		% 1 3 0.5
		% 2 3 0.58
		% 3 3 0.9
		% -> yields a 4x4 matrix:
		\addplot3[surf] file {plotdata/first3d.dat};
	\end{axis}
\end{tikzpicture}
\end{codeexample}

	For matrix data in files, it is important to specify the ordering in which the matrix entries have been written. The default configuration is |mesh/ordering=x varies|, so you need to change it to |mesh/ordering=y varies| in case you have columnwise ordering.
\end{addplot3operation}

\begin{addplot3operation}[]{table}{\oarg{column selection}\marg{file}}
	The \verbpdfref{\addplot3 table} input works in the same way as its two dimensional counterpart \verbpdfref{\addplot table}. It only expects a column for the $z$ coordinates. Furthermore, it interprets empty input lines as end--of--row (more generally, end--of--scanline) markers, just as for |plot file|. The remark above about the |mesh/ordering| applies here as well.
\end{addplot3operation}

\begin{pgfplotskeylist}{mesh/rows=\marg{integer},mesh/cols=\marg{integer}}
	For visualization of mesh or surface plots which need some sort of matrix input, the dimensions of the input matrix need to be known in order to visualize the plots correctly. The matrix structure may be known from end--of--row marks (empty lines as general end--of--scanline markers in the input stream) as has been described above.

	If the matrix structure is not yet known, it is necessary to provide at least one of |mesh/rows| or |mesh/cols| where |mesh/rows| indicates the number of samples for $y$ coordinates whereas |mesh/cols| is the number of samples used for $x$ coordinates (see also |mesh/ordering|). 

	Thus, the following example is also a valid method to define an input matrix.
\begin{codeexample}[]
\begin{tikzpicture}
	\begin{axis}
		% this yields also a 3x4 matrix:
		\addplot3[surf,mesh/rows=3] coordinates {
			(0,0,0) (1,0,0)   (2,0,0)   (3,0,0)
			(0,1,0) (1,1,0.6) (2,1,0.7) (3,1,0.5)
			(0,2,0) (1,2,0.7) (2,2,0.8) (3,2,0.5)
		};
	\end{axis}
\end{tikzpicture}
\end{codeexample}

	It is enough to supply one of |mesh/rows| or |mesh/cols| -- the missing value will be determined automatically.
	
	If you provide one of |mesh/rows| or |mesh/cols|, any end--of--row marker seen inside of input files or coordinate streams will be ignored.

\end{pgfplotskeylist}

\begin{pgfplotskeylist}{mesh/scanline verbose=\mchoice{true,false} (initially false)}
	Provides debug messages in the \LaTeX\ output about end--of--scanline markers.

	The message will tell whether end--of--scanlines have been found and if they are the same.
\end{pgfplotskeylist}

\begin{pgfplotskey}{mesh/ordering=\mchoice{x varies,y varies,rowwise,colwise} (initially x varies)}
	Allows to configure the sequence in which matrices (meshes) are read from \verbpdfref{\addplot3 coordinates}, \verbpdfref{\addplot3 file} or \verbpdfref{\addplot3 table}.

	Here, \declaretext{x varies} means a sequence of points where $n$=|mesh/cols| successive points have the $y$ coordinate fixed. This is intuitive when you write down a function because $x$ is horizontal and $y$ vertical. Note that in matrix terminology, $x$ refers to \emph{column indices} whereas $y$ refers to \emph{row indices}. Thus, |x varies| is equivalent to \declaretext{rowwise} ordering in this sense. This is the initial configuration.
	
\long\def\temporarytest{\noexpand\par}
\begin{codeexample}[newline=\temporarytest]
\begin{tikzpicture}
\begin{axis}[mesh/ordering=x varies]
	% this yields a 3x4 matrix in `x varies'
	% ordering:
	\addplot3[surf] coordinates {
		(0,0,0) (1,0,0)   (2,0,0)   (3,0,0)

		(0,1,0) (1,1,0.6) (2,1,0.7) (3,1,0.5)

		(0,2,0) (1,2,0.7) (2,2,0.8) (3,2,0.5)
	};
\end{axis}
\end{tikzpicture}
\end{codeexample}

	Consequently, |mesh/ordering=|\declaretext{y varies} provides points such that successive $m$=|mesh/rows| points form a column, i.e. the $x$ coordinate is fixed and the $y$ coordinate changes. In this sense, |y varies| is equivalent to \declaretext{colwise} ordering, it is actually a matrix transposition.
\long\def\temporarytest{\noexpand\par}
\begin{codeexample}[newline=\temporarytest]
\begin{tikzpicture}
\begin{axis}[mesh/ordering=y varies]
	% this yields a 3x4 matrix in colwise ordering:
	\addplot3[surf] coordinates {
		(0,0,0) (0,1,0)   (0,2,0)

		(1,0,0) (1,1,0.6) (1,2,0.7)

		(2,0,0) (2,1,0.7) (2,2,0.8)

		(3,0,0) (3,1,0.5) (3,2,0.5)
	};
\end{axis}
\end{tikzpicture}
\end{codeexample}
	Again, note the subtle difference to the common matrix indexing where a column has the second index fixed. \PGFPlots\ refers to the way one would write down a function on a sheet of paper (this is consistent with how Matlab (tm) displays discrete functions with matrices).

\end{pgfplotskey}

\begin{addplot3operation}[]{\marg{math expression}}{}
\label{cmd:addplot3:expr}
	\pgfmanualpdflabel{\textbackslash addplot3 expression}{}%
	Expression plotting also works in the same way as for two dimensional plots. Now, however, a two dimensional mesh is sampled instead of a single line, which may depend on |x| and |y|.

	The method \verbpdfref{\addplot3} \marg{math expr} visualizes the function $f(x,y) = $\meta{math expr} where $ f \colon [x_1,x_2] \times [y_1,y_2] \to \R$. The interval $[x_1,x_2]$ is determined using the |domain| key, for example using |domain=0:1|. The interval $[y_1,y_2]$ is determined using the |y domain| key. If |y domain| is empty, $[y_1,y_2] = [x_1,x_2]$ will be assumed. If |y domain=0:0| (or any other interval of length zero), it is assumed that the plot does not depend on |y| (thus, it is a line plot).

	The number of samples in $x$ direction is set using the |samples| key. The number of samples in $y$ direction is set using the |samples y| key. If |samples y| is not set, the same value as for $x$ is used. If |samples y|$\,\le 1$, it is assumed that the plot does not depend on |y| (meaning it is a line plot).

\pgfplotsexpensiveexample
\begin{codeexample}[]
\begin{tikzpicture}
	\begin{axis}
		\addplot3[surf] {y};
	\end{axis}
\end{tikzpicture}
\end{codeexample}

\pgfplotsexpensiveexample
\begin{codeexample}[]
\begin{tikzpicture}
	\begin{axis}[colorbar]
		\addplot3
			[surf,faceted color=blue,
			 samples=15,
			 domain=0:1,y domain=-1:1]
			{x^2 - y^2};
	\end{axis}
\end{tikzpicture}
\end{codeexample}

	Expression plotting sets |mesh/rows| and |mesh/cols| automatically; these settings don't have any effect for expression plotting.
\end{addplot3operation}

\begin{addplot3operation}[]{expression}{\marg{math expression}}
	The syntax

	\verbpdfref{\addplot3} \marg{math expression}|;|

	as short-hand equivalent for

	\verbpdfref{\addplot3 expression} \marg{math expression}|;|
\end{addplot3operation}

\begin{addplot3operation}[]{(\meta{$x$ expression},\meta{$y$ expression},\meta{$z$ expression})}{}
	A variant of \verbpdfref{\addplot3 expression} which allows to provide different coordinate expressions for the $x$, $y$ and $z$ coordinates. This can be used to generate parametrized plots.

	Please note that |\addplot3 (x,y,x^2)| is equivalent to |\addplot3 expression {x^2}|.

	Note further that since the complete point expression is surrounded by round braces, round braces inside of \meta{$x$ expression}, \meta{$y$ expression} or \meta{$z$ expression} need to be treated specially. Surround the expressions (which contain round braces) with curly braces:

	|\addplot3 (|\marg{$x$ expr}|, |\marg{$y$ expr}|, |\marg{$z$ expr}|);|
\end{addplot3operation}

\subsubsection{Line Plots}

Three dimensional line plots are generated if the input source has no matrix structure. Line plots take the input coordinates and connect them in the order of appearance.

\begin{codeexample}[]
\begin{tikzpicture}
	\begin{axis}[xlabel=$x$,ylabel=$y$]
	\addplot3 coordinates {(0,0,0) (0,0.5,1) (0,1,0)};
	\addplot3 coordinates {(0,1,0) (0.5,1,1) (1,1,0)};
	\end{axis}
\end{tikzpicture}
\end{codeexample}
If there is no value for neither |mesh/rows| nor |mesh/cols| or if one of them is |1|, \PGFPlots\ will draw a line plot. This is also the case if there is no end--of--scanline marker (empty line) in the input stream.

For \verbpdfref{\addplot3 expression}, this requires to set |samples y=0| to disable the generation of a mesh.
\begin{codeexample}[]
\begin{tikzpicture}
\begin{axis}[view={60}{30}]
\addplot3+[domain=0:5*pi,samples=60,samples y=0] 
	({sin(deg(x))},
	 {cos(deg(x))},
	 {2*x/(5*pi)});
\end{axis}
\end{tikzpicture}
\end{codeexample}

Three dimensional line plots will usually employ lines to connect points (i.e.\ the initial |sharp plot| handler of \Tikz). The |smooth| method of \Tikz\ might also prove be an option. Note that no piecewise constant plot, comb or bar plot handler is supported for three dimensional axes.

\subsubsection{Scatter Plots}

Three dimensional scatter plots have the same interface as for two dimensional scatter plots, so all examples of Section~\ref{sec:pgfplots:scatter:2d} can be used for the three dimensional case as well. 
The key features are to use |only marks| and/or |scatter| as plot styles. 

We provide some more examples which are specific for the three dimensional case.

Our first example uses |only marks| to place the current plot |mark| at each input position:
\pgfplotsexpensiveexample
\begin{codeexample}[]
\begin{tikzpicture}
	\begin{axis}[
		xlabel=$x$,
		ylabel=$y$,
		zlabel={$f(x,y) = x\cdot y$},
		title=A Scatter Plot Example]
	% `pgfplotsexample4_grid.dat' contains a
	% large sequence of input points of the form
	% x_0   x_1     f(x)    
	% 0     0       0       
	% 0     0.03125 0       
	% 0     0.0625  0       
	% 0     0.09375 0       
	% 0     0.125   0       
	% 0     0.15625 0       
	\addplot3+[only marks] table
		{plotdata/pgfplotsexample4_grid.dat};
	\end{axis}
\end{tikzpicture}
\end{codeexample}

If we add the key |scatter|, the plot mark will also use the colors of the current |colormap|:
\pgfplotsexpensiveexample
\begin{codeexample}[]
\begin{tikzpicture}
	\begin{axis}[
		xlabel=$x$,
		ylabel=$y$,
		zlabel={$f(x,y) = x\cdot y$},
		title=A Scatter Plot Example]
	\addplot3+[only marks,scatter] table 
		{plotdata/pgfplotsexample4_grid.dat};
	\end{axis}
\end{tikzpicture}
\end{codeexample}

A more sophisticated example is to draw the approximated function as a |surf| plot (which requires matrix data) and the underlying grid (which is |scatter|ed data) somewhere into the same axis. We choose to place the $(x,y)$ grid points at $z=1.4$. Furthermore, we want the grid points to be colored according to the value of column |f(x)| in the input table:
\pgfplotsexpensiveexample
\begin{codeexample}[]
\begin{tikzpicture}
	\begin{axis}[
		3d box,
		zmax=1.4,
		colorbar,
		xlabel=$x$,
		ylabel=$y$,
		zlabel={$f(x,y) = x\cdot y$},
		title={Using Coordinate Filters to fix $z=1.4$}]
	% `pgfplotsexample4.dat' contains similar data as in 
	% `pgfplotsexample4_grid.dat', but it uses a uniform
	% matrix structure (same number of points in every scanline).
	% See examples above for extracts.
	\addplot3[surf,mesh/ordering=y varies] 
		table {plotdata/pgfplotsexample4.dat};
	\addplot3[scatter,scatter src=\thisrow{f(x)},only marks, z filter/.code={\def\pgfmathresult{1.4}}] 
		table {plotdata/pgfplotsexample4_grid.dat};
	\end{axis}
\end{tikzpicture}
\end{codeexample}
\noindent We used |z filter| to fix the $z$ coordinate to $1.4$. We could also have used the |table/z expr=1.4| feature
\begin{codeexample}[code only]
	\addplot3[scatter,scatter src=\thisrow{f(x)},only marks] 
		table[z expr=1.4] {plotdata/pgfplotsexample4_grid.dat};
\end{codeexample}
\noindent to get exactly the same effect. Choose whatever you like best. The |z filter| works for every coordinate input routine, the |z expr| feature is only available for |plot table|.


The following example uses |mark=cube*| and |z buffer=sort| to place boxes at each input coordinate. The color for each box is determined by |point meta={x+y+3}|. The remaining keys are just for pretty printing.
\pgfplotsexpensiveexample
\begin{codeexample}[]
\begin{tikzpicture}
\begin{axis}[
	view={120}{40},
	width=220pt,
	height=220pt,
	grid=major,
	z buffer=sort,
	xmin=-1,xmax=9,
	ymin=-1,ymax=9,
	zmin=-1,zmax=9,
	enlargelimits=upper,
	xtick={-1,1,...,19},
	ytick={-1,1,...,19},
	ztick={-1,1,...,19},
	xlabel={$l_1$},
	ylabel={$l_2$},
	zlabel={$l_3$},
	point meta={x+y+z+3},
	colormap={summap}{
		color=(black); color=(blue); 
		color=(black); color=(white) 
		color=(orange) color=(violet) 
		color=(red)
	},
	scatter/use mapped color={
		draw=mapped color,fill=mapped color!70},
	]
	% `pgfplots_scatter4.dat' contains a large sequence of
	% the form
	% l_0   l_1     l_2     
	% 1     6       -1      
	% -1    -1      -1      
	% 0     -1      -1      
	% -1    0       -1      
	% -1    -1      0       
	% 1     -1      -1      
	% 0     0       -1      
	% 0     -1      0       
	\addplot3[only marks,scatter,mark=cube*,mark size=7] 
		table {plotdata/pgfplots_scatterdata4.dat};

\end{axis}
\end{tikzpicture}
\end{codeexample}


\subsubsection{Mesh Plots}
\label{sec:2d:mesh}
\begin{plottype}[/pgfplots]{mesh}
	A mesh plot uses different colors for each mesh segment. The color is determined using a ``color coordinate'' which is also called ``meta data'' throughout this document. It is the same data which is used for surface and scatter plots as well, see Section~\ref{pgfplots:pointmeta}. In the initial configuration, the ``color coordinate'' is the $z$ axis (or the $y$ axis for two dimensional plots). This color coordinate is mapped linearly into the current color map to determine the color for each mesh segment. Thus, if the smallest occurring color data is, say, $-1$ and the largest is $42$, points with color data $-1$ will get the color at the lower end of the color map and points with color data $42$ the color of the upper end of the color map.

\pgfplotsexpensiveexample
\begin{codeexample}[]
\begin{tikzpicture}
	\begin{axis}
		\addplot3[mesh] {x^2};
	\end{axis}
\end{tikzpicture}
\end{codeexample}

	A mesh plot can be combined with markers or with the |scatter| key which also draws markers in different colors.

\pgfplotsexpensiveexample
\begin{codeexample}[]
\begin{tikzpicture}
	\begin{axis}
	\addplot3+[mesh,scatter,samples=10,domain=0:1] 
		{x*(1-x)*y*(1-y)};
	\end{axis}
\end{tikzpicture}
\end{codeexample}

\pgfplotsexpensiveexample
\begin{codeexample}[]
\begin{tikzpicture}
	\begin{axis}[grid=major,view={210}{30}]
	\addplot3+[mesh,scatter,samples=10,domain=0:1] 
		{5*x*sin(2*deg(x)) * y*(1-y)};
	\end{axis}
\end{tikzpicture}
\end{codeexample}

	Occasionally, one may want to hide the background mesh segments. This can be realized using the |surf| plot handler (see below) and a specific fill color:
\pgfplotsexpensiveexample
\begin{codeexample}[]
\begin{tikzpicture}
	\begin{axis}[title=With background]
	\addplot3[mesh,domain=-2:2] {exp(-x^2-y^2)};	
	\end{axis}
\end{tikzpicture}
\begin{tikzpicture}
	\begin{axis}[title=Without background]
	\addplot3[surf,fill=white,domain=-2:2] {exp(-x^2-y^2)};	
	\end{axis}
\end{tikzpicture}
\end{codeexample}
	The fill color needs to be provided explicitly.

	\paragraph{Details:}
	\begin{itemize}
		\item 
	A mesh plot uses the same implementation as |shader=flat| to get one color for each single segment. Thus, if |shader=flat mean|, the color for a segment is determined using the \emph{mean} of the color data of adjacent vertices. If |shader=flat corner|, the color of a segment is the color of \emph{one} adjacent vertex.
		\item As soon as |mesh| is activated, |color=mapped color| is installed. This is \emph{necessary} unless one needs a different color -- but |mapped color| is the only color which reflects the color data.

		It is possible to use a different color using the |color=|\meta{color name} as for any other plot.

		\item It is easily possible to add |mark=|\meta{marker name} to mesh plots, |scatter| is also possible. Scatter plots will use the same color data as for the mesh.
	\end{itemize}

\pgfplotsexpensiveexample
\begin{codeexample}[]
\begin{tikzpicture}
	\begin{axis}[view/az=14]
	\addplot3[mesh,draw=red,samples=10] {x^2-y^2};	
	\end{axis}
\end{tikzpicture}
\end{codeexample}
	
	Mesh plots use the |mesh legend| style to typeset legend images.
\end{plottype}

\begin{pgfplotskey}{mesh/check=\mchoice{false,warning,error} (initially error)}
	Allows to configure whether an error is generated if |mesh/rows| $\times$ |mesh/cols| does not equal the total number of coordinates.

	If you know exactly what you are doing, it may be useful to disable the check. If you are unsure, it is best to leave the initial setting.
\end{pgfplotskey}

\begin{pgfplotskey}{z buffer=\mchoice{default,none,auto,sort,reverse x seq,reverse y seq,reverse xy seq} (initially default)}
	This key allows to choose between different $z$ buffering strategies. A $z$ buffer determines which parts of an image should be drawn in front of other parts. Since both, the graphics packages \PGF\ and the final document format |.pdf| are inherently two dimensional, this work has to be done in \TeX. Currently, several (fast) heuristics can be used which work reasonably well for simple mesh- and surface plots. Furthermore, there is a (time consuming) sorting method which also works if the fast heuristics fails.

	The $z$ buffering algorithms of \PGFPlots\ apply only to a single |\addplot| command. Different |\addplot| commands will be drawn on top of each other, in the order of appearance.

	The choice \declaretext{default} checks if we are currently working with a mesh or surface plot and uses |auto| in this case. If not, it sets |z buffer=none|.

	The choice \declaretext{none} disables $z$ buffering. This is also the case for two dimensional axes which don't need $z$ buffering.

	The choice \declaretext{auto} is the initial value for any mesh or surface plot: it uses a very fast heuristics to decide how to realize $z$ buffering for mesh and surface plots. The idea is to reverse either the sequence of all $x$ coordinates, or those of all $y$ coordinates, or both. For regular meshes, this suffices to provide $z$ buffering. In other words: the choice |auto| will use one of the three reverse strategies |reverse |*| seq| (or none at all). The choice |auto|, applied to |patch| plots, uses |z buffer=sort| since |patch| plots have no matrix structure.

	The choice \declaretext{sort} can be used for scatter, line, mesh, surface and patch plots. It sorts according to the depth of each point (or mesh segment). Sorting in \TeX\ uses a slow algorithm and may require a lot of memory (although it has the expected runtime asymptotics $\mathcal O(N \log N)$). The depth of a mesh segment is just \emph{one} number, currently determined as \emph{mean} over the vertex depths. Since |z buffer=sort| is actually just a more intelligent way of drawing mesh segments on top of each other, it may still fail. Failure can occur if mesh segments are large and overlap at different parts of the segment (see Wikipedia ``Painter's algorithm''). If you experience problems of this sort, consider reducing the mesh width (the mesh element size) such that they can be sorted independently (for example automatically using |patch refines=2|, see the |patchplots| library).

	The remaining choices apply only to mesh/surface plots (i.e.\ for matrix data) and do nothing more then their name indicates: they reverse the coordinate sequences of the input matrix (using quasi linear runtime). They should only be used in conjunction by |z buffer=auto|.
\end{pgfplotskey}

\subsubsection{Surface Plots}
\label{sec:pgfplots:surfplots}
\begin{plottype}[/pgfplots]{surf}
	A surface plot visualizes a two dimensional, single patch using different fill colors for each patch segment. Each patch segment is a (pseudo) rectangle, that means input data is given in form of a data matrix as is discussed in the introductory section about three dimensional coordinates,~\ref{pgfplots:sec:threedim}.

\pgfplotsexpensiveexample
\begin{codeexample}[]
\begin{tikzpicture}
	\begin{axis}
		\addplot3[surf,shader=interp] {x*y};
	\end{axis}
\end{tikzpicture}
\end{codeexample}

	The simplest way to generate surface plots is to use the plot expression feature, but -- as discussed in Section~\ref{pgfplots:sec:threedim} -- other input methods like \verbpdfref{\addplot3 table} or \verbpdfref{\addplot3 coordinates} are also possible. 

	The appearance can be configured using |colormap|s, the value of the |shader|, |faceted color| keys and the current |color| and/or |draw|/|fill| color. As for |mesh| plots, the special |color=mapped color| is installed for the faces. The stroking color for faceted plots can be set with |faceted color| (see below for details).

\pgfplotsexpensiveexample
\begin{codeexample}[]
\begin{tikzpicture}
	\begin{axis}[
		grid=major,
		colormap/greenyellow]
	\addplot3[surf,samples=30,domain=0:1] 
		{5*x*sin(2*deg(x)) * y};
	\end{axis}
\end{tikzpicture}
\end{codeexample}

\pgfplotsexpensiveexample
\begin{codeexample}[]
\begin{tikzpicture}
	\begin{axis}
		\addplot3[surf,faceted color=blue] {x+y};
	\end{axis}
\end{tikzpicture}
\end{codeexample}

\pgfplotsexpensiveexample
\begin{codeexample}[]
\begin{tikzpicture}
	\begin{axis}[colormap/cool]
	\addplot3[surf,samples=10,domain=0:1,
		shader=interp] 
		{x*(1-x)*y*(1-y)};
	\end{axis}
\end{tikzpicture}
\begin{tikzpicture}
	\begin{axis}[colormap/cool]
	\addplot3[surf,samples=25,domain=0:1,
		shader=flat] 
		{x*(1-x)*y*(1-y)};
	\end{axis}
\end{tikzpicture}
\end{codeexample}

\pgfplotsexpensiveexample
\begin{codeexample}[]
\begin{tikzpicture}
	\begin{axis}[grid=major]
		\addplot3[surf,shader=interp,
			samples=25,domain=0:2,y domain=0:1] 
			{exp(-x) * sin(pi*deg(y))};
	\end{axis}
\end{tikzpicture}
\end{codeexample}

\pgfplotsexpensiveexample
\begin{codeexample}[]
\begin{tikzpicture}
	\begin{axis}[grid=major]
		\addplot3[surf,shader=faceted,
			samples=25,domain=0:2,y domain=0:1] 
			{exp(-x) * sin(pi*deg(y))};
	\end{axis}
\end{tikzpicture}
\end{codeexample}

	Details about the shading algorithm are provided below in the documentation of |shader|.

	Surface plots use the |mesh legend| style to create legend images.
\end{plottype}

\begin{pgfplotskey}{shader=\mchoice{flat,interp,faceted,flat corner,flat mean,faceted interp} (initially faceted)}
	Configures the shader used for surface plots. The shader determines how the color data available at each single vertex is used to fill the surface patch.

	The simplest choice is to use one fill color for each segment, the choice \declareandlabel{flat}.

\pgfplotsexpensiveexample
\begin{codeexample}[]
\begin{tikzpicture}
	\begin{axis}
	\addplot3[surf,shader=flat,
		samples=10,domain=0:1] 
		{x^2*y};
	\end{axis}
\end{tikzpicture}
\end{codeexample}

	\noindent There are (currently) two possibilities to determine the single color for every segment:
	\begin{description}
		\item[\declaretext{flat corner}] Uses the color data of one vertex to color the segment. It is not defined which vertex is used here\footnote{\PGFPlots\ just uses the last vertex encountered in its internal processings -- but after any $z$ buffer re-orderings.}.

		\item[\declaretext{flat mean}] Uses the mean of all four color data values as segment color. This is the initial value as it provides symmetric colors for symmetric functions.
	\end{description}
	The choice |flat| is actually the same as |flat mean|. Please note that |shader=flat mean| and |shader=flat corner| also influence mesh plots -- the choices determine the mesh segment color.

	Another choice is |shader=|\declareandlabel{interp} which uses Goraud shading (smooth linear interpolation of two triangles approximating rectangles) to fill the segments. 

\pgfplotsexpensiveexample
\begin{codeexample}[]
\begin{tikzpicture}
	\begin{axis}
	\addplot3[surf,shader=interp,
		samples=10,domain=0:1] 
		{x^2*y};
	\end{axis}
\end{tikzpicture}
\end{codeexample}

	The |shader=interp| employs a low--level shading implementation which is currently (only) available for the postscript driver \declaretext{pgfsys-dvips.def} and the |pdflatex| driver \declaretext{pgfsys-pdftex.def}. For other drivers, the choice |shader=interp| will result in a warning and is equivalent to |shader=flat mean|. See also below for detail remarks.
	
	Note that |shader=interp,patch type=bilinear| allows real bilinear interpolation, see the |patchplots| library.


	The choice |shader=|\declareandlabel{faceted} uses a constant fill color for every mesh segment (as for |flat|) and the value of the key |/pgfplots/faceted color| to draw the connecting mesh elements:
\pgfplotsexpensiveexample
\begin{codeexample}[]
\begin{tikzpicture}
	\begin{axis}
	\addplot3[surf,shader=faceted,
		samples=10,domain=0:1] 
		{x^2*y};
	\end{axis}
\end{tikzpicture}
\end{codeexample}

	The last choice is |shader=|\declareandlabel{faceted interp}. As the name suggests, it is a mixture of |interp| and |faceted| in the sense that each element is shaded using linear triangle interpolation (see also the |patchplots| library for bilinear interpolation) in the same way as for |interp|, but additionally, the edges are colored in |faceted color|:
\pgfplotsexpensiveexample
\begin{codeexample}[]
\begin{tikzpicture}
	\begin{axis}
	\addplot3[surf,shader=faceted interp,
		samples=10,domain=0:1] 
		{x^2*y};
	\end{axis}
\end{tikzpicture}
\end{codeexample}
	\noindent In principle, there is nothing wrong with the idea as such, and it looks quite good -- but it enlarges the resulting pdf document considerably and might take a long time to render. It works as follows: for every mesh element (either triangle for |patch| plots or rectangle for lattice plots), it creates a low level shading. It then fills the single mesh element with that shading, and strokes the edges with |faceted color|. The declaration of that many low level shadings is rather inefficient in terms of pdf objects (large output files) and might render slowly\footnote{My experience is as follows: Acrobat reader can efficiently render huge \texttt{interp} shadings. But it is very slow for \texttt{faceted interp} shadings. Linux viewers like xpdf, okular and evince take a very long time to render \texttt{interp} shadings, but are fast for \texttt{faceted interp} shadings.}. For orthogonal plots (like |view={0}{90}|), the effect of |faceted interp| can be gained with less cost if one uses two separate |\addplot| commands: one with |surf| and one with |mesh|. Handle this choice with care.

	\paragraph{Details:}
	\begin{itemize}
		\item All shaders support |z buffer=sort| (starting with version 1.4)
		\item The choice |shader=faceted| is the same as |shader=flat| -- except that it uses a special draw color.
		
		So, |shader=faceted| has the same effect as 
		
		|shader=flat,draw=\pgfkeysvalueof{/pgfplots/faceted color}|.

		\item The |flat| shader uses the current |draw| and |fill| colors. They are set with |color=mapped color| and can be overruled with |draw=|\meta{draw color} and |fill=|\meta{fill color}. The |mapped color| always contains the color of the color map. 

		\item You easily add |mark=|\meta{plot mark} to mesh and/or surface plots or even colored plot marks with |scatter|. The scatter plot feature will use the same color data as for the surface.

		But: Markers and surfaces do not share the same depth information. They are drawn on top of each other.

		
		\item Remarks on |shader=interp|:
			\begin{itemize}
				\item It uses the current color map in any case, ignoring |draw| and |fill|.
				\item For surface plots with lots of points, |shader=interp| produces smaller |pdf| documents, requires less compilation time in \TeX\ and requires less time to display in Acrobat Reader than |shader=flat|.

				\item So, the postscript driver \emph{truncates} coordinates to 24 bit -- which might result in a loss of precision (the truncation is not very intelligent). See the |surf shading/precision| key for details. To improve compatibility, this 24 bit truncation algorithm is enabled by default also for pdf documents.
				\item 
				At the time of this writing, few viewers provide satisfying support for |shader=interp|. The Acrobat Reader has full and fast support for interpolated shadings. But some free Linux viewers like xpdf,
				okular and evince need a long time and do not display the colors correctly\footnote{The author of this package has submitted bugfixes to xpdf/libpoppler, so this issue will hopefully be fixed with upcoming versions.} (evince even shows transparency). I hope this message will soon become outdated... if not, provide bug reports to the Linux community to communicate the need to improve support for Type 4 (|patch|) and Type 5 pdf (|surf|) and Type 7 (|patch| and elements of the |patchplots| library) shadings.
				\item The |interp| shader yields the same outcome as |faceted interp,faceted color=none|, although |faceted interp| requires much more ressources.
			\end{itemize}
	\end{itemize}

\pgfplotsexpensiveexample
\begin{codeexample}[]
\begin{tikzpicture}
	\begin{axis}
	\addplot3[surf,shader=flat,
		draw=black,
		samples=10,domain=0:1] 
		{x^2*y};
	\end{axis}
\end{tikzpicture}
\end{codeexample}

\pgfplotsexpensiveexample
\begin{codeexample}[]
\begin{tikzpicture}
	\begin{axis}
	\addplot3[surf,shader=faceted,
		scatter,mark=*,
		samples=10,domain=0:1] 
		{x^2*y};
	\end{axis}
\end{tikzpicture}
\end{codeexample}
\end{pgfplotskey}

\begin{pgfplotskey}{faceted color=\marg{color name} (initially mapped color!80!black)}
	Defines the color to be used for meshes of faceted surface plots.

	Set |faceted color=none| to disable edge colors.
\end{pgfplotskey}

\begin{pgfplotskey}{surf shading/precision=\mchoice{pdf,postscript,ps} (initially postscript)}
	A key to configure how the low level driver for |shader=interp| writes its data. The choice |pdf| uses 32~bit binary coordinates (which is lossless). The resulting |.pdf| files appear to be correct, but they can't be converted to postscript -- the converter software always complains about an error. 

	The choice |postscript| (or, in short, |ps|) uses 24~bit truncated binary coordinates. This results in both, readable |.ps| and |.pdf| files. However, the truncation is lossy.

	If anyone has ideas how to fix this problem: let me know. As far as I know, Postscript should accept 32~bit coordinates, so it might be a mistake in the shading driver.
\end{pgfplotskey}

\subsubsection{Contour Plots}
{
\tikzset{external/figure name/.add={}{contour_}}%
\PGFPlots\ supports visualization of contour plots whose coordinates have been computed by \emph{external tools}. The |contour prepared| plot handler coming with \PGFPlots\ takes precomputed contour line coordinates and handles their visualization (|contour/draw color|, |contour/labels| etc.). The |contour gnuplot| style takes matrix input in the same format as for |mesh| or |surf| (that includes any of the \PGFPlots\ matrix input methods). It then writes the matrix data to a file and invokes |gnuplot| (or other, user customizable external programs) to compute contour coordinates. Finally, the computed contours are visualized with the |contour prepared| algorithm. Thus, external programs need to compute the contour coordinates and \PGFPlots\ visualizes the result.

We discuss the high level interface to external programs first and continue with |contour prepared| later-on.

\begin{plottype}[/pgfplots]{contour gnuplot=\textcolor{black}{\marg{{\normalfont options with `\texttt{contour/}' or `\texttt{contour external/}' prefix}}}}
	This is a high level contour plot interface. It expects matrix data in the same way as two dimensional |surf| or |mesh| plots do. It then computes contours and visualizes them.
\pgfplotsexpensiveexample
\begin{codeexample}[]
\begin{tikzpicture}
	\begin{axis}[view={0}{90}]
	\addplot3[contour gnuplot]
		{x*y};
	\end{axis}
\end{tikzpicture}
\end{codeexample}
	\noindent The example uses \verbpdfref{\addplot3} together with |expression| plotting, that means the input data is of the form $(x_i,y_i,f(x_i,y_i))$. The |view={0}{90}| flag means ``view from top'', otherwise the contour lines would have been drawn as $z$ value:
\pgfplotsexpensiveexample
\begin{codeexample}[]
\begin{tikzpicture}
	\begin{axis}
	\addplot3[contour gnuplot]
		{exp(0-x^2-y^2)};
	\end{axis}
\end{tikzpicture}
\end{codeexample}

As mentioned, you can use any of the \PGFPlots\ input methods as long as it yields matrix output. Thus, we can re-use our introductory example of matrix data, this time with inline data:
\pgfplotsexpensiveexample
\begin{codeexample}[]%
\begin{tikzpicture}%
	\begin{axis}[view={0}{90}]%
	\addplot3[contour gnuplot]%
		coordinates {
			(0,0,0) (1,0,0)   (2,0,0)   (3,0,0)

			(0,1,0) (1,1,0.6) (2,1,0.7) (3,1,0.5)

			(0,2,0) (1,2,0.7) (2,2,0.8) (3,2,0.5)
		};
	\end{axis}%
\end{tikzpicture}%
\end{codeexample}
	\noindent 

	What happens behind the scenes is that \PGFPlots\ takes the input matrix and writes all encountered coordinates to a temporary file, including the end--of--scanline markers. Then, it generates a small |gnuplot| script and invokes |gnuplot| to compute the contour coordinates, writing everything into a temporary output file. Afterwards, it includes |gnuplot|'s output file just as if you'd write |\addplot3[contour prepared] file |\marg{temporaryfile}|;|.

	All this invocation of |gnuplot|, including input/output file management is transparent to the user. It only requires two things: first of all, it requires matrix data as input\footnote{Note that \texttt{contour gnuplot} processes the input stream only once. Consequently, the temporary file will contain only information which was available before the first point has been seen. The example above works because it contains empty lines as end-of-scanline markers. If you do not provide such markers, you may need to provide two of the three options \texttt{mesh/rows}, \texttt{mesh/cols}, or \texttt{mesh/num points}.}. Second, it requires you to enable system calls. Consider the documentation for \verbpdfref{plot gnuplot} for how to enable system calls.

	There are several fine-tuning parameters of the input/output file management, and it is even possible to invoke different programs than |gnuplot| (even |matlab|). These details are discussed at the end of this section, see below at page~\pageref{key:pgfplots:contour:gnuplot}.
\end{plottype}

\begin{pgfplotskey}{contour/number=\marg{integer} (initially 5)}
	Configures the number of contour lines which should be produced by any external contouring algorithm.	
\pgfplotsexpensiveexample
\begin{codeexample}[]
\begin{tikzpicture}
    \begin{axis}[
        title={$x \exp(-x^2-y^2)$},
		domain=-2:2,enlarge x limits,
        view={0}{90},
    ]
   \addplot3[contour gnuplot={number=14},thick]
          {exp(0-x^2-y^2)*x};
    \end{axis}
\end{tikzpicture}
\end{codeexample}
	It is also possible to change the |/pgf/number format| settings, see the documentation for the |contour/every contour label| style below.


	Note that |contour/number| has no effect on |contour prepared|.
\end{pgfplotskey}

\begin{plottype}[/pgfplots]{contour prepared=\textcolor{black}{\marg{{\normalfont options with `\texttt{contour/}' prefix}}}}
	A plot handler which expects already computed contours on input and visualizes them. It cannot compute contours on its own.

	\begin{pgfplotskey}{contour prepared format=\mchoice{standard,matlab} (initially standard)}
	There are two accepted input formats. The first is a long sequence of coordinates of the form $(x,y,z)$ where all successive coordinates with the same $z$ value make up a contour level (this is only part of complete truth, see below). The end--of--scanline markers (empty lines in the input) mark an interruption in one contour level.

	For example, |contour prepared format=standard| could be\footnote{This is actually the output from our \texttt{\textbackslash addplot3[contour gnuplot] coordinates} example from above.}
\begin{codeexample}[]
\begin{tikzpicture}
	\begin{axis}
	\addplot[contour prepared]
		table {
			 2  2  0.8        
			                  
			 0.857143  2  0.6 
			 1  1  0.6        
			 2  0.857143  0.6 
			 2.5  1  0.6      
			 2.66667  2  0.6  
			                  
			 0.571429  2  0.4 
			 0.666667  1  0.4 
			 1  0.666667  0.4 
			 2  0.571429  0.4 
			 3  0.8  0.4      
			                  
			 0.285714  2  0.2 
			 0.333333  1  0.2 
			 1  0.333333  0.2 
			 2  0.285714  0.2 
			 3  0.4  0.2      
		};
	\end{axis}
\end{tikzpicture}
\end{codeexample}
	\noindent Note that the empty lines are not necessary in this case: empty lines make only a difference if they occur within the same contour level (i.e. if the same $z$ value appears above and below of them).
		
		The choice |contour prepared format=matlab| expects two--dimensional input data where the contour level and the number of elements of the contour line are provided as $x$ and $y$ coordinates, respectively, of a leading point. Such a format is used by |matlab|'s contour algorithms, i.e.\ it resembles the output of the matlab commands |data=contour(...)| or |data=contourc(...)|.

% I generates the following example with plotdata/pgfplotscontourmatlabexample.m

\begin{codeexample}[]
\begin{tikzpicture}
	\begin{axis}
	\addplot[contour prepared,
		contour prepared format=matlab]
	table {
% (0.2,5) ==> contour `0.2' (x), 5 points follow (y):
	   2.0000000e-01   5.0000000e+00 
	   3.0000000e+00   4.0000000e-01 
	   2.0000000e+00   2.8571429e-01 
	   1.0000000e+00   3.3333333e-01 
	   3.3333333e-01   1.0000000e+00 
	   2.8571429e-01   2.0000000e+00 
% (0.4,5) ==> contour `0.4', consists of 5 points
	   4.0000000e-01   5.0000000e+00 
	   3.0000000e+00   8.0000000e-01 
	   2.0000000e+00   5.7142857e-01 
	   1.0000000e+00   6.6666667e-01 
	   6.6666667e-01   1.0000000e+00 
	   5.7142857e-01   2.0000000e+00 
% (0.6,6) ==> contour `0.6', has 6 points
	   6.0000000e-01   6.0000000e+00 
	   2.6666667e+00   2.0000000e+00 
	   2.5000000e+00   1.0000000e+00 
	   2.0000000e+00   8.5714286e-01 
	   1.0000000e+00   1.0000000e+00 
	   1.0000000e+00   1.0000000e+00 
	   8.5714286e-01   2.0000000e+00 
		};
	\end{axis}
\end{tikzpicture}
\end{codeexample}

		In case you use matlab, you can generate such data with
\begin{verbatim}
[x,y]=meshgrid(linspace(0,1,15));
data=contour(x,y,x.*y);
data=data';
save 'exporteddata.dat' data -ASCII
\end{verbatim}
	\end{pgfplotskey}

	As already mentioned in the beginning, the $z$ coordinate is not necessarily the coordinate used to delimit contour levels. In fact, the |point meta| data is acquired here, i.e.\ you are free to use whatever $z$ coordinate you want as long as you have a correct |point meta| value. The example from above could be modified as follows:
\begin{codeexample}[]
\begin{tikzpicture}
	\begin{axis}[
		title=Separating $z$ from Color Value,
		xlabel=$x$,
		ylabel=$y$,
	]
	\addplot3[contour prepared,
		point meta=\thisrow{level}]
		table {
	 x         y   z   level   
	 0.857143  2  0.4 0.6		
	 1         1  0.6  0.6		
	 2  0.857143 0.6  0.6		
	 2.5  1      0.6  0.6		
	 2.66667  2  0.4  0.6		
	                  		
	 0.571429  2  0.2 0.4		
	 0.666667  1  0.4 0.4		
	 1  0.666667  0.4 0.4		
	 2  0.571429  0.4 0.4		
	 3  0.8       0.2 0.4		
	                  		
	 0.285714  2  0   0.2		
	 0.333333  1  0.2 0.2		
	 1  0.333333  0.2 0.2		
	 2  0.285714  0.2 0.2		
	 3  0.4       0   0.2		
		};
	\end{axis}
\end{tikzpicture}
\end{codeexample}
	\noindent The example above uses different $z$ coordinates for each first and each last point on contour lines. The contour lines as such are defined by the |level| column since we wrote |point meta=\thisrow{level}|. Such a feature also allows |contour prepared| for nonstandard axes, compare the examples for the |ternary| lib on page~\pageref{page:ternary:contour}.

	\begin{pgfplotskey}{contour/draw color=\marg{color} (initially mapped color)}
		Defines the draw color for every contour. Note that only |mapped color| actually depends on the contour level.
	\end{pgfplotskey}

	\begin{pgfplotskey}{contour/labels=\marg{true,false} (initially true)}
		Configures whether contour labels shall be drawn or not.
	\end{pgfplotskey}
	\begin{pgfplotskey}{contour/label distance=\marg{dimension} (initially 70pt)}
		Configures the distance between adjacend contour labels within the same contour level.
	\end{pgfplotskey}

	\begin{stylekey}{/pgfplots/contour/every contour label}
		Allows to customize contour labels. The preferred way to change this style is the |contour label style=|\marg{options} method, see below.

		The initial value is
\begin{codeexample}[code only]
\pgfplotsset{
	contour/every contour label/.style={
		sloped,
		transform shape,
		inner sep=2pt,
		every node/.style={mapped color!50!black,fill=white},
		/pgf/number format/relative={\pgfplotspointmetarangeexponent},
	}
}
\end{codeexample}
	\noindent Note that |\pgfplotspointmetarangeexponent|$=e$ where $\pm m \cdot 10^e$ is the largest occuring label value (technically, it is the largest occurring value of |point meta|).

		The following example modifies the |/pgf/number format| styles for contour labels:
\begin{codeexample}[]
\begin{tikzpicture}
    \begin{axis}[
        title={$x \exp(-x^2-y^2)$},
		domain=-2:2,enlarge x limits,
        view={0}{90},
    ]
   \addplot3[
   		contour gnuplot={
			scanline marks=required,
   			number=14,
			contour label style={
				/pgf/number format/fixed,
				/pgf/number format/precision=1,
			},
		},thick
	]
          {exp(0-x^2-y^2)*x};
    \end{axis}
\end{tikzpicture}
\end{codeexample}
	\end{stylekey}
	
\pgfplotsshortstylekey contour/contour label style=contour/every contour label\pgfeov
	\begin{stylekey}{/pgfplots/contour/labels over line}
		A style which changes |every contour label| such that labels are right over the lines, without fill color.

\begin{codeexample}[]
\begin{tikzpicture}
	\begin{axis}[view={0}{90}]
	\addplot3[contour gnuplot={
		labels over line,number=9}]
		{x*y};
	\end{axis}
\end{tikzpicture}
\end{codeexample}
	\end{stylekey}

	\begin{stylekey}{/pgfplots/contour/handler}
		Allows to modify the plot handler which connects the points of a single contour level.

		The initial value is 
\begin{codeexample}[code only]
\pgfplotsset{contour/handler/.style={/tikz/sharp plot}}
\end{codeexample}
		but a useful alternative might be the |smooth| handler.
	\end{stylekey}

	\begin{pgfplotscodekey}{contour/label node code}
		A lowlevel interface to modify how contour labels are placed.

		The initial value is
\begin{codeexample}[code only]
\pgfplotsset{
	contour/label node code/.code={\node {\pgfmathprintnumber{#1}};}
}
\end{codeexample}
	\end{pgfplotscodekey}

\end{plottype}


\begin{plottype}[/pgfplots]{contour external=\textcolor{black}{\marg{{\normalfont options with `\texttt{contour/}' or `\texttt{contour external/}' prefix}}}}
	This handler constitutes a generic interface to external programs to compute contour lines. The |contour gnuplot| method is actually a special case of |contour external|.

	\begin{pgfplotskey}{contour external/file=\marg{base file name} (initially empty)}
		The initial configuration is to automatically generate a unique file name.
	\end{pgfplotskey}

	\begin{pgfplotskey}{contour external/scanline marks=\mchoice{false,if in input,required,true} (initially if in input)}
		Controls how |contour external| writes end-of-scanline markers. 

		The choice |false| writes no such markers at all. In this case, |script| should contain |mesh/rows| and/or |mesh/cols|.

		The choice |if in input| generates end-of-scanline markers if they appear in the provided input data (either as empty lines or if the user provided at least two of the three options |mesh/rows|, |mesh/cols|, or |mesh/num points| explicitly).

		The choice |required| works like |if in input|, but it will fail unless there really was such a marker.

		The choice |true| is an alias for |required|.
	\end{pgfplotskey}

	\begin{pgfplotskey}{contour external/script=\marg{Code for external program} (initially empty)}
		Provides template code to generate a script for the external program. Inside of \meta{Code for external program}, the placeholder |\infile| will expand to the temporary input file and |\outfile| to the temporary output file. The temporary |\infile| is a text file containing one point on each line, in the form |x y meta meta|, separated by tabstops. Whenever a scanline is complete, an empty line is issued (but only if these scanline markers are found in the input stream as well). The complete set of scanlines forms a matrix. There are no additional comments or extra characters in the file. The macro |\ordering| will expand to |0| if the matrix is stored in |mesh/ordering=x varies| and |\ordering| will be |1| for |mesh/ordering=y varies|.

		Inside of \meta{Code for external program}, you can also use |\pgfkeysvalueof{/pgfplots/mesh/rows}| and |\pgfkeysvalueof{/pgfplots/mesh/cols}|; they expand to the matrix' size. Similarly, |\pgfkeysvalueof{/pgfplots/mesh/num points}| expands to the total number of points.
	\end{pgfplotskey}

	\begin{pgfplotskey}{contour external/script extension=\marg{extension} (initially script)}
		The file name extension for the temporary script.
	\end{pgfplotskey}

	\begin{pgfplotskey}{contour external/cmd=\marg{system call} (initially empty)}
		A template to generate system calls for the external program. Inside of \meta{system call}, you may use |\script| as placeholder for the filename which contains the result of |contour external/script|.
	\end{pgfplotskey}

	\begin{stylekey}{/pgfplots/contour gnuplot}
		\label{key:pgfplots:contour:gnuplot}
		The initial configuration is
\begin{codeexample}[code only]
\pgfplotsset{
	contour gnuplot/.style={
		contour external={
			script={
				unset surface; 
				set cntrparam levels \pgfkeysvalueof{/pgfplots/contour/number};
				set contour;
				set table \"\outfile\"; 
				splot \"\infile\";
			},
			cmd={gnuplot \"\script\"},
			#1,%
		},
	}
}
\end{codeexample}
	Note that |contour gnuplot| requires explicit scanline markers in the input stream, and it assumes |mesh/ordering=x varies|.
	\end{stylekey}

	Note that |contour external| lacks the intelligence to detect changes; it will always re-generate the output (unless the |-shell-escape| feature is not active).
\end{plottype}

%--------------------------------------------------
% \subsubsection{Filled Contours (Experimental)}
% Filled contour plots are \emph{not} ready yet. There is only limited experimental support up to now. Use at your own risk!
% 
% \begin{pgfplotskey}{contour/data limits={$(\underline x,\underline y,\underline z,\underline m)$ $(\bar x,\bar y,\bar z,\bar m)$} (initially empty)}
% 	The data limits for $x$, $y$, $z$ and |point meta|, separated by comma.
% \end{pgfplotskey}
% 
% \begin{pgfplotskey}{contour/filled=\mchoice{true,false} (initially false)}
% 	A boolean which configures the (highly experimental) feature to fill any |contour prepared| plot.
% \end{pgfplotskey}
% \begin{pgfplotskey}{contour/fill color=\marg{color} (initially mapped color)}
% 	Designates the fill color. Use something like |fill color=mapped color!80!black| if you want to distinguish between edges and filled area.
% \end{pgfplotskey}
%-------------------------------------------------- 

}

\subsubsection{Parameterized Plots}
Parameterized plots use the same plot types as documented in the preceding sections: both |mesh| and |surf|ace plots are actually special parametrized plots where $x$ and $y$ are on cartesian grid points.

Parameterized plots just need a special way to provide the coordinates:

\pgfplotsexpensiveexample
\begin{codeexample}[]
\begin{tikzpicture}
	\begin{axis}[view={60}{30}]
	\addplot3+[domain=0:5*pi,samples=60,samples y=0] 
		({sin(deg(x))},
		 {cos(deg(x))},
		 {2*x/(5*pi)});
	\end{axis}
\end{tikzpicture}
\end{codeexample}
\noindent The preceding example uses |samples y=0| to indicate that a line shall be sampled instead of a matrix. The curly braces are necessary because \TeX\ can't nest round braces. The single expressions here are used to parametrize the helix.

Another example follows. Note that |z buffer=sort| is a necessary method here.

\pgfplotsexpensiveexample
\begin{codeexample}[]
\begin{tikzpicture}
\begin{axis}[view={60}{30}]
	\addplot3[mesh,z buffer=sort,
		samples=20,domain=-1:0,y domain=0:2*pi]
		({sqrt(1-x^2) * cos(deg(y))},
		 {sqrt( 1-x^2 ) * sin(deg(y))},
		 x);
\end{axis}
\end{tikzpicture}
\end{codeexample}

\pgfplotsexpensiveexample
\begin{codeexample}[]
\begin{tikzpicture}
\begin{axis}[view={60}{30}]
	\addplot3[mesh,z buffer=sort,
		scatter,only marks,scatter src=z,
		samples=30,domain=-1:1,y domain=0:2*pi]
		({sqrt(1-x^2) * cos(deg(y))},
		 {sqrt( 1-x^2 ) * sin(deg(y))},
		 x);
\end{axis}
\end{tikzpicture}
\end{codeexample}

\pgfplotsexpensiveexample
\begin{codeexample}[]
\begin{tikzpicture}
\begin{axis}[view={60}{30}]
	\addplot3[surf,shader=interp,z buffer=sort,
		samples=30,domain=-1:0,y domain=0:2*pi]
		({sqrt(1-x^2) * cos(deg(y))},
		 {sqrt( 1-x^2 ) * sin(deg(y))},
		 x);
\end{axis}
\end{tikzpicture}
\end{codeexample}

\subsubsection{3D Quiver Plots (Arrows)}
Three dimensional |quiver| plots are possible with the same interface as their two-dimensional counterparts, simply provide the third coordinate using |quiver/w|. Please refer to Section~\ref{sec:pgfplots:quiver2d} for details and examples.

\subsubsection{About 3D Const Plots and 3D Bar Plots}
There are currently \emph{no} equivalents of |const plot| and its variants or the bar plot types like |ybar| for three dimensional axes, sorry.

\subsubsection{Patch Plots}
\label{sec:pgfplots:3d:patch}
\begin{plottype}[/pgfplots]{patch}
	Patch plots are similar to |mesh| and |surf| plots in that they describe a filled area by means of a geometry.

	However, |patch| plots are defined by \emph{explicitly} providing the elements of the geometry: they expect a sequence of triangles (or other |patch type|s) which make up the mesh.

	There are two dimensional and three dimensional patch plots, both with the same interfaces which are explained in the following sections.

	The standard input format (constituted by |mesh input=patches|) is to provide a sequence of coordinates (either two-- or three--dimensional) as usual. Each consecutive set of points makes up a patch element, which is often a triangle:
\begin{codeexample}[]
\begin{tikzpicture}
	\begin{axis}
	\addplot[patch]
	table {
		x y 
		0 0 
		1 1 
		2 0
% empty lines do not hurt, they are ignored here:

		1 1 
		2 0 
		3 1 
		
		2 0 
		3 1 
		4 0 
		
	};
	\end{axis}
\end{tikzpicture}
\end{codeexample}
	\noindent Patch plots use |point meta| to determine fill colors. In its initial configuration, |point meta| will be set to the $y$ coordinate (or the $z$ coordinate for three dimensional |patch| plots). Set |point meta| somehow to color the patches:
\begin{codeexample}[]
\begin{tikzpicture}
	\begin{axis}
	\addplot[patch]
	table[point meta=\thisrow{c}] {
		x y c
		0 0 0.2
		1 1 0
		2 0 1
		
		1 1 0
		2 0 1
		3 1 0
		
		2 0 1
		3 1 0
		4 0 0.5
	};
	\end{axis}
\end{tikzpicture}
\end{codeexample}
	Patch plots make use of the |mesh| configuration, including the |shader|. Thus, the example above uses the initial |shader=faceted| (which uses the \emph{mean} color data to determine a triangle's color and a related stroke color). The |shader=interp| yields the following result\footnote{At the time of this writing, many free readers, especially those for Linux, have difficulties displaying the correct color maps and take a long time to render. Acrobat reader displays the shading according to the pdf standard. Bugfixes for xpdf/libpoppler are currently about to be tested.}:
\begin{codeexample}[]
\begin{tikzpicture}
	\begin{axis}
	\addplot[patch,shader=interp]
	table[point meta=\thisrow{c}] {
		x y c
		0 0 0.2
		1 1 0
		2 0 1
		
		1 1 0
		2 0 1
		3 1 0
		
		2 0 1
		3 1 0
		4 0 0.5
	};
	\end{axis}
\end{tikzpicture}
\end{codeexample}
	\noindent For triangles, |shader=interp| results in linearly interpolated |point meta| values throughout each individual triangle, which are then mapped to the color map (a technique also known as Gouraud shading).

	The color data does not need to be continuous, it is associated to triangle vertices. Thus, changing some of the color values allows individually shaded regions:
\begin{codeexample}[]
\begin{tikzpicture}
	\begin{axis}
	\addplot[patch,shader=interp]
	table[point meta=\thisrow{c}] {
		x y c
		0 0 0.2
		1 1 0
		2 0 1
		
		1 1 0
		2 0 -1
		3 1 0
		
		2 0 0.5
		3 1 1
		4 0 0.5
	};
	\end{axis}
\end{tikzpicture}
\end{codeexample}
	
	Two dimensional |patch| plots simply draw triangles in their order of appearance. In three dimensions, single elements are sorted according to their view depth, with foreground elements drawn on top of background elements (``Painter's algorithm'', see |z buffer=sort|).

\begin{pgfplotskeylist}{%
	patch table=\marg{table file name or inline table} (initially empty),%
	patch table with point meta=\marg{table file name or inline table} (initially empty),%
	patch table with individual point meta=\marg{table file name or inline table} (initially empty)%
}
	Allows to provide patch connectivity data stored in an input table.

	A non--empty argument for |patch table| enables patch input mode. Now, the standard input stream is a long list of vertices which are stored in an array using their |\coordindex| as key. Each row of \meta{table file name or inline table} makes up one patch, defined by indices into the vertex array:
\begin{codeexample}[]
\begin{tikzpicture}
	\begin{axis}
	\addplot[patch,table/row sep=\\,patch table={%
		0 1 2\\
		1 2 3\\
		4 3 5\\
	}]
	table[row sep=\\,point meta=\thisrow{c}] {
		x y c  \\
		0 0 0.2\\% 0
		1 1 0  \\% 1
		2 0 1  \\% 2
		3 1 0  \\% 3
		2 0 0.5\\% 4
		4 0 0.5\\% 5
	};
	\end{axis}
\end{tikzpicture}
\end{codeexample}
	\noindent The example consists of \emph{two separate} tables. The |patch table| argument is a table, provided inline where rows are separated by |\\| (which is the purpose of the |row sep=\\| key as you guessed\footnote{Note that the choice \texttt{row sep=\textbackslash\textbackslash} is much more robust here: newlines would be converted to spaces by \TeX\ before \PGFPlots\ had a chance to see them.}). The |patch table| here declares three triangles: the triangle made up by vertex $\#0$, $\#1$ and $\#2$, the triangle made up by $\#1$, $\#2$ and $\#3$ and finally the one using the vertices $\#4$, $\#3$ and $\#5$. The vertices as such are provided using the standard input methods of \PGFPlots; in our case using a table as well. The standard input simply provides coordinates (and |point meta|) which are stored in the vertex array; you could also have used |plot coordinates| to provide them (or |plot expression|).
	
	The argument to |patch table| needs to be a table -- either a file name or an inline table as in the example above. The first $n$ columns of this table are assumed to contain indices into the vertex array (which is made up using all vertices of the standard input as explained in the previous paragraph). The entries in this table can be provided in floating point, just make sure they are not rounded. The variable $n$ is the number of vertices required to make up a single patch. For triangular patches, it is $n=3$, for |patch type=bilinear| it is $n=4$ and similar for other choices of |patch type|.

	The alternative \declaretext{patch table with point meta} is almost the same as |patch table| -- but it allows to provide (a single) |point meta| (color data) per patch instead of per vertex. Here, a further column of the argument table is interpreted as color data:
\begin{codeexample}[]
\begin{tikzpicture}
	\begin{axis}
	% this uses per-patch color data:
	\addplot[patch,table/row sep=\\,
	patch table with point meta={%
		0 1 2 100\\
		1 2 3 10\\
		4 3 5 0\\
	}]
	table[row sep=\\] {
		x y \\
		0 0 \\% 0
		1 1 \\% 1
		2 0 \\% 2
		3 1 \\% 3
		2 0 \\% 4
		4 0 \\% 5
	};
	\end{axis}
\end{tikzpicture}
\end{codeexample}
	\noindent The |patch table with point meta| always prefers |point meta| data from the provided table argument. However, it is still supported to write |point meta=\thisrow|\marg{colname} or similar constructs -- but now, \meta{colname} refers to the provided table argument. More precisely, |point meta| is evaluated in a context where the patch connectivity has been resolved and the |patch table with point meta| is loaded.

	The other alternative \declaretext{patch table with individual point meta} is very similar, but instead of a flat color per patch, it allows to write one color value for every patch:
\begin{codeexample}[]
\begin{tikzpicture}
	\begin{axis}
	% this uses n per-patch color values:
	\addplot[patch,shader=interp,
	table/row sep=\\,
	patch table with individual point meta={%
		0 1 2 100 100 100\\% V_0 V_1 V_2 C_0 C_1 C_2
		1 2 3 10 0 50\\
		4 3 5 0 0 100\\
	}]
	table[row sep=\\] {
		x y \\
		0 0 \\% 0
		1 1 \\% 1
		2 0 \\% 2
		3 1 \\% 3
		2 0 \\% 4
		4 0 \\% 5
	};
	\end{axis}
\end{tikzpicture}
\end{codeexample}
	\noindent To find the |point meta| data for vertex $\#i, i=0,1,2$, \PGFPlots\ searches in column $i+n$ where $n$ is the number of vertices for |patch type| (in our case, $n=3$). 
	
	Technical remark: The key |patch table with individual point meta| automatically installs |point meta=explicit| as well. It might be confusing to override the value of |point meta| here (although it is allowed). 

	The |patch table| input type allows to reduce the size of geometries since vertices are stored just once. \PGFPlots\ unpacks them into memory into the redundant format in order to work with single patch elements\footnote{The reason for such an approach is that \TeX\ doesn't really know what an array is -- and according to my experience, arrays implemented by macros tend to blow up \TeX's memory limits even faster than the alternative.}. In case you experience \TeX\ memory problems with this connectivity input, consider using the redundant format. It uses other types of memory limits.
	\index{Errors!Patch Input and Memory Problems}
\end{pgfplotskeylist}
	
	A more involved example is shown below; it uses |\addplot3[patch]| to visualize a three dimensional |patch| plot, provided by means of a long sequence of patches:
\pgfplotsexpensiveexample
\begin{codeexample}[]
\begin{tikzpicture}
\begin{axis}[axis equal]
% FokkerDrI_layer_0.patches.dat contains:
% # each row is one vertex; three consecutive 
% # vertices make one triangle (patch)
% 105.577	-19.7332	2.85249	
% 88.9233	-21.1254	13.0359	
% 89.2104	-22.1547	1.46467	
% # end of facet 0
% 105.577	-19.7332	2.85249	
% 105.577	-17.2161	12.146	
% 88.9233	-21.1254	13.0359	
% # end of facet 1
\addplot3[patch] 
	file
	{plotdata/FokkerDrI_layer_0.patches.dat};
\end{axis}
\end{tikzpicture}
\end{codeexample}
	\noindent The ordering in which triangles are specified is irrelevant, three--dimensional patch plots use |z buffer=sort| to sort patches according to their depth (defined as mean depth over each vertex), where foreground patches are drawn on top of background patches. This so--called ``Painter's algorithm'' works well for most meshes. If it fails, consider using |patch refines=1| or |patch refines=2| to split larger elements into small ones automatically.


	The drawing color associated to single vertices can be changed using the |point meta| key (which is the common method to configure color data in \PGFPlots). The initial configuration is |point meta=z| for three dimensional |patch| plots, i.e.\ to use the $z$ coordinate also as color data. Use |point meta=\thisrow|\marg{colname} in conjunction with |\addplot3[patch] table| to load a selected table column.

	Patch plots are (almost) the same as |mesh| or |surf| plots, they only have more freedom in their input format (and a more complicated geometry). Actually, ``|patch|'' is just a style for |surf,mesh input=patches|. In other words, |patch| \emph{is} the same as |surf|, it even shares the same internal implementation. Thus, most of the keys to configure |mesh| or |surf| plots apply to |patch| as well, especially |shader| and |z buffer|. As already mentioned, |\addplot3[patch]| automatically activates |z buffer=sort| to ensure a good drawing sequence. The |shader| can be used to modify the appearance:
\pgfplotsexpensiveexample
\begin{codeexample}[]
\begin{tikzpicture}
\begin{axis}
% FokkerDrI_layer_0.facetIdx.dat contains:
% # each row makes up one facet; it 
% # consists of 0-based indices into 
% # the vertex array
% 0	1	2 % triangle of vertices #0,#1 and #2
% 0	3	1 % triangle of vertices #0,#3 and #1	
% 3	4	1	
% 5	6	7	
% 6	8	7	
% 8	9	7	
% 8	10	9	
% ...
% while FokkerDrI_layer_0.vertices.dat contains
% 105.577	-19.7332	2.85249	% vertex #0
% 88.9233	-21.1254	13.0359	% vertex #1
% 89.2104	-22.1547	1.46467	% vertex #2
% 105.577	-17.2161	12.146	
% 105.577	-10.6054	18.7567	
% 105.577	7.98161	18.7567	
% 105.577	14.5923	12.146	
% ...
\addplot3[patch,shader=interp,
	patch table=
		{plotdata/FokkerDrI_layer_0.facetIdx.dat}] 
	file
	{plotdata/FokkerDrI_layer_0.vertices.dat};
\end{axis}
\end{tikzpicture}
\end{codeexample}
	See the description of |shader=interp| for details and remarks. The example above makes use of the alternative syntax to provide a geometry: the |patch table| input. It allows to provide vertices separate from patch connectivity, where each patch is defined using three indices into the vertex array as discussed above.

\pgfplotsexpensiveexample
\begin{codeexample}[]
\begin{tikzpicture}
\begin{axis}[view/h=70]
% FokkerDrI_layer_0.patches.dat contains:
% # each row is one vertex; three consecutive 
% # vertices make one triangle (patch)
% 105.577	-19.7332	2.85249	
% 88.9233	-21.1254	13.0359	
% 89.2104	-22.1547	1.46467	
% # end of facet 0
% 105.577	-19.7332	2.85249	
% 105.577	-17.2161	12.146	
% 88.9233	-21.1254	13.0359	
% # end of facet 1
\addplot3[patch,mesh] 
	file
	{plotdata/FokkerDrI_layer_0.patches.dat};
\end{axis}
\end{tikzpicture}
\end{codeexample}

\begin{pgfplotskey}{mesh input=\mchoice{lattice,patches}}
	This key controls how input coordinates are decoded to get patches. It is used only if |patch table| is empty (|patch table| has its own way to decode input coordinates). Usually, you won't need to bother with this key as it is set implicitly.

	The choice |mesh input=lattice| is the initial configuration for |mesh| and |surf| plots: it expects input in a compact matrix form as described at the beginning of this section starting with page~\pageref{sec:3d} and requires a |mesh/ordering| and perhaps end--of--scanline markers. It yields patches with exactly four corners and is compatible with |patch type=rectangle| and |patch type=bilinear| (the latter requiring to load the |patchplots| library).

	The choice |mesh input=patches| is implicitly set when you use the |patch| style (remember that |surf| is actually some sort of patch plot on its own). It expects the input format as described for |patch| plots, i.e.\ $n$ consecutive coordinates make up the vertices of a single patch where $n$ is the expected number of vertices for the configured |patch type|. 

	Note that a non--empty |patch table| implies |mesh input=patches|.
\end{pgfplotskey}

\begin{pgfplotskey}{patch type=\mchoice{default,rectangle,triangle,line} (initially default)}
\label{key:patch:type}
	Defines the type of patch. 

	The initial configuration |patch type=|\declaretext{default} checks the configuration of |mesh input|: for |mesh input=patches|, it uses |triangle|. For |mesh input=lattice|, it checks if there is just one row or just one col and uses |patch type=line| in such a case, otherwise it uses |patch type=rectangle|.

	The choice |patch type=|\declareandlabel{rectangle} expects $n=4$ vertices. The vertices can be either encoded as a matrix or, using |mesh input=patches|, in the sequence in which you would connect the vertices:
\begin{codeexample}[]
\begin{tikzpicture}
	\begin{axis}[nodes near coords={(\coordindex)},
		title=Rectangle from matrix input]
	% note that surf implies 'patch type=rectangle'
	\addplot[surf,mesh/rows=2,patch type=rectangle] 
	coordinates {
		(0,0) (1,0) 
		(0,1) (1,1)
	};
	\end{axis}
\end{tikzpicture}
\end{codeexample}
\begin{codeexample}[]
\begin{tikzpicture}
	\begin{axis}[nodes near coords={(\coordindex)},
		title=Rectangle from patch input]
	\addplot[patch,patch type=rectangle] 
	coordinates {
		(0,0) (1,0) (1,1) (0,1)
	};
	\end{axis}
\end{tikzpicture}
\end{codeexample}
	\noindent As for all other |patch type| values, the vertices can be arbitrary two-- or three--dimensional points, there may be even two on top of each other (resulting in a triangle). When used together with |shader=interp|, |patch type=rectangle| is visualized using two Gouraud shaded triangles (see below for |triangle|). It is the \emph{most efficient} representation for interpolated shadings together with |mesh input=lattice| since the input lattice is written directly into the pdf. Use |patch type=rectangle| if you want rectangular elements and perhaps ``some sort'' of smooth shading. Use |patch type=bilinear| of the |patchplots| library in case you need real bilinear shading.

	The choice |patch type=|\declareandlabel{triangle} expects $n=3$ vertices which make up a triangle. The ordering of the vertices is irrelevant: 
\begin{codeexample}[]
\begin{tikzpicture}
	\begin{axis}[nodes near coords={(\coordindex)}]
	\addplot[patch,patch type=triangle] 
	coordinates {
		(0,0) (1,0) (0,1)
	};
	\end{axis}
\end{tikzpicture}
\end{codeexample}
	\noindent The use of |shader=interp| is realized by means of linear interpolation of the three color values (specified with the |point meta| key) between the corners; the resulting interpolated |point meta| values are then mapped into the actual |colormap|. This type of interpolation is called Gouraud shading.


	The choice |patch type=|\declareandlabel{line} expects $n=2$ vertices which make up a line. It is used for one-dimensional |mesh| plots (see Section~\ref{sec:1d:mesh} for examples).

	There are more values for |patch type| like |bilinear|, |triangle quadr|, |biquadratic|, |coons| and |tensor bezier|. Please refer to the separate |patchplots| library in Section~\ref{sec:lib:patchplots}.
\end{pgfplotskey}

\begin{stylekey}{/pgfplots/every patch}
	This style will be installed as soon as the |patch| plot handler is activated. 

	The initial configuration is
\begin{codeexample}[code only]
\pgfplotsset{
	every patch/.style={miter limit=1}
}
\end{codeexample}
	\noindent which improves display of sharp triangle corners significantly (see the \Tikz\ manual for details about |miter limit| and line join parameters).
\end{stylekey}

	There is much more to say about patch plots, like |patch type| which allows triangles, bilinear elements, quadratic triangles, biquadratic quadrilaterals, coons patches; the |patch refines| key which allows automatic refinement, |patch to triangles| which triangulates higher order elements;  how matrix data can be used for rectangular shapes and more. These details are subject of the |patchplots| library in Section~\ref{sec:lib:patchplots}.
\end{plottype}
}