File: README.pod

package info (click to toggle)
libpdl-graphics-gnuplot-perl 2.019-1
  • links: PTS, VCS
  • area: main
  • in suites: bookworm, sid
  • size: 556 kB
  • sloc: perl: 4,115; makefile: 8
file content (2592 lines) | stat: -rw-r--r-- 91,421 bytes parent folder | download
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
1480
1481
1482
1483
1484
1485
1486
1487
1488
1489
1490
1491
1492
1493
1494
1495
1496
1497
1498
1499
1500
1501
1502
1503
1504
1505
1506
1507
1508
1509
1510
1511
1512
1513
1514
1515
1516
1517
1518
1519
1520
1521
1522
1523
1524
1525
1526
1527
1528
1529
1530
1531
1532
1533
1534
1535
1536
1537
1538
1539
1540
1541
1542
1543
1544
1545
1546
1547
1548
1549
1550
1551
1552
1553
1554
1555
1556
1557
1558
1559
1560
1561
1562
1563
1564
1565
1566
1567
1568
1569
1570
1571
1572
1573
1574
1575
1576
1577
1578
1579
1580
1581
1582
1583
1584
1585
1586
1587
1588
1589
1590
1591
1592
1593
1594
1595
1596
1597
1598
1599
1600
1601
1602
1603
1604
1605
1606
1607
1608
1609
1610
1611
1612
1613
1614
1615
1616
1617
1618
1619
1620
1621
1622
1623
1624
1625
1626
1627
1628
1629
1630
1631
1632
1633
1634
1635
1636
1637
1638
1639
1640
1641
1642
1643
1644
1645
1646
1647
1648
1649
1650
1651
1652
1653
1654
1655
1656
1657
1658
1659
1660
1661
1662
1663
1664
1665
1666
1667
1668
1669
1670
1671
1672
1673
1674
1675
1676
1677
1678
1679
1680
1681
1682
1683
1684
1685
1686
1687
1688
1689
1690
1691
1692
1693
1694
1695
1696
1697
1698
1699
1700
1701
1702
1703
1704
1705
1706
1707
1708
1709
1710
1711
1712
1713
1714
1715
1716
1717
1718
1719
1720
1721
1722
1723
1724
1725
1726
1727
1728
1729
1730
1731
1732
1733
1734
1735
1736
1737
1738
1739
1740
1741
1742
1743
1744
1745
1746
1747
1748
1749
1750
1751
1752
1753
1754
1755
1756
1757
1758
1759
1760
1761
1762
1763
1764
1765
1766
1767
1768
1769
1770
1771
1772
1773
1774
1775
1776
1777
1778
1779
1780
1781
1782
1783
1784
1785
1786
1787
1788
1789
1790
1791
1792
1793
1794
1795
1796
1797
1798
1799
1800
1801
1802
1803
1804
1805
1806
1807
1808
1809
1810
1811
1812
1813
1814
1815
1816
1817
1818
1819
1820
1821
1822
1823
1824
1825
1826
1827
1828
1829
1830
1831
1832
1833
1834
1835
1836
1837
1838
1839
1840
1841
1842
1843
1844
1845
1846
1847
1848
1849
1850
1851
1852
1853
1854
1855
1856
1857
1858
1859
1860
1861
1862
1863
1864
1865
1866
1867
1868
1869
1870
1871
1872
1873
1874
1875
1876
1877
1878
1879
1880
1881
1882
1883
1884
1885
1886
1887
1888
1889
1890
1891
1892
1893
1894
1895
1896
1897
1898
1899
1900
1901
1902
1903
1904
1905
1906
1907
1908
1909
1910
1911
1912
1913
1914
1915
1916
1917
1918
1919
1920
1921
1922
1923
1924
1925
1926
1927
1928
1929
1930
1931
1932
1933
1934
1935
1936
1937
1938
1939
1940
1941
1942
1943
1944
1945
1946
1947
1948
1949
1950
1951
1952
1953
1954
1955
1956
1957
1958
1959
1960
1961
1962
1963
1964
1965
1966
1967
1968
1969
1970
1971
1972
1973
1974
1975
1976
1977
1978
1979
1980
1981
1982
1983
1984
1985
1986
1987
1988
1989
1990
1991
1992
1993
1994
1995
1996
1997
1998
1999
2000
2001
2002
2003
2004
2005
2006
2007
2008
2009
2010
2011
2012
2013
2014
2015
2016
2017
2018
2019
2020
2021
2022
2023
2024
2025
2026
2027
2028
2029
2030
2031
2032
2033
2034
2035
2036
2037
2038
2039
2040
2041
2042
2043
2044
2045
2046
2047
2048
2049
2050
2051
2052
2053
2054
2055
2056
2057
2058
2059
2060
2061
2062
2063
2064
2065
2066
2067
2068
2069
2070
2071
2072
2073
2074
2075
2076
2077
2078
2079
2080
2081
2082
2083
2084
2085
2086
2087
2088
2089
2090
2091
2092
2093
2094
2095
2096
2097
2098
2099
2100
2101
2102
2103
2104
2105
2106
2107
2108
2109
2110
2111
2112
2113
2114
2115
2116
2117
2118
2119
2120
2121
2122
2123
2124
2125
2126
2127
2128
2129
2130
2131
2132
2133
2134
2135
2136
2137
2138
2139
2140
2141
2142
2143
2144
2145
2146
2147
2148
2149
2150
2151
2152
2153
2154
2155
2156
2157
2158
2159
2160
2161
2162
2163
2164
2165
2166
2167
2168
2169
2170
2171
2172
2173
2174
2175
2176
2177
2178
2179
2180
2181
2182
2183
2184
2185
2186
2187
2188
2189
2190
2191
2192
2193
2194
2195
2196
2197
2198
2199
2200
2201
2202
2203
2204
2205
2206
2207
2208
2209
2210
2211
2212
2213
2214
2215
2216
2217
2218
2219
2220
2221
2222
2223
2224
2225
2226
2227
2228
2229
2230
2231
2232
2233
2234
2235
2236
2237
2238
2239
2240
2241
2242
2243
2244
2245
2246
2247
2248
2249
2250
2251
2252
2253
2254
2255
2256
2257
2258
2259
2260
2261
2262
2263
2264
2265
2266
2267
2268
2269
2270
2271
2272
2273
2274
2275
2276
2277
2278
2279
2280
2281
2282
2283
2284
2285
2286
2287
2288
2289
2290
2291
2292
2293
2294
2295
2296
2297
2298
2299
2300
2301
2302
2303
2304
2305
2306
2307
2308
2309
2310
2311
2312
2313
2314
2315
2316
2317
2318
2319
2320
2321
2322
2323
2324
2325
2326
2327
2328
2329
2330
2331
2332
2333
2334
2335
2336
2337
2338
2339
2340
2341
2342
2343
2344
2345
2346
2347
2348
2349
2350
2351
2352
2353
2354
2355
2356
2357
2358
2359
2360
2361
2362
2363
2364
2365
2366
2367
2368
2369
2370
2371
2372
2373
2374
2375
2376
2377
2378
2379
2380
2381
2382
2383
2384
2385
2386
2387
2388
2389
2390
2391
2392
2393
2394
2395
2396
2397
2398
2399
2400
2401
2402
2403
2404
2405
2406
2407
2408
2409
2410
2411
2412
2413
2414
2415
2416
2417
2418
2419
2420
2421
2422
2423
2424
2425
2426
2427
2428
2429
2430
2431
2432
2433
2434
2435
2436
2437
2438
2439
2440
2441
2442
2443
2444
2445
2446
2447
2448
2449
2450
2451
2452
2453
2454
2455
2456
2457
2458
2459
2460
2461
2462
2463
2464
2465
2466
2467
2468
2469
2470
2471
2472
2473
2474
2475
2476
2477
2478
2479
2480
2481
2482
2483
2484
2485
2486
2487
2488
2489
2490
2491
2492
2493
2494
2495
2496
2497
2498
2499
2500
2501
2502
2503
2504
2505
2506
2507
2508
2509
2510
2511
2512
2513
2514
2515
2516
2517
2518
2519
2520
2521
2522
2523
2524
2525
2526
2527
2528
2529
2530
2531
2532
2533
2534
2535
2536
2537
2538
2539
2540
2541
2542
2543
2544
2545
2546
2547
2548
2549
2550
2551
2552
2553
2554
2555
2556
2557
2558
2559
2560
2561
2562
2563
2564
2565
2566
2567
2568
2569
2570
2571
2572
2573
2574
2575
2576
2577
2578
2579
2580
2581
2582
2583
2584
2585
2586
2587
2588
2589
2590
2591
2592
=head1 OVERVIEW

This is a Gnuplot-based plotter for PDL. This repository stores the history for
the PDL::Graphics::Gnuplot module on CPAN. Install the module via CPAN. CPAN
page at L<http://metacpan.org/pod/PDL::Graphics::Gnuplot>.

=cut

=head1 NAME

PDL::Graphics::Gnuplot - Gnuplot-based plotting for PDL

=head1 SYNOPSIS

 pdl> use PDL::Graphics::Gnuplot;

 pdl> $x = sequence(101) - 50;
 pdl> gplot($x**2);
 pdl> gplot($x**2,{xr=>[0,50]});

 pdl> gplot( {title => 'Parabola with error bars'},
       with => 'xyerrorbars', legend => 'Parabola',
       $x**2 * 10, abs($x)/10, abs($x)*5 );

 pdl> $xy = zeroes(21,21)->ndcoords - pdl(10,10);
 pdl> $z = inner($xy, $xy);
 pdl> gplot({title  => 'Heat map',
             trid   => 1,
             view   => [0,0]
            },
            with => 'image', xvals($z),yvals($z),zeroes($z),$z*2
           );

 pdl> $w = gpwin();                             # constructor
 pdl> $pi    = 3.14159;
 pdl> $theta = zeroes(200)->xlinvals(0, 6*$pi);
 pdl> $z     = zeroes(200)->xlinvals(0, 5);
 pdl> $w->plot3d(cos($theta), sin($theta), $z);
 pdl> $w->terminfo();                           # get information


=head1 DESCRIPTION

This module allows PDL data to be plotted using Gnuplot as a backend
for 2D and 3D plotting and image display.  Gnuplot (not affiliated
with the Gnu project) is a venerable, open-source program that
produces both interactive and publication-quality plots on many
different output devices.  It is available through most Linux
repositories, on MacOS, and from its website
L<http://www.gnuplot.info>.

It is not necessary to understand the gnuplot syntax to generate
basic, or even complex, plots - though the full syntax is available
for advanced users who want the full flexibility of the Gnuplot
backend.

Gnuplot recognizes both hard-copy and interactive plotting devices,
and on interactive devices (like X11) it is possible to pan, scale,
and rotate both 2-D and 3-D plots interactively.  You can also enter
graphical data through mouse clicks on the device window.  On some
hardcopy devices (e.g. "PDF") that support multipage output, it is
necessary to close the device after plotting to ensure a valid file is
written out.

C<PDL::Graphics::Gnuplot> exports two routines by default: a
constructor, C<gpwin()> and a general purpose plot routine,
C<gplot()>.  Depending on options, C<gplot()> can produce line plots,
scatterplots, error boxes, "candlesticks", images, or any overlain
combination of these elements; or perspective views of 3-D renderings
such as surface plots.

A call to C<gplot()> looks like:

 gplot({temp_plot_options}, # optional hash ref
      curve_options, data, data, ... ,
      curve_options, data, data, ... );

The data entries are columns to be plotted.  They are normally
an optional ordinate and a required abscissa, but some plot modes
can use more columns than that.  The collection of columns is called
a "tuple".  Each column must be a separate PDL or an ARRAY ref.  If
all the columns are PDLs, you can add extra dimensions to make threaded
collections of curves.

