1This is plplotdoc.info, produced by makeinfo version 6.5 from 2plplotdoc.texi. 3 4INFO-DIR-SECTION Scientific Visualization 5START-INFO-DIR-ENTRY 6* Documentation of the PLplot plotting software: (plplotdoc). 7 This reference contains 8 complete user documentation 9 for the PLplot plotting 10 software 11END-INFO-DIR-ENTRY 12 13 14File: plplotdoc.info, Node: Building an Extended WISH, Next: Embedding Plots in Graphical User Interfaces, Prev: Using PLplot from Tcl, Up: Supported computer languages 15 1614 Building an Extended WISH 17**************************** 18 19Beginning with PLplot 5.0, a new and powerful paradigm for interaction 20with PLplot is introduced. This new paradigm consists of an integration 21of PLplot with a powerful scripting language (Tcl), and extensions to 22that language to support X Windows interface development (Tk) and object 23oriented programming ([incr Tcl]). Taken together, these four software 24systems (Tcl/Tk/itcl/PLplot) comprise a powerful environment for the 25rapid prototyping and development of sophisticated, flexible, X Windows 26applications with access to the PLplot API. Yet that is only the 27beginning—Tcl was born to be extended. The true power of this paradigm 28is achieved when you add your own, powerful, application specific 29extensions to the above quartet, thus creating an environment for the 30development of wholly new applications with only a few keystrokes of 31shell programming ... 32 33* Menu: 34 35* Introduction to Tcl:: 36* Introduction to Tk:: 37* Introduction to [incr Tcl]:: 38* PLplot Extensions to Tcl:: 39* Custom Extensions to Tcl:: 40 41 42File: plplotdoc.info, Node: Introduction to Tcl, Next: Introduction to Tk, Up: Building an Extended WISH 43 4414.1 Introduction to Tcl 45======================== 46 47The Tool Command Language, or just Tcl (pronounced ‘tickle’) is an 48embeddable script language which can be used to control a wide variety 49of applications. Designed by John Ousterhout of UC Berkeley, Tcl is 50freely available under the standard Berkeley copyright. Tcl and Tk 51(described below) are extensively documented in a new book published by 52Addison Wesley, entitled ‘Tcl and the Tk toolkit’ by John Ousterhout. 53This book is a must have for those interested in developing powerful 54extensible applications with high quality X Windows user interfaces. 55The discussion in this chapter cannot hope to approach the level of 56introduction provided by that book. Rather we will concentrate on 57trying to convey some of the excitement, and show the nuts and bolts of 58using Tcl and some extensions to provide a powerful and flexible 59interface to the PLplot library within your application. 60 61* Menu: 62 63* Motivation for Tcl:: 64* Capabilities of Tcl:: 65* Acquiring Tcl:: 66 67 68File: plplotdoc.info, Node: Motivation for Tcl, Next: Capabilities of Tcl, Up: Introduction to Tcl 69 7014.1.1 Motivation for Tcl 71------------------------- 72 73The central observation which led Ousterhout to create Tcl was the 74realization that many applications require the use of some sort of a 75special purpose, application specific, embedded ‘macro language’. 76Application programmers cobble these ‘tiny languages’ into their codes 77in order to provide flexibility and some modicum of high level control. 78But the end result is frequently a quirky and fragile language. And 79each application has a different ‘tiny language’ associated with it. 80The idea behind Tcl, then, was to create a single ‘core language’ which 81could be easily embedded into a wide variety of applications. Further, 82it should be easily extensible so that individual applications can 83easily provide application specific capabilities available in the macro 84language itself, while still providing a robust, uniform syntax across a 85variety of applications. To say that Tcl satisfies these requirements 86would be a spectacular understatement. 87 88 89File: plplotdoc.info, Node: Capabilities of Tcl, Next: Acquiring Tcl, Prev: Motivation for Tcl, Up: Introduction to Tcl 90 9114.1.2 Capabilities of Tcl 92-------------------------- 93 94The mechanics of using Tcl are very straightforward. Basically you just 95have to include the file ‘tcl.h’, issue some API calls to create a Tcl 96interpreter, and then evaluate a script file or perform other operations 97supported by the Tcl API. Then just link against ‘libtcl.a’ and off you 98go. 99 100 Having done this, you have essentially created a shell. That is, 101your program can now execute shell scripts in the Tcl language. Tcl 102provides support for basic control flow, variable substitution file i/o 103and subroutines. In addition to the built in Tcl commands, you can 104define your own subroutines as Tcl procedures which effectively become 105new keywords. 106 107 But the real power of this approach is to add new commands to the 108interpreter which are realized by compiled C code in your application. 109Tcl provides a straightforward API call which allows you to register a 110function in your code to be called whenever the interpreter comes across 111a specific keyword of your choosing in the shell scripts it executes. 112 113 This facility allows you with tremendous ease, to endow your 114application with a powerful, robust and full featured macro language, 115trivially extend that macro language with new keywords which trigger 116execution of compiled application specific commands, and thereby raise 117the level of interaction with your code to one of essentially shell 118programming via script editing. 119 120 121File: plplotdoc.info, Node: Acquiring Tcl, Prev: Capabilities of Tcl, Up: Introduction to Tcl 122 12314.1.3 Acquiring Tcl 124-------------------- 125 126There are several important sources of info and code for Tcl. 127Definitely get the book mentioned above, and the source code for the Tcl 128and Tk toolkits can be downloaded from The Tcl developer Xchange 129(http://www.tcl.tk/software/tcltk/download.html). 130 131 Additionally there is a newsgroup, ‘comp.lang.tcl’ which is well 132read, and an excellent place for people to get oriented, find help, etc. 133Highly recommended. 134 135 In any event, in order to use the Tk driver in PLplot, you will need 136Tcl-8.2 and Tk-8.2 (or higher versions). Additionally, in order to use 137the extended WISH paradigm (described below) you will need iTcl-3.1 (or 138a higher version). 139 140 However, you will quite likely find Tcl/Tk to be very addictive, and 141the great plethora of add-ons available at ‘harbor’ will undoubtedly 142attract no small amount of your attention. It has been our experience 143that all of these extensions fit together very well. You will find that 144there are large sectors of the Tcl user community which create so-called 145‘MegaWishes’ which combine many of the available extensions into a 146single, heavily embellished, shell interpreter. The benefits of this 147approach will become apparent as you gain experience with Tcl and Tk. 148 149 150File: plplotdoc.info, Node: Introduction to Tk, Next: Introduction to [incr Tcl], Prev: Introduction to Tcl, Up: Building an Extended WISH 151 15214.2 Introduction to Tk 153======================= 154 155As mentioned above, Tcl is designed to be extensible. The first and 156most basic Tcl extension is Tk, an X11 toolkit. Tk provides the same 157basic facilities that you may be familiar with from other X11 toolkits 158such as Athena and Motif, except that they are provided in the context 159of the Tcl language. There are C bindings too, but these are seldom 160needed—the vast majority of useful Tk applications can be coded using 161Tcl scripts. 162 163 If it has not become obvious already, it is worth noting at this 164point that Tcl is one example of a family of languages known generally 165as ‘Very High Level Languages’, or VHLL’s. Essentially a VHLL raises 166the level of programming to a very high level, allowing very short token 167streams to accomplish as much as would be required by many scores of the 168more primitive actions available in a basic HLL. Consider, for example, 169the basic ‘Hello World!’ application written in Tcl/Tk. 170 171 172 #!/usr/local/bin/wish -f 173 174 button .hello -text "Hello World!" -command "destroy ." 175 pack .hello 176 177 That’s it! That’s all there is to it. If you have ever programmed X 178using a traditional toolkit such as Athena or Motif, you can appreciate 179how amazingly much more convenient this is. If not, you can either take 180our word for it that this is 20 times less code than you would need to 181use a standard toolkit, or you can go write the same program in one of 182the usual toolkits and see for yourself... 183 184 We cannot hope to provide a thorough introduction to Tk programming 185in this section. Instead, we will just say that immensely complex 186applications can be constructed merely by programming in exactly the way 187shown in the above script. By writing more complex scripts, and by 188utilizing the additional widgets provided by Tk, one can create 189beautiful, extensive user interfaces. Moreover, this can be done in a 190tiny fraction of the time it takes to do the same work in a conventional 191toolkit. Literally minutes versus days. 192 193 Tk provides widgets for labels, buttons, radio buttons, frames with 194or without borders, menubars, pull downs, toplevels, canvases, edit 195boxes, scroll bars, etc. 196 197 A look at the interface provided by the PLplot Tk driver should help 198give you a better idea of what you can do with this paradigm. Also 199check out some of the contributed Tcl/Tk packages available at harbor. 200There are high quality Tk interfaces to a great many familiar Unix 201utilities ranging from mail to info, to SQL, to news, etc. The list is 202endless and growing fast... 203 204 205File: plplotdoc.info, Node: Introduction to [incr Tcl], Next: PLplot Extensions to Tcl, Prev: Introduction to Tk, Up: Building an Extended WISH 206 20714.3 Introduction to [incr Tcl] 208=============================== 209 210Another extremely powerful and popular extension to Tcl is [incr Tcl]. 211[incr Tcl] is to Tcl what C++ is to C. The analogy is very extensive. 212Itcl provides an object oriented extension to Tcl supporting clustering 213of procedures and data into what is called an ‘itcl_class’. An 214‘itcl_class’ can have methods as well as instance data. And they 215support inheritance. Essentially if you know how C++ relates to C, and 216if you know Tcl, then you understand the programming model provided by 217Itcl. 218 219 In particular, you can use Itcl to implement new widgets which are 220composed of more basic Tk widgets. A file selector is an example. 221Using Tk, one can build up a very nice file selector comprised of more 222basic Tk widgets such as entries, listboxes, scrollbars, etc. 223 224 But what if you need two file selectors? You have to do it all 225again. Or what if you need two different kinds of file selectors, you 226get to do it again and add some incremental code. 227 228 This is exactly the sort of thing object orientation is intended to 229assist. Using Itcl you can create an ‘itcl_class FileSelector’ and then 230you can instantiate them freely as easily as: 231 232 233 FileSelector .fs1 234 .fs1 -dir . -find "*.cc" 235 236 and so forth. 237 238 These high level widgets composed of smaller Tk widgets, are known as 239‘megawidgets’. There is a developing subculture of the Tcl/Tk community 240for designing and implementing megawidgets, and [incr Tcl] is the most 241popular enabling technology. 242 243 In particular, it is the enabling technology which is employed for 244the construction of the PLplot Tcl extensions, described below. 245 246 247File: plplotdoc.info, Node: PLplot Extensions to Tcl, Next: Custom Extensions to Tcl, Prev: Introduction to [incr Tcl], Up: Building an Extended WISH 248 24914.4 PLplot Extensions to Tcl 250============================= 251 252Following the paradigm described above, PLplot provides extensions to 253Tcl as well, designed to allow the use of PLplot from Tcl/Tk programs. 254Essentially the idea here is to allow PLplot programmers to achieve two 255goals: 256 257 • To access PLplot facilities from their own extended WISH and/or 258 Tcl/Tk user interface scripts. 259 260 • To have PLplot display its output in a window integrated directly 261 into the rest of their Tcl/Tk interface. 262 263 For instance, prior to PLplot 5.0, if a programmer wanted to use 264PLplot in a Tcl/Tk application, the best he could manage was to call the 265PLplot C API from compiled C code, and get the output via the Xwin 266driver, which would display in it’s own toplevel window. In other 267words, there was no integration, and the result was pretty sloppy. 268 269 With PLplot 5.0, there is now a supported Tcl interface to PLplot 270functionality. This is provided through a ‘family’ of PLplot 271megawidgets implemented in [incr Tcl]. Using this interface, a 272programmer can get a PLplot window/widget into a Tk interface as easily 273as: 274 275 276 PLWin .plw 277 pack .plw 278 279 Actually, there’s the update/init business—need to clear that up. 280 281 The ‘PLWin’ class then mirrors much of the PLplot C API, so that a 282user can generate plots in the PLplot widget entirely from Tcl. This is 283demonstrated in the ‘tk02’ demo, 284 285 286File: plplotdoc.info, Node: Custom Extensions to Tcl, Prev: PLplot Extensions to Tcl, Up: Building an Extended WISH 287 28814.5 Custom Extensions to Tcl 289============================= 290 291By this point, you should have a pretty decent understanding of the 292underlying philosophy of Tcl and Tk, and the whole concept of 293extensions, of which [incr Tcl] and PLplot are examples. These alone 294are enough to allow the rapid prototyping and development of powerful, 295flexible graphical applications. Normally the programmer simply writes 296a shell script to be executed by the Tk windowing shell, ‘wish’. It is 297in vogue for each Tcl/Tk extension package to build it’s own ‘extended 298WISH’. There are many examples of this, and indeed even PLplot’s 299‘plserver’ program, described in an earlier chapter, could just as 300easily have been called ‘plwish’. 301 302 In any event, as exciting and useful as these standalone, extended 303windowing shells may be, they are ultimately only the beginning of what 304you can do. The real benefit of this approach is realized when you make 305your own ‘extended WISH’, comprised of Tcl, Tk, any of the standard 306extensions you like, and finally embellished with a smattering of 307application specific extensions designed to support your own application 308domain. In this section we give a detailed introduction to the process 309of constructing your own WISH. After that, you’re on your own... 310 311* Menu: 312 313* WISH Construction:: 314* WISH Linking:: 315* WISH Programming:: 316 317 318File: plplotdoc.info, Node: WISH Construction, Next: WISH Linking, Up: Custom Extensions to Tcl 319 32014.5.1 WISH Construction 321------------------------ 322 323The standard way to make your own WISH, as supported by the Tcl/Tk 324system, is to take a boilerplate file, ‘tkAppInit.c’, edit to reflect 325the Tcl/Tk extensions you will be requiring, add some commands to the 326interpreter, and link it all together. 327 328 Here for example is the important part of the ‘tk02’ demo, extracted 329from the file ‘xtk02.c’, which is effectively the extended WISH 330definition file for the ‘tk02’ demo. Comments and other miscellany are 331omitted. 332 333 334 #include "tk.h" 335 #include "itcl.h" 336 337 /* ... */ 338 339 int myplotCmd (ClientData, Tcl_Interp *, int, char **); 340 341 int 342 Tcl_AppInit(interp) 343 Tcl_Interp *interp; /* Interpreter for application. */ 344 { 345 int plFrameCmd (ClientData, Tcl_Interp *, int, char **); 346 347 Tk_Window main; 348 349 main = Tk_MainWindow(interp); 350 351 /* 352 * Call the init procedures for included packages. Each call should 353 * look like this: 354 * 355 * if (Mod_Init(interp) == TCL_ERROR) { 356 * return TCL_ERROR; 357 * } 358 * 359 * where "Mod" is the name of the module. 360 */ 361 362 if (Tcl_Init(interp) == TCL_ERROR) { 363 return TCL_ERROR; 364 } 365 if (Tk_Init(interp) == TCL_ERROR) { 366 return TCL_ERROR; 367 } 368 if (Itcl_Init(interp) == TCL_ERROR) { 369 return TCL_ERROR; 370 } 371 if (Pltk_Init(interp) == TCL_ERROR) { 372 return TCL_ERROR; 373 } 374 375 /* 376 * Call Tcl_CreateCommand for application-specific commands, if 377 * they weren't already created by the init procedures called above. 378 */ 379 380 Tcl_CreateCommand(interp, "myplot", myplotCmd, 381 (ClientData) main, (void (*)(ClientData)) NULL); 382 383 384 /* 385 * Specify a user-specific start up file to invoke if the 386 * application is run interactively. Typically the start up 387 * file is "~/.apprc" where "app" is the name of the application. 388 * If this line is deleted then no user-specific start up file 389 * will be run under any conditions. 390 */ 391 392 tcl_RcFileName = "~/.wishrc"; 393 return TCL_OK; 394 } 395 396 /* ... myPlotCmd, etc ... */ 397 398 The calls to ‘Tcl_Init()’ and ‘Tk_Init()’ are in every WISH. To make 399an extended WISH, you add calls to the initialization routines for any 400extension packages you want to use, in this [incr Tcl] (‘Itcl_Init()’) 401and PLplot (‘Pltk_Init()’). Finally you add keywords to the 402interpreter, associating them with functions in your code using 403‘Tcl_CreateCommand()’ as shown. 404 405 In particular, PLplot has a number of [incr Tcl] classes in its Tcl 406library. If you want to be able to use those in your WISH, you need to 407include the initialization of [incr Tcl]. 408 409 410File: plplotdoc.info, Node: WISH Linking, Next: WISH Programming, Prev: WISH Construction, Up: Custom Extensions to Tcl 411 41214.5.2 WISH Linking 413------------------- 414 415Having constructed your ‘Tcl_AppInit()’ function, you now merely need to 416link this file with your own private files to provide the code for any 417functions you registered via ‘Tcl_CreateCommand()’ (and any they depend 418on), against the Tcl, Tk and extension libraries you are using. 419 420 421 cc -c tkAppInit.c 422 cc -c mycommands.c 423 cc -o my_wish tkAppInit.o mycommands.o 424 -lplplotftk -ltcl -ltk -litcl -lX11 -lm 425 426 Add any needed ‘-L’ options as needed. 427 428 Voila! You have made a wish. 429 430 431File: plplotdoc.info, Node: WISH Programming, Prev: WISH Linking, Up: Custom Extensions to Tcl 432 43314.5.3 WISH Programming 434----------------------- 435 436Now you are ready to put the genie to work. The basic plan here is to 437write shell scripts which use your new application specific windowing 438shell as their interpreter, to implement X Windows user interfaces to 439control and utilize the facilities made available in your extensions. 440 441 Effectively this just comes down to writing Tcl/Tk code, embellished 442as appropriate with calls to the extension commands you registered. 443Additionally, since this wish includes the PLplot extensions, you can 444instantiate any of the PLplot family of [incr Tcl] classes, and invoke 445methods on those objects to effect the drawing of graphs. Similarly, 446you may have your extension commands (which are coded in C) call the 447PLplot C programmers API to draw into the widget. In this way you can 448have the best of both worlds. Use compiled C code when the 449computational demands require the speed of compiled code, or use Tcl 450when your programming convenience is more important than raw speed. 451 452 453File: plplotdoc.info, Node: Embedding Plots in Graphical User Interfaces, Prev: Building an Extended WISH, Up: Supported computer languages 454 45515 Embedding Plots in Graphical User Interfaces 456*********************************************** 457 458This chapter should describe how to embed plots in graphical user 459interfaces. *note Building an Extended WISH:: does that for Tk, but 460embedding plots in GTK+ and Qt GUI’s NEEDS DOCUMENTATION. Until that 461GTK+ and QT4 documentation is prepared, look at examples/c/README.cairo 462and examples/c++/README.qt_example for some proof-of-concept examples. 463 464 465File: plplotdoc.info, Node: Reference, Prev: Supported computer languages, Up: Top 466 467Reference 468********* 469 470* Menu: 471 472* Bibliography:: 473* The Common API for PLplot:: 474* The Specialized C/C++ API for PLplot:: 475* The Specialized Fortran API for PLplot:: 476* API compatibility definition:: 477* Obsolete/Deprecated API for PLplot:: 478* Internal C functions in PLplot:: 479* The PLplot Libraries:: 480 481 482File: plplotdoc.info, Node: Bibliography, Next: The Common API for PLplot, Up: Reference 483 48416 Bibliography 485*************** 486 487These articles are descriptions of PLplot itself or else scientific 488publications whose figures were generated with PLplot. 489 490* Menu: 491 492* References:: 493 494 495File: plplotdoc.info, Node: References, Up: Bibliography 496 49716.1 References 498=============== 499 500Furnish G., Das Graphikpaket PLplot (in German) 501(http://www.linux-magazin.de/ausgabe/1996/12/Plplot/plplot.html), Linux 502Magazin, 1996 December 503 504 Furnish G., Horton W., Kishimoto Y., LeBrun M., Tajima T., Global 505Gyrokinetic Simulation of Tokamak Transport, Physics of Plasmas, 6, 1, 5061999 507 508 Irwin A.W., Fukushima T., A Numerical Time Ephemeris of the Earth, 509Astronomy and Astrophysics, 348, 642, 1999 510 511 LeBrun M.J., Tajima T., Gray M., Furnish G., Horton W., Toroidal 512Effects on Drift-Wave Turbulence, Physics of Fluids, B5, 752, 1993 513 514 515File: plplotdoc.info, Node: The Common API for PLplot, Next: The Specialized C/C++ API for PLplot, Prev: Bibliography, Up: Reference 516 51717 The Common API for PLplot 518**************************** 519 520The purpose of this chapter is to document the common API for every 521PLplot function that should be available across all PLplot language 522bindings. Therefore, this chapter excludes obsolete/deprecated API 523functions which are listed in *note Obsolete/Deprecated API for PLplot:: 524and also excludes API specialized for each language binding that is 525documented in *note The Specialized C/C++ API for PLplot:: and 526subsequent chapters. 527 528 The common API constitutes the most important part of the PLplot API 529that programmers need to know. 530 531 For the C case, these common API routines have prototypes defined in 532‘plplot.h’ using PLplot C types for arguments (*note plplot-types::). 533The names for these types have been chosen to be self-documenting. So 534‘PLINT’ refers to the PLplot integer type, and ‘PLFLT’ refers to the 535PLplot floating-point type. If the name has a ‘_VECTOR’ or ‘_MATRIX’ 536suffix the type corresponds to the one-dimensional or two-dimensional 537array argument type native to the language being supported by PLplot. 538If the name does not have either of those two suffixes or if it has a 539suffix of ‘_SCALAR’, then it refers to a scalar quantity. Finally, note 540that most of our common API arguments are input only and are guaranteed 541not to be changed by the PLplot routine. However, in some cases the 542argument is used for output quantities which _are_ changed by the PLplot 543routine, and in this case we include ‘_NC’ (standing for "non-constant") 544in the argument type name. 545 546 We document our common API below for the C case, but it should be 547fairly straightforward to infer the corresponding API for any of our 548supported languages from these results because of the self-documenting 549names we use for the PLplot C types for arguments (*note 550plplot-types::). Of course, the best way to learn how to use our common 551API for the language of your choice is to look at our standard set of 552examples (http://plplot.org/examples.php). For additional language 553documentation you should consult the various chapters in *note Supported 554computer languages: Supported computer languages. as well. 555 556 What follows is a list of all common API functions of the latest 557PLplot version. The following information is provided for each 558function: 559 560 1. The function name and a brief description. 561 562 2. The function as it would be called from C. 563 564 3. A complete description of the function. 565 566 4. A description of each argument that the function takes. 567 568 5. The redacted argument form of the function as well as any language 569 specific variations that might occur on the general calling scheme 570 described in the following paragraph. 571 572 6. A list of PLplot examples that demonstrate how to use the function. 573 574 The general calling scheme for the other languages supported by 575PLplot is as follows, using the function ‘plline’ (*note plline; Draw a 576line::) as an example. 577 578 • C: ‘plline( n, x, y );’ 579 580 • Ada/standard: ‘Draw_Curve( x, y );’ 581 582 • Ada/traditional: ‘plline( x, y );’ 583 584 • C++: ‘pls->line(n, x, y );’ 585 586 • D: ‘plline( x, y );’ 587 588 • Fortran: ‘plline( x, y )’ 589 590 • Java: ‘pls.line( x, y );’ 591 592 • Lua: ‘pl.line( x, y )’ 593 594 • OCaml: ‘plline x y;’ 595 596 • Octave: ‘plline( x', y' );’ 597 598 • Python: ‘plline( x, y )’ 599 600 • Tcl/Tk: ‘$w cmd plline x y’ 601 602Note that in all our supported languages other than C and C++, the 603argument ‘‘n’’ (which specifies the length of the input vectors ‘‘x’’ 604and ‘‘y’’) is not used in the argument list since that information is 605already available from the vector (and matrix in the general case) 606arguments themselves. This is what we refer to above as the ‘redacted 607argument form’ of the function. 608 609* Menu: 610 611* pl_setcontlabelformat; Set format of numerical label for contours:: 612* pl_setcontlabelparam; Set parameters of contour labelling other than format of numerical label:: 613* pladv; Advance the (sub-)page: pladv; Advance the [sub-]page. 614* plarc; Draw a circular or elliptical arc : plarc; Draw a circular or elliptical arc. 615* plaxes; Draw a box with axes, etc. with arbitrary origin : plaxes; Draw a box with axes; etc_ with arbitrary origin. 616* plbin; Plot a histogram from binned data : plbin; Plot a histogram from binned data. 617* plbop; Begin a new page:: 618* plbox; Draw a box with axes, etc: plbox; Draw a box with axes; etc. 619* plbox3; Draw a box with axes, etc, in 3-d : plbox3; Draw a box with axes; etc; in 3-d. 620* plbtime; Calculate broken-down time from continuous time for the current stream : plbtime; Calculate broken-down time from continuous time for the current stream. 621* plcalc_world; Calculate world coordinates and corresponding window index from relative device coordinates : plcalc_world; Calculate world coordinates and corresponding window index from relative device coordinates. 622* plclear; Clear current (sub)page : plclear; Clear current [sub]page. 623* plcol0; Set color, cmap0 : plcol0; Set color; cmap0. 624* plcol1; Set color, cmap1 : plcol1; Set color; cmap1. 625* plcolorbar; Plot color bar for image, shade or gradient plots : plcolorbar; Plot color bar for image; shade or gradient plots. 626* plconfigtime; Configure the transformation between continuous and broken-down time for the current stream : plconfigtime; Configure the transformation between continuous and broken-down time for the current stream. 627* plcont; Contour plot : plcont; Contour plot. 628* plcpstrm; Copy state parameters from the reference stream to the current stream : plcpstrm; Copy state parameters from the reference stream to the current stream. 629* plctime; Calculate continuous time from broken-down time for the current stream : plctime; Calculate continuous time from broken-down time for the current stream. 630* plend; End plotting session : plend; End plotting session. 631* plend1; End plotting session for current stream : plend1; End plotting session for current stream. 632* plenv0; Same as plenv but if in multiplot mode does not advance the subpage, instead clears it : plenv0; Same as plenv but if in multiplot mode does not advance the subpage; instead clears it. 633* plenv; Set up standard window and draw box : plenv; Set up standard window and draw box. 634* pleop; Eject current page : pleop; Eject current page. 635* plerrx; Draw error bars in x direction : plerrx; Draw error bars in x direction. 636* plerry; Draw error bars in the y direction : plerry; Draw error bars in the y direction. 637* plfamadv; Advance to the next family file on the next new page : plfamadv; Advance to the next family file on the next new page. 638* plfill; Draw filled polygon : plfill; Draw filled polygon. 639* plfill3; Draw filled polygon in 3D : plfill3; Draw filled polygon in 3D. 640* plflush; Flushes the output stream : plflush; Flushes the output stream. 641* plfont; Set font : plfont; Set font. 642* plfontld; Load Hershey fonts : plfontld; Load Hershey fonts. 643* plGetCursor; Wait for graphics input event and translate to world coordinates. : plGetCursor; Wait for graphics input event and translate to world coordinates_. 644* plgchr; Get character default height and current (scaled) height : plgchr; Get character default height and current [scaled] height. 645* plgcmap1_range; Get the cmap1 argument range for continuous color plots : plgcmap1_range; Get the cmap1 argument range for continuous color plots. 646* plgcol0; Returns 8-bit RGB values for given color index from cmap0 : plgcol0; Returns 8-bit RGB values for given color index from cmap0. 647* plgcol0a; Returns 8-bit RGB values and PLFLT alpha transparency value for given color index from cmap0 : plgcol0a; Returns 8-bit RGB values and PLFLT alpha transparency value for given color index from cmap0. 648* plgcolbg; Returns the background color (cmap0[0]) by 8-bit RGB value : plgcolbg; Returns the background color [cmap0[0]] by 8-bit RGB value. 649* plgcolbga; Returns the background color (cmap0[0]) by 8-bit RGB value and PLFLT alpha transparency value : plgcolbga; Returns the background color [cmap0[0]] by 8-bit RGB value and PLFLT alpha transparency value. 650* plgcompression; Get the current device-compression setting : plgcompression; Get the current device-compression setting. 651* plgdev; Get the current device (keyword) name : plgdev; Get the current device [keyword] name. 652* plgdidev; Get parameters that define current device-space window : plgdidev; Get parameters that define current device-space window. 653* plgdiori; Get plot orientation : plgdiori; Get plot orientation. 654* plgdiplt; Get parameters that define current plot-space window : plgdiplt; Get parameters that define current plot-space window. 655* plgdrawmode; Get drawing mode (depends on device support!) : plgdrawmode; Get drawing mode [depends on device support!]. 656* plgfam; Get family file parameters : plgfam; Get family file parameters. 657* plgfci; Get FCI (font characterization integer) : plgfci; Get FCI [font characterization integer]. 658* plgfnam; Get output file name : plgfnam; Get output file name. 659* plgfont; Get family, style and weight of the current font : plgfont; Get family; style and weight of the current font. 660* plglevel; Get the (current) run level : plglevel; Get the [current] run level. 661* plgpage; Get page parameters : plgpage; Get page parameters. 662* plgra; Switch to graphics screen : plgra; Switch to graphics screen. 663* plgradient; Draw linear gradient inside polygon : plgradient; Draw linear gradient inside polygon. 664* plgriddata; Grid data from irregularly sampled data : plgriddata; Grid data from irregularly sampled data. 665* plgspa; Get current subpage parameters : plgspa; Get current subpage parameters. 666* plgstrm; Get current stream number : plgstrm; Get current stream number. 667* plgver; Get the current library version number : plgver; Get the current library version number. 668* plgvpd; Get viewport limits in normalized device coordinates : plgvpd; Get viewport limits in normalized device coordinates. 669* plgvpw; Get viewport limits in world coordinates : plgvpw; Get viewport limits in world coordinates. 670* plgxax; Get x axis parameters : plgxax; Get x axis parameters. 671* plgyax; Get y axis parameters : plgyax; Get y axis parameters. 672* plgzax; Get z axis parameters : plgzax; Get z axis parameters. 673* plhist; Plot a histogram from unbinned data : plhist; Plot a histogram from unbinned data. 674* plhlsrgb; Convert HLS color to RGB : plhlsrgb; Convert HLS color to RGB. 675* plimagefr; Plot a 2D matrix using cmap1 : plimagefr; Plot a 2D matrix using cmap1. 676* plimage; Plot a 2D matrix using cmap1 with automatic color adjustment : plimage; Plot a 2D matrix using cmap1 with automatic color adjustment. 677* plinit; Initialize PLplot : plinit; Initialize PLplot. 678* pljoin; Draw a line between two points : pljoin; Draw a line between two points. 679* pllab; Simple routine to write labels : pllab; Simple routine to write labels. 680* pllegend; Plot legend using discretely annotated filled boxes, lines, and/or lines of symbols : pllegend; Plot legend using discretely annotated filled boxes; lines; and/or lines of symbols. 681* pllightsource; Sets the 3D position of the light source : pllightsource; Sets the 3D position of the light source. 682* plline; Draw a line : plline; Draw a line. 683* plline3; Draw a line in 3 space : plline3; Draw a line in 3 space. 684* pllsty; Select line style : pllsty; Select line style. 685* plmap; Plot continental outline or shapefile data in world coordinates : plmap; Plot continental outline or shapefile data in world coordinates. 686* plmapfill; Plot all or a subset of Shapefile data, filling the polygons : plmapfill; Plot all or a subset of Shapefile data; filling the polygons. 687* plmapline; Plot all or a subset of Shapefile data using lines in world coordinates : plmapline; Plot all or a subset of Shapefile data using lines in world coordinates. 688* plmapstring; Plot all or a subset of Shapefile data using strings or points in world coordinates : plmapstring; Plot all or a subset of Shapefile data using strings or points in world coordinates. 689* plmaptex; Draw text at points defined by Shapefile data in world coordinates : plmaptex; Draw text at points defined by Shapefile data in world coordinates. 690* plmeridians; Plot latitude and longitude lines : plmeridians; Plot latitude and longitude lines. 691* plmesh; Plot surface mesh : plmesh; Plot surface mesh. 692* plmeshc; Magnitude colored plot surface mesh with contour : plmeshc; Magnitude colored plot surface mesh with contour. 693* plmkstrm; Creates a new stream and makes it the default : plmkstrm; Creates a new stream and makes it the default. 694* plmtex; Write text relative to viewport boundaries : plmtex; Write text relative to viewport boundaries. 695* plmtex3; Write text relative to viewport boundaries in 3D plots : plmtex3; Write text relative to viewport boundaries in 3D plots. 696* plot3d; Plot 3-d surface plot : plot3d; Plot 3-d surface plot. 697* plot3dc; Magnitude colored plot surface with contour : plot3dc; Magnitude colored plot surface with contour. 698* plot3dcl; Magnitude colored plot surface with contour for z[x][y] with y index limits : plot3dcl; Magnitude colored plot surface with contour for z[x][y] with y index limits. 699* plparseopts; Parse command-line arguments : plparseopts; Parse command-line arguments. 700* plpat; Set area line fill pattern : plpat; Set area line fill pattern. 701* plpath; Draw a line between two points, accounting for coordinate transforms : plpath; Draw a line between two points; accounting for coordinate transforms. 702* plpoin; Plot a glyph at the specified points : plpoin; Plot a glyph at the specified points. 703* plpoin3; Plot a glyph at the specified 3D points : plpoin3; Plot a glyph at the specified 3D points. 704* plpoly3; Draw a polygon in 3 space : plpoly3; Draw a polygon in 3 space. 705* plprec; Set precision in numeric labels : plprec; Set precision in numeric labels. 706* plpsty; Select area fill pattern : plpsty; Select area fill pattern. 707* plptex; Write text inside the viewport : plptex; Write text inside the viewport. 708* plptex3; Write text inside the viewport of a 3D plot : plptex3; Write text inside the viewport of a 3D plot. 709* plrandd; Random number generator returning a real random number in the range [0,1] : plrandd; Random number generator returning a real random number in the range [0;1]. 710* plreplot; Replays contents of plot buffer to current device/file : plreplot; Replays contents of plot buffer to current device/file. 711* plrgbhls; Convert RGB color to HLS : plrgbhls; Convert RGB color to HLS. 712* plschr; Set character size : plschr; Set character size. 713* plscmap0; Set cmap0 colors by 8-bit RGB values : plscmap0; Set cmap0 colors by 8-bit RGB values. 714* plscmap0a; Set cmap0 colors by 8-bit RGB values and PLFLT alpha transparency value : plscmap0a; Set cmap0 colors by 8-bit RGB values and PLFLT alpha transparency value. 715* plscmap0n; Set number of colors in cmap0 : plscmap0n; Set number of colors in cmap0. 716* plscmap1_range; Set the cmap1 argument range for continuous color plots : plscmap1_range; Set the cmap1 argument range for continuous color plots. 717* plscmap1; Set opaque RGB cmap1 colors values : plscmap1; Set opaque RGB cmap1 colors values. 718* plscmap1a; Set semitransparent cmap1 RGBA colors. : plscmap1a; Set semitransparent cmap1 RGBA colors_. 719* plscmap1l; Set cmap1 colors using a piece-wise linear relationship : plscmap1l; Set cmap1 colors using a piece-wise linear relationship. 720* plscmap1la; Set cmap1 colors and alpha transparency using a piece-wise linear relationship : plscmap1la; Set cmap1 colors and alpha transparency using a piece-wise linear relationship. 721* plscmap1n; Set number of colors in cmap1 : plscmap1n; Set number of colors in cmap1. 722* plscol0; Set 8-bit RGB values for given cmap0 color index : plscol0; Set 8-bit RGB values for given cmap0 color index. 723* plscol0a; Set 8-bit RGB values and PLFLT alpha transparency value for given cmap0 color index : plscol0a; Set 8-bit RGB values and PLFLT alpha transparency value for given cmap0 color index. 724* plscolbg; Set the background color by 8-bit RGB value : plscolbg; Set the background color by 8-bit RGB value. 725* plscolbga; Set the background color by 8-bit RGB value and PLFLT alpha transparency value. : plscolbga; Set the background color by 8-bit RGB value and PLFLT alpha transparency value_. 726* plscolor; Used to globally turn color output on/off : plscolor; Used to globally turn color output on/off. 727* plscompression; Set device-compression level : plscompression; Set device-compression level. 728* plsdev; Set the device (keyword) name : plsdev; Set the device [keyword] name. 729* plsdidev; Set parameters that define current device-space window : plsdidev; Set parameters that define current device-space window. 730* plsdimap; Set up transformation from metafile coordinates : plsdimap; Set up transformation from metafile coordinates. 731* plsdiori; Set plot orientation : plsdiori; Set plot orientation. 732* plsdiplt; Set parameters that define current plot-space window : plsdiplt; Set parameters that define current plot-space window. 733* plsdiplz; Set parameters incrementally (zoom mode) that define current plot-space window : plsdiplz; Set parameters incrementally [zoom mode] that define current plot-space window. 734* plsdrawmode; Set drawing mode (depends on device support!) : plsdrawmode; Set drawing mode [depends on device support!]. 735* plseed; Set seed for internal random number generator. : plseed; Set seed for internal random number generator_. 736* plsesc; Set the escape character for text strings : plsesc; Set the escape character for text strings. 737* plsetopt; Set any command-line option : plsetopt; Set any command-line option. 738* plsfam; Set family file parameters : plsfam; Set family file parameters. 739* plsfci; Set FCI (font characterization integer) : plsfci; Set FCI [font characterization integer]. 740* plsfnam; Set output file name : plsfnam; Set output file name. 741* plsfont; Set family, style and weight of the current font : plsfont; Set family; style and weight of the current font. 742* plshades; Shade regions on the basis of value : plshades; Shade regions on the basis of value. 743* plshade; Shade individual region on the basis of value : plshade; Shade individual region on the basis of value. 744* plslabelfunc; Assign a function to use for generating custom axis labels : plslabelfunc; Assign a function to use for generating custom axis labels. 745* plsmaj; Set length of major ticks : plsmaj; Set length of major ticks. 746* plsmem; Set the memory area to be plotted (RGB) : plsmem; Set the memory area to be plotted [RGB]. 747* plsmema; Set the memory area to be plotted (RGBA) : plsmema; Set the memory area to be plotted [RGBA]. 748* plsmin; Set length of minor ticks : plsmin; Set length of minor ticks. 749* plsori; Set orientation : plsori; Set orientation. 750* plspage; Set page parameters : plspage; Set page parameters. 751* plspal0; Set the cmap0 palette using the specified cmap0*.pal format file : plspal0; Set the cmap0 palette using the specified cmap0*_pal format file. 752* plspal1; Set the cmap1 palette using the specified cmap1*.pal format file : plspal1; Set the cmap1 palette using the specified cmap1*_pal format file. 753* plspause; Set the pause (on end-of-page) status : plspause; Set the pause [on end-of-page] status. 754* plsstrm; Set current output stream : plsstrm; Set current output stream. 755* plssub; Set the number of subpages in x and y : plssub; Set the number of subpages in x and y. 756* plssym; Set symbol size : plssym; Set symbol size. 757* plstar; Initialization : plstar; Initialization. 758* plstart; Initialization : plstart; Initialization. 759* plstransform; Set a global coordinate transform function : plstransform; Set a global coordinate transform function. 760* plstring; Plot a glyph at the specified points : plstring; Plot a glyph at the specified points. 761* plstring3; Plot a glyph at the specified 3D points : plstring3; Plot a glyph at the specified 3D points. 762* plstripa; Add a point to a strip chart : plstripa; Add a point to a strip chart. 763* plstripc; Create a 4-pen strip chart : plstripc; Create a 4-pen strip chart. 764* plstripd; Deletes and releases memory used by a strip chart : plstripd; Deletes and releases memory used by a strip chart. 765* plstyl; Set line style : plstyl; Set line style. 766* plsurf3d; Plot shaded 3-d surface plot : plsurf3d; Plot shaded 3-d surface plot. 767* plsurf3dl; Plot shaded 3-d surface plot for z[x][y] with y index limits : plsurf3dl; Plot shaded 3-d surface plot for z[x][y] with y index limits. 768* plsvect; Set arrow style for vector plots : plsvect; Set arrow style for vector plots. 769* plsvpa; Specify viewport in absolute coordinates : plsvpa; Specify viewport in absolute coordinates. 770* plsxax; Set x axis parameters : plsxax; Set x axis parameters. 771* plsyax; Set y axis parameters : plsyax; Set y axis parameters. 772* plsym; Plot a glyph at the specified points : plsym; Plot a glyph at the specified points. 773* plszax; Set z axis parameters : plszax; Set z axis parameters. 774* pltext; Switch to text screen : pltext; Switch to text screen. 775* pltimefmt; Set format for date / time labels : pltimefmt; Set format for date / time labels. 776* plvasp; Specify viewport using aspect ratio only : plvasp; Specify viewport using aspect ratio only. 777* plvect; Vector plot : plvect; Vector plot. 778* plvpas; Specify viewport using coordinates and aspect ratio : plvpas; Specify viewport using coordinates and aspect ratio. 779* plvpor; Specify viewport using normalized subpage coordinates : plvpor; Specify viewport using normalized subpage coordinates. 780* plvsta; Select standard viewport : plvsta; Select standard viewport. 781* plw3d; Configure the transformations required for projecting a 3D surface on a 2D window : plw3d; Configure the transformations required for projecting a 3D surface on a 2D window. 782* plwidth; Set pen width : plwidth; Set pen width. 783* plwind; Specify window : plwind; Specify window. 784* plxormod; Enter or leave xor mode : plxormod; Enter or leave xor mode. 785 786 787File: plplotdoc.info, Node: pl_setcontlabelformat; Set format of numerical label for contours, Next: pl_setcontlabelparam; Set parameters of contour labelling other than format of numerical label, Up: The Common API for PLplot 788 78917.1 pl_setcontlabelformat: Set format of numerical label for contours 790====================================================================== 791 792 pl_setcontlabelformat (lexp, sigdig); 793 794 Set format of numerical label for contours. 795 796‘lexp’ (‘‘PLINT’ (*note PLINT-type::)’, input) 797 If the contour numerical label is greater than 10^(lexp) or less 798 than 10^(-lexp), then the exponential format is used. Default 799 value of lexp is 4. 800 801‘sigdig’ (‘‘PLINT’ (*note PLINT-type::)’, input) 802 Number of significant digits. Default value is 2. 803 804 Redacted form: ‘pl_setcontlabelformat(lexp, sigdig)’ 805 806 This function is used example 9. 807 808 809File: plplotdoc.info, Node: pl_setcontlabelparam; Set parameters of contour labelling other than format of numerical label, Next: pladv; Advance the [sub-]page, Prev: pl_setcontlabelformat; Set format of numerical label for contours, Up: The Common API for PLplot 810 81117.2 pl_setcontlabelparam: Set parameters of contour labelling other than format of numerical label 812=================================================================================================== 813 814 pl_setcontlabelparam (offset, size, spacing, active); 815 816 Set parameters of contour labelling other than those handled by 817‘pl_setcontlabelformat’ (*note pl_setcontlabelformat; Set format of 818numerical label for contours::). 819 820‘offset’ (‘‘PLFLT’ (*note PLFLT-type::)’, input) 821 Offset of label from contour line (if set to 0.0, labels are 822 printed on the lines). Default value is 0.006. 823 824‘size’ (‘‘PLFLT’ (*note PLFLT-type::)’, input) 825 Font height for contour labels (normalized). Default value is 0.3. 826 827‘spacing’ (‘‘PLFLT’ (*note PLFLT-type::)’, input) 828 Spacing parameter for contour labels. Default value is 0.1. 829 830‘active’ (‘‘PLINT’ (*note PLINT-type::)’, input) 831 Activate labels. Set to 1 if you want contour labels on. Default 832 is off (0). 833 834 Redacted form: ‘pl_setcontlabelparam(offset, size, spacing, active)’ 835 836 This function is used in example 9. 837 838 839File: plplotdoc.info, Node: pladv; Advance the [sub-]page, Next: plarc; Draw a circular or elliptical arc, Prev: pl_setcontlabelparam; Set parameters of contour labelling other than format of numerical label, Up: The Common API for PLplot 840 84117.3 pladv: Advance the (sub-)page 842================================== 843 844 pladv (page); 845 846 Advances to the next subpage if ‘‘sub’=0’, performing a page advance 847if there are no remaining subpages on the current page. If subpages 848aren’t being used, ‘‘pladv’ (*note pladv; Advance the [sub-]page::)(0)’ 849will always advance the page. If ‘‘page’>0’, PLplot switches to the 850specified subpage. Note that this allows you to overwrite a plot on the 851specified subpage; if this is not what you intended, use ‘pleop’ (*note 852pleop; Eject current page::) followed by ‘plbop’ (*note plbop; Begin a 853new page::) to first advance the page. This routine is called 854automatically (with ‘‘page’=0’) by ‘plenv’ (*note plenv; Set up standard 855window and draw box::), but if ‘plenv’ (*note plenv; Set up standard 856window and draw box::) is not used, ‘pladv’ (*note pladv; Advance the 857[sub-]page::) must be called after initializing PLplot but before 858defining the viewport. 859 860‘page’ (‘‘PLINT’ (*note PLINT-type::)’, input) 861 Specifies the subpage number (starting from 1 in the top left 862 corner and increasing along the rows) to which to advance. Set to 863 zero to advance to the next subpage (or to the next page if 864 subpages are not being used). 865 866 Redacted form: ‘pladv(page)’ 867 868 This function is used in examples 1, 2, 4, 6-12, 14-18, 20, 21, 86923-27, 29, and 31. 870 871 872File: plplotdoc.info, Node: plarc; Draw a circular or elliptical arc, Next: plaxes; Draw a box with axes; etc_ with arbitrary origin, Prev: pladv; Advance the [sub-]page, Up: The Common API for PLplot 873 87417.4 plarc: Draw a circular or elliptical arc 875============================================= 876 877 plarc (x, y, a, b, angle1, angle2, rotate, fill); 878 879 Draw a possibly filled arc centered at ‘‘x’’, ‘‘y’’ with semimajor 880axis ‘‘a’’ and semiminor axis ‘‘b’’, starting at ‘‘angle1’’ and ending 881at ‘‘angle2’’. 882 883‘x’ (‘‘PLFLT’ (*note PLFLT-type::)’, input) 884 X coordinate of arc center. 885 886‘y’ (‘‘PLFLT’ (*note PLFLT-type::)’, input) 887 Y coordinate of arc center. 888 889‘a’ (‘‘PLFLT’ (*note PLFLT-type::)’, input) 890 Length of the semimajor axis of the arc. 891 892‘b’ (‘‘PLFLT’ (*note PLFLT-type::)’, input) 893 Length of the semiminor axis of the arc. 894 895‘angle1’ (‘‘PLFLT’ (*note PLFLT-type::)’, input) 896 Starting angle of the arc relative to the semimajor axis. 897 898‘angle2’ (‘‘PLFLT’ (*note PLFLT-type::)’, input) 899 Ending angle of the arc relative to the semimajor axis. 900 901‘rotate’ (‘‘PLFLT’ (*note PLFLT-type::)’, input) 902 Angle of the semimajor axis relative to the X-axis. 903 904‘fill’ (‘‘PLBOOL’ (*note PLBOOL-type::)’, input) 905 Draw a filled arc. 906 907 Redacted form: 908 909 • General: ‘plarc(x, y, a, b, angle1, angle2, rotate, fill)’ 910 911 This function is used in examples 3 and 27. 912 913 914File: plplotdoc.info, Node: plaxes; Draw a box with axes; etc_ with arbitrary origin, Next: plbin; Plot a histogram from binned data, Prev: plarc; Draw a circular or elliptical arc, Up: The Common API for PLplot 915 91617.5 plaxes: Draw a box with axes, etc. with arbitrary origin 917============================================================= 918 919 plaxes (x0, y0, xopt, xtick, nxsub, yopt, ytick, nysub); 920 921 Draws a box around the currently defined viewport with arbitrary 922world-coordinate origin specified by ‘‘x0’’ and ‘‘y0’’ and labels it 923with world coordinate values appropriate to the window. Thus ‘plaxes’ 924(*note plaxes; Draw a box with axes; etc_ with arbitrary origin::) 925should only be called after defining both viewport and window. The 926ascii character strings ‘‘xopt’’ and ‘‘yopt’’ specify how the box should 927be drawn as described below. If ticks and/or subticks are to be drawn 928for a particular axis, the tick intervals and number of subintervals may 929be specified explicitly, or they may be defaulted by setting the 930appropriate arguments to zero. 931 932‘x0’ (‘‘PLFLT’ (*note PLFLT-type::)’, input) 933 World X coordinate of origin. 934 935‘y0’ (‘‘PLFLT’ (*note PLFLT-type::)’, input) 936 World Y coordinate of origin. 937 938‘xopt’ (‘‘PLCHAR_VECTOR’ (*note PLCHAR_VECTOR-type::)’, input) 939 An ascii character string specifying options for the x axis. The 940 string can include any combination of the following letters (upper 941 or lower case) in any order: 942 943 • ‘a’: Draws axis, X-axis is horizontal line (‘y=0’), and Y-axis 944 is vertical line (‘x=0’). 945 946 • ‘b’: Draws bottom (X) or left (Y) edge of frame. 947 948 • ‘c’: Draws top (X) or right (Y) edge of frame. 949 950 • ‘d’: Plot labels as date / time. Values are assumed to be 951 seconds since the epoch (as used by gmtime). 952 953 • ‘f’: Always use fixed point numeric labels. 954 955 • ‘g’: Draws a grid at the major tick interval. 956 957 • ‘h’: Draws a grid at the minor tick interval. 958 959 • ‘i’: Inverts tick marks, so they are drawn outwards, rather 960 than inwards. 961 962 • ‘l’: Labels axis logarithmically. This only affects the 963 labels, not the data, and so it is necessary to compute the 964 logarithms of data points before passing them to any of the 965 drawing routines. 966 967 • ‘m’: Writes numeric labels at major tick intervals in the 968 unconventional location (above box for X, right of box for Y). 969 970 • ‘n’: Writes numeric labels at major tick intervals in the 971 conventional location (below box for X, left of box for Y). 972 973 • ‘o’: Use custom labelling function to generate axis label 974 text. The custom labelling function can be defined with the 975 ‘plslabelfunc’ (*note plslabelfunc; Assign a function to use 976 for generating custom axis labels::) command. 977 978 • ‘s’: Enables subticks between major ticks, only valid if ‘t’ 979 is also specified. 980 981 • ‘t’: Draws major ticks. 982 983 • ‘u’: Exactly like "b" except don’t draw edge line. 984 985 • ‘w’: Exactly like "c" except don’t draw edge line. 986 987 • ‘x’: Exactly like "t" (including the side effect of the 988 numerical labels for the major ticks) except exclude drawing 989 the major and minor tick marks. 990 991‘xtick’ (‘‘PLFLT’ (*note PLFLT-type::)’, input) 992 World coordinate interval between major ticks on the x axis. If it 993 is set to zero, PLplot automatically generates a suitable tick 994 interval. 995 996‘nxsub’ (‘‘PLINT’ (*note PLINT-type::)’, input) 997 Number of subintervals between major x axis ticks for minor ticks. 998 If it is set to zero, PLplot automatically generates a suitable 999 minor tick interval. 1000 1001‘yopt’ (‘‘PLCHAR_VECTOR’ (*note PLCHAR_VECTOR-type::)’, input) 1002 An ascii character string specifying options for the y axis. The 1003 string can include any combination of the letters defined above for 1004 ‘‘xopt’’, and in addition may contain: 1005 1006 • ‘v’: Write numeric labels for the y axis parallel to the base 1007 of the graph, rather than parallel to the axis. 1008 1009‘ytick’ (‘‘PLFLT’ (*note PLFLT-type::)’, input) 1010 World coordinate interval between major ticks on the y axis. If it 1011 is set to zero, PLplot automatically generates a suitable tick 1012 interval. 1013 1014‘nysub’ (‘‘PLINT’ (*note PLINT-type::)’, input) 1015 Number of subintervals between major y axis ticks for minor ticks. 1016 If it is set to zero, PLplot automatically generates a suitable 1017 minor tick interval. 1018 1019 Redacted form: 1020 1021 • General: ‘plaxes(x0, y0, xopt, xtick, nxsub, yopt, ytick, nysub)’ 1022 1023 This function is not used in any examples. 1024 1025 1026File: plplotdoc.info, Node: plbin; Plot a histogram from binned data, Next: plbop; Begin a new page, Prev: plaxes; Draw a box with axes; etc_ with arbitrary origin, Up: The Common API for PLplot 1027 102817.6 plbin: Plot a histogram from binned data 1029============================================= 1030 1031 plbin (nbin, x, y, opt); 1032 1033 Plots a histogram consisting of ‘‘nbin’’ bins. The value associated 1034with the ‘i’’th bin is placed in ‘‘x’[i]’, and the number of points in 1035the bin is placed in ‘‘y’[i]’. For proper operation, the values in 1036‘‘x’[i]’ must form a strictly increasing sequence. By default, ‘‘x’[i]’ 1037is the left-hand edge of the ‘i’’th bin. If ‘‘opt’=PL_BIN_CENTRED’ is 1038used, the bin boundaries are placed midway between the values in the 1039‘‘x’’ vector. Also see ‘plhist’ (*note plhist; Plot a histogram from 1040unbinned data::) for drawing histograms from unbinned data. 1041 1042‘nbin’ (‘‘PLINT’ (*note PLINT-type::)’, input) 1043 Number of bins (i.e., number of values in ‘‘x’’ and ‘‘y’’ vectors.) 1044 1045‘x’ (‘‘PLFLT_VECTOR’ (*note PLFLT_VECTOR-type::)’, input) 1046 A vector containing values associated with bins. These must form a 1047 strictly increasing sequence. 1048 1049‘y’ (‘‘PLFLT_VECTOR’ (*note PLFLT_VECTOR-type::)’, input) 1050 A vector containing a number which is proportional to the number of 1051 points in each bin. This is a ‘PLFLT’ (instead of ‘PLINT’) vector 1052 so as to allow histograms of probabilities, etc. 1053 1054‘opt’ (‘‘PLINT’ (*note PLINT-type::)’, input) 1055 Is a combination of several flags: 1056 1057 • ‘‘opt’=PL_BIN_DEFAULT’: The ‘‘x’’ represent the lower bin 1058 boundaries, the outer bins are expanded to fill up the entire 1059 x-axis and bins of zero height are simply drawn. 1060 1061 • ‘‘opt’=PL_BIN_CENTRED|...’: The bin boundaries are to be 1062 midway between the ‘‘x’’ values. If the values in ‘‘x’’ are 1063 equally spaced, the values are the center values of the bins. 1064 1065 • ‘‘opt’=PL_BIN_NOEXPAND|...’: The outer bins are drawn with 1066 equal size as the ones inside. 1067 1068 • ‘‘opt’=PL_BIN_NOEMPTY|...’: Bins with zero height are not 1069 drawn (there is a gap for such bins). 1070 1071 Redacted form: 1072 1073 • General: ‘plbin(x, y, opt)’ 1074 1075 • Python: ‘plbin(nbin, x, y, opt)’ 1076 1077 This function is not used in any examples. 1078 1079 1080File: plplotdoc.info, Node: plbop; Begin a new page, Next: plbox; Draw a box with axes; etc, Prev: plbin; Plot a histogram from binned data, Up: The Common API for PLplot 1081 108217.7 plbop: Begin a new page 1083============================ 1084 1085 plbop (); 1086 1087 Begins a new page. For a file driver, the output file is opened if 1088necessary. Advancing the page via ‘pleop’ (*note pleop; Eject current 1089page::) and ‘plbop’ (*note plbop; Begin a new page::) is useful when a 1090page break is desired at a particular point when plotting to subpages. 1091Another use for ‘pleop’ (*note pleop; Eject current page::) and ‘plbop’ 1092(*note plbop; Begin a new page::) is when plotting pages to different 1093files, since you can manually set the file name by calling ‘plsfnam’ 1094(*note plsfnam; Set output file name::) after the call to ‘pleop’ (*note 1095pleop; Eject current page::). (In fact some drivers may only support a 1096single page per file, making this a necessity.) One way to handle this 1097case automatically is to page advance via ‘pladv’ (*note pladv; Advance 1098the [sub-]page::), but enable familying (see ‘plsfam’ (*note plsfam; Set 1099family file parameters::)) with a small limit on the file size so that a 1100new family member file will be created on each page break. 1101 1102 Redacted form: ‘plbop()’ 1103 1104 This function is used in examples 2 and 20. 1105 1106 1107File: plplotdoc.info, Node: plbox; Draw a box with axes; etc, Next: plbox3; Draw a box with axes; etc; in 3-d, Prev: plbop; Begin a new page, Up: The Common API for PLplot 1108 110917.8 plbox: Draw a box with axes, etc 1110===================================== 1111 1112 plbox (xopt, xtick, nxsub, yopt, ytick, nysub); 1113 1114 Draws a box around the currently defined viewport, and labels it with 1115world coordinate values appropriate to the window. Thus ‘plbox’ (*note 1116plbox; Draw a box with axes; etc::) should only be called after defining 1117both viewport and window. The ascii character strings ‘‘xopt’’ and 1118‘‘yopt’’ specify how the box should be drawn as described below. If 1119ticks and/or subticks are to be drawn for a particular axis, the tick 1120intervals and number of subintervals may be specified explicitly, or 1121they may be defaulted by setting the appropriate arguments to zero. 1122 1123‘xopt’ (‘‘PLCHAR_VECTOR’ (*note PLCHAR_VECTOR-type::)’, input) 1124 An ascii character string specifying options for the x axis. The 1125 string can include any combination of the following letters (upper 1126 or lower case) in any order: 1127 1128 • ‘a’: Draws axis, X-axis is horizontal line (‘y=0’), and Y-axis 1129 is vertical line (‘x=0’). 1130 1131 • ‘b’: Draws bottom (X) or left (Y) edge of frame. 1132 1133 • ‘c’: Draws top (X) or right (Y) edge of frame. 1134 1135 • ‘d’: Plot labels as date / time. Values are assumed to be 1136 seconds since the epoch (as used by gmtime). 1137 1138 • ‘f’: Always use fixed point numeric labels. 1139 1140 • ‘g’: Draws a grid at the major tick interval. 1141 1142 • ‘h’: Draws a grid at the minor tick interval. 1143 1144 • ‘i’: Inverts tick marks, so they are drawn outwards, rather 1145 than inwards. 1146 1147 • ‘l’: Labels axis logarithmically. This only affects the 1148 labels, not the data, and so it is necessary to compute the 1149 logarithms of data points before passing them to any of the 1150 drawing routines. 1151 1152 • ‘m’: Writes numeric labels at major tick intervals in the 1153 unconventional location (above box for X, right of box for Y). 1154 1155 • ‘n’: Writes numeric labels at major tick intervals in the 1156 conventional location (below box for X, left of box for Y). 1157 1158 • ‘o’: Use custom labelling function to generate axis label 1159 text. The custom labelling function can be defined with the 1160 ‘plslabelfunc’ (*note plslabelfunc; Assign a function to use 1161 for generating custom axis labels::) command. 1162 1163 • ‘s’: Enables subticks between major ticks, only valid if ‘t’ 1164 is also specified. 1165 1166 • ‘t’: Draws major ticks. 1167 1168 • ‘u’: Exactly like "b" except don’t draw edge line. 1169 1170 • ‘w’: Exactly like "c" except don’t draw edge line. 1171 1172 • ‘x’: Exactly like "t" (including the side effect of the 1173 numerical labels for the major ticks) except exclude drawing 1174 the major and minor tick marks. 1175 1176‘xtick’ (‘‘PLFLT’ (*note PLFLT-type::)’, input) 1177 World coordinate interval between major ticks on the x axis. If it 1178 is set to zero, PLplot automatically generates a suitable tick 1179 interval. 1180 1181‘nxsub’ (‘‘PLINT’ (*note PLINT-type::)’, input) 1182 Number of subintervals between major x axis ticks for minor ticks. 1183 If it is set to zero, PLplot automatically generates a suitable 1184 minor tick interval. 1185 1186‘yopt’ (‘‘PLCHAR_VECTOR’ (*note PLCHAR_VECTOR-type::)’, input) 1187 An ascii character string specifying options for the y axis. The 1188 string can include any combination of the letters defined above for 1189 ‘‘xopt’’, and in addition may contain: 1190 1191 • ‘v’: Write numeric labels for the y axis parallel to the base 1192 of the graph, rather than parallel to the axis. 1193 1194‘ytick’ (‘‘PLFLT’ (*note PLFLT-type::)’, input) 1195 World coordinate interval between major ticks on the y axis. If it 1196 is set to zero, PLplot automatically generates a suitable tick 1197 interval. 1198 1199‘nysub’ (‘‘PLINT’ (*note PLINT-type::)’, input) 1200 Number of subintervals between major y axis ticks for minor ticks. 1201 If it is set to zero, PLplot automatically generates a suitable 1202 minor tick interval. 1203 1204 Redacted form: 1205 1206 • General: ‘plbox(xopt, xtick, nxsub, yopt, ytick, nysub)’ 1207 1208 This function is used in examples 1, 2, 4, 6, 6-12, 14-18, 21, 23-26, 1209and 29. 1210 1211 1212File: plplotdoc.info, Node: plbox3; Draw a box with axes; etc; in 3-d, Next: plbtime; Calculate broken-down time from continuous time for the current stream, Prev: plbox; Draw a box with axes; etc, Up: The Common API for PLplot 1213 121417.9 plbox3: Draw a box with axes, etc, in 3-d 1215============================================== 1216 1217 plbox3 (xopt, xlabel, xtick, nxsub, yopt, ylabel, ytick, nysub, 1218 zopt, zlabel, ztick, nzsub); 1219 1220 Draws axes, numeric and text labels for a three-dimensional surface 1221plot. For a more complete description of three-dimensional plotting see 1222*note Three-dimensional Plots::. 1223 1224‘xopt’ (‘‘PLCHAR_VECTOR’ (*note PLCHAR_VECTOR-type::)’, input) 1225 An ascii character string specifying options for the x axis. The 1226 string can include any combination of the following letters (upper 1227 or lower case) in any order: 1228 1229 • ‘b’: Draws axis at base, at height ‘z=‘zmin’’ where ‘‘zmin’’ 1230 is defined by call to ‘plw3d’ (*note plw3d; Configure the 1231 transformations required for projecting a 3D surface on a 2D 1232 window::). This character must be specified in order to use 1233 any of the other options. 1234 1235 • ‘d’: Plot labels as date / time. Values are assumed to be 1236 seconds since the epoch (as used by gmtime). 1237 1238 • ‘f’: Always use fixed point numeric labels. 1239 1240 • ‘i’: Inverts tick marks, so they are drawn downwards, rather 1241 than upwards. 1242 1243 • ‘l’: Labels axis logarithmically. This only affects the 1244 labels, not the data, and so it is necessary to compute the 1245 logarithms of data points before passing them to any of the 1246 drawing routines. 1247 1248 • ‘n’: Writes numeric labels at major tick intervals. 1249 1250 • ‘o’: Use custom labelling function to generate axis label 1251 text. The custom labelling function can be defined with the 1252 ‘plslabelfunc’ (*note plslabelfunc; Assign a function to use 1253 for generating custom axis labels::) command. 1254 1255 • ‘s’: Enables subticks between major ticks, only valid if ‘t’ 1256 is also specified. 1257 1258 • ‘t’: Draws major ticks. 1259 1260 • ‘u’: If this is specified, the text label for the axis is 1261 written under the axis. 1262 1263‘xlabel’ (‘‘PLCHAR_VECTOR’ (*note PLCHAR_VECTOR-type::)’, input) 1264 A UTF-8 character string specifying the text label for the x axis. 1265 It is only drawn if ‘u’ is in the ‘‘xopt’’ string. 1266 1267‘xtick’ (‘‘PLFLT’ (*note PLFLT-type::)’, input) 1268 World coordinate interval between major ticks on the x axis. If it 1269 is set to zero, PLplot automatically generates a suitable tick 1270 interval. 1271 1272‘nxsub’ (‘‘PLINT’ (*note PLINT-type::)’, input) 1273 Number of subintervals between major x axis ticks for minor ticks. 1274 If it is set to zero, PLplot automatically generates a suitable 1275 minor tick interval. 1276 1277‘yopt’ (‘‘PLCHAR_VECTOR’ (*note PLCHAR_VECTOR-type::)’, input) 1278 An ascii character string specifying options for the y axis. The 1279 string is interpreted in the same way as ‘‘xopt’’. 1280 1281‘ylabel’ (‘‘PLCHAR_VECTOR’ (*note PLCHAR_VECTOR-type::)’, input) 1282 A UTF-8 character string specifying the text label for the y axis. 1283 It is only drawn if ‘u’ is in the ‘‘yopt’’ string. 1284 1285‘ytick’ (‘‘PLFLT’ (*note PLFLT-type::)’, input) 1286 World coordinate interval between major ticks on the y axis. If it 1287 is set to zero, PLplot automatically generates a suitable tick 1288 interval. 1289 1290‘nysub’ (‘‘PLINT’ (*note PLINT-type::)’, input) 1291 Number of subintervals between major y axis ticks for minor ticks. 1292 If it is set to zero, PLplot automatically generates a suitable 1293 minor tick interval. 1294 1295‘zopt’ (‘‘PLCHAR_VECTOR’ (*note PLCHAR_VECTOR-type::)’, input) 1296 An ascii character string specifying options for the z axis. The 1297 string can include any combination of the following letters (upper 1298 or lower case) in any order: 1299 1300 • ‘b’: Draws z axis to the left of the surface plot. 1301 1302 • ‘c’: Draws z axis to the right of the surface plot. 1303 1304 • ‘d’: Draws grid lines parallel to the x-y plane behind the 1305 figure. These lines are not drawn until after ‘plot3d’ (*note 1306 plot3d; Plot 3-d surface plot::) or ‘plmesh’ (*note plmesh; 1307 Plot surface mesh::) are called because of the need for hidden 1308 line removal. 1309 1310 • ‘e’: Plot labels as date / time. Values are assumed to be 1311 seconds since the epoch (as used by gmtime). Note this 1312 suboption is interpreted the same as the ‘d’ suboption for 1313 ‘‘xopt’’ and ‘‘yopt’’, but it has to be identified as ‘e’ for 1314 ‘‘zopt’’ since ‘d’ has already been used for the different 1315 purpose above. 1316 1317 • ‘f’: Always use fixed point numeric labels. 1318 1319 • ‘i’: Inverts tick marks, so they are drawn away from the 1320 center. 1321 1322 • ‘l’: Labels axis logarithmically. This only affects the 1323 labels, not the data, and so it is necessary to compute the 1324 logarithms of data points before passing them to any of the 1325 drawing routines. 1326 1327 • ‘m’: Writes numeric labels at major tick intervals on the 1328 right-hand z axis. 1329 1330 • ‘n’: Writes numeric labels at major tick intervals on the 1331 left-hand z axis. 1332 1333 • ‘o’: Use custom labelling function to generate axis label 1334 text. The custom labelling function can be defined with the 1335 ‘plslabelfunc’ (*note plslabelfunc; Assign a function to use 1336 for generating custom axis labels::) command. 1337 1338 • ‘s’: Enables subticks between major ticks, only valid if ‘t’ 1339 is also specified. 1340 1341 • ‘t’: Draws major ticks. 1342 1343 • ‘u’: If this is specified, the text label is written beside 1344 the left-hand axis. 1345 1346 • ‘v’: If this is specified, the text label is written beside 1347 the right-hand axis. 1348 1349‘zlabel’ (‘‘PLCHAR_VECTOR’ (*note PLCHAR_VECTOR-type::)’, input) 1350 A UTF-8 character string specifying the text label for the z axis. 1351 It is only drawn if ‘u’ or ‘v’ are in the ‘‘zopt’’ string. 1352 1353‘ztick’ (‘‘PLFLT’ (*note PLFLT-type::)’, input) 1354 World coordinate interval between major ticks on the z axis. If it 1355 is set to zero, PLplot automatically generates a suitable tick 1356 interval. 1357 1358‘nzsub’ (‘‘PLINT’ (*note PLINT-type::)’, input) 1359 Number of subintervals between major z axis ticks for minor ticks. 1360 If it is set to zero, PLplot automatically generates a suitable 1361 minor tick interval. 1362 1363 Redacted form: 1364 1365 • General: ‘plbox3(xopt, xlabel, xtick, nxsub, yopt, ylabel, ytick, 1366 nysub, zopt, zlabel, ztick, nzsub)’ 1367 1368 This function is used in examples 8, 11, 18, and 21. 1369 1370 1371File: plplotdoc.info, Node: plbtime; Calculate broken-down time from continuous time for the current stream, Next: plcalc_world; Calculate world coordinates and corresponding window index from relative device coordinates, Prev: plbox3; Draw a box with axes; etc; in 3-d, Up: The Common API for PLplot 1372 137317.10 plbtime: Calculate broken-down time from continuous time for the current stream 1374===================================================================================== 1375 1376 plbtime (year, month, day, hour, min, sec, ctime); 1377 1378 Calculate broken-down time; ‘‘year’’, ‘‘month’’, ‘‘day’’, ‘‘hour’’, 1379‘‘min’’, ‘‘sec’’; from continuous time, ‘‘ctime’’ for the current 1380stream. This function is the inverse of ‘plctime’ (*note plctime; 1381Calculate continuous time from broken-down time for the current 1382stream::). 1383 1384 The PLplot definition of broken-down time is a calendar time that 1385completely ignores all time zone offsets, i.e., it is the user’s 1386responsibility to apply those offsets (if so desired) before using the 1387PLplot time API. By default broken-down time is defined using the 1388proleptic Gregorian calendar without the insertion of leap seconds and 1389continuous time is defined as the number of seconds since the Unix epoch 1390of 1970-01-01T00:00:00Z. However, other definitions of broken-down and 1391continuous time are possible, see ‘plconfigtime’ (*note plconfigtime; 1392Configure the transformation between continuous and broken-down time for 1393the current stream::). 1394 1395‘year’ (‘‘PLINT_NC_SCALAR’ (*note PLINT_NC_SCALAR-type::)’, output) 1396 Returned value of years with positive values corresponding to CE 1397 (i.e., 1 = 1 CE, etc.) and non-negative values corresponding to 1398 BCE (e.g., 0 = 1 BCE, -1 = 2 BCE, etc.) 1399 1400‘month’ (‘‘PLINT_NC_SCALAR’ (*note PLINT_NC_SCALAR-type::)’, output) 1401 Returned value of month within the year in the range from 0 1402 (January) to 11 (December). 1403 1404‘day’ (‘‘PLINT_NC_SCALAR’ (*note PLINT_NC_SCALAR-type::)’, output) 1405 Returned value of day within the month in the range from 1 to 31. 1406 1407‘hour’ (‘‘PLINT_NC_SCALAR’ (*note PLINT_NC_SCALAR-type::)’, output) 1408 Returned value of hour within the day in the range from 0 to 23. 1409 1410‘min’ (‘‘PLINT_NC_SCALAR’ (*note PLINT_NC_SCALAR-type::)’, output) 1411 Returned value of minute within the hour in the range from 0 to 59 1412 1413‘sec’ (‘‘PLFLT_NC_SCALAR’ (*note PLFLT_NC_SCALAR-type::)’, output) 1414 Returned value of second within the minute in range from 0. to 60. 1415 1416‘ctime’ (‘‘PLFLT’ (*note PLFLT-type::)’, input) 1417 Continuous time from which the broken-down time is calculated. 1418 1419 Redacted form: 1420 1421 • General: ‘plbtime(year, month, day, hour, min, sec, ctime)’ 1422 1423 This function is used in example 29. 1424 1425 1426File: plplotdoc.info, Node: plcalc_world; Calculate world coordinates and corresponding window index from relative device coordinates, Next: plclear; Clear current [sub]page, Prev: plbtime; Calculate broken-down time from continuous time for the current stream, Up: The Common API for PLplot 1427 142817.11 plcalc_world: Calculate world coordinates and corresponding window index from relative device coordinates 1429=============================================================================================================== 1430 1431 plcalc_world (rx, ry, wx, wy, window); 1432 1433 Calculate world coordinates, ‘‘wx’’ and ‘‘wy’’, and corresponding 1434‘‘window’’ index from relative device coordinates, ‘‘rx’’ and ‘‘ry’’. 1435 1436‘rx’ (‘‘PLFLT’ (*note PLFLT-type::)’, input) 1437 Input relative device coordinate (0.0-1.0) for the x coordinate. 1438 1439‘ry’ (‘‘PLFLT’ (*note PLFLT-type::)’, input) 1440 Input relative device coordinate (0.0-1.0) for the y coordinate. 1441 1442‘wx’ (‘‘PLFLT_NC_SCALAR’ (*note PLFLT_NC_SCALAR-type::)’, output) 1443 Returned value of the x world coordinate corresponding to the 1444 relative device coordinates ‘‘rx’’ and ‘‘ry’’. 1445 1446‘wy’ (‘‘PLFLT_NC_SCALAR’ (*note PLFLT_NC_SCALAR-type::)’, output) 1447 Returned value of the y world coordinate corresponding to the 1448 relative device coordinates ‘‘rx’’ and ‘‘ry’’. 1449 1450‘window’ (‘‘PLINT_NC_SCALAR’ (*note PLINT_NC_SCALAR-type::)’, output) 1451 Returned value of the last defined window index that corresponds to 1452 the input relative device coordinates (and the returned world 1453 coordinates). To give some background on the window index, for 1454 each page the initial window index is set to zero, and each time 1455 ‘plwind’ (*note plwind; Specify window::) is called within the 1456 page, world and device coordinates are stored for the window and 1457 the window index is incremented. Thus, for a simple page layout 1458 with non-overlapping viewports and one window per viewport, 1459 ‘‘window’’ corresponds to the viewport index (in the order which 1460 the viewport/windows were created) of the only viewport/window 1461 corresponding to ‘‘rx’’ and ‘‘ry’’. However, for more complicated 1462 layouts with potentially overlapping viewports and possibly more 1463 than one window (set of world coordinates) per viewport, ‘‘window’’ 1464 and the corresponding output world coordinates corresponds to the 1465 last window created that fulfills the criterion that the relative 1466 device coordinates are inside it. Finally, in all cases where the 1467 input relative device coordinates are not inside any 1468 viewport/window, then the returned value of the last defined window 1469 index is set to -1. 1470 1471 Redacted form: 1472 1473 • General: ‘plcalc_world(rx, ry, wx, wy, window)’ 1474 1475 This function is used in example 31. 1476 1477 1478File: plplotdoc.info, Node: plclear; Clear current [sub]page, Next: plcol0; Set color; cmap0, Prev: plcalc_world; Calculate world coordinates and corresponding window index from relative device coordinates, Up: The Common API for PLplot 1479 148017.12 plclear: Clear current (sub)page 1481====================================== 1482 1483 plclear (); 1484 1485 Clears the current page, effectively erasing everything that have 1486been drawn. This command only works with interactive drivers; if the 1487driver does not support this, the page is filled with the background 1488color in use. If the current page is divided into subpages, only the 1489current subpage is erased. The nth subpage can be selected with ‘pladv’ 1490(*note pladv; Advance the [sub-]page::)(n). 1491 1492 Redacted form: 1493 1494 • General: ‘plclear()’ 1495 1496 This function is not used in any examples. 1497 1498 1499File: plplotdoc.info, Node: plcol0; Set color; cmap0, Next: plcol1; Set color; cmap1, Prev: plclear; Clear current [sub]page, Up: The Common API for PLplot 1500 150117.13 plcol0: Set color, cmap0 1502============================== 1503 1504 plcol0 (icol0); 1505 1506 Sets the color index for cmap0 (see *note Color Map0::). 1507 1508‘icol0’ (‘‘PLINT’ (*note PLINT-type::)’, input) 1509 Integer representing the color. The defaults at present are (these 1510 may change): 1511 1512 0 black (default background) 1513 1 red (default foreground) 1514 2 yellow 1515 3 green 1516 4 aquamarine 1517 5 pink 1518 6 wheat 1519 7 grey 1520 8 brown 1521 9 blue 1522 10 BlueViolet 1523 11 cyan 1524 12 turquoise 1525 13 magenta 1526 14 salmon 1527 15 white 1528 1529 Use ‘plscmap0’ (*note plscmap0; Set cmap0 colors by 8-bit RGB 1530 values::) to change the entire cmap0 color palette and ‘plscol0’ 1531 (*note plscol0; Set 8-bit RGB values for given cmap0 color index::) 1532 to change an individual color in the cmap0 color palette. 1533 1534 Redacted form: ‘plcol0(icol0)’ 1535 1536 This function is used in examples 1-9, 11-16, 18-27, and 29. 1537 1538 1539File: plplotdoc.info, Node: plcol1; Set color; cmap1, Next: plcolorbar; Plot color bar for image; shade or gradient plots, Prev: plcol0; Set color; cmap0, Up: The Common API for PLplot 1540 154117.14 plcol1: Set color, cmap1 1542============================== 1543 1544 plcol1 (col1); 1545 1546 Sets the color for cmap1 (see *note Color Map1::). 1547 1548‘col1’ (‘‘PLFLT’ (*note PLFLT-type::)’, input) 1549 This value must be in the range (0.0-1.0) and is mapped to color 1550 using the continuous cmap1 palette which by default ranges from 1551 blue to the background color to red. The cmap1 palette can also be 1552 straightforwardly changed by the user with ‘plscmap1’ (*note 1553 plscmap1; Set opaque RGB cmap1 colors values::) or ‘plscmap1l’ 1554 (*note plscmap1l; Set cmap1 colors using a piece-wise linear 1555 relationship::). 1556 1557 Redacted form: ‘plcol1(col1)’ 1558 1559 This function is used in examples 12 and 21. 1560 1561 1562File: plplotdoc.info, Node: plcolorbar; Plot color bar for image; shade or gradient plots, Next: plconfigtime; Configure the transformation between continuous and broken-down time for the current stream, Prev: plcol1; Set color; cmap1, Up: The Common API for PLplot 1563 156417.15 plcolorbar: Plot color bar for image, shade or gradient plots 1565=================================================================== 1566 1567 plcolorbar (p_colorbar_width, p_colorbar_height, opt, position, x, 1568 y, x_length, y_length, bg_color, bb_color, bb_style, low_cap_color, 1569 high_cap_color, cont_color, cont_width, n_labels, label_opts, 1570 labels, naxes, axis_opts, ticks, sub_ticks, n_values, values); 1571 1572 Routine for creating a continuous color bar for image, shade, or 1573gradient plots. (See ‘pllegend’ (*note pllegend; Plot legend using 1574discretely annotated filled boxes; lines; and/or lines of symbols::) for 1575similar functionality for creating legends with discrete elements). The 1576arguments of plcolorbar provide control over the location and size of 1577the color bar as well as the location and characteristics of the 1578elements (most of which are optional) within that color bar. The 1579resulting color bar is clipped at the boundaries of the current subpage. 1580(N.B. the adopted coordinate system used for some of the parameters is 1581defined in the documentation of the ‘‘position’’ parameter.) 1582 1583‘p_colorbar_width’ (‘‘PLFLT_NC_SCALAR’ (*note PLFLT_NC_SCALAR-type::)’, output) 1584 Returned value of the labelled and decorated color bar width in 1585 adopted coordinates. 1586 1587‘p_colorbar_height’ (‘‘PLFLT_NC_SCALAR’ (*note PLFLT_NC_SCALAR-type::)’, output) 1588 Returned value of the labelled and decorated color bar height in 1589 adopted coordinates. 1590 1591‘opt’ (‘‘PLINT’ (*note PLINT-type::)’, input) 1592 ‘‘opt’’ contains bits controlling the overall color bar. The 1593 orientation (direction of the maximum value) of the color bar is 1594 specified with ‘PL_ORIENT_RIGHT’, ‘PL_ORIENT_TOP’, 1595 ‘PL_ORIENT_LEFT’, or ‘PL_ORIENT_BOTTOM’. If none of these bits are 1596 specified, the default orientation is toward the top if the 1597 colorbar is placed on the left or right of the viewport or toward 1598 the right if the colorbar is placed on the top or bottom of the 1599 viewport. If the ‘PL_COLORBAR_BACKGROUND’ bit is set, plot a 1600 (semitransparent) background for the color bar. If the 1601 ‘PL_COLORBAR_BOUNDING_BOX’ bit is set, plot a bounding box for the 1602 color bar. The type of color bar must be specified with one of 1603 ‘PL_COLORBAR_IMAGE’, ‘PL_COLORBAR_SHADE’, or 1604 ‘PL_COLORBAR_GRADIENT’. If more than one of those bits is set only 1605 the first one in the above list is honored. The position of the 1606 (optional) label/title can be specified with ‘PL_LABEL_RIGHT’, 1607 ‘PL_LABEL_TOP’, ‘PL_LABEL_LEFT’, or ‘PL_LABEL_BOTTOM’. If no label 1608 position bit is set then no label will be drawn. If more than one 1609 of this list of bits is specified, only the first one on the list 1610 is honored. End-caps for the color bar can added with 1611 ‘PL_COLORBAR_CAP_LOW’ and ‘PL_COLORBAR_CAP_HIGH’. If a particular 1612 color bar cap option is not specified then no cap will be drawn for 1613 that end. As a special case for ‘PL_COLORBAR_SHADE’, the option 1614 ‘PL_COLORBAR_SHADE_LABEL’ can be specified. If this option is 1615 provided then any tick marks and tick labels will be placed at the 1616 breaks between shaded segments. TODO: This should be expanded to 1617 support custom placement of tick marks and tick labels at custom 1618 value locations for any color bar type. 1619 1620‘position’ (‘‘PLINT’ (*note PLINT-type::)’, input) 1621 ‘‘position’’ contains bits which control the overall position of 1622 the color bar and the definition of the adopted coordinates used 1623 for positions just like what is done for the position argument for 1624 ‘pllegend’ (*note pllegend; Plot legend using discretely annotated 1625 filled boxes; lines; and/or lines of symbols::). However, note 1626 that the defaults for the position bits (see below) are different 1627 than the ‘pllegend’ (*note pllegend; Plot legend using discretely 1628 annotated filled boxes; lines; and/or lines of symbols::) case. 1629 The combination of the ‘PL_POSITION_LEFT’, ‘PL_POSITION_RIGHT’, 1630 ‘PL_POSITION_TOP’, ‘PL_POSITION_BOTTOM’, ‘PL_POSITION_INSIDE’, and 1631 ‘PL_POSITION_OUTSIDE’ bits specifies one of the 16 possible 1632 standard positions (the 4 corners and centers of the 4 sides for 1633 both the inside and outside cases) of the color bar relative to the 1634 adopted coordinate system. The corner positions are specified by 1635 the appropriate combination of two of the ‘PL_POSITION_LEFT’, 1636 ‘PL_POSITION_RIGHT’, ‘PL_POSITION_TOP’, and ‘PL_POSITION_BOTTOM’ 1637 bits while the sides are specified by a single value of one of 1638 those bits. The adopted coordinates are normalized viewport 1639 coordinates if the ‘PL_POSITION_VIEWPORT’ bit is set or normalized 1640 subpage coordinates if the ‘PL_POSITION_SUBPAGE’ bit is set. 1641 Default position bits: If none of ‘PL_POSITION_LEFT’, 1642 ‘PL_POSITION_RIGHT’, ‘PL_POSITION_TOP’, or ‘PL_POSITION_BOTTOM’ are 1643 set, then use ‘PL_POSITION_RIGHT’. If neither of 1644 ‘PL_POSITION_INSIDE’ or ‘PL_POSITION_OUTSIDE’ is set, use 1645 ‘PL_POSITION_OUTSIDE’. If neither of ‘PL_POSITION_VIEWPORT’ or 1646 ‘PL_POSITION_SUBPAGE’ is set, use ‘PL_POSITION_VIEWPORT’. 1647 1648‘x’ (‘‘PLFLT’ (*note PLFLT-type::)’, input) 1649 X offset of the color bar position in adopted coordinates from the 1650 specified standard position of the color bar. For positive x, the 1651 direction of motion away from the standard position is 1652 inward/outward from the standard corner positions or standard left 1653 or right positions if the 1654 ‘PL_POSITION_INSIDE’/‘PL_POSITION_OUTSIDE’ bit is set in 1655 ‘‘position’’. For the standard top or bottom positions, the 1656 direction of motion is toward positive X. 1657 1658‘y’ (‘‘PLFLT’ (*note PLFLT-type::)’, input) 1659 Y offset of the color bar position in adopted coordinates from the 1660 specified standard position of the color bar. For positive y, the 1661 direction of motion away from the standard position is 1662 inward/outward from the standard corner positions or standard top 1663 or bottom positions if the 1664 ‘PL_POSITION_INSIDE’/‘PL_POSITION_OUTSIDE’ bit is set in 1665 ‘‘position’’. For the standard left or right positions, the 1666 direction of motion is toward positive Y. 1667 1668‘x_length’ (‘‘PLFLT’ (*note PLFLT-type::)’, input) 1669 Length of the body of the color bar in the X direction in adopted 1670 coordinates. 1671 1672‘y_length’ (‘‘PLFLT’ (*note PLFLT-type::)’, input) 1673 Length of the body of the color bar in the Y direction in adopted 1674 coordinates. 1675 1676‘bg_color’ (‘‘PLINT’ (*note PLINT-type::)’, input) 1677 The cmap0 color of the background for the color bar 1678 (‘PL_COLORBAR_BACKGROUND’). 1679 1680‘bb_color’ (‘‘PLINT’ (*note PLINT-type::)’, input) 1681 The cmap0 color of the bounding-box line for the color bar 1682 (‘PL_COLORBAR_BOUNDING_BOX’). 1683 1684‘bb_style’ (‘‘PLINT’ (*note PLINT-type::)’, input) 1685 The ‘pllsty’ (*note pllsty; Select line style::) style number for 1686 the bounding-box line for the color bar (‘PL_COLORBAR_BACKGROUND’). 1687 1688‘low_cap_color’ (‘‘PLFLT’ (*note PLFLT-type::)’, input) 1689 The cmap1 color of the low-end color bar cap, if it is drawn 1690 (‘PL_COLORBAR_CAP_LOW’). 1691 1692‘high_cap_color’ (‘‘PLFLT’ (*note PLFLT-type::)’, input) 1693 The cmap1 color of the high-end color bar cap, if it is drawn 1694 (‘PL_COLORBAR_CAP_HIGH’). 1695 1696‘cont_color’ (‘‘PLINT’ (*note PLINT-type::)’, input) 1697 The cmap0 contour color for ‘PL_COLORBAR_SHADE’ plots. This is 1698 passed directly to ‘plshades’ (*note plshades; Shade regions on the 1699 basis of value::), so it will be interpreted according to the 1700 design of ‘plshades’ (*note plshades; Shade regions on the basis of 1701 value::). 1702 1703‘cont_width’ (‘‘PLFLT’ (*note PLFLT-type::)’, input) 1704 Contour width for ‘PL_COLORBAR_SHADE’ plots. This is passed 1705 directly to ‘plshades’ (*note plshades; Shade regions on the basis 1706 of value::), so it will be interpreted according to the design of 1707 ‘plshades’ (*note plshades; Shade regions on the basis of value::). 1708 1709‘n_labels’ (‘‘PLINT’ (*note PLINT-type::)’, input) 1710 Number of labels to place around the color bar. 1711 1712‘label_opts’ (‘‘PLINT_VECTOR’ (*note PLINT_VECTOR-type::)’, input) 1713 A vector of options for each of ‘n_labels’ labels. 1714 1715‘labels’ (‘‘PLCHAR_MATRIX’ (*note PLCHAR_MATRIX-type::)’, input) 1716 A vector of ‘n_labels’ UTF-8 character strings containing the 1717 labels for the color bar. Ignored if no label position is 1718 specified with one of the ‘PL_COLORBAR_LABEL_RIGHT’, 1719 ‘PL_COLORBAR_LABEL_TOP’, ‘PL_COLORBAR_LABEL_LEFT’, or 1720 ‘PL_COLORBAR_LABEL_BOTTOM’ bits in the corresponding label_opts 1721 field. 1722 1723‘n_axes’ (‘‘PLINT’ (*note PLINT-type::)’, input) 1724 Number of axis definitions provided. This value must be greater 1725 than 0. It is typically 1 (numerical axis labels are provided for 1726 one of the long edges of the color bar), but it can be larger if 1727 multiple numerical axis labels for the long edges of the color bar 1728 are desired. 1729 1730‘axis_opts’ (‘‘PLCHAR_MATRIX’ (*note PLCHAR_MATRIX-type::)’, input) 1731 A vector of ‘n_axes’ ascii character strings containing options 1732 (interpreted as for ‘plbox’ (*note plbox; Draw a box with axes; 1733 etc::)) for the color bar’s axis definitions. 1734 1735‘ticks’ (‘‘PLFLT_VECTOR’ (*note PLFLT_VECTOR-type::)’, input) 1736 A vector of n_axes values of the spacing of the major tick marks 1737 (interpreted as for ‘plbox’ (*note plbox; Draw a box with axes; 1738 etc::)) for the color bar’s axis definitions. 1739 1740‘sub_ticks’ (‘‘PLINT_VECTOR’ (*note PLINT_VECTOR-type::)’, input) 1741 A vector of n_axes values of the number of subticks (interpreted as 1742 for ‘plbox’ (*note plbox; Draw a box with axes; etc::)) for the 1743 color bar’s axis definitions. 1744 1745‘n_values’ (‘‘PLINT_VECTOR’ (*note PLINT_VECTOR-type::)’, input) 1746 A vector containing the number of elements in each of the 1747 ‘‘n_axes’’ rows of the ‘‘values’’ matrix. 1748 1749‘values’ (‘‘PLFLT_MATRIX’ (*note PLFLT_MATRIX-type::)’, input) 1750 A matrix containing the numeric values for the data range 1751 represented by the color bar. For a row index of ‘‘i_axis’’ (where 1752 0 < ‘‘i_axis’’ < ‘‘n_axes’’), the number of elements in the row is 1753 specified by ‘‘n_values’’[‘‘i_axis’’]. For ‘PL_COLORBAR_IMAGE’ and 1754 ‘PL_COLORBAR_GRADIENT’ the number of elements is 2, and the 1755 corresponding row elements of the ‘‘values’’ matrix are the minimum 1756 and maximum value represented by the colorbar. For 1757 ‘PL_COLORBAR_SHADE’, the number and values of the elements of a row 1758 of the ‘‘values’’ matrix is interpreted the same as the ‘‘nlevel’’ 1759 and ‘‘clevel’’ arguments of ‘plshades’ (*note plshades; Shade 1760 regions on the basis of value::). 1761 1762 Redacted form: ‘plcolorbar(p_colorbar_width, p_colorbar_height, opt, 1763position, x, y, x_length, y_length, bg_color, bb_color, bb_style, 1764low_cap_color, high_cap_color, cont_color, cont_width, label_opts, 1765labels, axis_opts, ticks, sub_ticks, values)’ 1766 1767 This function is used in examples 16 and 33. 1768 1769 1770File: plplotdoc.info, Node: plconfigtime; Configure the transformation between continuous and broken-down time for the current stream, Next: plcont; Contour plot, Prev: plcolorbar; Plot color bar for image; shade or gradient plots, Up: The Common API for PLplot 1771 177217.16 plconfigtime: Configure the transformation between continuous and broken-down time for the current stream 1773=============================================================================================================== 1774 1775 plconfigtime (scale, offset1, offset2, ccontrol, ifbtime_offset, 1776 year, month, day, hour, min, sec); 1777 1778 Configure the transformation between continuous and broken-down time 1779for the current stream. This transformation is used by both ‘ plbtime’ 1780(*note plbtime; Calculate broken-down time from continuous time for the 1781current stream::) and ‘plctime’ (*note plctime; Calculate continuous 1782time from broken-down time for the current stream::). 1783 1784‘scale’ (‘‘PLFLT’ (*note PLFLT-type::)’, input) 1785 The number of days per continuous time unit. As a special case, if 1786 ‘scale’ is 0., then all other arguments are ignored, and the result 1787 (the default used by PLplot) is the equivalent of a call to 1788 plconfigtime(1./86400., 0., 0., 0x0, 1, 1970, 0, 1, 0, 0, 0.). 1789 That is, for this special case broken-down time is calculated with 1790 the proleptic Gregorian calendar with no leap seconds inserted, and 1791 the continuous time is defined as the number of seconds since the 1792 Unix epoch of 1970-01-01T00:00:00Z. 1793 1794‘offset1’ (‘‘PLFLT’ (*note PLFLT-type::)’, input) 1795 If ‘ifbtime_offset’ is true, the parameters ‘offset1’ and ‘offset2’ 1796 are completely ignored. Otherwise, the sum of these parameters 1797 (with units in days) specify the epoch of the continuous time 1798 relative to the MJD epoch corresponding to the Gregorian calendar 1799 date of 1858-11-17T00:00:00Z or JD = 2400000.5. Two PLFLT numbers 1800 are used to specify the origin to allow users (by specifying 1801 ‘offset1’ as an integer that can be exactly represented by a 1802 floating-point variable and specifying ‘offset2’ as a number in the 1803 range from 0. to 1) the chance to minimize the numerical errors of 1804 the continuous time representation. 1805 1806‘offset2’ (‘‘PLFLT’ (*note PLFLT-type::)’, input) 1807 See documentation of ‘offset1’. 1808 1809‘ccontrol’ (‘‘PLINT’ (*note PLINT-type::)’, input) 1810 ‘ccontrol’ contains bits controlling the transformation. If the 1811 0x1 bit is set, then the proleptic Julian calendar is used for 1812 broken-down time rather than the proleptic Gregorian calendar. If 1813 the 0x2 bit is set, then leap seconds that have been historically 1814 used to define UTC are inserted into the broken-down time. Other 1815 possibilities for additional control bits for ccontrol exist such 1816 as making the historical time corrections in the broken-down time 1817 corresponding to ET (ephemeris time) or making the (slightly 1818 non-constant) corrections from international atomic time (TAI) to 1819 what astronomers define as terrestrial time (TT). But those 1820 additional possibilities have not been implemented yet in the 1821 qsastime library (one of the PLplot utility libraries). 1822 1823‘ifbtime_offset’ (‘‘PLBOOL’ (*note PLBOOL-type::)’, input) 1824 ‘ifbtime_offset’ controls how the epoch of the continuous time 1825 scale is specified by the user. If ‘ifbtime_offset’ is false, then 1826 ‘offset1’ and ‘offset2’ are used to specify the epoch, and the 1827 following broken-down time parameters are completely ignored. If 1828 ‘ifbtime_offset’ is true, then ‘offset1’ and ‘offset2’ are 1829 completely ignored, and the following broken-down time parameters 1830 are used to specify the epoch. 1831 1832‘year’ (‘‘PLINT’ (*note PLINT-type::)’, input) 1833 Year of epoch. 1834 1835‘month’ (‘‘PLINT’ (*note PLINT-type::)’, input) 1836 Month of epoch in range from 0 (January) to 11 (December). 1837 1838‘day’ (‘‘PLINT’ (*note PLINT-type::)’, input) 1839 Day of epoch in range from 1 to 31. 1840 1841‘hour’ (‘‘PLINT’ (*note PLINT-type::)’, input) 1842 Hour of epoch in range from 0 to 23 1843 1844‘min’ (‘‘PLINT’ (*note PLINT-type::)’, input) 1845 Minute of epoch in range from 0 to 59. 1846 1847‘sec’ (‘‘PLFLT’ (*note PLFLT-type::)’, input) 1848 Second of epoch in range from 0. to 60. 1849 1850 Redacted form: 1851 1852 • General: ‘plconfigtime(scale, offset1, offset2, ccontrol, 1853 ifbtime_offset, year, month, day, hour, min, sec)’ 1854 1855 This function is used in example 29. 1856 1857 1858File: plplotdoc.info, Node: plcont; Contour plot, Next: plcpstrm; Copy state parameters from the reference stream to the current stream, Prev: plconfigtime; Configure the transformation between continuous and broken-down time for the current stream, Up: The Common API for PLplot 1859 186017.17 plcont: Contour plot 1861========================== 1862 1863 plcont (f, nx, ny, kx, lx, ky, ly, clevel, nlevel, pltr, 1864 pltr_data); 1865 1866 Draws a contour plot of the data in ‘‘f’[‘nx’][‘ny’]’, using the 1867‘‘nlevel’’ contour levels specified by ‘‘clevel’’. Only the region of 1868the matrix from ‘‘kx’’ to ‘‘lx’’ and from ‘‘ky’’ to ‘‘ly’’ is plotted 1869out where all these index ranges are interpreted as one-based for 1870historical reasons. A transformation routine pointed to by ‘‘pltr’’ 1871with a generic pointer ‘‘pltr_data’’ for additional data required by the 1872transformation routine is used to map indices within the matrix to the 1873world coordinates. 1874 1875‘f’ (‘‘PLFLT_MATRIX’ (*note PLFLT_MATRIX-type::)’, input) 1876 A matrix containing data to be contoured. 1877 1878‘nx, ny’ (‘‘PLINT’ (*note PLINT-type::)’, input) 1879 The dimensions of the matrix ‘‘f’’. 1880 1881‘kx, lx’ (‘‘PLINT’ (*note PLINT-type::)’, input) 1882 Range of ‘x’ indices to consider where ‘0 ≤ kx-1 < lx-1 < nx’. 1883 Values of ‘kx’ and ‘lx’ are one-based rather than zero-based for 1884 historical backwards-compatibility reasons. 1885 1886‘ky, ly’ (‘‘PLINT’ (*note PLINT-type::)’, input) 1887 Range of ‘y’ indices to consider where ‘0 ≤ ky-1 < ly-1 < ny’. 1888 Values of ‘ky’ and ‘ly’ are one-based rather than zero-based for 1889 historical backwards-compatibility reasons. 1890 1891‘clevel’ (‘‘PLFLT_VECTOR’ (*note PLFLT_VECTOR-type::)’, input) 1892 A vector specifying the levels at which to draw contours. 1893 1894‘nlevel’ (‘‘PLINT’ (*note PLINT-type::)’, input) 1895 Number of contour levels to draw. 1896 1897‘pltr’ (‘‘PLTRANSFORM_callback’ (*note PLTRANSFORM_callback-type::)’, input) 1898 A callback function that defines the transformation between the 1899 zero-based indices of the matrix ‘‘f’’ and the world coordinates. 1900 1901 For the C case, transformation functions are provided in the PLplot 1902 library: ‘pltr0’ (*note pltr0; Identity transformation for matrix 1903 index to world coordinate mapping::) for the identity mapping, and 1904 ‘pltr1’ (*note pltr1; Linear interpolation for matrix index to 1905 world coordinate mapping using singly dimensioned coordinate 1906 arrays::) and ‘pltr2’ (*note pltr2; Linear interpolation for grid 1907 to world mapping using doubly dimensioned coordinate arrays 1908 [row-major order as per normal C 2d arrays]::) for arbitrary 1909 mappings respectively defined by vectors and matrices. In 1910 addition, C callback routines for the transformation can be 1911 supplied by the user such as the ‘mypltr’ function in 1912 ‘examples/c/x09c.c’ which provides a general linear transformation 1913 between index coordinates and world coordinates. 1914 1915 For languages other than C you should consult *note Supported 1916 computer languages: Supported computer languages. for the details 1917 concerning how ‘PLTRANSFORM_callback’ (*note 1918 PLTRANSFORM_callback-type::) arguments are interfaced. However, in 1919 general, a particular pattern of callback-associated arguments such 1920 as a ‘tr’ vector with 6 elements; ‘xg’ and ‘yg’ vectors; or ‘xg’ 1921 and ‘yg’ matrices are respectively interfaced to a 1922 linear-transformation routine similar to the above ‘mypltr’ 1923 function; ‘pltr1’ (*note pltr1; Linear interpolation for matrix 1924 index to world coordinate mapping using singly dimensioned 1925 coordinate arrays::); and ‘pltr2’ (*note pltr2; Linear 1926 interpolation for grid to world mapping using doubly dimensioned 1927 coordinate arrays [row-major order as per normal C 2d arrays]::). 1928 Furthermore, some of our more sophisticated bindings (see, e.g., 1929 *note Fortran Language::) support native language callbacks for 1930 handling index to world-coordinate transformations. Examples of 1931 these various approaches are given in ‘examples/<language>x09*’, 1932 ‘examples/<language>x16*’, ‘examples/<language>x20*’, 1933 ‘examples/<language>x21*’, and ‘examples/<language>x22*’, for all 1934 our supported languages. 1935 1936‘pltr_data’ (‘‘PLPointer’ (*note PLPointer-type::)’, input) 1937 Extra parameter to help pass information to ‘pltr0’ (*note pltr0; 1938 Identity transformation for matrix index to world coordinate 1939 mapping::), ‘pltr1’ (*note pltr1; Linear interpolation for matrix 1940 index to world coordinate mapping using singly dimensioned 1941 coordinate arrays::), ‘pltr2’ (*note pltr2; Linear interpolation 1942 for grid to world mapping using doubly dimensioned coordinate 1943 arrays [row-major order as per normal C 2d arrays]::), or whatever 1944 callback routine that is externally supplied. 1945 1946 Redacted form: ‘plcont(f, kx, lx, ky, ly, clevel, pltr, pltr_data)’ 1947where (see above discussion) the ‘pltr, pltr_data’ callback arguments 1948are sometimes replaced by a ‘tr’ vector with 6 elements; ‘xg’ and ‘yg’ 1949vectors; or ‘xg’ and ‘yg’ matrices. 1950 1951 This function is used in examples 9, 14, 16, and 22. 1952 1953 1954File: plplotdoc.info, Node: plcpstrm; Copy state parameters from the reference stream to the current stream, Next: plctime; Calculate continuous time from broken-down time for the current stream, Prev: plcont; Contour plot, Up: The Common API for PLplot 1955 195617.18 plcpstrm: Copy state parameters from the reference stream to the current stream 1957===================================================================================== 1958 1959 plcpstrm (iplsr, flags); 1960 1961 Copies state parameters from the reference stream to the current 1962stream. Tell driver interface to map device coordinates unless ‘‘flags’ 1963== 1’. 1964 1965 This function is used for making save files of selected plots (e.g. 1966from the TK driver). After initializing, you can get a copy of the 1967current plot to the specified device by switching to this stream and 1968issuing a ‘plcpstrm’ (*note plcpstrm; Copy state parameters from the 1969reference stream to the current stream::) and a ‘plreplot’ (*note 1970plreplot; Replays contents of plot buffer to current device/file::), 1971with calls to ‘plbop’ (*note plbop; Begin a new page::) and ‘pleop’ 1972(*note pleop; Eject current page::) as appropriate. The plot buffer 1973must have previously been enabled (done automatically by some display 1974drivers, such as X). 1975 1976‘iplsr’ (‘‘PLINT’ (*note PLINT-type::)’, input) 1977 Number of reference stream. 1978 1979‘flags’ (‘‘PLBOOL’ (*note PLBOOL-type::)’, input) 1980 If ‘‘flags’’ is set to true the device coordinates are _not_ copied 1981 from the reference to current stream. 1982 1983 Redacted form: ‘plcpstrm(iplsr, flags)’ 1984 1985 This function is used in example 1,20. 1986 1987 1988File: plplotdoc.info, Node: plctime; Calculate continuous time from broken-down time for the current stream, Next: plend; End plotting session, Prev: plcpstrm; Copy state parameters from the reference stream to the current stream, Up: The Common API for PLplot 1989 199017.19 plctime: Calculate continuous time from broken-down time for the current stream 1991===================================================================================== 1992 1993 plctime (year, month, day, hour, min, sec, ctime); 1994 1995 Calculate continuous time, ‘‘ctime’’, from broken-down time for the 1996current stream. The broken-down time is specified by the following 1997parameters: ‘‘year’’, ‘‘month’’, ‘‘day’’, ‘‘hour’’, ‘‘min’’, and 1998‘‘sec’’. This function is the inverse of ‘ plbtime’ (*note plbtime; 1999Calculate broken-down time from continuous time for the current 2000stream::). 2001 2002 The PLplot definition of broken-down time is a calendar time that 2003completely ignores all time zone offsets, i.e., it is the user’s 2004responsibility to apply those offsets (if so desired) before using the 2005PLplot time API. By default broken-down time is defined using the 2006proleptic Gregorian calendar without the insertion of leap seconds and 2007continuous time is defined as the number of seconds since the Unix epoch 2008of 1970-01-01T00:00:00Z. However, other definitions of broken-down and 2009continuous time are possible, see ‘plconfigtime’ (*note plconfigtime; 2010Configure the transformation between continuous and broken-down time for 2011the current stream::) which specifies that transformation for the 2012current stream. 2013 2014‘year’ (‘‘PLINT’ (*note PLINT-type::)’, input) 2015 Input year. 2016 2017‘month’ (‘‘PLINT’ (*note PLINT-type::)’, input) 2018 Input month in range from 0 (January) to 11 (December). 2019 2020‘day’ (‘‘PLINT’ (*note PLINT-type::)’, input) 2021 Input day in range from 1 to 31. 2022 2023‘hour’ (‘‘PLINT’ (*note PLINT-type::)’, input) 2024 Input hour in range from 0 to 23 2025 2026‘min’ (‘‘PLINT’ (*note PLINT-type::)’, input) 2027 Input minute in range from 0 to 59. 2028 2029‘sec’ (‘‘PLFLT’ (*note PLFLT-type::)’, input) 2030 Input second in range from 0. to 60. 2031 2032‘ctime’ (‘‘PLFLT_NC_SCALAR’ (*note PLFLT_NC_SCALAR-type::)’, output) 2033 Returned value of the continuous time calculated from the 2034 broken-down time specified by the previous parameters. 2035 2036 Redacted form: 2037 2038 • General: ‘plctime(year, month, day, hour, min, sec, ctime)’ 2039 2040 This function is used in example 29. 2041 2042 2043File: plplotdoc.info, Node: plend; End plotting session, Next: plend1; End plotting session for current stream, Prev: plctime; Calculate continuous time from broken-down time for the current stream, Up: The Common API for PLplot 2044 204517.20 plend: End plotting session 2046================================= 2047 2048 plend (); 2049 2050 Ends a plotting session, tidies up all the output files, switches 2051interactive devices back into text mode and frees up any memory that was 2052allocated. Must be called before end of program. 2053 2054 By default, PLplot’s interactive devices (Xwin, TK, etc.) go into a 2055wait state after a call to plend or other functions which trigger the 2056end of a plot page. To avoid this, use the ‘plspause’ (*note plspause; 2057Set the pause [on end-of-page] status::) function. 2058 2059 Redacted form: ‘plend()’ 2060 2061 This function is used in all of the examples. 2062 2063 2064File: plplotdoc.info, Node: plend1; End plotting session for current stream, Next: plenv0; Same as plenv but if in multiplot mode does not advance the subpage; instead clears it, Prev: plend; End plotting session, Up: The Common API for PLplot 2065 206617.21 plend1: End plotting session for current stream 2067===================================================== 2068 2069 plend1 (); 2070 2071 Ends a plotting session for the current output stream only. See 2072‘plsstrm’ (*note plsstrm; Set current output stream::) for more info. 2073 2074 Redacted form: ‘plend1()’ 2075 2076 This function is used in examples 1 and 20. 2077 2078 2079File: plplotdoc.info, Node: plenv0; Same as plenv but if in multiplot mode does not advance the subpage; instead clears it, Next: plenv; Set up standard window and draw box, Prev: plend1; End plotting session for current stream, Up: The Common API for PLplot 2080 208117.22 plenv0: Same as ‘plenv’ but if in multiplot mode does not advance the subpage, instead clears it 2082====================================================================================================== 2083 2084 plenv0 (xmin, xmax, ymin, ymax, just, axis); 2085 2086 Sets up plotter environment for simple graphs by calling ‘pladv’ 2087(*note pladv; Advance the [sub-]page::) and setting up viewport and 2088window to sensible default values. ‘plenv0’ (*note plenv0; Same as 2089plenv but if in multiplot mode does not advance the subpage; instead 2090clears it::) leaves a standard margin (left-hand margin of eight 2091character heights, and a margin around the other three sides of five 2092character heights) around most graphs for axis labels and a title. When 2093these defaults are not suitable, use the individual routines ‘plvpas’ 2094(*note plvpas; Specify viewport using coordinates and aspect ratio::), 2095‘plvpor’ (*note plvpor; Specify viewport using normalized subpage 2096coordinates::), or ‘plvasp’ (*note plvasp; Specify viewport using aspect 2097ratio only::) for setting up the viewport, ‘plwind’ (*note plwind; 2098Specify window::) for defining the window, and ‘plbox’ (*note plbox; 2099Draw a box with axes; etc::) for drawing the box. 2100 2101‘xmin’ (‘‘PLFLT’ (*note PLFLT-type::)’, input) 2102 Value of x at left-hand edge of window (in world coordinates). 2103 2104‘xmax’ (‘‘PLFLT’ (*note PLFLT-type::)’, input) 2105 Value of x at right-hand edge of window (in world coordinates). 2106 2107‘ymin’ (‘‘PLFLT’ (*note PLFLT-type::)’, input) 2108 Value of y at bottom edge of window (in world coordinates). 2109 2110‘ymax’ (‘‘PLFLT’ (*note PLFLT-type::)’, input) 2111 Value of y at top edge of window (in world coordinates). 2112 2113‘just’ (‘‘PLINT’ (*note PLINT-type::)’, input) 2114 Controls how the axes will be scaled: 2115 2116 • ‘-1’: the scales will not be set, the user must set up the 2117 scale before calling ‘plenv0’ (*note plenv0; Same as plenv but 2118 if in multiplot mode does not advance the subpage; instead 2119 clears it::) using ‘plsvpa’ (*note plsvpa; Specify viewport in 2120 absolute coordinates::), ‘plvasp’ (*note plvasp; Specify 2121 viewport using aspect ratio only::) or other. 2122 2123 • ‘0’: the x and y axes are scaled independently to use as much 2124 of the screen as possible. 2125 2126 • ‘1’: the scales of the x and y axes are made equal. 2127 2128 • ‘2’: the axis of the x and y axes are made equal, and the plot 2129 box will be square. 2130 2131‘axis’ (‘‘PLINT’ (*note PLINT-type::)’, input) 2132 Controls drawing of the box around the plot: 2133 2134 • ‘-2’: draw no box, no tick marks, no numeric tick labels, no 2135 axes. 2136 2137 • ‘-1’: draw box only. 2138 2139 • ‘0’: draw box, ticks, and numeric tick labels. 2140 2141 • ‘1’: also draw coordinate axes at ‘x=0’ and ‘y=0’. 2142 2143 • ‘2’: also draw a grid at major tick positions in both 2144 coordinates. 2145 2146 • ‘3’: also draw a grid at minor tick positions in both 2147 coordinates. 2148 2149 • ‘10’: same as 0 except logarithmic ‘x’ tick marks. (The ‘x’ 2150 data have to be converted to logarithms separately.) 2151 2152 • ‘11’: same as 1 except logarithmic ‘x’ tick marks. (The ‘x’ 2153 data have to be converted to logarithms separately.) 2154 2155 • ‘12’: same as 2 except logarithmic ‘x’ tick marks. (The ‘x’ 2156 data have to be converted to logarithms separately.) 2157 2158 • ‘13’: same as 3 except logarithmic ‘x’ tick marks. (The ‘x’ 2159 data have to be converted to logarithms separately.) 2160 2161 • ‘20’: same as 0 except logarithmic ‘y’ tick marks. (The ‘y’ 2162 data have to be converted to logarithms separately.) 2163 2164 • ‘21’: same as 1 except logarithmic ‘y’ tick marks. (The ‘y’ 2165 data have to be converted to logarithms separately.) 2166 2167 • ‘22’: same as 2 except logarithmic ‘y’ tick marks. (The ‘y’ 2168 data have to be converted to logarithms separately.) 2169 2170 • ‘23’: same as 3 except logarithmic ‘y’ tick marks. (The ‘y’ 2171 data have to be converted to logarithms separately.) 2172 2173 • ‘30’: same as 0 except logarithmic ‘x’ and ‘y’ tick marks. 2174 (The ‘x’ and ‘y’ data have to be converted to logarithms 2175 separately.) 2176 2177 • ‘31’: same as 1 except logarithmic ‘x’ and ‘y’ tick marks. 2178 (The ‘x’ and ‘y’ data have to be converted to logarithms 2179 separately.) 2180 2181 • ‘32’: same as 2 except logarithmic ‘x’ and ‘y’ tick marks. 2182 (The ‘x’ and ‘y’ data have to be converted to logarithms 2183 separately.) 2184 2185 • ‘33’: same as 3 except logarithmic ‘x’ and ‘y’ tick marks. 2186 (The ‘x’ and ‘y’ data have to be converted to logarithms 2187 separately.) 2188 2189 • ‘40’: same as 0 except date / time ‘x’ labels. 2190 2191 • ‘41’: same as 1 except date / time ‘x’ labels. 2192 2193 • ‘42’: same as 2 except date / time ‘x’ labels. 2194 2195 • ‘43’: same as 3 except date / time ‘x’ labels. 2196 2197 • ‘50’: same as 0 except date / time ‘y’ labels. 2198 2199 • ‘51’: same as 1 except date / time ‘y’ labels. 2200 2201 • ‘52’: same as 2 except date / time ‘y’ labels. 2202 2203 • ‘53’: same as 3 except date / time ‘y’ labels. 2204 2205 • ‘60’: same as 0 except date / time ‘x’ and ‘y’ labels. 2206 2207 • ‘61’: same as 1 except date / time ‘x’ and ‘y’ labels. 2208 2209 • ‘62’: same as 2 except date / time ‘x’ and ‘y’ labels. 2210 2211 • ‘63’: same as 3 except date / time ‘x’ and ‘y’ labels. 2212 2213 • ‘70’: same as 0 except custom ‘x’ and ‘y’ labels. 2214 2215 • ‘71’: same as 1 except custom ‘x’ and ‘y’ labels. 2216 2217 • ‘72’: same as 2 except custom ‘x’ and ‘y’ labels. 2218 2219 • ‘73’: same as 3 except custom ‘x’ and ‘y’ labels. 2220 2221 Redacted form: ‘plenv0(xmin, xmax, ymin, ymax, just, axis)’ 2222 2223 This function is used in example 21. 2224 2225 2226File: plplotdoc.info, Node: plenv; Set up standard window and draw box, Next: pleop; Eject current page, Prev: plenv0; Same as plenv but if in multiplot mode does not advance the subpage; instead clears it, Up: The Common API for PLplot 2227 222817.23 plenv: Set up standard window and draw box 2229================================================ 2230 2231 plenv (xmin, xmax, ymin, ymax, just, axis); 2232 2233 Sets up plotter environment for simple graphs by calling ‘pladv’ 2234(*note pladv; Advance the [sub-]page::) and setting up viewport and 2235window to sensible default values. ‘plenv’ (*note plenv; Set up 2236standard window and draw box::) leaves a standard margin (left-hand 2237margin of eight character heights, and a margin around the other three 2238sides of five character heights) around most graphs for axis labels and 2239a title. When these defaults are not suitable, use the individual 2240routines ‘plvpas’ (*note plvpas; Specify viewport using coordinates and 2241aspect ratio::), ‘plvpor’ (*note plvpor; Specify viewport using 2242normalized subpage coordinates::), or ‘plvasp’ (*note plvasp; Specify 2243viewport using aspect ratio only::) for setting up the viewport, 2244‘plwind’ (*note plwind; Specify window::) for defining the window, and 2245‘plbox’ (*note plbox; Draw a box with axes; etc::) for drawing the box. 2246 2247‘xmin’ (‘‘PLFLT’ (*note PLFLT-type::)’, input) 2248 Value of x at left-hand edge of window (in world coordinates). 2249 2250‘xmax’ (‘‘PLFLT’ (*note PLFLT-type::)’, input) 2251 Value of x at right-hand edge of window (in world coordinates). 2252 2253‘ymin’ (‘‘PLFLT’ (*note PLFLT-type::)’, input) 2254 Value of y at bottom edge of window (in world coordinates). 2255 2256‘ymax’ (‘‘PLFLT’ (*note PLFLT-type::)’, input) 2257 Value of y at top edge of window (in world coordinates). 2258 2259‘just’ (‘‘PLINT’ (*note PLINT-type::)’, input) 2260 Controls how the axes will be scaled: 2261 2262 • ‘-1’: the scales will not be set, the user must set up the 2263 scale before calling ‘plenv’ (*note plenv; Set up standard 2264 window and draw box::) using ‘plsvpa’ (*note plsvpa; Specify 2265 viewport in absolute coordinates::), ‘plvasp’ (*note plvasp; 2266 Specify viewport using aspect ratio only::) or other. 2267 2268 • ‘0’: the x and y axes are scaled independently to use as much 2269 of the screen as possible. 2270 2271 • ‘1’: the scales of the x and y axes are made equal. 2272 2273 • ‘2’: the axis of the x and y axes are made equal, and the plot 2274 box will be square. 2275 2276‘axis’ (‘‘PLINT’ (*note PLINT-type::)’, input) 2277 Controls drawing of the box around the plot: 2278 2279 • ‘-2’: draw no box, no tick marks, no numeric tick labels, no 2280 axes. 2281 2282 • ‘-1’: draw box only. 2283 2284 • ‘0’: draw box, ticks, and numeric tick labels. 2285 2286 • ‘1’: also draw coordinate axes at ‘x=0’ and ‘y=0’. 2287 2288 • ‘2’: also draw a grid at major tick positions in both 2289 coordinates. 2290 2291 • ‘3’: also draw a grid at minor tick positions in both 2292 coordinates. 2293 2294 • ‘10’: same as 0 except logarithmic ‘x’ tick marks. (The ‘x’ 2295 data have to be converted to logarithms separately.) 2296 2297 • ‘11’: same as 1 except logarithmic ‘x’ tick marks. (The ‘x’ 2298 data have to be converted to logarithms separately.) 2299 2300 • ‘12’: same as 2 except logarithmic ‘x’ tick marks. (The ‘x’ 2301 data have to be converted to logarithms separately.) 2302 2303 • ‘13’: same as 3 except logarithmic ‘x’ tick marks. (The ‘x’ 2304 data have to be converted to logarithms separately.) 2305 2306 • ‘20’: same as 0 except logarithmic ‘y’ tick marks. (The ‘y’ 2307 data have to be converted to logarithms separately.) 2308 2309 • ‘21’: same as 1 except logarithmic ‘y’ tick marks. (The ‘y’ 2310 data have to be converted to logarithms separately.) 2311 2312 • ‘22’: same as 2 except logarithmic ‘y’ tick marks. (The ‘y’ 2313 data have to be converted to logarithms separately.) 2314 2315 • ‘23’: same as 3 except logarithmic ‘y’ tick marks. (The ‘y’ 2316 data have to be converted to logarithms separately.) 2317 2318 • ‘30’: same as 0 except logarithmic ‘x’ and ‘y’ tick marks. 2319 (The ‘x’ and ‘y’ data have to be converted to logarithms 2320 separately.) 2321 2322 • ‘31’: same as 1 except logarithmic ‘x’ and ‘y’ tick marks. 2323 (The ‘x’ and ‘y’ data have to be converted to logarithms 2324 separately.) 2325 2326 • ‘32’: same as 2 except logarithmic ‘x’ and ‘y’ tick marks. 2327 (The ‘x’ and ‘y’ data have to be converted to logarithms 2328 separately.) 2329 2330 • ‘33’: same as 3 except logarithmic ‘x’ and ‘y’ tick marks. 2331 (The ‘x’ and ‘y’ data have to be converted to logarithms 2332 separately.) 2333 2334 • ‘40’: same as 0 except date / time ‘x’ labels. 2335 2336 • ‘41’: same as 1 except date / time ‘x’ labels. 2337 2338 • ‘42’: same as 2 except date / time ‘x’ labels. 2339 2340 • ‘43’: same as 3 except date / time ‘x’ labels. 2341 2342 • ‘50’: same as 0 except date / time ‘y’ labels. 2343 2344 • ‘51’: same as 1 except date / time ‘y’ labels. 2345 2346 • ‘52’: same as 2 except date / time ‘y’ labels. 2347 2348 • ‘53’: same as 3 except date / time ‘y’ labels. 2349 2350 • ‘60’: same as 0 except date / time ‘x’ and ‘y’ labels. 2351 2352 • ‘61’: same as 1 except date / time ‘x’ and ‘y’ labels. 2353 2354 • ‘62’: same as 2 except date / time ‘x’ and ‘y’ labels. 2355 2356 • ‘63’: same as 3 except date / time ‘x’ and ‘y’ labels. 2357 2358 • ‘70’: same as 0 except custom ‘x’ and ‘y’ labels. 2359 2360 • ‘71’: same as 1 except custom ‘x’ and ‘y’ labels. 2361 2362 • ‘72’: same as 2 except custom ‘x’ and ‘y’ labels. 2363 2364 • ‘73’: same as 3 except custom ‘x’ and ‘y’ labels. 2365 2366 Redacted form: ‘plenv(xmin, xmax, ymin, ymax, just, axis)’ 2367 2368 This function is used in example 1,3,9,13,14,19-22,29. 2369 2370 2371File: plplotdoc.info, Node: pleop; Eject current page, Next: plerrx; Draw error bars in x direction, Prev: plenv; Set up standard window and draw box, Up: The Common API for PLplot 2372 237317.24 pleop: Eject current page 2374=============================== 2375 2376 pleop (); 2377 2378 Clears the graphics screen of an interactive device, or ejects a page 2379on a plotter. See ‘plbop’ (*note plbop; Begin a new page::) for more 2380information. 2381 2382 Redacted form: ‘pleop()’ 2383 2384 This function is used in example 2,14. 2385 2386 2387File: plplotdoc.info, Node: plerrx; Draw error bars in x direction, Next: plerry; Draw error bars in the y direction, Prev: pleop; Eject current page, Up: The Common API for PLplot 2388 238917.25 plerrx: Draw error bars in x direction 2390============================================ 2391 2392 plerrx (n, xmin, xmax, y); 2393 2394 Draws a set of ‘‘n’’ error bars in x direction, the ‘i’’th error bar 2395extending from ‘‘xmin’[i]’ to ‘‘xmax’[i]’ at y coordinate ‘‘y’[i]’. The 2396terminals of the error bars are of length equal to the minor tick length 2397(settable using ‘plsmin’ (*note plsmin; Set length of minor ticks::)). 2398 2399‘n’ (‘‘PLINT’ (*note PLINT-type::)’, input) 2400 Number of error bars to draw. 2401 2402‘xmin’ (‘‘PLFLT_VECTOR’ (*note PLFLT_VECTOR-type::)’, input) 2403 A vector containing the x coordinates of the left-hand endpoints of 2404 the error bars. 2405 2406‘xmax’ (‘‘PLFLT_VECTOR’ (*note PLFLT_VECTOR-type::)’, input) 2407 A vector containing the x coordinates of the right-hand endpoints 2408 of the error bars. 2409 2410‘y’ (‘‘PLFLT_VECTOR’ (*note PLFLT_VECTOR-type::)’, input) 2411 A vector containing the y coordinates of the error bars. 2412 2413 Redacted form: 2414 2415 • General: ‘plerrx(xmin, ymax, y)’ 2416 2417 This function is used in example 29. 2418 2419 2420File: plplotdoc.info, Node: plerry; Draw error bars in the y direction, Next: plfamadv; Advance to the next family file on the next new page, Prev: plerrx; Draw error bars in x direction, Up: The Common API for PLplot 2421 242217.26 plerry: Draw error bars in the y direction 2423================================================ 2424 2425 plerry (n, x, ymin, ymax); 2426 2427 Draws a set of ‘‘n’’ error bars in the y direction, the ‘i’’th error 2428bar extending from ‘‘ymin’[i]’ to ‘‘ymax’[i]’ at x coordinate ‘‘x’[i]’. 2429The terminals of the error bars are of length equal to the minor tick 2430length (settable using ‘plsmin’ (*note plsmin; Set length of minor 2431ticks::)). 2432 2433‘n’ (‘‘PLINT’ (*note PLINT-type::)’, input) 2434 Number of error bars to draw. 2435 2436‘x’ (‘‘PLFLT_VECTOR’ (*note PLFLT_VECTOR-type::)’, input) 2437 A vector containing the x coordinates of the error bars. 2438 2439‘ymin’ (‘‘PLFLT_VECTOR’ (*note PLFLT_VECTOR-type::)’, input) 2440 A vector containing the y coordinates of the lower endpoints of the 2441 error bars. 2442 2443‘ymax’ (‘‘PLFLT_VECTOR’ (*note PLFLT_VECTOR-type::)’, input) 2444 A vector containing the y coordinates of the upper endpoints of the 2445 error bars. 2446 2447 Redacted form: 2448 2449 • General: ‘plerry(x, ymin, ymax)’ 2450 2451 This function is used in example 29. 2452 2453 2454File: plplotdoc.info, Node: plfamadv; Advance to the next family file on the next new page, Next: plfill; Draw filled polygon, Prev: plerry; Draw error bars in the y direction, Up: The Common API for PLplot 2455 245617.27 plfamadv: Advance to the next family file on the next new page 2457==================================================================== 2458 2459 plfamadv (); 2460 2461 Advance to the next family file on the next new page. 2462 2463 Redacted form: ‘plfamadv()’ 2464 2465 This function is not used in any examples. 2466 2467 2468File: plplotdoc.info, Node: plfill; Draw filled polygon, Next: plfill3; Draw filled polygon in 3D, Prev: plfamadv; Advance to the next family file on the next new page, Up: The Common API for PLplot 2469 247017.28 plfill: Draw filled polygon 2471================================= 2472 2473 plfill (n, x, y); 2474 2475 Fills the polygon defined by the ‘‘n’’ points ‘(‘x’[i], ‘y’[i])’ 2476using the pattern defined by ‘plpsty’ (*note plpsty; Select area fill 2477pattern::) or ‘plpat’ (*note plpat; Set area line fill pattern::). The 2478default fill style is a solid fill. The routine will automatically 2479close the polygon between the last and first vertices. If multiple 2480closed polygons are passed in ‘‘x’’ and ‘‘y’’ then ‘plfill’ (*note 2481plfill; Draw filled polygon::) will fill in between them. 2482 2483‘n’ (‘‘PLINT’ (*note PLINT-type::)’, input) 2484 Number of vertices in polygon. 2485 2486‘x’ (‘‘PLFLT_VECTOR’ (*note PLFLT_VECTOR-type::)’, input) 2487 A vector containing the x coordinates of vertices. 2488 2489‘y’ (‘‘PLFLT_VECTOR’ (*note PLFLT_VECTOR-type::)’, input) 2490 A vector containing the y coordinates of vertices. 2491 2492 Redacted form: ‘plfill(x,y)’ 2493 2494 This function is used in examples 12, 13, 15, 16, 21, 24, and 25. 2495 2496 2497File: plplotdoc.info, Node: plfill3; Draw filled polygon in 3D, Next: plflush; Flushes the output stream, Prev: plfill; Draw filled polygon, Up: The Common API for PLplot 2498 249917.29 plfill3: Draw filled polygon in 3D 2500======================================== 2501 2502 plfill3 (n, x, y, z); 2503 2504 Fills the 3D polygon defined by the ‘‘n’’ points in the ‘‘x’’, ‘‘y’’, 2505and ‘‘z’’ vectors using the pattern defined by ‘plpsty’ (*note plpsty; 2506Select area fill pattern::) or ‘plpat’ (*note plpat; Set area line fill 2507pattern::). The routine will automatically close the polygon between 2508the last and first vertices. If multiple closed polygons are passed in 2509‘‘x’’, ‘‘y’’, and ‘‘z’’ then ‘plfill3’ (*note plfill3; Draw filled 2510polygon in 3D::) will fill in between them. 2511 2512‘n’ (‘‘PLINT’ (*note PLINT-type::)’, input) 2513 Number of vertices in polygon. 2514 2515‘x’ (‘‘PLFLT_VECTOR’ (*note PLFLT_VECTOR-type::)’, input) 2516 A vector containing the x coordinates of vertices. 2517 2518‘y’ (‘‘PLFLT_VECTOR’ (*note PLFLT_VECTOR-type::)’, input) 2519 A vector containing the y coordinates of vertices. 2520 2521‘z’ (‘‘PLFLT_VECTOR’ (*note PLFLT_VECTOR-type::)’, input) 2522 A vector containing the z coordinates of vertices. 2523 2524 Redacted form: 2525 2526 • General: ‘plfill3(x, y, z)’ 2527 2528 This function is used in example 15. 2529 2530 2531File: plplotdoc.info, Node: plflush; Flushes the output stream, Next: plfont; Set font, Prev: plfill3; Draw filled polygon in 3D, Up: The Common API for PLplot 2532 253317.30 plflush: Flushes the output stream 2534======================================== 2535 2536 plflush (); 2537 2538 Flushes the output stream. Use sparingly, if at all. 2539 2540 Redacted form: ‘plflush()’ 2541 2542 This function is used in examples 1 and 14. 2543 2544 2545File: plplotdoc.info, Node: plfont; Set font, Next: plfontld; Load Hershey fonts, Prev: plflush; Flushes the output stream, Up: The Common API for PLplot 2546 254717.31 plfont: Set font 2548====================== 2549 2550 plfont (ifont); 2551 2552 Sets the font used for subsequent text and symbols. For devices that 2553still use Hershey fonts this routine has no effect unless the Hershey 2554fonts with extended character set are loaded (see ‘plfontld’ (*note 2555plfontld; Load Hershey fonts::)). For unicode-aware devices that use 2556system fonts instead of Hershey fonts, this routine calls the ‘plsfci’ 2557(*note plsfci; Set FCI [font characterization integer]::) routine with 2558argument set up appropriately for the various cases below. However, 2559this method of specifying the font for unicode-aware devices is 2560deprecated, and the much more flexible method of calling ‘plsfont’ 2561(*note plsfont; Set family; style and weight of the current font::) 2562directly is recommended instead (where ‘plsfont’ (*note plsfont; Set 2563family; style and weight of the current font::) provides a user-friendly 2564interface to ‘plsfci’ (*note plsfci; Set FCI [font characterization 2565integer]::)), 2566 2567‘ifont’ (‘‘PLINT’ (*note PLINT-type::)’, input) 2568 Specifies the font: 2569 2570 • ‘1’: Sans serif font (simplest and fastest) 2571 2572 • ‘2’: Serif font 2573 2574 • ‘3’: Italic font 2575 2576 • ‘4’: Script font 2577 2578 Redacted form: ‘plfont(ifont)’ 2579 2580 This function is used in examples 1, 2, 4, 7, 13, 24, and 26. 2581 2582 2583File: plplotdoc.info, Node: plfontld; Load Hershey fonts, Next: plGetCursor; Wait for graphics input event and translate to world coordinates_, Prev: plfont; Set font, Up: The Common API for PLplot 2584 258517.32 plfontld: Load Hershey fonts 2586================================== 2587 2588 plfontld (fnt); 2589 2590 Loads the Hershey fonts used for text and symbols. This routine may 2591be called before or after initializing PLplot. If not explicitly called 2592before PLplot initialization, then by default that initialization loads 2593Hershey fonts with the extended character set. This routine only has a 2594practical effect for devices that still use Hershey fonts (as opposed to 2595modern devices that use unicode-aware system fonts instead of Hershey 2596fonts). 2597 2598‘fnt’ (‘‘PLINT’ (*note PLINT-type::)’, input) 2599 Specifies the type of Hershey fonts to load. A zero value 2600 specifies Hershey fonts with the standard character set and a 2601 non-zero value (the default assumed if ‘plfontld’ (*note plfontld; 2602 Load Hershey fonts::) is never called) specifies Hershey fonts with 2603 the extended character set. 2604 2605 Redacted form: ‘plfontld(fnt)’ 2606 2607 This function is used in examples 1 and 7. 2608 2609 2610File: plplotdoc.info, Node: plGetCursor; Wait for graphics input event and translate to world coordinates_, Next: plgchr; Get character default height and current [scaled] height, Prev: plfontld; Load Hershey fonts, Up: The Common API for PLplot 2611 261217.33 plGetCursor: Wait for graphics input event and translate to world coordinates. 2613==================================================================================== 2614 2615 PLINT plGetCursor (gin); 2616 2617 Wait for graphics input event and translate to world coordinates. 2618Returns 0 if no translation to world coordinates is possible. 2619 2620‘gin’ (‘‘PLGraphicsIn’ (*note PLGraphicsIn; PLplot Graphics Input structure::) *’, output) 2621 Pointer to ‘PLGraphicsIn’ (*note PLGraphicsIn; PLplot Graphics 2622 Input structure::) structure which will contain the output. The 2623 structure is not allocated by the routine and must exist before the 2624 function is called. 2625 2626 This function returns 1 on success and 0 if no translation to world 2627coordinates is possible. 2628 2629 Redacted form: ‘plGetCursor(gin)’ 2630 2631 This function is used in examples 1 and 20. 2632 2633 2634File: plplotdoc.info, Node: plgchr; Get character default height and current [scaled] height, Next: plgcmap1_range; Get the cmap1 argument range for continuous color plots, Prev: plGetCursor; Wait for graphics input event and translate to world coordinates_, Up: The Common API for PLplot 2635 263617.34 plgchr: Get character default height and current (scaled) height 2637====================================================================== 2638 2639 plgchr (p_def, p_ht); 2640 2641 Get character default height and current (scaled) height. 2642 2643‘p_def’ (‘‘PLFLT_NC_SCALAR’ (*note PLFLT_NC_SCALAR-type::)’, output) 2644 Returned value of the default character height (mm). 2645 2646‘p_ht’ (‘‘PLFLT_NC_SCALAR’ (*note PLFLT_NC_SCALAR-type::)’, output) 2647 Returned value of the scaled character height (mm). 2648 2649 Redacted form: ‘plgchr(p_def, p_ht)’ 2650 2651 This function is used in example 23. 2652 2653 2654File: plplotdoc.info, Node: plgcmap1_range; Get the cmap1 argument range for continuous color plots, Next: plgcol0; Returns 8-bit RGB values for given color index from cmap0, Prev: plgchr; Get character default height and current [scaled] height, Up: The Common API for PLplot 2655 265617.35 plgcmap1_range: Get the cmap1 argument range for continuous color plots 2657============================================================================= 2658 2659 plgcmap1_range (min_color, max_color); 2660 2661 Get the cmap1 argument range for continuous color plots. (Use 2662‘plscmap1_range’ (*note plscmap1_range; Set the cmap1 argument range for 2663continuous color plots::) to set the cmap1 argument range.) 2664 2665‘min_color’ (‘‘PLFLT_NC_SCALAR’ (*note PLFLT_NC_SCALAR-type::)’, output) 2666 Returned value of the current minimum cmap1 argument. 2667 2668‘max_color’ (‘‘PLFLT_NC_SCALAR’ (*note PLFLT_NC_SCALAR-type::)’, output) 2669 Returned value of the current maximum cmap1 argument. 2670 2671 Redacted form: ‘plgcmap1_range(min_color, max_color)’ 2672 2673 This function is currently not used in any example. 2674 2675 2676File: plplotdoc.info, Node: plgcol0; Returns 8-bit RGB values for given color index from cmap0, Next: plgcol0a; Returns 8-bit RGB values and PLFLT alpha transparency value for given color index from cmap0, Prev: plgcmap1_range; Get the cmap1 argument range for continuous color plots, Up: The Common API for PLplot 2677 267817.36 plgcol0: Returns 8-bit RGB values for given color index from cmap0 2679======================================================================== 2680 2681 plgcol0 (icol0, r, g, b); 2682 2683 Returns 8-bit RGB values (0-255) for given color from cmap0 (see 2684*note Color Map0::). Values are negative if an invalid color id is 2685given. 2686 2687‘icol0’ (‘‘PLINT’ (*note PLINT-type::)’, input) 2688 Index of desired cmap0 color. 2689 2690‘r’ (‘‘PLINT_NC_SCALAR’ (*note PLINT_NC_SCALAR-type::)’, output) 2691 Returned value of the 8-bit red value. 2692 2693‘g’ (‘‘PLINT_NC_SCALAR’ (*note PLINT_NC_SCALAR-type::)’, output) 2694 Returned value of the 8-bit green value. 2695 2696‘b’ (‘‘PLINT_NC_SCALAR’ (*note PLINT_NC_SCALAR-type::)’, output) 2697 Returned value of the 8-bit blue value. 2698 2699 Redacted form: ‘plgcol0(icol0, r, g, b)’ 2700 2701 This function is used in example 2. 2702 2703 2704File: plplotdoc.info, Node: plgcol0a; Returns 8-bit RGB values and PLFLT alpha transparency value for given color index from cmap0, Next: plgcolbg; Returns the background color [cmap0[0]] by 8-bit RGB value, Prev: plgcol0; Returns 8-bit RGB values for given color index from cmap0, Up: The Common API for PLplot 2705 270617.37 plgcol0a: Returns 8-bit RGB values and PLFLT alpha transparency value for given color index from cmap0 2707============================================================================================================ 2708 2709 plgcol0a (icol0, r, g, b, alpha); 2710 2711 Returns 8-bit RGB values (0-255) and PLFLT alpha transparency value 2712(0.0-1.0) for given color from cmap0 (see *note Color Map0::). Values 2713are negative if an invalid color id is given. 2714 2715‘icol0’ (‘‘PLINT’ (*note PLINT-type::)’, input) 2716 Index of desired cmap0 color. 2717 2718‘r’ (‘‘PLINT_NC_SCALAR’ (*note PLINT_NC_SCALAR-type::)’, output) 2719 Returned value of the red intensity in the range from 0 to 255. 2720 2721‘g’ (‘‘PLINT_NC_SCALAR’ (*note PLINT_NC_SCALAR-type::)’, output) 2722 Returned value of the green intensity in the range from 0 to 255. 2723 2724‘b’ (‘‘PLINT_NC_SCALAR’ (*note PLINT_NC_SCALAR-type::)’, output) 2725 Returned value of the blue intensity in the range from 0 to 255. 2726 2727‘alpha’ (‘‘PLFLT_NC_SCALAR’ (*note PLFLT_NC_SCALAR-type::)’, output) 2728 Returned value of the alpha transparency in the range from 2729 (0.0-1.0). 2730 2731 Redacted form: ‘plgcola(r, g, b)’ 2732 2733 This function is used in example 30. 2734 2735 2736File: plplotdoc.info, Node: plgcolbg; Returns the background color [cmap0[0]] by 8-bit RGB value, Next: plgcolbga; Returns the background color [cmap0[0]] by 8-bit RGB value and PLFLT alpha transparency value, Prev: plgcol0a; Returns 8-bit RGB values and PLFLT alpha transparency value for given color index from cmap0, Up: The Common API for PLplot 2737 273817.38 plgcolbg: Returns the background color (cmap0[0]) by 8-bit RGB value 2739========================================================================== 2740 2741 plgcolbg (r, g, b); 2742 2743 Returns the background color (cmap0[0]) by 8-bit RGB value. 2744 2745‘r’ (‘‘PLINT_NC_SCALAR’ (*note PLINT_NC_SCALAR-type::)’, output) 2746 Returned value of the red intensity in the range from 0 to 255. 2747 2748‘g’ (‘‘PLINT_NC_SCALAR’ (*note PLINT_NC_SCALAR-type::)’, output) 2749 Returned value of the green intensity in the range from 0 to 255. 2750 2751‘b’ (‘‘PLINT_NC_SCALAR’ (*note PLINT_NC_SCALAR-type::)’, output) 2752 Returned value of the blue intensity in the range from 0 to 255. 2753 2754 Redacted form: ‘plgcolbg(r, g, b)’ 2755 2756 This function is used in example 31. 2757 2758 2759File: plplotdoc.info, Node: plgcolbga; Returns the background color [cmap0[0]] by 8-bit RGB value and PLFLT alpha transparency value, Next: plgcompression; Get the current device-compression setting, Prev: plgcolbg; Returns the background color [cmap0[0]] by 8-bit RGB value, Up: The Common API for PLplot 2760 276117.39 plgcolbga: Returns the background color (cmap0[0]) by 8-bit RGB value and PLFLT alpha transparency value 2762============================================================================================================== 2763 2764 plgcolbga (r, g, b, alpha); 2765 2766 Returns the background color (cmap0[0]) by 8-bit RGB value and PLFLT 2767alpha transparency value. 2768 2769‘r’ (‘‘PLINT_NC_SCALAR’ (*note PLINT_NC_SCALAR-type::)’, output) 2770 Returned value of the red intensity in the range from 0 to 255. 2771 2772‘g’ (‘‘PLINT_NC_SCALAR’ (*note PLINT_NC_SCALAR-type::)’, output) 2773 Returned value of the green intensity in the range from 0 to 255. 2774 2775‘b’ (‘‘PLINT_NC_SCALAR’ (*note PLINT_NC_SCALAR-type::)’, output) 2776 Returned value of the blue intensity in the range from 0 to 255. 2777 2778‘alpha’ (‘‘PLFLT_NC_SCALAR’ (*note PLFLT_NC_SCALAR-type::)’, output) 2779 Returned value of the alpha transparency in the range (0.0-1.0). 2780 2781 This function is used in example 31. 2782 2783 2784File: plplotdoc.info, Node: plgcompression; Get the current device-compression setting, Next: plgdev; Get the current device [keyword] name, Prev: plgcolbga; Returns the background color [cmap0[0]] by 8-bit RGB value and PLFLT alpha transparency value, Up: The Common API for PLplot 2785 278617.40 plgcompression: Get the current device-compression setting 2787================================================================ 2788 2789 plgcompression (compression); 2790 2791 Get the current device-compression setting. This parameter is only 2792used for drivers that provide compression. 2793 2794‘compression’ (‘‘PLINT_NC_SCALAR’ (*note PLINT_NC_SCALAR-type::)’, output) 2795 Returned value of the compression setting for the current device. 2796 2797 Redacted form: ‘plgcompression(compression)’ 2798 2799 This function is used in example 31. 2800 2801 2802File: plplotdoc.info, Node: plgdev; Get the current device [keyword] name, Next: plgdidev; Get parameters that define current device-space window, Prev: plgcompression; Get the current device-compression setting, Up: The Common API for PLplot 2803 280417.41 plgdev: Get the current device (keyword) name 2805=================================================== 2806 2807 plgdev (p_dev); 2808 2809 Get the current device (keyword) name. Note: you _must_ have 2810allocated space for this (80 characters is safe). 2811 2812‘p_dev’ (‘‘PLCHAR_NC_VECTOR’ (*note PLCHAR_NC_VECTOR-type::)’, output) 2813 Returned ascii character string (with preallocated length of 80 2814 characters or more) containing the device (keyword) name. 2815 2816 Redacted form: ‘plgdev(p_dev)’ 2817 2818 This function is used in example 14. 2819 2820 2821File: plplotdoc.info, Node: plgdidev; Get parameters that define current device-space window, Next: plgdiori; Get plot orientation, Prev: plgdev; Get the current device [keyword] name, Up: The Common API for PLplot 2822 282317.42 plgdidev: Get parameters that define current device-space window 2824====================================================================== 2825 2826 plgdidev (p_mar, p_aspect, p_jx, p_jy); 2827 2828 Get relative margin width, aspect ratio, and relative justification 2829that define current device-space window. If ‘plsdidev’ (*note plsdidev; 2830Set parameters that define current device-space window::) has not been 2831called the default values pointed to by ‘‘p_mar’’, ‘‘p_aspect’’, 2832‘‘p_jx’’, and ‘‘p_jy’’ will all be 0. 2833 2834‘p_mar’ (‘‘PLFLT_NC_SCALAR’ (*note PLFLT_NC_SCALAR-type::)’, output) 2835 Returned value of the relative margin width. 2836 2837‘p_aspect’ (‘‘PLFLT_NC_SCALAR’ (*note PLFLT_NC_SCALAR-type::)’, output) 2838 Returned value of the aspect ratio. 2839 2840‘p_jx’ (‘‘PLFLT_NC_SCALAR’ (*note PLFLT_NC_SCALAR-type::)’, output) 2841 Returned value of the relative justification in x. 2842 2843‘p_jy’ (‘‘PLFLT_NC_SCALAR’ (*note PLFLT_NC_SCALAR-type::)’, output) 2844 Returned value of the relative justification in y. 2845 2846 Redacted form: ‘plgdidev(p_mar, p_aspect, p_jx, p_jy)’ 2847 2848 This function is used in example 31. 2849 2850 2851File: plplotdoc.info, Node: plgdiori; Get plot orientation, Next: plgdiplt; Get parameters that define current plot-space window, Prev: plgdidev; Get parameters that define current device-space window, Up: The Common API for PLplot 2852 285317.43 plgdiori: Get plot orientation 2854==================================== 2855 2856 plgdiori (p_rot); 2857 2858 Get plot orientation parameter which is multiplied by 90 degrees to 2859obtain the angle of rotation. Note, arbitrary rotation parameters such 2860as 0.2 (corresponding to 18 degrees) are possible, but the usual values 2861for the rotation parameter are 0., 1., 2., and 3. corresponding to 0 2862degrees (landscape mode), 90 degrees (portrait mode), 180 degrees 2863(seascape mode), and 270 degrees (upside-down mode). If ‘plsdiori’ 2864(*note plsdiori; Set plot orientation::) has not been called the default 2865value pointed to by ‘‘p_rot’’ will be 0. 2866 2867‘p_rot’ (‘‘PLFLT_NC_SCALAR’ (*note PLFLT_NC_SCALAR-type::)’, output) 2868 Returned value of the orientation parameter. 2869 2870 Redacted form: ‘plgdiori(p_rot)’ 2871 2872 This function is not used in any examples. 2873 2874 2875File: plplotdoc.info, Node: plgdiplt; Get parameters that define current plot-space window, Next: plgdrawmode; Get drawing mode [depends on device support!], Prev: plgdiori; Get plot orientation, Up: The Common API for PLplot 2876 287717.44 plgdiplt: Get parameters that define current plot-space window 2878==================================================================== 2879 2880 plgdiplt (p_xmin, p_ymin, p_xmax, p_ymax); 2881 2882 Get relative minima and maxima that define current plot-space window. 2883If ‘plsdiplt’ (*note plsdiplt; Set parameters that define current 2884plot-space window::) has not been called the default values pointed to 2885by ‘‘p_xmin’’, ‘‘p_ymin’’, ‘‘p_xmax’’, and ‘‘p_ymax’’ will be 0., 0., 28861., and 1. 2887 2888‘p_xmin’ (‘‘PLFLT_NC_SCALAR’ (*note PLFLT_NC_SCALAR-type::)’, output) 2889 Returned value of the relative minimum in x. 2890 2891‘p_ymin’ (‘‘PLFLT_NC_SCALAR’ (*note PLFLT_NC_SCALAR-type::)’, output) 2892 Returned value of the relative minimum in y. 2893 2894‘p_xmax’ (‘‘PLFLT_NC_SCALAR’ (*note PLFLT_NC_SCALAR-type::)’, output) 2895 Returned value of the relative maximum in x. 2896 2897‘p_ymax’ (‘‘PLFLT_NC_SCALAR’ (*note PLFLT_NC_SCALAR-type::)’, output) 2898 Returned value of the relative maximum in y. 2899 2900 Redacted form: ‘plgdiplt(p_xmin, p_ymin, p_xmax, p_ymax)’ 2901 2902 This function is used in example 31. 2903 2904 2905File: plplotdoc.info, Node: plgdrawmode; Get drawing mode [depends on device support!], Next: plgfam; Get family file parameters, Prev: plgdiplt; Get parameters that define current plot-space window, Up: The Common API for PLplot 2906 290717.45 plgdrawmode: Get drawing mode (depends on device support!) 2908================================================================ 2909 2910 plgdrawmode (); 2911 2912 Get drawing mode. Note only one device driver (cairo) currently 2913supports this at the moment, and for that case the PLINT value returned 2914by this function is one of ‘PL_DRAWMODE_DEFAULT’, ‘PL_DRAWMODE_REPLACE’, 2915‘PL_DRAWMODE_XOR’, or ‘PL_DRAWMODE_UNKNOWN’. This function returns 2916‘PL_DRAWMODE_UNKNOWN’ for the rest of the device drivers. See also 2917‘plsdrawmode’ (*note plsdrawmode; Set drawing mode [depends on device 2918support!]::). 2919 2920 Redacted form: ‘plgdrawmode()’ 2921 2922 This function is used in example 34. 2923 2924 2925File: plplotdoc.info, Node: plgfam; Get family file parameters, Next: plgfci; Get FCI [font characterization integer], Prev: plgdrawmode; Get drawing mode [depends on device support!], Up: The Common API for PLplot 2926 292717.46 plgfam: Get family file parameters 2928======================================== 2929 2930 plgfam (p_fam, p_num, p_bmax); 2931 2932 Gets information about current family file, if familying is enabled. 2933See *note Family File Output:: for more information. 2934 2935‘p_fam’ (‘‘PLINT_NC_SCALAR’ (*note PLINT_NC_SCALAR-type::)’, output) 2936 Returned value of the current family flag value. If nonzero, 2937 familying is enabled for the current device. 2938 2939‘p_num’ (‘‘PLINT_NC_SCALAR’ (*note PLINT_NC_SCALAR-type::)’, output) 2940 Returned value of the current family file number. 2941 2942‘p_bmax’ (‘‘PLINT_NC_SCALAR’ (*note PLINT_NC_SCALAR-type::)’, output) 2943 Returned value of the maximum file size (in bytes) for a family 2944 file. 2945 2946 Redacted form: ‘plgfam(p_fam, p_num, p_bmax)’ 2947 2948 This function is used in examples 14 and 31. 2949 2950 2951File: plplotdoc.info, Node: plgfci; Get FCI [font characterization integer], Next: plgfnam; Get output file name, Prev: plgfam; Get family file parameters, Up: The Common API for PLplot 2952 295317.47 plgfci: Get FCI (font characterization integer) 2954===================================================== 2955 2956 plgfci (p_fci); 2957 2958 Gets information about the current font using the FCI approach. See 2959*note FCI:: for more information. 2960 2961‘p_fci’ (‘‘PLUNICODE_NC_SCALAR’ (*note PLUNICODE_NC_SCALAR-type::)’, output) 2962 Returned value of the current FCI value. 2963 2964 Redacted form: ‘plgfci(p_fci)’ 2965 2966 This function is used in example 23. 2967 2968 2969File: plplotdoc.info, Node: plgfnam; Get output file name, Next: plgfont; Get family; style and weight of the current font, Prev: plgfci; Get FCI [font characterization integer], Up: The Common API for PLplot 2970 297117.48 plgfnam: Get output file name 2972=================================== 2973 2974 plgfnam (fnam); 2975 2976 Gets the current output file name, if applicable. 2977 2978‘fnam’ (‘‘PLCHAR_NC_VECTOR’ (*note PLCHAR_NC_VECTOR-type::)’, output) 2979 Returned ascii character string (with preallocated length of 80 2980 characters or more) containing the file name. 2981 2982 Redacted form: ‘plgfnam(fnam)’ 2983 2984 This function is used in example 31. 2985 2986 2987File: plplotdoc.info, Node: plgfont; Get family; style and weight of the current font, Next: plglevel; Get the [current] run level, Prev: plgfnam; Get output file name, Up: The Common API for PLplot 2988 298917.49 plgfont: Get family, style and weight of the current font 2990=============================================================== 2991 2992 plgfont (p_family, p_style, p_weight); 2993 2994 Gets information about current font. See *note FCI:: for more 2995information on font selection. 2996 2997‘p_family’ (‘‘PLINT_NC_SCALAR’ (*note PLINT_NC_SCALAR-type::)’, output) 2998 Returned value of the current font family. The available values 2999 are given by the PL_FCI_* constants in ‘plplot.h’. Current options 3000 are PL_FCI_SANS, PL_FCI_SERIF, PL_FCI_MONO, PL_FCI_SCRIPT and 3001 PL_FCI_SYMBOL. If p_family is NULL then the font family is not 3002 returned. 3003 3004‘p_style’ (‘‘PLINT_NC_SCALAR’ (*note PLINT_NC_SCALAR-type::)’, output) 3005 Returned value of the current font style. The available values are 3006 given by the PL_FCI_* constants in ‘plplot.h’. Current options are 3007 PL_FCI_UPRIGHT, PL_FCI_ITALIC and PL_FCI_OBLIQUE. If p_style is 3008 NULL then the font style is not returned. 3009 3010‘p_weight’ (‘‘PLINT_NC_SCALAR’ (*note PLINT_NC_SCALAR-type::)’, output) 3011 Returned value of the current font weight. The available values 3012 are given by the PL_FCI_* constants in ‘plplot.h’. Current options 3013 are PL_FCI_MEDIUM and PL_FCI_BOLD. If p_weight is NULL then the 3014 font weight is not returned. 3015 3016 Redacted form: ‘plgfont(p_family, p_style, p_weight)’ 3017 3018 This function is used in example 23. 3019 3020 3021File: plplotdoc.info, Node: plglevel; Get the [current] run level, Next: plgpage; Get page parameters, Prev: plgfont; Get family; style and weight of the current font, Up: The Common API for PLplot 3022 302317.50 plglevel: Get the (current) run level 3024=========================================== 3025 3026 plglevel (p_level); 3027 3028 Get the (current) run level. Valid settings are: 3029 3030 • 0, uninitialized 3031 3032 • 1, initialized 3033 3034 • 2, viewport defined 3035 3036 • 3, world coordinates defined 3037 3038‘p_level’ (‘‘PLINT_NC_SCALAR’ (*note PLINT_NC_SCALAR-type::)’, output) 3039 Returned value of the run level. 3040 3041 Redacted form: ‘plglevel(p_level)’ 3042 3043 This function is used in example 31. 3044 3045 3046File: plplotdoc.info, Node: plgpage; Get page parameters, Next: plgra; Switch to graphics screen, Prev: plglevel; Get the [current] run level, Up: The Common API for PLplot 3047 304817.51 plgpage: Get page parameters 3049================================== 3050 3051 plgpage (p_xp, p_yp, p_xleng, p_yleng, p_xoff, p_yoff); 3052 3053 Gets the current page configuration. The length and offset values 3054are expressed in units that are specific to the current driver. For 3055instance: screen drivers will usually interpret them as number of 3056pixels, whereas printer drivers will usually use mm. 3057 3058‘p_xp’ (‘‘PLFLT_NC_SCALAR’ (*note PLFLT_NC_SCALAR-type::)’, output) 3059 Returned value of the number of pixels/inch (DPI) in x. 3060 3061‘p_yp’ (‘‘PLFLT_NC_SCALAR’ (*note PLFLT_NC_SCALAR-type::)’, output) 3062 Returned value of the number of pixels/inch (DPI) in y. 3063 3064‘p_xleng’ (‘‘PLINT_NC_SCALAR’ (*note PLINT_NC_SCALAR-type::)’, output) 3065 Returned value of the x page length. 3066 3067‘p_yleng’ (‘‘PLINT_NC_SCALAR’ (*note PLINT_NC_SCALAR-type::)’, output) 3068 Returned value of the y page length. 3069 3070‘p_xoff’ (‘‘PLINT_NC_SCALAR’ (*note PLINT_NC_SCALAR-type::)’, output) 3071 Returned value of the x page offset. 3072 3073‘p_yoff’ (‘‘PLINT_NC_SCALAR’ (*note PLINT_NC_SCALAR-type::)’, output) 3074 Returned value of the y page offset. 3075 3076 Redacted form: ‘plgpage(p_xp, p_yp, p_xleng, p_yleng, p_xoff, 3077p_yoff)’ 3078 3079 This function is used in examples 14 and 31. 3080 3081 3082File: plplotdoc.info, Node: plgra; Switch to graphics screen, Next: plgradient; Draw linear gradient inside polygon, Prev: plgpage; Get page parameters, Up: The Common API for PLplot 3083 308417.52 plgra: Switch to graphics screen 3085====================================== 3086 3087 plgra (); 3088 3089 Sets an interactive device to graphics mode, used in conjunction with 3090‘pltext’ (*note pltext; Switch to text screen::) to allow graphics and 3091text to be interspersed. On a device which supports separate text and 3092graphics windows, this command causes control to be switched to the 3093graphics window. If already in graphics mode, this command is ignored. 3094It is also ignored on devices which only support a single window or use 3095a different method for shifting focus. See also ‘pltext’ (*note pltext; 3096Switch to text screen::). 3097 3098 Redacted form: ‘plgra()’ 3099 3100 This function is used in example 1. 3101 3102 3103File: plplotdoc.info, Node: plgradient; Draw linear gradient inside polygon, Next: plgriddata; Grid data from irregularly sampled data, Prev: plgra; Switch to graphics screen, Up: The Common API for PLplot 3104 310517.53 plgradient: Draw linear gradient inside polygon 3106===================================================== 3107 3108 plgradient (n, x, y, angle); 3109 3110 Draw a linear gradient using cmap1 inside the polygon defined by the 3111‘‘n’’ points ‘(‘x’[i], ‘y’[i])’. Interpretation of the polygon is the 3112same as for ‘plfill’ (*note plfill; Draw filled polygon::). The polygon 3113coordinates and the gradient angle are all expressed in world 3114coordinates. The angle from the ‘‘x’’ axis for both the rotated 3115coordinate system and the gradient vector is specified by ‘‘angle’’. 3116The magnitude of the gradient vector is the difference between the 3117maximum and minimum values of ‘‘x’’ for the vertices in the rotated 3118coordinate system. The origin of the gradient vector can be interpreted 3119as being anywhere on the line corresponding to the minimum ‘‘x’’ value 3120for the vertices in the rotated coordinate system. The distance along 3121the gradient vector is linearly transformed to the independent variable 3122of color map 1 which ranges from 0. at the tail of the gradient vector 3123to 1. at the head of the gradient vector. What is drawn is the RGBA 3124color corresponding to the independent variable of cmap1. For more 3125information about cmap1 (see *note Color Map1::). 3126 3127‘n’ (‘‘PLINT’ (*note PLINT-type::)’, input) 3128 Number of vertices in polygon. 3129 3130‘x’ (‘‘PLFLT_VECTOR’ (*note PLFLT_VECTOR-type::)’, input) 3131 A vector containing the x coordinates of vertices. 3132 3133‘y’ (‘‘PLFLT_VECTOR’ (*note PLFLT_VECTOR-type::)’, input) 3134 A vector containing the y coordinates of vertices. 3135 3136‘angle’ (‘‘PLFLT’ (*note PLFLT-type::)’, input) 3137 Angle (degrees) of gradient vector from x axis. 3138 3139 Redacted form: ‘plgradient(x,y,angle)’ 3140 3141 This function is used in examples 25 and 30. 3142 3143 3144File: plplotdoc.info, Node: plgriddata; Grid data from irregularly sampled data, Next: plgspa; Get current subpage parameters, Prev: plgradient; Draw linear gradient inside polygon, Up: The Common API for PLplot 3145 314617.54 plgriddata: Grid data from irregularly sampled data 3147========================================================= 3148 3149 plgriddata (x, y, z, npts, xg, nptsx, yg, nptsy, zg, type, data); 3150 3151 Real world data is frequently irregularly sampled, but PLplot 3D 3152plots require data organized as a grid, i.e., with x sample point values 3153independent of y coordinate and vice versa. This function takes 3154irregularly sampled data from the ‘x[npts]’, ‘y[npts]’, and ‘z[npts]’ 3155vectors; reads the desired grid location from the input vectors 3156‘xg[nptsx]’ and ‘yg[nptsy]’; and returns the interpolated result on that 3157grid using the output matrix ‘zg[nptsx][nptsy]’. The algorithm used to 3158interpolate the data to the grid is specified with the argument ‘type’ 3159which can have one parameter specified in argument ‘data’. 3160 3161‘x’ (‘‘PLFLT_VECTOR’ (*note PLFLT_VECTOR-type::)’, input) 3162 The input ‘x’ vector. 3163 3164‘y’ (‘‘PLFLT_VECTOR’ (*note PLFLT_VECTOR-type::)’, input) 3165 The input ‘y’ vector. 3166 3167‘z’ (‘‘PLFLT_VECTOR’ (*note PLFLT_VECTOR-type::)’, input) 3168 The input ‘z’ vector. Each triple ‘x[i]’, ‘y[i]’, ‘z[i]’ 3169 represents one data sample coordinate. 3170 3171‘npts’ (‘‘PLINT’ (*note PLINT-type::)’, input) 3172 The number of data samples in the ‘x’, ‘y’ and ‘z’ vectors. 3173 3174‘xg’ (‘‘PLFLT_VECTOR’ (*note PLFLT_VECTOR-type::)’, input) 3175 A vector that specifies the grid spacing in the x direction. 3176 Usually ‘xg’ has ‘nptsx’ equally spaced values from the minimum to 3177 the maximum values of the ‘x’ input vector. 3178 3179‘nptsx’ (‘‘PLINT’ (*note PLINT-type::)’, input) 3180 The number of points in the ‘xg’ vector. 3181 3182‘yg’ (‘‘PLFLT_VECTOR’ (*note PLFLT_VECTOR-type::)’, input) 3183 A vector that specifies the grid spacing in the y direction. 3184 Similar to the ‘xg’ parameter. 3185 3186‘nptsy’ (‘‘PLINT’ (*note PLINT-type::)’, input) 3187 The number of points in the ‘yg’ vector. 3188 3189‘zg’ (‘‘PLFLT_NC_MATRIX’ (*note PLFLT_NC_MATRIX-type::)’, output) 3190 The matrix of interpolated results where data lies in the grid 3191 specified by ‘xg’ and ‘yg’. Therefore the ‘zg’ matrix must be 3192 dimensioned ‘nptsx’ by ‘nptsy’. 3193 3194‘type’ (‘‘PLINT’ (*note PLINT-type::)’, input) 3195 The type of grid interpolation algorithm to use, which can be: 3196 3197 • ‘GRID_CSA’: Bivariate Cubic Spline approximation 3198 3199 • ‘GRID_DTLI’: Delaunay Triangulation Linear Interpolation 3200 3201 • ‘GRID_NNI’: Natural Neighbors Interpolation 3202 3203 • ‘GRID_NNIDW’: Nearest Neighbors Inverse Distance Weighted 3204 3205 • ‘GRID_NNLI’: Nearest Neighbors Linear Interpolation 3206 3207 • ‘GRID_NNAIDW’: Nearest Neighbors Around Inverse Distance 3208 Weighted 3209 3210 For details of the algorithms read the source file ‘plgridd.c’. 3211 3212‘data’ (‘‘PLFLT’ (*note PLFLT-type::)’, input) 3213 Some gridding algorithms require extra data, which can be specified 3214 through this argument. Currently, for algorithm: 3215 3216 • ‘GRID_NNIDW’, ‘data’ specifies the number of neighbors to use, 3217 the lower the value, the noisier (more local) the 3218 approximation is. 3219 3220 • ‘GRID_NNLI’, ‘data’ specifies what a thin triangle is, in the 3221 range [1. .. 2.]. High values enable the usage of very thin 3222 triangles for interpolation, possibly resulting in error in 3223 the approximation. 3224 3225 • ‘GRID_NNI’, only weights greater than ‘data’ will be accepted. 3226 If 0, all weights will be accepted. 3227 3228 Redacted form: 3229 3230 • General: ‘plgriddata(x, y, z, xg, yg, zg, type, data)’ 3231 3232 • Python: ‘‘zg’=‘plgriddata(x, y, z, xg, yg, type, data)’’ 3233 3234 This function is used in example 21. 3235 3236 3237File: plplotdoc.info, Node: plgspa; Get current subpage parameters, Next: plgstrm; Get current stream number, Prev: plgriddata; Grid data from irregularly sampled data, Up: The Common API for PLplot 3238 323917.55 plgspa: Get current subpage parameters 3240============================================ 3241 3242 plgspa (xmin, xmax, ymin, ymax); 3243 3244 Gets the size of the current subpage in millimeters measured from the 3245bottom left hand corner of the output device page or screen. Can be 3246used in conjunction with ‘plsvpa’ (*note plsvpa; Specify viewport in 3247absolute coordinates::) for setting the size of a viewport in absolute 3248coordinates (millimeters). 3249 3250‘xmin’ (‘‘PLFLT_NC_SCALAR’ (*note PLFLT_NC_SCALAR-type::)’, output) 3251 Returned value of the position of the left hand edge of the subpage 3252 in millimeters. 3253 3254‘xmax’ (‘‘PLFLT_NC_SCALAR’ (*note PLFLT_NC_SCALAR-type::)’, output) 3255 Returned value of the position of the right hand edge of the 3256 subpage in millimeters. 3257 3258‘ymin’ (‘‘PLFLT_NC_SCALAR’ (*note PLFLT_NC_SCALAR-type::)’, output) 3259 Returned value of the position of the bottom edge of the subpage in 3260 millimeters. 3261 3262‘ymax’ (‘‘PLFLT_NC_SCALAR’ (*note PLFLT_NC_SCALAR-type::)’, output) 3263 Returned value of the position of the top edge of the subpage in 3264 millimeters. 3265 3266 Redacted form: ‘plgspa(xmin, xmax, ymin, ymax)’ 3267 3268 This function is used in example 23. 3269 3270 3271File: plplotdoc.info, Node: plgstrm; Get current stream number, Next: plgver; Get the current library version number, Prev: plgspa; Get current subpage parameters, Up: The Common API for PLplot 3272 327317.56 plgstrm: Get current stream number 3274======================================== 3275 3276 plgstrm (p_strm); 3277 3278 Gets the number of the current output stream. See also ‘plsstrm’ 3279(*note plsstrm; Set current output stream::). 3280 3281‘p_strm’ (‘‘PLINT_NC_SCALAR’ (*note PLINT_NC_SCALAR-type::)’, output) 3282 Returned value of the current stream value. 3283 3284 Redacted form: ‘plgstrm(p_strm)’ 3285 3286 This function is used in example 1,20. 3287 3288 3289File: plplotdoc.info, Node: plgver; Get the current library version number, Next: plgvpd; Get viewport limits in normalized device coordinates, Prev: plgstrm; Get current stream number, Up: The Common API for PLplot 3290 329117.57 plgver: Get the current library version number 3292==================================================== 3293 3294 plgver (p_ver); 3295 3296 Get the current library version number. Note: you _must_ have 3297allocated space for this (80 characters is safe). 3298 3299‘p_ver’ (‘‘PLCHAR_NC_VECTOR’ (*note PLCHAR_NC_VECTOR-type::)’, output) 3300 Returned ascii character string (with preallocated length of 80 3301 characters or more) containing the PLplot version number. 3302 3303 Redacted form: ‘plgver(p_ver)’ 3304 3305 This function is used in example 1. 3306 3307 3308File: plplotdoc.info, Node: plgvpd; Get viewport limits in normalized device coordinates, Next: plgvpw; Get viewport limits in world coordinates, Prev: plgver; Get the current library version number, Up: The Common API for PLplot 3309 331017.58 plgvpd: Get viewport limits in normalized device coordinates 3311================================================================== 3312 3313 plgvpd (p_xmin, p_xmax, p_ymin, p_ymax); 3314 3315 Get viewport limits in normalized device coordinates. 3316 3317‘p_xmin’ (‘‘PLFLT_NC_SCALAR’ (*note PLFLT_NC_SCALAR-type::)’, output) 3318 Returned value of the lower viewport limit of the normalized device 3319 coordinate in x. 3320 3321‘p_xmax’ (‘‘PLFLT_NC_SCALAR’ (*note PLFLT_NC_SCALAR-type::)’, output) 3322 Returned value of the upper viewport limit of the normalized device 3323 coordinate in x. 3324 3325‘p_ymin’ (‘‘PLFLT_NC_SCALAR’ (*note PLFLT_NC_SCALAR-type::)’, output) 3326 Returned value of the lower viewport limit of the normalized device 3327 coordinate in y. 3328 3329‘p_ymax’ (‘‘PLFLT_NC_SCALAR’ (*note PLFLT_NC_SCALAR-type::)’, output) 3330 Returned value of the upper viewport limit of the normalized device 3331 coordinate in y. 3332 3333 Redacted form: 3334 3335 • General: ‘plgvpd(p_xmin, p_xmax, p_ymin, p_ymax)’ 3336 3337 This function is used in example 31. 3338 3339 3340File: plplotdoc.info, Node: plgvpw; Get viewport limits in world coordinates, Next: plgxax; Get x axis parameters, Prev: plgvpd; Get viewport limits in normalized device coordinates, Up: The Common API for PLplot 3341 334217.59 plgvpw: Get viewport limits in world coordinates 3343====================================================== 3344 3345 plgvpw (p_xmin, p_xmax, p_ymin, p_ymax); 3346 3347 Get viewport limits in world coordinates. 3348 3349‘p_xmin’ (‘‘PLFLT_NC_SCALAR’ (*note PLFLT_NC_SCALAR-type::)’, output) 3350 Returned value of the lower viewport limit of the world coordinate 3351 in x. 3352 3353‘p_xmax’ (‘‘PLFLT_NC_SCALAR’ (*note PLFLT_NC_SCALAR-type::)’, output) 3354 Returned value of the upper viewport limit of the world coordinate 3355 in x. 3356 3357‘p_ymin’ (‘‘PLFLT_NC_SCALAR’ (*note PLFLT_NC_SCALAR-type::)’, output) 3358 Returned value of the lower viewport limit of the world coordinate 3359 in y. 3360 3361‘p_ymax’ (‘‘PLFLT_NC_SCALAR’ (*note PLFLT_NC_SCALAR-type::)’, output) 3362 Returned value of the upper viewport limit of the world coordinate 3363 in y. 3364 3365 Redacted form: 3366 3367 • General: ‘plgvpw(p_xmin, p_xmax, p_ymin, p_ymax)’ 3368 3369 This function is used in example 31. 3370 3371 3372File: plplotdoc.info, Node: plgxax; Get x axis parameters, Next: plgyax; Get y axis parameters, Prev: plgvpw; Get viewport limits in world coordinates, Up: The Common API for PLplot 3373 337417.60 plgxax: Get x axis parameters 3375=================================== 3376 3377 plgxax (p_digmax, p_digits); 3378 3379 Returns current values of the ‘‘p_digmax’’ and ‘‘p_digits’’ flags for 3380the x axis. ‘‘p_digits’’ is updated after the plot is drawn, so this 3381routine should only be called _after_ the call to ‘plbox’ (*note plbox; 3382Draw a box with axes; etc::) (or ‘ plbox3’ (*note plbox3; Draw a box 3383with axes; etc; in 3-d::)) is complete. See *note Annotating the 3384Viewport:: for more information. 3385 3386‘p_digmax’ (‘‘PLINT_NC_SCALAR’ (*note PLINT_NC_SCALAR-type::)’, output) 3387 Returned value of the maximum number of digits for the x axis. If 3388 nonzero, the printed label has been switched to a floating-point 3389 representation when the number of digits exceeds this value. 3390 3391‘p_digits’ (‘‘PLINT_NC_SCALAR’ (*note PLINT_NC_SCALAR-type::)’, output) 3392 Returned value of the actual number of digits for the numeric 3393 labels (x axis) from the last plot. 3394 3395 Redacted form: ‘plgxax(p_digmax, p_digits)’ 3396 3397 This function is used in example 31. 3398 3399 3400File: plplotdoc.info, Node: plgyax; Get y axis parameters, Next: plgzax; Get z axis parameters, Prev: plgxax; Get x axis parameters, Up: The Common API for PLplot 3401 340217.61 plgyax: Get y axis parameters 3403=================================== 3404 3405 plgyax (p_digmax, p_digits); 3406 3407 Identical to ‘plgxax’ (*note plgxax; Get x axis parameters::), except 3408that arguments are flags for y axis. See the description of ‘plgxax’ 3409(*note plgxax; Get x axis parameters::) for more detail. 3410 3411‘p_digmax’ (‘‘PLINT_NC_SCALAR’ (*note PLINT_NC_SCALAR-type::)’, output) 3412 Returned value of the maximum number of digits for the y axis. If 3413 nonzero, the printed label has been switched to a floating-point 3414 representation when the number of digits exceeds this value. 3415 3416‘p_digits’ (‘‘PLINT_NC_SCALAR’ (*note PLINT_NC_SCALAR-type::)’, output) 3417 Returned value of the actual number of digits for the numeric 3418 labels (y axis) from the last plot. 3419 3420 Redacted form: ‘plgyax(p_digmax, p_digits)’ 3421 3422 This function is used in example 31. 3423 3424 3425File: plplotdoc.info, Node: plgzax; Get z axis parameters, Next: plhist; Plot a histogram from unbinned data, Prev: plgyax; Get y axis parameters, Up: The Common API for PLplot 3426 342717.62 plgzax: Get z axis parameters 3428=================================== 3429 3430 plgzax (p_digmax, p_digits); 3431 3432 Identical to ‘plgxax’ (*note plgxax; Get x axis parameters::), except 3433that arguments are flags for z axis. See the description of ‘plgxax’ 3434(*note plgxax; Get x axis parameters::) for more detail. 3435 3436‘p_digmax’ (‘‘PLINT_NC_SCALAR’ (*note PLINT_NC_SCALAR-type::)’, output) 3437 Returned value of the maximum number of digits for the z axis. If 3438 nonzero, the printed label has been switched to a floating-point 3439 representation when the number of digits exceeds this value. 3440 3441‘p_digits’ (‘‘PLINT_NC_SCALAR’ (*note PLINT_NC_SCALAR-type::)’, output) 3442 Returned value of the actual number of digits for the numeric 3443 labels (z axis) from the last plot. 3444 3445 Redacted form: ‘plgzax(p_digmax, p_digits)’ 3446 3447 This function is used in example 31. 3448 3449 3450File: plplotdoc.info, Node: plhist; Plot a histogram from unbinned data, Next: plhlsrgb; Convert HLS color to RGB, Prev: plgzax; Get z axis parameters, Up: The Common API for PLplot 3451 345217.63 plhist: Plot a histogram from unbinned data 3453================================================= 3454 3455 plhist (n, data, datmin, datmax, nbin, opt); 3456 3457 Plots a histogram from ‘‘n’’ data points stored in the ‘‘data’’ 3458vector. This routine bins the data into ‘‘nbin’’ bins equally spaced 3459between ‘‘datmin’’ and ‘‘datmax’’, and calls ‘plbin’ (*note plbin; Plot 3460a histogram from binned data::) to draw the resulting histogram. 3461Parameter ‘‘opt’’ allows, among other things, the histogram either to be 3462plotted in an existing window or causes ‘plhist’ (*note plhist; Plot a 3463histogram from unbinned data::) to call ‘plenv’ (*note plenv; Set up 3464standard window and draw box::) with suitable limits before plotting the 3465histogram. 3466 3467‘n’ (‘‘PLINT’ (*note PLINT-type::)’, input) 3468 Number of data points. 3469 3470‘data’ (‘‘PLFLT_VECTOR’ (*note PLFLT_VECTOR-type::)’, input) 3471 A vector containing the values of the ‘‘n’’ data points. 3472 3473‘datmin’ (‘‘PLFLT’ (*note PLFLT-type::)’, input) 3474 Left-hand edge of lowest-valued bin. 3475 3476‘datmax’ (‘‘PLFLT’ (*note PLFLT-type::)’, input) 3477 Right-hand edge of highest-valued bin. 3478 3479‘nbin’ (‘‘PLINT’ (*note PLINT-type::)’, input) 3480 Number of (equal-sized) bins into which to divide the interval 3481 ‘‘xmin’’ to ‘‘xmax’’. 3482 3483‘opt’ (‘‘PLINT’ (*note PLINT-type::)’, input) 3484 Is a combination of several flags: 3485 3486 • ‘‘opt’=PL_HIST_DEFAULT’: The axes are automatically rescaled 3487 to fit the histogram data, the outer bins are expanded to fill 3488 up the entire x-axis, data outside the given extremes are 3489 assigned to the outer bins and bins of zero height are simply 3490 drawn. 3491 3492 • ‘‘opt’=PL_HIST_NOSCALING|...’: The existing axes are not 3493 rescaled to fit the histogram data, without this flag, ‘plenv’ 3494 (*note plenv; Set up standard window and draw box::) is called 3495 to set the world coordinates. 3496 3497 • ‘‘opt’=PL_HIST_IGNORE_OUTLIERS|...’: Data outside the given 3498 extremes are not taken into account. This option should 3499 probably be combined with ‘‘opt’=PL_HIST_NOEXPAND|...’, so as 3500 to properly present the data. 3501 3502 • ‘‘opt’=PL_HIST_NOEXPAND|...’: The outer bins are drawn with 3503 equal size as the ones inside. 3504 3505 • ‘‘opt’=PL_HIST_NOEMPTY|...’: Bins with zero height are not 3506 drawn (there is a gap for such bins). 3507 3508 Redacted form: ‘plhist(data, datmin, datmax, nbin, opt)’ 3509 3510 This function is used in example 5. 3511 3512 3513File: plplotdoc.info, Node: plhlsrgb; Convert HLS color to RGB, Next: plimagefr; Plot a 2D matrix using cmap1, Prev: plhist; Plot a histogram from unbinned data, Up: The Common API for PLplot 3514 351517.64 plhlsrgb: Convert HLS color to RGB 3516======================================== 3517 3518 plhlsrgb (h, l, s, p_r, p_g, p_b); 3519 3520 Convert HLS color coordinates to RGB. 3521 3522‘h’ (‘‘PLFLT’ (*note PLFLT-type::)’, input) 3523 Hue in degrees (0.0-360.0) on the color cylinder. 3524 3525‘l’ (‘‘PLFLT’ (*note PLFLT-type::)’, input) 3526 Lightness expressed as a fraction (0.0-1.0) of the axis of the 3527 color cylinder. 3528 3529‘s’ (‘‘PLFLT’ (*note PLFLT-type::)’, input) 3530 Saturation expressed as a fraction (0.0-1.0) of the radius of the 3531 color cylinder. 3532 3533‘p_r’ (‘‘PLFLT_NC_SCALAR’ (*note PLFLT_NC_SCALAR-type::)’, output) 3534 Returned value of the red intensity (0.0-1.0) of the color. 3535 3536‘p_g’ (‘‘PLFLT_NC_SCALAR’ (*note PLFLT_NC_SCALAR-type::)’, output) 3537 Returned value of the green intensity (0.0-1.0) of the color. 3538 3539‘p_b’ (‘‘PLFLT_NC_SCALAR’ (*note PLFLT_NC_SCALAR-type::)’, output) 3540 Returned value of the blue intensity (0.0-1.0) of the color. 3541 3542 Redacted form: 3543 3544 • General: ‘plhlsrgb(h, l, s, p_r, p_g, p_b)’ 3545 3546 This function is used in example 2. 3547 3548 3549File: plplotdoc.info, Node: plimagefr; Plot a 2D matrix using cmap1, Next: plimage; Plot a 2D matrix using cmap1 with automatic color adjustment, Prev: plhlsrgb; Convert HLS color to RGB, Up: The Common API for PLplot 3550 355117.65 plimagefr: Plot a 2D matrix using cmap1 3552============================================= 3553 3554 plimagefr (idata, nx, ny, xmin, xmax, ymin, ymax, zmin, zmax, 3555 valuemin, valuemax, pltr, pltr_data); 3556 3557 Plot a 2D matrix using cmap1. 3558 3559‘idata’ (‘‘PLFLT_MATRIX’ (*note PLFLT_MATRIX-type::)’, input) 3560 A matrix of values (intensities) to plot. Should have dimensions 3561 of ‘nx’ by ‘ny’. 3562 3563‘nx, ny’ (‘‘PLINT’ (*note PLINT-type::)’, input) 3564 Dimensions of idata 3565 3566‘xmin, xmax, ymin, ymax’ (‘‘PLFLT’ (*note PLFLT-type::)’, input) 3567 See the discussion of ‘pltr’ below for how these arguments are used 3568 (only for the special case when the callback function ‘pltr’ is not 3569 supplied). 3570 3571‘zmin, zmax’ (‘‘PLFLT’ (*note PLFLT-type::)’, input) 3572 Only data between zmin and zmax (inclusive) will be plotted. 3573 3574‘valuemin, valuemax’ (‘‘PLFLT’ (*note PLFLT-type::)’, input) 3575 The minimum and maximum data values to use for value to color 3576 mappings. A datum equal to or less than valuemin will be plotted 3577 with color 0.0, while a datum equal to or greater than valuemax 3578 will be plotted with color 1.0. Data between valuemin and valuemax 3579 map linearly to colors in the range (0.0-1.0). 3580 3581‘pltr’ (‘‘PLTRANSFORM_callback’ (*note PLTRANSFORM_callback-type::)’, input) 3582 A callback function that defines the transformation between the 3583 zero-based indices of the matrix ‘‘idata’’ and world coordinates. 3584 If ‘pltr’ is not supplied (e.g., is set to NULL in the C case), 3585 then the x indices of ‘‘idata’’ are mapped to the range ‘xmin’ 3586 through ‘xmax’ and the y indices of ‘‘idata’’ are mapped to the 3587 range ‘ymin’ through ‘ymax’. 3588 3589 For the C case, transformation functions are provided in the PLplot 3590 library: ‘pltr0’ (*note pltr0; Identity transformation for matrix 3591 index to world coordinate mapping::) for the identity mapping, and 3592 ‘pltr1’ (*note pltr1; Linear interpolation for matrix index to 3593 world coordinate mapping using singly dimensioned coordinate 3594 arrays::) and ‘pltr2’ (*note pltr2; Linear interpolation for grid 3595 to world mapping using doubly dimensioned coordinate arrays 3596 [row-major order as per normal C 2d arrays]::) for arbitrary 3597 mappings respectively defined by vectors and matrices. In 3598 addition, C callback routines for the transformation can be 3599 supplied by the user such as the ‘mypltr’ function in 3600 ‘examples/c/x09c.c’ which provides a general linear transformation 3601 between index coordinates and world coordinates. 3602 3603 For languages other than C you should consult *note Supported 3604 computer languages: Supported computer languages. for the details 3605 concerning how ‘PLTRANSFORM_callback’ (*note 3606 PLTRANSFORM_callback-type::) arguments are interfaced. However, in 3607 general, a particular pattern of callback-associated arguments such 3608 as a ‘tr’ vector with 6 elements; ‘xg’ and ‘yg’ vectors; or ‘xg’ 3609 and ‘yg’ matrices are respectively interfaced to a 3610 linear-transformation routine similar to the above ‘mypltr’ 3611 function; ‘pltr1’ (*note pltr1; Linear interpolation for matrix 3612 index to world coordinate mapping using singly dimensioned 3613 coordinate arrays::); and ‘pltr2’ (*note pltr2; Linear 3614 interpolation for grid to world mapping using doubly dimensioned 3615 coordinate arrays [row-major order as per normal C 2d arrays]::). 3616 Furthermore, some of our more sophisticated bindings (see, e.g., 3617 *note Fortran Language::) support native language callbacks for 3618 handling index to world-coordinate transformations. Examples of 3619 these various approaches are given in ‘examples/<language>x09*’, 3620 ‘examples/<language>x16*’, ‘examples/<language>x20*’, 3621 ‘examples/<language>x21*’, and ‘examples/<language>x22*’, for all 3622 our supported languages. 3623 3624‘pltr_data’ (‘‘PLPointer’ (*note PLPointer-type::)’, input) 3625 Extra parameter to help pass information to ‘pltr0’ (*note pltr0; 3626 Identity transformation for matrix index to world coordinate 3627 mapping::), ‘pltr1’ (*note pltr1; Linear interpolation for matrix 3628 index to world coordinate mapping using singly dimensioned 3629 coordinate arrays::), ‘pltr2’ (*note pltr2; Linear interpolation 3630 for grid to world mapping using doubly dimensioned coordinate 3631 arrays [row-major order as per normal C 2d arrays]::), or whatever 3632 routine is externally supplied. 3633 3634 Redacted form: 3635 3636 • General: ‘ plimagefr(idata, xmin, xmax, ymin, ymax, zmin, zmax, 3637 valuemin, valuemax, pltr, pltr_data) ’ 3638 3639 This function is used in example 20. 3640 3641 3642File: plplotdoc.info, Node: plimage; Plot a 2D matrix using cmap1 with automatic color adjustment, Next: plinit; Initialize PLplot, Prev: plimagefr; Plot a 2D matrix using cmap1, Up: The Common API for PLplot 3643 364417.66 plimage: Plot a 2D matrix using cmap1 with automatic color adjustment 3645=========================================================================== 3646 3647 plimage (idata, nx, ny, xmin, xmax, ymin, ymax, zmin, zmax, Dxmin, 3648 Dxmax, Dymin, Dymax); 3649 3650 Plot a 2D matrix using the cmap1 palette. The color scale is 3651automatically adjusted to use the maximum and minimum values in idata as 3652valuemin and valuemax in a call to ‘plimagefr’ (*note plimagefr; Plot a 36532D matrix using cmap1::). 3654 3655‘idata’ (‘‘PLFLT_MATRIX’ (*note PLFLT_MATRIX-type::)’, input) 3656 A matrix containing function values to plot. Should have 3657 dimensions of ‘nx’ by ‘ny’. 3658 3659‘nx, ny’ (‘‘PLINT’ (*note PLINT-type::)’, input) 3660 Dimensions of idata 3661 3662‘xmin, xmax, ymin, ymax’ (‘‘PLFLT’ (*note PLFLT-type::)’, input) 3663 The ‘x’ and ‘y’ index ranges are linearly transformed to these 3664 world coordinate ranges such that ‘idata[0][0]’ corresponds to 3665 ‘(xmin, ymin)’ and ‘idata[nx - 1][ny - 1]’ corresponds to ‘(xmax, 3666 ymax)’. 3667 3668‘zmin, zmax’ (‘‘PLFLT’ (*note PLFLT-type::)’, input) 3669 Only data between zmin and zmax (inclusive) will be plotted. 3670 3671‘Dxmin, Dxmax, Dymin, Dymax’ (‘‘PLFLT’ (*note PLFLT-type::)’, input) 3672 Plot only the window of points whose plot coordinates fall inside 3673 the window of (Dxmin, Dymin) to (Dxmax, Dymax). 3674 3675 Redacted form: 3676 3677 • General: ‘ plimage(idata, xmin, xmax, ymin, ymax, zmin, zmax, 3678 Dxmin, Dxmax, Dymin, Dymax) ’ 3679 3680 This function is used in example 20. 3681 3682 3683File: plplotdoc.info, Node: plinit; Initialize PLplot, Next: pljoin; Draw a line between two points, Prev: plimage; Plot a 2D matrix using cmap1 with automatic color adjustment, Up: The Common API for PLplot 3684 368517.67 plinit: Initialize PLplot 3686=============================== 3687 3688 plinit (); 3689 3690 Initializing the plotting package. The program prompts for the 3691device keyword or number of the desired output device. Hitting a RETURN 3692in response to the prompt is the same as selecting the first device. 3693‘plinit’ (*note plinit; Initialize PLplot::) will issue no prompt if 3694either the device was specified previously (via command line flag, the 3695‘plsetopt’ (*note plsetopt; Set any command-line option::) function, or 3696the ‘plsdev’ (*note plsdev; Set the device [keyword] name::) function), 3697or if only one device is enabled when PLplot is installed. If subpages 3698have been specified, the output device is divided into ‘nx’ by ‘ny’ 3699subpages, each of which may be used independently. If ‘plinit’ (*note 3700plinit; Initialize PLplot::) is called again during a program, the 3701previously opened file will be closed. The subroutine ‘pladv’ (*note 3702pladv; Advance the [sub-]page::) is used to advance from one subpage to 3703the next. 3704 3705 Redacted form: ‘plinit()’ 3706 3707 This function is used in all of the examples. 3708 3709 3710File: plplotdoc.info, Node: pljoin; Draw a line between two points, Next: pllab; Simple routine to write labels, Prev: plinit; Initialize PLplot, Up: The Common API for PLplot 3711 371217.68 pljoin: Draw a line between two points 3713============================================ 3714 3715 pljoin (x1, y1, x2, y2); 3716 3717 Joins the point ‘(‘x1’, ‘y1’)’ to ‘(‘x2’, ‘y2’)’. 3718 3719‘x1’ (‘‘PLFLT’ (*note PLFLT-type::)’, input) 3720 x coordinate of first point. 3721 3722‘y1’ (‘‘PLFLT’ (*note PLFLT-type::)’, input) 3723 y coordinate of first point. 3724 3725‘x2’ (‘‘PLFLT’ (*note PLFLT-type::)’, input) 3726 x coordinate of second point. 3727 3728‘y2’ (‘‘PLFLT’ (*note PLFLT-type::)’, input) 3729 y coordinate of second point. 3730 3731 Redacted form: ‘pljoin(x1,y1,x2,y2)’ 3732 3733 This function is used in examples 3 and 14. 3734 3735 3736File: plplotdoc.info, Node: pllab; Simple routine to write labels, Next: pllegend; Plot legend using discretely annotated filled boxes; lines; and/or lines of symbols, Prev: pljoin; Draw a line between two points, Up: The Common API for PLplot 3737 373817.69 pllab: Simple routine to write labels 3739=========================================== 3740 3741 pllab (xlabel, ylabel, tlabel); 3742 3743 Routine for writing simple labels. Use ‘plmtex’ (*note plmtex; Write 3744text relative to viewport boundaries::) for more complex labels. 3745 3746‘xlabel’ (‘‘PLCHAR_VECTOR’ (*note PLCHAR_VECTOR-type::)’, input) 3747 A UTF-8 character string specifying the label for the x axis. 3748 3749‘ylabel’ (‘‘PLCHAR_VECTOR’ (*note PLCHAR_VECTOR-type::)’, input) 3750 A UTF-8 character string specifying the label for the y axis. 3751 3752‘tlabel’ (‘‘PLCHAR_VECTOR’ (*note PLCHAR_VECTOR-type::)’, input) 3753 A UTF-8 character string specifying the title of the plot. 3754 3755 Redacted form: ‘pllab(xlabel, ylabel, tlabel)’ 3756 3757 This function is used in examples 1, 5, 9, 12, 14-16, 20-22, and 29. 3758 3759 3760File: plplotdoc.info, Node: pllegend; Plot legend using discretely annotated filled boxes; lines; and/or lines of symbols, Next: pllightsource; Sets the 3D position of the light source, Prev: pllab; Simple routine to write labels, Up: The Common API for PLplot 3761 376217.70 pllegend: Plot legend using discretely annotated filled boxes, lines, and/or lines of symbols 3763=================================================================================================== 3764 3765 pllegend (p_legend_width, p_legend_height, opt, position, x, y, 3766 plot_width, bg_color, bb_color, bb_style, nrow, ncolumn, nlegend, 3767 opt_array, text_offset, text_scale, text_spacing, 3768 test_justification, text_colors, text, box_colors, box_patterns, 3769 box_scales, box_line_widths, line_colors, line_styles, line_widths, 3770 symbol_colors, symbol_scales, symbol_numbers, symbols); 3771 3772 Routine for creating a discrete plot legend with a plotted filled 3773box, line, and/or line of symbols for each annotated legend entry. (See 3774‘plcolorbar’ (*note plcolorbar; Plot color bar for image; shade or 3775gradient plots::) for similar functionality for creating continuous 3776color bars.) The arguments of pllegend provide control over the 3777location and size of the legend as well as the location and 3778characteristics of the elements (most of which are optional) within that 3779legend. The resulting legend is clipped at the boundaries of the 3780current subpage. (N.B. the adopted coordinate system used for some of 3781the parameters is defined in the documentation of the ‘‘position’’ 3782parameter.) 3783 3784‘p_legend_width’ (‘‘PLFLT_NC_SCALAR’ (*note PLFLT_NC_SCALAR-type::)’, output) 3785 Returned value of the legend width in adopted coordinates. This 3786 quantity is calculated from ‘‘plot_width’’, ‘‘text_offset’’, 3787 ‘‘ncolumn’’ (possibly modified inside the routine depending on 3788 ‘‘nlegend’’ and ‘‘nrow’’), and the length (calculated internally) 3789 of the longest text string. 3790 3791‘p_legend_height’ (‘‘PLFLT_NC_SCALAR’ (*note PLFLT_NC_SCALAR-type::)’, output) 3792 Returned value of the legend height in adopted coordinates. This 3793 quantity is calculated from ‘‘text_scale’’, ‘‘text_spacing’’, and 3794 ‘‘nrow’’ (possibly modified inside the routine depending on 3795 ‘‘nlegend’’ and ‘‘nrow’’). 3796 3797‘opt’ (‘‘PLINT’ (*note PLINT-type::)’, input) 3798 ‘‘opt’’ contains bits controlling the overall legend. If the 3799 ‘PL_LEGEND_TEXT_LEFT’ bit is set, put the text area on the left of 3800 the legend and the plotted area on the right. Otherwise, put the 3801 text area on the right of the legend and the plotted area on the 3802 left. If the ‘PL_LEGEND_BACKGROUND’ bit is set, plot a 3803 (semitransparent) background for the legend. If the 3804 ‘PL_LEGEND_BOUNDING_BOX’ bit is set, plot a bounding box for the 3805 legend. If the ‘PL_LEGEND_ROW_MAJOR’ bit is set and (both of the 3806 possibly internally transformed) ‘‘nrow’’ > 1 and ‘‘ncolumn’’ > 1, 3807 then plot the resulting array of legend entries in row-major order. 3808 Otherwise, plot the legend entries in column-major order. 3809 3810‘position’ (‘‘PLINT’ (*note PLINT-type::)’, input) 3811 ‘‘position’’ contains bits which control the overall position of 3812 the legend and the definition of the adopted coordinates used for 3813 positions just like what is done for the position argument for 3814 ‘plcolorbar’ (*note plcolorbar; Plot color bar for image; shade or 3815 gradient plots::). However, note that the defaults for the 3816 position bits (see below) are different than the ‘plcolorbar’ 3817 (*note plcolorbar; Plot color bar for image; shade or gradient 3818 plots::) case. The combination of the ‘PL_POSITION_LEFT’, 3819 ‘PL_POSITION_RIGHT’, ‘PL_POSITION_TOP’, ‘PL_POSITION_BOTTOM’, 3820 ‘PL_POSITION_INSIDE’, and ‘PL_POSITION_OUTSIDE’ bits specifies one 3821 of the 16 possible standard positions (the 4 corners and centers of 3822 the 4 sides for both the inside and outside cases) of the legend 3823 relative to the adopted coordinate system. The corner positions 3824 are specified by the appropriate combination of two of the 3825 ‘PL_POSITION_LEFT’, ‘PL_POSITION_RIGHT’, ‘PL_POSITION_TOP’, and 3826 ‘PL_POSITION_BOTTOM’ bits while the sides are specified by a single 3827 value of one of those bits. The adopted coordinates are normalized 3828 viewport coordinates if the ‘PL_POSITION_VIEWPORT’ bit is set or 3829 normalized subpage coordinates if the ‘PL_POSITION_SUBPAGE’ bit is 3830 set. Default position bits: If none of ‘PL_POSITION_LEFT’, 3831 ‘PL_POSITION_RIGHT’, ‘PL_POSITION_TOP’, or ‘PL_POSITION_BOTTOM’ are 3832 set, then use the combination of ‘PL_POSITION_RIGHT’ and 3833 ‘PL_POSITION_TOP’. If neither of ‘PL_POSITION_INSIDE’ or 3834 ‘PL_POSITION_OUTSIDE’ is set, use ‘PL_POSITION_INSIDE’. If neither 3835 of ‘PL_POSITION_VIEWPORT’ or ‘PL_POSITION_SUBPAGE’ is set, use 3836 ‘PL_POSITION_VIEWPORT’. 3837 3838‘x’ (‘‘PLFLT’ (*note PLFLT-type::)’, input) 3839 X offset of the legend position in adopted coordinates from the 3840 specified standard position of the legend. For positive x, the 3841 direction of motion away from the standard position is 3842 inward/outward from the standard corner positions or standard left 3843 or right positions if the 3844 ‘PL_POSITION_INSIDE’/‘PL_POSITION_OUTSIDE’ bit is set in 3845 ‘‘position’’. For the standard top or bottom positions, the 3846 direction of motion is toward positive X. 3847 3848‘y’ (‘‘PLFLT’ (*note PLFLT-type::)’, input) 3849 Y offset of the legend position in adopted coordinates from the 3850 specified standard position of the legend. For positive y, the 3851 direction of motion away from the standard position is 3852 inward/outward from the standard corner positions or standard top 3853 or bottom positions if the 3854 ‘PL_POSITION_INSIDE’/‘PL_POSITION_OUTSIDE’ bit is set in 3855 ‘‘position’’. For the standard left or right positions, the 3856 direction of motion is toward positive Y. 3857 3858‘plot_width’ (‘‘PLFLT’ (*note PLFLT-type::)’, input) 3859 Horizontal width in adopted coordinates of the plot area (where the 3860 colored boxes, lines, and/or lines of symbols are drawn) of the 3861 legend. 3862 3863‘bg_color’ (‘‘PLINT’ (*note PLINT-type::)’, input) 3864 The cmap0 color of the background for the legend 3865 (‘PL_LEGEND_BACKGROUND’). 3866 3867‘bb_color’ (‘‘PLINT’ (*note PLINT-type::)’, input) 3868 The cmap0 color of the bounding-box line for the legend 3869 (‘PL_LEGEND_BOUNDING_BOX’). 3870 3871‘bb_style’ (‘‘PLINT’ (*note PLINT-type::)’, input) 3872 The pllsty style number for the bounding-box line for the legend 3873 (‘PL_LEGEND_BACKGROUND’). 3874 3875‘nrow’ (‘‘PLINT’ (*note PLINT-type::)’, input) 3876 The number of rows in the matrix used to render the ‘nlegend’ 3877 legend entries. For internal transformations of ‘nrow’, see 3878 further remarks under ‘nlegend’. 3879 3880‘ncolumn’ (‘‘PLINT’ (*note PLINT-type::)’, input) 3881 The number of columns in the matrix used to render the ‘nlegend’ 3882 legend entries. For internal transformations of ‘ncolumn’, see 3883 further remarks under ‘nlegend’. 3884 3885‘nlegend’ (‘‘PLINT’ (*note PLINT-type::)’, input) 3886 Number of legend entries. The above ‘nrow’ and ‘ncolumn’ values 3887 are transformed internally to be consistent with ‘nlegend’. If 3888 either ‘nrow’ or ‘ncolumn’ is non-positive it is replaced by 1. If 3889 the resulting product of ‘nrow’ and ‘ncolumn’ is less than 3890 ‘nlegend’, the smaller of the two (or ‘nrow’, if ‘nrow’ == 3891 ‘ncolumn’) is increased so the product is >= ‘nlegend’. Thus, for 3892 example, the common ‘nrow’ = 0, ‘ncolumn’ = 0 case is transformed 3893 internally to ‘nrow’ = ‘nlegend’, ‘ncolumn’ = 1; i.e., the usual 3894 case of a legend rendered as a single column. 3895 3896‘opt_array’ (‘‘PLINT_VECTOR’ (*note PLINT_VECTOR-type::)’, input) 3897 A vector of ‘nlegend’ values of options to control each individual 3898 plotted area corresponding to a legend entry. If the 3899 ‘PL_LEGEND_NONE’ bit is set, then nothing is plotted in the plotted 3900 area. If the ‘PL_LEGEND_COLOR_BOX’, ‘PL_LEGEND_LINE’, and/or 3901 ‘PL_LEGEND_SYMBOL’ bits are set, the area corresponding to a legend 3902 entry is plotted with a colored box; a line; and/or a line of 3903 symbols. 3904 3905‘text_offset’ (‘‘PLFLT’ (*note PLFLT-type::)’, input) 3906 Offset of the text area from the plot area in units of character 3907 width. 3908 3909‘text_scale’ (‘‘PLFLT’ (*note PLFLT-type::)’, input) 3910 Character height scale for text annotations. 3911 3912‘text_spacing’ (‘‘PLFLT’ (*note PLFLT-type::)’, input) 3913 Vertical spacing in units of the character height from one legend 3914 entry to the next. 3915 3916‘text_justification’ (‘‘PLFLT’ (*note PLFLT-type::)’, input) 3917 Justification parameter used for text justification. The most 3918 common values of text_justification are 0., 0.5, or 1. 3919 corresponding to a text that is left justified, centred, or right 3920 justified within the text area, but other values are allowed as 3921 well. 3922 3923‘text_colors’ (‘‘PLINT_VECTOR’ (*note PLINT_VECTOR-type::)’, input) 3924 A vector containing ‘nlegend’ cmap0 text colors. 3925 3926‘text’ (‘‘PLCHAR_MATRIX’ (*note PLCHAR_MATRIX-type::)’, input) 3927 A vector of ‘nlegend’ UTF-8 character strings containing the legend 3928 annotations. 3929 3930‘box_colors’ (‘‘PLINT_VECTOR’ (*note PLINT_VECTOR-type::)’, input) 3931 A vector containing ‘nlegend’ cmap0 colors for the discrete colored 3932 boxes (‘PL_LEGEND_COLOR_BOX’). 3933 3934‘box_patterns’ (‘‘PLINT_VECTOR’ (*note PLINT_VECTOR-type::)’, input) 3935 A vector containing ‘nlegend’ patterns (plpsty indices) for the 3936 discrete colored boxes (‘PL_LEGEND_COLOR_BOX’). 3937 3938‘box_scales’ (‘‘PLFLT_VECTOR’ (*note PLFLT_VECTOR-type::)’, input) 3939 A vector containing ‘nlegend’ scales (units of fraction of 3940 character height) for the height of the discrete colored boxes 3941 (‘PL_LEGEND_COLOR_BOX’). 3942 3943‘box_line_widths’ (‘‘PLFLT_VECTOR’ (*note PLFLT_VECTOR-type::)’, input) 3944 A vector containing ‘nlegend’ line widths for the patterns 3945 specified by box_patterns (‘PL_LEGEND_COLOR_BOX’). 3946 3947‘line_colors’ (‘‘PLINT_VECTOR’ (*note PLINT_VECTOR-type::)’, input) 3948 A vector containing ‘nlegend’ cmap0 line colors (‘PL_LEGEND_LINE’). 3949 3950‘line_styles’ (‘‘PLINT_VECTOR’ (*note PLINT_VECTOR-type::)’, input) 3951 A vector containing ‘nlegend’ line styles (plsty indices) 3952 (‘PL_LEGEND_LINE’). 3953 3954‘line_widths’ (‘‘PLFLT_VECTOR’ (*note PLFLT_VECTOR-type::)’, input) 3955 A vector containing ‘nlegend’ line widths (‘PL_LEGEND_LINE’). 3956 3957‘symbol_colors’ (‘‘PLINT_VECTOR’ (*note PLINT_VECTOR-type::)’, input) 3958 A vector containing ‘nlegend’ cmap0 symbol colors 3959 (‘PL_LEGEND_SYMBOL’). 3960 3961‘symbol_scales’ (‘‘PLFLT_VECTOR’ (*note PLFLT_VECTOR-type::)’, input) 3962 A vector containing ‘nlegend’ scale values for the symbol height 3963 (‘PL_LEGEND_SYMBOL’). 3964 3965‘symbol_numbers’ (‘‘PLINT_VECTOR’ (*note PLINT_VECTOR-type::)’, input) 3966 A vector containing ‘nlegend’ numbers of symbols to be drawn across 3967 the width of the plotted area (‘PL_LEGEND_SYMBOL’). 3968 3969‘symbols’ (‘‘PLCHAR_MATRIX’ (*note PLCHAR_MATRIX-type::)’, input) 3970 A vector of ‘nlegend’ UTF-8 character strings containing the legend 3971 symbols. (‘PL_LEGEND_SYMBOL’). 3972 3973 Redacted form: ‘pllegend(p_legend_width, p_legend_height, opt, 3974position, x, y, plot_width, bg_color, bb_color, bb_style, nrow, ncolumn, 3975opt_array, text_offset, text_scale, text_spacing, test_justification, 3976text_colors, text, box_colors, box_patterns, box_scales, 3977box_line_widths, line_colors, line_styles, line_widths, symbol_colors, 3978symbol_scales, symbol_numbers, symbols)’ 3979 3980 This function is used in examples 4, 26, and 33. 3981 3982 3983File: plplotdoc.info, Node: pllightsource; Sets the 3D position of the light source, Next: plline; Draw a line, Prev: pllegend; Plot legend using discretely annotated filled boxes; lines; and/or lines of symbols, Up: The Common API for PLplot 3984 398517.71 pllightsource: Sets the 3D position of the light source 3986============================================================= 3987 3988 pllightsource (x, y, z); 3989 3990 Sets the 3D position of the light source for use with ‘plsurf3d’ 3991(*note plsurf3d; Plot shaded 3-d surface plot::) and ‘plsurf3dl’ (*note 3992plsurf3dl; Plot shaded 3-d surface plot for z[x][y] with y index 3993limits::) 3994 3995‘x’ (‘‘PLFLT’ (*note PLFLT-type::)’, input) 3996 X-coordinate of the light source. 3997 3998‘y’ (‘‘PLFLT’ (*note PLFLT-type::)’, input) 3999 Y-coordinate of the light source. 4000 4001‘z’ (‘‘PLFLT’ (*note PLFLT-type::)’, input) 4002 Z-coordinate of the light source. 4003 4004 Redacted form: ‘pllightsource(x, y, z)’ 4005 4006 This function is used in example 8. 4007 4008 4009File: plplotdoc.info, Node: plline; Draw a line, Next: plline3; Draw a line in 3 space, Prev: pllightsource; Sets the 3D position of the light source, Up: The Common API for PLplot 4010 401117.72 plline: Draw a line 4012========================= 4013 4014 plline (n, x, y); 4015 4016 Draws line defined by ‘‘n’’ points in ‘‘x’’ and ‘‘y’’. 4017 4018‘n’ (‘‘PLINT’ (*note PLINT-type::)’, input) 4019 Number of points defining line. 4020 4021‘x’ (‘‘PLFLT_VECTOR’ (*note PLFLT_VECTOR-type::)’, input) 4022 A vector containing the x coordinates of points. 4023 4024‘y’ (‘‘PLFLT_VECTOR’ (*note PLFLT_VECTOR-type::)’, input) 4025 A vector containing the y coordinates of points. 4026 4027 Redacted form: ‘plline(x, y)’ 4028 4029 This function is used in examples 1, 3, 4, 9, 12-14, 16, 18, 20, 22, 403025-27, and 29. 4031 4032 4033File: plplotdoc.info, Node: plline3; Draw a line in 3 space, Next: pllsty; Select line style, Prev: plline; Draw a line, Up: The Common API for PLplot 4034 403517.73 plline3: Draw a line in 3 space 4036===================================== 4037 4038 plline3 (n, x, y, z); 4039 4040 Draws line in 3 space defined by ‘‘n’’ points in ‘‘x’’, ‘‘y’’, and 4041‘‘z’’. You must first set up the viewport, the 2d viewing window (in 4042world coordinates), and the 3d normalized coordinate box. See ‘x18c.c’ 4043for more info. 4044 4045‘n’ (‘‘PLINT’ (*note PLINT-type::)’, input) 4046 Number of points defining line. 4047 4048‘x’ (‘‘PLFLT_VECTOR’ (*note PLFLT_VECTOR-type::)’, input) 4049 A vector containing the x coordinates of points. 4050 4051‘y’ (‘‘PLFLT_VECTOR’ (*note PLFLT_VECTOR-type::)’, input) 4052 A vector containing the y coordinates of points. 4053 4054‘z’ (‘‘PLFLT_VECTOR’ (*note PLFLT_VECTOR-type::)’, input) 4055 A vector containing the z coordinates of points. 4056 4057 Redacted form: ‘plline3(x, y, z)’ 4058 4059 This function is used in example 18. 4060 4061 4062File: plplotdoc.info, Node: pllsty; Select line style, Next: plmap; Plot continental outline or shapefile data in world coordinates, Prev: plline3; Draw a line in 3 space, Up: The Common API for PLplot 4063 406417.74 pllsty: Select line style 4065=============================== 4066 4067 pllsty (lin); 4068 4069 This sets the line style according to one of eight predefined 4070patterns (also see ‘plstyl’ (*note plstyl; Set line style::)). 4071 4072‘lin’ (‘‘PLINT’ (*note PLINT-type::)’, input) 4073 Integer value between 1 and 8. Line style 1 is a continuous line, 4074 line style 2 is a line with short dashes and gaps, line style 3 is 4075 a line with long dashes and gaps, line style 4 has long dashes and 4076 short gaps and so on. 4077 4078 Redacted form: ‘pllsty(lin)’ 4079 4080 This function is used in examples 9, 12, 22, and 25. 4081 4082 4083File: plplotdoc.info, Node: plmap; Plot continental outline or shapefile data in world coordinates, Next: plmapfill; Plot all or a subset of Shapefile data; filling the polygons, Prev: pllsty; Select line style, Up: The Common API for PLplot 4084 408517.75 plmap: Plot continental outline or shapefile data in world coordinates 4086============================================================================ 4087 4088 plmap ( mapform , name , minx , maxx , miny , maxy ); 4089 4090 Plots continental outlines or shapefile data in world coordinates. A 4091demonstration of how to use this function to create different 4092projections can be found in examples/c/x19c. PLplot is provided with 4093basic coastal outlines and USA state borders. To use the map 4094functionality PLplot must be compiled with the shapelib library. 4095Shapefiles have become a popular standard for geographical data and data 4096in this format can be easily found from a number of online sources. 4097Shapefile data is actually provided as three or more files with the same 4098filename, but different extensions. The .shp and .shx files are 4099required for plotting Shapefile data with PLplot. 4100 4101 PLplot currently supports the point, multipoint, polyline and polygon 4102objects within shapefiles. However holes in polygons are not supported. 4103When plmap is used the type of object is derived from the shapefile, if 4104you wish to override the type then use one of the other plmap variants. 4105The built in maps have line data only. 4106 4107‘mapform’ (‘‘PLMAPFORM_callback’ (*note PLMAPFORM_callback-type::)’, input) 4108 A user supplied function to transform the original map data 4109 coordinates to a new coordinate system. The PLplot-supplied map 4110 data is provided as latitudes and longitudes; other Shapefile data 4111 may be provided in other coordinate systems as can be found in 4112 their .prj plain text files. For example, by using this transform 4113 we can change from a longitude, latitude coordinate to a polar 4114 stereographic projection. Initially, x[0]..[n-1] are the original 4115 x coordinates (longitudes for the PLplot-supplied data) and 4116 y[0]..y[n-1] are the corresponding y coordinates (latitudes for the 4117 PLplot supplied data). After the call to mapform(), x[] and y[] 4118 should be replaced by the corresponding plot coordinates. If no 4119 transform is desired, mapform can be replaced by NULL. 4120 4121‘name’ (‘‘PLCHAR_VECTOR’ (*note PLCHAR_VECTOR-type::)’, input) 4122 An ascii character string specifying the type of map plotted. This 4123 is either one of the PLplot built-in maps or the file name of a set 4124 of Shapefile files without the file extensions. For the PLplot 4125 built-in maps the possible values are: 4126 4127 • ‘"globe"’ – continental outlines 4128 4129 • ‘"usa"’ – USA and state boundaries 4130 4131 • ‘"cglobe"’ – continental outlines and countries 4132 4133 • ‘"usaglobe"’ – USA, state boundaries and continental outlines 4134 4135‘minx’ (‘‘PLFLT’ (*note PLFLT-type::)’, input) 4136 The minimum x value of map elements to be drawn. The units must 4137 match the shapefile (built in maps are degrees lat/lon). Objects 4138 in the file which do not encroach on the box defined by minx, maxx, 4139 miny, maxy will not be rendered. But note this is simply an 4140 optimisation, not a clipping so for objects with some points inside 4141 the box and some points outside the box all the points will be 4142 rendered. These parameters also define latitude and longitude 4143 wrapping for shapefiles using these units. Longitude points will 4144 be wrapped by integer multiples of 360 degrees to place them in the 4145 box. This allows the same data to be used on plots from -180-180 4146 or 0-360 longitude ranges. In fact if you plot from -180-540 you 4147 will get two cycles of data drawn. The value of minx must be less 4148 than the value of maxx. Passing in a nan, max/-max floating point 4149 number or +/-infinity will case the bounding box from the shapefile 4150 to be used. 4151 4152‘maxx’ (‘‘PLFLT’ (*note PLFLT-type::)’, input) 4153 The maximum x value of map elements to be drawn - see minx. 4154 4155‘miny’ (‘‘PLFLT’ (*note PLFLT-type::)’, input) 4156 The minimum y value of map elements to be drawn - see minx. 4157 4158‘maxy’ (‘‘PLFLT’ (*note PLFLT-type::)’, input) 4159 The maximum y value of map elements to be drawn - see minx. 4160 4161 Redacted form: ‘plmap(mapform, name, minx, maxx, miny, maxy)’ 4162 4163 This function is used in example 19. 4164 4165 4166File: plplotdoc.info, Node: plmapfill; Plot all or a subset of Shapefile data; filling the polygons, Next: plmapline; Plot all or a subset of Shapefile data using lines in world coordinates, Prev: plmap; Plot continental outline or shapefile data in world coordinates, Up: The Common API for PLplot 4167 416817.76 plmapfill: Plot all or a subset of Shapefile data, filling the polygons 4169============================================================================= 4170 4171 plmapfill ( mapform , name , minx , maxx , miny , maxy , 4172 plotentries , nplotentries ); 4173 4174 As per ‘plmapline’ (*note plmapline; Plot all or a subset of 4175Shapefile data using lines in world coordinates::), however the items 4176are filled in the same way as ‘plfill’ (*note plfill; Draw filled 4177polygon::). 4178 4179‘mapform’ (‘‘PLMAPFORM_callback’ (*note PLMAPFORM_callback-type::)’, input) 4180 A user supplied function to transform the coordinates given in the 4181 shapefile into a plot coordinate system. By using this transform, 4182 we can change from a longitude, latitude coordinate to a polar 4183 stereographic project, for example. Initially, x[0]..[n-1] are the 4184 longitudes and y[0]..y[n-1] are the corresponding latitudes. After 4185 the call to mapform(), x[] and y[] should be replaced by the 4186 corresponding plot coordinates. If no transform is desired, 4187 mapform can be replaced by NULL. 4188 4189‘name’ (‘‘PLCHAR_VECTOR’ (*note PLCHAR_VECTOR-type::)’, input) 4190 An ascii character string specifying the file name of a set of 4191 Shapefile files without the file extension. 4192 4193‘minx’ (‘‘PLFLT’ (*note PLFLT-type::)’, input) 4194 The minimum x value to be plotted. This must be in the same units 4195 as used by the Shapefile. You could use a very large negative 4196 number to plot everything, but you can improve performance by 4197 limiting the area drawn. The units must match those of the 4198 Shapefile projection, which may be for example longitude or 4199 distance. The value of minx must be less than the value of maxx. 4200 4201‘maxx’ (‘‘PLFLT’ (*note PLFLT-type::)’, input) 4202 The maximum x value to be plotted. You could use a very large 4203 number to plot everything, but you can improve performance by 4204 limiting the area drawn. 4205 4206‘miny’ (‘‘PLFLT’ (*note PLFLT-type::)’, input) 4207 The minimum y value to be plotted. This must be in the same units 4208 as used by the Shapefile. You could use a very large negative 4209 number to plot everything, but you can improve performance by 4210 limiting the area drawn. The units must match those of the 4211 Shapefile projection, which may be for example latitude or 4212 distance. The value of miny must be less than the value of maxy. 4213 4214‘maxy’ (‘‘PLFLT’ (*note PLFLT-type::)’, input) 4215 The maximum y value to be plotted. You could use a very large 4216 number to plot everything, but you can improve performance by 4217 limiting the area drawn. 4218 4219‘plotentries’ (‘‘PLINT_VECTOR’ (*note PLINT_VECTOR-type::)’, input) 4220 A vector containing the zero-based indices of the Shapefile 4221 elements which will be drawn. Setting ‘plotentries’ to NULL will 4222 plot all elements of the Shapefile. 4223 4224‘nplotentries’ (‘‘PLINT’ (*note PLINT-type::)’, input) 4225 The number of items in ‘plotentries’. Ignored if ‘plotentries’ is 4226 NULL. 4227 4228 Redacted form: ‘plmapfill(mapform, name, minx, maxx, miny, maxy, 4229plotentries)’ 4230 4231 This function is used in example 19. 4232 4233 4234File: plplotdoc.info, Node: plmapline; Plot all or a subset of Shapefile data using lines in world coordinates, Next: plmapstring; Plot all or a subset of Shapefile data using strings or points in world coordinates, Prev: plmapfill; Plot all or a subset of Shapefile data; filling the polygons, Up: The Common API for PLplot 4235 423617.77 plmapline: Plot all or a subset of Shapefile data using lines in world coordinates 4237======================================================================================== 4238 4239 plmapline ( mapform , name , minx , maxx , miny , maxy , 4240 plotentries , nplotentries ); 4241 4242 Plot all or a subset of Shapefile data using lines in world 4243coordinates. Our 19th standard example demonstrates how to use this 4244function. This function plots data from a Shapefile using lines as in 4245‘plmap’ (*note plmap; Plot continental outline or shapefile data in 4246world coordinates::), however it also has the option of also only 4247drawing specified elements from the Shapefile. The vector of indices of 4248the required elements are passed as a function argument. The Shapefile 4249data should include a metadata file (extension.dbf) listing all items 4250within the Shapefile. This file can be opened by most popular 4251spreadsheet programs and can be used to decide which indices to pass to 4252this function. 4253 4254‘mapform’ (‘‘PLMAPFORM_callback’ (*note PLMAPFORM_callback-type::)’, input) 4255 A user supplied function to transform the coordinates given in the 4256 shapefile into a plot coordinate system. By using this transform, 4257 we can change from a longitude, latitude coordinate to a polar 4258 stereographic project, for example. Initially, x[0]..[n-1] are the 4259 longitudes and y[0]..y[n-1] are the corresponding latitudes. After 4260 the call to mapform(), x[] and y[] should be replaced by the 4261 corresponding plot coordinates. If no transform is desired, 4262 mapform can be replaced by NULL. 4263 4264‘name’ (‘‘PLCHAR_VECTOR’ (*note PLCHAR_VECTOR-type::)’, input) 4265 An ascii character string specifying the file name of a set of 4266 Shapefile files without the file extension. 4267 4268‘minx’ (‘‘PLFLT’ (*note PLFLT-type::)’, input) 4269 The minimum x value to be plotted. This must be in the same units 4270 as used by the Shapefile. You could use a very large negative 4271 number to plot everything, but you can improve performance by 4272 limiting the area drawn. The units must match those of the 4273 Shapefile projection, which may be for example longitude or 4274 distance. The value of minx must be less than the value of maxx. 4275 4276‘maxx’ (‘‘PLFLT’ (*note PLFLT-type::)’, input) 4277 The maximum x value to be plotted. You could use a very large 4278 number to plot everything, but you can improve performance by 4279 limiting the area drawn. 4280 4281‘miny’ (‘‘PLFLT’ (*note PLFLT-type::)’, input) 4282 The minimum y value to be plotted. This must be in the same units 4283 as used by the Shapefile. You could use a very large negative 4284 number to plot everything, but you can improve performance by 4285 limiting the area drawn. The units must match those of the 4286 Shapefile projection, which may be for example latitude or 4287 distance. The value of miny must be less than the value of maxy. 4288 4289‘maxy’ (‘‘PLFLT’ (*note PLFLT-type::)’, input) 4290 The maximum y value to be plotted. You could use a very large 4291 number to plot everything, but you can improve performance by 4292 limiting the area drawn. 4293 4294‘plotentries’ (‘‘PLINT_VECTOR’ (*note PLINT_VECTOR-type::)’, input) 4295 A vector containing the zero-based indices of the Shapefile 4296 elements which will be drawn. Setting ‘plotentries’ to NULL will 4297 plot all elements of the Shapefile. 4298 4299‘nplotentries’ (‘‘PLINT’ (*note PLINT-type::)’, input) 4300 The number of items in ‘plotentries’. Ignored if ‘plotentries’ is 4301 NULL. 4302 4303 Redacted form: ‘plmapline(mapform, name, minx, maxx, miny, maxy, 4304plotentries)’ 4305 4306 This function is used in example 19. 4307 4308 4309File: plplotdoc.info, Node: plmapstring; Plot all or a subset of Shapefile data using strings or points in world coordinates, Next: plmaptex; Draw text at points defined by Shapefile data in world coordinates, Prev: plmapline; Plot all or a subset of Shapefile data using lines in world coordinates, Up: The Common API for PLplot 4310 431117.78 plmapstring: Plot all or a subset of Shapefile data using strings or points in world coordinates 4312====================================================================================================== 4313 4314 plmapstring ( mapform , name , string , minx , maxx , miny , maxy , 4315 plotentries , nplotentries ); 4316 4317 As per ‘plmapline’ (*note plmapline; Plot all or a subset of 4318Shapefile data using lines in world coordinates::), however the items 4319are plotted as strings or points in the same way as ‘plstring’ (*note 4320plstring; Plot a glyph at the specified points::). 4321 4322‘mapform’ (‘‘PLMAPFORM_callback’ (*note PLMAPFORM_callback-type::)’, input) 4323 A user supplied function to transform the coordinates given in the 4324 shapefile into a plot coordinate system. By using this transform, 4325 we can change from a longitude, latitude coordinate to a polar 4326 stereographic project, for example. Initially, x[0]..[n-1] are the 4327 longitudes and y[0]..y[n-1] are the corresponding latitudes. After 4328 the call to mapform(), x[] and y[] should be replaced by the 4329 corresponding plot coordinates. If no transform is desired, 4330 mapform can be replaced by NULL. 4331 4332‘name’ (‘‘PLCHAR_VECTOR’ (*note PLCHAR_VECTOR-type::)’, input) 4333 An ascii character string specifying the file name of a set of 4334 Shapefile files without the file extension. 4335 4336‘string’ (‘‘PLCHAR_VECTOR’ (*note PLCHAR_VECTOR-type::)’, input) 4337 A UTF-8 character string to be drawn. 4338 4339‘minx’ (‘‘PLFLT’ (*note PLFLT-type::)’, input) 4340 The minimum x value to be plotted. This must be in the same units 4341 as used by the Shapefile. You could use a very large negative 4342 number to plot everything, but you can improve performance by 4343 limiting the area drawn. The units must match those of the 4344 Shapefile projection, which may be for example longitude or 4345 distance. The value of minx must be less than the value of maxx. 4346 4347‘maxx’ (‘‘PLFLT’ (*note PLFLT-type::)’, input) 4348 The maximum x value to be plotted. You could use a very large 4349 number to plot everything, but you can improve performance by 4350 limiting the area drawn. 4351 4352‘miny’ (‘‘PLFLT’ (*note PLFLT-type::)’, input) 4353 The minimum y value to be plotted. This must be in the same units 4354 as used by the Shapefile. You could use a very large negative 4355 number to plot everything, but you can improve performance by 4356 limiting the area drawn. The units must match those of the 4357 Shapefile projection, which may be for example latitude or 4358 distance. The value of miny must be less than the value of maxy. 4359 4360‘maxy’ (‘‘PLFLT’ (*note PLFLT-type::)’, input) 4361 The maximum y value to be plotted. You could use a very large 4362 number to plot everything, but you can improve performance by 4363 limiting the area drawn. 4364 4365‘plotentries’ (‘‘PLINT_VECTOR’ (*note PLINT_VECTOR-type::)’, input) 4366 A vector containing the zero-based indices of the Shapefile 4367 elements which will be drawn. Setting ‘plotentries’ to NULL will 4368 plot all elements of the Shapefile. 4369 4370‘nplotentries’ (‘‘PLINT’ (*note PLINT-type::)’, input) 4371 The number of items in ‘plotentries’. Ignored if ‘plotentries’ is 4372 NULL. 4373 4374 Redacted form: ‘plmapstring(mapform, name, string, minx, maxx, miny, 4375maxy, plotentries)’ 4376 4377 This function is not used in any examples. 4378 4379 4380File: plplotdoc.info, Node: plmaptex; Draw text at points defined by Shapefile data in world coordinates, Next: plmeridians; Plot latitude and longitude lines, Prev: plmapstring; Plot all or a subset of Shapefile data using strings or points in world coordinates, Up: The Common API for PLplot 4381 438217.79 plmaptex: Draw text at points defined by Shapefile data in world coordinates 4383================================================================================== 4384 4385 plmaptex ( mapform , name , dx , dy , just , text , minx , maxx , 4386 miny , maxy , plotentry ); 4387 4388 As per ‘plmapline’ (*note plmapline; Plot all or a subset of 4389Shapefile data using lines in world coordinates::), however the items 4390are plotted as text in the same way as ‘plptex’ (*note plptex; Write 4391text inside the viewport::). 4392 4393‘mapform’ (‘‘PLMAPFORM_callback’ (*note PLMAPFORM_callback-type::)’, input) 4394 A user supplied function to transform the coordinates given in the 4395 shapefile into a plot coordinate system. By using this transform, 4396 we can change from a longitude, latitude coordinate to a polar 4397 stereographic project, for example. Initially, x[0]..[n-1] are the 4398 longitudes and y[0]..y[n-1] are the corresponding latitudes. After 4399 the call to mapform(), x[] and y[] should be replaced by the 4400 corresponding plot coordinates. If no transform is desired, 4401 mapform can be replaced by NULL. 4402 4403‘name’ (‘‘PLCHAR_VECTOR’ (*note PLCHAR_VECTOR-type::)’, input) 4404 An ascii character string specifying the file name of a set of 4405 Shapefile files without the file extension. 4406 4407‘dx’ (‘‘PLFLT’ (*note PLFLT-type::)’, input) 4408 Used to define the slope of the texts which is dy/dx. 4409 4410‘dy’ (‘‘PLFLT’ (*note PLFLT-type::)’, input) 4411 Used to define the slope of the texts which is dy/dx. 4412 4413‘just’ (‘‘PLFLT’ (*note PLFLT-type::)’, input) 4414 Set the justification of the text. The value given will be the 4415 fraction of the distance along the string that sits at the given 4416 point. 0.0 gives left aligned text, 0.5 gives centralized text and 4417 1.0 gives right aligned text. 4418 4419‘text’ (‘‘PLCHAR_VECTOR’ (*note PLCHAR_VECTOR-type::)’, input) 4420 A UTF-8 character string to be drawn. 4421 4422‘minx’ (‘‘PLFLT’ (*note PLFLT-type::)’, input) 4423 The minimum x value to be plotted. This must be in the same units 4424 as used by the Shapefile. You could use a very large negative 4425 number to plot everything, but you can improve performance by 4426 limiting the area drawn. The units must match those of the 4427 Shapefile projection, which may be for example longitude or 4428 distance. The value of minx must be less than the value of maxx. 4429 4430‘maxx’ (‘‘PLFLT’ (*note PLFLT-type::)’, input) 4431 The maximum x value to be plotted. You could use a very large 4432 number to plot everything, but you can improve performance by 4433 limiting the area drawn. 4434 4435‘miny’ (‘‘PLFLT’ (*note PLFLT-type::)’, input) 4436 The minimum y value to be plotted. This must be in the same units 4437 as used by the Shapefile. You could use a very large negative 4438 number to plot everything, but you can improve performance by 4439 limiting the area drawn. The units must match those of the 4440 Shapefile projection, which may be for example latitude or 4441 distance. The value of miny must be less than the value of maxy. 4442 4443‘maxy’ (‘‘PLFLT’ (*note PLFLT-type::)’, input) 4444 The maximum y value to be plotted. You could use a very large 4445 number to plot everything, but you can improve performance by 4446 limiting the area drawn. 4447 4448‘plotentry’ (‘‘PLINT’ (*note PLINT-type::)’, input) 4449 An integer indicating which text string of the Shapefile (zero 4450 indexed) will be drawn. 4451 4452 Redacted form: ‘plmaptex(mapform, name, dx, dy, just, text, minx, 4453maxx, miny, maxy, plotentry)’ 4454 4455 This function is used in example 19. 4456 4457 4458File: plplotdoc.info, Node: plmeridians; Plot latitude and longitude lines, Next: plmesh; Plot surface mesh, Prev: plmaptex; Draw text at points defined by Shapefile data in world coordinates, Up: The Common API for PLplot 4459 446017.80 plmeridians: Plot latitude and longitude lines 4461==================================================== 4462 4463 plmeridians ( mapform , dlong , dlat , minlong , maxlong , minlat , 4464 maxlat ); 4465 4466 Displays latitude and longitude on the current plot. The lines are 4467plotted in the current color and line style. 4468 4469‘mapform’ (‘‘PLMAPFORM_callback’ (*note PLMAPFORM_callback-type::)’, input) 4470 A user supplied function to transform the coordinate longitudes and 4471 latitudes to a plot coordinate system. By using this transform, we 4472 can change from a longitude, latitude coordinate to a polar 4473 stereographic project, for example. Initially, x[0]..[n-1] are the 4474 longitudes and y[0]..y[n-1] are the corresponding latitudes. After 4475 the call to mapform(), x[] and y[] should be replaced by the 4476 corresponding plot coordinates. If no transform is desired, 4477 mapform can be replaced by NULL. 4478 4479‘dlong’ (‘‘PLFLT’ (*note PLFLT-type::)’, input) 4480 The interval in degrees at which the longitude lines are to be 4481 plotted. 4482 4483‘dlat’ (‘‘PLFLT’ (*note PLFLT-type::)’, input) 4484 The interval in degrees at which the latitude lines are to be 4485 plotted. 4486 4487‘minlong’ (‘‘PLFLT’ (*note PLFLT-type::)’, input) 4488 The value of the longitude on the left side of the plot. The value 4489 of minlong must be less than the value of maxlong, and the quantity 4490 maxlong-minlong must be less than or equal to 360. 4491 4492‘maxlong’ (‘‘PLFLT’ (*note PLFLT-type::)’, input) 4493 The value of the longitude on the right side of the plot. 4494 4495‘minlat’ (‘‘PLFLT’ (*note PLFLT-type::)’, input) 4496 The minimum latitude to be plotted on the background. One can 4497 always use -90.0 as the boundary outside the plot window will be 4498 automatically eliminated. However, the program will be faster if 4499 one can reduce the size of the background plotted. 4500 4501‘maxlat’ (‘‘PLFLT’ (*note PLFLT-type::)’, input) 4502 The maximum latitudes to be plotted on the background. One can 4503 always use 90.0 as the boundary outside the plot window will be 4504 automatically eliminated. 4505 4506 Redacted form: ‘plmeridians(mapform, dlong, dlat, minlong, maxlong, 4507minlat, maxlat)’ 4508 4509 This function is used in example 19. 4510 4511 4512File: plplotdoc.info, Node: plmesh; Plot surface mesh, Next: plmeshc; Magnitude colored plot surface mesh with contour, Prev: plmeridians; Plot latitude and longitude lines, Up: The Common API for PLplot 4513 451417.81 plmesh: Plot surface mesh 4515=============================== 4516 4517 plmesh ( x , y , z , nx , ny , opt ); 4518 4519 Plots a surface mesh within the environment set up by ‘plw3d’ (*note 4520plw3d; Configure the transformations required for projecting a 3D 4521surface on a 2D window::). The surface is defined by the matrix ‘ 4522‘z’[‘nx’][‘ny’] ’, the point ‘‘z’[i][j]’ being the value of the function 4523at ‘(‘x’[i], ‘y’[j])’. Note that the points in vectors ‘‘x’’ and ‘‘y’’ 4524do not need to be equally spaced, but must be stored in ascending order. 4525The parameter ‘‘opt’’ controls the way in which the surface is 4526displayed. For further details see *note Three-dimensional Plots::. 4527 4528‘x’ (‘‘PLFLT_VECTOR’ (*note PLFLT_VECTOR-type::)’, input) 4529 A vector containing the x coordinates at which the function is 4530 evaluated. 4531 4532‘y’ (‘‘PLFLT_VECTOR’ (*note PLFLT_VECTOR-type::)’, input) 4533 A vector containing the y coordinates at which the function is 4534 evaluated. 4535 4536‘z’ (‘‘PLFLT_MATRIX’ (*note PLFLT_MATRIX-type::)’, input) 4537 A matrix containing function values to plot. Should have 4538 dimensions of ‘nx’ by ‘ny’. 4539 4540‘nx’ (‘‘PLINT’ (*note PLINT-type::)’, input) 4541 Number of ‘‘x’’ values at which function has been evaluated. 4542 4543‘ny’ (‘‘PLINT’ (*note PLINT-type::)’, input) 4544 Number of ‘‘y’’ values at which function has been evaluated. 4545 4546‘opt’ (‘‘PLINT’ (*note PLINT-type::)’, input) 4547 Determines the way in which the surface is represented: 4548 4549 • ‘ ‘opt’=DRAW_LINEX ’: Lines are drawn showing ‘ ‘z’ ’ as a 4550 function of ‘ ‘x’ ’ for each value of ‘ ‘y’[j] ’. 4551 4552 • ‘ ‘opt’=DRAW_LINEY ’: Lines are drawn showing ‘ ‘z’ ’ as a 4553 function of ‘ ‘y’ ’ for each value of ‘ ‘x’[i] ’. 4554 4555 • ‘ ‘opt’=DRAW_LINEXY ’: Network of lines is drawn connecting 4556 points at which function is defined. 4557 4558 Redacted form: ‘plmesh(x, y, z, opt)’ 4559 4560 This function is used in example 11. 4561 4562 4563File: plplotdoc.info, Node: plmeshc; Magnitude colored plot surface mesh with contour, Next: plmkstrm; Creates a new stream and makes it the default, Prev: plmesh; Plot surface mesh, Up: The Common API for PLplot 4564 456517.82 plmeshc: Magnitude colored plot surface mesh with contour 4566=============================================================== 4567 4568 plmeshc ( x , y , z , nx , ny , opt , clevel , nlevel ); 4569 4570 A more powerful form of ‘plmesh (*note plmesh; Plot surface mesh::)’: 4571the surface mesh can be colored accordingly to the current z value being 4572plotted, a contour plot can be drawn at the base XY plane, and a curtain 4573can be drawn between the plotted function border and the base XY plane. 4574 4575‘x’ (‘‘PLFLT_VECTOR’ (*note PLFLT_VECTOR-type::)’, input) 4576 A vector containing the x coordinates at which the function is 4577 evaluated. 4578 4579‘y’ (‘‘PLFLT_VECTOR’ (*note PLFLT_VECTOR-type::)’, input) 4580 A vector containing the y coordinates at which the function is 4581 evaluated. 4582 4583‘z’ (‘‘PLFLT_MATRIX’ (*note PLFLT_MATRIX-type::)’, input) 4584 A matrix containing function values to plot. Should have 4585 dimensions of ‘nx’ by ‘ny’. 4586 4587‘nx’ (‘‘PLINT’ (*note PLINT-type::)’, input) 4588 Number of ‘‘x’’ values at which function is evaluated. 4589 4590‘ny’ (‘‘PLINT’ (*note PLINT-type::)’, input) 4591 Number of ‘‘y’’ values at which function is evaluated. 4592 4593‘opt’ (‘‘PLINT’ (*note PLINT-type::)’, input) 4594 Determines the way in which the surface is represented. To specify 4595 more than one option just add the options, e.g. DRAW_LINEXY + 4596 MAG_COLOR 4597 4598 • ‘ ‘opt’=DRAW_LINEX ’: Lines are drawn showing ‘ ‘z’ ’ as a 4599 function of ‘ ‘x’ ’ for each value of ‘ ‘y’[j] ’. 4600 4601 • ‘ ‘opt’=DRAW_LINEY ’: Lines are drawn showing ‘ ‘z’ ’ as a 4602 function of ‘ ‘y’ ’ for each value of ‘ ‘x’[i] ’. 4603 4604 • ‘ ‘opt’=DRAW_LINEXY ’: Network of lines is drawn connecting 4605 points at which function is defined. 4606 4607 • ‘ ‘opt’=MAG_COLOR ’: Each line in the mesh is colored 4608 according to the z value being plotted. The color is used 4609 from the current cmap1. 4610 4611 • ‘ ‘opt’=BASE_CONT ’: A contour plot is drawn at the base XY 4612 plane using parameters ‘nlevel’ and ‘clevel’. 4613 4614 • ‘ ‘opt’=DRAW_SIDES ’: draws a curtain between the base XY 4615 plane and the borders of the plotted function. 4616 4617‘clevel’ (‘‘PLFLT_VECTOR’ (*note PLFLT_VECTOR-type::)’, input) 4618 A vector containing the contour levels. 4619 4620‘nlevel’ (‘‘PLINT’ (*note PLINT-type::)’, input) 4621 Number of elements in the ‘clevel’ vector. 4622 4623 Redacted form: ‘plmeshc(x, y, z, opt, clevel)’ 4624 4625 This function is used in example 11. 4626 4627 4628File: plplotdoc.info, Node: plmkstrm; Creates a new stream and makes it the default, Next: plmtex; Write text relative to viewport boundaries, Prev: plmeshc; Magnitude colored plot surface mesh with contour, Up: The Common API for PLplot 4629 463017.83 plmkstrm: Creates a new stream and makes it the default 4631============================================================= 4632 4633 plmkstrm ( p_strm ); 4634 4635 Creates a new stream and makes it the default. Differs from using 4636‘plsstrm’ (*note plsstrm; Set current output stream::), in that a free 4637stream number is found, and returned. Unfortunately, I _have_ to start 4638at stream 1 and work upward, since stream 0 is preallocated. One of the 4639_big_ flaws in the PLplot API is that no initial, library-opening call 4640is required. So stream 0 must be preallocated, and there is no simple 4641way of determining whether it is already in use or not. 4642 4643‘p_strm’ (‘‘PLINT_NC_SCALAR’ (*note PLINT_NC_SCALAR-type::)’, output) 4644 Returned value of the stream number of the created stream. 4645 4646 Redacted form: ‘plmkstrm(p_strm)’ 4647 4648 This function is used in examples 1 and 20. 4649 4650 4651File: plplotdoc.info, Node: plmtex; Write text relative to viewport boundaries, Next: plmtex3; Write text relative to viewport boundaries in 3D plots, Prev: plmkstrm; Creates a new stream and makes it the default, Up: The Common API for PLplot 4652 465317.84 plmtex: Write text relative to viewport boundaries 4654======================================================== 4655 4656 plmtex ( side , disp , pos , just , text ); 4657 4658 Writes text at a specified position relative to the viewport 4659boundaries. Text may be written inside or outside the viewport, but is 4660clipped at the subpage boundaries. The reference point of a string lies 4661along a line passing through the string at half the height of a capital 4662letter. The position of the reference point along this line is 4663determined by ‘ ‘just’ ’, and the position of the reference point 4664relative to the viewport is set by ‘ ‘disp’ ’ and ‘ ‘pos’ ’. 4665 4666‘side’ (‘‘PLCHAR_VECTOR’ (*note PLCHAR_VECTOR-type::)’, input) 4667 An ascii character string specifying the side of the viewport along 4668 which the text is to be written. The string must be one of: 4669 4670 • ‘b’: Bottom of viewport, text written parallel to edge. 4671 4672 • ‘bv’: Bottom of viewport, text written at right angles to 4673 edge. 4674 4675 • ‘l’: Left of viewport, text written parallel to edge. 4676 4677 • ‘lv’: Left of viewport, text written at right angles to edge. 4678 4679 • ‘r’: Right of viewport, text written parallel to edge. 4680 4681 • ‘rv’: Right of viewport, text written at right angles to edge. 4682 4683 • ‘t’: Top of viewport, text written parallel to edge. 4684 4685 • ‘tv’: Top of viewport, text written at right angles to edge. 4686 4687‘disp’ (‘‘PLFLT’ (*note PLFLT-type::)’, input) 4688 Position of the reference point of string, measured outwards from 4689 the specified viewport edge in units of the current character 4690 height. Use negative ‘‘disp’’ to write within the viewport. 4691 4692‘pos’ (‘‘PLFLT’ (*note PLFLT-type::)’, input) 4693 Position of the reference point of string along the specified edge, 4694 expressed as a fraction of the length of the edge. 4695 4696‘just’ (‘‘PLFLT’ (*note PLFLT-type::)’, input) 4697 Specifies the position of the string relative to its reference 4698 point. If ‘ ‘just’=0. ’, the reference point is at the left and if 4699 ‘ ‘just’=1. ’, it is at the right of the string. Other values of ‘ 4700 ‘just’ ’ give intermediate justifications. 4701 4702‘text’ (‘‘PLCHAR_VECTOR’ (*note PLCHAR_VECTOR-type::)’, input) 4703 A UTF-8 character string to be written out. 4704 4705 Redacted form: 4706 4707 • General: ‘plmtex(side, disp, pos, just, text)’ 4708 4709 This function is used in examples 3, 4, 6-8, 11, 12, 14, 18, 23, and 471026. 4711 4712 4713File: plplotdoc.info, Node: plmtex3; Write text relative to viewport boundaries in 3D plots, Next: plot3d; Plot 3-d surface plot, Prev: plmtex; Write text relative to viewport boundaries, Up: The Common API for PLplot 4714 471517.85 plmtex3: Write text relative to viewport boundaries in 3D plots 4716===================================================================== 4717 4718 plmtex3 ( side , disp , pos , just , text ); 4719 4720 Writes text at a specified position relative to the viewport 4721boundaries. Text may be written inside or outside the viewport, but is 4722clipped at the subpage boundaries. The reference point of a string lies 4723along a line passing through the string at half the height of a capital 4724letter. The position of the reference point along this line is 4725determined by ‘ ‘just’ ’, and the position of the reference point 4726relative to the viewport is set by ‘ ‘disp’ ’ and ‘ ‘pos’ ’. 4727 4728‘side’ (‘‘PLCHAR_VECTOR’ (*note PLCHAR_VECTOR-type::)’, input) 4729 An ascii character string specifying the side of the viewport along 4730 which the text is to be written. The string should contain one or 4731 more of the following characters: ‘[xyz][ps][v]’. Only one label 4732 is drawn at a time, i.e. ‘xyp’ will only label the X axis, not 4733 both the X and Y axes. 4734 4735 • ‘x’: Label the X axis. 4736 4737 • ‘y’: Label the Y axis. 4738 4739 • ‘z’: Label the Z axis. 4740 4741 • ‘p’: Label the ‘primary’ axis. For Z this is the leftmost Z 4742 axis. For X it is the axis that starts at y-min. For Y it is 4743 the axis that starts at x-min. 4744 4745 • ‘s’: Label the ‘secondary’ axis. 4746 4747 • ‘v’: Draw the text perpendicular to the axis. 4748 4749‘disp’ (‘‘PLFLT’ (*note PLFLT-type::)’, input) 4750 Position of the reference point of string, measured outwards from 4751 the specified viewport edge in units of the current character 4752 height. Use negative ‘‘disp’’ to write within the viewport. 4753 4754‘pos’ (‘‘PLFLT’ (*note PLFLT-type::)’, input) 4755 Position of the reference point of string along the specified edge, 4756 expressed as a fraction of the length of the edge. 4757 4758‘just’ (‘‘PLFLT’ (*note PLFLT-type::)’, input) 4759 Specifies the position of the string relative to its reference 4760 point. If ‘ ‘just’=0. ’, the reference point is at the left and if 4761 ‘ ‘just’=1. ’, it is at the right of the string. Other values of ‘ 4762 ‘just’ ’ give intermediate justifications. 4763 4764‘text’ (‘‘PLCHAR_VECTOR’ (*note PLCHAR_VECTOR-type::)’, input) 4765 A UTF-8 character string to be written out. 4766 4767 Redacted form: ‘plmtex3(side, disp, pos, just, text)’ 4768 4769 This function is used in example 28. 4770 4771 4772File: plplotdoc.info, Node: plot3d; Plot 3-d surface plot, Next: plot3dc; Magnitude colored plot surface with contour, Prev: plmtex3; Write text relative to viewport boundaries in 3D plots, Up: The Common API for PLplot 4773 477417.86 plot3d: Plot 3-d surface plot 4775=================================== 4776 4777 plot3d ( x , y , z , nx , ny , opt , side ); 4778 4779 Plots a three-dimensional surface plot within the environment set up 4780by ‘plw3d’ (*note plw3d; Configure the transformations required for 4781projecting a 3D surface on a 2D window::). The surface is defined by 4782the matrix ‘ ‘z’[‘nx’][‘ny’] ’, the point ‘‘z’[i][j]’ being the value of 4783the function at ‘(‘x’[i],‘y’[j])’. Note that the points in vectors 4784‘‘x’’ and ‘‘y’’ do not need to be equally spaced, but must be stored in 4785ascending order. The parameter ‘‘opt’’ controls the way in which the 4786surface is displayed. For further details see *note Three-dimensional 4787Plots::. The only difference between ‘plmesh’ (*note plmesh; Plot 4788surface mesh::) and ‘plot3d’ (*note plot3d; Plot 3-d surface plot::) is 4789that ‘plmesh’ (*note plmesh; Plot surface mesh::) draws the bottom side 4790of the surface, while ‘plot3d’ (*note plot3d; Plot 3-d surface plot::) 4791only draws the surface as viewed from the top. 4792 4793‘x’ (‘‘PLFLT_VECTOR’ (*note PLFLT_VECTOR-type::)’, input) 4794 A vector containing the x coordinates at which the function is 4795 evaluated. 4796 4797‘y’ (‘‘PLFLT_VECTOR’ (*note PLFLT_VECTOR-type::)’, input) 4798 A vector containing the y coordinates at which the function is 4799 evaluated. 4800 4801‘z’ (‘‘PLFLT_MATRIX’ (*note PLFLT_MATRIX-type::)’, input) 4802 A matrix containing function values to plot. Should have 4803 dimensions of ‘nx’ by ‘ny’. 4804 4805‘nx’ (‘‘PLINT’ (*note PLINT-type::)’, input) 4806 Number of ‘‘x’’ values at which function is evaluated. 4807 4808‘ny’ (‘‘PLINT’ (*note PLINT-type::)’, input) 4809 Number of ‘‘y’’ values at which function is evaluated. 4810 4811‘opt’ (‘‘PLINT’ (*note PLINT-type::)’, input) 4812 Determines the way in which the surface is represented: 4813 4814 • ‘ ‘opt’=DRAW_LINEX ’: Lines are drawn showing ‘ ‘z’ ’ as a 4815 function of ‘ ‘x’ ’ for each value of ‘ ‘y’[j] ’. 4816 4817 • ‘ ‘opt’=DRAW_LINEY ’: Lines are drawn showing ‘ ‘z’ ’ as a 4818 function of ‘ ‘y’ ’ for each value of ‘ ‘x’[i] ’. 4819 4820 • ‘ ‘opt’=DRAW_LINEXY ’: Network of lines is drawn connecting 4821 points at which function is defined. 4822 4823‘side’ (‘‘PLBOOL’ (*note PLBOOL-type::)’, input) 4824 Flag to indicate whether or not “sides” should be draw on the 4825 figure. If ‘ ‘side’ ’ is true sides are drawn, otherwise no sides 4826 are drawn. 4827 4828 Redacted form: ‘plot3d(x, y, z, opt, side)’ 4829 4830 This function is used in examples 11 and 21. 4831 4832 4833File: plplotdoc.info, Node: plot3dc; Magnitude colored plot surface with contour, Next: plot3dcl; Magnitude colored plot surface with contour for z[x][y] with y index limits, Prev: plot3d; Plot 3-d surface plot, Up: The Common API for PLplot 4834 483517.87 plot3dc: Magnitude colored plot surface with contour 4836========================================================== 4837 4838 plot3dc ( x , y , z , nx , ny , opt , clevel , nlevel ); 4839 4840 Aside from dropping the ‘side’ functionality this is a more powerful 4841form of ‘plot3d (*note plot3d; Plot 3-d surface plot::)’: the surface 4842mesh can be colored accordingly to the current z value being plotted, a 4843contour plot can be drawn at the base XY plane, and a curtain can be 4844drawn between the plotted function border and the base XY plane. The 4845arguments are identical to those of ‘plmeshc (*note plmeshc; Magnitude 4846colored plot surface mesh with contour::)’. The only difference between 4847‘plmeshc’ (*note plmeshc; Magnitude colored plot surface mesh with 4848contour::) and ‘plot3dc’ (*note plot3dc; Magnitude colored plot surface 4849with contour::) is that ‘plmeshc’ (*note plmeshc; Magnitude colored plot 4850surface mesh with contour::) draws the bottom side of the surface, while 4851‘plot3dc’ (*note plot3dc; Magnitude colored plot surface with contour::) 4852only draws the surface as viewed from the top. 4853 4854‘x’ (‘‘PLFLT_VECTOR’ (*note PLFLT_VECTOR-type::)’, input) 4855 A vector containing the x coordinates at which the function is 4856 evaluated. 4857 4858‘y’ (‘‘PLFLT_VECTOR’ (*note PLFLT_VECTOR-type::)’, input) 4859 A vector containing the y coordinates at which the function is 4860 evaluated. 4861 4862‘z’ (‘‘PLFLT_MATRIX’ (*note PLFLT_MATRIX-type::)’, input) 4863 A matrix containing function values to plot. Should have 4864 dimensions of ‘nx’ by ‘ny’. 4865 4866‘nx’ (‘‘PLINT’ (*note PLINT-type::)’, input) 4867 Number of ‘‘x’’ values at which function is evaluated. 4868 4869‘ny’ (‘‘PLINT’ (*note PLINT-type::)’, input) 4870 Number of ‘ ‘y’ ’ values at which function is evaluated. 4871 4872‘opt’ (‘‘PLINT’ (*note PLINT-type::)’, input) 4873 Determines the way in which the surface is represented. To specify 4874 more than one option just add the options, e.g. DRAW_LINEXY + 4875 MAG_COLOR 4876 4877 • ‘ ‘opt’=DRAW_LINEX ’: Lines are drawn showing ‘ ‘z’ ’ as a 4878 function of ‘ ‘x’ ’ for each value of ‘ ‘y’[j] ’. 4879 4880 • ‘ ‘opt’=DRAW_LINEY ’: Lines are drawn showing ‘ ‘z’ ’ as a 4881 function of ‘ ‘y’ ’ for each value of ‘ ‘x’[i] ’. 4882 4883 • ‘ ‘opt’=DRAW_LINEXY ’: Network of lines is drawn connecting 4884 points at which function is defined. 4885 4886 • ‘ ‘opt’=MAG_COLOR ’: Each line in the mesh is colored 4887 according to the z value being plotted. The color is used 4888 from the current cmap1. 4889 4890 • ‘ ‘opt’=BASE_CONT ’: A contour plot is drawn at the base XY 4891 plane using parameters ‘nlevel’ and ‘clevel’. 4892 4893 • ‘ ‘opt’=DRAW_SIDES ’: draws a curtain between the base XY 4894 plane and the borders of the plotted function. 4895 4896‘clevel’ (‘‘PLFLT_VECTOR’ (*note PLFLT_VECTOR-type::)’, input) 4897 A vector containing the contour levels. 4898 4899‘nlevel’ (‘‘PLINT’ (*note PLINT-type::)’, input) 4900 Number of elements in the ‘clevel’ vector. 4901 4902 Redacted form: 4903 4904 • General: ‘plot3dc(x, y, z, opt, clevel)’ 4905 4906 This function is used in example 21. 4907 4908 4909File: plplotdoc.info, Node: plot3dcl; Magnitude colored plot surface with contour for z[x][y] with y index limits, Next: plparseopts; Parse command-line arguments, Prev: plot3dc; Magnitude colored plot surface with contour, Up: The Common API for PLplot 4910 491117.88 plot3dcl: Magnitude colored plot surface with contour for z[x][y] with y index limits 4912=========================================================================================== 4913 4914 plot3dcl ( x , y , z , nx , ny , opt , clevel , nlevel , indexxmin 4915 , indexxmax , indexymin , indexymax ); 4916 4917 When the implementation is completed this variant of ‘plot3dc’ (*note 4918plot3dc; Magnitude colored plot surface with contour::) (see that 4919function’s documentation for more details) should be suitable for the 4920case where the area of the ‘‘x’’, ‘‘y’’ coordinate grid where ‘‘z’’ is 4921defined can be non-rectangular. The implementation is incomplete so the 4922last 4 parameters of plot3dcl; ‘ ‘indexxmin’ ’, ‘ ‘indexxmax’ ’, ‘ 4923‘indexymin’ ’, and ‘ ‘indexymax’ ’; are currently ignored and the 4924functionality is otherwise identical to that of ‘plot3dc’ (*note 4925plot3dc; Magnitude colored plot surface with contour::). 4926 4927‘x’ (‘‘PLFLT_VECTOR’ (*note PLFLT_VECTOR-type::)’, input) 4928 A vector containing the x coordinates at which the function is 4929 evaluated. 4930 4931‘y’ (‘‘PLFLT_VECTOR’ (*note PLFLT_VECTOR-type::)’, input) 4932 A vector containing the y coordinates at which the function is 4933 evaluated. 4934 4935‘z’ (‘‘PLFLT_MATRIX’ (*note PLFLT_MATRIX-type::)’, input) 4936 A matrix containing function values to plot. Should have 4937 dimensions of ‘nx’ by ‘ny’. 4938 4939‘nx’ (‘‘PLINT’ (*note PLINT-type::)’, input) 4940 Number of ‘‘x’’ values at which the function is evaluated. 4941 4942‘ny’ (‘‘PLINT’ (*note PLINT-type::)’, input) 4943 Number of ‘ ‘y’ ’ values at which the function is evaluated. 4944 4945‘opt’ (‘‘PLINT’ (*note PLINT-type::)’, input) 4946 Determines the way in which the surface is represented. To specify 4947 more than one option just add the options, e.g. DRAW_LINEXY + 4948 MAG_COLOR 4949 4950 • ‘ ‘opt’=DRAW_LINEX ’: Lines are drawn showing ‘ ‘z’ ’ as a 4951 function of ‘ ‘x’ ’ for each value of ‘ ‘y’[j] ’. 4952 4953 • ‘ ‘opt’=DRAW_LINEY ’: Lines are drawn showing ‘ ‘z’ ’ as a 4954 function of ‘ ‘y’ ’ for each value of ‘ ‘x’[i] ’. 4955 4956 • ‘ ‘opt’=DRAW_LINEXY ’: Network of lines is drawn connecting 4957 points at which function is defined. 4958 4959 • ‘ ‘opt’=MAG_COLOR ’: Each line in the mesh is colored 4960 according to the z value being plotted. The color is used 4961 from the current cmap1. 4962 4963 • ‘ ‘opt’=BASE_CONT ’: A contour plot is drawn at the base XY 4964 plane using parameters ‘nlevel’ and ‘clevel’. 4965 4966 • ‘ ‘opt’=DRAW_SIDES ’: draws a curtain between the base XY 4967 plane and the borders of the plotted function. 4968 4969‘clevel’ (‘‘PLFLT_VECTOR’ (*note PLFLT_VECTOR-type::)’, input) 4970 A vector containing the contour levels. 4971 4972‘nlevel’ (‘‘PLINT’ (*note PLINT-type::)’, input) 4973 Number of elements in the ‘clevel’ vector. 4974 4975‘indexxmin’ (‘‘PLINT’ (*note PLINT-type::)’, input) 4976 The index value (which must be ≥ 0) that corresponds to the first ‘ 4977 ‘x’ ’ index where ‘ ‘z’ ’ is defined. 4978 4979‘indexxmax’ (‘‘PLINT’ (*note PLINT-type::)’, input) 4980 The index value (which must be ≤ ‘ ‘nx’ ’) which corresponds (by 4981 convention) to one more than the last ‘ ‘x’ ’ index value where ‘ 4982 ‘z’ ’ is defined. 4983 4984‘indexymin’ (‘‘PLINT_VECTOR’ (*note PLINT_VECTOR-type::)’, input) 4985 A vector containing ‘‘y’’ index values which all must be ≥ 0. 4986 These values are the first ‘‘y’’ index where ‘‘z’’ is defined for a 4987 particular ‘‘x’ ’ index in the range from ‘‘indexxmin’ ’ to 4988 ‘‘indexxmax - 1’’. The dimension of ‘‘indexymin’’ is 4989 ‘‘indexxmax’’. 4990 4991‘indexymax’ (‘‘PLINT_VECTOR’ (*note PLINT_VECTOR-type::)’, input) 4992 A vector containing ‘‘y’’ index values which all must be ≤ ‘‘ny’’. 4993 These values correspond (by convention) to one more than the last 4994 ‘‘y’’ index where ‘‘z’’ is defined for a particular ‘‘x’’ index in 4995 the range from ‘‘indexxmin’’ to ‘‘indexxmax - 1’’. The dimension 4996 of ‘‘indexymax’’ is ‘‘indexxmax’’. 4997 4998 Redacted form: 4999 5000 • General: ‘ plot3dcl(x, y, z, opt, clevel, indexxmin, indexymin, 5001 indexymax) ’ 5002 5003 This function is not used in any example. 5004 5005 5006File: plplotdoc.info, Node: plparseopts; Parse command-line arguments, Next: plpat; Set area line fill pattern, Prev: plot3dcl; Magnitude colored plot surface with contour for z[x][y] with y index limits, Up: The Common API for PLplot 5007 500817.89 plparseopts: Parse command-line arguments 5009=============================================== 5010 5011 PLINT plparseopts ( p_argc , argv , mode ); 5012 5013 Parse command-line arguments. 5014 5015 ‘plparseopts’ (*note plparseopts; Parse command-line arguments::) 5016removes all recognized flags (decreasing argc accordingly), so that 5017invalid input may be readily detected. It can also be used to process 5018user command line flags. The user can merge an option table of type 5019PLOptionTable into the internal option table info structure using 5020‘plMergeOpts’ (*note plMergeOpts; Merge use option table into internal 5021info structure::). Or, the user can specify that ONLY the external 5022table(s) be parsed by calling ‘plClearOpts’ (*note plClearOpts; Clear 5023internal option table info structure::) before ‘plMergeOpts’ (*note 5024plMergeOpts; Merge use option table into internal info structure::). 5025 5026 The default action taken by ‘plparseopts’ (*note plparseopts; Parse 5027command-line arguments::) is as follows: 5028 5029Returns with an error if an unrecognized option or badly formed 5030option-value pair are encountered. 5031Returns immediately (return code 0) when the first non-option command 5032line argument is found. 5033Returns with the return code of the option handler, if one was called. 5034Deletes command line arguments from argv list as they are found, and 5035decrements argc accordingly. 5036Does not show "invisible" options in usage or help messages. 5037Assumes the program name is contained in argv[0]. 5038 5039 These behaviors may be controlled through the ‘mode’ argument. 5040 5041‘p_argc’ (‘int *’, input/output) 5042 Number of arguments. 5043 5044‘argv’ (‘‘PLCHAR_NC_MATRIX’ (*note PLCHAR_NC_MATRIX-type::)’, input/output) 5045 A vector of character strings containing ‘‘*p_argc’’ command-line 5046 arguments. 5047 5048‘mode’ (‘‘PLINT’ (*note PLINT-type::)’, input) 5049 Parsing mode with the following possibilities: 5050 5051 • PL_PARSE_FULL (1) – Full parsing of command line and all error 5052 messages enabled, including program exit when an error occurs. 5053 Anything on the command line that isn’t recognized as a valid 5054 option or option argument is flagged as an error. 5055 5056 • PL_PARSE_QUIET (2) – Turns off all output except in the case 5057 of errors. 5058 5059 • PL_PARSE_NODELETE (4) – Turns off deletion of processed 5060 arguments. 5061 5062 • PL_PARSE_SHOWALL (8) – Show invisible options 5063 5064 • PL_PARSE_NOPROGRAM (32) – Specified if argv[0] is NOT a 5065 pointer to the program name. 5066 5067 • PL_PARSE_NODASH (64) – Set if leading dash is NOT required. 5068 5069 • PL_PARSE_SKIP (128) – Set to quietly skip over any 5070 unrecognized arguments. 5071 5072 Redacted form: 5073 5074 • General: ‘plparseopts(argv, mode)’ 5075 5076 This function is used in all of the examples. 5077 5078 5079File: plplotdoc.info, Node: plpat; Set area line fill pattern, Next: plpath; Draw a line between two points; accounting for coordinate transforms, Prev: plparseopts; Parse command-line arguments, Up: The Common API for PLplot 5080 508117.90 plpat: Set area line fill pattern 5082======================================= 5083 5084 plpat ( nlin , inc , del ); 5085 5086 Sets the area line fill pattern to be used, e.g., for calls to 5087‘plfill’ (*note plfill; Draw filled polygon::). The pattern consists of 50881 or 2 sets of parallel lines with specified inclinations and spacings. 5089The arguments to this routine are the number of sets to use (1 or 2) 5090followed by two vectors (with 1 or 2 elements) specifying the 5091inclinations in tenths of a degree and the spacing in micrometers. (See 5092also ‘plpsty’ (*note plpsty; Select area fill pattern::)) 5093 5094‘nlin’ (‘‘PLINT’ (*note PLINT-type::)’, input) 5095 Number of sets of lines making up the pattern, either 1 or 2. 5096 5097‘inc’ (‘‘PLINT_VECTOR’ (*note PLINT_VECTOR-type::)’, input) 5098 A vector containing ‘‘nlin’’ values of the inclination in tenths of 5099 a degree. (Should be between -900 and 900). 5100 5101‘del’ (‘‘PLINT_VECTOR’ (*note PLINT_VECTOR-type::)’, input) 5102 A vector containing ‘‘nlin’’ values of the spacing in micrometers 5103 between the lines making up the pattern. 5104 5105 Redacted form: 5106 5107 • General: ‘plpat(inc, del)’ 5108 5109 This function is used in example 15. 5110 5111 5112File: plplotdoc.info, Node: plpath; Draw a line between two points; accounting for coordinate transforms, Next: plpoin; Plot a glyph at the specified points, Prev: plpat; Set area line fill pattern, Up: The Common API for PLplot 5113 511417.91 plpath: Draw a line between two points, accounting for coordinate transforms 5115================================================================================== 5116 5117 plpath ( n , x1 , y1 , x2 , y2 ); 5118 5119 Joins the point ‘ (‘x1’, ‘y1’) ’ to ‘ (‘x2’, ‘y2’) ’. If a global 5120coordinate transform is defined then the line is broken in to ‘ ‘n’ ’ 5121segments to approximate the path. If no transform is defined then this 5122simply acts like a call to ‘pljoin’ (*note pljoin; Draw a line between 5123two points::). 5124 5125‘n’ (‘‘PLINT’ (*note PLINT-type::)’, input) 5126 number of points to use to approximate the path. 5127 5128‘x1’ (‘‘PLFLT’ (*note PLFLT-type::)’, input) 5129 x coordinate of first point. 5130 5131‘y1’ (‘‘PLFLT’ (*note PLFLT-type::)’, input) 5132 y coordinate of first point. 5133 5134‘x2’ (‘‘PLFLT’ (*note PLFLT-type::)’, input) 5135 x coordinate of second point. 5136 5137‘y2’ (‘‘PLFLT’ (*note PLFLT-type::)’, input) 5138 y coordinate of second point. 5139 5140 Redacted form: ‘plpath(n,x1,y1,x2,y2)’ 5141 5142 This function is used in example 22. 5143 5144 5145File: plplotdoc.info, Node: plpoin; Plot a glyph at the specified points, Next: plpoin3; Plot a glyph at the specified 3D points, Prev: plpath; Draw a line between two points; accounting for coordinate transforms, Up: The Common API for PLplot 5146 514717.92 plpoin: Plot a glyph at the specified points 5148================================================== 5149 5150 plpoin ( n , x , y , code ); 5151 5152 Plot a glyph at the specified points. (This function is largely 5153superseded by ‘plstring’ (*note plstring; Plot a glyph at the specified 5154points::) which gives access to many[!] more glyphs.) ‘ ‘code’=-1 ’ 5155means try to just draw a point. Right now it’s just a move and a draw 5156at the same place. Not ideal, since a sufficiently intelligent output 5157device may optimize it away, or there may be faster ways of doing it. 5158This is OK for now, though, and offers a 4X speedup over drawing a 5159Hershey font "point" (which is actually diamond shaped and therefore 5160takes 4 strokes to draw). If 0 < code < 32, then a useful (but small 5161subset) of Hershey symbols is plotted. If 32 <= code <= 127 the 5162corresponding printable ASCII character is plotted. 5163 5164‘n’ (‘‘PLINT’ (*note PLINT-type::)’, input) 5165 Number of points in the ‘ ‘x’ ’ and ‘ ‘y’ ’ vectors. 5166 5167‘x’ (‘‘PLFLT_VECTOR’ (*note PLFLT_VECTOR-type::)’, input) 5168 A vector containing the x coordinates of points. 5169 5170‘y’ (‘‘PLFLT_VECTOR’ (*note PLFLT_VECTOR-type::)’, input) 5171 A vector containing the y coordinates of points. 5172 5173‘code’ (‘‘PLINT’ (*note PLINT-type::)’, input) 5174 Hershey symbol code (in "ascii-indexed" form with -1 <= code <= 5175 127) corresponding to a glyph to be plotted at each of the ‘ ‘n’ ’ 5176 points. 5177 5178 Redacted form: ‘plpoin(x, y, code)’ 5179 5180 This function is used in examples 1, 6, 14, and 29. 5181 5182 5183File: plplotdoc.info, Node: plpoin3; Plot a glyph at the specified 3D points, Next: plpoly3; Draw a polygon in 3 space, Prev: plpoin; Plot a glyph at the specified points, Up: The Common API for PLplot 5184 518517.93 plpoin3: Plot a glyph at the specified 3D points 5186====================================================== 5187 5188 plpoin3 ( n , x , y , z , code ); 5189 5190 Plot a glyph at the specified 3D points. (This function is largely 5191superseded by ‘plstring3’ (*note plstring3; Plot a glyph at the 5192specified 3D points::) which gives access to many[!] more glyphs.) Set 5193up the call to this function similar to what is done for ‘plline3’ 5194(*note plline3; Draw a line in 3 space::). ‘ ‘code’=-1 ’ means try to 5195just draw a point. Right now it’s just a move and a draw at the same 5196place. Not ideal, since a sufficiently intelligent output device may 5197optimize it away, or there may be faster ways of doing it. This is OK 5198for now, though, and offers a 4X speedup over drawing a Hershey font 5199"point" (which is actually diamond shaped and therefore takes 4 strokes 5200to draw). If 0 < code < 32, then a useful (but small subset) of Hershey 5201symbols is plotted. If 32 <= code <= 127 the corresponding printable 5202ASCII character is plotted. 5203 5204‘n’ (‘‘PLINT’ (*note PLINT-type::)’, input) 5205 Number of points in the ‘ ‘x’ ’ and ‘ ‘y’ ’ vectors. 5206 5207‘x’ (‘‘PLFLT_VECTOR’ (*note PLFLT_VECTOR-type::)’, input) 5208 A vector containing the x coordinates of points. 5209 5210‘y’ (‘‘PLFLT_VECTOR’ (*note PLFLT_VECTOR-type::)’, input) 5211 A vector containing the y coordinates of points. 5212 5213‘z’ (‘‘PLFLT_VECTOR’ (*note PLFLT_VECTOR-type::)’, input) 5214 A vector containing the z coordinates of points. 5215 5216‘code’ (‘‘PLINT’ (*note PLINT-type::)’, input) 5217 Hershey symbol code (in "ascii-indexed" form with -1 <= code <= 5218 127) corresponding to a glyph to be plotted at each of the ‘ ‘n’ ’ 5219 points. 5220 5221 Redacted form: ‘plpoin3(x, y, z, code)’ 5222 5223 This function is not used in any example. 5224 5225 5226File: plplotdoc.info, Node: plpoly3; Draw a polygon in 3 space, Next: plprec; Set precision in numeric labels, Prev: plpoin3; Plot a glyph at the specified 3D points, Up: The Common API for PLplot 5227 522817.94 plpoly3: Draw a polygon in 3 space 5229======================================== 5230 5231 plpoly3 ( n , x , y , z , draw , ifcc ); 5232 5233 Draws a polygon in 3 space defined by ‘ ‘n’ ’ points in ‘ ‘x’ ’, ‘ 5234‘y’ ’, and ‘ ‘z’ ’. Setup like ‘plline3’ (*note plline3; Draw a line in 52353 space::), but differs from that function in that ‘plpoly3’ (*note 5236plpoly3; Draw a polygon in 3 space::) attempts to determine if the 5237polygon is viewable depending on the order of the points within the 5238vector and the value of ‘‘ifcc’’. If the back of polygon is facing the 5239viewer, then it isn’t drawn. If this isn’t what you want, then use 5240‘plline3’ (*note plline3; Draw a line in 3 space::) instead. 5241 5242 The points are assumed to be in a plane, and the directionality of 5243the plane is determined from the first three points. Additional points 5244do not _have_ to lie on the plane defined by the first three, but if 5245they do not, then the determination of visibility obviously can’t be 5246100% accurate... So if you’re 3 space polygons are too far from planar, 5247consider breaking them into smaller polygons. ‘3 points define a plane’ 5248:-). 5249 5250 _Bugs_: If one of the first two segments is of zero length, or if 5251they are co-linear, the calculation of visibility has a 50/50 chance of 5252being correct. Avoid such situations :-). See ‘x18c.c’ for an example 5253of this problem. (Search for ‘20.1’). 5254 5255‘n’ (‘‘PLINT’ (*note PLINT-type::)’, input) 5256 Number of points defining line. 5257 5258‘x’ (‘‘PLFLT_VECTOR’ (*note PLFLT_VECTOR-type::)’, input) 5259 A vector containing ‘n’ x coordinates of points. 5260 5261‘y’ (‘‘PLFLT_VECTOR’ (*note PLFLT_VECTOR-type::)’, input) 5262 A vector containing ‘n’ y coordinates of points. 5263 5264‘z’ (‘‘PLFLT_VECTOR’ (*note PLFLT_VECTOR-type::)’, input) 5265 A vector containing ‘n’ z coordinates of points. 5266 5267‘draw’ (‘‘PLBOOL_VECTOR’ (*note PLBOOL_VECTOR-type::)’, input) 5268 A vector containing ‘n-1’ Boolean values which control drawing the 5269 segments of the polygon. If ‘‘draw[i]’’ is true, then the polygon 5270 segment from index ‘‘[i]’’ to ‘‘[i+1]’’ is drawn, otherwise, not. 5271 5272‘ifcc’ (‘‘PLBOOL’ (*note PLBOOL-type::)’, input) 5273 If ‘ ‘ifcc’ ’ is true the directionality of the polygon is 5274 determined by assuming the points are laid out in a 5275 counter-clockwise order. Otherwise, the directionality of the 5276 polygon is determined by assuming the points are laid out in a 5277 clockwise order. 5278 5279 Redacted form: ‘plpoly3(x, y, z, code)’ 5280 5281 This function is used in example 18. 5282 5283 5284File: plplotdoc.info, Node: plprec; Set precision in numeric labels, Next: plpsty; Select area fill pattern, Prev: plpoly3; Draw a polygon in 3 space, Up: The Common API for PLplot 5285 528617.95 plprec: Set precision in numeric labels 5287============================================= 5288 5289 plprec ( setp , prec ); 5290 5291 Sets the number of places after the decimal point in numeric labels. 5292 5293‘setp’ (‘‘PLINT’ (*note PLINT-type::)’, input) 5294 If ‘ ‘setp’ ’ is equal to 0 then PLplot automatically determines 5295 the number of places to use after the decimal point in numeric 5296 labels (like those used to label axes). If ‘ ‘setp’ ’ is 1 then ‘ 5297 ‘prec’ ’ sets the number of places. 5298 5299‘prec’ (‘‘PLINT’ (*note PLINT-type::)’, input) 5300 The number of characters to draw after the decimal point in numeric 5301 labels. 5302 5303 Redacted form: ‘plprec(setp, prec)’ 5304 5305 This function is used in example 29. 5306 5307 5308File: plplotdoc.info, Node: plpsty; Select area fill pattern, Next: plptex; Write text inside the viewport, Prev: plprec; Set precision in numeric labels, Up: The Common API for PLplot 5309 531017.96 plpsty: Select area fill pattern 5311====================================== 5312 5313 plpsty ( patt ); 5314 5315 If ‘patt’ is zero or less use either a hardware solid fill if the 5316drivers have that capability (virtually all do) or fall back to a 5317software emulation of a solid fill using the eighth area line fill 5318pattern. If 0 < ‘patt’ ≤ 8, then select one of eight predefined area 5319line fill patterns to use (see ‘plpat’ (*note plpat; Set area line fill 5320pattern::) if you desire other patterns). 5321 5322‘patt’ (‘‘PLINT’ (*note PLINT-type::)’, input) 5323 The desired pattern index. If ‘patt’ is zero or less, then a solid 5324 fill is (normally, see qualifiers above) used. For ‘patt’ in the 5325 range from 1 to 8 and assuming the driver has not supplied line 5326 fill capability itself (most deliberately do not so that line fill 5327 patterns look identical for those drivers), the patterns consist of 5328 (1) horizontal lines, (2) vertical lines, (3) lines at 45 degrees, 5329 (4) lines at -45 degrees, (5) lines at 30 degrees, (6) lines at -30 5330 degrees, (7) both vertical and horizontal lines, and (8) lines at 5331 both 45 degrees and -45 degrees. 5332 5333 Redacted form: ‘plpsty(patt)’ 5334 5335 This function is used in examples 12, 13, 15, 16, and 25. 5336 5337 5338File: plplotdoc.info, Node: plptex; Write text inside the viewport, Next: plptex3; Write text inside the viewport of a 3D plot, Prev: plpsty; Select area fill pattern, Up: The Common API for PLplot 5339 534017.97 plptex: Write text inside the viewport 5341============================================ 5342 5343 plptex ( x , y , dx , dy , just , text ); 5344 5345 Writes text at a specified position and inclination within the 5346viewport. Text is clipped at the viewport boundaries. The reference 5347point of a string lies along a line passing through the string at half 5348the height of a capital letter. The position of the reference point 5349along this line is determined by ‘ ‘just’ ’, the reference point is 5350placed at world coordinates ‘ (‘x’, ‘y’) ’ within the viewport. The 5351inclination of the string is specified in terms of differences of world 5352coordinates making it easy to write text parallel to a line in a graph. 5353 5354‘x’ (‘‘PLFLT’ (*note PLFLT-type::)’, input) 5355 x coordinate of reference point of string. 5356 5357‘y’ (‘‘PLFLT’ (*note PLFLT-type::)’, input) 5358 y coordinate of reference point of string. 5359 5360‘dx’ (‘‘PLFLT’ (*note PLFLT-type::)’, input) 5361 Together with ‘ ‘dy’ ’, this specifies the inclination of the 5362 string. The baseline of the string is parallel to a line joining ‘ 5363 (‘x’, ‘y’) ’ to ‘ (‘x’+‘dx’, ‘y’+‘dy’) ’. 5364 5365‘dy’ (‘‘PLFLT’ (*note PLFLT-type::)’, input) 5366 Together with ‘ ‘dx’ ’, this specifies the inclination of the 5367 string. 5368 5369‘just’ (‘‘PLFLT’ (*note PLFLT-type::)’, input) 5370 Specifies the position of the string relative to its reference 5371 point. If ‘ ‘just’=0. ’, the reference point is at the left and if 5372 ‘ ‘just’=1. ’, it is at the right of the string. Other values of ‘ 5373 ‘just’ ’ give intermediate justifications. 5374 5375‘text’ (‘‘PLCHAR_VECTOR’ (*note PLCHAR_VECTOR-type::)’, input) 5376 A UTF-8 character string to be written out. 5377 5378 Redacted form: ‘plptex(x, y, dx, dy, just, text)’ 5379 5380 This function is used in example 2-4,10,12-14,20,23,24,26. 5381 5382 5383File: plplotdoc.info, Node: plptex3; Write text inside the viewport of a 3D plot, Next: plrandd; Random number generator returning a real random number in the range [0;1], Prev: plptex; Write text inside the viewport, Up: The Common API for PLplot 5384 538517.98 plptex3: Write text inside the viewport of a 3D plot 5386========================================================== 5387 5388 plptex3 ( wx , wy , wz , dx , dy , dz , sx , sy , sz , just , text 5389 ); 5390 5391 Writes text at a specified position and inclination and with a 5392specified shear within the viewport. Text is clipped at the viewport 5393boundaries. The reference point of a string lies along a line passing 5394through the string at half the height of a capital letter. The position 5395of the reference point along this line is determined by ‘ ‘just’ ’, and 5396the reference point is placed at world coordinates ‘ (‘wx’, ‘wy’, ‘wz’) 5397’ within the viewport. The inclination and shear of the string is 5398specified in terms of differences of world coordinates making it easy to 5399write text parallel to a line in a graph. 5400 5401‘wx’ (‘‘PLFLT’ (*note PLFLT-type::)’, input) 5402 x world coordinate of reference point of string. 5403 5404‘wy’ (‘‘PLFLT’ (*note PLFLT-type::)’, input) 5405 y world coordinate of reference point of string. 5406 5407‘wz’ (‘‘PLFLT’ (*note PLFLT-type::)’, input) 5408 z world coordinate of reference point of string. 5409 5410‘dx’ (‘‘PLFLT’ (*note PLFLT-type::)’, input) 5411 Together with ‘ ‘dy’ and ‘ dz ’ ’, this specifies the inclination 5412 of the string. The baseline of the string is parallel to a line 5413 joining ‘ (‘x’, ‘y’, ‘z’) ’ to ‘ (‘x’+‘dx’, ‘y’+‘dy’, ‘z’+‘dz’) ’. 5414 5415‘dy’ (‘‘PLFLT’ (*note PLFLT-type::)’, input) 5416 Together with ‘ ‘dx’ and ‘dz’ ’, this specifies the inclination of 5417 the string. 5418 5419‘dz’ (‘‘PLFLT’ (*note PLFLT-type::)’, input) 5420 Together with ‘ ‘dx’ and ‘dy’ ’, this specifies the inclination of 5421 the string. 5422 5423‘sx’ (‘‘PLFLT’ (*note PLFLT-type::)’, input) 5424 Together with ‘ ‘sy’ and ‘ sz ’ ’, this specifies the shear of the 5425 string. The string is sheared so that the characters are 5426 vertically parallel to a line joining ‘ (‘x’, ‘y’, ‘z’) ’ to ‘ 5427 (‘x’+‘sx’, ‘y’+‘sy’, ‘z’+‘sz’) ’. If ‘ ‘sx’ = ‘sy’ = ‘sz’ = 0.) ’ 5428 then the text is not sheared. 5429 5430‘sy’ (‘‘PLFLT’ (*note PLFLT-type::)’, input) 5431 Together with ‘ ‘sx’ and ‘sz’ ’, this specifies shear of the 5432 string. 5433 5434‘sz’ (‘‘PLFLT’ (*note PLFLT-type::)’, input) 5435 Together with ‘ ‘sx’ and ‘sy’ ’, this specifies shear of the 5436 string. 5437 5438‘just’ (‘‘PLFLT’ (*note PLFLT-type::)’, input) 5439 Specifies the position of the string relative to its reference 5440 point. If ‘ ‘just’=0. ’, the reference point is at the left and if 5441 ‘ ‘just’=1. ’, it is at the right of the string. Other values of ‘ 5442 ‘just’ ’ give intermediate justifications. 5443 5444‘text’ (‘‘PLCHAR_VECTOR’ (*note PLCHAR_VECTOR-type::)’, input) 5445 A UTF-8 character string to be written out. 5446 5447 Redacted form: ‘ plptex3(x, y, z, dx, dy, dz, sx, sy, sz, just, text) 5448’ 5449 5450 This function is used in example 28. 5451 5452 5453File: plplotdoc.info, Node: plrandd; Random number generator returning a real random number in the range [0;1], Next: plreplot; Replays contents of plot buffer to current device/file, Prev: plptex3; Write text inside the viewport of a 3D plot, Up: The Common API for PLplot 5454 545517.99 plrandd: Random number generator returning a real random number in the range [0,1] 5456======================================================================================== 5457 5458 plrandd (); 5459 5460 Random number generator returning a real random number in the range 5461[0,1]. The generator is based on the Mersenne Twister. Most languages 5462/ compilers provide their own random number generator, and so this is 5463provided purely for convenience and to give a consistent random number 5464generator across all languages supported by PLplot. This is 5465particularly useful for comparing results from the test suite of 5466examples. 5467 5468 Redacted form: ‘plrandd()’ 5469 5470 This function is used in examples 17 and 21. 5471 5472 5473File: plplotdoc.info, Node: plreplot; Replays contents of plot buffer to current device/file, Next: plrgbhls; Convert RGB color to HLS, Prev: plrandd; Random number generator returning a real random number in the range [0;1], Up: The Common API for PLplot 5474 547517.100 plreplot: Replays contents of plot buffer to current device/file 5476======================================================================= 5477 5478 plreplot (); 5479 5480 Replays contents of plot buffer to current device/file. 5481 5482 Redacted form: ‘plreplot()’ 5483 5484 This function is used in example 1,20. 5485 5486 5487File: plplotdoc.info, Node: plrgbhls; Convert RGB color to HLS, Next: plschr; Set character size, Prev: plreplot; Replays contents of plot buffer to current device/file, Up: The Common API for PLplot 5488 548917.101 plrgbhls: Convert RGB color to HLS 5490========================================= 5491 5492 plrgbhls ( r , g , b , p_h , p_l , p_s ); 5493 5494 Convert RGB color coordinates to HLS 5495 5496‘r’ (‘‘PLFLT’ (*note PLFLT-type::)’, input) 5497 Red intensity (0.0-1.0) of the color. 5498 5499‘g’ (‘‘PLFLT’ (*note PLFLT-type::)’, input) 5500 Green intensity (0.0-1.0) of the color. 5501 5502‘b’ (‘‘PLFLT’ (*note PLFLT-type::)’, input) 5503 Blue intensity (0.0-1.0) of the color. 5504 5505‘p_h’ (‘‘PLFLT_NC_SCALAR’ (*note PLFLT_NC_SCALAR-type::)’, output) 5506 Returned value of the hue in degrees (0.0-360.0) on the color 5507 cylinder. 5508 5509‘p_l’ (‘‘PLFLT_NC_SCALAR’ (*note PLFLT_NC_SCALAR-type::)’, output) 5510 Returned value of the lightness expressed as a fraction (0.0-1.0) 5511 of the axis of the color cylinder. 5512 5513‘p_s’ (‘‘PLFLT_NC_SCALAR’ (*note PLFLT_NC_SCALAR-type::)’, output) 5514 Returned value of the saturation expressed as a fraction (0.0-1.0) 5515 of the radius of the color cylinder. 5516 5517 Redacted form: 5518 5519 • General: ‘plrgbhls(r, g, b, p_h, p_l, p_s)’ 5520 5521 This function is used in example 2. 5522 5523 5524File: plplotdoc.info, Node: plschr; Set character size, Next: plscmap0; Set cmap0 colors by 8-bit RGB values, Prev: plrgbhls; Convert RGB color to HLS, Up: The Common API for PLplot 5525 552617.102 plschr: Set character size 5527================================= 5528 5529 plschr ( def , scale ); 5530 5531 This sets up the size of all subsequent characters drawn. The actual 5532height of a character is the product of the default character size and a 5533scaling factor. 5534 5535‘def’ (‘‘PLFLT’ (*note PLFLT-type::)’, input) 5536 The default height of a character in millimeters, should be set to 5537 zero if the default height is to remain unchanged. For rasterized 5538 drivers the dx and dy values specified in ‘plspage’ (*note plspage; 5539 Set page parameters::) are used to convert from mm to pixels (note 5540 the different unit systems used). This dpi aware scaling is not 5541 implemented for all drivers yet. 5542 5543‘scale’ (‘‘PLFLT’ (*note PLFLT-type::)’, input) 5544 Scale factor to be applied to default to get actual character 5545 height. 5546 5547 Redacted form: ‘plschr(def, scale)’ 5548 5549 This function is used in examples 2, 13, 23, and 24. 5550 5551 5552File: plplotdoc.info, Node: plscmap0; Set cmap0 colors by 8-bit RGB values, Next: plscmap0a; Set cmap0 colors by 8-bit RGB values and PLFLT alpha transparency value, Prev: plschr; Set character size, Up: The Common API for PLplot 5553 555417.103 plscmap0: Set cmap0 colors by 8-bit RGB values 5555===================================================== 5556 5557 plscmap0 ( r , g , b , ncol0 ); 5558 5559 Set cmap0 colors using 8-bit RGB values (see *note Color Map0::). 5560This sets the entire color map – only as many colors as specified will 5561be allocated. 5562 5563‘r’ (‘‘PLINT_VECTOR’ (*note PLINT_VECTOR-type::)’, input) 5564 A vector containing unsigned 8-bit integers (0-255) representing 5565 the degree of red in the color. 5566 5567‘g’ (‘‘PLINT_VECTOR’ (*note PLINT_VECTOR-type::)’, input) 5568 A vector containing unsigned 8-bit integers (0-255) representing 5569 the degree of green in the color. 5570 5571‘b’ (‘‘PLINT_VECTOR’ (*note PLINT_VECTOR-type::)’, input) 5572 A vector containing unsigned 8-bit integers (0-255) representing 5573 the degree of blue in the color. 5574 5575‘ncol0’ (‘‘PLINT’ (*note PLINT-type::)’, input) 5576 Number of items in the ‘ ‘r’ ’, ‘ ‘g’ ’, and ‘ ‘b’ ’ vectors. 5577 5578 Redacted form: ‘plscmap0(r, g, b)’ 5579 5580 This function is used in examples 2 and 24. 5581 5582 5583File: plplotdoc.info, Node: plscmap0a; Set cmap0 colors by 8-bit RGB values and PLFLT alpha transparency value, Next: plscmap0n; Set number of colors in cmap0, Prev: plscmap0; Set cmap0 colors by 8-bit RGB values, Up: The Common API for PLplot 5584 558517.104 plscmap0a: Set cmap0 colors by 8-bit RGB values and PLFLT alpha transparency value 5586========================================================================================= 5587 5588 plscmap0a ( r , g , b , alpha , ncol0 ); 5589 5590 Set cmap0 colors using 8-bit RGB values (see *note Color Map0::) and 5591PLFLT alpha transparency value. This sets the entire color map – only 5592as many colors as specified will be allocated. 5593 5594‘r’ (‘‘PLINT_VECTOR’ (*note PLINT_VECTOR-type::)’, input) 5595 A vector containing unsigned 8-bit integers (0-255) representing 5596 the degree of red in the color. 5597 5598‘g’ (‘‘PLINT_VECTOR’ (*note PLINT_VECTOR-type::)’, input) 5599 A vector containing unsigned 8-bit integers (0-255) representing 5600 the degree of green in the color. 5601 5602‘b’ (‘‘PLINT_VECTOR’ (*note PLINT_VECTOR-type::)’, input) 5603 A vector containing unsigned 8-bit integers (0-255) representing 5604 the degree of blue in the color. 5605 5606‘alpha’ (‘‘PLFLT_VECTOR’ (*note PLFLT_VECTOR-type::)’, input) 5607 A vector containing values (0.0-1.0) representing the alpha 5608 transparency of the color. 5609 5610‘ncol0’ (‘‘PLINT’ (*note PLINT-type::)’, input) 5611 Number of items in the ‘ ‘r’ ’, ‘ ‘g’ ’, ‘ ‘b’ ’, and ‘ ‘alpha’ ’ 5612 vectors. 5613 5614 Redacted form: ‘plscmap0a(r, g, b, alpha)’ 5615 5616 This function is used in examples 30. 5617 5618 5619File: plplotdoc.info, Node: plscmap0n; Set number of colors in cmap0, Next: plscmap1_range; Set the cmap1 argument range for continuous color plots, Prev: plscmap0a; Set cmap0 colors by 8-bit RGB values and PLFLT alpha transparency value, Up: The Common API for PLplot 5620 562117.105 plscmap0n: Set number of colors in cmap0 5622=============================================== 5623 5624 plscmap0n ( ncol0 ); 5625 5626 Set number of colors in cmap0 (see *note Color Map0::). Allocate (or 5627reallocate) cmap0, and fill with default values for those colors not 5628previously allocated. The first 16 default colors are given in the 5629‘plcol0’ (*note plcol0; Set color; cmap0::) documentation. For larger 5630indices the default color is red. 5631 5632 The drivers are not guaranteed to support more than 16 colors. 5633 5634‘ncol0’ (‘‘PLINT’ (*note PLINT-type::)’, input) 5635 Number of colors that will be allocated in the cmap0 palette. If 5636 this number is zero or less, then the value from the previous call 5637 to ‘plscmap0n’ (*note plscmap0n; Set number of colors in cmap0::) 5638 is used and if there is no previous call, then a default value is 5639 used. 5640 5641 Redacted form: ‘plscmap0n(ncol0)’ 5642 5643 This function is used in examples 15, 16, and 24. 5644 5645 5646File: plplotdoc.info, Node: plscmap1_range; Set the cmap1 argument range for continuous color plots, Next: plscmap1; Set opaque RGB cmap1 colors values, Prev: plscmap0n; Set number of colors in cmap0, Up: The Common API for PLplot 5647 564817.106 plscmap1_range: Set the cmap1 argument range for continuous color plots 5649============================================================================== 5650 5651 plscmap1_range ( min_color , max_color ); 5652 5653 Set the cmap1 argument range for continuous color plots that 5654corresponds to the range of data values. The maximum range 5655corresponding to the entire cmap1 palette is 0.0-1.0, and the smaller 5656the cmap1 argument range that is specified with this routine, the 5657smaller the subset of the cmap1 color palette that is used to represent 5658the continuous data being plotted. If ‘min_color’ is greater than 5659‘max_color’ or ‘max_color’ is greater than 1.0 or ‘min_color’ is less 5660than 0.0 then no change is made to the cmap1 argument range. (Use 5661‘plgcmap1_range’ (*note plgcmap1_range; Get the cmap1 argument range for 5662continuous color plots::) to get the cmap1 argument range.) 5663 5664‘min_color’ (‘‘PLFLT’ (*note PLFLT-type::)’, input) 5665 The minimum cmap1 argument. If less than 0.0, then 0.0 is used 5666 instead. 5667 5668‘max_color’ (‘‘PLFLT’ (*note PLFLT-type::)’, input) 5669 The maximum cmap1 argument. If greater than 1.0, then 1.0 is used 5670 instead. 5671 5672 Redacted form: ‘plscmap1_range(min_color, max_color)’ 5673 5674 This function is currently used in example 33. 5675 5676 5677File: plplotdoc.info, Node: plscmap1; Set opaque RGB cmap1 colors values, Next: plscmap1a; Set semitransparent cmap1 RGBA colors_, Prev: plscmap1_range; Set the cmap1 argument range for continuous color plots, Up: The Common API for PLplot 5678 567917.107 plscmap1: Set opaque RGB cmap1 colors values 5680=================================================== 5681 5682 plscmap1 ( r , g , b , ncol1 ); 5683 5684 Set opaque cmap1 colors (see *note Color Map1::) using RGB vector 5685values. This function also sets the number of cmap1 colors. N.B. 5686Continuous cmap1 colors are indexed with a floating-point index in the 5687range from 0.0-1.0 which is linearly transformed (e.g., by ‘plcol1’ 5688(*note plcol1; Set color; cmap1::)) to an integer index of these RGB 5689vectors in the range from 0 to ‘ncol1-1’. So in order for this 5690continuous color model to work properly, it is the responsibility of the 5691user of ‘plscmap1’ (*note plscmap1; Set opaque RGB cmap1 colors 5692values::) to insure that these RGB vectors are continuous functions of 5693their integer indices. 5694 5695‘r’ (‘‘PLINT_VECTOR’ (*note PLINT_VECTOR-type::)’, input) 5696 A vector that represents (using unsigned 8-bit integers in the 5697 range from 0-255) the degree of red in the color as a continuous 5698 function of the integer index of the vector. 5699 5700‘g’ (‘‘PLINT_VECTOR’ (*note PLINT_VECTOR-type::)’, input) 5701 A vector that represents (using unsigned 8-bit integers in the 5702 range from 0-255) the degree of green in the color as a continuous 5703 function of the integer index of the vector. 5704 5705‘b’ (‘‘PLINT_VECTOR’ (*note PLINT_VECTOR-type::)’, input) 5706 A vector that represents (using unsigned 8-bit integers in the 5707 range from 0-255) the degree of blue in the color as a continuous 5708 function of the integer index of the vector. 5709 5710‘ncol1’ (‘‘PLINT’ (*note PLINT-type::)’, input) 5711 Number of items in the ‘ ‘r’ ’, ‘ ‘g’ ’, and ‘ ‘b’ ’ vectors. 5712 5713 Redacted form: ‘plscmap1(r, g, b)’ 5714 5715 This function is used in example 31. 5716 5717 5718File: plplotdoc.info, Node: plscmap1a; Set semitransparent cmap1 RGBA colors_, Next: plscmap1l; Set cmap1 colors using a piece-wise linear relationship, Prev: plscmap1; Set opaque RGB cmap1 colors values, Up: The Common API for PLplot 5719 572017.108 plscmap1a: Set semitransparent cmap1 RGBA colors. 5721======================================================== 5722 5723 plscmap1a ( r , g , b , alpha , ncol1 ); 5724 5725 Set semitransparent cmap1 colors (see *note Color Map1::) using RGBA 5726vector values. This function also sets the number of cmap1 colors. 5727N.B. Continuous cmap1 colors are indexed with a floating-point index in 5728the range from 0.0-1.0 which is linearly transformed (e.g., by ‘plcol1’ 5729(*note plcol1; Set color; cmap1::)) to an integer index of these RGBA 5730vectors in the range from 0 to ‘ncol1-1’. So in order for this 5731continuous color model to work properly, it is the responsibility of the 5732user of ‘plscmap1’ (*note plscmap1; Set opaque RGB cmap1 colors 5733values::) to insure that these RGBA vectors are continuous functions of 5734their integer indices. 5735 5736‘r’ (‘‘PLINT_VECTOR’ (*note PLINT_VECTOR-type::)’, input) 5737 A vector that represents (using unsigned 8-bit integers in the 5738 range from 0-255) the degree of red in the color as a continuous 5739 function of the integer index of the vector. 5740 5741‘g’ (‘‘PLINT_VECTOR’ (*note PLINT_VECTOR-type::)’, input) 5742 A vector that represents (using unsigned 8-bit integers in the 5743 range from 0-255) the degree of green in the color as a continuous 5744 function of the integer index of the vector. 5745 5746‘b’ (‘‘PLINT_VECTOR’ (*note PLINT_VECTOR-type::)’, input) 5747 A vector that represents (using unsigned 8-bit integers in the 5748 range from 0-255) the degree of blue in the color as a continuous 5749 function of the integer index of the vector. 5750 5751‘alpha’ (‘‘PLFLT_VECTOR’ (*note PLFLT_VECTOR-type::)’, input) 5752 A vector that represents (using PLFLT values in the range from 5753 0.0-1.0 where 0.0 corresponds to completely transparent and 1.0 5754 corresponds to completely opaque) the alpha transparency of the 5755 color as a continuous function of the integer index of the vector. 5756 5757‘ncol1’ (‘‘PLINT’ (*note PLINT-type::)’, input) 5758 Number of items in the ‘ ‘r’ ’, ‘ ‘g’ ’, ‘ ‘b’ ’, and ‘ ‘alpha’ ’ 5759 vectors. 5760 5761 Redacted form: ‘plscmap1a(r, g, b, alpha)’ 5762 5763 This function is used in example 31. 5764 5765 5766File: plplotdoc.info, Node: plscmap1l; Set cmap1 colors using a piece-wise linear relationship, Next: plscmap1la; Set cmap1 colors and alpha transparency using a piece-wise linear relationship, Prev: plscmap1a; Set semitransparent cmap1 RGBA colors_, Up: The Common API for PLplot 5767 576817.109 plscmap1l: Set cmap1 colors using a piece-wise linear relationship 5769========================================================================= 5770 5771 plscmap1l ( itype , npts , intensity , coord1 , coord2 , coord3 , 5772 alt_hue_path ); 5773 5774 Set cmap1 colors using a piece-wise linear relationship between the 5775cmap1 intensity index (0.0-1.0) and position in HLS or RGB color space 5776(see *note Color Map1::). May be called at any time. 5777 5778 The idea here is to specify a number of control points that define 5779the mapping between input cmap1 intensity indices and HLS or RGB. 5780Between these points, linear interpolation is used which gives a smooth 5781variation of color with intensity index. Any number of control points 5782may be specified, located at arbitrary positions, although typically 2 - 57834 are enough. Another way of stating this is that we are traversing a 5784given number of lines through HLS or RGB space as we move through cmap1 5785intensity indices. The control points at the minimum and maximum 5786position (0 and 1) must always be specified. By adding more control 5787points you can get more variation. One good technique for plotting 5788functions that vary about some expected average is to use an additional 57892 control points in the center (position ~= 0.5) that are the same 5790lightness as the background (typically white for paper output, black for 5791crt), and same hue as the boundary control points. This allows the 5792highs and lows to be very easily distinguished. 5793 5794 Each control point must specify the cmap1 intensity index and the 5795associated three coordinates in HLS or RGB space. The first point 5796_must_ correspond to position = 0, and the last to position = 1. 5797 5798 If RGB colors are provided then the interpolation takes place in RGB 5799space and is trivial. However if HLS colors are provided then, because 5800of the circular nature of the color wheel for the hue coordinate, the 5801interpolation could be performed in either direction around the color 5802wheel. The default behaviour is for the hue to be linearly interpolated 5803ignoring this circular property of hue. So for example, the hues 0 5804(red) and 240 (blue) will get interpolated via yellow, green and cyan. 5805If instead you wish to interpolate the other way around the color wheel 5806you have two options. You may provide hues outside the range [0, 360), 5807so by using a hue of -120 for blue or 360 for red the interpolation will 5808proceed via magenta. Alternatively you can utilise the alt_hue_path 5809variable to reverse the direction of interpolation if you need to 5810provide hues within the [0-360) range. 5811 5812 * Examples of interpolation * 5813 5814Hue alt_hue_path color scheme 5815[120 240] false green-cyan-blue 5816[240 120] false blue-cyan-green 5817[120 -120] false green-yellow-red-magenta-blue 5818[240 480] false blue-magenta-red-yellow-green 5819[120 240] true green-yellow-red-magenta-blue 5820[240 120] true blue-magenta-red-yellow-green 5821 5822 * Bounds on coordinates* 5823 5824RGB R [0, 1] magnitude 5825RGB G [0, 1] magnitude 5826RGB B [0, 1] magnitude 5827HLS hue [0, 360] degrees 5828HLS lightness [0, 1] magnitude 5829HLS saturation [0, 1] magnitude 5830 5831‘itype’ (‘‘PLBOOL’ (*note PLBOOL-type::)’, input) 5832 true: RGB, false: HLS. 5833 5834‘npts’ (‘‘PLINT’ (*note PLINT-type::)’, input) 5835 number of control points 5836 5837‘intensity’ (‘‘PLFLT_VECTOR’ (*note PLFLT_VECTOR-type::)’, input) 5838 A vector containing the cmap1 intensity index (0.0-1.0) in 5839 ascending order for each control point. 5840 5841‘coord1’ (‘‘PLFLT_VECTOR’ (*note PLFLT_VECTOR-type::)’, input) 5842 A vector containing the first coordinate (H or R) for each control 5843 point. 5844 5845‘coord2’ (‘‘PLFLT_VECTOR’ (*note PLFLT_VECTOR-type::)’, input) 5846 A vector containing the second coordinate (L or G) for each control 5847 point. 5848 5849‘coord3’ (‘‘PLFLT_VECTOR’ (*note PLFLT_VECTOR-type::)’, input) 5850 A vector containing the third coordinate (S or B) for each control 5851 point. 5852 5853‘alt_hue_path’ (‘‘PLBOOL_VECTOR’ (*note PLBOOL_VECTOR-type::)’, input) 5854 A vector (with ‘npts - 1’ elements), each containing either true to 5855 use the reversed HLS interpolation or false to use the regular HLS 5856 interpolation. (‘alt_hue_path[i]’ refers to the interpolation 5857 interval between the ‘i’ and ‘i + 1’ control points). This 5858 parameter is not used for RGB colors (‘itype = true’). 5859 5860 Redacted form: ‘plscmap1l(itype, intensity, coord1, coord2, coord3, 5861alt_hue_path)’ 5862 5863 This function is used in examples 8, 11, 12, 15, 20, and 21. 5864 5865 5866File: plplotdoc.info, Node: plscmap1la; Set cmap1 colors and alpha transparency using a piece-wise linear relationship, Next: plscmap1n; Set number of colors in cmap1, Prev: plscmap1l; Set cmap1 colors using a piece-wise linear relationship, Up: The Common API for PLplot 5867 586817.110 plscmap1la: Set cmap1 colors and alpha transparency using a piece-wise linear relationship 5869================================================================================================= 5870 5871 plscmap1la ( itype , npts , intensity , coord1 , coord2 , coord3 , 5872 alpha , alt_hue_path ); 5873 5874 This is a variant of ‘plscmap1l’ (*note plscmap1l; Set cmap1 colors 5875using a piece-wise linear relationship::) that supports alpha channel 5876transparency. It sets cmap1 colors using a piece-wise linear 5877relationship between cmap1 intensity index (0.0-1.0) and position in HLS 5878or RGB color space (see *note Color Map1::) with ‘‘alpha’’ transparency 5879value (0.0-1.0). It may be called at any time. 5880 5881‘itype’ (‘‘PLBOOL’ (*note PLBOOL-type::)’, input) 5882 true: RGB, false: HLS. 5883 5884‘npts’ (‘‘PLINT’ (*note PLINT-type::)’, input) 5885 number of control points. 5886 5887‘intensity’ (‘‘PLFLT_VECTOR’ (*note PLFLT_VECTOR-type::)’, input) 5888 A vector containing the cmap1 intensity index (0.0-1.0) in 5889 ascending order for each control point. 5890 5891‘coord1’ (‘‘PLFLT_VECTOR’ (*note PLFLT_VECTOR-type::)’, input) 5892 A vector containing the first coordinate (H or R) for each control 5893 point. 5894 5895‘coord2’ (‘‘PLFLT_VECTOR’ (*note PLFLT_VECTOR-type::)’, input) 5896 A vector containing the second coordinate (L or G) for each control 5897 point. 5898 5899‘coord3’ (‘‘PLFLT_VECTOR’ (*note PLFLT_VECTOR-type::)’, input) 5900 A vector containing the third coordinate (S or B) for each control 5901 point. 5902 5903‘alpha’ (‘‘PLFLT_VECTOR’ (*note PLFLT_VECTOR-type::)’, input) 5904 A vector containing the alpha transparency value (0.0-1.0) for each 5905 control point. 5906 5907‘alt_hue_path’ (‘‘PLBOOL_VECTOR’ (*note PLBOOL_VECTOR-type::)’, input) 5908 A vector (with ‘npts - 1’ elements) containing the alternative 5909 interpolation method Boolean value for each control point interval. 5910 (‘alt_hue_path[i]’ refers to the interpolation interval between the 5911 ‘i’ and ‘i + 1’ control points). 5912 5913 Redacted form: ‘ plscmap1la(itype, intensity, coord1, coord2, coord3, 5914alpha, alt_hue_path) ’ 5915 5916 This function is used in example 30. 5917 5918 5919File: plplotdoc.info, Node: plscmap1n; Set number of colors in cmap1, Next: plscol0; Set 8-bit RGB values for given cmap0 color index, Prev: plscmap1la; Set cmap1 colors and alpha transparency using a piece-wise linear relationship, Up: The Common API for PLplot 5920 592117.111 plscmap1n: Set number of colors in cmap1 5922=============================================== 5923 5924 plscmap1n ( ncol1 ); 5925 5926 Set number of colors in cmap1, (re-)allocate cmap1, and set default 5927values if this is the first allocation (see *note Color Map1::). 5928 5929‘ncol1’ (‘‘PLINT’ (*note PLINT-type::)’, input) 5930 Number of colors that will be allocated in the cmap1 palette. If 5931 this number is zero or less, then the value from the previous call 5932 to ‘plscmap1n’ (*note plscmap1n; Set number of colors in cmap1::) 5933 is used and if there is no previous call, then a default value is 5934 used. 5935 5936 Redacted form: ‘plscmap1n(ncol1)’ 5937 5938 This function is used in examples 8, 11, 20, and 21. 5939 5940 5941File: plplotdoc.info, Node: plscol0; Set 8-bit RGB values for given cmap0 color index, Next: plscol0a; Set 8-bit RGB values and PLFLT alpha transparency value for given cmap0 color index, Prev: plscmap1n; Set number of colors in cmap1, Up: The Common API for PLplot 5942 594317.112 plscol0: Set 8-bit RGB values for given cmap0 color index 5944================================================================ 5945 5946 plscol0 ( icol0 , r , g , b ); 5947 5948 Set 8-bit RGB values for given cmap0 (see *note Color Map0::) index. 5949Overwrites the previous color value for the given index and, thus, does 5950not result in any additional allocation of space for colors. 5951 5952‘icol0’ (‘‘PLINT’ (*note PLINT-type::)’, input) 5953 Color index. Must be less than the maximum number of colors (which 5954 is set by default, by ‘plscmap0n’ (*note plscmap0n; Set number of 5955 colors in cmap0::), or even by ‘plscmap0’ (*note plscmap0; Set 5956 cmap0 colors by 8-bit RGB values::)). 5957 5958‘r’ (‘‘PLINT’ (*note PLINT-type::)’, input) 5959 Unsigned 8-bit integer (0-255) representing the degree of red in 5960 the color. 5961 5962‘g’ (‘‘PLINT’ (*note PLINT-type::)’, input) 5963 Unsigned 8-bit integer (0-255) representing the degree of green in 5964 the color. 5965 5966‘b’ (‘‘PLINT’ (*note PLINT-type::)’, input) 5967 Unsigned 8-bit integer (0-255) representing the degree of blue in 5968 the color. 5969 5970 Redacted form: ‘plscol0(icol0, r, g, b)’ 5971 5972 This function is used in any example 31. 5973 5974 5975File: plplotdoc.info, Node: plscol0a; Set 8-bit RGB values and PLFLT alpha transparency value for given cmap0 color index, Next: plscolbg; Set the background color by 8-bit RGB value, Prev: plscol0; Set 8-bit RGB values for given cmap0 color index, Up: The Common API for PLplot 5976 597717.113 plscol0a: Set 8-bit RGB values and PLFLT alpha transparency value for given cmap0 color index 5978==================================================================================================== 5979 5980 plscol0a ( icol0 , r , g , b , alpha ); 5981 5982 Set 8-bit RGB value and PLFLT alpha transparency value for given 5983cmap0 (see *note Color Map0::) index. Overwrites the previous color 5984value for the given index and, thus, does not result in any additional 5985allocation of space for colors. 5986 5987‘icol0’ (‘‘PLINT’ (*note PLINT-type::)’, input) 5988 Color index. Must be less than the maximum number of colors (which 5989 is set by default, by ‘plscmap0n’ (*note plscmap0n; Set number of 5990 colors in cmap0::), or even by ‘plscmap0’ (*note plscmap0; Set 5991 cmap0 colors by 8-bit RGB values::)). 5992 5993‘r’ (‘‘PLINT’ (*note PLINT-type::)’, input) 5994 Unsigned 8-bit integer (0-255) representing the degree of red in 5995 the color. 5996 5997‘g’ (‘‘PLINT’ (*note PLINT-type::)’, input) 5998 Unsigned 8-bit integer (0-255) representing the degree of green in 5999 the color. 6000 6001‘b’ (‘‘PLINT’ (*note PLINT-type::)’, input) 6002 Unsigned 8-bit integer (0-255) representing the degree of blue in 6003 the color. 6004 6005‘alpha’ (‘‘PLFLT’ (*note PLFLT-type::)’, input) 6006 Value of the alpha transparency in the range (0.0-1.0). 6007 6008 This function is used in example 30. 6009 6010 6011File: plplotdoc.info, Node: plscolbg; Set the background color by 8-bit RGB value, Next: plscolbga; Set the background color by 8-bit RGB value and PLFLT alpha transparency value_, Prev: plscol0a; Set 8-bit RGB values and PLFLT alpha transparency value for given cmap0 color index, Up: The Common API for PLplot 6012 601317.114 plscolbg: Set the background color by 8-bit RGB value 6014============================================================ 6015 6016 plscolbg ( r , g , b ); 6017 6018 Set the background color (color 0 in cmap0) by 8-bit RGB value (see 6019*note Color Map0::). 6020 6021‘r’ (‘‘PLINT’ (*note PLINT-type::)’, input) 6022 Unsigned 8-bit integer (0-255) representing the degree of red in 6023 the color. 6024 6025‘g’ (‘‘PLINT’ (*note PLINT-type::)’, input) 6026 Unsigned 8-bit integer (0-255) representing the degree of green in 6027 the color. 6028 6029‘b’ (‘‘PLINT’ (*note PLINT-type::)’, input) 6030 Unsigned 8-bit integer (0-255) representing the degree of blue in 6031 the color. 6032 6033 Redacted form: ‘plscolbg(r, g, b)’ 6034 6035 This function is used in examples 15 and 31. 6036 6037 6038File: plplotdoc.info, Node: plscolbga; Set the background color by 8-bit RGB value and PLFLT alpha transparency value_, Next: plscolor; Used to globally turn color output on/off, Prev: plscolbg; Set the background color by 8-bit RGB value, Up: The Common API for PLplot 6039 604017.115 plscolbga: Set the background color by 8-bit RGB value and PLFLT alpha transparency value. 6041================================================================================================= 6042 6043 plscolbga ( r , g , b , alpha ); 6044 6045 Set the background color (color 0 in cmap0) by 8-bit RGB value and 6046PLFLT alpha transparency value (see *note Color Map0::). 6047 6048‘r’ (‘‘PLINT’ (*note PLINT-type::)’, input) 6049 Unsigned 8-bit integer (0-255) representing the degree of red in 6050 the color. 6051 6052‘g’ (‘‘PLINT’ (*note PLINT-type::)’, input) 6053 Unsigned 8-bit integer (0-255) representing the degree of green in 6054 the color. 6055 6056‘b’ (‘‘PLINT’ (*note PLINT-type::)’, input) 6057 Unsigned 8-bit integer (0-255) representing the degree of blue in 6058 the color. 6059 6060‘alpha’ (‘‘PLFLT’ (*note PLFLT-type::)’, input) 6061 Value of the alpha transparency in the range (0.0-1.0). 6062 6063 This function is used in example 31. 6064 6065 6066File: plplotdoc.info, Node: plscolor; Used to globally turn color output on/off, Next: plscompression; Set device-compression level, Prev: plscolbga; Set the background color by 8-bit RGB value and PLFLT alpha transparency value_, Up: The Common API for PLplot 6067 606817.116 plscolor: Used to globally turn color output on/off 6069========================================================== 6070 6071 plscolor ( color ); 6072 6073 Used to globally turn color output on/off for those drivers/devices 6074that support it. 6075 6076‘color’ (‘‘PLINT’ (*note PLINT-type::)’, input) 6077 Color flag (Boolean). If zero, color is turned off. If non-zero, 6078 color is turned on. 6079 6080 Redacted form: ‘plscolor(color)’ 6081 6082 This function is used in example 31. 6083 6084 6085File: plplotdoc.info, Node: plscompression; Set device-compression level, Next: plsdev; Set the device [keyword] name, Prev: plscolor; Used to globally turn color output on/off, Up: The Common API for PLplot 6086 608717.117 plscompression: Set device-compression level 6088=================================================== 6089 6090 plscompression ( compression ); 6091 6092 Set device-compression level. Only used for drivers that provide 6093compression. This function, if used, should be invoked before a call to 6094‘plinit’ (*note plinit; Initialize PLplot::). 6095 6096‘compression’ (‘‘PLINT’ (*note PLINT-type::)’, input) 6097 The desired compression level. This is a device-dependent value. 6098 Currently only the jpeg and png devices use these values. For jpeg 6099 value is the jpeg quality which should normally be in the range 6100 0-95. Higher values denote higher quality and hence larger image 6101 sizes. For png values are in the range -1 to 99. Values of 0-9 6102 are taken as the compression level for zlib. A value of -1 denotes 6103 the default zlib compression level. Values in the range 10-99 are 6104 divided by 10 and then used as the zlib compression level. Higher 6105 compression levels correspond to greater compression and small file 6106 sizes at the expense of more computation. 6107 6108 Redacted form: ‘plscompression(compression)’ 6109 6110 This function is used in example 31. 6111 6112 6113File: plplotdoc.info, Node: plsdev; Set the device [keyword] name, Next: plsdidev; Set parameters that define current device-space window, Prev: plscompression; Set device-compression level, Up: The Common API for PLplot 6114 611517.118 plsdev: Set the device (keyword) name 6116============================================ 6117 6118 plsdev ( devname ); 6119 6120 Set the device (keyword) name. 6121 6122‘devname’ (‘‘PLCHAR_VECTOR’ (*note PLCHAR_VECTOR-type::)’, input) 6123 An ascii character string containing the device name keyword of the 6124 required output device. If ‘devname’ is NULL or if the first 6125 character of the string is a “?”, the normal (prompted) start up is 6126 used. 6127 6128 Redacted form: ‘plsdev(devname)’ 6129 6130 This function is used in examples 1, 14, and 20. 6131 6132 6133File: plplotdoc.info, Node: plsdidev; Set parameters that define current device-space window, Next: plsdimap; Set up transformation from metafile coordinates, Prev: plsdev; Set the device [keyword] name, Up: The Common API for PLplot 6134 613517.119 plsdidev: Set parameters that define current device-space window 6136======================================================================= 6137 6138 plsdidev ( mar , aspect , jx , jy ); 6139 6140 Set relative margin width, aspect ratio, and relative justification 6141that define current device-space window. If you want to just use the 6142previous value for any of these, just pass in the magic value PL_NOTSET. 6143It is unlikely that one should ever need to change the aspect ratio but 6144it’s in there for completeness. If ‘plsdidev’ (*note plsdidev; Set 6145parameters that define current device-space window::) is not called the 6146default values of ‘ ‘mar’ ’, ‘ ‘jx’ ’, and ‘ ‘jy’ ’ are all 0. ‘ 6147‘aspect’ ’ is set to a device-specific value. 6148 6149‘mar’ (‘‘PLFLT’ (*note PLFLT-type::)’, input) 6150 Relative margin width. 6151 6152‘aspect’ (‘‘PLFLT’ (*note PLFLT-type::)’, input) 6153 Aspect ratio. 6154 6155‘jx’ (‘‘PLFLT’ (*note PLFLT-type::)’, input) 6156 Relative justification in x. Value must lie in the range -0.5 to 6157 0.5. 6158 6159‘jy’ (‘‘PLFLT’ (*note PLFLT-type::)’, input) 6160 Relative justification in y. Value must lie in the range -0.5 to 6161 0.5. 6162 6163 Redacted form: ‘plsdidev(mar, aspect, jx, jy)’ 6164 6165 This function is used in example 31. 6166 6167 6168File: plplotdoc.info, Node: plsdimap; Set up transformation from metafile coordinates, Next: plsdiori; Set plot orientation, Prev: plsdidev; Set parameters that define current device-space window, Up: The Common API for PLplot 6169 617017.120 plsdimap: Set up transformation from metafile coordinates 6171================================================================ 6172 6173 plsdimap ( dimxmin , dimxmax , dimymin , dimymax , dimxpmm , 6174 dimypmm ); 6175 6176 Set up transformation from metafile coordinates. The size of the 6177plot is scaled so as to preserve aspect ratio. This isn’t intended to 6178be a general-purpose facility just yet (not sure why the user would need 6179it, for one). 6180 6181‘dimxmin’ (‘‘PLINT’ (*note PLINT-type::)’, input) 6182 NEEDS DOCUMENTATION 6183 6184‘dimxmax’ (‘‘PLINT’ (*note PLINT-type::)’, input) 6185 NEEDS DOCUMENTATION 6186 6187‘dimymin’ (‘‘PLINT’ (*note PLINT-type::)’, input) 6188 NEEDS DOCUMENTATION 6189 6190‘dimymax’ (‘‘PLINT’ (*note PLINT-type::)’, input) 6191 NEEDS DOCUMENTATION 6192 6193‘dimxpmm’ (‘‘PLFLT’ (*note PLFLT-type::)’, input) 6194 NEEDS DOCUMENTATION 6195 6196‘dimypmm’ (‘‘PLFLT’ (*note PLFLT-type::)’, input) 6197 NEEDS DOCUMENTATION 6198 6199 Redacted form: ‘plsdimap(dimxmin, dimxmax, dimymin, dimymax, dimxpmm, 6200dimypmm)’ 6201 6202 This function is not used in any examples. 6203 6204 6205File: plplotdoc.info, Node: plsdiori; Set plot orientation, Next: plsdiplt; Set parameters that define current plot-space window, Prev: plsdimap; Set up transformation from metafile coordinates, Up: The Common API for PLplot 6206 620717.121 plsdiori: Set plot orientation 6208===================================== 6209 6210 plsdiori ( rot ); 6211 6212 Set plot orientation parameter which is multiplied by 90 degrees to 6213obtain the angle of rotation. Note, arbitrary rotation parameters such 6214as 0.2 (corresponding to 18 degrees) are possible, but the usual values 6215for the rotation parameter are 0., 1., 2., and 3. corresponding to 0 6216degrees (landscape mode), 90 degrees (portrait mode), 180 degrees 6217(seascape mode), and 270 degrees (upside-down mode). If ‘plsdiori’ 6218(*note plsdiori; Set plot orientation::) is not called the default value 6219of ‘ ‘rot’ ’ is 0. 6220 6221 N.B. aspect ratio is unaffected by calls to ‘plsdiori’ (*note 6222plsdiori; Set plot orientation::). So you will probably want to change 6223the aspect ratio to a value suitable for the plot orientation using a 6224call to ‘plsdidev’ (*note plsdidev; Set parameters that define current 6225device-space window::) or the command-line options ‘ ‘-a’ ’ or ‘ 6226‘-freeaspect’ ’. For more documentation of those options see *note 6227Command Line Arguments::. Such command-line options can be set 6228internally using ‘plsetopt’ (*note plsetopt; Set any command-line 6229option::) or set directly using the command line and parsed using a call 6230to ‘plparseopts’ (*note plparseopts; Parse command-line arguments::). 6231 6232‘rot’ (‘‘PLFLT’ (*note PLFLT-type::)’, input) 6233 Plot orientation parameter. 6234 6235 Redacted form: ‘plsdiori(rot)’ 6236 6237 This function is not used in any examples. 6238 6239