PDL::Graphics::Gnuplot also implements an object oriented
interface. Plot objects track individual gnuplot subprocesses.  Direct
calls to C<gplot()> are tracked through a global object that stores
globally set configuration variables.

The C<gplot()> sub (or the C<plot()> method) collects two kinds of
options hash: B<plot options>, which describe the overall structure of
the plot being produced (e.g. axis specifications, window size, and
title), and B<curve options>, which describe the behavior of
individual traces or collections of points being plotted.  In
addition, the module itself supports options that allow direct
pass-through of plotting commands to the underlying gnuplot process.

=head2 Basic plotting

Gnuplot generates many kinds of plot, from basic line plots and histograms
to scaled labels.  Individual plots can be 2-D or 3-D, and different sets
of plot styles are supported in each mode.  Plots can be sent to a variety
of devices; see the description of plot options, below.

You can specify what type of graphics output you want, but in most cases
doing nothing will cause a plot to be rendered on your screen: with
X windows on UNIX or Linux systems, with an XQuartz windows on MacOS,
or with a native window on Microsoft Windows.

You select a plot style with the "with" curve option, and feed in columns
of data (usually ordinate followed by abscissa).  The collection of columns
is called a "tuple".  These plots have two columns in their tuples:

 $x = xvals(51)-25; $y = $x**2;
 gplot(with=>'points', $x, $y);  # Draw points on a parabola
 gplot(with=>'lines', $x, $y);   # Draw a parabola
 gplot({title=>"Parabolic fit"},
       with=>"yerrorbars", legend=>"data", $x, $y+(random($y)-0.5)*2*$y/20, pdl($y/20),
       with=>"lines",      legend=>"fit",  $x, $y);

Normal threading rules apply across the arguments to a given plot.

All data are required to be supplied as either PDLs or list refs.
If you use a list ref as a data column, then normal
threading is disabled.  For example:

 $x = xvals(5);
 $y = xvals(5)**2;
 $labels = ['one','two','three','four','five'];
 gplot(with=>'labels',$x,$y,$labels);

See below for supported curve styles.

=head3 Modifying plots

Gnuplot is built around a monolithic plot model - it is not possible to
add new data directly to a plot without redrawing the entire plot. To support
replotting, PDL::Graphics::Gnuplot stores the data you plot in the plot object,
so that you can add new data with the "replot" command:

 $w=gpwin(x11);
 $x=xvals(101)/100;
 $y=$x;
 $w->plot($x,$y);
 $w->replot($x,$y*$y);

For speed, the data are *not* disconnected from their original variables - so
this will plot X vs. sqrt(X):

 $x = xvals(101)/100;
 $y = xvals(101)/100;
 $w->plot($x,$y);
 $y->inplace->sqrt;
 $w->replot();

=head3 Plotting to an image file or device

PDL:Graphics::Gnuplot can plot to most of the devices supported by
gnuplot itself.  You can specify the file type with the "output"
method or the object constructor "gplot".  Either one will allow you
to name a type of file to produce, and a collection of options speciic to
that type of output file.

=head3 Image plotting

Several of the plot styles accept image data.  The tuple parameters work the
same way as for basic plots, but each "column" is a 2-D PDL rather than a 1-D PDL.
As a special case, the "with image" plot style accepts either a 2-D or a 3-D PDL.
If you pass in 3-D PDL, the extra dimension can have size 1, 3, or 4.  It is interpreted
as running across (R,G,B,A) color planes.

=head3 3-D plotting

You can plot in 3-D by setting the plot option C<trid> to a true value.  Three
dimensional plots accept either 1-D or 2-D PDLs as data columns.  If you feed
in 2-D "columns", many of the common plot styles will generalize appropriately
to 3-D.  For example, to plot a 2-D surface as a line grid, you can use the "lines"
style and feed in 2-D columns instead of 1-D columns.

=head2 Enhanced text

Most gnuplot output devices include the option to markup "enhanced text". That means
text is interpreted so that you can change its font and size, and insert superscripts
and subscripts into labels.  Codes are:

=over 3

=item {}

Text grouping - enclose text in braces to group characters, as in LaTeX.

=item ^

Superscript the next character or group (shrinks it slightly too where that is supported).

=item _

Subscript the next character or group (shrinks it slightly too where that is supported).

=item @

Phantom box (occupies no width; controls height for super- and subscripting)

=item &

Controllable-width space, e.g. &amp;{template-string}

=item ~

overstrike -- e.g. ~a{0.8-} overprints '-' on 'a', raised by 0.8xfontsize.

=item {/[fontname][=fontsize | *fontscale] text}

Change font to (optional) fontname, and optional absolute font size or relative font scale ("fontsize" and "fontscale" are numbers).  The space after the size parameter is not rendered.

=item \

Backslash escapes control characters to render them as themselves.

=back

=head2 Color specification

There are several contexts where you can specify color of plot elements.  In those
places, you can specify colors exactly as in the Gnuplot manual, or more tersely.
In general, a color spec can be any one of the following:

=over 3

=item - an integer

This specifies a recognizable unique color in the same order as used by the plotting engine.

=item - the name of a color

(e.g. "blue").  Supported color names are listed in the variable C<@Alien::Gnuplot::colors>.

=item - an RGB value string

Strings have the form C<#RRGGBB>, where the C<#> is literal and the RR, GG, and BB are hexadecimal bytes.

=item - the word "palette"

"palette" indicates that color is to be drawn from the scaled colorbar
palette (which you can set with the "clut" plot option), by lookup
using an additional column in the associated data tuple.

=item - the word "variable"

"variable" indicates that color is to be drawn from the integer
plotting colors used by the plotting engine, indexed by an additional
column in the associated data tuple.

=item - the phrase "rgb variable"

"rgb variable" indicates that color is to be directly specified by a
24 bit integer specifying 8-bit values for (from most significant byte
to least significant byte) R, G, and B in the output color.  The
integer is drawn from an additional column in the associated data tuple.

=back


=head2 Plot styles supported

Gnuplot itself supports a wide range of plot styles, and all are supported by
PDL::Graphics::Gnuplot.  Most of the basic plot styles collect tuples of 1-D columns
in 2-D mode (for ordinary plots), or either 1-D or 2-D "columns" in 3-D mode (for
grid surface plots and such).  Image modes always collect tuples made of 2-D "columns".

You can pass in 1-D columns as either PDLs or ARRAY refs.  That is important for
plot types (such as "labels") that require a collection of strings rather than
numeric data.

Each plot style can by modified to support particular colors or line
style options.  These modifications get passed in as curve options (see
below). For example, to plot a blue line you can use
C<with=E<gt>'lines',lc=E<gt>'blue'>.  To match the autogenerated style of a
particular line you can use the C<ls> curve option.

The GNuplot plot styles supported are:

=over 3

=item * C<boxerrorbars> - combo of C<boxes> and C<yerrorbars>, below (2D)

=item * C<boxes> - simple boxes around regions on the plot (2D)

=item * C<boxxyerrorbars> - Render X and Y error bars as boxes (2D)

=item * C<candlesticks> - Y error bars with inner and outer limits (2D)

=item * C<circles> - circles with variable radius at each point: X/Y/radius (2D)

=item * C<dots> - tiny points ("dots") at each point, e.g. for scatterplots (2D/3D)

=item * C<ellipses> - ellipses.  Accepts X/Y/major/minor/angle (2D)

=item * C<filledcurves> - closed polygons or axis-to-line filled shapes (2D)

=item * C<financebars> - financial style plot. Accepts date/open/low/high/close (2D)

=item * C<fsteps> - square bin plot; delta-Y, then delta-X (see C<steps>, C<histeps>) (2D)

=item * C<histeps> - square bin plot; plateaus centered on X coords (see C<fsteps>, C<steps>) (2D)

=item * C<histogram> - binned histogram of dataset (not direct plot; see C<newhistogram>) (2D)

=item * C<fits> - (PDL-specific) renders FITS image files in scientific coordinates

=item * C<image> - Takes (i), (x,y,i), or (x,y,z,i).  See C<rgbimage>, C<rgbalpha>, C<fits>. (2D/3D)

=item * C<impulses> - vertical line from axis to the plotted point (2D/3D)

=item * C<labels> - Text labels at specified locations all over the plot (2D/3D)

=item * C<lines> - regular line plot (2D/3D)

=item * C<linespoints> - line plot with symbols at plotted points (2D/3D)

=item * C<newhistogram> - multiple-histogram-friendly histogram style (see C<histogram>) (2D)

=item * C<points> - symbols at plotted points (2D/3D)

=item * C<rgbalpha> - R/G/B color image with variable transparency (2D/3D)

=item * C<rgbimage> - R/G/B color image (2D/3D)

=item * C<steps> - square bin plot; delta-X, then delta-Y (see C<fsteps>, C<histeps>) (2D)

=item * C<vectors> - Small arrows: (x,y,[z]) -> (x+dx,y+dy,[z+dz]) (2D/3D)

=item * C<xerrorbars> - points with X error bars ("T" form) (2D)

=item * C<xyerrorbars> - points with both X and Y error bars ("T" form) (2D)

=item * C<yerrorbars> - points with Y error bars ("T" form) (2D)

=item * C<xerrorlines> - line plot with X errorbars at each point.  (2D)

=item * C<xyerrorlines> - line plot with XY errorbars at each point. (2D)

=item * C<yerrorlines> - line plot with Y error limits at each point. (2D)

=item * C<pm3d> - three-dimensional variable-position surface plot

=back

=head2 Options arguments

The plot options are parameters that affect the whole plot, like the title of
the plot, the axis labels, the extents, 2d/3d selection, etc. All the plot
options are described below in L<"Plot Options"|/"PLOT OPTIONS">.  Plot options can be set
in the plot object, or passed to the plotting methods directly.  Plot options can
be passed in as a leading interpolated hash, as a leading hash ref, or as a trailing
hash ref in the argument list to any of the main plotting routines (C<gplot>, C<plot>,
C<image>, etc.).

The curve options are parameters that affect only one curve in particular. Each
call to C<plot()> can contain many curves, and options for a particular curve
I<precede> the data for that curve in the argument list. The actual type of curve
(the "with" option) is persistent, but all other curve options and modifiers
are not.  An example:

 gplot( with => 'points',  $x, $a,
        {axes=> x1y2},     $x, $b,
        with => 'lines',   $x, $c );

This plots 3 curves: $a vs. $x plotted with points on the main y-axis (this is
the default), $b vs. $x plotted with points on the secondary y axis, and $c
vs. $x plotted with lines on the main y-axis (the default). Note that the curve
options can be supplied as either an inline hash or a hash ref.

All the curve options are described below in L<"Curve Options"|/"CURVE OPTIONS">.

If you want to plot multiple curves of the same type without setting
any curve options explicitly, you must include an empty hash ref
between the tuples for subsequent lines, as in:

 gplot( $x, $a, {}, $x, $b, {}, $x, $c );

=head2 Data arguments

Following the curve options in the C<plot()> argument list is the
actual data being plotted. Each output data point is a "tuple" whose
size varies depending on what is being plotted. For example if we're
making a simple 2D x-y plot, each tuple has 2 values; if we're making
a 3d plot with each point having variable size and color, each tuple
has 5 values (x,y,z,size,color). Each tuple element must be passed
separately.  For ordinary 2-D plots, the 0 dim of the tuple elements
runs across plotted point.  PDL threading is active, so you can plot
multiple curves with similar curve options on a normal 2-D plot, just
by stacking data inside the passed-in PDLs.  (An exception is that
threading is disabled if one or more of the data elements is a list
ref).

=head3 PDLs vs list refs

The usual way to pass in data is as a PDL -- one PDL per column of data
in the tuple.  But strings, in particular, cannot easily be hammered into
PDLs.  Therefore any column in each tuple can be a list ref containing
values (either numeric or string).  The column is interpreted using the
usual polymorphous cast-behind-your-back behavior of Perl.  For the sake
of sanity, if even one list ref is present in a tuple, then threading is
disabled in that tuple: everything has to have a nice 1-D shape.


=head3 Implicit domains

When making a simple 2D plot, if exactly 1 dimension is missing,
PDL::Graphics::Gnuplot will use C<sequence(N)> as the domain. This is
why code like C<plot(pdl(1,5,3,4,4) )> works. Only one PDL is given
here, but the plot type ("lines" by default) requires 2 elements per
tuple. We are thus exactly 1 ndarray short; C<sequence(5)> is used as
the missing domain PDL.  This is thus equivalent to
C<plot(sequence(5), pdl(1,5,3,4,4) )>.

If plotting in 3d or displaying an image, an implicit domain will be
used if we are exactly 2 ndarrays short. In this case,
PDL::Graphics::Gnuplot will use a 2D grid as a domain. Example:

 my $xy = zeros(21,21)->ndcoords - pdl(10,10);
 gplot({'3d' => 1},
        with => 'points', inner($xy, $xy));
 gplot( with => 'image',  sin(rvals(51,51)) );

Here the only given ndarray has dimensions (21,21). This is a 3D plot, so we are
exactly 2 ndarrays short. Thus, PDL::Graphics::Gnuplot generates an implicit
domain, corresponding to a 21-by-21 grid.

C<PDL::Graphics::Gnuplot> requires explicit separators between tuples
for different plots, so it is always clear from the arguments you pass
in just how many columns you are supplying. For example,
C<plot($a,$b)> will plot C<$b> vs. C<$a>.  If you actually want to
plot an overlay of both C<$a> and C<$b> against array index, you want
C<plot($a,{},$b)> instead.  The C<{}> is a hash ref containing a
collection of all the curve options that you are changing between
the two curves -- in this case, zero of them.

=head2 Images

PDL::Graphics::Gnuplot supports four styles of image plot, via the "with" curve option.

The "image" style accepts a single image plane and displays it using
the palette (pseudocolor map) that is specified in the plot options
for that plot.  As a special case, if you supply as data a (3xWxH) or
(WxHx3) PDL it is treated as an RGB image and displayed with the
"rgbimage" style (below), provided there are at least 5 pixels in each of the
other two dimensions (just to be sure).  For quick image display there
is also an "image" method:

 use PDL::Graphics::Gnuplot qw/image gplot/;
 $im = sin(rvals(51,51)/2);
 image( $im );                # display the image
 gplot( with=>'image', $im );  # display the image (longer form)

The colors are autoscaled in both cases.  To set a particular color range, use
the 'cbrange' plot option:

 image( {cbrange=>[0,1]}, $im );

You can plot rgb images directly with the image style, just by including a
3rd dimension of size 3 on your image:

 $rgbim = pdl( xvals($im), yvals($im),rvals($im)/sqrt(2));
 image( $rgbim );                # display an RGB image
 gplot( with=>'image', $rgbim ); # display an RGB image (longer form)

Some additional plot styles exist to specify RGB and RGB transparent forms
directly.  These are the "with" styles "rgbimage" and "rgbalpha".  For each
of them you must specify the channels as separate PDLs:

 gplot( with=>'rgbimage', $rgbim->dog );               # RGB  the long way
 gplot( with=>'rgbalpha', $rgbim->dog, 255*($im>0) );  # RGBA the long way

According to the gnuplot specification you can also give X and Y
values for each pixel, as in

 gplot( with=>'image', xvals($im), yvals($im), $im )

but this appears not to work properly for anything more complicated
than a trivial matrix of X and Y values.

PDL::Graphics::Gnuplot provides a "fits" plot style that interprets
World Coordinate System (WCS) information supplied in the header of
the scientific image format FITS. The image is displayed in rectified
scientific coordinates, rather than in pixel coordinates.  You can plot
FITS images in scientific coordinates with

 gplot( with=>'fits', $fitsdata );

The fits plot style accepts a modifier "resample" (which may be
abbreviated), that allows you to downsample and/or rectify the image
before it is passed to the Gnuplot back-end.  This is useful either to
cut down on the burden of transferring large blocks of image data or
to rectify images with nonlinear WCS transformations in their headers.
(gnuplot itself has a bug that prevents direct rendering of images in
nonlinear coordinates).

 gplot( with=>'fits res 200', $fitsdata );
 gplot( with=>'fits res 100,400',$fitsdata );

to specify that the output are to be resampled onto a square 200x200
grid or a 100x400 grid, respectively.  The resample sizes must be
positive integers.

=head2 Interactivity

Several of the graphical backends of Gnuplot are interactive, allowing
you to pan, zoom, rotate and measure the data interactively in the plot
window. See the Gnuplot documentation for details about how to do
this. Some terminals (such as C<wxt>) are persistently interactive. Other
terminals (such as C<x11>) maintain their interactivity only while the
underlying gnuplot process is active -- i.e. until another plot is
created with the same PDL::Graphics::Gnuplot object, or until the perl
process exits (whichever comes first).  Still others (the hardcopy
devices) aren't interactive at all.

Some interactive devices (notably C<wxt> and C<x11>) also support
mouse input: you can write PDL scripts that accept and manipulate
graphical input from the plotted window.

=head1 PLOT OPTIONS

Gnuplot controls plot style with "plot options" that configure and
specify virtually all aspects of the plot to be produced.   Plot
options are tracked as stored state in the PDL::Graphics::Gnuplot
object.  You can set them by passing them in to the constructor, to an
C<options> method, or to the C<plot> method itself.

Nearly all the underlying Gnuplot plot options are supported, as well
as some additional options that are parsed by the module itself for
convenience.

There are many, many plot options.  For convenience, we've grouped
them by general category below.  Each group has a heading "POs for E<lt>fooE<gt>",
describing the category.  You can skip below them all if you want to
read about curve options or other aspects of PDL::Graphics::Gnuplot.

=head2 POs for Output: terminal, termoption, output, device, hardcopy

You can send plots to a variety of different devices; Gnuplot calls
devices "terminals".  With the object-oriented interface, you must set
the output device with the constructor C<PDL::Graphics::Gnuplot::new>
(or the exported constructor C<gpwin>) or the C<output> method.  If you
use the simple non-object interface, you can set the output with the
C<terminal>, C<termoption>, and C<output> plot options.

C<terminal> sets the output device type for Gnuplot, and C<output> sets the
actual output file or window number.

C<device> and C<hardcopy> are for convenience. C<device> offers a
PGPLOT-style device specifier in "filename/device" format (the "filename"
gets sent to the "output" option, the "device" gets sent to the "terminal"
option). C<hardcopy> takes an output file name, attempts to parse out a
file suffix and infer a device type. C<hardcopy> also uses a common set of
terminal options needed to fill an entire letter page with a plot.

For finer grained control of the plotting environment, you can send
"terminal options" to Gnuplot.  If you set the terminal directly with
plot options, you can include terminal options by interpolating them
into a string, as in C<terminal jpeg interlace butt crop>, or you can
use the constructor C<new> (also exported as C<gpwin>), which parses
terminal options as an argument list.

The routine C<PDL::Graphics::Gnuplot::terminfo> prints a list of all
available terminals or, if you pass in a terminal name, options accepted
by that terminal.


=head2 POs for Titles

The options described here are

=over

=item title

=item xlabel

=item x2label

=item ylabel

=item y2label

=item zlabel

=item cblabel

=item key

=back

Gnuplot supports "enhanced" text escapes on most terminals; see "text",
below.

The C<title> option lets you set a title for the whole plot.

Individual plot components are labeled with the C<label> options.
C<xlabel>, C<x2label>, C<ylabel>, and C<y2label> specify axis titles
for 2-D plots.  The C<zlabel> works for 3-D plots.  The C<cblabel> option
sets the label for the color box, in plot types that have one (e.g.
image display).

(Don't be confused by C<clabel>, which doesn't set a label at all, rather
specifies the printf format used by contour labels in contour plots.)

C<key> controls where the plot key (that relates line/symbol style to label)
is placed on the plot.  It takes a scalar boolean indicating whether to turn the
key on (with default values) or off, or a list ref containing any of the following
arguments (all are optional) in the order listed:

=over 3

=item * ( on | off ) - turn the key on or off

=item * ( inside | outside | lmargin | rmargin | tmargin | bmargin | at <pos> )

These keywords set the location of the key -- "inside/outside" is
relative to the plot border; the margin keywords indicate location in
the margins of the plot; and at <pos> (where <pos> is a comma-delimited string
containing (x,y): C<key=E<gt>[at=E<gt>"0.5,0.5"]>) is an exact location to place the key.

=item * ( left | right | center ) ( top | bottom | center ) - horiz./vert. alignment

=item * ( vertical | horizontal ) - stacking direction within the key

=item * ( Left | Right ) - justification of plot labels within the key (note case)

=item * [no]reverse - switch order of label and sample line

=item * [no]invert - invert the stack order of the labels

=item * samplen <length> - set the length of the sample lines

=item * spacing <dist> - set the spacing between adjacent labels in the list

=item * [no]autotitle - control whether labels are generated when not specified

=item * title "<text>" - set a title for the key

=item * [no]enhanced - override terminal settings for enhanced text interpretation

=item * font "<face>,<size>" - set font for the labels

=item * textcolor <colorspec>

=item * [no]box linestyle <ls> linetype <lt> linewidth <lw> - control box around the key

=back

=head2 POs for axes, grids, & borders

The options described here are

=over

=item grid

=item xzeroaxis

=item x2zeroaxis

=item yzeroaxis

=item y2zeroaxis

=item zzeroaxis

=item border

=back

Normally, tick marks and their labels are applied to the border of a plot,
and no extra axes (e.g. the y=0 line) nor coordinate grids are shown.  You can
specify which (if any) zero axes should be drawn, and which (if any)
borders should be drawn.

The C<border> option controls whether the plot itself has a border
drawn around it.  You can feed it a scalar boolean value to indicate
whether borders should be drawn around the plot -- or you can feed in a list
ref containing options.  The options are all optional but must be supplied
in the order given.

=over 3

=item * <integer> - packed bit flags for which border lines to draw


The default if you set a true value for C<border> is to draw all border lines.
You can feed in a single integer value containing a bit mask, to draw only some
border lines.  From LSB to MSB, the coded lines are bottom, left, top, right for
2D plots -- e.g. 5 will draw bottom and top borders but neither left nor right.

In three dimensions, 12 bits are used to describe the twelve edges of
a cube surrounding the plot.  In groups of three, the first four
control the bottom (xy) plane edges in the same order as in the 2-D
plots; the middle four control the vertical edges that rise from the
clockwise end of the bottom plane edges; and the last four control the
top plane edges.

=item * ( back | front ) - draw borders first or last (controls hidden line appearance)

=item * linewidth <lw>, linestyle <ls>, linetype <lt>

These are Gnuplot's usual three options for line control.

=back

The C<grid> option indicates whether gridlines should be drawn on
each axis.  It takes a list ref of arguments, each of which is either "no" or "m" or "",
followed by an axis name and "tics" --
e.g. C<< grid=>["noxtics","ymtics"] >> draws no X gridlines and draws
(horizontal) Y gridlines on Y axis major and minor tics, while
C<< grid=>["xtics","ytics"] >> or C<< grid=>["xtics ytics"] >> will draw both
vertical (X) and horizontal (Y) grid lines on major tics.

vTo draw a coordinate grid with default values, set C<< grid=>1 >>.  For more
control, feed in a list ref with zero or more of the following parameters, in order:

The C<zeroaxis> keyword indicates whether to actually draw each axis
line at the corresponding zero along its indicated dimension.  For
example, to draw the X axis (y=0), use C<< xzeroaxis=>1 >>.  If you just
want the axis turned on with default values, you can feed in a Boolean
scalar; if you want to set its parameters, you can feed in a list ref
containing linewidth, linestyle, and linetype (with appropriate
parameters for each), e.g.  C<< xzeroaxis=>[linewidth=>2] >>.

=head2 POs for axis range and mode

The options described here are

=over

=item xrange

=item x2range

=item yrange

=item y2range

=item zrange

=item rrange

=item cbrange

=item trange

=item urange

=item vrange

=item autoscale

=item logscale

=back

Gnuplot accepts explicit ranges as plot options for all axes.  Each option
accepts a list ref with (min, max).  If either min or max is missing, then
the opposite limit is autoscaled.  The x and y ranges refer to the usual
ordinate and abscissa of the plot; x2 and y2 refer to alternate ordinate and
abscissa; z if for 3-D plots; r is for polar plots; t, u, and v are for parametric
plots.  cb is for the color box on plots that include it (see "color", below).

C<rrange> is used for radial coordinates (which
are accessible using the C<mapping> plot option, below).

C<cbrange> (for 'color box range') sets the range of values over which
palette colors (either gray or pseudocolor) are matched.  It is valid
in any color-mapped plot (including images or palette-mapped lines or
points), even if no color box is being displayed for this plot.

C<trange>, C<urange>, and C<vrange> set ranges for the parametric coordinates
if you are plotting a parametric curve.

By default all axes are autoscaled unless you specify a range on that
axis, and partially (min or max) autoscaled if you specify a partial
range on that axis.  C<autoscale> allows more explicit control of how
autoscaling is performed, on an axis-by-axis basis.  It accepts a hash
ref, each element of which specifies how a single axis should be
autoscaled.  Each keyword contains an axis name followed by one of
"fix", "min", "max", "fixmin", or "fixmax".  You can set all the axes at
once by setting the keyword name to ' '.  Examples:

 autoscale=>{x=>'max',y=>'fix'};

There is an older list ref syntax which is deprecated but still accepted.

To not autoscale an axis at all, specify a range for it. The fix style of
autoscaling forces the autoscaler to use the actual min/max of the data as
the limit for the corresponding axis -- by default the axis gets extended
to the next minor tic (as set by the autoticker or by a tic specification, see
below).

C<logscale> allows you to turn on logarithmic scaling for any or all
axes, and to set the base of the logarithm.  It takes a list ref, the
first element of which is a string mushing together the names of all
the axes to scale logarithmically, and the second of which is the base
of the logarithm: C<< logscale=>[xy=>10] >>.  You can also leave off the
base if you want base-10 logs: C<< logscale=>['xy'] >>.

=head2 POs for Axis tick marks

The options described here are

=over

=item xtics

=item x2tics

=item ytics

=item y2tics

=item ztics

=item cbtics

=item mxtics

=item mx2tics

=item mytics

=item my2tics

=item mztics

=item mcbtics

=back

Axis tick marks are called "tics" within Gnuplot, and they are extensively
controllable via the "{axis}tics" options.  In particular, major and minor
ticks are supported, as are arbitrarily variable length ticks, non-equally
spaced ticks, and arbitrarily labelled ticks.  Support exists for time formatted
ticks (see C<POs for time data values> below).

By default, gnuplot will automatically place major and minor ticks.
You can turn off ticks on an axis by setting the appropriate {foo}tics
option to a defined, false scalar value (e.g. C<< xtics=>0 >>).  If you
want to set major tics to happen at a regular specified intervals, you can set the
appropriate tics option to a nonzero scalar value (e.g. C<< xtics=>2 >> to
specify a tic every 2 units on the X axis).  To use default values for the
tick positioning, specify an empty hash or array ref (e.g. C<< xtics=>{} >>), or
a string containing only whitespace (e.g. C<< xtics=>' ' >>).

If you prepend an 'm' to any tics option, it affects minor tics instead of
major tics (major tics typically show units; minor tics typically show fractions
of a unit).

Each tics option can accept a hash ref containing options to pass to
Gnuplot.  You can also pass in a snippet of gnuplot command, as either
a string or an array ref -- but those techniques are deprecated and may
disappear in a future version of C<PDL:Graphics::Gnuplot>.

The keywords are case-insensitive and may be abbreviated, just as with
other option types.  They are:

=over 2

=item * axis - set to 1 to place tics on the axis (the default)

=item * border - set to 1 to place tics on the border (not the default)

=item * mirror - set to 1 to place mirrored tics on the opposite axis/border (the default, unless an alternate axis interferes -- e.g. y2)

=item * in - set to 1 to draw tics inward from the axis/border

=item * out - set to 1 to draw tics outward from the axis/border

=item * scale - multiplier on tic length compared to the default

If you pass in undef, tics get the default length.  If you pass in a scalar, major tics get scaled.  You can pass in an array ref to scale minor tics too.

=item * rotate - turn label text by the given angle (in degrees) on the drawing plane

=item * offset - offset label text from default position, (units: characters; requires array ref containing x,y)

=item * locations - sets tic locations.  Gets an array ref: [incr], [start, incr], or [start, incr, stop].

=item * labels - sets tic locations explicitly, with text labels for each. If you specify both C<locations> and C<labels>, you get both sets of tics on the same axis.

The labels should be a nested list ref that is a collection of duals
or triplets.  Each dual or triplet should contain [label, position, minorflag],
as in C<< labels=>[["one",1,0],["three-halves",1.5,1],["two",2,0]] >>.

=item * format - printf-style format string for tic labels.  There are
some extensions to the gnuplot format tags -- see the gnuplot manual.
Gnuplot 4.8 and higher have C<%h>, which works like C<%g> but uses
extended text formatting if it is available.

=item * font - set font name and size (system font name)

=item * rangelimited - set to 1 to limit tics to the range of values actually present in the plot

=item * textcolor - set the color of the tick labels (see L</"Color specification">)

=back

For example, to turn on inward mirrored X axis ticks with diagonal Arial 9 text, use:

 xtics => {axis=>1,mirror=>1,in=>1,rotate=>45,font=>'Arial,9'}

or

 xtics => ['axis','mirror','in','rotate by 45','font "Arial,9"']

=head2 POs for time data values

The options described here are

=over

=item xmtics

=item x2mtics

=item ymtics

=item y2mtics

=item zmtics

=item cbmtics

=item xdtics

=item x2dtics

=item ydtics

=item y2dtics

=item zdtics

=item cbdtics

=item xdata

=item x2data

=item ydata

=item y2data

=item zdata

=item cbdata

=back

Gnuplot contains support for plotting absolute time and date on any of its axes,
with conventional formatting. There are three main methods, which are mutually exclusive
(i.e. you should not attempt to use two at once on the same axis).

=over 3

=item B<Plotting timestamps using UNIX times>

You can set any axis to plot timestamps rather than numeric values by
setting the corresponding "data" plot option to "time",
e.g. C<< xdata=>"time" >>.  If you do so, then numeric values in the
corresponding data are interpreted as UNIX time (seconds since the
UNIX epoch, neglecting leap seconds).  No provision is made for
UTC<->TAI conversion.  You can format how the times are plotted with
the "format" option in the various "tics" options(above).  Output
specifiers should be in UNIX strftime(3) format -- for example,
C<< xdata=>"time",xtics=>{format=>"%Y-%b-%dT%H:%M:%S"} >>
will plot UNIX times as ISO timestamps in the ordinate.

Due to limitations within gnuplot, the time resolution in this mode is
limited to 1 second - if you want fractional seconds, you must use numerically
formatted times (and/or create your own tick labels using the C<labels> suboption
to the C<?tics> option.

B<Timestamp format specifiers>

Time format specifiers use the following printf-like codes:

=over 3

=item * B<Year A.D.>: C<%Y> is 4-digit year; C<%y> is 2-digit year (1969-2068)

=item * B<Month of year>: C<%m>: 01-12; C<%b> or C<%h>: abrev. name; C<%B>: full name

=item * B<Week of year>: C<%W> (week starting Monday); C<%U> (week starting Sunday)

=item * B<Day of year>: C<%j> (1-366; boundary is midnight)

=item * B<Day of month>: C<%d> (01-31)

=item * B<Day of week>: C<%w> (0-6, Sunday=0), %a (abrev. name), %A (full name)

=item * B<Hour of day>: C<%k> (0-23); C<%H> (00-23); C<%l> (1-12); C<%I> (01-12)

=item * B<Am/pm>: C<%p> ("am" or "pm")

=item * B<Minute of hour>: C<%M> (00-60)

=item * B<Second of minute>: C<%S> (0-60)

=item * B<Total seconds since start of 2000 A.D.>: C<%s>

=item * B<Timestamps>: C<%T> (same as C<%H:%M:%S>); C<%R> (same as C<%H:%M>); C<%r> (same as C<%I:%M:%S %p>)

=item * B<Datestamps>: C<%D> (same as C<%m/%d/%y>); C<%F> (same as C<%Y-%m-%d>)

=item * B<ISO timestamps>: use C<%DT%T>.

=back

=item B<day-of-week plotting>

If you just want to plot named days of the week, you can instead use
the C<dtics> options set plotting to day of week, where 0 is Sunday and 6
is Saturday; values are interpreted modulo 7.  For example, C<<
xmtics=>1,xrange=>[-4,9] >> will plot two weeks from Wednesday to
Wednesday. As far as output format goes, this is exactly equivalent to
using the C<%w> option with full formatting - but you can treat the
numeric range in terms of weeks rather than seconds.

=item B<month-of-year plotting>

The C<mtics> options set plotting to months of the year, where 1 is January and 12 is
December, so C<< xdtics=>1, xrange=>[0,4] >> will include Christmas through Easter.
This is exactly equivalent to using the C<%d> option with full formatting - but you
can treat the numeric range in terms of months rather than seconds.

=back

=head2 POs for location/size

The options described here are

=over

=item tmargin

=item bmargin

=item lmargin

=item rmargin

=item offsets

=item origin

=item size

=item justify

=item clip

=back

Adjusting the size, location, and margins of the plot on the plotting
surface is something of a null operation for most single plots -- but
you can tweak the placement and size of the plot with these options.
That is particularly useful for multiplots, where you might like to
make an inset plot or to lay out a set of plots in a custom way.

The margin options accept scalar values -- either a positive number of
character heights or widths of margin around the plot compared to the
edge of the device window, or a string that starts with "at screen "
and interpolates a number containing the fraction of the plot window
offset.  The "at screen" technique allows exact plot placement and is
an alternative to the C<origin> and C<size> options below.

The C<offsets> option allows you to put an empty boundary around the
data, inside the plot borders, in an autosacaled graph.  The offsets
only affect the x1 and y1 axes, and only in 2D plot commands.
C<offsets> accepts a list ref with four values for the offsets, which
are given in scientific (plotted) axis units.

The C<origin> option lets you specify the origin (lower left corner)
of an individual plot on the plotting window.  The coordinates are
screen coordinates -- i.e. fraction of the total plotting window.

The size option lets you adjust the size and aspect ratio of the plot,
as an absolute fraction of the plot window size.  You feed in fractional
ratios, as in C<< size=>[$xfrac, $yfrac] >>.  You can also feed in some keywords
to adjust the aspect ratio of the plot.  The size option overrides any
autoscaling that is done by the auto-layout in multiplot mode, so use
with caution -- particularly if you are multiplotting.  You can use
"size" to adjust the aspect ratio of a plot, but this is deprecated
in favor of the pseudo-option C<justify>.

C<justify> sets the scientific aspect ratio of a 2-D plot.  Unity
yields a plot with a square scientific aspect ratio.  Larger
numbers yield taller plots.

C<clip> controls the border between the plotted data and the border of the plot.
There are three clip types supported:   points, one, and two.  You can set them
independently by passing in booleans with their names: C<< clip=>[points=>1,two=>0] >>.

=head2 POs for Color: colorbox, palette, clut, pseudocolor, pc, perceptual, pcp

Color plots are supported via RGB and pseudocolor.  Plots that use pseudcolor or
grayscale can have a "color box" that shows the photometric meaning of the color.

The colorbox generally appears when necessary but can be controlled manually
with the C<colorbox> option.  C<colorbox> accepts a scalar boolean value indicating
whether or no to draw a color box, or a list ref containing additional options.
The options are all, well, optional but must appear in the order given:

=over 3

=item ( vertical | horizontal ) - indicates direction of the gradient in the box

=item ( default | user ) - indicates user origin and size

If you specify C<default> the colorbox will be placed on the right-hand side of the plot; if you specify C<user>, you give the location and size in subsequent arguments:

 colorbox => [ 'user', 'origin'=>"$x,$y", 'size' => "$x,$y" ]

=item ( front | back ) - draws the colorbox before or after the plot

=item ( noborder | bdefault | border <line style> ) - specify border

The line style is a numeric type as described in the gnuplot manual.

=back

The C<palette> option offers many arguments that are not fully
documented in this version but are explained in the gnuplot manual.
It offers complete control over the pseudocolor mapping function.

For simple color maps, C<clut> gives access to a set of named color
maps.  (from "Color Look Up Table").  A few existing color maps are:
"default", "gray", "sepia", "ocean", "rainbow", "heat1", "heat2", and
"wheel".  To see a complete list, specify an invalid table,
e.g. C<< clut=>'xxx' >>.  C<clut> is maintained but is superseded
by C<pc> and C<pcp> (below), which give access to a better variety
of color tables, and have better support for scientific images.

C<pseudocolor> (synonym C<pc>) gives access to the color tables built
in to the C<PDL::Transform::Color> package, if that package is
available.  It takes either a color table name or a list ref which
is a collection of arguments that get sent to the
C<PDL::Transform::Color::t_pc> transform definition method. Sending
the empty string or undef will generate a list of allowable color
table names.  Many of the color tables are "photometric" and
will render photometric data correctly without gamma correction.

C<perceptual> (synonym C<pcp>) gives the same access to
C<PDL::Transform::Color> as does C<pseudocolor>, but the
"equal-perceptual-difference" scaling is used -- i.e. input
values are gamma-corrected by the module so that uniform
shifts in numeric value yield approximately uniform perceptual
shifts.

If you use C<pseudocolor> or C<perceptual>, and if
C<PDL::Transform::Color> can be loaded, then the external module
is used to define a custom Gnuplot palette by linear interpolation
across 256 values.  That palette is then used to translate your
monochrome data to a color image.  The Gnuplot output is assumed
to be sRGB.  This is probably OK for most output devices.

=head2 POs for 3D: trid, view, pm3d, hidden3d, dgrid3d, surface, xyplane, mapping

If C<trid> or its synonym C<3d> is true, Gnuplot renders a 3-D plot.
This changes the default tuple size from 2 to 3.  This
option is used to switch between the Gnuplot "plot" and "splot"
command, but it is tracked with persistent state just as any other
option.

The C<view> option controls the viewpoint of the 3-D plot.  It takes a
list of numbers: C<< view=>[$rot_x, $rot_z, $scale, $scale_z] >>.  After
each number, you can omit the subsequent ones.  Alternatively,
C<< view=>['map'] >> represents the drawing as a map (e.g. for contour
plots) and C<< view=>[equal=>'xy'] >> forces equal length scales on the X
and Y axes regardless of perspective, while C<< view=>[equal=>'xyz'] >>
sets equal length scales on all three axes.

The C<pm3d> option accepts several parameters to control the pm3d plot style,
which is a palette-mapped 3d surface.  They are not documented here in this
version of the module but are explained in the gnuplot manual.

C<hidden3d> accepts a list of parameters to control how hidden surfaces are
plotted (or not) in 3D. It accepts a boolean argument indicating whether to hide
"hidden" surfaces and lines; or a list ref containing parameters that control how
hidden surfaces and lines are handled.  For details see the gnuplot manual.

C<xyplane> sets the location of that plane (which is drawn) relative
to the rest of the plot in 3-space.  It takes a single string: "at" or
"relative", and a number.  C<< xyplane=>[at=>$z] >> places the XY plane at the
stated Z value (in scientific units) on the plot.  C<< xyplane=>[relative=>$frac] >>
places the XY plane $frac times the length of the scaled Z axis *below* the Z
axis (i.e. 0 places it at the bottom of the plotted Z axis; and -1 places it
at the top of the plotted Z axis).

C<mapping> takes a single string: "cartesian", "spherical", or
"cylindrical".  It determines the interpretation of data coordinates
in 3-space. (Compare to the C<polar> option in 2-D).

=head2 POs for Contour plots - contour, cntrparam

Contour plots are only implemented in 3D.  To make a normal 2D contour
plot, use 3-D mode, but set the view to "map" - which projects the 3-D
plot onto its 2-D XY plane. (This is convoluted, for sure -- future
versions of this module may have a cleaner way to do it).

C<contour> enables contour drawing on surfaces in 3D.  It takes a
single string, which should be "base", "surface", or "both".

C<cntrparam> manages how contours are generated and smoothed.  It
accepts a list ref with a collection of Gnuplot parameters that are
issued one per line; refer to the Gnuplot manual for how to operate
it.

=head2 POs for Polar plots - polar, angles, mapping

You can make 2-D polar plots by setting C<polar> to a true value.  The
ordinate is then plotted as angle, and the abscissa is radius on the plot.
The ordinate can be in either radians or degrees, depending on the
C<angles> parameter

C<angles> takes either "degrees" or "radians" (default is radians).

C<mapping> is used to set 3-D polar plots, either cylindrical or spherical
(see the section on 3-D plotting, above).

=head2 POs for Markup - label, arrow, object

You specify plot markup in advance of the plot command, with plot
options (or add it later with the C<replot> method).  The options give
you access to a collection of (separately) numbered descriptions that
are accumulated into the plot object.  To add a markup object to the
next plot, supply the appropriate options as a list ref or as a single
string.  To specify all markup objects at once, supply the appropriate
options for all of them as a nested list-of-lists.

To modify an object, you can specify it by number, either by appending
the number to the plot option name (e.g. C<arrow3>) or by supplying it
as the first element of the option list for that object.

To remove all objects of a given type, supply undef (e.g. C<< arrow=>undef >>).

For example, to place two labels, use the plot option:

 label => [["Upper left",at=>"10,10"],["lower right",at=>"20,5"]];

To add a label to an existing plot object, if you don't care about what
index number it gets, do this:

 $w->options( label=>["my new label",at=>[10,20]] );

If you do care what index number it gets (or want to replace an existing label),
do this:

 $w->options( label=>[$n, "my replacement label", at=>"10,20"] );

where C<$w> is a Gnuplot object and C<$n> contains the label number
you care about.


=head3 label - add a text label to the plot.

The C<label> option allows adding small bits of text at arbitrary
locations on the plot.

Each label specifier list ref accepts the following suboptions, in
order.  All of them are optional -- if no options other than the index
tag are given, then any existing label with that index is deleted.

For examples, please refer to the Gnuplot 4.4 manual, p. 117.

=over 3

=item <tag> - optional index number (integer)

=item <label text> - text to place on the plot.

You may supply double-quotes inside the string, but it is not
necessary in most cases (only if the string contains just an integer
and you are not specifying a <tag>.

=item at <position> - where to place the text (sci. coordinates)

The <position> should be a string containing a gnuplot position specifier.
At its simplest, the position is just two numbers separated by
a comma, as in C<< label2=>["foo",at=>"5,3"] >>, to specify (X,Y) location
on the plot in scientific coordinates.  Each number can be preceded
by a coordinate system specifier; see the Gnuplot 4.4 manual (page 20)
for details.

=item ( left | center | right ) - text placement rel. to position

=item rotate [ by <degrees> ] - text rotation

If "rotate" appears in the list alone, then the label is rotated 90 degrees
CCW (bottom-to-top instead of left-to-right).  The following "by" clause is
optional.

=item font "<name>,<size>" - font specifier

The <name>,<size> must be double quoted in the string (this may be fixed
in a future version), as in

 label3=>["foo",at=>"3,4",font=>'"Helvetica,18"']

=item noenhanced - turn off gnuplot enhanced text processing (if enabled)

=item ( front | back ) - rendering order (last or first)

=item textcolor <colorspec>

=item (point <pointstyle> | nopoint ) - control whether the exact position is marked

=item offset <offset> - offfset from position (in points).

=back

=head3 arrow - place an arrow or callout line on the plot

Works similarly to the C<label> option, but with an arrow instead of text.

The arguments, all of which are optional but which must be given in the order listed,
are:

=over 3

=item from <position> - start of arrow line

The <position> should be a string containing a gnuplot position specifier.
At its simplest, the position is just two numbers separated by
a comma, as in C<< arrow2=>["foo",at=>"5,3"] >>, to specify (X,Y) location
on the plot in scientific coordinates.  Each number can be preceded
by a coordinate system specifier; see the Gnuplot 4.4 manual (page 20)
for details.

=item ( to | rto ) <position>  - end of arrow line

These work like C<from>.  For absolute placement, use "to".  For placement
relative to the C<from> position, use "rto".

=item (arrowstyle | as) <arrow_style>

This specifies that the arrow be drawn in a particular predeclared numerical
style.  If you give this parameter, you should omit all the following ones.

=item ( nohead | head | backhead | heads ) - specify arrowhead placement

=item size <length>,<angle>,<backangle> - specify arrowhead geometry

=item ( filled | empty | nofilled ) - specify arrowhead fill

=item ( front | back ) - specify drawing order ( last | first )

=item linestyle <line_style> - specify a numeric linestyle

=item linetype <line_type> - specify numeric line type

=item linewidth <line_width> - multiplier on the width of the line

=back

=head3 object - place a shape on the graph

C<object>s are rectangles, ellipses, circles, or polygons that can be placed
arbitrarily on the plotting plane.

The arguments, all of which are optional but which must be given in the order listed, are:

=over 3

=item <object-type> <object-properties> - type name of the shape and its type-specific properties

The <object-type> is one of four words: "rectangle", "ellipse", "circle", or "polygon".

You can specify a rectangle with C<< from=>$pos1, [r]to=>$pos2 >>, with C<< center=>$pos1, size=>"$w,$h" >>,
or with C<< at=>$pos1,size=>"$w,$h" >>.

You can specify an ellipse with C<< at=>$pos, size=>"$w,$h" >> or C<< center=>$pos, size=>"$w,$h" >>, followed
by C<< angle=>$a >>.

You can specify a circle with C<< at=>$pos, >> or C<< center=>$pos, >>, followed
by C<< size=>$radius >> and (optionally) C<< arc=>"[$begin:$end]" >>.

You can specify a polygon with C<< from=>$pos1,to=>$pos2,to=>$pos3,...to=>$posn >> or with
C<< from=>$pos1,rto=>$diff1,rto=>$diff2,...rto=>$diffn >>.

=item ( front | back | behind ) - draw the object last | first | really-first.

=item fc <colorspec> - specify fill color

=item fs <fillstyle> - specify fill style

=item lw <width> - multiplier on line width

=back

=head2 POs for appearance tweaks - bars, boxwidth, isosamples, pointsize, style

B<C<bars>> sets the width and behavior of the tick marks at the ends of error bars.
It takes a list containing at most two elements, both of which are optional:

=over 3

=item * A width specifier, which should be a numeric size multiplier times the usual
width (which is about one character width in the default font size), or the word
C<fullwidth> to make the ticks the same width as their associated boxes in boxplots
and histograms.

=item * the word "front" or "back" to indicate drawing order in plots that might contain
filled rectangles (e.g. boxes, candlesticks, or histograms).

=back

If you pass in the undefined value you get no ticks on errorbars; if you pass in the
empty list ref you get default ticks.

B<C<boxwidth>> sets the width of drawn boxes in boxplots, candlesticks, and histograms.  It
takes a list containing at most two elements:

=over 3

=item * a numeric width

=item * one of the words C<absolute> or C<relative>.

=back

Unless you set C<relative>, the numeric width sets the width of boxes
in X-axis scientific units (on log scales, this is measured at x=1 and
the same width is used throughout the plot plane).  If C<relative> is
included, the numeric width is taken to be a multiplier on the default
width.

B<C<isosamples>> sets isoline density for plotting functions as
surfaces.  You supply one or two numbers.  The first is the number of
iso-u lines and the second is the number of iso-v lines.  If you only
specify one, then the two are taken to be the same.  From the gnuplot
manual: "An isoline is a curve parameterized by one of the surface
parameters while the other surface parameter is fixed.  Isolines
provide a simple means to display a surface.  By fixing the u
parameter of surface s(u,v), the iso-u lines of the form c(v) =
s(u0,v) are produced, and by fixing the v parameter, the iso-v lines
of the form c(u)=s(u,v0) are produced".

B<C<pointsize>> accepts a single number and scales the size of points used in plots.

B<C<style>> provides a great deal of customization for individual plot styles.
It is not (yet) fully parsed by PDL::Graphics::Gnuplot; please refer to the Gnuplot
manual for details (it is pp. 145ff in the Gnuplot 4.6.1 maual).  C<style> accepts
a hash ref whose keys are plot styles (such as you would feed to the C<with> curve option),
and whose values are list refs containing keywords and other parameters to modify how each
plot style should be displayed.

=head2 POs for locale/internationalization - locale, decimalsign

C<locale> is used to control date stamp creation.  See the gnuplot manual.

C<decimalsign>  accepts a character to use in lieu of a "." for the decimalsign.
(e.g. in European countries use C<< decimalsign=>',' >>).

C<globalwith> is used as a default plot style if no valid 'with' curve option is present for
a given curve.

If set to a nonzero value, C<timestamp> causes a time stamp to be
placed on the side of the plot, e.g. for keeping track of drafts.

C<zero> sets the approximation threshold for zero values within gnuplot.  Its default is 1e-8.

C<fontpath> sets a font search path for gnuplot.  It accepts a collection of file names as a list ref.

=head2 POs for advanced Gnuplot tweaks: topcmds, extracmds, bottomcmds, binary, dump, tee

Plotting is carried out by sending a collection of commands to an underlying
gnuplot process.  In general, the plot options cause "set" commands to be
sent, configuring gnuplot to make the plot; these are followed by a "plot" or
"splot" command and by any cleanup that is necessary to keep gnuplot in a known state.

Provisions exist for sending commands directly to Gnuplot as part of a plot.  You
can send commands at the top of the configuration but just under the initial
"set terminal" and "set output" commands (with the C<topcmds> option), at the bottom
of the configuration and just before the "plot" command (with the C<extracmds> option),
or after the plot command (with the C<bottomcmds> option).  Each of these plot
options takes a list ref, each element of which should be one command line for
gnuplot.

Most plotting is done with binary data transfer to Gnuplot; however, due to
some bugs in Gnuplot binary handling, certain types of plot data are sent in ASCII.
In particular, time series and label data require transmission in ASCII (as of Gnuplot 4.4).
You can force ASCII transmission of all but image data by explicitly setting the
C<< binary=>0 >> option.

C<dump> is used for debugging. If true, it writes out the gnuplot commands to
STDOUT I<instead> of writing to a gnuplot process. Useful to see what commands
would be sent to gnuplot. This is a dry run. Note that if the 'binary' option is
given (see below), then this dump will contain binary data. If this binary data
should be suppressed from the dump, set C<< dump => 'nobinary' >>.

C<tee> is used for debugging. If true, writes out the gnuplot commands to STDERR
I<in addition> to writing to a gnuplot process. This is I<not> a dry run: data
is sent to gnuplot I<and> to the log. Useful for debugging I/O issues. Note that
if the 'binary' option is given (see below), then this log will contain binary
data. If this binary data should be suppressed from the log, set C<< tee =>
'nobinary' >>.

=head1 CURVE OPTIONS

The curve options describe details of specific curves within a plot.
They are in a hash, whose keys are as follows:

=over 2

=item legend

Specifies the legend label for this curve

=item axes

Lets you specify which X and/or Y axes to plot on.  Gnuplot supports
a main and alternate X and Y axis.  You specify them as a packed string
with the x and y axes indicated: for example, C<x1y1> to plot on the main
axes, or C<x1y2> to plot using an alternate Y axis (normally gridded on
the right side of the plot).

=item with

Specifies the plot style for this curve. The value is passed to gnuplot
using its 'with' keyword, so valid values are whatever gnuplot
supports.  See above ("Plot styles supported") for a list of supported
curve styles.

The following curve options in this list modify the plot style further.
Not all of them are applicable to all plot styles -- for example, it makes
no sense to specify a fill style for C<< with=>lines >>.

For historical reasons, you can supply the with modifier curve options
as a single string in the "with" curve option.  That usage is deprecated
and will disappear in a future version of PDL::Graphics::Gnuplot.

=item linetype (abbrev 'lt')

This is a numeric selector from the default collection of line styles.
It includes automagic selection of dash style, color, and width from the
default set of linetypes for your current output terminal.

=item dashtype (abbrev 'dt')

This is can be either a numeric type selector (0 for no dashes) or
an ARRAY ref containing a list of up to 5 pairs of (dash length,
space length).  The C<dashtype> curve option is only supported for
Gnuplot versions 5.0 and above.

If you don't specify a C<dashtype> curve option, the default behavior
matches the behavior of earlier gnuplots: many terminals support a
"dashed" terminal/output option, and if you have set that option (with
the constructor or with the C<output> method) then lines are uniquely
dashed by default.  To make a single curve solid, specify C<dt=>0> as
a curve option for it; or to make all curves solid, use the constructor
or the C<output> method to set the terminal option C<dashed=>0>.

If your gnuplot is older than v5.0, the dashtype curve option is
ignored (and causes a warning to be emitted).

=item linestyle (abbrev 'ls')

This works exactly like C<< linetype >> above, except that you can modify
individual line styles by setting the C<< style line <num> >> plot option.
That is handy for a custom style you might use across several curves either
a single plot or several plots.

=item linewidth (abbrev 'lw')

This is a numeric multiplier on the usual default line width in your current
terminal.

=item linecolor (abbrev 'lc')

This is a color specifier for the color of the line.  See L</"Color specification">.
You can feed in a standard color name (they're listed in the
package-global variable C<@PDL::Graphics::Gnuplot::colornames>), a
small integer to index the standard linetype colors, the word
"variable" to indicate that the line color is a standard linetype
color to be drawn from an additional column of data, a string of the
form #RRGGBB, where the # is literal and the RR, GG, and BB are
hexadecimal bytes, the words "rgbcolor variable" to specify an
additional column of data containing 24-bit packed integers with RGB
color values, C<< [palette=>'frac',<val>] >> to specify a single
fractional position (scaled 0-1) in the current palette, or C<<
[palette=>'cb',<val>] >> to specify a single value in the scaled
cbrange.

There is no C<< linecolor=>[palette=>variable] >> due to Gnuplot's
non-orthogonal syntax.  To draw line color from the palette, via an
additional data column, see the separate "palette" curve option
(below).

=item textcolor (abbrev 'tc')

For plot styles like C<labels> that specify text, this sets the color
of the text.  It has the same format as C<linecolor> (above).

=item pointtype (abbrev 'pt')

Selects a point glyph shape from the built-in list for your terminal,
for plots that render points as small glyphs (like C<points> and
C<linespoints>).

=item pointsize (abbrev 'ps')

Selects a fractional size for point glyphs, relative to the default size
on your terminal, for plots that render points as small glyphs.

=item fillstyle (abbrev 'fs')

Specify the way that filled regions should be colored, in plots that
have fillable areas (like C<boxes>).  Unlike C<linestyle> above,
C<fillstyle> accepts a full specification rather than an index into a
set of predefined styles. You can feed in: C<< 'empty' >> for no fill;
C<< 'transparent solid <density>' >> for a solid fill with optional
<density> from 0.0 to 1.0 (default 1.0); C<< 'transparent pattern <n>'
>> for a pattern fill--plotting multiple datasets causes the pattern
to cycle through all available pattern types, starting from pattern
<n> (be aware that the default <n>=0 may be equivalent to 'empty');
The 'transparent' portions of the strings are optional, and are only
effective on terminals that support transparency. Be aware that the
quality of the visual output may depend on terminal type and rendering
software.

Any of those fill style specification strings can have a border
specification string appended to it.  To specify a border, append
C<'border'>, and then optionally either C<< 'lt=><type>' >> or C<<
'lc=><colorspec>' >> to the string.  To specify no border, append
C<'noborder'>.

=item nohidden3d

If you are making a 3D plot and have used the plot option C<hidden3d> to get
hidden line removal, you can override that for a particular curve by setting
the C<nohidden3d> option to a true value.  Only the single curve with C<nohidden3d>
set will have its hidden points rendered.

=item nocontours

If you are making a contour 3D plot, you can inhibit rendering of
contours for a particular curve by setting C<nocontours> to a true
value.

=item nosurface

If you are making a surface 3D plot, you can inhibit rendering of the
surface associated with a particular curve, by setting C<nosurface> to
a true value.

=item palette

Setting C<< palette => 1 >> causes line color to be drawn from an additional
column in the data tuple.  This column is always the very last column in the
tuple, in case of conflict (e.g. if you set both C<< pointsize=>variable >> and
C<< palette=>1 >>, then the palette column is the last column and the pointsize
column is second-to-last).

=item tuplesize

Specifies how many values represent each data point.  Normally you
don't need to set this as individual C<with> styles implicitly set a
tuple size (which is automatically extended if you specify additional
modifiers such as C<palette> that require more data); this option
lets you override PDL::Graphics::Gnuplot's parsing in case of irregularity.

=item cdims

Specifies the dimensions of of each column in this curve's tuple.  It must
be 0, 1, or 2.   Normally you don't need to set this for most plots; the
main use is to specify that a 2-D data PDL is to be interpreted as a collection
of 1-D columns rather than a single 2-D grid (which would be the default
in a 3-D plot). For example:

    $w=gpwin();
    $r2 = rvals(21,21)**2;
    $w->plot3d( wi=>'lines', xvals($r2), yvals($r2), $r2 );

will produce a grid of values on a paraboloid. To instead plot a collection
of lines using the threaded syntax, try

    $w->plot3d( wi=>'lines', cd=>1, xvals($r2), yvals($r2), $r2 );

which will plot 21 separate curves in a threaded manner.

=back

=head1 RECIPES

Most of these come directly from Gnuplot commands. See the Gnuplot docs for
details.

=head2 2D plotting

If we're plotting an ndarray $y of y-values to be plotted sequentially (implicit
domain), all you need is

  gplot($y);

If we also have a corresponding $x domain, we can plot $y vs. $x with

  gplot($x, $y);

=head3 Simple style control

To change line thickness:

  gplot(with => 'lines',linewidth=>4, $x, $y);
  gplot(with => 'lines', lw=>4, $x, $y);

To change point size and point type:

  gplot(with => 'points',pointtype=>8, $x, $y);
  gplot(with => 'points',pt=>8, $x, $y);

=head3 Errorbars

To plot errorbars that show $y +- 1, plotted with an implicit domain

  gplot(with => 'yerrorbars', $y, $y->ones);

Same with an explicit $x domain:

  gplot(with => 'yerrorbars', $x, $y, $y->ones);

Symmetric errorbars on both x and y. $x +- 1, $y +- 2:

  gplot(with => 'xyerrorbars', $x, $y, $x->ones, 2*$y->ones);

To plot asymmetric errorbars that show the range $y-1 to $y+2 (note that here
you must specify the actual errorbar-end positions, NOT just their deviations
from the center; this is how Gnuplot does it)

  gplot(with => 'yerrorbars', $y, $y - $y->ones, $y + 2*$y->ones);

=head3 More multi-value styles

Plotting with variable-size circles (size given in plot units, requires Gnuplot >= 4.4)

  gplot(with => 'circles', $x, $y, $radii);

Plotting with a variably-sized arbitrary point type (size given in multiples of
the "default" point size)

  gplot(with => 'points', pointtype=>7, pointsize=>'variable',
        $x, $y, $sizes);

Color-coded points

  gplot(with => 'points', palette=>1,
        $x, $y, $colors);

Variable-size AND color-coded circles. A Gnuplot (4.4.0) bug make it necessary to
specify the color range here

  gplot(cbmin => $mincolor, cbmax => $maxcolor,
        with => 'circles', palette=>1,
        $x, $y, $radii, $colors);

=head2 3D plotting

General style control works identically for 3D plots as in 2D plots.

To plot a set of 3d points, with a square aspect ratio (squareness requires
Gnuplot >= 4.4):

  splot(square => 1, $x, $y, $z);

If $xy is a 2D ndarray, we can plot it as a height map on an implicit domain

  splot($xy);

Complicated 3D plot with fancy styling:

  my $pi    = 3.14159;
  my $theta = zeros(200)->xlinvals(0, 6*$pi);
  my $z     = zeros(200)->xlinvals(0, 5);

  splot(title => 'double helix',

        { with => 'linespoints',
          pointsize=>'variable',
          pointtype=>7,
          palette=>1,
          legend => 'spiral 1' },
        { legend => 'spiral 2' },

        # 2 sets of x, 2 sets of y, single z
        PDL::cat( cos($theta), -cos($theta)),
        PDL::cat( sin($theta), -sin($theta)),
        $z,

        # pointsize, color
        0.5 + abs(cos($theta)), sin(2*$theta) );

3D plots can be plotted as a heat map.

  splot( extracmds => 'set view 0,0',
         with => 'image',
         $xy );

=head2 Hardcopies

To send any plot to a file, instead of to the screen, one can simply do

  gplot(hardcopy => 'output.pdf',
        $x, $y);

The C<hardcopy> option is a shorthand for the C<terminal> and
C<output> options. The output device is chosen from the file name
suffix.

If you want more (any) control over the output options (e.g. page
size, font, etc.) then you can specify the output device using the
C<output> method or the constructor itself -- or the corresponding plot
options in the non-object mode. For example, to generate a PDF of a
particular size with a particular font size for the text, one can do

  gplot(terminal => 'pdfcairo solid color font ",10" size 11in,8.5in',
        output   => 'output.pdf',
        $x, $y);

This command is equivalent to the C<hardcopy> shorthand used previously, but the
fonts and sizes can be changed.

Using the object oriented mode, you could instead say:

  $w = gpwin();
  $w->plot( $x, $y );
  $w->output( pdfcairo, solid=>1, color=>1,font=>',10',size=>[11,8.5,'in'] );
  $w->replot();
  $w->close();

Many hardcopy output terminals (such as C<pdf> and C<svg>) will not
dump their plot to the file unless the file is explicitly closed with a
change of output device or a call to C<reset>, C<restart>, or C<close>.
This is because those devices support multipage output and also require
and end-of-file marker to close the file.

=head1 Plotting examples

=head2 A simple example

   my $win = gpwin('x11');
   $win->plot( sin(xvals(45)) * 3.14159/10 );

Here we just plot a simple function.  The default plot style is a
line.  Line plots take a 2-tuple (X and Y values).  Since we have
supplied only one element, C<plot()> understands it to be the Y value
(abscissa) of the plot, and supplies value indices as X values -- so
we get a plot of just over 2 cycles of the sine wave over an X range
across X values from 0 to 44.

=head2 A not-so-simple example

   $win = gpwin('x11');
   $pi = 3.14159;
   $win->plot( {with => line}, xvals(10)**2, xvals(10),
               {with => circles}, 2 * xvals(50), 2 * sin(xvals(50) * $pi / 10), xvals(50)/20
    );

This plots sqrt(x) in an interesting way, and overplots some circles of varying size.
The line plot accepts a 2-tuple, and we supply both X and Y.  The circles plot accepts
a 3-tuple: X, Y, and R.

=head2 A complicated example:

   $pi    = 3.14159;
   $theta = xvals(201) * 6 * $pi / 200;
   $z     = xvals(201) * 5 / 200;

   gplot( {trid => 1, title => 'double helix',cbr=>[0,1]},
         {with => 'linespoints',
          pointsize=>'variable',
          pointtype=>2,
          palette=>1,
          legend => ['spiral 1','spiral 2'],
          cdim=>1},
         pdl( cos($theta), -cos($theta) ),       # x
         pdl( sin($theta), -sin($theta) ),       # y
         $z,                                     # z
         (0.5 + abs(cos($theta))),               # pointsize
         sin($theta/3),                          # color
         { with=>'points',
           pointsize=>'variable',
           pointtype=>5,
           palette=>0
         },
         zeroes(6),                         # x
         zeroes(6),                         # y
         xvals(6),                          # z
         xvals(6)+1                         # point size
   );

This is a 3d plot with variable size and color. There are 5 values in
the tuple.  The first 2 ndarrays have dimensions (N,2); all the other
ndarrays have a single dimension. The "cdim=>1" specifies that each column
of data should be one-dimensional. Thus the PDL threading generates 2
distinct curves, with varying values for x,y and identical values for
everything else.  To label the curves differently, 2 different sets of
curve options are given.  Omitting the "cdim" curve option would yield
a 201x2 grid with the "linespoints" plotstyle, rather than two separate
curves.

In addition to the threaded pair of linespoints curves, there are six
variable size points plotted as filled squares, as a secondary curve.

Plot options are passed in in two places:  as a leading hash ref, and as
a trailing hash ref.  Any other hash elements or hash refs must be curve
options.

Curves are delimited by non-data arguments.  After the initial hash
ref, curve options for the first curve (the threaded pair of spirals)
are passed in as a second hash ref.  The curve's data arguments are
ended by the first non-data argument (the hash ref with the curve
options for the second curve).


=head1 FUNCTIONS

=cut
=pod

=head2 gpwin

=for usage

 use PDL::Graphics::Gnuplot;
 $w = gpwin( @options );
 $w->plot( @plot_args );


=for ref

gpwin is the PDL::Graphics::Gnuplot exported constructor.  It is
exported by default and is a synonym for "new
PDL::Graphics::Gnuplot(...)".  If given no arguments, it creates a
plot object with the default terminal settings for your gnuplot.  You
can also give it the name of a Gnuplot terminal type (e.g. 'x11') and
some terminal and output options (see "output").


=cut
=pod

=head2 new

=for usage

    $w = new PDL::Graphics::Gnuplot;
    $w->plot( @plot_args );
    #
    # Specify plot options alone
    $w = new PDL::Graphics::Gnuplot( {%plot_options} );
    #
    # Specify device and device options (and optional default plot options)
    $w = new PDL::Graphics::Gnuplot( device, %device_options, {%plot_options} );
    $w->plot( @plot_args );

=for ref

Creates a PDL::Graphics::Gnuplot persistent plot object, and connects it to gnuplot.

For convenience, you can specify the output device and its options
right here in the constructor.  Because different gnuplot devices
accept different options, you must specify a device if you want to
specify any device configuration options (such as window size, output
file, text mode, or default font).

If you don't specify a device type, then the Gnuplot default device
for your system gets used.  You can set that with an environment
variable (check the Gnuplot documentation).

Gnuplot uses the word "terminal" for output devices; you can see a
list of terminals supported by PDL::Graphics::Gnuplot by invoking
C<PDL::Graphics::Gnuplot::terminfo()> (for example in the perldl shell).

For convenience, you can provide default plot options here.  If the last
argument to C<new()> is a trailing hash ref, it is treated as plot options.

After you have created an object, you can change its terminal/output
device with the C<output> method, which is useful for (e.g.) throwing
up an interactive plot and then sending it to a hardcopy device. See
C<output> for a description of terminal options and how to format
them.

Normally, the object connects to the command "gnuplot" in your path,
using the C<Alien::Gnuplot> module.  If you need to specify a binary
other than this default, check the C<Alien::Gnuplot> documentation.

=for example

  my $plot = PDL::Graphics::Gnuplot->new({title => 'Object-oriented plot'});
  $plot->plot( legend => 'curve', sequence(5) );


=cut
=pod

=head2 output

=for usage

    $window->output( $device );
    $window->output( $device, %device_options );
    $window->output( $device, %device_options, {plot_options} );
    $window->output( %device_options, {plot_options} );
    $window->output( %device_options );

=for ref

Sets the output device and options for a Gnuplot object. If you omit
the C<$device> name, then you get the gnuplot default device (generally
C<x11>, C<wxt>, or C<aqua>, depending on platform).

You can control the output device of a PDL::Graphics::Gnuplot object on
the fly.  That is useful, for example, to replot several versions of the
same plot to different output devices (interactive and hardcopy).

Gnuplot interprets terminal options differently per device.
PDL::Graphics::Gnuplot attempts to interpret some of the more common
ones in a common way.  In particular:

=over 3

=item size

Most drivers support a "size" option to specify the size of the output
plotting surface.  The format is [$width, $height, $unit]; the
trailing unit string is optional but recommended, since the default
unit of length changes from device to device.

The unit string can be in, cm, mm, px, char, or pt.  Pixels are taken
to be 1 point in size (72 pixels per inch) and dimensions are computed
accordingly.  Characters are taken to be 12 point in size (6 per
inch).

=item output

This option actually sets the object's "output" option for most terminal
devices; that changes the file to which the plot will be written.  Some
devices, notably X11 and Aqua, don't make proper use of "output"; for those
devices, specifying "output" in the object constructor actually sets the
appropriate terminal option (e.g. "window" in the X11 terminal).
This is described as a "plot option" in the Gnuplot manual, but it is
treated as a setup variable and parsed with the setup/terminal options here
in the constructor.

If you don't specify an output device, plots will go to sequentially-numbered
files of the form C<Plot-E<lt>nE<gt>.E<lt>sufE<gt>> in your current working
directory.  In that case, PDL::Graphics::Gnuplot will report (on STDERR)
where the plot ended up.

=item enhanced

This is a flag that indicates whether to enable Gnuplot's enhanced text
processing (e.g. for superscripts and subscripts).  Set it to a false
value for plain text, to a true value for enhanced text (which includes
LaTeX-like markup for super/sub scripts and fonts).

=item aa

For certain pixel-grid terminals (currently only C<pncairo> and
C<png>, as of v2.012), you can specify an antialiasing factor for the
output.  The output is rendered oversized by a factor of C<aa>, then
scaled down using C<PDL::Transform>.  Fixed font sized, line widths,
and point sizes are autoscaled -- but you must handle variable ones
explicitly.

Antialiasing is done in the gamma=2.2 approximation, to match the sRGB
coding that most pixel image files use.  (See PDL::Transform::Color
for more information).

=back

For a brief description of the terminal options that any one device supports,
you can run PDL::Graphics::Gnuplot::terminfo().

As with plot options, terminal options can be abbreviated to the shortest
unique string -- so (e.g.) "size" can generally be abbreviated "si" and
"monochrome" can be abbreviated "mono" or "mo".

=cut
=pod

=head2 close

=for usage

  $w=gpwin();
  $w->plot(xvals(5));
  $w->close;

=for ref

Close gnuplot process (actually just a synonym for restart)

Some of the gnuplot terminals (e.g. pdf) don't write out a file
promptly.  The close method closes the associated gnuplot subprocess,
forcing the file to be written out.  It is implemented as a simple
restart operation.

The object preserves the plot state, so C<replot> and similar methods
still work with the new subprocess.

=cut
=pod

=head2 restart

=for usage

    $w->restart();
    PDL::Graphics::Gnuplot::restart();

=for ref

Restart the gnuplot backend for a plot object

Occasionally the gnuplot backend can get into an unknown state.
C<restart> kills the gnuplot backend and starts a new one, preserving
state in the object.  (i.e. C<replot> and similar functions work even
with the new subprocess).

Called with no arguments, C<restart> applies to the global plot object.

=cut
=pod

=head2 reset

=for usage

    $w->reset()

=for ref

Clear state from the gnuplot backend

Clears all plot option state from the underlying object.  All plot
options except "terminal", "termoptions", "output", and "multiplot"
are cleared.  This is similar to the "reset" command supported by
gnuplot itself, and in fact it also causes a "reset" to be sent to
gnuplot.


=cut
=pod

=head2 options

=for usage

  $w = new PDL::Graphics::Gnuplot();
  $w->options( globalwith=>'lines' );
  print %{$w->options()};

=for ref

Set/get persistent plot options for a plot object

The options method parses plot options into a gnuplot object on a
cumulative basis, and returns the resultant options hash.

If called as a sub rather than a method, options() changes the
global gnuplot object.

=cut
=pod

=head2 gplot

=for ref

Plot method exported by default (synonym for "PDL::Graphics::Gnuplot::plot")

=head2 plot

=for ref

This is the main plotting routine in PDL::Graphics::Gnuplot.

Each C<plot()> call creates a new plot from whole cloth, either creating
or overwriting the output for that device.

If you want to add features to an existing plot, use C<replot>.

C<plot()> understands the PDL bad value mechanism.  Bad values are omitted
from the plot.

=for usage

 $w=gpwin();
 $w->plot({temp_plot_options},                 # optional
      curve_options, data, data, ... ,      # curve_options are optional for the first plot
      curve_options, data, data, ... ,
       {temp_plot_options});

Most of the arguments are optional.

All of the extensive array of gnuplot plot styles are supported, including images and 3-D plots.

=for example

 use PDL::Graphics::Gnuplot qw(plot);
 my $x = sequence(101) - 50;
 plot($x**2);

See main POD for PDL::Graphics::Gnuplot for details.

You can pass plot options into plot as either a leading or trailing hash ref, or both.
If you pass both, the trailing hash ref is parsed last and overrides the leading hash.

For debugging and curiosity purposes, the last plot command issued to gnuplot
is maintained in a package global: C<$PDL::Graphics::Gnuplot::last_plotcmd>, and also
in each object as the {last_plotcmd} field.

=cut
=pod

=head2 replot

=for ref

Replot the last plot (possibly with new arguments).

C<replot> is similar to gnuplot's "replot" command - it allows you to
regenerate the last plot made with this object.  You can change the
plot by adding new elements to it, modifying options, or even (with the
"device" method) changing the output device.  C<replot> takes the same
arguments as C<plot>.

If you give no arguments at all (or only a plot object) then the plot
is simply redrawn.  If you give plot arguments, they are added to the
new plot exactly as if you'd included them in the original plot
element list, and maintained for subsequent replots.

(Compare to 'markup').

=cut
=pod

=head2 markup

=for ref

Add ephemeral markup to the last plot.

C<markup> works exactly the same as C<replot>, except that any
new arguments are not added to the replot list - so you can
add temporary markup to a plot and regenerate the plot later
without it.

=cut
=pod

=head2 plot3d

=for ref

Generate 3D plots. Synonym for C<plot(trid =E<gt> 1, ...)>

=cut
=pod

=head2 splot

=for ref

Generate 3D plots.  Synonym for C<plot(trid =E<gt> 1, ...)>

=cut
=pod

=head2 lines

=for ref

Generates plots with lines, by default. Shorthand for C<plot(globalwith =E<gt> 'lines', ...)>

=cut
=pod

=head2 points

=for ref

Generates plots with points, by default. Shorthand for C<plot(globalwith =E<gt> 'points', ...)>

=cut
=pod

=head2 image

=for ref

Displays an image (either greyscale or RGB).  Shorthand for C<plot(globalwith =E<gt> 'image', ...)>

=cut
=pod

=head2 imag

=for ref

Synonym for "image", for people who grew up with PDL::Graphics::PGPLOT and can't remember the closing 'e'

=cut
=pod

=head2 fits

=for ref

Displays a FITS image.  Synonym for C<plot(globalwith =E<gt> 'fits', ...)>.

=cut
=pod

=head2 multiplot

=for example

 $a = (xvals(101)/100) * 6 * 3.14159/180;
 $b = sin($a);

 $w->multiplot(layout=>[2,2,"columnsfirst"]);
 $w->plot({title=>"points"},with=>"points",$a,$b);
 $w->plot({title=>"lines"}, with=>"lines", $a,$b);
 $w->plot({title=>"image"}, with=>"image", $a->(*1) * $b );
 $w->end_multi();

=for ref

Plot multiple plots into a single page of output.

The C<multiplot> method enables multiplot mode in gnuplot, which permits
multiple plots on a single pane.  Plots can be lain out in a grid,
or can be lain out freeform using the C<size> and C<origin> plot
options for each of the individual plots.

It is not possible to change the terminal or output device when in
multiplot mode; if you try to do that, by setting one of those plot
options, PDL::Graphics::Gnuplot will throw an error.

The options hash will accept:

=over 3

=item layout - define a regular grid of plots to multiplot

C<layout> should be followed by an ARRAY ref that contains at least
number of columns ("NX") followed by number of rows ("NY).  After
that, you may include any of the "rowsfirst", "columnsfirst",
"downwards", or "upwards" keywords to specify traversal order through
the grid.  Only the first letter is examined, so (e.g.) "down" or even
"dog" works the same as "downwards".

=item title - define a title for the entire page

C<title> should be followed by a single scalar containing the title string.

=item scale - make gridded plots larger or smaller than their allocated space

C<scale> takes either a scalar or a list ref containing one or two
values.  If only one value is supplied, it is a general scale factor
of each plot in the grid.  If two values are supplied, the first is an
X stretch factor for each plot in the grid, and the second is a Y
stretch factor for each plot in the grid.

=item offset - offset each plot from its grid origin

C<offset> takes a list ref containing two values, that control placement
of each plot within the grid.

=back

=head2 end_multi

=for usage

 $w=gpwin();
 $w->multiplot(layout=>[2,1]);
 $w->plot({title=>"points},with=>'points',$a,$b);
 $w->plot({title=>"lines",with=>"lines",$a,$b);
 $w->end_multi();

=for ref

Ends a multiplot block (i.e. a block of plots that are meant to render to a single page).

=cut
=pod

=head2 read_mouse

=for usage

  ($x,$y,$char,$modstring) = $w->read_mouse($message);
  $hash = $w->read_mouse($message);

=for ref

Get a mouse click or keystroke from the active interactive plot window.

For interactive devices (e.g. x11, wxt, aqua), read_mouse lets you accept a
keystroke or mouse button input from the gnuplot window.  In list context, it
returns four arguments containing the reported X, Y, keystroke character, and
modifiers packed in a string.  In scalar context, it returns a hash ref containing
those things.

read_mouse blocks execution for input, but responds gracefully to interrupts.

=cut
=pod

=head2 read_polygon

=for usage

  $points = $w->read_polygon(%opt)

=for ref

Read in a polygon by accepting mouse clicks.  The polygon is returned as a 2xN PDL of ($x,$y) values in scientific units. Acceptable options are:

=over 3

=item message - what to print before collecting points

There are some printf-style escapes for the prompt:


* C<%c> - expands to "an open" or "a closed"

* C<%n> - number of points currently in the polygon

* C<%N> - number of points expected for the polygon

* C<%k> - list of all keys accepted

* C<%%> - %

=item prompt  - what to print to prompt the user for the next point

C<prompt> uses the same escapes as C<message>.

=item n_points - number of points to accept (or 0 for indefinite)

With 0 value, points are accepted until the user presses 'q' or 'ESC' on the keyboard with focus
on the graph.  With other value, points are accepted until that happens *or* until the number
of points is at least n_points.

=item actions - hash of callback code refs indexed by character for action

You can optionally call a callback routine when any particular
character is pressed.  The actions table is a hash ref whose keys are
characters and whose values are either code refs (to be called on the
associated keypress) or array refs containing a short description
string followed by a code ref.  Non-printable characters (e.g. ESC,
BS, DEL) are accessed via a hash followed by a three digit decimal
ASCII code -- e.g. "#127" for DEL. Button events are indexed with the
strings "BUTTON1", "BUTTON2", and "BUTTON3", and modifications must be
entered as well for shift, control, and

The code ref receives the arguments ($obj, $c, $poly,$x,$y,$mods), where:

=over 2

=item C<$obj> is the plot object

=item C<$c> is the character (or "BUTTONC<n>" string),

=item C<$poly> is a scalar ref; $$poly is the current polygon before the action,

=item C<$x> and C<$y> are the current scientific coordinates, and

=item C<$mods> is the modifier string.

You can't override the 'q' or '#027' (ESC) callbacks.  You *can* override
the BUTTON1 and DEL callbacks, potentially preventing the user from entering points
at all!  You should do that with caution.

=item closed - (default false): generate a closed polygon

This works by duplicating the initial point at the end of the point list.

=item markup - (default 'linespoints'): style to use to render the polygon on the fly

If this is set to a true value, it should be a valid 'with' specifier (curve option).
The routine will call markup after each click.

=back

=back

=cut
=pod

=head2 pause_until_close

=for usage

  $w->pause_until_close;

=for ref

Wait until the active interactive plot window is closed (e.g., by clicking the
close button, hitting the close key-binding which defaults to C<q>).

C<pause_until_close> blocks execution until the close event.

=cut
=pod

=head2 terminfo

=for usage

    use PDL::Graphics::Gnuplot qw/terminfo/;
    terminfo();        # print info about all known terminals
    terminfo 'aqua';   # print info about the aqua terminal

    $w = gpwin();
    $w->terminfo();

=for ref

Print out information about gnuplot terminals and their custom option syntax.

The "terminfo" routine is a reference tool to describe the Gnuplot
terminal types and the options they accept.  It's mainly useful in
interactive sessions.  It outputs information directly to the terminal.

=cut
=head1 COMPATIBILITY

Everything should work on all platforms that support Gnuplot and Perl.
Currently, MacOS, Fedora and Debian Linux, Cygwin, and Microsoft
Windows (under both Active State Strawberry Perl) have been tested to
work, although the interprocess control link is not as reliable under
Microsoft Windows as under POSIX systems.  Please report successes or
failures on other platforms to the authors. A transcript of a failed
run with {tee => 1} would be most helpful.

=head1 REPOSITORY

L<https://github.com/drzowie/PDL-Graphics-Gnuplot>

=head1 AUTHOR

Craig DeForest, C<< <craig@deforest.org> >> and Dima Kogan, C<< <dima@secretsauce.net> >>

=head1 STILL TO DO

=over 3

=item some plot and curve options need better parsing:

=over 3

=item - labels need attention (plot option labels)

They need to be handled as hashes, not just as array refs.  Also, they don't seem to be working with timestamps.
Further, deeply nested options (e.g. "at" for labels) need attention.

=back

=item - new plot styles

The "boxplot" plot style (new to gnuplot 4.6?) requires a different using
syntax and will require some hacking to support.

=back

=head1 LICENSE AND COPYRIGHT

Copyright 2011-2013 Craig DeForest and Dima Kogan

This program is free software; you can redistribute it and/or modify it
under the terms of either: the GNU General Public License as published
by the Free Software Foundation; or the Perl Artistic License included with
the Perl language.

See http://dev.perl.org/licenses/ for more information.

=cut