1@c DO NOT EDIT! Generated automatically by munge-texi.pl. 2 3@c Copyright (C) 1996-2019 John W. Eaton 4@c 5@c This file is part of Octave. 6@c 7@c Octave is free software: you can redistribute it and/or modify it 8@c under the terms of the GNU General Public License as published by 9@c the Free Software Foundation, either version 3 of the License, or 10@c (at your option) any later version. 11@c 12@c Octave is distributed in the hope that it will be useful, but 13@c WITHOUT ANY WARRANTY; without even the implied warranty of 14@c MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 15@c GNU General Public License for more details. 16@c 17@c You should have received a copy of the GNU General Public License 18@c along with Octave; see the file COPYING. If not, see 19@c <https://www.gnu.org/licenses/>. 20 21@node Plotting 22@chapter Plotting 23@cindex plotting 24@cindex graphics 25 26@menu 27* Introduction to Plotting:: 28* High-Level Plotting:: 29* Graphics Data Structures:: 30* Advanced Plotting:: 31@end menu 32 33@node Introduction to Plotting 34@section Introduction to Plotting 35 36Earlier versions of Octave provided plotting through the use of gnuplot. This 37capability is still available. But, newer versions of Octave offer more modern 38plotting capabilities using OpenGL@. Which plotting system is used is 39controlled by the @code{graphics_toolkit} function. @xref{Graphics Toolkits}. 40 41The function call @code{graphics_toolkit ("qt")} selects the Qt/OpenGL system, 42@code{graphics_toolkit ("fltk")} selects the FLTK/OpenGL system, and 43@code{graphics_toolkit ("gnuplot")} selects the gnuplot system. The three 44systems may be used selectively through the use of the @code{graphics_toolkit} 45property of the graphics handle for each figure. This is explained in 46@ref{Graphics Data Structures}. 47 48@strong{Caution:} The OpenGL-based toolkits use single precision variables 49internally which limits the maximum value that can be displayed to 50approximately @math{10^{38}}. If your data contains larger values you must use 51the gnuplot toolkit which supports values up to @math{10^{308}}. Similarly, 52single precision variables can accurately represent only 6-9 base10 digits. If 53your data contains very fine differences (approximately 1e-8) these cannot be 54resolved with the OpenGL-based graphics toolkits and the gnuplot toolkit 55is required. 56 57@strong{Note:} The gnuplot graphics toolkit uses the third party program 58gnuplot for plotting. The communication from Octave to gnuplot is done via a 59one-way pipe. This has implications for performance and functionality. 60Performance is significantly slower because the entire data set, which could 61be many megabytes, must be passed to gnuplot over the pipe. Functionality 62is negatively affected because the pipe is one-way from Octave to gnuplot. 63Octave has no way of knowing about user interactions with the plot window (be 64it resizing, moving, closing, or anything else). It is recommended not to 65interact with (or close) a gnuplot window if you will access the figure from 66Octave later on. 67 68@node High-Level Plotting 69@section High-Level Plotting 70@cindex plotting, high-level 71 72Octave provides simple means to create many different types of two- and 73three-dimensional plots using high-level functions. 74 75If you need more detailed control, see @ref{Graphics Data Structures} 76and @ref{Advanced Plotting}. 77 78@menu 79* Two-Dimensional Plots:: 80* Three-Dimensional Plots:: 81* Plot Annotations:: 82* Multiple Plots on One Page:: 83* Multiple Plot Windows:: 84* Manipulation of Plot Objects:: 85* Manipulation of Plot Windows:: 86* Use of the @code{interpreter} Property:: 87* Printing and Saving Plots:: 88* Interacting with Plots:: 89* Test Plotting Functions:: 90@end menu 91 92@node Two-Dimensional Plots 93@subsection Two-Dimensional Plots 94 95@menu 96* Axis Configuration:: 97* Two-dimensional Function Plotting:: 98* Two-dimensional Geometric Shapes:: 99@end menu 100 101The @code{plot} function allows you to create simple x-y plots with 102linear axes. For example, 103 104@example 105@group 106x = -10:0.1:10; 107plot (x, sin (x)); 108xlabel ("x"); 109ylabel ("sin (x)"); 110title ("Simple 2-D Plot"); 111@end group 112@end example 113 114@noindent 115displays a sine wave shown in @ref{fig:plot}. On most systems, this 116command will open a separate plot window to display the graph. 117 118@float Figure,fig:plot 119@center @image{plot,4in} 120@caption{Simple Two-Dimensional Plot.} 121@end float 122 123@c plot scripts/plot/draw/plot.m 124@anchor{XREFplot} 125@deftypefn {} {} plot (@var{y}) 126@deftypefnx {} {} plot (@var{x}, @var{y}) 127@deftypefnx {} {} plot (@var{x}, @var{y}, @var{fmt}) 128@deftypefnx {} {} plot (@dots{}, @var{property}, @var{value}, @dots{}) 129@deftypefnx {} {} plot (@var{x1}, @var{y1}, @dots{}, @var{xn}, @var{yn}) 130@deftypefnx {} {} plot (@var{hax}, @dots{}) 131@deftypefnx {} {@var{h} =} plot (@dots{}) 132Produce 2-D plots. 133 134Many different combinations of arguments are possible. The simplest 135form is 136 137@example 138plot (@var{y}) 139@end example 140 141@noindent 142where the argument is taken as the set of @var{y} coordinates and the 143@var{x} coordinates are taken to be the range @code{1:numel (@var{y})}. 144 145If more than one argument is given, they are interpreted as 146 147@example 148plot (@var{y}, @var{property}, @var{value}, @dots{}) 149@end example 150 151@noindent 152or 153 154@example 155plot (@var{x}, @var{y}, @var{property}, @var{value}, @dots{}) 156@end example 157 158@noindent 159or 160 161@example 162plot (@var{x}, @var{y}, @var{fmt}, @dots{}) 163@end example 164 165@noindent 166and so on. Any number of argument sets may appear. The @var{x} and 167@var{y} values are interpreted as follows: 168 169@itemize @bullet 170@item 171If a single data argument is supplied, it is taken as the set of @var{y} 172coordinates and the @var{x} coordinates are taken to be the indices of 173the elements, starting with 1. 174 175@item 176If @var{x} and @var{y} are scalars, a single point is plotted. 177 178@item 179@code{squeeze()} is applied to arguments with more than two dimensions, 180but no more than two singleton dimensions. 181 182@item 183If both arguments are vectors, the elements of @var{y} are plotted versus 184the elements of @var{x}. 185 186@item 187If @var{x} is a vector and @var{y} is a matrix, then 188the columns (or rows) of @var{y} are plotted versus @var{x}. 189(using whichever combination matches, with columns tried first.) 190 191@item 192If the @var{x} is a matrix and @var{y} is a vector, 193@var{y} is plotted versus the columns (or rows) of @var{x}. 194(using whichever combination matches, with columns tried first.) 195 196@item 197If both arguments are matrices, the columns of @var{y} are plotted 198versus the columns of @var{x}. In this case, both matrices must have 199the same number of rows and columns and no attempt is made to transpose 200the arguments to make the number of rows match. 201@end itemize 202 203Multiple property-value pairs may be specified, but they must appear 204in pairs. These arguments are applied to the line objects drawn by 205@code{plot}. Useful properties to modify are @qcode{"linestyle"}, 206@qcode{"linewidth"}, @qcode{"color"}, @qcode{"marker"}, 207@qcode{"markersize"}, @qcode{"markeredgecolor"}, @qcode{"markerfacecolor"}. 208The full list of properties is documented at 209@ref{Line Properties}. 210 211The @var{fmt} format argument can also be used to control the plot style. 212It is a string composed of four optional parts: 213"<linestyle><marker><color><;displayname;>". 214When a marker is specified, but no linestyle, only the markers are 215plotted. Similarly, if a linestyle is specified, but no marker, then 216only lines are drawn. If both are specified then lines and markers will 217be plotted. If no @var{fmt} and no @var{property}/@var{value} pairs are 218given, then the default plot style is solid lines with no markers and the 219color determined by the @qcode{"colororder"} property of the current axes. 220 221Format arguments: 222 223@table @asis 224@item linestyle 225 226@multitable @columnfractions 0.06 0.94 227@item @samp{-} @tab Use solid lines (default). 228@item @samp{--} @tab Use dashed lines. 229@item @samp{:} @tab Use dotted lines. 230@item @samp{-.} @tab Use dash-dotted lines. 231@end multitable 232 233@item marker 234 235@multitable @columnfractions 0.06 0.94 236@item @samp{+} @tab crosshair 237@item @samp{o} @tab circle 238@item @samp{*} @tab star 239@item @samp{.} @tab point 240@item @samp{x} @tab cross 241@item @samp{s} @tab square 242@item @samp{d} @tab diamond 243@item @samp{^} @tab upward-facing triangle 244@item @samp{v} @tab downward-facing triangle 245@item @samp{>} @tab right-facing triangle 246@item @samp{<} @tab left-facing triangle 247@item @samp{p} @tab pentagram 248@item @samp{h} @tab hexagram 249@end multitable 250 251@item color 252 253@multitable @columnfractions 0.06 0.94 254@item @samp{k} @tab blacK 255@item @samp{r} @tab Red 256@item @samp{g} @tab Green 257@item @samp{b} @tab Blue 258@item @samp{y} @tab Yellow 259@item @samp{m} @tab Magenta 260@item @samp{c} @tab Cyan 261@item @samp{w} @tab White 262@end multitable 263 264@item @qcode{";displayname;"} 265Here @qcode{"displayname"} is the label to use for the plot legend. 266@end table 267 268The @var{fmt} argument may also be used to assign legend labels. 269To do so, include the desired label between semicolons after the 270formatting sequence described above, e.g., @qcode{"+b;Key Title;"}. 271Note that the last semicolon is required and Octave will generate 272an error if it is left out. 273 274Here are some plot examples: 275 276@example 277plot (x, y, "or", x, y2, x, y3, "m", x, y4, "+") 278@end example 279 280This command will plot @code{y} with red circles, @code{y2} with solid 281lines, @code{y3} with solid magenta lines, and @code{y4} with points 282displayed as @samp{+}. 283 284@example 285plot (b, "*", "markersize", 10) 286@end example 287 288This command will plot the data in the variable @code{b}, 289with points displayed as @samp{*} and a marker size of 10. 290 291@example 292@group 293t = 0:0.1:6.3; 294plot (t, cos(t), "-;cos(t);", t, sin(t), "-b;sin(t);"); 295@end group 296@end example 297 298This will plot the cosine and sine functions and label them accordingly 299in the legend. 300 301If the first argument @var{hax} is an axes handle, then plot into this axes, 302rather than the current axes returned by @code{gca}. 303 304The optional return value @var{h} is a vector of graphics handles to 305the created line objects. 306 307To save a plot, in one of several image formats such as PostScript 308or PNG, use the @code{print} command. 309 310@xseealso{@ref{XREFaxis,,axis}, @ref{XREFbox,,box}, @ref{XREFgrid,,grid}, @ref{XREFhold,,hold}, @ref{XREFlegend,,legend}, @ref{XREFtitle,,title}, @ref{XREFxlabel,,xlabel}, @ref{XREFylabel,,ylabel}, @ref{XREFxlim,,xlim}, @ref{XREFylim,,ylim}, @ref{XREFezplot,,ezplot}, @ref{XREFerrorbar,,errorbar}, @ref{XREFfplot,,fplot}, @ref{XREFline,,line}, @ref{XREFplot3,,plot3}, @ref{XREFpolar,,polar}, @ref{XREFloglog,,loglog}, @ref{XREFsemilogx,,semilogx}, @ref{XREFsemilogy,,semilogy}, @ref{XREFsubplot,,subplot}} 311@end deftypefn 312 313 314The @code{plotyy} function may be used to create a plot with two 315independent y axes. 316 317@c plotyy scripts/plot/draw/plotyy.m 318@anchor{XREFplotyy} 319@deftypefn {} {} plotyy (@var{x1}, @var{y1}, @var{x2}, @var{y2}) 320@deftypefnx {} {} plotyy (@dots{}, @var{fun}) 321@deftypefnx {} {} plotyy (@dots{}, @var{fun1}, @var{fun2}) 322@deftypefnx {} {} plotyy (@var{hax}, @dots{}) 323@deftypefnx {} {[@var{ax}, @var{h1}, @var{h2}] =} plotyy (@dots{}) 324Plot two sets of data with independent y-axes and a common x-axis. 325 326The arguments @var{x1} and @var{y1} define the arguments for the first plot 327and @var{x1} and @var{y2} for the second. 328 329By default the arguments are evaluated with 330@code{feval (@@plot, @var{x}, @var{y})}. However the type of plot can be 331modified with the @var{fun} argument, in which case the plots are 332generated by @code{feval (@var{fun}, @var{x}, @var{y})}. @var{fun} can be 333a function handle, an inline function, or a string of a function name. 334 335The function to use for each of the plots can be independently defined 336with @var{fun1} and @var{fun2}. 337 338If the first argument @var{hax} is an axes handle, then it defines 339the principal axes in which to plot the @var{x1} and @var{y1} data. 340 341The return value @var{ax} is a vector with the axes handles of the two 342y-axes. @var{h1} and @var{h2} are handles to the objects generated by the 343plot commands. 344 345@example 346@group 347x = 0:0.1:2*pi; 348y1 = sin (x); 349y2 = exp (x - 1); 350ax = plotyy (x, y1, x - 1, y2, @@plot, @@semilogy); 351xlabel ("X"); 352ylabel (ax(1), "Axis 1"); 353ylabel (ax(2), "Axis 2"); 354@end group 355@end example 356 357When using @code{plotyy} in conjunction with @code{subplot} make sure to 358call @code{subplot} first and pass the resulting axes handle to 359@code{plotyy}. Do not call @code{subplot} with any of the axes handles 360returned by @code{plotyy} or the other axes will be removed. 361 362@xseealso{@ref{XREFplot,,plot}, @ref{XREFsubplot,,subplot}} 363@end deftypefn 364 365 366The functions @code{semilogx}, @code{semilogy}, and @code{loglog} are 367similar to the @code{plot} function, but produce plots in which one or 368both of the axes use log scales. 369 370@c semilogx scripts/plot/draw/semilogx.m 371@anchor{XREFsemilogx} 372@deftypefn {} {} semilogx (@var{y}) 373@deftypefnx {} {} semilogx (@var{x}, @var{y}) 374@deftypefnx {} {} semilogx (@var{x}, @var{y}, @var{property}, @var{value}, @dots{}) 375@deftypefnx {} {} semilogx (@var{x}, @var{y}, @var{fmt}) 376@deftypefnx {} {} semilogx (@var{hax}, @dots{}) 377@deftypefnx {} {@var{h} =} semilogx (@dots{}) 378Produce a 2-D plot using a logarithmic scale for the x-axis. 379 380See the documentation of @code{plot} for a description of the 381arguments that @code{semilogx} will accept. 382 383If the first argument @var{hax} is an axes handle, then plot into this axes, 384rather than the current axes returned by @code{gca}. 385 386The optional return value @var{h} is a graphics handle to the created plot. 387@xseealso{@ref{XREFplot,,plot}, @ref{XREFsemilogy,,semilogy}, @ref{XREFloglog,,loglog}} 388@end deftypefn 389 390 391@c semilogy scripts/plot/draw/semilogy.m 392@anchor{XREFsemilogy} 393@deftypefn {} {} semilogy (@var{y}) 394@deftypefnx {} {} semilogy (@var{x}, @var{y}) 395@deftypefnx {} {} semilogy (@var{x}, @var{y}, @var{property}, @var{value}, @dots{}) 396@deftypefnx {} {} semilogy (@var{x}, @var{y}, @var{fmt}) 397@deftypefnx {} {} semilogy (@var{h}, @dots{}) 398@deftypefnx {} {@var{h} =} semilogy (@dots{}) 399Produce a 2-D plot using a logarithmic scale for the y-axis. 400 401See the documentation of @code{plot} for a description of the 402arguments that @code{semilogy} will accept. 403 404If the first argument @var{hax} is an axes handle, then plot into this axes, 405rather than the current axes returned by @code{gca}. 406 407The optional return value @var{h} is a graphics handle to the created plot. 408@xseealso{@ref{XREFplot,,plot}, @ref{XREFsemilogx,,semilogx}, @ref{XREFloglog,,loglog}} 409@end deftypefn 410 411 412@c loglog scripts/plot/draw/loglog.m 413@anchor{XREFloglog} 414@deftypefn {} {} loglog (@var{y}) 415@deftypefnx {} {} loglog (@var{x}, @var{y}) 416@deftypefnx {} {} loglog (@var{x}, @var{y}, @var{prop}, @var{value}, @dots{}) 417@deftypefnx {} {} loglog (@var{x}, @var{y}, @var{fmt}) 418@deftypefnx {} {} loglog (@var{hax}, @dots{}) 419@deftypefnx {} {@var{h} =} loglog (@dots{}) 420Produce a 2-D plot using logarithmic scales for both axes. 421 422See the documentation of @code{plot} for a description of the arguments 423that @code{loglog} will accept. 424 425If the first argument @var{hax} is an axes handle, then plot into this axes, 426rather than the current axes returned by @code{gca}. 427 428The optional return value @var{h} is a graphics handle to the created plot. 429@xseealso{@ref{XREFplot,,plot}, @ref{XREFsemilogx,,semilogx}, @ref{XREFsemilogy,,semilogy}} 430@end deftypefn 431 432 433The functions @code{bar}, @code{barh}, @code{stairs}, and @code{stem} 434are useful for displaying discrete data. For example, 435 436@example 437@group 438randn ("state", 1); 439hist (randn (10000, 1), 30); 440xlabel ("Value"); 441ylabel ("Count"); 442title ("Histogram of 10,000 normally distributed random numbers"); 443@end group 444@end example 445 446@noindent 447produces the histogram of 10,000 normally distributed random numbers 448shown in @ref{fig:hist}. Note that, @code{randn ("state", 1);}, initializes 449the random number generator for @code{randn} to a known value so that the 450returned values are reproducible; This guarantees that the figure produced 451is identical to the one in this manual. 452 453@float Figure,fig:hist 454@center @image{hist,4in} 455@caption{Histogram.} 456@end float 457 458@c bar scripts/plot/draw/bar.m 459@anchor{XREFbar} 460@deftypefn {} {} bar (@var{y}) 461@deftypefnx {} {} bar (@var{x}, @var{y}) 462@deftypefnx {} {} bar (@dots{}, @var{w}) 463@deftypefnx {} {} bar (@dots{}, @var{style}) 464@deftypefnx {} {} bar (@dots{}, @var{prop}, @var{val}, @dots{}) 465@deftypefnx {} {} bar (@var{hax}, @dots{}) 466@deftypefnx {} {@var{h} =} bar (@dots{}, @var{prop}, @var{val}, @dots{}) 467Produce a bar graph from two vectors of X-Y data. 468 469If only one argument is given, @var{y}, it is taken as a vector of Y values 470and the X coordinates are the range @code{1:numel (@var{y})}. 471 472The optional input @var{w} controls the width of the bars. A value of 4731.0 will cause each bar to exactly touch any adjacent bars. 474The default width is 0.8. 475 476If @var{y} is a matrix, then each column of @var{y} is taken to be a 477separate bar graph plotted on the same graph. By default the columns 478are plotted side-by-side. This behavior can be changed by the @var{style} 479argument which can take the following values: 480 481@table @asis 482@item @qcode{"grouped"} (default) 483Side-by-side bars with a gap between bars and centered over the 484X-coordinate. 485 486@item @qcode{"stacked"} 487Bars are stacked so that each X value has a single bar composed of 488multiple segments. 489 490@item @qcode{"hist"} 491Side-by-side bars with no gap between bars and centered over the 492X-coordinate. 493 494@item @qcode{"histc"} 495Side-by-side bars with no gap between bars and left-aligned to the 496X-coordinate. 497@end table 498 499Optional property/value pairs are passed directly to the underlying patch 500objects. The full list of properties is documented at 501@ref{Patch Properties}. 502 503If the first argument @var{hax} is an axes handle, then plot into this axes, 504rather than the current axes returned by @code{gca}. 505 506The optional return value @var{h} is a vector of handles to the created 507"bar series" hggroups with one handle per column of the variable @var{y}. 508This series makes it possible to change a common element in one bar series 509object and have the change reflected in the other "bar series". 510For example, 511 512@example 513@group 514h = bar (rand (5, 10)); 515set (h(1), "basevalue", 0.5); 516@end group 517@end example 518 519@noindent 520changes the position on the base of all of the bar series. 521 522The following example modifies the face and edge colors using 523property/value pairs. 524 525@example 526bar (randn (1, 100), "facecolor", "r", "edgecolor", "b"); 527@end example 528 529@noindent 530The color of the bars is taken from the figure's colormap, such that 531 532@example 533@group 534bar (rand (10, 3)); 535colormap (summer (64)); 536@end group 537@end example 538 539@noindent 540will change the colors used for the bars. The color of bars can also be set 541manually using the @qcode{"facecolor"} property as shown below. 542 543@example 544@group 545h = bar (rand (10, 3)); 546set (h(1), "facecolor", "r") 547set (h(2), "facecolor", "g") 548set (h(3), "facecolor", "b") 549@end group 550@end example 551 552@xseealso{@ref{XREFbarh,,barh}, @ref{XREFhist,,hist}, @ref{XREFpie,,pie}, @ref{XREFplot,,plot}, @ref{XREFpatch,,patch}} 553@end deftypefn 554 555 556@c barh scripts/plot/draw/barh.m 557@anchor{XREFbarh} 558@deftypefn {} {} barh (@var{y}) 559@deftypefnx {} {} barh (@var{x}, @var{y}) 560@deftypefnx {} {} barh (@dots{}, @var{w}) 561@deftypefnx {} {} barh (@dots{}, @var{style}) 562@deftypefnx {} {} barh (@dots{}, @var{prop}, @var{val}, @dots{}) 563@deftypefnx {} {} barh (@var{hax}, @dots{}) 564@deftypefnx {} {@var{h} =} barh (@dots{}, @var{prop}, @var{val}, @dots{}) 565Produce a horizontal bar graph from two vectors of X-Y data. 566 567If only one argument is given, it is taken as a vector of Y values 568and the X coordinates are the range @code{1:numel (@var{y})}. 569 570The optional input @var{w} controls the width of the bars. A value of 5711.0 will cause each bar to exactly touch any adjacent bars. 572The default width is 0.8. 573 574If @var{y} is a matrix, then each column of @var{y} is taken to be a 575separate bar graph plotted on the same graph. By default the columns 576are plotted side-by-side. This behavior can be changed by the @var{style} 577argument which can take the following values: 578 579@table @asis 580@item @qcode{"grouped"} (default) 581Side-by-side bars with a gap between bars and centered over the 582Y-coordinate. 583 584@item @qcode{"stacked"} 585Bars are stacked so that each Y value has a single bar composed of 586multiple segments. 587 588@item @qcode{"hist"} 589Side-by-side bars with no gap between bars and centered over the 590Y-coordinate. 591 592@item @qcode{"histc"} 593Side-by-side bars with no gap between bars and left-aligned to the 594Y-coordinate. 595@end table 596 597Optional property/value pairs are passed directly to the underlying patch 598objects. The full list of properties is documented at 599@ref{Patch Properties}. 600 601If the first argument @var{hax} is an axes handle, then plot into this axes, 602rather than the current axes returned by @code{gca}. 603 604The optional return value @var{h} is a graphics handle to the created 605bar series hggroup. For a description of the use of the 606bar series, @pxref{XREFbar,,bar}. 607@xseealso{@ref{XREFbar,,bar}, @ref{XREFhist,,hist}, @ref{XREFpie,,pie}, @ref{XREFplot,,plot}, @ref{XREFpatch,,patch}} 608@end deftypefn 609 610 611@c hist scripts/plot/draw/hist.m 612@anchor{XREFhist} 613@deftypefn {} {} hist (@var{y}) 614@deftypefnx {} {} hist (@var{y}, @var{nbins}) 615@deftypefnx {} {} hist (@var{y}, @var{x}) 616@deftypefnx {} {} hist (@var{y}, @var{x}, @var{norm}) 617@deftypefnx {} {} hist (@dots{}, @var{prop}, @var{val}, @dots{}) 618@deftypefnx {} {} hist (@var{hax}, @dots{}) 619@deftypefnx {} {[@var{nn}, @var{xx}] =} hist (@dots{}) 620Produce histogram counts or plots. 621 622With one vector input argument, @var{y}, plot a histogram of the values 623with 10 bins. The range of the histogram bins is determined by the 624range of the data (difference between maximum and minimum value in @var{y}). 625Extreme values are lumped into the first and last bins. If @var{y} is a 626matrix then plot a histogram where each bin contains one bar per input 627column of @var{y}. 628 629If the optional second argument is a scalar, @var{nbins}, it defines the 630number of bins. 631 632If the optional second argument is a vector, @var{x}, it defines the centers 633of the bins. The width of the bins is determined from the adjacent values 634in the vector. The total number of bins is @code{numel (@var{x})}. 635 636If a third argument @var{norm} is provided, the histogram is normalized. 637In case @var{norm} is a positive scalar, the resulting bars are normalized 638to @var{norm}. If @var{norm} is a vector of positive scalars of length 639@code{columns (@var{y})}, then the resulting bar of @code{@var{y}(:,i)} is 640normalized to @code{@var{norm}(i)}. 641 642@example 643@group 644[nn, xx] = hist (rand (10, 3), 5, [1 2 3]); 645sum (nn, 1) 646@result{} ans = 647 1 2 3 648@end group 649@end example 650 651The histogram's appearance may be modified by specifying property/value 652pairs to the underlying patch object. For example, the face and edge color 653may be modified: 654 655@example 656@group 657hist (randn (1, 100), 25, "facecolor", "r", "edgecolor", "b"); 658@end group 659@end example 660 661@noindent 662The histogram's colors also depend upon the current colormap. 663 664@example 665@group 666hist (rand (10, 3)); 667colormap (summer ()); 668@end group 669@end example 670 671The full list of patch properties is documented at @ref{Patch Properties}. 672 673If the first argument @var{hax} is an axes handle, then plot into this axes, 674rather than the current axes returned by @code{gca}. 675 676If an output is requested then no plot is made. Instead, return the values 677@var{nn} (numbers of elements) and @var{xx} (bin centers) such that 678@code{bar (@var{xx}, @var{nn})} will plot the histogram. 679 680@xseealso{@ref{XREFhistc,,histc}, @ref{XREFbar,,bar}, @ref{XREFpie,,pie}, @ref{XREFrose,,rose}} 681@end deftypefn 682 683 684@c stemleaf scripts/plot/draw/stemleaf.m 685@anchor{XREFstemleaf} 686@deftypefn {} {} stemleaf (@var{x}, @var{caption}) 687@deftypefnx {} {} stemleaf (@var{x}, @var{caption}, @var{stem_sz}) 688@deftypefnx {} {@var{plotstr} =} stemleaf (@dots{}) 689Compute and display a stem and leaf plot of the vector @var{x}. 690 691The input @var{x} should be a vector of integers. Any non-integer values 692will be converted to integer by @code{@var{x} = fix (@var{x})}. By default 693each element of @var{x} will be plotted with the last digit of the element 694as a leaf value and the remaining digits as the stem. For example, 123 695will be plotted with the stem @samp{12} and the leaf @samp{3}. The second 696argument, @var{caption}, should be a character array which provides a 697description of the data. It is included as a heading for the output. 698 699The optional input @var{stem_sz} sets the width of each stem. 700The stem width is determined by @code{10^(@var{stem_sz} + 1)}. 701The default stem width is 10. 702 703The output of @code{stemleaf} is composed of two parts: a 704"Fenced Letter Display," followed by the stem-and-leaf plot itself. 705The Fenced Letter Display is described in @cite{Exploratory Data Analysis}. 706Briefly, the entries are as shown: 707 708@example 709@group 710 711 Fenced Letter Display 712#% nx|___________________ nx = numel (x) 713M% mi| md | mi median index, md median 714H% hi|hl hu| hs hi lower hinge index, hl,hu hinges, 7151 |x(1) x(nx)| hs h_spreadx(1), x(nx) first 716 _______ and last data value. 717 ______|step |_______ step 1.5*h_spread 718 f|ifl ifh| inner fence, lower and higher 719 |nfl nfh| no.\ of data points within fences 720 F|ofl ofh| outer fence, lower and higher 721 |nFl nFh| no.\ of data points outside outer 722 fences 723@end group 724@end example 725 726The stem-and-leaf plot shows on each line the stem value followed by the 727string made up of the leaf digits. If the @var{stem_sz} is not 1 the 728successive leaf values are separated by ",". 729 730With no return argument, the plot is immediately displayed. If an output 731argument is provided, the plot is returned as an array of strings. 732 733The leaf digits are not sorted. If sorted leaf values are desired, use 734@code{@var{xs} = sort (@var{x})} before calling @code{stemleaf (@var{xs})}. 735 736The stem and leaf plot and associated displays are described in: 737Chapter 3, @cite{Exploratory Data Analysis} by @nospell{J. W. Tukey}, 738Addison-Wesley, 1977. 739@xseealso{@ref{XREFhist,,hist}, @ref{XREFprintd,,printd}} 740@end deftypefn 741 742 743@c printd scripts/plot/util/printd.m 744@anchor{XREFprintd} 745@deftypefn {} {} printd (@var{obj}, @var{filename}) 746@deftypefnx {} {@var{out_file} =} printd (@dots{}) 747 748Convert any object acceptable to @code{disp} into the format selected by 749the suffix of @var{filename}. 750 751If the return argument @var{out_file} is given, the name of the created 752file is returned. 753 754This function is intended to facilitate manipulation of the output of 755functions such as @code{stemleaf}. 756@xseealso{@ref{XREFstemleaf,,stemleaf}} 757@end deftypefn 758 759 760@c stairs scripts/plot/draw/stairs.m 761@anchor{XREFstairs} 762@deftypefn {} {} stairs (@var{y}) 763@deftypefnx {} {} stairs (@var{x}, @var{y}) 764@deftypefnx {} {} stairs (@dots{}, @var{style}) 765@deftypefnx {} {} stairs (@dots{}, @var{prop}, @var{val}, @dots{}) 766@deftypefnx {} {} stairs (@var{hax}, @dots{}) 767@deftypefnx {} {@var{h} =} stairs (@dots{}) 768@deftypefnx {} {[@var{xstep}, @var{ystep}] =} stairs (@dots{}) 769Produce a stairstep plot. 770 771The arguments @var{x} and @var{y} may be vectors or matrices. 772If only one argument is given, it is taken as a vector of Y values 773and the X coordinates are taken to be the indices of the elements 774(@code{@var{x} = 1:numel (@var{y})}). 775 776The style to use for the plot can be defined with a line style @var{style} 777of the same format as the @code{plot} command. 778 779Multiple property/value pairs may be specified, but they must appear in 780pairs. The full list of properties is documented at 781@ref{Line Properties}. 782 783If the first argument @var{hax} is an axes handle, then plot into this axes, 784rather than the current axes returned by @code{gca}. 785 786If one output argument is requested, return a graphics handle to the 787created plot. If two output arguments are specified, the data are generated 788but not plotted. For example, 789 790@example 791stairs (x, y); 792@end example 793 794@noindent 795and 796 797@example 798@group 799[xs, ys] = stairs (x, y); 800plot (xs, ys); 801@end group 802@end example 803 804@noindent 805are equivalent. 806@xseealso{@ref{XREFbar,,bar}, @ref{XREFhist,,hist}, @ref{XREFplot,,plot}, @ref{XREFstem,,stem}} 807@end deftypefn 808 809 810@c stem scripts/plot/draw/stem.m 811@anchor{XREFstem} 812@deftypefn {} {} stem (@var{y}) 813@deftypefnx {} {} stem (@var{x}, @var{y}) 814@deftypefnx {} {} stem (@dots{}, @var{linespec}) 815@deftypefnx {} {} stem (@dots{}, "filled") 816@deftypefnx {} {} stem (@dots{}, @var{prop}, @var{val}, @dots{}) 817@deftypefnx {} {} stem (@var{hax}, @dots{}) 818@deftypefnx {} {@var{h} =} stem (@dots{}) 819Plot a 2-D stem graph. 820 821If only one argument is given, it is taken as the y-values and the 822x-coordinates are taken from the indices of the elements. 823 824If @var{y} is a matrix, then each column of the matrix is plotted as 825a separate stem graph. In this case @var{x} can either be a vector, 826the same length as the number of rows in @var{y}, or it can be a 827matrix of the same size as @var{y}. 828 829The default color is @qcode{"b"} (blue), the default line style is 830@qcode{"-"}, and the default marker is @qcode{"o"}. The line style can 831be altered by the @var{linespec} argument in the same manner as the 832@code{plot} command. If the @qcode{"filled"} argument is present the 833markers at the top of the stems will be filled in. For example, 834 835@example 836@group 837x = 1:10; 838y = 2*x; 839stem (x, y, "r"); 840@end group 841@end example 842 843@noindent 844plots 10 stems with heights from 2 to 20 in red; 845 846Optional property/value pairs may be specified to control the appearance 847of the plot. The full list of properties is documented at 848@ref{Line Properties}. 849 850If the first argument @var{hax} is an axes handle, then plot into this axes, 851rather than the current axes returned by @code{gca}. 852 853The optional return value @var{h} is a handle to a @nospell{"stem series"} 854hggroup. The single hggroup handle has all of the graphical elements 855comprising the plot as its children; This allows the properties of 856multiple graphics objects to be changed by modifying just a single 857property of the @nospell{"stem series"} hggroup. 858 859For example, 860 861@example 862@group 863x = [0:10]'; 864y = [sin(x), cos(x)] 865h = stem (x, y); 866set (h(2), "color", "g"); 867set (h(1), "basevalue", -1) 868@end group 869@end example 870 871@noindent 872changes the color of the second @nospell{"stem series"} and moves the base 873line of the first. 874 875Stem Series Properties 876 877@table @asis 878@item linestyle 879The linestyle of the stem. (Default: @qcode{"-"}) 880 881@item linewidth 882The width of the stem. (Default: 0.5) 883 884@item color 885The color of the stem, and if not separately specified, the marker. 886(Default: @qcode{"b"} [blue]) 887 888@item marker 889The marker symbol to use at the top of each stem. (Default: @qcode{"o"}) 890 891@item markeredgecolor 892The edge color of the marker. (Default: @qcode{"color"} property) 893 894@item markerfacecolor 895The color to use for @nospell{"filling"} the marker. 896(Default: @qcode{"none"} [unfilled]) 897 898@item markersize 899The size of the marker. (Default: 6) 900 901@item baseline 902The handle of the line object which implements the baseline. Use @code{set} 903with the returned handle to change graphic properties of the baseline. 904 905@item basevalue 906The y-value where the baseline is drawn. (Default: 0) 907@end table 908@xseealso{@ref{XREFstem3,,stem3}, @ref{XREFbar,,bar}, @ref{XREFhist,,hist}, @ref{XREFplot,,plot}, @ref{XREFstairs,,stairs}} 909@end deftypefn 910 911 912@c stem3 scripts/plot/draw/stem3.m 913@anchor{XREFstem3} 914@deftypefn {} {} stem3 (@var{x}, @var{y}, @var{z}) 915@deftypefnx {} {} stem3 (@dots{}, @var{linespec}) 916@deftypefnx {} {} stem3 (@dots{}, "filled") 917@deftypefnx {} {} stem3 (@dots{}, @var{prop}, @var{val}, @dots{}) 918@deftypefnx {} {} stem3 (@var{hax}, @dots{}) 919@deftypefnx {} {@var{h} =} stem3 (@dots{}) 920Plot a 3-D stem graph. 921 922Stems are drawn from the height @var{z} to the location in the x-y plane 923determined by @var{x} and @var{y}. The default color is @qcode{"b"} (blue), 924the default line style is @qcode{"-"}, and the default marker is 925@qcode{"o"}. 926 927The line style can be altered by the @var{linespec} argument in the same 928manner as the @code{plot} command. If the @qcode{"filled"} argument is 929present the markers at the top of the stems will be filled in. 930 931Optional property/value pairs may be specified to control the appearance 932of the plot. The full list of properties is documented at 933@ref{Line Properties}. 934 935If the first argument @var{hax} is an axes handle, then plot into this axes, 936rather than the current axes returned by @code{gca}. 937 938The optional return value @var{h} is a handle to the @nospell{"stem series"} 939hggroup containing the line and marker objects used for the plot. 940@xref{XREFstem}, for a description of the @nospell{"stem series"} 941object. 942 943Example: 944 945@example 946@group 947theta = 0:0.2:6; 948stem3 (cos (theta), sin (theta), theta); 949@end group 950@end example 951 952@noindent 953plots 31 stems with heights from 0 to 6 lying on a circle. 954 955Implementation Note: Color definitions with RGB-triples are not valid. 956@xseealso{@ref{XREFstem,,stem}, @ref{XREFbar,,bar}, @ref{XREFhist,,hist}, @ref{XREFplot,,plot}} 957@end deftypefn 958 959 960@c scatter scripts/plot/draw/scatter.m 961@anchor{XREFscatter} 962@deftypefn {} {} scatter (@var{x}, @var{y}) 963@deftypefnx {} {} scatter (@var{x}, @var{y}, @var{s}) 964@deftypefnx {} {} scatter (@var{x}, @var{y}, @var{s}, @var{c}) 965@deftypefnx {} {} scatter (@dots{}, @var{style}) 966@deftypefnx {} {} scatter (@dots{}, "filled") 967@deftypefnx {} {} scatter (@dots{}, @var{prop}, @var{val}, @dots{}) 968@deftypefnx {} {} scatter (@var{hax}, @dots{}) 969@deftypefnx {} {@var{h} =} scatter (@dots{}) 970Draw a 2-D scatter plot. 971 972A marker is plotted at each point defined by the coordinates in the vectors 973@var{x} and @var{y}. 974 975The size of the markers is determined by @var{s}, which can be a scalar 976or a vector of the same length as @var{x} and @var{y}. If @var{s} 977is not given, or is an empty matrix, then a default value of 36 square 978points is used (The marker size itself is @code{sqrt (s)}). 979 980The color of the markers is determined by @var{c}, which can be a string 981defining a fixed color; a 3-element vector giving the red, green, and blue 982components of the color; a vector of the same length as @var{x} that gives 983a scaled index into the current colormap; or an @nospell{Nx3} matrix 984defining the RGB color of each marker individually. 985 986The marker to use can be changed with the @var{style} argument; it is a 987string defining a marker in the same manner as the @code{plot} command. 988If no marker is specified it defaults to @qcode{"o"} or circles. 989If the argument @qcode{"filled"} is given then the markers are filled. 990 991Additional property/value pairs are passed directly to the underlying 992patch object. The full list of properties is documented at 993@ref{Patch Properties}. 994 995If the first argument @var{hax} is an axes handle, then plot into this axes, 996rather than the current axes returned by @code{gca}. 997 998The optional return value @var{h} is a graphics handle to the created 999scatter object. 1000 1001Example: 1002 1003@example 1004@group 1005x = randn (100, 1); 1006y = randn (100, 1); 1007scatter (x, y, [], sqrt (x.^2 + y.^2)); 1008@end group 1009@end example 1010 1011@xseealso{@ref{XREFscatter3,,scatter3}, @ref{XREFpatch,,patch}, @ref{XREFplot,,plot}} 1012@end deftypefn 1013 1014 1015@c plotmatrix scripts/plot/draw/plotmatrix.m 1016@anchor{XREFplotmatrix} 1017@deftypefn {} {} plotmatrix (@var{x}, @var{y}) 1018@deftypefnx {} {} plotmatrix (@var{x}) 1019@deftypefnx {} {} plotmatrix (@dots{}, @var{style}) 1020@deftypefnx {} {} plotmatrix (@var{hax}, @dots{}) 1021@deftypefnx {} {[@var{h}, @var{ax}, @var{bigax}, @var{p}, @var{pax}] =} plotmatrix (@dots{}) 1022Scatter plot of the columns of one matrix against another. 1023 1024Given the arguments @var{x} and @var{y} that have a matching number of 1025rows, @code{plotmatrix} plots a set of axes corresponding to 1026 1027@example 1028plot (@var{x}(:, i), @var{y}(:, j)) 1029@end example 1030 1031When called with a single argument @var{x} this is equivalent to 1032 1033@example 1034plotmatrix (@var{x}, @var{x}) 1035@end example 1036 1037@noindent 1038except that the diagonal of the set of axes will be replaced with the 1039histogram @code{hist (@var{x}(:, i))}. 1040 1041The marker to use can be changed with the @var{style} argument, that is a 1042string defining a marker in the same manner as the @code{plot} command. 1043 1044If the first argument @var{hax} is an axes handle, then plot into this axes, 1045rather than the current axes returned by @code{gca}. 1046 1047The optional return value @var{h} provides handles to the individual 1048graphics objects in the scatter plots, whereas @var{ax} returns the 1049handles to the scatter plot axes objects. 1050 1051@var{bigax} is a hidden axes object that surrounds the other axes, such 1052that the commands @code{xlabel}, @code{title}, etc., will be associated 1053with this hidden axes. 1054 1055Finally, @var{p} returns the graphics objects associated with the histogram 1056and @var{pax} the corresponding axes objects. 1057 1058Example: 1059 1060@example 1061plotmatrix (randn (100, 3), "g+") 1062@end example 1063 1064@xseealso{@ref{XREFscatter,,scatter}, @ref{XREFplot,,plot}} 1065@end deftypefn 1066 1067 1068@c pareto scripts/plot/draw/pareto.m 1069@anchor{XREFpareto} 1070@deftypefn {} {} pareto (@var{y}) 1071@deftypefnx {} {} pareto (@var{y}, @var{x}) 1072@deftypefnx {} {} pareto (@var{hax}, @dots{}) 1073@deftypefnx {} {@var{h} =} pareto (@dots{}) 1074Draw a Pareto chart. 1075 1076A Pareto chart is a bar graph that arranges information in such a way 1077that priorities for process improvement can be established; It organizes 1078and displays information to show the relative importance of data. The chart 1079is similar to the histogram or bar chart, except that the bars are arranged 1080in decreasing magnitude from left to right along the x-axis. 1081 1082The fundamental idea (Pareto principle) behind the use of Pareto 1083diagrams is that the majority of an effect is due to a small subset of the 1084causes. For quality improvement, the first few contributing causes 1085(leftmost bars as presented on the diagram) to a problem usually account for 1086the majority of the result. Thus, targeting these "major causes" for 1087elimination results in the most cost-effective improvement scheme. 1088 1089Typically only the magnitude data @var{y} is present in which case 1090@var{x} is taken to be the range @code{1 : length (@var{y})}. If @var{x} 1091is given it may be a string array, a cell array of strings, or a numerical 1092vector. 1093 1094If the first argument @var{hax} is an axes handle, then plot into this axes, 1095rather than the current axes returned by @code{gca}. 1096 1097The optional return value @var{h} is a 2-element vector with a graphics 1098handle for the created bar plot and a second handle for the created line 1099plot. 1100 1101An example of the use of @code{pareto} is 1102 1103@example 1104@group 1105Cheese = @{"Cheddar", "Swiss", "Camembert", ... 1106 "Munster", "Stilton", "Blue"@}; 1107Sold = [105, 30, 70, 10, 15, 20]; 1108pareto (Sold, Cheese); 1109@end group 1110@end example 1111@xseealso{@ref{XREFbar,,bar}, @ref{XREFbarh,,barh}, @ref{XREFhist,,hist}, @ref{XREFpie,,pie}, @ref{XREFplot,,plot}} 1112@end deftypefn 1113 1114 1115@c rose scripts/plot/draw/rose.m 1116@anchor{XREFrose} 1117@deftypefn {} {} rose (@var{th}) 1118@deftypefnx {} {} rose (@var{th}, @var{nbins}) 1119@deftypefnx {} {} rose (@var{th}, @var{bins}) 1120@deftypefnx {} {} rose (@var{hax}, @dots{}) 1121@deftypefnx {} {@var{h} =} rose (@dots{}) 1122@deftypefnx {} {[@var{thout} @var{rout}] =} rose (@dots{}) 1123Plot an angular histogram. 1124 1125With one vector argument, @var{th}, plot the histogram with 20 angular bins. 1126If @var{th} is a matrix then each column of @var{th} produces a separate 1127histogram. 1128 1129If @var{nbins} is given and is a scalar, then the histogram is produced with 1130@var{nbin} bins. If @var{bins} is a vector, then the center of each bin is 1131defined by the values in @var{bins} and the number of bins is 1132given by the number of elements in @var{bins}. 1133 1134If the first argument @var{hax} is an axes handle, then plot into this axes, 1135rather than the current axes returned by @code{gca}. 1136 1137The optional return value @var{h} is a vector of graphics handles to the 1138line objects representing each histogram. 1139 1140If two output arguments are requested then no plot is made and 1141the polar vectors necessary to plot the histogram are returned instead. 1142 1143Example 1144 1145@example 1146@group 1147[th, r] = rose ([2*randn(1e5,1), pi + 2*randn(1e5,1)]); 1148polar (th, r); 1149@end group 1150@end example 1151 1152Programming Note: When specifying bin centers with the @var{bins} input, 1153the edges for bins 2 to N-1 are spaced so that @code{@var{bins}(i)} is 1154centered between the edges. The final edge is drawn halfway between bin N 1155and bin 1. This guarantees that all input @var{th} will be placed into one 1156of the bins, but also means that for some combinations bin 1 and bin N may 1157not be centered on the user's given values. 1158@xseealso{@ref{XREFhist,,hist}, @ref{XREFpolar,,polar}} 1159@end deftypefn 1160 1161 1162The @code{contour}, @code{contourf} and @code{contourc} functions 1163produce two-dimensional contour plots from three-dimensional data. 1164 1165@c contour scripts/plot/draw/contour.m 1166@anchor{XREFcontour} 1167@deftypefn {} {} contour (@var{z}) 1168@deftypefnx {} {} contour (@var{z}, @var{vn}) 1169@deftypefnx {} {} contour (@var{x}, @var{y}, @var{z}) 1170@deftypefnx {} {} contour (@var{x}, @var{y}, @var{z}, @var{vn}) 1171@deftypefnx {} {} contour (@dots{}, @var{style}) 1172@deftypefnx {} {} contour (@var{hax}, @dots{}) 1173@deftypefnx {} {[@var{c}, @var{h}] =} contour (@dots{}) 1174Create a 2-D contour plot. 1175 1176Plot level curves (contour lines) of the matrix @var{z}, using the 1177contour matrix @var{c} computed by @code{contourc} from the same 1178arguments; see the latter for their interpretation. 1179 1180The appearance of contour lines can be defined with a line style @var{style} 1181in the same manner as @code{plot}. Only line style and color are used; 1182Any markers defined by @var{style} are ignored. 1183 1184If the first argument @var{hax} is an axes handle, then plot into this axes, 1185rather than the current axes returned by @code{gca}. 1186 1187The optional output @var{c} contains the contour levels in @code{contourc} 1188format. 1189 1190The optional return value @var{h} is a graphics handle to the hggroup 1191comprising the contour lines. 1192 1193Example: 1194 1195@example 1196@group 1197x = 0:3; 1198y = 0:2; 1199z = y' * x; 1200contour (x, y, z, 2:3) 1201@end group 1202@end example 1203 1204@xseealso{@ref{XREFezcontour,,ezcontour}, @ref{XREFcontourc,,contourc}, @ref{XREFcontourf,,contourf}, @ref{XREFcontour3,,contour3}, @ref{XREFclabel,,clabel}, @ref{XREFmeshc,,meshc}, @ref{XREFsurfc,,surfc}, @ref{XREFcaxis,,caxis}, @ref{XREFcolormap,,colormap}, @ref{XREFplot,,plot}} 1205 1206@end deftypefn 1207 1208 1209@c contourf scripts/plot/draw/contourf.m 1210@anchor{XREFcontourf} 1211@deftypefn {} {} contourf (@var{z}) 1212@deftypefnx {} {} contourf (@var{z}, @var{vn}) 1213@deftypefnx {} {} contourf (@var{x}, @var{y}, @var{z}) 1214@deftypefnx {} {} contourf (@var{x}, @var{y}, @var{z}, @var{vn}) 1215@deftypefnx {} {} contourf (@dots{}, @var{style}) 1216@deftypefnx {} {} contourf (@var{hax}, @dots{}) 1217@deftypefnx {} {[@var{c}, @var{h}] =} contourf (@dots{}) 1218Create a 2-D contour plot with filled intervals. 1219 1220Plot level curves (contour lines) of the matrix @var{z} and fill the region 1221between lines with colors from the current colormap. 1222 1223The level curves are taken from the contour matrix @var{c} computed by 1224@code{contourc} for the same arguments; see the latter for their 1225interpretation. 1226 1227The appearance of contour lines can be defined with a line style @var{style} 1228in the same manner as @code{plot}. Only line style and color are used; 1229Any markers defined by @var{style} are ignored. 1230 1231If the first argument @var{hax} is an axes handle, then plot into this axes, 1232rather than the current axes returned by @code{gca}. 1233 1234The optional output @var{c} contains the contour levels in @code{contourc} 1235format. 1236 1237The optional return value @var{h} is a graphics handle to the hggroup 1238comprising the contour lines. 1239 1240The following example plots filled contours of the @code{peaks} function. 1241 1242@example 1243@group 1244[x, y, z] = peaks (50); 1245contourf (x, y, z, -7:9) 1246@end group 1247@end example 1248@xseealso{@ref{XREFezcontourf,,ezcontourf}, @ref{XREFcontour,,contour}, @ref{XREFcontourc,,contourc}, @ref{XREFcontour3,,contour3}, @ref{XREFclabel,,clabel}, @ref{XREFmeshc,,meshc}, @ref{XREFsurfc,,surfc}, @ref{XREFcaxis,,caxis}, @ref{XREFcolormap,,colormap}, @ref{XREFplot,,plot}} 1249@end deftypefn 1250 1251 1252@c contourc scripts/plot/draw/contourc.m 1253@anchor{XREFcontourc} 1254@deftypefn {} {[@var{c}, @var{lev}] =} contourc (@var{z}) 1255@deftypefnx {} {[@var{c}, @var{lev}] =} contourc (@var{z}, @var{vn}) 1256@deftypefnx {} {[@var{c}, @var{lev}] =} contourc (@var{x}, @var{y}, @var{z}) 1257@deftypefnx {} {[@var{c}, @var{lev}] =} contourc (@var{x}, @var{y}, @var{z}, @var{vn}) 1258Compute contour lines (isolines of constant Z value). 1259 1260The matrix @var{z} contains height values above the rectangular grid 1261determined by @var{x} and @var{y}. If only a single input @var{z} is 1262provided then @var{x} is taken to be @code{1:columns (@var{z})} and @var{y} 1263is taken to be @code{1:rows (@var{z})}. The minimum data size is 2x2. 1264 1265The optional input @var{vn} is either a scalar denoting the number of 1266contour lines to compute or a vector containing the Z values where lines 1267will be computed. When @var{vn} is a vector the number of contour lines 1268is @code{numel (@var{vn})}. However, to compute a single contour line 1269at a given value use @code{@var{vn} = [val, val]}. If @var{vn} is omitted 1270it defaults to 10. 1271 1272The return value @var{c} is a 2x@var{n} matrix containing the 1273contour lines in the following format 1274 1275@example 1276@group 1277@var{c} = [lev1, x1, x2, @dots{}, levn, x1, x2, ... 1278 len1, y1, y2, @dots{}, lenn, y1, y2, @dots{}] 1279@end group 1280@end example 1281 1282@noindent 1283in which contour line @var{n} has a level (height) of @var{levn} and 1284length of @var{lenn}. 1285 1286The optional return value @var{lev} is a vector with the Z values of 1287the contour levels. 1288 1289Example: 1290 1291@example 1292@group 1293x = 0:2; 1294y = x; 1295z = x' * y; 1296c = contourc (x, y, z, 2:3) 1297 @result{} c = 1298 2.0000 1.0000 1.0000 2.0000 2.0000 3.0000 1.5000 2.0000 1299 4.0000 2.0000 2.0000 1.0000 1.0000 2.0000 2.0000 1.5000 1300@end group 1301@end example 1302@xseealso{@ref{XREFcontour,,contour}, @ref{XREFcontourf,,contourf}, @ref{XREFcontour3,,contour3}, @ref{XREFclabel,,clabel}} 1303@end deftypefn 1304 1305 1306@c contour3 scripts/plot/draw/contour3.m 1307@anchor{XREFcontour3} 1308@deftypefn {} {} contour3 (@var{z}) 1309@deftypefnx {} {} contour3 (@var{z}, @var{vn}) 1310@deftypefnx {} {} contour3 (@var{x}, @var{y}, @var{z}) 1311@deftypefnx {} {} contour3 (@var{x}, @var{y}, @var{z}, @var{vn}) 1312@deftypefnx {} {} contour3 (@dots{}, @var{style}) 1313@deftypefnx {} {} contour3 (@var{hax}, @dots{}) 1314@deftypefnx {} {[@var{c}, @var{h}] =} contour3 (@dots{}) 1315Create a 3-D contour plot. 1316 1317@code{contour3} plots level curves (contour lines) of the matrix @var{z} 1318at a Z level corresponding to each contour. This is in contrast to 1319@code{contour} which plots all of the contour lines at the same Z level 1320and produces a 2-D plot. 1321 1322The level curves are taken from the contour matrix @var{c} computed by 1323@code{contourc} for the same arguments; see the latter for their 1324interpretation. 1325 1326The appearance of contour lines can be defined with a line style @var{style} 1327in the same manner as @code{plot}. Only line style and color are used; 1328Any markers defined by @var{style} are ignored. 1329 1330If the first argument @var{hax} is an axes handle, then plot into this axes, 1331rather than the current axes returned by @code{gca}. 1332 1333The optional output @var{c} are the contour levels in @code{contourc} 1334format. 1335 1336The optional return value @var{h} is a graphics handle to the hggroup 1337comprising the contour lines. 1338 1339Example: 1340 1341@example 1342@group 1343contour3 (peaks (19)); 1344colormap cool; 1345hold on; 1346surf (peaks (19), "facecolor", "none", "edgecolor", "black"); 1347@end group 1348@end example 1349 1350@xseealso{@ref{XREFcontour,,contour}, @ref{XREFcontourc,,contourc}, @ref{XREFcontourf,,contourf}, @ref{XREFclabel,,clabel}, @ref{XREFmeshc,,meshc}, @ref{XREFsurfc,,surfc}, @ref{XREFcaxis,,caxis}, @ref{XREFcolormap,,colormap}, @ref{XREFplot,,plot}} 1351@end deftypefn 1352 1353 1354The @code{errorbar}, @code{semilogxerr}, @code{semilogyerr}, and 1355@code{loglogerr} functions produce plots with error bar markers. For 1356example, 1357 1358@example 1359@group 1360rand ("state", 2); 1361x = 0:0.1:10; 1362y = sin (x); 1363lerr = 0.1 .* rand (size (x)); 1364uerr = 0.1 .* rand (size (x)); 1365errorbar (x, y, lerr, uerr); 1366axis ([0, 10, -1.1, 1.1]); 1367xlabel ("x"); 1368ylabel ("sin (x)"); 1369title ("Errorbar plot of sin (x)"); 1370@end group 1371@end example 1372 1373@noindent 1374produces the figure shown in @ref{fig:errorbar}. 1375 1376@float Figure,fig:errorbar 1377@center @image{errorbar,4in} 1378@caption{Errorbar plot.} 1379@end float 1380 1381@c errorbar scripts/plot/draw/errorbar.m 1382@anchor{XREFerrorbar} 1383@deftypefn {} {} errorbar (@var{y}, @var{ey}) 1384@deftypefnx {} {} errorbar (@var{y}, @dots{}, @var{fmt}) 1385@deftypefnx {} {} errorbar (@var{x}, @var{y}, @var{ey}) 1386@deftypefnx {} {} errorbar (@var{x}, @var{y}, @var{err}, @var{fmt}) 1387@deftypefnx {} {} errorbar (@var{x}, @var{y}, @var{lerr}, @var{uerr}, @var{fmt}) 1388@deftypefnx {} {} errorbar (@var{x}, @var{y}, @var{ex}, @var{ey}, @var{fmt}) 1389@deftypefnx {} {} errorbar (@var{x}, @var{y}, @var{lx}, @var{ux}, @var{ly}, @var{uy}, @var{fmt}) 1390@deftypefnx {} {} errorbar (@var{x1}, @var{y1}, @dots{}, @var{fmt}, @var{xn}, @var{yn}, @dots{}) 1391@deftypefnx {} {} errorbar (@var{hax}, @dots{}) 1392@deftypefnx {} {@var{h} =} errorbar (@dots{}) 1393Create a 2-D plot with errorbars. 1394 1395Many different combinations of arguments are possible. The simplest form is 1396 1397@example 1398errorbar (@var{y}, @var{ey}) 1399@end example 1400 1401@noindent 1402where the first argument is taken as the set of @var{y} coordinates, the 1403second argument @var{ey} are the errors around the @var{y} values, and the 1404@var{x} coordinates are taken to be the indices of the elements 1405(@code{1:numel (@var{y})}). 1406 1407The general form of the function is 1408 1409@example 1410errorbar (@var{x}, @var{y}, @var{err1}, @dots{}, @var{fmt}, @dots{}) 1411@end example 1412 1413@noindent 1414After the @var{x} and @var{y} arguments there can be 1, 2, or 4 1415parameters specifying the error values depending on the nature of the error 1416values and the plot format @var{fmt}. 1417 1418@table @asis 1419@item @var{err} (scalar) 1420When the error is a scalar all points share the same error value. 1421The errorbars are symmetric and are drawn from @var{data}-@var{err} to 1422@var{data}+@var{err}. 1423The @var{fmt} argument determines whether @var{err} is in the x-direction, 1424y-direction (default), or both. 1425 1426@item @var{err} (vector or matrix) 1427Each data point has a particular error value. 1428The errorbars are symmetric and are drawn from @var{data}(n)-@var{err}(n) to 1429@var{data}(n)+@var{err}(n). 1430 1431@item @var{lerr}, @var{uerr} (scalar) 1432The errors have a single low-side value and a single upper-side value. 1433The errorbars are not symmetric and are drawn from @var{data}-@var{lerr} to 1434@var{data}+@var{uerr}. 1435 1436@item @var{lerr}, @var{uerr} (vector or matrix) 1437Each data point has a low-side error and an upper-side error. 1438The errorbars are not symmetric and are drawn from 1439@var{data}(n)-@var{lerr}(n) to @var{data}(n)+@var{uerr}(n). 1440@end table 1441 1442Any number of data sets (@var{x1},@var{y1}, @var{x2},@var{y2}, @dots{}) may 1443appear as long as they are separated by a format string @var{fmt}. 1444 1445If @var{y} is a matrix, @var{x} and the error parameters must also be 1446matrices having the same dimensions. The columns of @var{y} are plotted 1447versus the corresponding columns of @var{x} and errorbars are taken from 1448the corresponding columns of the error parameters. 1449 1450If @var{fmt} is missing, the yerrorbars ("~") plot style is assumed. 1451 1452If the @var{fmt} argument is supplied then it is interpreted, as in normal 1453plots, to specify the line style, marker, and color. In addition, 1454@var{fmt} may include an errorbar style which @strong{must precede} the 1455ordinary format codes. The following errorbar styles are supported: 1456 1457@table @samp 1458@item ~ 1459Set yerrorbars plot style (default). 1460 1461@item > 1462Set xerrorbars plot style. 1463 1464@item ~> 1465Set xyerrorbars plot style. 1466 1467@item #~ 1468Set yboxes plot style. 1469 1470@item # 1471Set xboxes plot style. 1472 1473@item #~> 1474Set xyboxes plot style. 1475@end table 1476 1477If the first argument @var{hax} is an axes handle, then plot into this axes, 1478rather than the current axes returned by @code{gca}. 1479 1480The optional return value @var{h} is a handle to the hggroup object 1481representing the data plot and errorbars. 1482 1483Note: For compatibility with @sc{matlab} a line is drawn through all data 1484points. However, most scientific errorbar plots are a scatter plot of 1485points with errorbars. To accomplish this, add a marker style to the 1486@var{fmt} argument such as @qcode{"."}. Alternatively, remove the line 1487by modifying the returned graphic handle with 1488@code{set (h, "linestyle", "none")}. 1489 1490Examples: 1491 1492@example 1493errorbar (@var{x}, @var{y}, @var{ex}, ">.r") 1494@end example 1495 1496@noindent 1497produces an xerrorbar plot of @var{y} versus @var{x} with @var{x} 1498errorbars drawn from @var{x}-@var{ex} to @var{x}+@var{ex}. The marker 1499@qcode{"."} is used so no connecting line is drawn and the errorbars 1500appear in red. 1501 1502@example 1503@group 1504errorbar (@var{x}, @var{y1}, @var{ey}, "~", 1505 @var{x}, @var{y2}, @var{ly}, @var{uy}) 1506@end group 1507@end example 1508 1509@noindent 1510produces yerrorbar plots with @var{y1} and @var{y2} versus @var{x}. 1511Errorbars for @var{y1} are drawn from @var{y1}-@var{ey} to 1512@var{y1}+@var{ey}, errorbars for @var{y2} from @var{y2}-@var{ly} to 1513@var{y2}+@var{uy}. 1514 1515@example 1516@group 1517errorbar (@var{x}, @var{y}, @var{lx}, @var{ux}, 1518 @var{ly}, @var{uy}, "~>") 1519@end group 1520@end example 1521 1522@noindent 1523produces an xyerrorbar plot of @var{y} versus @var{x} in which 1524@var{x} errorbars are drawn from @var{x}-@var{lx} to @var{x}+@var{ux} 1525and @var{y} errorbars from @var{y}-@var{ly} to @var{y}+@var{uy}. 1526@xseealso{@ref{XREFsemilogxerr,,semilogxerr}, @ref{XREFsemilogyerr,,semilogyerr}, @ref{XREFloglogerr,,loglogerr}, @ref{XREFplot,,plot}} 1527@end deftypefn 1528 1529 1530@c semilogxerr scripts/plot/draw/semilogxerr.m 1531@anchor{XREFsemilogxerr} 1532@deftypefn {} {} semilogxerr (@var{y}, @var{ey}) 1533@deftypefnx {} {} semilogxerr (@var{y}, @dots{}, @var{fmt}) 1534@deftypefnx {} {} semilogxerr (@var{x}, @var{y}, @var{ey}) 1535@deftypefnx {} {} semilogxerr (@var{x}, @var{y}, @var{err}, @var{fmt}) 1536@deftypefnx {} {} semilogxerr (@var{x}, @var{y}, @var{lerr}, @var{uerr}, @var{fmt}) 1537@deftypefnx {} {} semilogxerr (@var{x}, @var{y}, @var{ex}, @var{ey}, @var{fmt}) 1538@deftypefnx {} {} semilogxerr (@var{x}, @var{y}, @var{lx}, @var{ux}, @var{ly}, @var{uy}, @var{fmt}) 1539@deftypefnx {} {} semilogxerr (@var{x1}, @var{y1}, @dots{}, @var{fmt}, @var{xn}, @var{yn}, @dots{}) 1540@deftypefnx {} {} semilogxerr (@var{hax}, @dots{}) 1541@deftypefnx {} {@var{h} =} semilogxerr (@dots{}) 1542Produce 2-D plots using a logarithmic scale for the x-axis and errorbars 1543at each data point. 1544 1545Many different combinations of arguments are possible. The most common 1546form is 1547 1548@example 1549semilogxerr (@var{x}, @var{y}, @var{ey}, @var{fmt}) 1550@end example 1551 1552@noindent 1553which produces a semi-logarithmic plot of @var{y} versus @var{x} 1554with errors in the @var{y}-scale defined by @var{ey} and the plot 1555format defined by @var{fmt}. @xref{XREFerrorbar,,errorbar}, for available 1556formats and additional information. 1557 1558If the first argument @var{hax} is an axes handle, then plot into this axes, 1559rather than the current axes returned by @code{gca}. 1560 1561@xseealso{@ref{XREFerrorbar,,errorbar}, @ref{XREFsemilogyerr,,semilogyerr}, @ref{XREFloglogerr,,loglogerr}} 1562@end deftypefn 1563 1564 1565@c semilogyerr scripts/plot/draw/semilogyerr.m 1566@anchor{XREFsemilogyerr} 1567@deftypefn {} {} semilogyerr (@var{y}, @var{ey}) 1568@deftypefnx {} {} semilogyerr (@var{y}, @dots{}, @var{fmt}) 1569@deftypefnx {} {} semilogyerr (@var{x}, @var{y}, @var{ey}) 1570@deftypefnx {} {} semilogyerr (@var{x}, @var{y}, @var{err}, @var{fmt}) 1571@deftypefnx {} {} semilogyerr (@var{x}, @var{y}, @var{lerr}, @var{uerr}, @var{fmt}) 1572@deftypefnx {} {} semilogyerr (@var{x}, @var{y}, @var{ex}, @var{ey}, @var{fmt}) 1573@deftypefnx {} {} semilogyerr (@var{x}, @var{y}, @var{lx}, @var{ux}, @var{ly}, @var{uy}, @var{fmt}) 1574@deftypefnx {} {} semilogyerr (@var{x1}, @var{y1}, @dots{}, @var{fmt}, @var{xn}, @var{yn}, @dots{}) 1575@deftypefnx {} {} semilogyerr (@var{hax}, @dots{}) 1576@deftypefnx {} {@var{h} =} semilogyerr (@dots{}) 1577Produce 2-D plots using a logarithmic scale for the y-axis and errorbars 1578at each data point. 1579 1580Many different combinations of arguments are possible. The most common 1581form is 1582 1583@example 1584semilogyerr (@var{x}, @var{y}, @var{ey}, @var{fmt}) 1585@end example 1586 1587@noindent 1588which produces a semi-logarithmic plot of @var{y} versus @var{x} 1589with errors in the @var{y}-scale defined by @var{ey} and the plot 1590format defined by @var{fmt}. @xref{XREFerrorbar,,errorbar}, for available 1591formats and additional information. 1592 1593If the first argument @var{hax} is an axes handle, then plot into this axes, 1594rather than the current axes returned by @code{gca}. 1595 1596@xseealso{@ref{XREFerrorbar,,errorbar}, @ref{XREFsemilogxerr,,semilogxerr}, @ref{XREFloglogerr,,loglogerr}} 1597@end deftypefn 1598 1599 1600@c loglogerr scripts/plot/draw/loglogerr.m 1601@anchor{XREFloglogerr} 1602@deftypefn {} {} loglogerr (@var{y}, @var{ey}) 1603@deftypefnx {} {} loglogerr (@var{y}, @dots{}, @var{fmt}) 1604@deftypefnx {} {} loglogerr (@var{x}, @var{y}, @var{ey}) 1605@deftypefnx {} {} loglogerr (@var{x}, @var{y}, @var{err}, @var{fmt}) 1606@deftypefnx {} {} loglogerr (@var{x}, @var{y}, @var{lerr}, @var{uerr}, @var{fmt}) 1607@deftypefnx {} {} loglogerr (@var{x}, @var{y}, @var{ex}, @var{ey}, @var{fmt}) 1608@deftypefnx {} {} loglogerr (@var{x}, @var{y}, @var{lx}, @var{ux}, @var{ly}, @var{uy}, @var{fmt}) 1609@deftypefnx {} {} loglogerr (@var{x1}, @var{y1}, @dots{}, @var{fmt}, @var{xn}, @var{yn}, @dots{}) 1610@deftypefnx {} {} loglogerr (@var{hax}, @dots{}) 1611@deftypefnx {} {@var{h} =} loglogerr (@dots{}) 1612Produce 2-D plots on a double logarithm axis with errorbars. 1613 1614Many different combinations of arguments are possible. The most common 1615form is 1616 1617@example 1618loglogerr (@var{x}, @var{y}, @var{ey}, @var{fmt}) 1619@end example 1620 1621@noindent 1622which produces a double logarithm plot of @var{y} versus @var{x} 1623with errors in the @var{y}-scale defined by @var{ey} and the plot 1624format defined by @var{fmt}. @xref{XREFerrorbar,,errorbar}, for available 1625formats and additional information. 1626 1627If the first argument @var{hax} is an axes handle, then plot into this axes, 1628rather than the current axes returned by @code{gca}. 1629@xseealso{@ref{XREFerrorbar,,errorbar}, @ref{XREFsemilogxerr,,semilogxerr}, @ref{XREFsemilogyerr,,semilogyerr}} 1630@end deftypefn 1631 1632 1633Finally, the @code{polar} function allows you to easily plot data in 1634polar coordinates. However, the display coordinates remain rectangular 1635and linear. For example, 1636 1637@example 1638@group 1639polar (0:0.1:10*pi, 0:0.1:10*pi); 1640title ("Example polar plot from 0 to 10*pi"); 1641@end group 1642@end example 1643 1644@noindent 1645produces the spiral plot shown in @ref{fig:polar}. 1646 1647@float Figure,fig:polar 1648@center @image{polar,4in} 1649@caption{Polar plot.} 1650@end float 1651 1652@c polar scripts/plot/draw/polar.m 1653@anchor{XREFpolar} 1654@deftypefn {} {} polar (@var{theta}, @var{rho}) 1655@deftypefnx {} {} polar (@var{theta}, @var{rho}, @var{fmt}) 1656@deftypefnx {} {} polar (@var{cplx}) 1657@deftypefnx {} {} polar (@var{cplx}, @var{fmt}) 1658@deftypefnx {} {} polar (@var{hax}, @dots{}) 1659@deftypefnx {} {@var{h} =} polar (@dots{}) 1660Create a 2-D plot from polar coordinates @var{theta} and @var{rho}. 1661 1662The input @var{theta} is assumed to be radians and is converted to degrees 1663for plotting. If you have degrees then you must convert 1664(@pxref{XREFcart2pol,,cart2pol}) to radians before passing the data to this 1665function. 1666 1667If a single complex input @var{cplx} is given then the real part is used 1668for @var{theta} and the imaginary part is used for @var{rho}. 1669 1670The optional argument @var{fmt} specifies the line format in the same way 1671as @code{plot}. 1672 1673If the first argument @var{hax} is an axes handle, then plot into this axes, 1674rather than the current axes returned by @code{gca}. 1675 1676The optional return value @var{h} is a graphics handle to the created plot. 1677 1678Implementation Note: The polar axis is drawn using line and text objects 1679encapsulated in an hggroup. The hggroup properties are linked to the 1680original axes object such that altering an appearance property, for example 1681@code{fontname}, will update the polar axis. Two new properties are 1682added to the original axes--@code{rtick}, @code{ttick}--which replace 1683@code{xtick}, @code{ytick}. The first is a list of tick locations in the 1684radial (rho) direction; The second is a list of tick locations in the 1685angular (theta) direction specified in degrees, i.e., in the range 0--359. 1686@xseealso{@ref{XREFrose,,rose}, @ref{XREFcompass,,compass}, @ref{XREFplot,,plot}, @ref{XREFcart2pol,,cart2pol}} 1687@end deftypefn 1688 1689 1690@c pie scripts/plot/draw/pie.m 1691@anchor{XREFpie} 1692@deftypefn {} {} pie (@var{x}) 1693@deftypefnx {} {} pie (@dots{}, @var{explode}) 1694@deftypefnx {} {} pie (@dots{}, @var{labels}) 1695@deftypefnx {} {} pie (@var{hax}, @dots{}) 1696@deftypefnx {} {@var{h} =} pie (@dots{}) 1697Plot a 2-D pie chart. 1698 1699When called with a single vector argument, produce a pie chart of the 1700elements in @var{x}. The size of the ith slice is the percentage that the 1701element @var{x}i represents of the total sum of @var{x}: 1702@code{pct = @var{x}(i) / sum (@var{x})}. 1703 1704The optional input @var{explode} is a vector of the same length as @var{x} 1705that, if nonzero, "explodes" the slice from the pie chart. 1706 1707The optional input @var{labels} is a cell array of strings of the same 1708length as @var{x} specifying the label for each slice. 1709 1710If the first argument @var{hax} is an axes handle, then plot into this axes, 1711rather than the current axes returned by @code{gca}. 1712 1713The optional return value @var{h} is a list of handles to the patch 1714and text objects generating the plot. 1715 1716Note: If @code{sum (@var{x}) @leq{} 1} then the elements of @var{x} are 1717interpreted as percentages directly and are not normalized by @code{sum 1718(x)}. Furthermore, if the sum is less than 1 then there will be a missing 1719slice in the pie plot to represent the missing, unspecified percentage. 1720 1721@xseealso{@ref{XREFpie3,,pie3}, @ref{XREFbar,,bar}, @ref{XREFhist,,hist}, @ref{XREFrose,,rose}} 1722@end deftypefn 1723 1724 1725@c pie3 scripts/plot/draw/pie3.m 1726@anchor{XREFpie3} 1727@deftypefn {} {} pie3 (@var{x}) 1728@deftypefnx {} {} pie3 (@dots{}, @var{explode}) 1729@deftypefnx {} {} pie3 (@dots{}, @var{labels}) 1730@deftypefnx {} {} pie3 (@var{hax}, @dots{}) 1731@deftypefnx {} {@var{h} =} pie3 (@dots{}) 1732Plot a 3-D pie chart. 1733 1734Called with a single vector argument, produces a 3-D pie chart of the 1735elements in @var{x}. The size of the ith slice is the percentage that the 1736element @var{x}i represents of the total sum of @var{x}: 1737@code{pct = @var{x}(i) / sum (@var{x})}. 1738 1739The optional input @var{explode} is a vector of the same length as @var{x} 1740that, if nonzero, "explodes" the slice from the pie chart. 1741 1742The optional input @var{labels} is a cell array of strings of the same 1743length as @var{x} specifying the label for each slice. 1744 1745If the first argument @var{hax} is an axes handle, then plot into this axes, 1746rather than the current axes returned by @code{gca}. 1747 1748The optional return value @var{h} is a list of graphics handles to the 1749patch, surface, and text objects generating the plot. 1750 1751Note: If @code{sum (@var{x}) @leq{} 1} then the elements of @var{x} are 1752interpreted as percentages directly and are not normalized by @code{sum 1753(x)}. Furthermore, if the sum is less than 1 then there will be a missing 1754slice in the pie plot to represent the missing, unspecified percentage. 1755 1756@xseealso{@ref{XREFpie,,pie}, @ref{XREFbar,,bar}, @ref{XREFhist,,hist}, @ref{XREFrose,,rose}} 1757@end deftypefn 1758 1759 1760@c quiver scripts/plot/draw/quiver.m 1761@anchor{XREFquiver} 1762@deftypefn {} {} quiver (@var{u}, @var{v}) 1763@deftypefnx {} {} quiver (@var{x}, @var{y}, @var{u}, @var{v}) 1764@deftypefnx {} {} quiver (@dots{}, @var{s}) 1765@deftypefnx {} {} quiver (@dots{}, @var{style}) 1766@deftypefnx {} {} quiver (@dots{}, "filled") 1767@deftypefnx {} {} quiver (@var{hax}, @dots{}) 1768@deftypefnx {} {@var{h} =} quiver (@dots{}) 1769 1770Plot a 2-D vector field with arrows. 1771 1772Plot the (@var{u}, @var{v}) components of a vector field at the grid points 1773defined by (@var{x}, @var{y}). If the grid is uniform then @var{x} and 1774@var{y} can be specified as vectors and @code{meshgrid} is used to create 1775the 2-D grid. 1776 1777If @var{x} and @var{y} are not given they are assumed to be 1778@code{(1:@var{m}, 1:@var{n})} where 1779@code{[@var{m}, @var{n}] = size (@var{u})}. 1780 1781The optional input @var{s} is a scalar defining a scaling factor to use for 1782the arrows of the field relative to the mesh spacing. A value of 1.0 will 1783result in the longest vector exactly filling one grid square. A value of 0 1784disables all scaling. The default value is 0.9. 1785 1786The style to use for the plot can be defined with a line style @var{style} 1787of the same format as the @code{plot} command. If a marker is specified 1788then the markers are drawn at the origin of the vectors (which are the grid 1789points defined by @var{x} and @var{y}). When a marker is specified, the 1790arrowhead is not drawn. If the argument @qcode{"filled"} is given then the 1791markers are filled. 1792 1793If the first argument @var{hax} is an axes handle, then plot into this axes, 1794rather than the current axes returned by @code{gca}. 1795 1796The optional return value @var{h} is a graphics handle to a quiver object. 1797A quiver object regroups the components of the quiver plot (body, arrow, 1798and marker), and allows them to be changed together. 1799 1800Example: 1801 1802@example 1803@group 1804[x, y] = meshgrid (1:2:20); 1805h = quiver (x, y, sin (2*pi*x/10), sin (2*pi*y/10)); 1806set (h, "maxheadsize", 0.33); 1807@end group 1808@end example 1809 1810@xseealso{@ref{XREFquiver3,,quiver3}, @ref{XREFcompass,,compass}, @ref{XREFfeather,,feather}, @ref{XREFplot,,plot}} 1811@end deftypefn 1812 1813 1814@c quiver3 scripts/plot/draw/quiver3.m 1815@anchor{XREFquiver3} 1816@deftypefn {} {} quiver3 (@var{x}, @var{y}, @var{z}, @var{u}, @var{v}, @var{w}) 1817@deftypefnx {} {} quiver3 (@var{z}, @var{u}, @var{v}, @var{w}) 1818@deftypefnx {} {} quiver3 (@dots{}, @var{s}) 1819@deftypefnx {} {} quiver3 (@dots{}, @var{style}) 1820@deftypefnx {} {} quiver3 (@dots{}, "filled") 1821@deftypefnx {} {} quiver3 (@var{hax}, @dots{}) 1822@deftypefnx {} {@var{h} =} quiver3 (@dots{}) 1823 1824Plot a 3-D vector field with arrows. 1825 1826Plot the (@var{u}, @var{v}, @var{w}) components of a vector field at the 1827grid points defined by (@var{x}, @var{y}, @var{z}). If the grid is uniform 1828then @var{x}, @var{y}, and @var{z} can be specified as vectors and 1829@code{meshgrid} is used to create the 3-D grid. 1830 1831If @var{x} and @var{y} are not given they are assumed to be 1832@code{(1:@var{m}, 1:@var{n})} where 1833@code{[@var{m}, @var{n}] = size (@var{u})}. 1834 1835The optional input @var{s} is a scalar defining a scaling factor to use for 1836the arrows of the field relative to the mesh spacing. A value of 1.0 will 1837result in the longest vector exactly filling one grid cube. A value of 0 1838disables all scaling. The default value is 0.9. 1839 1840The style to use for the plot can be defined with a line style @var{style} 1841of the same format as the @code{plot} command. If a marker is specified 1842then the markers are drawn at the origin of the vectors (which are the grid 1843points defined by @var{x}, @var{y}, @var{z}). When a marker is specified, 1844the arrowhead is not drawn. If the argument @qcode{"filled"} is given then 1845the markers are filled. 1846 1847If the first argument @var{hax} is an axes handle, then plot into this axes, 1848rather than the current axes returned by @code{gca}. 1849 1850The optional return value @var{h} is a graphics handle to a quiver object. 1851A quiver object regroups the components of the quiver plot (body, arrow, 1852and marker), and allows them to be changed together. 1853 1854@example 1855@group 1856[x, y, z] = peaks (25); 1857surf (x, y, z); 1858hold on; 1859[u, v, w] = surfnorm (x, y, z / 10); 1860h = quiver3 (x, y, z, u, v, w); 1861set (h, "maxheadsize", 0.33); 1862@end group 1863@end example 1864 1865@xseealso{@ref{XREFquiver,,quiver}, @ref{XREFcompass,,compass}, @ref{XREFfeather,,feather}, @ref{XREFplot,,plot}} 1866@end deftypefn 1867 1868 1869@c streamtube scripts/plot/draw/streamtube.m 1870@anchor{XREFstreamtube} 1871@deftypefn {} {} streamtube (@var{x}, @var{y}, @var{z}, @var{u}, @var{v}, @var{w}, @var{sx}, @var{sy}, @var{sz}) 1872@deftypefnx {} {} streamtube (@var{u}, @var{v}, @var{w}, @var{sx}, @var{sy}, @var{sz}) 1873@deftypefnx {} {} streamtube (@var{xyz}, @var{x}, @var{y}, @var{z}, @var{div}) 1874@deftypefnx {} {} streamtube (@var{xyz}, @var{div}) 1875@deftypefnx {} {} streamtube (@var{xyz}, @var{dia}) 1876@deftypefnx {} {} streamtube (@dots{}, @var{options}) 1877@deftypefnx {} {} streamtube (@var{hax}, @dots{}) 1878@deftypefnx {} {@var{h} =} streamtube (@dots{}) 1879Plot tubes scaled by the divergence along streamlines. 1880 1881@code{streamtube} draws tubes whose diameter is scaled by the divergence of 1882a vector field. The vector field is given by 1883@code{[@var{u}, @var{v}, @var{w}]} and is defined over a rectangular grid 1884given by @code{[@var{x}, @var{y}, @var{z}]}. The tubes start at the 1885seed points @code{[@var{sx}, @var{sy}, @var{sz}]} and are plot along 1886streamlines. 1887 1888@code{streamtube} can also be called with a cell array containing 1889pre-computed streamline data. To do this, @var{xyz} must be created with 1890the @code{stream3} command. @var{div} is used to scale the tubes. 1891In order to plot tubes scaled by the vector field divergence, @var{div} 1892must be calculated with the @code{divergence} command. 1893 1894A tube diameter of zero corresponds to the smallest scaling value along the 1895streamline and the largest tube diameter corresponds to the largest scaling 1896value. 1897 1898It is also possible to draw a tube along an arbitrary array of vertices 1899@var{xyz}. The tube diameter can be specified by the vertex array @var{dia} 1900or by a constant. 1901 1902The input parameter @var{options} is a 2-D vector of the form 1903@code{[@var{scale}, @var{n}]}. The first parameter scales the tube 1904diameter (default 1). The second parameter specifies the number of vertices 1905that are used to construct the tube circumference (default 20). 1906 1907If the first argument @var{hax} is an axes handle, then plot into this axes, 1908rather than the current axes returned by @code{gca}. 1909 1910The optional return value @var{h} is a graphics handle to the plot objects 1911created for each tube. 1912 1913@xseealso{@ref{XREFstream3,,stream3}, @ref{XREFstreamline,,streamline}, @ref{XREFostreamtube,,ostreamtube}} 1914@end deftypefn 1915 1916 1917@c ostreamtube scripts/plot/draw/ostreamtube.m 1918@anchor{XREFostreamtube} 1919@deftypefn {} {} ostreamtube (@var{x}, @var{y}, @var{z}, @var{u}, @var{v}, @var{w}, @var{sx}, @var{sy}, @var{sz}) 1920@deftypefnx {} {} ostreamtube (@var{u}, @var{v}, @var{w}, @var{sx}, @var{sy}, @var{sz}) 1921@deftypefnx {} {} ostreamtube (@var{xyz}, @var{x}, @var{y}, @var{z}, @var{u}, @var{v}, @var{w}) 1922@deftypefnx {} {} ostreamtube (@dots{}, @var{options}) 1923@deftypefnx {} {} ostreamtube (@var{hax}, @dots{}) 1924@deftypefnx {} {@var{h} =} ostreamtube (@dots{}) 1925Calculate and display streamtubes. 1926 1927Streamtubes are approximated by connecting circular crossflow areas 1928along a streamline. The expansion of the flow is determined by the local 1929crossflow divergence. 1930 1931The vector field is given by @code{[@var{u}, @var{v}, @var{w}]} and is 1932defined over a rectangular grid given by @code{[@var{x}, @var{y}, @var{z}]}. 1933The streamtubes start at the seed points 1934@code{[@var{sx}, @var{sy}, @var{sz}]}. 1935 1936The tubes are colored based on the local vector field strength. 1937 1938The input parameter @var{options} is a 2-D vector of the form 1939@code{[@var{scale}, @var{n}]}. The first parameter scales the start radius 1940of the streamtubes (default 1). The second parameter specifies the number 1941of vertices that are used to construct the tube circumference (default 20). 1942 1943@code{ostreamtube} can be called with a cell array containing pre-computed 1944streamline data. To do this, @var{xyz} must be created with the 1945@code{stream3} function. This option is useful if you need to alter the 1946integrator step size or the maximum number of vertices of the streamline. 1947 1948If the first argument @var{hax} is an axes handle, then plot into this axes, 1949rather than the current axes returned by @code{gca}. 1950 1951The optional return value @var{h} is a graphics handle to the plot 1952objects created for each streamtube. 1953 1954Example: 1955 1956@example 1957@group 1958[x, y, z] = meshgrid (-1:0.1:1, -1:0.1:1, -3:0.1:0); 1959u = -x / 10 - y; 1960v = x - y / 10; 1961w = - ones (size (x)) / 10; 1962ostreamtube (x, y, z, u, v, w, 1, 0, 0); 1963@end group 1964@end example 1965 1966@xseealso{@ref{XREFstream3,,stream3}, @ref{XREFstreamline,,streamline}, @ref{XREFstreamtube,,streamtube}} 1967@end deftypefn 1968 1969 1970@c streamline scripts/plot/draw/streamline.m 1971@anchor{XREFstreamline} 1972@deftypefn {} {} streamline (@var{x}, @var{y}, @var{z}, @var{u}, @var{v}, @var{w}, @var{sx}, @var{sy}, @var{sz}) 1973@deftypefnx {} {} streamline (@var{u}, @var{v}, @var{w}, @var{sx}, @var{sy}, @var{sz}) 1974@deftypefnx {} {} streamline (@dots{}, @var{options}) 1975@deftypefnx {} {} streamline (@var{hax}, @dots{}) 1976@deftypefnx {} {@var{h} =} streamline (@dots{}) 1977Plot streamlines of 2-D or 3-D vector fields. 1978 1979Plot streamlines of a 2-D or 3-D vector field given by 1980@code{[@var{u}, @var{v}]} or @code{[@var{u}, @var{v}, @var{w}]}. The vector 1981field is defined over a rectangular grid given by @code{[@var{x}, @var{y}]} 1982or @code{[@var{x}, @var{y}, @var{z}]}. The streamlines start at the seed 1983points @code{[@var{sx}, @var{sy}]} or @code{[@var{sx}, @var{sy}, @var{sz}]}. 1984 1985The input parameter @var{options} is a 2-D vector of the form 1986@code{[@var{stepsize}, @var{max_vertices}]}. The first parameter 1987specifies the step size used for trajectory integration (default 0.1). A 1988negative value is allowed which will reverse the direction of integration. 1989The second parameter specifies the maximum number of segments used to 1990create a streamline (default 10,000). 1991 1992If the first argument @var{hax} is an axes handle, then plot into this axes, 1993rather than the current axes returned by @code{gca}. 1994 1995The optional return value @var{h} is a graphics handle to the hggroup 1996comprising the field lines. 1997 1998Example: 1999 2000@example 2001@group 2002[x, y] = meshgrid (-1.5:0.2:2, -1:0.2:2); 2003u = - x / 4 - y; 2004v = x - y / 4; 2005streamline (x, y, u, v, 1.7, 1.5); 2006@end group 2007@end example 2008 2009@xseealso{@ref{XREFstream2,,stream2}, @ref{XREFstream3,,stream3}, @ref{XREFstreamtube,,streamtube}, @ref{XREFostreamtube,,ostreamtube}} 2010@end deftypefn 2011 2012 2013@c stream2 scripts/plot/draw/stream2.m 2014@anchor{XREFstream2} 2015@deftypefn {} {@var{xy} =} stream2 (@var{x}, @var{y}, @var{u}, @var{v}, @var{sx}, @var{sy}) 2016@deftypefnx {} {@var{xy} =} stream2 (@var{u}, @var{v}, @var{sx}, @var{sy}) 2017@deftypefnx {} {@var{xy} =} stream2 (@dots{}, @var{options}) 2018Compute 2-D streamline data. 2019 2020Calculates streamlines of a vector field given by @code{[@var{u}, @var{v}]}. 2021The vector field is defined over a rectangular grid given by 2022@code{[@var{x}, @var{y}]}. The streamlines start at the seed points 2023@code{[@var{sx}, @var{sy}]}. The returned value @var{xy} contains a cell 2024array of vertex arrays. If the starting point is outside the vector field, 2025@code{[]} is returned. 2026 2027The input parameter @var{options} is a 2-D vector of the form 2028@code{[@var{stepsize}, @var{max_vertices}]}. The first parameter 2029specifies the step size used for trajectory integration (default 0.1). A 2030negative value is allowed which will reverse the direction of integration. 2031The second parameter specifies the maximum number of segments used to 2032create a streamline (default 10,000). 2033 2034The return value @var{xy} is a @nospell{nverts x 2} matrix containing the 2035coordinates of the field line segments. 2036 2037Example: 2038 2039@example 2040@group 2041[x, y] = meshgrid (0:3); 2042u = 2 * x; 2043v = y; 2044xy = stream2 (x, y, u, v, 1.0, 0.5); 2045@end group 2046@end example 2047 2048@xseealso{@ref{XREFstreamline,,streamline}, @ref{XREFstream3,,stream3}} 2049@end deftypefn 2050 2051 2052@c stream3 scripts/plot/draw/stream3.m 2053@anchor{XREFstream3} 2054@deftypefn {} {@var{xyz} =} stream3 (@var{x}, @var{y}, @var{z}, @var{u}, @var{v}, @var{w}, @var{sx}, @var{sy}, @var{sz}) 2055@deftypefnx {} {@var{xyz} =} stream3 (@var{u}, @var{v}, @var{w}, @var{sx}, @var{sy}, @var{sz}) 2056@deftypefnx {} {@var{xyz} =} stream3 (@dots{}, @var{options}) 2057Compute 3-D streamline data. 2058 2059Calculate streamlines of a vector field given by @code{[@var{u}, @var{v}, 2060@var{w}]}. The vector field is defined over a rectangular grid given by 2061@code{[@var{x}, @var{y}, @var{z}]}. The streamlines start at the seed 2062points @code{[@var{sx}, @var{sy}, @var{sz}]}. The returned value @var{xyz} 2063contains a cell array of vertex arrays. If the starting point is outside 2064the vector field, @code{[]} is returned. 2065 2066The input parameter @var{options} is a 2-D vector of the form 2067@code{[@var{stepsize}, @var{max_vertices}]}. The first parameter 2068specifies the step size used for trajectory integration (default 0.1). A 2069negative value is allowed which will reverse the direction of integration. 2070The second parameter specifies the maximum number of segments used to 2071create a streamline (default 10,000). 2072 2073The return value @var{xyz} is a @nospell{nverts x 3} matrix containing the 2074coordinates of the field line segments. 2075 2076Example: 2077 2078@example 2079@group 2080[x, y, z] = meshgrid (0:3); 2081u = 2 * x; 2082v = y; 2083w = 3 * z; 2084xyz = stream3 (x, y, z, u, v, w, 1.0, 0.5, 0.0); 2085@end group 2086@end example 2087 2088@xseealso{@ref{XREFstream2,,stream2}, @ref{XREFstreamline,,streamline}, @ref{XREFstreamtube,,streamtube}, @ref{XREFostreamtube,,ostreamtube}} 2089@end deftypefn 2090 2091 2092@c compass scripts/plot/draw/compass.m 2093@anchor{XREFcompass} 2094@deftypefn {} {} compass (@var{u}, @var{v}) 2095@deftypefnx {} {} compass (@var{z}) 2096@deftypefnx {} {} compass (@dots{}, @var{style}) 2097@deftypefnx {} {} compass (@var{hax}, @dots{}) 2098@deftypefnx {} {@var{h} =} compass (@dots{}) 2099 2100Plot the @code{(@var{u}, @var{v})} components of a vector field emanating 2101from the origin of a polar plot. 2102 2103The arrow representing each vector has one end at the origin and the tip at 2104[@var{u}(i), @var{v}(i)]. If a single complex argument @var{z} is given, 2105then @code{@var{u} = real (@var{z})} and @code{@var{v} = imag (@var{z})}. 2106 2107The style to use for the plot can be defined with a line style @var{style} 2108of the same format as the @code{plot} command. 2109 2110If the first argument @var{hax} is an axes handle, then plot into this axes, 2111rather than the current axes returned by @code{gca}. 2112 2113The optional return value @var{h} is a vector of graphics handles to the 2114line objects representing the drawn vectors. 2115 2116@example 2117@group 2118a = toeplitz ([1;randn(9,1)], [1,randn(1,9)]); 2119compass (eig (a)); 2120@end group 2121@end example 2122 2123@xseealso{@ref{XREFpolar,,polar}, @ref{XREFfeather,,feather}, @ref{XREFquiver,,quiver}, @ref{XREFrose,,rose}, @ref{XREFplot,,plot}} 2124@end deftypefn 2125 2126 2127@c feather scripts/plot/draw/feather.m 2128@anchor{XREFfeather} 2129@deftypefn {} {} feather (@var{u}, @var{v}) 2130@deftypefnx {} {} feather (@var{z}) 2131@deftypefnx {} {} feather (@dots{}, @var{style}) 2132@deftypefnx {} {} feather (@var{hax}, @dots{}) 2133@deftypefnx {} {@var{h} =} feather (@dots{}) 2134 2135Plot the @code{(@var{u}, @var{v})} components of a vector field emanating 2136from equidistant points on the x-axis. 2137 2138If a single complex argument @var{z} is given, then 2139@code{@var{u} = real (@var{z})} and @code{@var{v} = imag (@var{z})}. 2140 2141The style to use for the plot can be defined with a line style @var{style} 2142of the same format as the @code{plot} command. 2143 2144If the first argument @var{hax} is an axes handle, then plot into this axes, 2145rather than the current axes returned by @code{gca}. 2146 2147The optional return value @var{h} is a vector of graphics handles to the 2148line objects representing the drawn vectors. 2149 2150@example 2151@group 2152phi = [0 : 15 : 360] * pi/180; 2153feather (sin (phi), cos (phi)); 2154@end group 2155@end example 2156 2157@xseealso{@ref{XREFplot,,plot}, @ref{XREFquiver,,quiver}, @ref{XREFcompass,,compass}} 2158@end deftypefn 2159 2160 2161@c pcolor scripts/plot/draw/pcolor.m 2162@anchor{XREFpcolor} 2163@deftypefn {} {} pcolor (@var{x}, @var{y}, @var{c}) 2164@deftypefnx {} {} pcolor (@var{c}) 2165@deftypefnx {} {} pcolor (@var{hax}, @dots{}) 2166@deftypefnx {} {@var{h} =} pcolor (@dots{}) 2167Produce a 2-D density plot. 2168 2169A @code{pcolor} plot draws rectangles with colors from the matrix @var{c} 2170over the two-dimensional region represented by the matrices @var{x} and 2171@var{y}. @var{x} and @var{y} are the coordinates of the mesh's vertices 2172and are typically the output of @code{meshgrid}. If @var{x} and @var{y} are 2173vectors, then a typical vertex is (@var{x}(j), @var{y}(i), @var{c}(i,j)). 2174Thus, columns of @var{c} correspond to different @var{x} values and rows 2175of @var{c} correspond to different @var{y} values. 2176 2177The values in @var{c} are scaled to span the range of the current 2178colormap. Limits may be placed on the color axis by the command 2179@code{caxis}, or by setting the @code{clim} property of the parent axis. 2180 2181The face color of each cell of the mesh is determined by interpolating 2182the values of @var{c} for each of the cell's vertices; Contrast this with 2183@code{imagesc} which renders one cell for each element of @var{c}. 2184 2185@code{shading} modifies an attribute determining the manner by which the 2186face color of each cell is interpolated from the values of @var{c}, 2187and the visibility of the cells' edges. By default the attribute is 2188@qcode{"faceted"}, which renders a single color for each cell's face with 2189the edge visible. 2190 2191If the first argument @var{hax} is an axes handle, then plot into this axes, 2192rather than the current axes returned by @code{gca}. 2193 2194The optional return value @var{h} is a graphics handle to the created 2195surface object. 2196 2197@xseealso{@ref{XREFcaxis,,caxis}, @ref{XREFshading,,shading}, @ref{XREFmeshgrid,,meshgrid}, @ref{XREFcontour,,contour}, @ref{XREFimagesc,,imagesc}} 2198@end deftypefn 2199 2200 2201@c area scripts/plot/draw/area.m 2202@anchor{XREFarea} 2203@deftypefn {} {} area (@var{y}) 2204@deftypefnx {} {} area (@var{x}, @var{y}) 2205@deftypefnx {} {} area (@dots{}, @var{lvl}) 2206@deftypefnx {} {} area (@dots{}, @var{prop}, @var{val}, @dots{}) 2207@deftypefnx {} {} area (@var{hax}, @dots{}) 2208@deftypefnx {} {@var{h} =} area (@dots{}) 2209Area plot of the columns of @var{y}. 2210 2211This plot shows the contributions of each column value to the row sum. 2212It is functionally similar to @code{plot (@var{x}, cumsum (@var{y}, 2))}, 2213except that the area under the curve is shaded. 2214 2215If the @var{x} argument is omitted it defaults to @code{1:rows (@var{y})}. 2216A value @var{lvl} can be defined that determines where the base level of 2217the shading under the curve should be defined. The default level is 0. 2218 2219Additional property/value pairs are passed directly to the underlying patch 2220object. The full list of properties is documented at 2221@ref{Patch Properties}. 2222 2223If the first argument @var{hax} is an axes handle, then plot into this axes, 2224rather than the current axes returned by @code{gca}. 2225 2226The optional return value @var{h} is a graphics handle to the hggroup 2227object comprising the area patch objects. The @qcode{"BaseValue"} property 2228of the hggroup can be used to adjust the level where shading begins. 2229 2230Example: Verify identity sin^2 + cos^2 = 1 2231 2232@example 2233@group 2234t = linspace (0, 2*pi, 100)'; 2235y = [sin(t).^2, cos(t).^2]; 2236area (t, y); 2237legend ("sin^2", "cos^2", "location", "NorthEastOutside"); 2238@end group 2239@end example 2240@xseealso{@ref{XREFplot,,plot}, @ref{XREFpatch,,patch}} 2241@end deftypefn 2242 2243 2244@c fill scripts/plot/draw/fill.m 2245@anchor{XREFfill} 2246@deftypefn {} {} fill (@var{x}, @var{y}, @var{c}) 2247@deftypefnx {} {} fill (@var{x1}, @var{y1}, @var{c1}, @var{x2}, @var{y2}, @var{c2}) 2248@deftypefnx {} {} fill (@dots{}, @var{prop}, @var{val}) 2249@deftypefnx {} {} fill (@var{hax}, @dots{}) 2250@deftypefnx {} {@var{h} =} fill (@dots{}) 2251Create one or more filled 2-D polygons. 2252 2253The inputs @var{x} and @var{y} are the coordinates of the polygon vertices. 2254If the inputs are matrices then the rows represent different vertices and 2255each column produces a different polygon. @code{fill} will close any open 2256polygons before plotting. 2257 2258The input @var{c} determines the color of the polygon. The simplest form 2259is a single color specification such as a @code{plot} format or an 2260RGB-triple. In this case the polygon(s) will have one unique color. If 2261@var{c} is a vector or matrix then the color data is first scaled using 2262@code{caxis} and then indexed into the current colormap. A row vector will 2263color each polygon (a column from matrices @var{x} and @var{y}) with a 2264single computed color. A matrix @var{c} of the same size as @var{x} and 2265@var{y} will compute the color of each vertex and then interpolate the face 2266color between the vertices. 2267 2268Multiple property/value pairs for the underlying patch object may be 2269specified, but they must appear in pairs. The full list of properties is 2270documented at @ref{Patch Properties}. 2271 2272If the first argument @var{hax} is an axes handle, then plot into this axes, 2273rather than the current axes returned by @code{gca}. 2274 2275The optional return value @var{h} is a vector of graphics handles to 2276the created patch objects. 2277 2278Example: red square 2279 2280@example 2281@group 2282vertices = [0 0 2283 1 0 2284 1 1 2285 0 1]; 2286fill (vertices(:,1), vertices(:,2), "r"); 2287axis ([-0.5 1.5, -0.5 1.5]) 2288axis equal 2289@end group 2290@end example 2291 2292@xseealso{@ref{XREFpatch,,patch}, @ref{XREFcaxis,,caxis}, @ref{XREFcolormap,,colormap}} 2293@end deftypefn 2294 2295 2296@c comet scripts/plot/draw/comet.m 2297@anchor{XREFcomet} 2298@deftypefn {} {} comet (@var{y}) 2299@deftypefnx {} {} comet (@var{x}, @var{y}) 2300@deftypefnx {} {} comet (@var{x}, @var{y}, @var{p}) 2301@deftypefnx {} {} comet (@var{hax}, @dots{}) 2302Produce a simple comet style animation along the trajectory provided by 2303the input coordinate vectors (@var{x}, @var{y}). 2304 2305If @var{x} is not specified it defaults to the indices of @var{y}. 2306 2307The speed of the comet may be controlled by @var{p}, which represents the 2308time each point is displayed before moving to the next one. The default for 2309@var{p} is @code{5 / numel (@var{y})}. 2310 2311If the first argument @var{hax} is an axes handle, then plot into this axes, 2312rather than the current axes returned by @code{gca}. 2313@xseealso{@ref{XREFcomet3,,comet3}} 2314@end deftypefn 2315 2316 2317@c comet3 scripts/plot/draw/comet3.m 2318@anchor{XREFcomet3} 2319@deftypefn {} {} comet3 (@var{z}) 2320@deftypefnx {} {} comet3 (@var{x}, @var{y}, @var{z}) 2321@deftypefnx {} {} comet3 (@var{x}, @var{y}, @var{z}, @var{p}) 2322@deftypefnx {} {} comet3 (@var{hax}, @dots{}) 2323Produce a simple comet style animation along the trajectory provided by 2324the input coordinate vectors (@var{x}, @var{y}, @var{z}). 2325 2326If only @var{z} is specified then @var{x}, @var{y} default to the indices 2327of @var{z}. 2328 2329The speed of the comet may be controlled by @var{p}, which represents the 2330time each point is displayed before moving to the next one. The default for 2331@var{p} is @code{5 / numel (@var{z})}. 2332 2333If the first argument @var{hax} is an axes handle, then plot into this axes, 2334rather than the current axes returned by @code{gca}. 2335@xseealso{@ref{XREFcomet,,comet}} 2336@end deftypefn 2337 2338 2339@node Axis Configuration 2340@subsubsection Axis Configuration 2341 2342The axis function may be used to change the axis limits of an existing 2343plot and various other axis properties, such as the aspect ratio and the 2344appearance of tic marks. By default, high level plotting functions such as 2345@code{plot} reset axes properties. Any customization of properties, for 2346example by calling @code{axis}, @code{xlim}, etc., should happen after the plot 2347is done or, alternatively, after calling the @ref{XREFhold, ,hold function}. 2348 2349@c axis scripts/plot/appearance/axis.m 2350@anchor{XREFaxis} 2351@deftypefn {} {} axis () 2352@deftypefnx {} {} axis ([@var{x_lo} @var{x_hi}]) 2353@deftypefnx {} {} axis ([@var{x_lo} @var{x_hi} @var{y_lo} @var{y_hi}]) 2354@deftypefnx {} {} axis ([@var{x_lo} @var{x_hi} @var{y_lo} @var{y_hi} @var{z_lo} @var{z_hi}]) 2355@deftypefnx {} {} axis ([@var{x_lo} @var{x_hi} @var{y_lo} @var{y_hi} @var{z_lo} @var{z_hi} @var{c_lo} @var{c_hi}]) 2356@deftypefnx {} {} axis (@var{option}) 2357@deftypefnx {} {} axis (@var{option1}, @var{option2}, @dots{}) 2358@deftypefnx {} {} axis (@var{hax}, @dots{}) 2359@deftypefnx {} {@var{limits} =} axis () 2360Set axis limits and appearance. 2361 2362The argument @var{limits} should be a 2-, 4-, 6-, or 8-element vector. The 2363first and second elements specify the lower and upper limits for the 2364x-axis. The third and fourth specify the limits for the y-axis, the fifth 2365and sixth specify the limits for the z-axis, and the seventh and eighth 2366specify the limits for the color axis. The special values @code{-Inf} and 2367@code{Inf} may be used to indicate that the limit should be automatically 2368computed based on the data in the axes. 2369 2370Without any arguments, @code{axis} turns autoscaling on. 2371 2372With one output argument, @code{@var{limits} = axis} returns the current 2373axis limits. 2374 2375The vector argument specifying limits is optional, and additional string 2376arguments may be used to specify various axis properties. 2377 2378The following options control the aspect ratio of the axes. 2379 2380@table @asis 2381@item @qcode{"square"} 2382Force a square axis aspect ratio. 2383 2384@item @qcode{"equal"} 2385Force x-axis unit distance to equal y-axis (and z-axis) unit distance. 2386 2387@item @qcode{"normal"} 2388Restore default aspect ratio. 2389@end table 2390 2391@noindent 2392The following options control the way axis limits are interpreted. 2393 2394@table @asis 2395@item @qcode{"auto"} 2396@itemx @qcode{"auto[xyz]"} 2397@itemx @qcode{"auto [xyz]"} 2398Set nice auto-computed limits around the data for all axes, or only 2399the specified axes. 2400 2401@item @qcode{"manual"} 2402Fix the current axes limits. 2403 2404@item @qcode{"tight"} 2405Fix axes to the limits of the data. 2406 2407@item @qcode{"image"} 2408Equivalent to @qcode{"tight"} and @qcode{"equal"}. 2409 2410@item @nospell{@qcode{"vis3d"}} 2411Set aspect ratio modes to @qcode{"manual"} for rotation without stretching. 2412@end table 2413 2414@noindent 2415The following options affect the appearance of tick marks. 2416 2417@table @asis 2418@item @qcode{"tic"} 2419@itemx @qcode{"tic[xyz]"} 2420@itemx @qcode{"tic [xyz]"} 2421Turn tick marks on for all axes, or turn them on for the specified axes and 2422off for the remainder. 2423 2424@item @qcode{"label"} 2425@itemx @qcode{"label[xyz]"} 2426@itemx @qcode{"label [xyz]"} 2427Turn tick labels on for all axes, or turn them on for the specified axes 2428and off for the remainder. 2429 2430@item @qcode{"nolabel"} 2431Turn tick labels off for all axes. 2432@end table 2433 2434Note: If there are no tick marks for an axes then there can be no labels. 2435 2436@noindent 2437The following options affect the direction of increasing values on the axes. 2438 2439@table @asis 2440@item @qcode{"xy"} 2441Default y-axis, larger values are near the top. 2442 2443@item @qcode{"ij"} 2444Reverse y-axis, smaller values are near the top. 2445@end table 2446 2447@noindent 2448The following options affects the visibility of the axes. 2449 2450@table @asis 2451@item @qcode{"on"} 2452Make the axes visible. 2453 2454@item @qcode{"off"} 2455Hide the axes. 2456@end table 2457 2458If the first argument @var{hax} is an axes handle, then operate on this 2459axes rather than the current axes returned by @code{gca}. 2460 2461Example 1: set X/Y limits and force a square aspect ratio 2462 2463@example 2464axis ([1, 2, 3, 4], "square"); 2465@end example 2466 2467Example 2: enable tick marks on all axes, 2468 enable tick mark labels only on the y-axis 2469 2470@example 2471axis ("tic", "labely"); 2472@end example 2473 2474@xseealso{@ref{XREFxlim,,xlim}, @ref{XREFylim,,ylim}, @ref{XREFzlim,,zlim}, @ref{XREFcaxis,,caxis}, @ref{XREFdaspect,,daspect}, @ref{XREFpbaspect,,pbaspect}, @ref{XREFbox,,box}, @ref{XREFgrid,,grid}} 2475@end deftypefn 2476 2477 2478Similarly the axis limits of the colormap can be changed with the caxis 2479function. 2480 2481@c caxis scripts/plot/appearance/caxis.m 2482@anchor{XREFcaxis} 2483@deftypefn {} {} caxis ([cmin cmax]) 2484@deftypefnx {} {} caxis ("auto") 2485@deftypefnx {} {} caxis ("manual") 2486@deftypefnx {} {} caxis (@var{hax}, @dots{}) 2487@deftypefnx {} {@var{limits} =} caxis () 2488Query or set color axis limits for plots. 2489 2490The limits argument should be a 2-element vector specifying the lower and 2491upper limits to assign to the first and last value in the colormap. Data 2492values outside this range are clamped to the first and last colormap 2493entries. 2494 2495If the @qcode{"auto"} option is given then automatic colormap limits are 2496applied. The automatic algorithm sets @var{cmin} to the minimum data value 2497and @var{cmax} to the maximum data value. If @qcode{"manual"} is specified 2498then the @qcode{"climmode"} property is set to @qcode{"manual"} and the 2499numeric values in the @qcode{"clim"} property are used for limits. 2500 2501If the first argument @var{hax} is an axes handle, then operate on 2502this axes rather than the current axes returned by @code{gca}. 2503 2504Called without arguments the current color axis limits are returned. 2505 2506Programming Note: The color axis affects the display of image, patch, and 2507surface graphics objects, but @strong{only} if the @qcode{"cdata"} property 2508has indexed data and the @qcode{"cdatamapping"} property is set to 2509@qcode{"scaled"}. Graphic objects with true color @code{cdata}, or 2510@qcode{"direct"} @code{cdatamapping} are not affected. 2511@xseealso{@ref{XREFcolormap,,colormap}, @ref{XREFaxis,,axis}} 2512@end deftypefn 2513 2514 2515The @code{xlim}, @code{ylim}, and @code{zlim} functions may be used to 2516get or set individual axis limits. Each has the same form. 2517 2518@c Add cross-references and function index entries for other limit functions. 2519@anchor{XREFylim} 2520@anchor{XREFzlim} 2521@findex ylim 2522@findex zlim 2523@c xlim scripts/plot/appearance/xlim.m 2524@anchor{XREFxlim} 2525@deftypefn {} {@var{xlimits} =} xlim () 2526@deftypefnx {} {@var{xmode} =} xlim ("mode") 2527@deftypefnx {} {} xlim ([@var{x_lo} @var{x_hi}]) 2528@deftypefnx {} {} xlim ("auto") 2529@deftypefnx {} {} xlim ("manual") 2530@deftypefnx {} {} xlim (@var{hax}, @dots{}) 2531Query or set the limits of the x-axis for the current plot. 2532 2533Called without arguments @code{xlim} returns the x-axis limits of the 2534current plot. 2535 2536With the input query @qcode{"mode"}, return the current x-limit calculation 2537mode which is either @qcode{"auto"} or @qcode{"manual"}. 2538 2539If passed a 2-element vector [@var{x_lo} @var{x_hi}], the limits of the 2540x-axis are set to these values and the mode is set to @qcode{"manual"}. 2541The special values -Inf and Inf can be used to indicate that either 2542the lower axis limit or upper axis limit should be automatically calculated. 2543 2544The current plotting mode can be changed by using either @qcode{"auto"} 2545or @qcode{"manual"} as the argument. 2546 2547If the first argument @var{hax} is an axes handle, then operate on 2548this axes rather than the current axes returned by @code{gca}. 2549 2550Programming Note: The @code{xlim} function operates by modifying the 2551@qcode{"xlim"} and @qcode{"xlimmode"} properties of an axes object. These 2552properties can be directly inspected and altered with @code{get}/@code{set}. 2553@xseealso{@ref{XREFylim,,ylim}, @ref{XREFzlim,,zlim}, @ref{XREFaxis,,axis}, @ref{XREFset,,set}, @ref{XREFget,,get}, @ref{XREFgca,,gca}} 2554@end deftypefn 2555 2556 2557The @code{xticks}, @code{yticks}, @code{zticks}, @code{rticks}, and 2558@code{thetaticks} functions may be used to get or set the tick mark locations 2559and modes on the respective axis. Each has the same form, although mode 2560options are not currently available for @code{rticks}, and @code{thetaticks}. 2561 2562@c FIXME: Update this section if polarplot and polar axes changes change the 2563@c associated axis properties. 2564@anchor{XREFyticks} 2565@anchor{XREFzticks} 2566@anchor{XREFrticks} 2567@anchor{XREFthetaticks} 2568@findex yticks 2569@findex zticks 2570@findex rticks 2571@findex thetaticks 2572@c xticks scripts/plot/appearance/xticks.m 2573@anchor{XREFxticks} 2574@deftypefn {} {@var{tickval} =} xticks 2575@deftypefnx {} {@var{mode} =} xticks ("mode") 2576@deftypefnx {} {} xticks (@var{tickval}) 2577@deftypefnx {} {} xticks ("auto") 2578@deftypefnx {} {} xticks ("manual") 2579@deftypefnx {} {@dots{} =} xticks (@var{hax}, @dots{}) 2580Query or set the tick values on the x-axis of the current axis. 2581 2582When called without an argument, return the current tick locations as 2583specified in the @qcode{"xtick"} axes property. These locations can be 2584changed by calling @code{xticks} with a vector of tick values. Note: 2585ascending order is not required. 2586 2587When called with argument @qcode{"mode"}, @code{xticks} returns the current 2588value of the axes property @qcode{"xtickmode"}. This property can be 2589changed by calling @code{xticks} with either @qcode{"auto"} (algorithm 2590determines tick positions) or @qcode{"manual"} (tick values remain fixed 2591regardless of axes resizing or rotation). Note: Specifying xtick values 2592will also set the property @qcode{"xtickmode"} to @qcode{"manual"}. 2593 2594If the first argument @var{hax} is an axes handle, then operate on 2595this axis rather than the current axes returned by @code{gca}. 2596 2597Requesting a return value when calling @code{xticks} to set a property value 2598will result in an error. 2599 2600@xseealso{@ref{XREFxticklabels,,xticklabels}, @ref{XREFyticks,,yticks}, @ref{XREFzticks,,zticks}, @ref{XREFrticks,,rticks}, @ref{XREFthetaticks,,thetaticks}, @ref{XREFget,,get}, @ref{XREFset,,set}} 2601@end deftypefn 2602 2603 2604The @code{xticklabels}, @code{yticklabels}, and @code{zticklabels} functions 2605may be used to get or set the label assigned to each tick location and the 2606labeling mode on the respective axis. Each has the same form. 2607 2608@c FIXME: Update this section if polarplot and polar axes changes change the 2609@c associated axis properties. 2610@c Matlab also implements rticklabels and thetaticklabels. 2611@anchor{XREFyticklabels} 2612@anchor{XREFzticklabels} 2613@findex yticklabels 2614@findex zticklabels 2615@c xticklabels scripts/plot/appearance/xticklabels.m 2616@anchor{XREFxticklabels} 2617@deftypefn {} {@var{tickval} =} xticklabels 2618@deftypefnx {} {@var{mode} =} xticklabels ("mode") 2619@deftypefnx {} {} xticklabels (@var{tickval}) 2620@deftypefnx {} {} xticklabels ("auto") 2621@deftypefnx {} {} xticklabels ("manual") 2622@deftypefnx {} {@dots{} =} xticklabels (@var{hax}, @dots{}) 2623Query or set the tick labels on the x-axis of the current axis. 2624 2625When called without an argument, return a cell array of strings of the 2626current tick labels as specified in the @qcode{"xticklabel"} axes property. 2627These labels can be changed by calling @code{xticklabels} with a cell array 2628of strings. Note: a vector of numbers will be mapped to a cell array of 2629strings. If fewer labels are specified than the current number of ticks, 2630blank labels will be appended to the array. 2631 2632When called with argument @qcode{"mode"}, @code{xticklabels} returns the 2633current value of the axes property @qcode{"xticklabelmode"}. This property 2634can be changed by calling @code{xticklabels} with either @qcode{"auto"} 2635(algorithm determines tick labels) or @qcode{"manual"} (tick labels remain 2636fixed). Note: Specifying xticklabel values will also set the 2637@qcode{"xticklabelmode"} and @qcode{"xticks"} properties to 2638@qcode{"manual"}. 2639 2640If the first argument @var{hax} is an axes handle, then operate on 2641this axis rather than the current axes returned by @code{gca}. 2642 2643Requesting a return value when calling @code{xticklabels} to set a property 2644value will result in an error. 2645 2646@xseealso{@ref{XREFxticks,,xticks}, @ref{XREFyticklabels,,yticklabels}, @ref{XREFzticklabels,,zticklabels}, @ref{XREFget,,get}, @ref{XREFset,,set}} 2647@end deftypefn 2648 2649 2650@node Two-dimensional Function Plotting 2651@subsubsection Two-dimensional Function Plotting 2652@cindex plotting, two-dimensional functions 2653 2654Octave can plot a function from a function handle or string defining the 2655function without the user needing to explicitly create the data to be 2656plotted. The function @code{fplot} also generates two-dimensional plots 2657with linear axes using a function name and limits for the range of the 2658x-coordinate instead of the x and y data. For example, 2659 2660@example 2661@group 2662fplot (@@sin, [-10, 10], 201); 2663@end group 2664@end example 2665 2666@noindent 2667produces a plot that is equivalent to the one above, but also includes a 2668legend displaying the name of the plotted function. 2669 2670@c fplot scripts/plot/draw/fplot.m 2671@anchor{XREFfplot} 2672@deftypefn {} {} fplot (@var{fn}) 2673@deftypefnx {} {} fplot (@var{fn}, @var{limits}) 2674@deftypefnx {} {} fplot (@dots{}, @var{tol}) 2675@deftypefnx {} {} fplot (@dots{}, @var{n}) 2676@deftypefnx {} {} fplot (@dots{}, @var{fmt}) 2677@deftypefnx {} {} fplot (@dots{}, @var{property}, @var{value}, @dots{}) 2678@deftypefnx {} {} fplot (@var{hax}, @dots{}) 2679@deftypefnx {} {[@var{x}, @var{y}] =} fplot (@dots{}) 2680Plot a function @var{fn} within the range defined by @var{limits}. 2681 2682@var{fn} is a function handle, inline function, or string containing the 2683name of the function to evaluate. 2684 2685The limits of the plot are of the form @w{@code{[@var{xlo}, @var{xhi}]}} or 2686@w{@code{[@var{xlo}, @var{xhi}, @var{ylo}, @var{yhi}]}}. If no limits 2687are specified the default is @code{[-5, 5]}. 2688 2689The next three arguments are all optional and any number of them may be 2690given in any order. 2691 2692@var{tol} is the relative tolerance to use for the plot and defaults 2693to 2e-3 (.2%). 2694 2695@var{n} is the minimum number of points to use. When @var{n} is specified, 2696the maximum stepsize will be @code{(@var{xhi} - @var{xlo}) / @var{n}}. More 2697than @var{n} points may still be used in order to meet the relative 2698tolerance requirement. 2699 2700The @var{fmt} argument specifies the linestyle to be used by the plot 2701command. 2702 2703Multiple property-value pairs may also be specified, but they must appear 2704in pairs. These arguments are applied to the line objects drawn by 2705@code{plot}. 2706 2707The full list of line properties is documented at 2708@ref{Line Properties}. 2709 2710If the first argument @var{hax} is an axes handle, then plot into this axes, 2711rather than the current axes returned by @code{gca}. 2712 2713With no output arguments, the results are immediately plotted. With two 2714output arguments, the 2-D plot data is returned. The data can subsequently 2715be plotted manually with @code{plot (@var{x}, @var{y})}. 2716 2717Example: 2718 2719@example 2720@group 2721fplot (@@cos, [0, 2*pi]) 2722fplot ("[cos(x), sin(x)]", [0, 2*pi]) 2723@end group 2724@end example 2725 2726Programming Notes: 2727 2728@code{fplot} works best with continuous functions. Functions with 2729discontinuities are unlikely to plot well. This restriction may be removed 2730in the future. 2731 2732@code{fplot} performance is better when the function accepts and returns a 2733vector argument. Consider this when writing user-defined functions and use 2734element-by-element operators such as @code{.*}, @code{./}, etc. 2735 2736@xseealso{@ref{XREFezplot,,ezplot}, @ref{XREFplot,,plot}} 2737@end deftypefn 2738 2739 2740Other functions that can create two-dimensional plots directly from a 2741function include @code{ezplot}, @code{ezcontour}, @code{ezcontourf} and 2742@code{ezpolar}. 2743 2744@c ezplot scripts/plot/draw/ezplot.m 2745@anchor{XREFezplot} 2746@deftypefn {} {} ezplot (@var{f}) 2747@deftypefnx {} {} ezplot (@var{f2v}) 2748@deftypefnx {} {} ezplot (@var{fx}, @var{fy}) 2749@deftypefnx {} {} ezplot (@dots{}, @var{dom}) 2750@deftypefnx {} {} ezplot (@dots{}, @var{n}) 2751@deftypefnx {} {} ezplot (@var{hax}, @dots{}) 2752@deftypefnx {} {@var{h} =} ezplot (@dots{}) 2753 2754Plot the 2-D curve defined by the function @var{f}. 2755 2756The function @var{f} may be a string, inline function, or function handle 2757and can have either one or two variables. If @var{f} has one variable, then 2758the function is plotted over the domain @code{-2*pi < @var{x} < 2*pi} 2759with 500 points. 2760 2761If @var{f2v} is a function of two variables then the implicit function 2762@code{@var{f}(@var{x},@var{y}) = 0} is calculated over the meshed domain 2763@code{-2*pi <= @var{x} | @var{y} <= 2*pi} with 60 points in each dimension. 2764 2765For example: 2766 2767@example 2768ezplot (@@(@var{x}, @var{y}) @var{x}.^2 - @var{y}.^2 - 1) 2769@end example 2770 2771If two functions are passed as inputs then the parametric function 2772 2773@example 2774@group 2775@var{x} = @var{fx} (@var{t}) 2776@var{y} = @var{fy} (@var{t}) 2777@end group 2778@end example 2779 2780@noindent 2781is plotted over the domain @code{-2*pi <= @var{t} <= 2*pi} with 500 points. 2782 2783If @var{dom} is a two element vector, it represents the minimum and maximum 2784values of both @var{x} and @var{y}, or @var{t} for a parametric plot. If 2785@var{dom} is a four element vector, then the minimum and maximum values are 2786@code{[xmin xmax ymin ymax]}. 2787 2788@var{n} is a scalar defining the number of points to use in plotting 2789the function. 2790 2791If the first argument @var{hax} is an axes handle, then plot into this axes, 2792rather than the current axes returned by @code{gca}. 2793 2794The optional return value @var{h} is a vector of graphics handles to 2795the created line objects. 2796 2797@xseealso{@ref{XREFplot,,plot}, @ref{XREFezplot3,,ezplot3}, @ref{XREFezpolar,,ezpolar}, @ref{XREFezcontour,,ezcontour}, @ref{XREFezcontourf,,ezcontourf}, @ref{XREFezmesh,,ezmesh}, @ref{XREFezmeshc,,ezmeshc}, @ref{XREFezsurf,,ezsurf}, @ref{XREFezsurfc,,ezsurfc}} 2798@end deftypefn 2799 2800 2801@c ezcontour scripts/plot/draw/ezcontour.m 2802@anchor{XREFezcontour} 2803@deftypefn {} {} ezcontour (@var{f}) 2804@deftypefnx {} {} ezcontour (@dots{}, @var{dom}) 2805@deftypefnx {} {} ezcontour (@dots{}, @var{n}) 2806@deftypefnx {} {} ezcontour (@var{hax}, @dots{}) 2807@deftypefnx {} {@var{h} =} ezcontour (@dots{}) 2808 2809Plot the contour lines of a function. 2810 2811@var{f} is a string, inline function, or function handle with two arguments 2812defining the function. By default the plot is over the meshed domain 2813@code{-2*pi <= @var{x} | @var{y} <= 2*pi} with 60 points in each dimension. 2814 2815If @var{dom} is a two element vector, it represents the minimum and maximum 2816values of both @var{x} and @var{y}. If @var{dom} is a four element vector, 2817then the minimum and maximum values are @code{[xmin xmax ymin ymax]}. 2818 2819@var{n} is a scalar defining the number of points to use in each dimension. 2820 2821If the first argument @var{hax} is an axes handle, then plot into this axes, 2822rather than the current axes returned by @code{gca}. 2823 2824The optional return value @var{h} is a graphics handle to the created plot. 2825 2826Example: 2827 2828@example 2829@group 2830f = @@(x,y) sqrt (abs (x .* y)) ./ (1 + x.^2 + y.^2); 2831ezcontour (f, [-3, 3]); 2832@end group 2833@end example 2834 2835@xseealso{@ref{XREFcontour,,contour}, @ref{XREFezcontourf,,ezcontourf}, @ref{XREFezplot,,ezplot}, @ref{XREFezmeshc,,ezmeshc}, @ref{XREFezsurfc,,ezsurfc}} 2836@end deftypefn 2837 2838 2839@c ezcontourf scripts/plot/draw/ezcontourf.m 2840@anchor{XREFezcontourf} 2841@deftypefn {} {} ezcontourf (@var{f}) 2842@deftypefnx {} {} ezcontourf (@dots{}, @var{dom}) 2843@deftypefnx {} {} ezcontourf (@dots{}, @var{n}) 2844@deftypefnx {} {} ezcontourf (@var{hax}, @dots{}) 2845@deftypefnx {} {@var{h} =} ezcontourf (@dots{}) 2846 2847Plot the filled contour lines of a function. 2848 2849@var{f} is a string, inline function, or function handle with two arguments 2850defining the function. By default the plot is over the meshed domain 2851@code{-2*pi <= @var{x} | @var{y} <= 2*pi} with 60 points in each dimension. 2852 2853If @var{dom} is a two element vector, it represents the minimum and maximum 2854values of both @var{x} and @var{y}. If @var{dom} is a four element vector, 2855then the minimum and maximum values are @code{[xmin xmax ymin ymax]}. 2856 2857@var{n} is a scalar defining the number of points to use in each dimension. 2858 2859If the first argument @var{hax} is an axes handle, then plot into this axes, 2860rather than the current axes returned by @code{gca}. 2861 2862The optional return value @var{h} is a graphics handle to the created plot. 2863 2864Example: 2865 2866@example 2867@group 2868f = @@(x,y) sqrt (abs (x .* y)) ./ (1 + x.^2 + y.^2); 2869ezcontourf (f, [-3, 3]); 2870@end group 2871@end example 2872 2873@xseealso{@ref{XREFcontourf,,contourf}, @ref{XREFezcontour,,ezcontour}, @ref{XREFezplot,,ezplot}, @ref{XREFezmeshc,,ezmeshc}, @ref{XREFezsurfc,,ezsurfc}} 2874@end deftypefn 2875 2876 2877@c ezpolar scripts/plot/draw/ezpolar.m 2878@anchor{XREFezpolar} 2879@deftypefn {} {} ezpolar (@var{f}) 2880@deftypefnx {} {} ezpolar (@dots{}, @var{dom}) 2881@deftypefnx {} {} ezpolar (@dots{}, @var{n}) 2882@deftypefnx {} {} ezpolar (@var{hax}, @dots{}) 2883@deftypefnx {} {@var{h} =} ezpolar (@dots{}) 2884 2885Plot a 2-D function in polar coordinates. 2886 2887The function @var{f} is a string, inline function, or function handle with 2888a single argument. The expected form of the function is 2889@code{@var{rho} = @var{f}(@var{theta})}. 2890By default the plot is over the domain @code{0 <= @var{theta} <= 2*pi} 2891with 500 points. 2892 2893If @var{dom} is a two element vector, it represents the minimum and maximum 2894values of @var{theta}. 2895 2896@var{n} is a scalar defining the number of points to use in plotting 2897the function. 2898 2899If the first argument @var{hax} is an axes handle, then plot into this axes, 2900rather than the current axes returned by @code{gca}. 2901 2902The optional return value @var{h} is a graphics handle to the created plot. 2903 2904Example: 2905 2906@example 2907ezpolar (@@(t) sin (5/4 * t), [0, 8*pi]); 2908@end example 2909 2910@xseealso{@ref{XREFpolar,,polar}, @ref{XREFezplot,,ezplot}} 2911@end deftypefn 2912 2913 2914@node Two-dimensional Geometric Shapes 2915@subsubsection Two-dimensional Geometric Shapes 2916 2917@c rectangle scripts/plot/draw/rectangle.m 2918@anchor{XREFrectangle} 2919@deftypefn {} {} rectangle () 2920@deftypefnx {} {} rectangle (@dots{}, "Position", @var{pos}) 2921@deftypefnx {} {} rectangle (@dots{}, "Curvature", @var{curv}) 2922@deftypefnx {} {} rectangle (@dots{}, "EdgeColor", @var{ec}) 2923@deftypefnx {} {} rectangle (@dots{}, "FaceColor", @var{fc}) 2924@deftypefnx {} {} rectangle (@var{hax}, @dots{}) 2925@deftypefnx {} {@var{h} =} rectangle (@dots{}) 2926Draw a rectangular patch defined by @var{pos} and @var{curv}. 2927 2928The variable @code{@var{pos}(1:2)} defines the lower left-hand corner of 2929the patch and @code{@var{pos}(3:4)} defines its width and height. By 2930default, the value of @var{pos} is @code{[0, 0, 1, 1]}. 2931 2932The variable @var{curv} defines the curvature of the sides of the rectangle 2933and may be a scalar or two-element vector with values between 0 and 1. 2934A value of 0 represents no curvature of the side, whereas a value of 1 2935means that the side is entirely curved into the arc of a circle. 2936If @var{curv} is a two-element vector, then the first element is the 2937curvature along the x-axis of the patch and the second along y-axis. 2938 2939If @var{curv} is a scalar, it represents the curvature of the shorter of the 2940two sides of the rectangle and the curvature of the other side is defined 2941by 2942 2943@example 2944min (pos(1:2)) / max (pos(1:2)) * curv 2945@end example 2946 2947Additional property/value pairs are passed to the underlying patch command. 2948The full list of properties is documented at @ref{Patch Properties}. 2949 2950If the first argument @var{hax} is an axes handle, then plot into this axes, 2951rather than the current axes returned by @code{gca}. 2952 2953The optional return value @var{h} is a graphics handle to the created 2954rectangle object. 2955@xseealso{@ref{XREFpatch,,patch}, @ref{XREFline,,line}, @ref{XREFcylinder,,cylinder}, @ref{XREFellipsoid,,ellipsoid}, @ref{XREFsphere,,sphere}} 2956@end deftypefn 2957 2958 2959@node Three-Dimensional Plots 2960@subsection Three-Dimensional Plots 2961@cindex plotting, three-dimensional 2962 2963The function @code{mesh} produces mesh surface plots. For example, 2964 2965@example 2966@group 2967tx = ty = linspace (-8, 8, 41)'; 2968[xx, yy] = meshgrid (tx, ty); 2969r = sqrt (xx .^ 2 + yy .^ 2) + eps; 2970tz = sin (r) ./ r; 2971mesh (tx, ty, tz); 2972xlabel ("tx"); 2973ylabel ("ty"); 2974zlabel ("tz"); 2975title ("3-D Sombrero plot"); 2976@end group 2977@end example 2978 2979@noindent 2980produces the familiar ``sombrero'' plot shown in @ref{fig:mesh}. Note 2981the use of the function @code{meshgrid} to create matrices of X and Y 2982coordinates to use for plotting the Z data. The @code{ndgrid} function 2983is similar to @code{meshgrid}, but works for N-dimensional matrices. 2984 2985@float Figure,fig:mesh 2986@center @image{mesh,4in} 2987@caption{Mesh plot.} 2988@end float 2989 2990The @code{meshc} function is similar to @code{mesh}, but also produces a 2991plot of contours for the surface. 2992 2993The @code{plot3} function displays arbitrary three-dimensional data, 2994without requiring it to form a surface. For example, 2995 2996@example 2997@group 2998t = 0:0.1:10*pi; 2999r = linspace (0, 1, numel (t)); 3000z = linspace (0, 1, numel (t)); 3001plot3 (r.*sin (t), r.*cos (t), z); 3002xlabel ("r.*sin (t)"); 3003ylabel ("r.*cos (t)"); 3004zlabel ("z"); 3005title ("plot3 display of 3-D helix"); 3006@end group 3007@end example 3008 3009@noindent 3010displays the spiral in three dimensions shown in @ref{fig:plot3}. 3011 3012@float Figure,fig:plot3 3013@center @image{plot3,4in} 3014@caption{Three-dimensional spiral.} 3015@end float 3016 3017Finally, the @code{view} function changes the viewpoint for 3018three-dimensional plots. 3019 3020@c mesh scripts/plot/draw/mesh.m 3021@anchor{XREFmesh} 3022@deftypefn {} {} mesh (@var{x}, @var{y}, @var{z}) 3023@deftypefnx {} {} mesh (@var{z}) 3024@deftypefnx {} {} mesh (@dots{}, @var{c}) 3025@deftypefnx {} {} mesh (@dots{}, @var{prop}, @var{val}, @dots{}) 3026@deftypefnx {} {} mesh (@var{hax}, @dots{}) 3027@deftypefnx {} {@var{h} =} mesh (@dots{}) 3028Plot a 3-D wireframe mesh. 3029 3030The wireframe mesh is plotted using rectangles. The vertices of the 3031rectangles [@var{x}, @var{y}] are typically the output of @code{meshgrid}. 3032over a 2-D rectangular region in the x-y plane. @var{z} determines the 3033height above the plane of each vertex. If only a single @var{z} matrix is 3034given, then it is plotted over the meshgrid 3035@code{@var{x} = 1:columns (@var{z}), @var{y} = 1:rows (@var{z})}. 3036Thus, columns of @var{z} correspond to different @var{x} values and rows 3037of @var{z} correspond to different @var{y} values. 3038 3039The color of the mesh is computed by linearly scaling the @var{z} values 3040to fit the range of the current colormap. Use @code{caxis} and/or 3041change the colormap to control the appearance. 3042 3043Optionally, the color of the mesh can be specified independently of @var{z} 3044by supplying a color matrix, @var{c}. 3045 3046Any property/value pairs are passed directly to the underlying surface 3047object. The full list of properties is documented at 3048@ref{Surface Properties}. 3049 3050If the first argument @var{hax} is an axes handle, then plot into this axes, 3051rather than the current axes returned by @code{gca}. 3052 3053The optional return value @var{h} is a graphics handle to the created 3054surface object. 3055 3056@xseealso{@ref{XREFezmesh,,ezmesh}, @ref{XREFmeshc,,meshc}, @ref{XREFmeshz,,meshz}, @ref{XREFtrimesh,,trimesh}, @ref{XREFcontour,,contour}, @ref{XREFsurf,,surf}, @ref{XREFsurface,,surface}, @ref{XREFmeshgrid,,meshgrid}, @ref{XREFhidden,,hidden}, @ref{XREFshading,,shading}, @ref{XREFcolormap,,colormap}, @ref{XREFcaxis,,caxis}} 3057@end deftypefn 3058 3059 3060@c meshc scripts/plot/draw/meshc.m 3061@anchor{XREFmeshc} 3062@deftypefn {} {} meshc (@var{x}, @var{y}, @var{z}) 3063@deftypefnx {} {} meshc (@var{z}) 3064@deftypefnx {} {} meshc (@dots{}, @var{c}) 3065@deftypefnx {} {} meshc (@dots{}, @var{prop}, @var{val}, @dots{}) 3066@deftypefnx {} {} meshc (@var{hax}, @dots{}) 3067@deftypefnx {} {@var{h} =} meshc (@dots{}) 3068Plot a 3-D wireframe mesh with underlying contour lines. 3069 3070The wireframe mesh is plotted using rectangles. The vertices of the 3071rectangles [@var{x}, @var{y}] are typically the output of @code{meshgrid}. 3072over a 2-D rectangular region in the x-y plane. @var{z} determines the 3073height above the plane of each vertex. If only a single @var{z} matrix is 3074given, then it is plotted over the meshgrid 3075@code{@var{x} = 1:columns (@var{z}), @var{y} = 1:rows (@var{z})}. 3076Thus, columns of @var{z} correspond to different @var{x} values and rows 3077of @var{z} correspond to different @var{y} values. 3078 3079The color of the mesh is computed by linearly scaling the @var{z} values 3080to fit the range of the current colormap. Use @code{caxis} and/or 3081change the colormap to control the appearance. 3082 3083Optionally the color of the mesh can be specified independently of @var{z} 3084by supplying a color matrix, @var{c}. 3085 3086Any property/value pairs are passed directly to the underlying surface 3087object. The full list of properties is documented at 3088@ref{Surface Properties}. 3089 3090If the first argument @var{hax} is an axes handle, then plot into this axes, 3091rather than the current axes returned by @code{gca}. 3092 3093The optional return value @var{h} is a 2-element vector with a graphics 3094handle to the created surface object and to the created contour plot. 3095 3096@xseealso{@ref{XREFezmeshc,,ezmeshc}, @ref{XREFmesh,,mesh}, @ref{XREFmeshz,,meshz}, @ref{XREFcontour,,contour}, @ref{XREFsurfc,,surfc}, @ref{XREFsurface,,surface}, @ref{XREFmeshgrid,,meshgrid}, @ref{XREFhidden,,hidden}, @ref{XREFshading,,shading}, @ref{XREFcolormap,,colormap}, @ref{XREFcaxis,,caxis}} 3097@end deftypefn 3098 3099 3100@c meshz scripts/plot/draw/meshz.m 3101@anchor{XREFmeshz} 3102@deftypefn {} {} meshz (@var{x}, @var{y}, @var{z}) 3103@deftypefnx {} {} meshz (@var{z}) 3104@deftypefnx {} {} meshz (@dots{}, @var{c}) 3105@deftypefnx {} {} meshz (@dots{}, @var{prop}, @var{val}, @dots{}) 3106@deftypefnx {} {} meshz (@var{hax}, @dots{}) 3107@deftypefnx {} {@var{h} =} meshz (@dots{}) 3108Plot a 3-D wireframe mesh with a surrounding curtain. 3109 3110The wireframe mesh is plotted using rectangles. The vertices of the 3111rectangles [@var{x}, @var{y}] are typically the output of @code{meshgrid}. 3112over a 2-D rectangular region in the x-y plane. @var{z} determines the 3113height above the plane of each vertex. If only a single @var{z} matrix is 3114given, then it is plotted over the meshgrid 3115@code{@var{x} = 1:columns (@var{z}), @var{y} = 1:rows (@var{z})}. 3116Thus, columns of @var{z} correspond to different @var{x} values and rows 3117of @var{z} correspond to different @var{y} values. 3118 3119The color of the mesh is computed by linearly scaling the @var{z} values 3120to fit the range of the current colormap. Use @code{caxis} and/or 3121change the colormap to control the appearance. 3122 3123Optionally the color of the mesh can be specified independently of @var{z} 3124by supplying a color matrix, @var{c}. 3125 3126Any property/value pairs are passed directly to the underlying surface 3127object. The full list of properties is documented at 3128@ref{Surface Properties}. 3129 3130If the first argument @var{hax} is an axes handle, then plot into this axes, 3131rather than the current axes returned by @code{gca}. 3132 3133The optional return value @var{h} is a graphics handle to the created 3134surface object. 3135 3136@xseealso{@ref{XREFmesh,,mesh}, @ref{XREFmeshc,,meshc}, @ref{XREFcontour,,contour}, @ref{XREFsurf,,surf}, @ref{XREFsurface,,surface}, @ref{XREFwaterfall,,waterfall}, @ref{XREFmeshgrid,,meshgrid}, @ref{XREFhidden,,hidden}, @ref{XREFshading,,shading}, @ref{XREFcolormap,,colormap}, @ref{XREFcaxis,,caxis}} 3137@end deftypefn 3138 3139 3140@c hidden scripts/plot/appearance/hidden.m 3141@anchor{XREFhidden} 3142@deftypefn {} {} hidden 3143@deftypefnx {} {} hidden on 3144@deftypefnx {} {} hidden off 3145@deftypefnx {} {@var{mode} =} hidden (@dots{}) 3146Control mesh hidden line removal. 3147 3148When called with no argument the hidden line removal state is toggled. 3149 3150When called with one of the modes @qcode{"on"} or @qcode{"off"} the state 3151is set accordingly. 3152 3153The optional output argument @var{mode} is the current state. 3154 3155Hidden Line Removal determines what graphic objects behind a mesh plot 3156are visible. The default is for the mesh to be opaque and lines behind 3157the mesh are not visible. If hidden line removal is turned off then 3158objects behind the mesh can be seen through the faces (openings) of the 3159mesh, although the mesh grid lines are still opaque. 3160 3161@xseealso{@ref{XREFmesh,,mesh}, @ref{XREFmeshc,,meshc}, @ref{XREFmeshz,,meshz}, @ref{XREFezmesh,,ezmesh}, @ref{XREFezmeshc,,ezmeshc}, @ref{XREFtrimesh,,trimesh}, @ref{XREFwaterfall,,waterfall}} 3162@end deftypefn 3163 3164 3165@c surf scripts/plot/draw/surf.m 3166@anchor{XREFsurf} 3167@deftypefn {} {} surf (@var{x}, @var{y}, @var{z}) 3168@deftypefnx {} {} surf (@var{z}) 3169@deftypefnx {} {} surf (@dots{}, @var{c}) 3170@deftypefnx {} {} surf (@dots{}, @var{prop}, @var{val}, @dots{}) 3171@deftypefnx {} {} surf (@var{hax}, @dots{}) 3172@deftypefnx {} {@var{h} =} surf (@dots{}) 3173Plot a 3-D surface mesh. 3174 3175The surface mesh is plotted using shaded rectangles. The vertices of the 3176rectangles [@var{x}, @var{y}] are typically the output of @code{meshgrid}. 3177over a 2-D rectangular region in the x-y plane. @var{z} determines the 3178height above the plane of each vertex. If only a single @var{z} matrix is 3179given, then it is plotted over the meshgrid 3180@code{@var{x} = 1:columns (@var{z}), @var{y} = 1:rows (@var{z})}. 3181Thus, columns of @var{z} correspond to different @var{x} values and rows 3182of @var{z} correspond to different @var{y} values. 3183 3184The color of the surface is computed by linearly scaling the @var{z} values 3185to fit the range of the current colormap. Use @code{caxis} and/or 3186change the colormap to control the appearance. 3187 3188Optionally, the color of the surface can be specified independently of 3189@var{z} by supplying a color matrix, @var{c}. 3190 3191Any property/value pairs are passed directly to the underlying surface 3192object. The full list of properties is documented at 3193@ref{Surface Properties}. 3194 3195If the first argument @var{hax} is an axes handle, then plot into this axes, 3196rather than the current axes returned by @code{gca}. 3197 3198The optional return value @var{h} is a graphics handle to the created 3199surface object. 3200 3201Note: The exact appearance of the surface can be controlled with the 3202@code{shading} command or by using @code{set} to control surface object 3203properties. 3204@xseealso{@ref{XREFezsurf,,ezsurf}, @ref{XREFsurfc,,surfc}, @ref{XREFsurfl,,surfl}, @ref{XREFsurfnorm,,surfnorm}, @ref{XREFtrisurf,,trisurf}, @ref{XREFcontour,,contour}, @ref{XREFmesh,,mesh}, @ref{XREFsurface,,surface}, @ref{XREFmeshgrid,,meshgrid}, @ref{XREFhidden,,hidden}, @ref{XREFshading,,shading}, @ref{XREFcolormap,,colormap}, @ref{XREFcaxis,,caxis}} 3205@end deftypefn 3206 3207 3208@c surfc scripts/plot/draw/surfc.m 3209@anchor{XREFsurfc} 3210@deftypefn {} {} surfc (@var{x}, @var{y}, @var{z}) 3211@deftypefnx {} {} surfc (@var{z}) 3212@deftypefnx {} {} surfc (@dots{}, @var{c}) 3213@deftypefnx {} {} surfc (@dots{}, @var{prop}, @var{val}, @dots{}) 3214@deftypefnx {} {} surfc (@var{hax}, @dots{}) 3215@deftypefnx {} {@var{h} =} surfc (@dots{}) 3216Plot a 3-D surface mesh with underlying contour lines. 3217 3218The surface mesh is plotted using shaded rectangles. The vertices of the 3219rectangles [@var{x}, @var{y}] are typically the output of @code{meshgrid}. 3220over a 2-D rectangular region in the x-y plane. @var{z} determines the 3221height above the plane of each vertex. If only a single @var{z} matrix is 3222given, then it is plotted over the meshgrid 3223@code{@var{x} = 1:columns (@var{z}), @var{y} = 1:rows (@var{z})}. 3224Thus, columns of @var{z} correspond to different @var{x} values and rows 3225of @var{z} correspond to different @var{y} values. 3226 3227The color of the surface is computed by linearly scaling the @var{z} values 3228to fit the range of the current colormap. Use @code{caxis} and/or 3229change the colormap to control the appearance. 3230 3231Optionally, the color of the surface can be specified independently of 3232@var{z} by supplying a color matrix, @var{c}. 3233 3234Any property/value pairs are passed directly to the underlying surface 3235object. The full list of properties is documented at 3236@ref{Surface Properties}. 3237 3238If the first argument @var{hax} is an axes handle, then plot into this axes, 3239rather than the current axes returned by @code{gca}. 3240 3241The optional return value @var{h} is a graphics handle to the created 3242surface object. 3243 3244Note: The exact appearance of the surface can be controlled with the 3245@code{shading} command or by using @code{set} to control surface object 3246properties. 3247@xseealso{@ref{XREFezsurfc,,ezsurfc}, @ref{XREFsurf,,surf}, @ref{XREFsurfl,,surfl}, @ref{XREFsurfnorm,,surfnorm}, @ref{XREFtrisurf,,trisurf}, @ref{XREFcontour,,contour}, @ref{XREFmesh,,mesh}, @ref{XREFsurface,,surface}, @ref{XREFmeshgrid,,meshgrid}, @ref{XREFhidden,,hidden}, @ref{XREFshading,,shading}, @ref{XREFcolormap,,colormap}, @ref{XREFcaxis,,caxis}} 3248@end deftypefn 3249 3250 3251@c surfl scripts/plot/draw/surfl.m 3252@anchor{XREFsurfl} 3253@deftypefn {} {} surfl (@var{z}) 3254@deftypefnx {} {} surfl (@var{x}, @var{y}, @var{z}) 3255@deftypefnx {} {} surfl (@dots{}, @var{lsrc}) 3256@deftypefnx {} {} surfl (@var{x}, @var{y}, @var{z}, @var{lsrc}, @var{P}) 3257@deftypefnx {} {} surfl (@dots{}, "cdata") 3258@deftypefnx {} {} surfl (@dots{}, "light") 3259@deftypefnx {} {} surfl (@var{hax}, @dots{}) 3260@deftypefnx {} {@var{h} =} surfl (@dots{}) 3261Plot a 3-D surface using shading based on various lighting models. 3262 3263The surface mesh is plotted using shaded rectangles. The vertices of the 3264rectangles [@var{x}, @var{y}] are typically the output of @code{meshgrid}. 3265over a 2-D rectangular region in the x-y plane. @var{z} determines the 3266height above the plane of each vertex. If only a single @var{z} matrix is 3267given, then it is plotted over the meshgrid 3268@code{@var{x} = 1:columns (@var{z}), @var{y} = 1:rows (@var{z})}. 3269Thus, columns of @var{z} correspond to different @var{x} values and rows 3270of @var{z} correspond to different @var{y} values. 3271 3272The default lighting mode @qcode{"cdata"}, changes the cdata property of the 3273surface object to give the impression of a lighted surface. 3274 3275The alternate mode @qcode{"light"} creates a light object to illuminate the 3276surface. 3277 3278The light source location may be specified using @var{lsrc} which can be 3279a 2-element vector [azimuth, elevation] in degrees, or a 3-element vector 3280[lx, ly, lz]. The default value is rotated 45 degrees counterclockwise to 3281the current view. 3282 3283The material properties of the surface can specified using a 4-element 3284vector @var{P} = [@var{AM} @var{D} @var{SP} @var{exp}] which defaults to 3285@var{p} = [0.55 0.6 0.4 10]. 3286 3287@table @asis 3288@item @qcode{"AM"} strength of ambient light 3289 3290@item @qcode{"D"} strength of diffuse reflection 3291 3292@item @qcode{"SP"} strength of specular reflection 3293 3294@item @qcode{"EXP"} specular exponent 3295@end table 3296 3297If the first argument @var{hax} is an axes handle, then plot into this axes, 3298rather than the current axes returned by @code{gca}. 3299 3300The optional return value @var{h} is a graphics handle to the created 3301surface object. 3302 3303Example: 3304 3305@example 3306@group 3307colormap (bone (64)); 3308surfl (peaks); 3309shading interp; 3310@end group 3311@end example 3312@xseealso{@ref{XREFdiffuse,,diffuse}, @ref{XREFspecular,,specular}, @ref{XREFsurf,,surf}, @ref{XREFshading,,shading}, @ref{XREFcolormap,,colormap}, @ref{XREFcaxis,,caxis}} 3313@end deftypefn 3314 3315 3316@c surfnorm scripts/plot/draw/surfnorm.m 3317@anchor{XREFsurfnorm} 3318@deftypefn {} {} surfnorm (@var{x}, @var{y}, @var{z}) 3319@deftypefnx {} {} surfnorm (@var{z}) 3320@deftypefnx {} {} surfnorm (@dots{}, @var{prop}, @var{val}, @dots{}) 3321@deftypefnx {} {} surfnorm (@var{hax}, @dots{}) 3322@deftypefnx {} {[@var{nx}, @var{ny}, @var{nz}] =} surfnorm (@dots{}) 3323Find the vectors normal to a meshgridded surface. 3324 3325If @var{x} and @var{y} are vectors, then a typical vertex is 3326(@var{x}(j), @var{y}(i), @var{z}(i,j)). Thus, columns of @var{z} correspond 3327to different @var{x} values and rows of @var{z} correspond to different 3328@var{y} values. If only a single input @var{z} is given then @var{x} is 3329taken to be @code{1:columns (@var{z})} and @var{y} is 3330@code{1:rows (@var{z})}. 3331 3332If no return arguments are requested, a surface plot with the normal 3333vectors to the surface is plotted. 3334 3335Any property/value input pairs are assigned to the surface object. The full 3336list of properties is documented at @ref{Surface Properties}. 3337 3338If the first argument @var{hax} is an axes handle, then plot into this axes, 3339rather than the current axes returned by @code{gca}. 3340 3341If output arguments are requested then the components of the normal 3342vectors are returned in @var{nx}, @var{ny}, and @var{nz} and no plot is 3343made. The normal vectors are unnormalized (magnitude != 1). To normalize, 3344use 3345 3346@example 3347@group 3348len = sqrt (nx.^2 + ny.^2 + nz.^2); 3349nx ./= len; ny ./= len; nz ./= len; 3350@end group 3351@end example 3352 3353An example of the use of @code{surfnorm} is 3354 3355@example 3356surfnorm (peaks (25)); 3357@end example 3358 3359Algorithm: The normal vectors are calculated by taking the cross product 3360of the diagonals of each of the quadrilateral faces in the meshgrid to find 3361the normal vectors at the center of each face. Next, for each meshgrid 3362point the four nearest normal vectors are averaged to obtain the final 3363normal to the surface at the meshgrid point. 3364 3365For surface objects, the @qcode{"VertexNormals"} property contains 3366equivalent information, except possibly near the boundary of the surface 3367where different interpolation schemes may yield slightly different values. 3368 3369@xseealso{@ref{XREFisonormals,,isonormals}, @ref{XREFquiver3,,quiver3}, @ref{XREFsurf,,surf}, @ref{XREFmeshgrid,,meshgrid}} 3370@end deftypefn 3371 3372 3373@c isosurface scripts/plot/draw/isosurface.m 3374@anchor{XREFisosurface} 3375@deftypefn {} {@var{fv} =} isosurface (@var{v}, @var{isoval}) 3376@deftypefnx {} {@var{fv} =} isosurface (@var{v}) 3377@deftypefnx {} {@var{fv} =} isosurface (@var{x}, @var{y}, @var{z}, @var{v}, @var{isoval}) 3378@deftypefnx {} {@var{fv} =} isosurface (@var{x}, @var{y}, @var{z}, @var{v}) 3379@deftypefnx {} {@var{fvc} =} isosurface (@dots{}, @var{col}) 3380@deftypefnx {} {@var{fv} =} isosurface (@dots{}, "noshare") 3381@deftypefnx {} {@var{fv} =} isosurface (@dots{}, "verbose") 3382@deftypefnx {} {[@var{f}, @var{v}] =} isosurface (@dots{}) 3383@deftypefnx {} {[@var{f}, @var{v}, @var{c}] =} isosurface (@dots{}) 3384@deftypefnx {} {} isosurface (@dots{}) 3385 3386Calculate isosurface of 3-D volume data. 3387 3388An isosurface connects points with the same value and is analogous to a 3389contour plot, but in three dimensions. 3390 3391The input argument @var{v} is a three-dimensional array that contains data 3392sampled over a volume. 3393 3394The input @var{isoval} is a scalar that specifies the value for the 3395isosurface. If @var{isoval} is omitted or empty, a @nospell{"good"} value 3396for an isosurface is determined from @var{v}. 3397 3398When called with a single output argument @code{isosurface} returns a 3399structure array @var{fv} that contains the fields @var{faces} and 3400@var{vertices} computed at the points 3401@code{[@var{x}, @var{y}, @var{z}] = meshgrid (1:l, 1:m, 1:n)} where 3402@code{[l, m, n] = size (@var{v})}. The output @var{fv} can be 3403used directly as input to the @code{patch} function. 3404 3405If called with additional input arguments @var{x}, @var{y}, and @var{z} 3406that are three-dimensional arrays with the same size as @var{v} or 3407vectors with lengths corresponding to the dimensions of @var{v}, then the 3408volume data is taken at the specified points. If @var{x}, @var{y}, or 3409@var{z} are empty, the grid corresponds to the indices (@code{1:n}) in 3410the respective direction (@pxref{XREFmeshgrid,,meshgrid}). 3411 3412The optional input argument @var{col}, which is a three-dimensional array 3413of the same size as @var{v}, specifies coloring of the isosurface. The 3414color data is interpolated, as necessary, to match @var{isoval}. The 3415output structure array, in this case, has the additional field 3416@var{facevertexcdata}. 3417 3418If given the string input argument @qcode{"noshare"}, vertices may be 3419returned multiple times for different faces. The default behavior is to 3420eliminate vertices shared by adjacent faces. 3421 3422The string input argument @qcode{"verbose"} is supported for @sc{matlab} 3423compatibility, but has no effect. 3424 3425Any string arguments must be passed after the other arguments. 3426 3427If called with two or three output arguments, return the information about 3428the faces @var{f}, vertices @var{v}, and color data @var{c} as separate 3429arrays instead of a single structure array. 3430 3431If called with no output argument, the isosurface geometry is directly 3432plotted with the @code{patch} command and a light object is added to 3433the axes if not yet present. 3434 3435For example, 3436 3437@example 3438@group 3439[x, y, z] = meshgrid (1:5, 1:5, 1:5); 3440v = rand (5, 5, 5); 3441isosurface (x, y, z, v, .5); 3442@end group 3443@end example 3444 3445@noindent 3446will directly draw a random isosurface geometry in a graphics window. 3447 3448An example of an isosurface geometry with different additional coloring: 3449@c Set example in small font to prevent overfull line 3450 3451@smallexample 3452N = 15; # Increase number of vertices in each direction 3453iso = .4; # Change isovalue to .1 to display a sphere 3454lin = linspace (0, 2, N); 3455[x, y, z] = meshgrid (lin, lin, lin); 3456v = abs ((x-.5).^2 + (y-.5).^2 + (z-.5).^2); 3457figure (); 3458 3459subplot (2,2,1); view (-38, 20); 3460[f, vert] = isosurface (x, y, z, v, iso); 3461p = patch ("Faces", f, "Vertices", vert, "EdgeColor", "none"); 3462pbaspect ([1 1 1]); 3463isonormals (x, y, z, v, p) 3464set (p, "FaceColor", "green", "FaceLighting", "gouraud"); 3465light ("Position", [1 1 5]); 3466 3467subplot (2,2,2); view (-38, 20); 3468p = patch ("Faces", f, "Vertices", vert, "EdgeColor", "blue"); 3469pbaspect ([1 1 1]); 3470isonormals (x, y, z, v, p) 3471set (p, "FaceColor", "none", "EdgeLighting", "gouraud"); 3472light ("Position", [1 1 5]); 3473 3474subplot (2,2,3); view (-38, 20); 3475[f, vert, c] = isosurface (x, y, z, v, iso, y); 3476p = patch ("Faces", f, "Vertices", vert, "FaceVertexCData", c, ... 3477 "FaceColor", "interp", "EdgeColor", "none"); 3478pbaspect ([1 1 1]); 3479isonormals (x, y, z, v, p) 3480set (p, "FaceLighting", "gouraud"); 3481light ("Position", [1 1 5]); 3482 3483subplot (2,2,4); view (-38, 20); 3484p = patch ("Faces", f, "Vertices", vert, "FaceVertexCData", c, ... 3485 "FaceColor", "interp", "EdgeColor", "blue"); 3486pbaspect ([1 1 1]); 3487isonormals (x, y, z, v, p) 3488set (p, "FaceLighting", "gouraud"); 3489light ("Position", [1 1 5]); 3490@end smallexample 3491 3492@xseealso{@ref{XREFisonormals,,isonormals}, @ref{XREFisocolors,,isocolors}, @ref{XREFisocaps,,isocaps}, @ref{XREFsmooth3,,smooth3}, @ref{XREFreducevolume,,reducevolume}, @ref{XREFreducepatch,,reducepatch}, @ref{XREFpatch,,patch}} 3493@end deftypefn 3494 3495 3496@c isonormals scripts/plot/draw/isonormals.m 3497@anchor{XREFisonormals} 3498@deftypefn {} {@var{vn} =} isonormals (@var{val}, @var{vert}) 3499@deftypefnx {} {@var{vn} =} isonormals (@var{val}, @var{hp}) 3500@deftypefnx {} {@var{vn} =} isonormals (@var{x}, @var{y}, @var{z}, @var{val}, @var{vert}) 3501@deftypefnx {} {@var{vn} =} isonormals (@var{x}, @var{y}, @var{z}, @var{val}, @var{hp}) 3502@deftypefnx {} {@var{vn} =} isonormals (@dots{}, "negate") 3503@deftypefnx {} {} isonormals (@var{val}, @var{hp}) 3504@deftypefnx {} {} isonormals (@var{x}, @var{y}, @var{z}, @var{val}, @var{hp}) 3505@deftypefnx {} {} isonormals (@dots{}, "negate") 3506 3507Calculate normals to an isosurface. 3508 3509The vertex normals @var{vn} are calculated from the gradient of the 35103-dimensional array @var{val} (size: lxmxn) containing the data for an 3511isosurface geometry. The normals point towards smaller values in @var{val}. 3512 3513If called with one output argument @var{vn}, and the second input argument 3514@var{vert} holds the vertices of an isosurface, then the normals @var{vn} 3515are calculated at the vertices @var{vert} on a grid given by 3516@code{[x, y, z] = meshgrid (1:l, 1:m, 1:n)}. The output argument 3517@var{vn} has the same size as @var{vert} and can be used to set the 3518@qcode{"VertexNormals"} property of the corresponding patch. 3519 3520If called with additional input arguments @var{x}, @var{y}, and @var{z}, 3521which are 3-dimensional arrays with the same size as @var{val}, 3522then the volume data is taken at these points. Instead of the vertex data 3523@var{vert}, a patch handle @var{hp} can be passed to the function. 3524 3525If the last input argument is the string @qcode{"negate"}, compute the 3526reverse vector normals of an isosurface geometry (i.e., pointed towards 3527larger values in @var{val}). 3528 3529If no output argument is given, the property @qcode{"VertexNormals"} of 3530the patch associated with the patch handle @var{hp} is changed directly. 3531 3532@xseealso{@ref{XREFisosurface,,isosurface}, @ref{XREFisocolors,,isocolors}, @ref{XREFsmooth3,,smooth3}} 3533@end deftypefn 3534 3535 3536@c isocaps scripts/plot/draw/isocaps.m 3537@anchor{XREFisocaps} 3538@deftypefn {} {@var{fvc} =} isocaps (@var{v}, @var{isoval}) 3539@deftypefnx {} {@var{fvc} =} isocaps (@var{v}) 3540@deftypefnx {} {@var{fvc} =} isocaps (@var{x}, @var{y}, @var{z}, @var{v}, @var{isoval}) 3541@deftypefnx {} {@var{fvc} =} isocaps (@var{x}, @var{y}, @var{z}, @var{v}) 3542@deftypefnx {} {@var{fvc} =} isocaps (@dots{}, @var{which_caps}) 3543@deftypefnx {} {@var{fvc} =} isocaps (@dots{}, @var{which_plane}) 3544@deftypefnx {} {@var{fvc} =} isocaps (@dots{}, @qcode{"verbose"}) 3545@deftypefnx {} {[@var{faces}, @var{vertices}, @var{fvcdata}] =} isocaps (@dots{}) 3546@deftypefnx {} {} isocaps (@dots{}) 3547 3548Create end-caps for isosurfaces of 3-D data. 3549 3550This function places caps at the open ends of isosurfaces. 3551 3552The input argument @var{v} is a three-dimensional array that contains data 3553sampled over a volume. 3554 3555The input @var{isoval} is a scalar that specifies the value for the 3556isosurface. If @var{isoval} is omitted or empty, a @nospell{"good"} value 3557for an isosurface is determined from @var{v}. 3558 3559When called with a single output argument, @code{isocaps} returns a 3560structure array @var{fvc} with the fields: @code{faces}, @code{vertices}, 3561and @code{facevertexcdata}. The results are computed at the points 3562@code{[@var{x}, @var{y}, @var{z}] = meshgrid (1:l, 1:m, 1:n)} where 3563@code{[l, m, n] = size (@var{v})}. The output @var{fvc} can be used 3564directly as input to the @code{patch} function. 3565 3566If called with additional input arguments @var{x}, @var{y}, and @var{z} 3567that are three-dimensional arrays with the same size as @var{v} or 3568vectors with lengths corresponding to the dimensions of @var{v}, then the 3569volume data is taken at the specified points. If @var{x}, @var{y}, or 3570@var{z} are empty, the grid corresponds to the indices (@code{1:n}) in 3571the respective direction (@pxref{XREFmeshgrid,,meshgrid}). 3572 3573The optional parameter @var{which_caps} can have one of the following 3574string values which defines how the data will be enclosed: 3575 3576@table @asis 3577@item @qcode{"above"}, @qcode{"a"} (default) 3578for end-caps that enclose the data above @var{isoval}. 3579 3580@item @qcode{"below"}, @qcode{"b"} 3581for end-caps that enclose the data below @var{isoval}. 3582@end table 3583 3584The optional parameter @var{which_plane} can have one of the following 3585string values to define which end-cap should be drawn: 3586 3587@table @asis 3588@item @qcode{"all"} (default) 3589for all of the end-caps. 3590 3591@item @qcode{"xmin"} 3592for end-caps at the lower x-plane of the data. 3593 3594@item @qcode{"xmax"} 3595for end-caps at the upper x-plane of the data. 3596 3597@item @qcode{"ymin"} 3598for end-caps at the lower y-plane of the data. 3599 3600@item @qcode{"ymax"} 3601for end-caps at the upper y-plane of the data. 3602 3603@item @qcode{"zmin"} 3604for end-caps at the lower z-plane of the data. 3605 3606@item @qcode{"zmax"} 3607for end-caps at the upper z-plane of the data. 3608@end table 3609 3610The string input argument @qcode{"verbose"} is supported for @sc{matlab} 3611compatibility, but has no effect. 3612 3613If called with two or three output arguments, the data for faces 3614@var{faces}, vertices @var{vertices}, and the color data 3615@var{facevertexcdata} are returned in separate arrays instead of a single 3616structure. 3617 3618If called with no output argument, the end-caps are drawn directly in the 3619current figure with the @code{patch} command. 3620 3621@xseealso{@ref{XREFisosurface,,isosurface}, @ref{XREFisonormals,,isonormals}, @ref{XREFpatch,,patch}} 3622@end deftypefn 3623 3624 3625@c isocolors scripts/plot/draw/isocolors.m 3626@anchor{XREFisocolors} 3627@deftypefn {} {@var{cdat} =} isocolors (@var{c}, @var{v}) 3628@deftypefnx {} {@var{cdat} =} isocolors (@var{x}, @var{y}, @var{z}, @var{c}, @var{v}) 3629@deftypefnx {} {@var{cdat} =} isocolors (@var{x}, @var{y}, @var{z}, @var{r}, @var{g}, @var{b}, @var{v}) 3630@deftypefnx {} {@var{cdat} =} isocolors (@var{r}, @var{g}, @var{b}, @var{v}) 3631@deftypefnx {} {@var{cdat} =} isocolors (@dots{}, @var{p}) 3632@deftypefnx {} {} isocolors (@dots{}) 3633 3634Compute isosurface colors. 3635 3636If called with one output argument, and the first input argument @var{c} 3637is a three-dimensional array that contains indexed color values, and the 3638second input argument @var{v} are the vertices of an isosurface geometry, 3639then return a matrix @var{cdat} with color data information for the geometry 3640at computed points @code{[x, y, z] = meshgrid (1:l, 1:m, 1:n)}. The output 3641argument @var{cdat} can be used to manually set the 3642@qcode{"FaceVertexCData"} property of an isosurface patch object. 3643 3644If called with additional input arguments @var{x}, @var{y} and @var{z} which 3645are three-dimensional arrays of the same size as @var{c} then the 3646color data is taken at those specified points. 3647 3648Instead of indexed color data @var{c}, @code{isocolors} can also be called 3649with RGB values @var{r}, @var{g}, @var{b}. If input arguments @var{x}, 3650@var{y}, @var{z} are not given then @code{meshgrid} computed values are 3651used. 3652 3653Optionally, a patch handle @var{p} can be given as the last input argument 3654to all function call variations and the vertex data will be extracted 3655from the isosurface patch object. Finally, if no output argument is given 3656then the colors of the patch given by the patch handle @var{p} are changed. 3657 3658@xseealso{@ref{XREFisosurface,,isosurface}, @ref{XREFisonormals,,isonormals}} 3659@end deftypefn 3660 3661 3662@c smooth3 scripts/plot/draw/smooth3.m 3663@anchor{XREFsmooth3} 3664@deftypefn {} {@var{smoothed_data} =} smooth3 (@var{data}) 3665@deftypefnx {} {@var{smoothed_data} =} smooth3 (@var{data}, @var{method}) 3666@deftypefnx {} {@var{smoothed_data} =} smooth3 (@var{data}, @var{method}, @var{sz}) 3667@deftypefnx {} {@var{smoothed_data} =} smooth3 (@var{data}, @var{method}, @var{sz}, @var{std_dev}) 3668Smooth values of 3-dimensional matrix @var{data}. 3669 3670This function may be used, for example, to reduce the impact of noise in 3671@var{data} before calculating isosurfaces. 3672 3673@var{data} must be a non-singleton 3-dimensional matrix. The output 3674@var{smoothed_data} is a matrix of the same size as @var{data}. 3675 3676The option input @var{method} determines which convolution kernel is used 3677for the smoothing process. Possible choices: 3678 3679@table @asis 3680@item @qcode{"box"}, @qcode{"b"} (default) 3681a convolution kernel with sharp edges. 3682 3683@item @qcode{"gaussian"}, @qcode{"g"} 3684a convolution kernel that is represented by a non-correlated trivariate 3685normal distribution function. 3686@end table 3687 3688@var{sz} is either a 3-element vector specifying the size of the 3689convolution kernel in the x-, y- and z-directions, or a scalar. In the 3690scalar case the same size is used for all three dimensions 3691(@code{[@var{sz}, @var{sz}, @var{sz}]}). The default value is 3. 3692 3693If @var{method} is @qcode{"gaussian"} then the optional input @var{std_dev} 3694defines the standard deviation of the trivariate normal distribution 3695function. @var{std_dev} is either a 3-element vector specifying the 3696standard deviation of the Gaussian convolution kernel in x-, y- and 3697z-directions, or a scalar. In the scalar case the same value is used for 3698all three dimensions. The default value is 0.65. 3699 3700@xseealso{@ref{XREFisosurface,,isosurface}, @ref{XREFisonormals,,isonormals}, @ref{XREFpatch,,patch}} 3701@end deftypefn 3702 3703 3704@c reducevolume scripts/plot/draw/reducevolume.m 3705@anchor{XREFreducevolume} 3706@deftypefn {} {[@var{nx}, @var{ny}, @var{nz}, @var{nv}] =} reducevolume (@var{v}, @var{r}) 3707@deftypefnx {} {[@var{nx}, @var{ny}, @var{nz}, @var{nv}] =} reducevolume (@var{x}, @var{y}, @var{z}, @var{v}, @var{r}) 3708@deftypefnx {} {@var{nv} =} reducevolume (@dots{}) 3709 3710Reduce the volume of the dataset in @var{v} according to the values in 3711@var{r}. 3712 3713@var{v} is a matrix that is non-singleton in the first 3 dimensions. 3714 3715@var{r} can either be a vector of 3 elements representing the reduction 3716factors in the x-, y-, and z-directions or a scalar, in which case the same 3717reduction factor is used in all three dimensions. 3718 3719@code{reducevolume} reduces the number of elements of @var{v} by taking 3720only every @var{r}-th element in the respective dimension. 3721 3722Optionally, @var{x}, @var{y}, and @var{z} can be supplied to represent the 3723set of coordinates of @var{v}. They can either be matrices of the same size 3724as @var{v} or vectors with sizes according to the dimensions of @var{v}, in 3725which case they are expanded to matrices (@pxref{XREFmeshgrid,,meshgrid}). 3726 3727If @code{reducevolume} is called with two arguments then @var{x}, @var{y}, 3728and @var{z} are assumed to match the respective indices of @var{v}. 3729 3730The reduced matrix is returned in @var{nv}. 3731 3732Optionally, the reduced set of coordinates are returned in @var{nx}, 3733@var{ny}, and @var{nz}, respectively. 3734 3735Examples: 3736 3737@example 3738@group 3739@var{v} = reshape (1:6*8*4, [6 8 4]); 3740@var{nv} = reducevolume (@var{v}, [4 3 2]); 3741@end group 3742@end example 3743 3744@example 3745@group 3746@var{v} = reshape (1:6*8*4, [6 8 4]); 3747@var{x} = 1:3:24; @var{y} = -14:5:11; @var{z} = linspace (16, 18, 4); 3748[@var{nx}, @var{ny}, @var{nz}, @var{nv}] = reducevolume (@var{x}, @var{y}, @var{z}, @var{v}, [4 3 2]); 3749@end group 3750@end example 3751 3752@xseealso{@ref{XREFisosurface,,isosurface}, @ref{XREFisonormals,,isonormals}} 3753@end deftypefn 3754 3755 3756@c reducepatch scripts/plot/draw/reducepatch.m 3757@anchor{XREFreducepatch} 3758@deftypefn {} {@var{reduced_fv} =} reducepatch (@var{fv}) 3759@deftypefnx {} {@var{reduced_fv} =} reducepatch (@var{faces}, @var{vertices}) 3760@deftypefnx {} {@var{reduced_fv} =} reducepatch (@var{patch_handle}) 3761@deftypefnx {} {} reducepatch (@var{patch_handle}) 3762@deftypefnx {} {@var{reduced_fv} =} reducepatch (@dots{}, @var{reduction_factor}) 3763@deftypefnx {} {@var{reduced_fv} =} reducepatch (@dots{}, "fast") 3764@deftypefnx {} {@var{reduced_fv} =} reducepatch (@dots{}, "verbose") 3765@deftypefnx {} {[@var{reduced_faces}, @var{reduces_vertices}] =} reducepatch (@dots{}) 3766 3767Reduce the number of faces and vertices in a patch object while retaining 3768the overall shape of the patch. 3769 3770The input patch can be represented by a structure @var{fv} with the 3771fields @code{faces} and @code{vertices}, by two matrices @var{faces} and 3772@var{vertices} (see, e.g., the result of @code{isosurface}), or by a 3773handle to a patch object @var{patch_handle} (@pxref{XREFpatch,,patch}). 3774 3775The number of faces and vertices in the patch is reduced by iteratively 3776collapsing the shortest edge of the patch to its midpoint (as discussed, 3777e.g., here: 3778@url{https://libigl.github.io/libigl/tutorial/tutorial.html#meshdecimation}). 3779 3780Currently, only patches consisting of triangles are supported. The 3781resulting patch also consists only of triangles. 3782 3783If @code{reducepatch} is called with a handle to a valid patch 3784@var{patch_handle}, and without any output arguments, then the given 3785patch is updated immediately. 3786 3787If the @var{reduction_factor} is omitted, the resulting structure 3788@var{reduced_fv} includes approximately 50% of the faces of the original 3789patch. If @var{reduction_factor} is a fraction between 0 (excluded) and 1 3790(excluded), a patch with approximately the corresponding fraction of faces 3791is determined. 3792If @var{reduction_factor} is an integer greater than or equal to 1, the 3793resulting patch has approximately @var{reduction_factor} faces. Depending 3794on the geometry of the patch, the resulting number of faces can differ from 3795the given value of @var{reduction_factor}. This is especially true when 3796many shared vertices are detected. 3797 3798For the reduction, it is necessary that vertices of touching faces are 3799shared. Shared vertices are detected automatically. This detection can be 3800skipped by passing the optional string argument @qcode{"fast"}. 3801 3802With the optional string arguments @qcode{"verbose"}, additional status 3803messages are printed to the command window. 3804 3805Any string input arguments must be passed after all other arguments. 3806 3807If called with one output argument, the reduced faces and vertices are 3808returned in a structure @var{reduced_fv} with the fields @code{faces} and 3809@code{vertices} (see the one output option of @code{isosurface}). 3810 3811If called with two output arguments, the reduced faces and vertices are 3812returned in two separate matrices @var{reduced_faces} and 3813@var{reduced_vertices}. 3814 3815@xseealso{@ref{XREFisosurface,,isosurface}, @ref{XREFisonormals,,isonormals}, @ref{XREFreducevolume,,reducevolume}, @ref{XREFpatch,,patch}} 3816@end deftypefn 3817 3818 3819@c shrinkfaces scripts/plot/draw/shrinkfaces.m 3820@anchor{XREFshrinkfaces} 3821@deftypefn {} {} shrinkfaces (@var{p}, @var{sf}) 3822@deftypefnx {} {@var{nfv} =} shrinkfaces (@var{p}, @var{sf}) 3823@deftypefnx {} {@var{nfv} =} shrinkfaces (@var{fv}, @var{sf}) 3824@deftypefnx {} {@var{nfv} =} shrinkfaces (@var{f}, @var{v}, @var{sf}) 3825@deftypefnx {} {[@var{nf}, @var{nv}] =} shrinkfaces (@dots{}) 3826 3827Reduce the size of faces in a patch by the shrink factor @var{sf}. 3828 3829The patch object can be specified by a graphics handle (@var{p}), a patch 3830structure (@var{fv}) with the fields @qcode{"faces"} and @qcode{"vertices"}, 3831or as two separate matrices (@var{f}, @var{v}) of faces and vertices. 3832 3833The shrink factor @var{sf} is a positive number specifying the percentage 3834of the original area the new face will occupy. If no factor is given the 3835default is 0.3 (a reduction to 30% of the original size). A factor greater 3836than 1.0 will result in the expansion of faces. 3837 3838Given a patch handle as the first input argument and no output parameters, 3839perform the shrinking of the patch faces in place and redraw the patch. 3840 3841If called with one output argument, return a structure with fields 3842@qcode{"faces"}, @qcode{"vertices"}, and @qcode{"facevertexcdata"} 3843containing the data after shrinking. This structure can be used directly 3844as an input argument to the @code{patch} function. 3845 3846@strong{Caution:}: Performing the shrink operation on faces which are not 3847convex can lead to undesirable results. 3848 3849Example: a triangulated 3/4 circle and the corresponding shrunken version. 3850 3851@example 3852@group 3853[phi r] = meshgrid (linspace (0, 1.5*pi, 16), linspace (1, 2, 4)); 3854tri = delaunay (phi(:), r(:)); 3855v = [r(:).*sin(phi(:)) r(:).*cos(phi(:))]; 3856clf () 3857p = patch ("Faces", tri, "Vertices", v, "FaceColor", "none"); 3858fv = shrinkfaces (p); 3859patch (fv) 3860axis equal 3861grid on 3862@end group 3863@end example 3864 3865@xseealso{@ref{XREFpatch,,patch}} 3866@end deftypefn 3867 3868 3869@c diffuse scripts/plot/appearance/diffuse.m 3870@anchor{XREFdiffuse} 3871@deftypefn {} {} diffuse (@var{sx}, @var{sy}, @var{sz}, @var{lv}) 3872Calculate the diffuse reflection strength of a surface defined by the normal 3873vector elements @var{sx}, @var{sy}, @var{sz}. 3874 3875The light source location vector @var{lv} can be given as a 2-element vector 3876[azimuth, elevation] in degrees or as a 3-element vector [x, y, z]. 3877@xseealso{@ref{XREFspecular,,specular}, @ref{XREFsurfl,,surfl}} 3878@end deftypefn 3879 3880 3881@c specular scripts/plot/appearance/specular.m 3882@anchor{XREFspecular} 3883@deftypefn {} {} specular (@var{sx}, @var{sy}, @var{sz}, @var{lv}, @var{vv}) 3884@deftypefnx {} {} specular (@var{sx}, @var{sy}, @var{sz}, @var{lv}, @var{vv}, @var{se}) 3885Calculate the specular reflection strength of a surface defined by the 3886normal vector elements @var{sx}, @var{sy}, @var{sz} using Phong's 3887approximation. 3888 3889The light source location and viewer location vectors are specified using 3890parameters @var{lv} and @var{vv} respectively. The location vectors can 3891given as 2-element vectors [azimuth, elevation] in degrees or as 3-element 3892vectors [x, y, z]. 3893 3894An optional sixth argument specifies the specular exponent (spread) 3895@var{se}. If not given, @var{se} defaults to 10. 3896@xseealso{@ref{XREFdiffuse,,diffuse}, @ref{XREFsurfl,,surfl}} 3897@end deftypefn 3898 3899 3900@c lighting scripts/plot/appearance/lighting.m 3901@anchor{XREFlighting} 3902@deftypefn {} {} lighting (@var{type}) 3903@deftypefnx {} {} lighting (@var{hax}, @var{type}) 3904Set the lighting of patch or surface graphic objects. 3905 3906Valid arguments for @var{type} are 3907 3908@table @asis 3909@item @qcode{"flat"} 3910Draw objects with faceted lighting effects. 3911 3912@item @qcode{"gouraud"} 3913Draw objects with linear interpolation of the lighting effects between the 3914vertices. 3915 3916@item @qcode{"none"} 3917Draw objects without light and shadow effects. 3918@end table 3919 3920If the first argument @var{hax} is an axes handle, then change the lighting 3921effects of objects in this axes, rather than the current axes returned by 3922@code{gca}. 3923 3924The lighting effects are only visible if at least one light object is 3925present and visible in the same axes. 3926 3927@xseealso{@ref{XREFlight,,light}, @ref{XREFfill,,fill}, @ref{XREFmesh,,mesh}, @ref{XREFpatch,,patch}, @ref{XREFpcolor,,pcolor}, @ref{XREFsurf,,surf}, @ref{XREFsurface,,surface}, @ref{XREFshading,,shading}} 3928@end deftypefn 3929 3930 3931@c material scripts/plot/appearance/material.m 3932@anchor{XREFmaterial} 3933@deftypefn {} {} material shiny 3934@deftypefnx {} {} material dull 3935@deftypefnx {} {} material metal 3936@deftypefnx {} {} material default 3937@deftypefnx {} {} material ([@var{as}, @var{ds}, @var{ss}]) 3938@deftypefnx {} {} material ([@var{as}, @var{ds}, @var{ss}, @var{se}]) 3939@deftypefnx {} {} material ([@var{as}, @var{ds}, @var{ss}, @var{se}, @var{scr}]) 3940@deftypefnx {} {} material (@var{hlist}, @dots{}) 3941@deftypefnx {} {@var{mtypes} =} material () 3942@deftypefnx {} {@var{refl_props} =} material (@var{mtype_string}) 3943Set reflectance properties for the lighting of surfaces and patches. 3944 3945This function changes the ambient, diffuse, and specular strengths, as well 3946as the specular exponent and specular color reflectance, of all 3947@code{patch} and @code{surface} objects in the current axes. This can be 3948used to simulate, to some extent, the reflectance properties of certain 3949materials when used with @code{light}. 3950 3951When called with a string, the aforementioned properties are set 3952according to the values in the following table: 3953 3954@multitable @columnfractions .0 .2 .15 .15 .15 .15 .15 .0 3955@headitem @tab @var{mtype} @tab ambient- strength @tab diffuse- 3956strength @tab specular- strength @tab specular- exponent @tab specular- 3957color- reflectance @tab 3958@item @tab @qcode{"shiny"} @tab 0.3 @tab 0.6 @tab 0.9 @tab 20 @tab 1.0 @tab 3959@item @tab @qcode{"dull"} @tab 0.3 @tab 0.8 @tab 0.0 @tab 10 @tab 1.0 @tab 3960@item @tab @qcode{"metal"} @tab 0.3 @tab 0.3 @tab 1.0 @tab 25 @tab 0.5 @tab 3961@item @tab @qcode{"default"} @tab @qcode{"default"} @tab @qcode{"default"} @tab @qcode{"default"} @tab 3962@qcode{"default"} @tab @qcode{"default"} @tab 3963@end multitable 3964 3965When called with a vector of three elements, the ambient, diffuse, and 3966specular strengths of all @code{patch} and @code{surface} objects in the 3967current axes are updated. An optional fourth vector element updates the 3968specular exponent, and an optional fifth vector element updates the 3969specular color reflectance. 3970 3971A list of graphic handles can also be passed as the first argument. In 3972this case, the properties of these handles and all child @code{patch} and 3973@code{surface} objects will be updated. 3974 3975Additionally, @code{material} can be called with a single output argument. 3976If called without input arguments, a column cell vector @var{mtypes} with 3977the strings for all available materials is returned. If the one input 3978argument @var{mtype_string} is the name of a material, a 1x5 cell vector 3979@var{refl_props} with the reflectance properties of that material is 3980returned. In both cases, no graphic properties are changed. 3981 3982@xseealso{@ref{XREFlight,,light}, @ref{XREFfill,,fill}, @ref{XREFmesh,,mesh}, @ref{XREFpatch,,patch}, @ref{XREFpcolor,,pcolor}, @ref{XREFsurf,,surf}, @ref{XREFsurface,,surface}} 3983@end deftypefn 3984 3985 3986@c camlight scripts/plot/draw/camlight.m 3987@anchor{XREFcamlight} 3988@deftypefn {} {} camlight {} 3989@deftypefnx {} {} camlight right 3990@deftypefnx {} {} camlight left 3991@deftypefnx {} {} camlight headlight 3992@deftypefnx {} {} camlight (@var{az}, @var{el}) 3993@deftypefnx {} {} camlight (@dots{}, @var{style}) 3994@deftypefnx {} {} camlight (@var{hl}, @dots{}) 3995@deftypefnx {} {} camlight (@var{hax}, @dots{}) 3996@deftypefnx {} {@var{h} =} camlight (@dots{}) 3997Add a light object to a figure using a simple interface. 3998 3999When called with no arguments, a light object is added to the current plot 4000and is placed slightly above and to the right of the camera's current 4001position: this is equivalent to @code{camlight right}. The commands 4002@code{camlight left} and @code{camlight headlight} behave similarly with 4003the placement being either left of the camera position or centered on the 4004camera position. 4005 4006For more control, the light position can be specified by an azimuthal 4007rotation @var{az} and an elevation angle @var{el}, both in degrees, 4008relative to the current properties of the camera. 4009 4010The optional string @var{style} specifies whether the light is a local point 4011source (@qcode{"local"}, the default) or placed at infinite distance 4012(@qcode{"infinite"}). 4013 4014If the first argument @var{hl} is a handle to a light object, then act on 4015this light object rather than creating a new object. 4016 4017If the first argument @var{hax} is an axes handle, then create a new light 4018object in this axes, rather than the current axes returned by @code{gca}. 4019 4020The optional return value @var{h} is a graphics handle to the light object. 4021This can be used to move or further change properties of the light object. 4022 4023Examples: 4024 4025Add a light object to a plot 4026 4027@example 4028@group 4029@c doctest: +SKIP 4030sphere (36); 4031camlight 4032@end group 4033@end example 4034 4035Position the light source exactly 4036 4037@example 4038@group 4039@c doctest: +SKIP 4040camlight (45, 30); 4041@end group 4042@end example 4043 4044Here the light is first pitched upwards (@pxref{XREFcamup,,camup}) from the 4045camera position (@pxref{XREFcampos,,campos}) by 30 degrees. It is then 4046yawed by 45 degrees to the right. Both rotations are centered around the 4047camera target (@pxref{XREFcamtarget,,camtarget}). 4048 4049Return a handle to further manipulate the light object 4050 4051@example 4052@group 4053@c doctest: +SKIP 4054clf 4055sphere (36); 4056hl = camlight ("left"); 4057set (hl, "color", "r"); 4058@end group 4059@end example 4060 4061@xseealso{@ref{XREFlight,,light}} 4062@end deftypefn 4063 4064 4065@c lightangle scripts/plot/draw/lightangle.m 4066@anchor{XREFlightangle} 4067@deftypefn {} {} lightangle (@var{az}, @var{el}) 4068@deftypefnx {} {} lightangle (@var{hax}, @var{az}, @var{el}) 4069@deftypefnx {} {} lightangle (@var{hl}, @var{az}, @var{el}) 4070@deftypefnx {} {@var{hl} =} lightangle (@dots{}) 4071@deftypefnx {} {[@var{az}, @var{el}] =} lightangle (@var{hl}) 4072Add a light object to the current axes using spherical coordinates. 4073 4074The light position is specified by an azimuthal rotation @var{az} and an 4075elevation angle @var{el}, both in degrees. 4076 4077If the first argument @var{hax} is an axes handle, then create a new light 4078object in this axes, rather than the current axes returned by @code{gca}. 4079 4080If the first argument @var{hl} is a handle to a light object, then act on 4081this light object rather than creating a new object. 4082 4083The optional return value @var{hl} is a graphics handle to the light object. 4084 4085Example: 4086 4087Add a light object to a plot 4088 4089@example 4090@group 4091@c doctest: +SKIP 4092clf; 4093sphere (36); 4094lightangle (45, 30); 4095@end group 4096@end example 4097 4098@xseealso{@ref{XREFlight,,light}, @ref{XREFview,,view}, @ref{XREFcamlight,,camlight}} 4099@end deftypefn 4100 4101 4102@c meshgrid scripts/plot/util/meshgrid.m 4103@anchor{XREFmeshgrid} 4104@deftypefn {} {[@var{xx}, @var{yy}] =} meshgrid (@var{x}, @var{y}) 4105@deftypefnx {} {[@var{xx}, @var{yy}, @var{zz}] =} meshgrid (@var{x}, @var{y}, @var{z}) 4106@deftypefnx {} {[@var{xx}, @var{yy}] =} meshgrid (@var{x}) 4107@deftypefnx {} {[@var{xx}, @var{yy}, @var{zz}] =} meshgrid (@var{x}) 4108Given vectors of @var{x} and @var{y} coordinates, return matrices @var{xx} 4109and @var{yy} corresponding to a full 2-D grid. 4110 4111The rows of @var{xx} are copies of @var{x}, and the columns of @var{yy} are 4112copies of @var{y}. If @var{y} is omitted, then it is assumed to be the same 4113as @var{x}. 4114 4115If the optional @var{z} input is given, or @var{zz} is requested, then the 4116output will be a full 3-D grid. If @var{z} is omitted and @var{zz} is 4117requested, it is assumed to be the same as @var{y}. 4118 4119@code{meshgrid} is most frequently used to produce input for a 2-D or 3-D 4120function that will be plotted. The following example creates a surface 4121plot of the ``sombrero'' function. 4122 4123@example 4124@group 4125f = @@(x,y) sin (sqrt (x.^2 + y.^2)) ./ sqrt (x.^2 + y.^2); 4126range = linspace (-8, 8, 41); 4127[@var{X}, @var{Y}] = meshgrid (range, range); 4128Z = f (X, Y); 4129surf (X, Y, Z); 4130@end group 4131@end example 4132 4133Programming Note: @code{meshgrid} is restricted to 2-D or 3-D grid 4134generation. The @code{ndgrid} function will generate 1-D through N-D 4135grids. However, the functions are not completely equivalent. If @var{x} 4136is a vector of length M and @var{y} is a vector of length N, then 4137@code{meshgrid} will produce an output grid which is NxM@. @code{ndgrid} 4138will produce an output which is @nospell{MxN} (transpose) for the same 4139input. Some core functions expect @code{meshgrid} input and others expect 4140@code{ndgrid} input. Check the documentation for the function in question 4141to determine the proper input format. 4142@xseealso{@ref{XREFndgrid,,ndgrid}, @ref{XREFmesh,,mesh}, @ref{XREFcontour,,contour}, @ref{XREFsurf,,surf}} 4143@end deftypefn 4144 4145 4146@c ndgrid scripts/plot/util/ndgrid.m 4147@anchor{XREFndgrid} 4148@deftypefn {} {[@var{y1}, @var{y2}, @dots{}, @var{y}n] =} ndgrid (@var{x1}, @var{x2}, @dots{}, @var{x}n) 4149@deftypefnx {} {[@var{y1}, @var{y2}, @dots{}, @var{y}n] =} ndgrid (@var{x}) 4150Given n vectors @var{x1}, @dots{}, @var{x}n, @code{ndgrid} returns n 4151arrays of dimension n. 4152 4153The elements of the i-th output argument contains the elements of the 4154vector @var{x}i repeated over all dimensions different from the i-th 4155dimension. Calling ndgrid with only one input argument @var{x} is 4156equivalent to calling ndgrid with all n input arguments equal to @var{x}: 4157 4158[@var{y1}, @var{y2}, @dots{}, @var{y}n] = ndgrid (@var{x}, @dots{}, @var{x}) 4159 4160Programming Note: @code{ndgrid} is very similar to the function 4161@code{meshgrid} except that the first two dimensions are transposed in 4162comparison to @code{meshgrid}. Some core functions expect @code{meshgrid} 4163input and others expect @code{ndgrid} input. Check the documentation for 4164the function in question to determine the proper input format. 4165@xseealso{@ref{XREFmeshgrid,,meshgrid}} 4166@end deftypefn 4167 4168 4169@c plot3 scripts/plot/draw/plot3.m 4170@anchor{XREFplot3} 4171@deftypefn {} {} plot3 (@var{x}, @var{y}, @var{z}) 4172@deftypefnx {} {} plot3 (@var{x}, @var{y}, @var{z}, @var{prop}, @var{value}, @dots{}) 4173@deftypefnx {} {} plot3 (@var{x}, @var{y}, @var{z}, @var{fmt}) 4174@deftypefnx {} {} plot3 (@var{x}, @var{cplx}) 4175@deftypefnx {} {} plot3 (@var{cplx}) 4176@deftypefnx {} {} plot3 (@var{hax}, @dots{}) 4177@deftypefnx {} {@var{h} =} plot3 (@dots{}) 4178Produce 3-D plots. 4179 4180Many different combinations of arguments are possible. The simplest 4181form is 4182 4183@example 4184plot3 (@var{x}, @var{y}, @var{z}) 4185@end example 4186 4187@noindent 4188in which the arguments are taken to be the vertices of the points to 4189be plotted in three dimensions. If all arguments are vectors of the 4190same length, then a single continuous line is drawn. If all arguments 4191are matrices, then each column of is treated as a separate line. No attempt 4192is made to transpose the arguments to make the number of rows match. 4193 4194If only two arguments are given, as 4195 4196@example 4197plot3 (@var{x}, @var{cplx}) 4198@end example 4199 4200@noindent 4201the real and imaginary parts of the second argument are used 4202as the @var{y} and @var{z} coordinates, respectively. 4203 4204If only one argument is given, as 4205 4206@example 4207plot3 (@var{cplx}) 4208@end example 4209 4210@noindent 4211the real and imaginary parts of the argument are used as the @var{y} 4212and @var{z} values, and they are plotted versus their index. 4213 4214Arguments may also be given in groups of three as 4215 4216@example 4217plot3 (@var{x1}, @var{y1}, @var{z1}, @var{x2}, @var{y2}, @var{z2}, @dots{}) 4218@end example 4219 4220@noindent 4221in which each set of three arguments is treated as a separate line or 4222set of lines in three dimensions. 4223 4224To plot multiple one- or two-argument groups, separate each group 4225with an empty format string, as 4226 4227@example 4228plot3 (@var{x1}, @var{c1}, "", @var{c2}, "", @dots{}) 4229@end example 4230 4231Multiple property-value pairs may be specified which will affect the line 4232objects drawn by @code{plot3}. If the @var{fmt} argument is supplied it 4233will format the line objects in the same manner as @code{plot}. 4234The full list of properties is documented at 4235@ref{Line Properties}. 4236 4237If the first argument @var{hax} is an axes handle, then plot into this axes, 4238rather than the current axes returned by @code{gca}. 4239 4240The optional return value @var{h} is a graphics handle to the created plot. 4241 4242Example: 4243 4244@example 4245@group 4246z = [0:0.05:5]; 4247plot3 (cos (2*pi*z), sin (2*pi*z), z, ";helix;"); 4248plot3 (z, exp (2i*pi*z), ";complex sinusoid;"); 4249@end group 4250@end example 4251@xseealso{@ref{XREFezplot3,,ezplot3}, @ref{XREFplot,,plot}} 4252@end deftypefn 4253 4254 4255@c view scripts/plot/appearance/view.m 4256@anchor{XREFview} 4257@deftypefn {} {} view (@var{azimuth}, @var{elevation}) 4258@deftypefnx {} {} view ([@var{azimuth} @var{elevation}]) 4259@deftypefnx {} {} view ([@var{x} @var{y} @var{z}]) 4260@deftypefnx {} {} view (2) 4261@deftypefnx {} {} view (3) 4262@deftypefnx {} {} view (@var{hax}, @dots{}) 4263@deftypefnx {} {[@var{azimuth}, @var{elevation}] =} view () 4264Query or set the viewpoint for the current axes. 4265 4266The parameters @var{azimuth} and @var{elevation} can be given as two 4267arguments or as 2-element vector. The viewpoint can also be specified with 4268Cartesian coordinates @var{x}, @var{y}, and @var{z}. 4269 4270The call @code{view (2)} sets the viewpoint to @w{@var{azimuth} = 0} 4271and @w{@var{elevation} = 90}, which is the default for 2-D graphs. 4272 4273The call @code{view (3)} sets the viewpoint to @w{@var{azimuth} = -37.5} 4274and @w{@var{elevation} = 30}, which is the default for 3-D graphs. 4275 4276If the first argument @var{hax} is an axes handle, then operate on 4277this axes rather than the current axes returned by @code{gca}. 4278 4279If no inputs are given, return the current @var{azimuth} and 4280@var{elevation}. 4281@end deftypefn 4282 4283 4284@c camlookat scripts/plot/appearance/camlookat.m 4285@anchor{XREFcamlookat} 4286@deftypefn {} {} camlookat () 4287@deftypefnx {} {} camlookat (@var{h}) 4288@deftypefnx {} {} camlookat (@var{handle_list}) 4289@deftypefnx {} {} camlookat (@var{hax}) 4290Move the camera and adjust its properties to look at objects. 4291 4292When the input is a handle @var{h}, the camera is set to point toward the 4293center of the bounding box of @var{h}. The camera's position is adjusted so 4294the bounding box approximately fills the field of view. 4295 4296This command fixes the camera's viewing direction 4297(@code{camtarget() - campos()}), camera up vector (@pxref{XREFcamup,,camup}) 4298and viewing angle (@pxref{XREFcamva,,camva}). The camera target 4299(@pxref{XREFcamtarget,,camtarget}) and camera position 4300(@pxref{XREFcampos,,campos}) are changed. 4301 4302 4303If the argument is a list @var{handle_list}, then a single bounding box for 4304all the objects is computed and the camera is then adjusted as above. 4305 4306If the argument is an axis object @var{hax}, then the children of the axis 4307are used as @var{handle_list}. When called with no inputs, it uses the 4308current axis (@pxref{XREFgca,,gca}). 4309 4310@xseealso{@ref{XREFcamorbit,,camorbit}, @ref{XREFcamzoom,,camzoom}, @ref{XREFcamroll,,camroll}} 4311@end deftypefn 4312 4313 4314@c campos scripts/plot/appearance/campos.m 4315@anchor{XREFcampos} 4316@deftypefn {} {@var{P} =} campos () 4317@deftypefnx {} {} campos ([@var{x} @var{y} @var{z}]) 4318@deftypefnx {} {@var{mode} =} campos ("mode") 4319@deftypefnx {} {} campos (@var{mode}) 4320@deftypefnx {} {} campos (@var{ax}, @dots{}) 4321Set or get the camera position. 4322 4323The default camera position is determined automatically based on the scene. 4324For example, to get the camera position: 4325 4326@example 4327@group 4328hf = figure(); 4329peaks() 4330p = campos () 4331 @result{} p = 4332 -27.394 -35.701 64.079 4333@end group 4334@end example 4335 4336We can then move the camera further up the z-axis: 4337 4338@example 4339@group 4340campos (p + [0 0 10]) 4341campos () 4342 @result{} ans = 4343 -27.394 -35.701 74.079 4344@end group 4345@end example 4346 4347Having made that change, the camera position @var{mode} is now manual: 4348 4349@example 4350@group 4351campos ("mode") 4352 @result{} manual 4353@end group 4354@end example 4355 4356We can set it back to automatic: 4357 4358@example 4359@group 4360campos ("auto") 4361campos () 4362 @result{} ans = 4363 -27.394 -35.701 64.079 4364close (hf) 4365@end group 4366@end example 4367 4368By default, these commands affect the current axis; alternatively, an axis 4369can be specified by the optional argument @var{ax}. 4370 4371@xseealso{@ref{XREFcamup,,camup}, @ref{XREFcamtarget,,camtarget}, @ref{XREFcamva,,camva}} 4372@end deftypefn 4373 4374 4375@c camorbit scripts/plot/appearance/camorbit.m 4376@anchor{XREFcamorbit} 4377@deftypefn {} {} camorbit (@var{theta}, @var{phi}) 4378@deftypefnx {} {} camorbit (@var{theta}, @var{phi}, @var{coorsys}) 4379@deftypefnx {} {} camorbit (@var{theta}, @var{phi}, @var{coorsys}, @var{dir}) 4380@deftypefnx {} {} camorbit (@var{theta}, @var{phi}, "data") 4381@deftypefnx {} {} camorbit (@var{theta}, @var{phi}, "data", "z") 4382@deftypefnx {} {} camorbit (@var{theta}, @var{phi}, "data", "x") 4383@deftypefnx {} {} camorbit (@var{theta}, @var{phi}, "data", "y") 4384@deftypefnx {} {} camorbit (@var{theta}, @var{phi}, "data", [@var{x} @var{y} @var{z}]) 4385@deftypefnx {} {} camorbit (@var{theta}, @var{phi}, "camera") 4386@deftypefnx {} {} camorbit (@var{hax}, @dots{}) 4387Rotate the camera up/down and left/right around its target. 4388 4389Move the camera @var{phi} degrees up and @var{theta} degrees to the right, 4390as if it were in an orbit around its target. 4391Example: 4392 4393@example 4394@group 4395@c doctest: +SKIP 4396sphere () 4397camorbit (30, 20) 4398@end group 4399@end example 4400 4401These rotations are centered around the camera target 4402(@pxref{XREFcamtarget,,camtarget}). 4403First the camera position is pitched up or down by rotating it @var{phi} 4404degrees around an axis orthogonal to both the viewing direction 4405(specifically @code{camtarget() - campos()}) and the camera ``up vector'' 4406(@pxref{XREFcamup,,camup}). 4407Example: 4408 4409@example 4410@group 4411@c doctest: +SKIP 4412camorbit (0, 20) 4413@end group 4414@end example 4415 4416The second rotation depends on the coordinate system @var{coorsys} and 4417direction @var{dir} inputs. 4418The default for @var{coorsys} is @qcode{"data"}. In this case, the camera 4419is yawed left or right by rotating it @var{theta} degrees around an axis 4420specified by @var{dir}. 4421The default for @var{dir} is @qcode{"z"}, corresponding to the vector 4422@code{[0, 0, 1]}. 4423Example: 4424 4425@example 4426@group 4427@c doctest: +SKIP 4428camorbit (30, 0) 4429@end group 4430@end example 4431 4432When @var{coorsys} is set to @qcode{"camera"}, the camera is moved left or 4433right by rotating it around an axis parallel to the camera up vector 4434(@pxref{XREFcamup,,camup}). 4435The input @var{dir} should not be specified in this case. 4436Example: 4437 4438@example 4439@group 4440@c doctest: +SKIP 4441camorbit (30, 0, "camera") 4442@end group 4443@end example 4444 4445(Note: the rotation by @var{phi} is unaffected by @qcode{"camera"}.) 4446 4447The @code{camorbit} command modifies two camera properties: 4448@ref{XREFcampos,,campos} and @ref{XREFcamup,,camup}. 4449 4450By default, this command affects the current axis; alternatively, an axis 4451can be specified by the optional argument @var{hax}. 4452 4453@xseealso{@ref{XREFcamzoom,,camzoom}, @ref{XREFcamroll,,camroll}, @ref{XREFcamlookat,,camlookat}} 4454@end deftypefn 4455 4456 4457@c camroll scripts/plot/appearance/camroll.m 4458@anchor{XREFcamroll} 4459@deftypefn {} {} camroll (@var{theta}) 4460@deftypefnx {} {} camroll (@var{ax}, @var{theta}) 4461Roll the camera. 4462 4463Roll the camera clockwise by @var{theta} degrees. 4464For example, the following command will roll the camera by 446530 degrees clockwise (to the right); this will cause the scene 4466to appear to roll by 30 degrees to the left: 4467 4468@example 4469@group 4470@c doctest: +SKIP 4471peaks () 4472camroll (30) 4473@end group 4474@end example 4475 4476Roll the camera back: 4477 4478@example 4479@group 4480@c doctest: +SKIP 4481camroll (-30) 4482@end group 4483@end example 4484 4485The following command restores the default camera roll: 4486 4487@example 4488@group 4489@c doctest: +SKIP 4490camup ("auto") 4491@end group 4492@end example 4493 4494By default, these commands affect the current axis; alternatively, an axis 4495can be specified by the optional argument @var{ax}. 4496 4497@xseealso{@ref{XREFcamzoom,,camzoom}, @ref{XREFcamorbit,,camorbit}, @ref{XREFcamlookat,,camlookat}, @ref{XREFcamup,,camup}} 4498@end deftypefn 4499 4500 4501@c camtarget scripts/plot/appearance/camtarget.m 4502@anchor{XREFcamtarget} 4503@deftypefn {} {@var{T} =} camtarget () 4504@deftypefnx {} {} camtarget ([@var{x} @var{y} @var{z}]) 4505@deftypefnx {} {@var{mode} =} camtarget ("mode") 4506@deftypefnx {} {} camtarget (@var{mode}) 4507@deftypefnx {} {} camtarget (@var{ax}, @dots{}) 4508Set or get where the camera is pointed. 4509 4510The camera target is a point in space where the camera is pointing. 4511Usually, it is determined automatically based on the scene: 4512 4513@example 4514@group 4515hf = figure(); 4516sphere (36) 4517v = camtarget () 4518 @result{} v = 4519 0 0 0 4520@end group 4521@end example 4522 4523We can turn the camera to point at a new target: 4524 4525@example 4526@group 4527camtarget ([1 1 1]) 4528camtarget () 4529 @result{} 1 1 1 4530@end group 4531@end example 4532 4533Having done so, the camera target @var{mode} is manual: 4534 4535@example 4536@group 4537camtarget ("mode") 4538 @result{} manual 4539@end group 4540@end example 4541 4542This means, for example, adding new objects to the scene will not retarget 4543the camera: 4544 4545@example 4546@group 4547hold on; 4548peaks () 4549camtarget () 4550 @result{} 1 1 1 4551@end group 4552@end example 4553 4554We can reset it to be automatic: 4555 4556@example 4557@group 4558@c doctest: +XFAIL 4559@c https://savannah.gnu.org/bugs/?44503 4560camtarget ("auto") 4561camtarget () 4562 @result{} 0 0 0.76426 4563close (hf) 4564@end group 4565@end example 4566 4567By default, these commands affect the current axis; alternatively, an axis 4568can be specified by the optional argument @var{ax}. 4569 4570@xseealso{@ref{XREFcampos,,campos}, @ref{XREFcamup,,camup}, @ref{XREFcamva,,camva}} 4571@end deftypefn 4572 4573 4574@c camup scripts/plot/appearance/camup.m 4575@anchor{XREFcamup} 4576@deftypefn {} {@var{up} =} camup () 4577@deftypefnx {} {} camup ([@var{x} @var{y} @var{z}]) 4578@deftypefnx {} {@var{mode} =} camup ("mode") 4579@deftypefnx {} {} camup (@var{mode}) 4580@deftypefnx {} {} camup (@var{ax}, @dots{}) 4581Set or get the camera up vector. 4582 4583By default, the camera is oriented so that ``up'' corresponds to the 4584positive z-axis: 4585 4586@example 4587@group 4588hf = figure (); 4589sphere (36) 4590v = camup () 4591 @result{} v = 4592 0 0 1 4593@end group 4594@end example 4595 4596Specifying a new ``up vector'' rolls the camera and sets the mode to manual: 4597 4598@example 4599@group 4600camup ([1 1 0]) 4601camup () 4602 @result{} 1 1 0 4603camup ("mode") 4604 @result{} manual 4605@end group 4606@end example 4607 4608Modifying the up vector does not modify the camera target 4609(@pxref{XREFcamtarget,,camtarget}). Thus, the camera up vector might not be 4610orthogonal to the direction of the camera's view: 4611 4612@example 4613@group 4614camup ([1 2 3]) 4615dot (camup (), camtarget () - campos ()) 4616 @result{} 6... 4617@end group 4618@end example 4619 4620A consequence is that ``pulling back'' on the up vector does not pitch the 4621camera view (as that would require changing the target). Setting the up 4622vector is thus typically used only to roll the camera. A more intuitive 4623command for this purpose is @ref{XREFcamroll,,camroll}. 4624 4625Finally, we can reset the up vector to automatic mode: 4626 4627@example 4628@group 4629camup ("auto") 4630camup () 4631 @result{} 0 0 1 4632close (hf) 4633@end group 4634@end example 4635 4636By default, these commands affect the current axis; alternatively, an axis 4637can be specified by the optional argument @var{ax}. 4638 4639@xseealso{@ref{XREFcampos,,campos}, @ref{XREFcamtarget,,camtarget}, @ref{XREFcamva,,camva}} 4640@end deftypefn 4641 4642 4643@c camva scripts/plot/appearance/camva.m 4644@anchor{XREFcamva} 4645@deftypefn {} {@var{a} =} camva () 4646@deftypefnx {} {} camva (@var{a}) 4647@deftypefnx {} {@var{mode} =} camva ("mode") 4648@deftypefnx {} {} camva (@var{mode}) 4649@deftypefnx {} {} camva (@var{ax}, @dots{}) 4650Set or get the camera viewing angle. 4651 4652The camera has a viewing angle which determines how much can be seen. By 4653default this is: 4654 4655@example 4656@group 4657hf = figure(); 4658sphere (36) 4659a = camva () 4660 @result{} a = 10.340 4661@end group 4662@end example 4663 4664To get a wider-angle view, we could double the viewing angle. This will 4665also set the mode to manual: 4666 4667@example 4668@group 4669camva (2*a) 4670camva ("mode") 4671 @result{} manual 4672@end group 4673@end example 4674 4675We can set it back to automatic: 4676 4677@example 4678@group 4679camva ("auto") 4680camva ("mode") 4681 @result{} auto 4682camva () 4683 @result{} ans = 10.340 4684close (hf) 4685@end group 4686@end example 4687 4688By default, these commands affect the current axis; alternatively, an axis 4689can be specified by the optional argument @var{ax}. 4690 4691@xseealso{@ref{XREFcampos,,campos}, @ref{XREFcamtarget,,camtarget}, @ref{XREFcamup,,camup}} 4692@end deftypefn 4693 4694 4695@c camzoom scripts/plot/appearance/camzoom.m 4696@anchor{XREFcamzoom} 4697@deftypefn {} {} camzoom (@var{zf}) 4698@deftypefnx {} {} camzoom (@var{ax}, @var{zf}) 4699Zoom the camera in or out. 4700 4701A value of @var{zf} larger than 1 ``zooms in'' such that the scene appears 4702magnified: 4703 4704@example 4705@group 4706hf = figure (); 4707sphere (36) 4708camzoom (1.2) 4709@end group 4710@end example 4711 4712A value smaller than 1 ``zooms out'' so the camera can see more of the 4713scene: 4714 4715@example 4716@group 4717camzoom (0.5) 4718@end group 4719@end example 4720 4721Technically speaking, zooming affects the ``viewing angle''. The following 4722command resets to the default zoom: 4723 4724@example 4725@group 4726camva ("auto") 4727close (hf) 4728@end group 4729@end example 4730 4731By default, these commands affect the current axis; alternatively, an axis 4732can be specified by the optional argument @var{ax}. 4733 4734@xseealso{@ref{XREFcamroll,,camroll}, @ref{XREFcamorbit,,camorbit}, @ref{XREFcamlookat,,camlookat}, @ref{XREFcamva,,camva}} 4735@end deftypefn 4736 4737 4738@c slice scripts/plot/draw/slice.m 4739@anchor{XREFslice} 4740@deftypefn {} {} slice (@var{x}, @var{y}, @var{z}, @var{v}, @var{sx}, @var{sy}, @var{sz}) 4741@deftypefnx {} {} slice (@var{x}, @var{y}, @var{z}, @var{v}, @var{xi}, @var{yi}, @var{zi}) 4742@deftypefnx {} {} slice (@var{v}, @var{sx}, @var{sy}, @var{sz}) 4743@deftypefnx {} {} slice (@var{v}, @var{xi}, @var{yi}, @var{zi}) 4744@deftypefnx {} {} slice (@dots{}, @var{method}) 4745@deftypefnx {} {} slice (@var{hax}, @dots{}) 4746@deftypefnx {} {@var{h} =} slice (@dots{}) 4747Plot slices of 3-D data/scalar fields. 4748 4749Each element of the 3-dimensional array @var{v} represents a scalar value at 4750a location given by the parameters @var{x}, @var{y}, and @var{z}. The 4751parameters @var{x}, @var{x}, and @var{z} are either 3-dimensional arrays of 4752the same size as the array @var{v} in the @qcode{"meshgrid"} format or 4753vectors. The parameters @var{xi}, etc.@: respect a similar format to 4754@var{x}, etc., and they represent the points at which the array @var{vi} 4755is interpolated using interp3. The vectors @var{sx}, @var{sy}, and 4756@var{sz} contain points of orthogonal slices of the respective axes. 4757 4758If @var{x}, @var{y}, @var{z} are omitted, they are assumed to be 4759@code{x = 1:size (@var{v}, 2)}, @code{y = 1:size (@var{v}, 1)} and 4760@code{z = 1:size (@var{v}, 3)}. 4761 4762@var{method} is one of: 4763 4764@table @asis 4765@item @qcode{"nearest"} 4766Return the nearest neighbor. 4767 4768@item @qcode{"linear"} 4769Linear interpolation from nearest neighbors. 4770 4771@item @qcode{"cubic"} 4772Cubic interpolation from four nearest neighbors (not implemented yet). 4773 4774@item @qcode{"spline"} 4775Cubic spline interpolation---smooth first and second derivatives 4776throughout the curve. 4777@end table 4778 4779The default method is @qcode{"linear"}. 4780 4781If the first argument @var{hax} is an axes handle, then plot into this axes, 4782rather than the current axes returned by @code{gca}. 4783 4784The optional return value @var{h} is a graphics handle to the created 4785surface object. 4786 4787Examples: 4788 4789@example 4790@group 4791[x, y, z] = meshgrid (linspace (-8, 8, 32)); 4792v = sin (sqrt (x.^2 + y.^2 + z.^2)) ./ (sqrt (x.^2 + y.^2 + z.^2)); 4793slice (x, y, z, v, [], 0, []); 4794 4795[xi, yi] = meshgrid (linspace (-7, 7)); 4796zi = xi + yi; 4797slice (x, y, z, v, xi, yi, zi); 4798@end group 4799@end example 4800@xseealso{@ref{XREFinterp3,,interp3}, @ref{XREFsurface,,surface}, @ref{XREFpcolor,,pcolor}} 4801@end deftypefn 4802 4803 4804@c ribbon scripts/plot/draw/ribbon.m 4805@anchor{XREFribbon} 4806@deftypefn {} {} ribbon (@var{y}) 4807@deftypefnx {} {} ribbon (@var{x}, @var{y}) 4808@deftypefnx {} {} ribbon (@var{x}, @var{y}, @var{width}) 4809@deftypefnx {} {} ribbon (@var{hax}, @dots{}) 4810@deftypefnx {} {@var{h} =} ribbon (@dots{}) 4811Draw a ribbon plot for the columns of @var{y} vs. @var{x}. 4812 4813If @var{x} is omitted, a vector containing the row numbers is assumed 4814(@code{1:rows (Y)}). Alternatively, @var{x} can also be a vector with 4815same number of elements as rows of @var{y} in which case the same 4816@var{x} is used for each column of @var{y}. 4817 4818The optional parameter @var{width} specifies the width of a single ribbon 4819(default is 0.75). 4820 4821If the first argument @var{hax} is an axes handle, then plot into this axes, 4822rather than the current axes returned by @code{gca}. 4823 4824The optional return value @var{h} is a vector of graphics handles to 4825the surface objects representing each ribbon. 4826@xseealso{@ref{XREFsurface,,surface}, @ref{XREFwaterfall,,waterfall}} 4827@end deftypefn 4828 4829 4830@c shading scripts/plot/appearance/shading.m 4831@anchor{XREFshading} 4832@deftypefn {} {} shading (@var{type}) 4833@deftypefnx {} {} shading (@var{hax}, @var{type}) 4834Set the shading of patch or surface graphic objects. 4835 4836Valid arguments for @var{type} are 4837 4838@table @asis 4839@item @qcode{"flat"} 4840Single colored patches with invisible edges. 4841 4842@item @qcode{"faceted"} 4843Single colored patches with black edges. 4844 4845@item @qcode{"interp"} 4846Colors between patch vertices are interpolated and the patch edges are 4847invisible. 4848@end table 4849 4850If the first argument @var{hax} is an axes handle, then plot into this axes, 4851rather than the current axes returned by @code{gca}. 4852@xseealso{@ref{XREFfill,,fill}, @ref{XREFmesh,,mesh}, @ref{XREFpatch,,patch}, @ref{XREFpcolor,,pcolor}, @ref{XREFsurf,,surf}, @ref{XREFsurface,,surface}, @ref{XREFhidden,,hidden}, @ref{XREFlighting,,lighting}} 4853@end deftypefn 4854 4855 4856@c scatter3 scripts/plot/draw/scatter3.m 4857@anchor{XREFscatter3} 4858@deftypefn {} {} scatter3 (@var{x}, @var{y}, @var{z}) 4859@deftypefnx {} {} scatter3 (@var{x}, @var{y}, @var{z}, @var{s}) 4860@deftypefnx {} {} scatter3 (@var{x}, @var{y}, @var{z}, @var{s}, @var{c}) 4861@deftypefnx {} {} scatter3 (@dots{}, @var{style}) 4862@deftypefnx {} {} scatter3 (@dots{}, "filled") 4863@deftypefnx {} {} scatter3 (@dots{}, @var{prop}, @var{val}) 4864@deftypefnx {} {} scatter3 (@var{hax}, @dots{}) 4865@deftypefnx {} {@var{h} =} scatter3 (@dots{}) 4866Draw a 3-D scatter plot. 4867 4868A marker is plotted at each point defined by the coordinates in the vectors 4869@var{x}, @var{y}, and @var{z}. 4870 4871The size of the markers is determined by @var{s}, which can be a scalar 4872or a vector of the same length as @var{x}, @var{y}, and @var{z}. If @var{s} 4873is not given, or is an empty matrix, then a default value of 8 points is 4874used. 4875 4876The color of the markers is determined by @var{c}, which can be a string 4877defining a fixed color; a 3-element vector giving the red, green, and blue 4878components of the color; a vector of the same length as @var{x} that gives 4879a scaled index into the current colormap; or an @nospell{Nx3} matrix 4880defining the RGB color of each marker individually. 4881 4882The marker to use can be changed with the @var{style} argument, that is a 4883string defining a marker in the same manner as the @code{plot} command. 4884If no marker is specified it defaults to @qcode{"o"} or circles. 4885If the argument @qcode{"filled"} is given then the markers are filled. 4886 4887Additional property/value pairs are passed directly to the underlying 4888patch object. The full list of properties is documented at 4889@ref{Patch Properties}. 4890 4891If the first argument @var{hax} is an axes handle, then plot into this axes, 4892rather than the current axes returned by @code{gca}. 4893 4894The optional return value @var{h} is a graphics handle to the hggroup 4895object representing the points. 4896 4897@example 4898@group 4899[x, y, z] = peaks (20); 4900scatter3 (x(:), y(:), z(:), [], z(:)); 4901@end group 4902@end example 4903 4904@xseealso{@ref{XREFscatter,,scatter}, @ref{XREFpatch,,patch}, @ref{XREFplot,,plot}} 4905@end deftypefn 4906 4907 4908@c waterfall scripts/plot/draw/waterfall.m 4909@anchor{XREFwaterfall} 4910@deftypefn {} {} waterfall (@var{x}, @var{y}, @var{z}) 4911@deftypefnx {} {} waterfall (@var{z}) 4912@deftypefnx {} {} waterfall (@dots{}, @var{c}) 4913@deftypefnx {} {} waterfall (@dots{}, @var{prop}, @var{val}, @dots{}) 4914@deftypefnx {} {} waterfall (@var{hax}, @dots{}) 4915@deftypefnx {} {@var{h} =} waterfall (@dots{}) 4916Plot a 3-D waterfall plot. 4917 4918A waterfall plot is similar to a @code{meshz} plot except only 4919mesh lines for the rows of @var{z} (x-values) are shown. 4920 4921The wireframe mesh is plotted using rectangles. The vertices of the 4922rectangles [@var{x}, @var{y}] are typically the output of @code{meshgrid}. 4923over a 2-D rectangular region in the x-y plane. @var{z} determines the 4924height above the plane of each vertex. If only a single @var{z} matrix is 4925given, then it is plotted over the meshgrid 4926@code{@var{x} = 1:columns (@var{z}), @var{y} = 1:rows (@var{z})}. 4927Thus, columns of @var{z} correspond to different @var{x} values and rows 4928of @var{z} correspond to different @var{y} values. 4929 4930The color of the mesh is computed by linearly scaling the @var{z} values 4931to fit the range of the current colormap. Use @code{caxis} and/or 4932change the colormap to control the appearance. 4933 4934Optionally the color of the mesh can be specified independently of @var{z} 4935by supplying a color matrix, @var{c}. 4936 4937Any property/value pairs are passed directly to the underlying surface 4938object. The full list of properties is documented at 4939@ref{Surface Properties}. 4940 4941If the first argument @var{hax} is an axes handle, then plot into this axes, 4942rather than the current axes returned by @code{gca}. 4943 4944The optional return value @var{h} is a graphics handle to the created 4945surface object. 4946 4947@xseealso{@ref{XREFmeshz,,meshz}, @ref{XREFmesh,,mesh}, @ref{XREFmeshc,,meshc}, @ref{XREFcontour,,contour}, @ref{XREFsurf,,surf}, @ref{XREFsurface,,surface}, @ref{XREFribbon,,ribbon}, @ref{XREFmeshgrid,,meshgrid}, @ref{XREFhidden,,hidden}, @ref{XREFshading,,shading}, @ref{XREFcolormap,,colormap}, @ref{XREFcaxis,,caxis}} 4948@end deftypefn 4949 4950 4951@menu 4952* Aspect Ratio:: 4953* Three-dimensional Function Plotting:: 4954* Three-dimensional Geometric Shapes:: 4955@end menu 4956 4957@node Aspect Ratio 4958@subsubsection Aspect Ratio 4959 4960For three-dimensional plots the aspect ratio can be set for data with 4961@code{daspect} and for the plot box with @code{pbaspect}. 4962@xref{Axis Configuration}, for controlling the x-, y-, and z-limits for 4963plotting. 4964 4965@c daspect scripts/plot/appearance/daspect.m 4966@anchor{XREFdaspect} 4967@deftypefn {} {@var{data_aspect_ratio} =} daspect () 4968@deftypefnx {} {} daspect (@var{data_aspect_ratio}) 4969@deftypefnx {} {} daspect (@var{mode}) 4970@deftypefnx {} {@var{data_aspect_ratio_mode} =} daspect ("mode") 4971@deftypefnx {} {} daspect (@var{hax}, @dots{}) 4972Query or set the data aspect ratio of the current axes. 4973 4974The aspect ratio is a normalized 3-element vector representing the span of 4975the x, y, and z-axis limits. 4976 4977@code{daspect (@var{mode})} 4978 4979Set the data aspect ratio mode of the current axes. @var{mode} is 4980either @qcode{"auto"} or @qcode{"manual"}. 4981 4982@code{daspect (@qcode{"mode"})} 4983 4984Return the data aspect ratio mode of the current axes. 4985 4986@code{daspect (@var{hax}, @dots{})} 4987 4988Operate on the axes in handle @var{hax} instead of the current axes. 4989 4990@xseealso{@ref{XREFaxis,,axis}, @ref{XREFpbaspect,,pbaspect}, @ref{XREFxlim,,xlim}, @ref{XREFylim,,ylim}, @ref{XREFzlim,,zlim}} 4991@end deftypefn 4992 4993 4994@c pbaspect scripts/plot/appearance/pbaspect.m 4995@anchor{XREFpbaspect} 4996@deftypefn {} {@var{plot_box_aspect_ratio} =} pbaspect ( ) 4997@deftypefnx {} {} pbaspect (@var{plot_box_aspect_ratio}) 4998@deftypefnx {} {} pbaspect (@var{mode}) 4999@deftypefnx {} {@var{plot_box_aspect_ratio_mode} =} pbaspect ("mode") 5000@deftypefnx {} {} pbaspect (@var{hax}, @dots{}) 5001 5002Query or set the plot box aspect ratio of the current axes. 5003 5004The aspect ratio is a normalized 3-element vector representing the rendered 5005lengths of the x, y, and z axes. 5006 5007@code{pbaspect(@var{mode})} 5008 5009Set the plot box aspect ratio mode of the current axes. @var{mode} is 5010either @qcode{"auto"} or @qcode{"manual"}. 5011 5012@code{pbaspect ("mode")} 5013 5014Return the plot box aspect ratio mode of the current axes. 5015 5016@code{pbaspect (@var{hax}, @dots{})} 5017 5018Operate on the axes in handle @var{hax} instead of the current axes. 5019 5020@xseealso{@ref{XREFaxis,,axis}, @ref{XREFdaspect,,daspect}, @ref{XREFxlim,,xlim}, @ref{XREFylim,,ylim}, @ref{XREFzlim,,zlim}} 5021@end deftypefn 5022 5023 5024@node Three-dimensional Function Plotting 5025@subsubsection Three-dimensional Function Plotting 5026 5027@c ezplot3 scripts/plot/draw/ezplot3.m 5028@anchor{XREFezplot3} 5029@deftypefn {} {} ezplot3 (@var{fx}, @var{fy}, @var{fz}) 5030@deftypefnx {} {} ezplot3 (@dots{}, @var{dom}) 5031@deftypefnx {} {} ezplot3 (@dots{}, @var{n}) 5032@deftypefnx {} {} ezplot3 (@dots{}, "animate") 5033@deftypefnx {} {} ezplot3 (@var{hax}, @dots{}) 5034@deftypefnx {} {@var{h} =} ezplot3 (@dots{}) 5035 5036Plot a parametrically defined curve in three dimensions. 5037 5038@var{fx}, @var{fy}, and @var{fz} are strings, inline functions, 5039or function handles with one argument defining the function. By 5040default the plot is over the domain @code{0 <= @var{t} <= 2*pi} 5041with 500 points. 5042 5043If @var{dom} is a two element vector, it represents the minimum and maximum 5044values of @var{t}. 5045 5046@var{n} is a scalar defining the number of points to use in plotting the 5047function. 5048 5049If the @qcode{"animate"} option is given then the plotting is animated 5050in the style of @code{comet3}. 5051 5052If the first argument @var{hax} is an axes handle, then plot into this axes, 5053rather than the current axes returned by @code{gca}. 5054 5055The optional return value @var{h} is a graphics handle to the created plot. 5056 5057@example 5058@group 5059fx = @@(t) cos (t); 5060fy = @@(t) sin (t); 5061fz = @@(t) t; 5062ezplot3 (fx, fy, fz, [0, 10*pi], 100); 5063@end group 5064@end example 5065 5066@xseealso{@ref{XREFplot3,,plot3}, @ref{XREFcomet3,,comet3}, @ref{XREFezplot,,ezplot}, @ref{XREFezmesh,,ezmesh}, @ref{XREFezsurf,,ezsurf}} 5067@end deftypefn 5068 5069 5070@c ezmesh scripts/plot/draw/ezmesh.m 5071@anchor{XREFezmesh} 5072@deftypefn {} {} ezmesh (@var{f}) 5073@deftypefnx {} {} ezmesh (@var{fx}, @var{fy}, @var{fz}) 5074@deftypefnx {} {} ezmesh (@dots{}, @var{dom}) 5075@deftypefnx {} {} ezmesh (@dots{}, @var{n}) 5076@deftypefnx {} {} ezmesh (@dots{}, "circ") 5077@deftypefnx {} {} ezmesh (@var{hax}, @dots{}) 5078@deftypefnx {} {@var{h} =} ezmesh (@dots{}) 5079 5080Plot the mesh defined by a function. 5081 5082@var{f} is a string, inline function, or function handle with two arguments 5083defining the function. By default the plot is over the meshed domain 5084@code{-2*pi <= @var{x} | @var{y} <= 2*pi} with 60 points in each dimension. 5085 5086If three functions are passed, then plot the parametrically defined 5087function @code{[@var{fx}(@var{s}, @var{t}), @var{fy}(@var{s}, @var{t}), 5088@var{fz}(@var{s}, @var{t})]}. 5089 5090If @var{dom} is a two element vector, it represents the minimum and maximum 5091values of both @var{x} and @var{y}. If @var{dom} is a four element vector, 5092then the minimum and maximum values are @code{[xmin xmax ymin ymax]}. 5093 5094@var{n} is a scalar defining the number of points to use in each dimension. 5095 5096If the argument @qcode{"circ"} is given, then the function is plotted over 5097a disk centered on the middle of the domain @var{dom}. 5098 5099If the first argument @var{hax} is an axes handle, then plot into this axes, 5100rather than the current axes returned by @code{gca}. 5101 5102The optional return value @var{h} is a graphics handle to the created 5103surface object. 5104 5105Example 1: 2-argument function 5106 5107@example 5108@group 5109f = @@(x,y) sqrt (abs (x .* y)) ./ (1 + x.^2 + y.^2); 5110ezmesh (f, [-3, 3]); 5111@end group 5112@end example 5113 5114Example 2: parametrically defined function 5115 5116@example 5117@group 5118fx = @@(s,t) cos (s) .* cos (t); 5119fy = @@(s,t) sin (s) .* cos (t); 5120fz = @@(s,t) sin (t); 5121ezmesh (fx, fy, fz, [-pi, pi, -pi/2, pi/2], 20); 5122@end group 5123@end example 5124 5125@xseealso{@ref{XREFmesh,,mesh}, @ref{XREFezmeshc,,ezmeshc}, @ref{XREFezplot,,ezplot}, @ref{XREFezsurf,,ezsurf}, @ref{XREFezsurfc,,ezsurfc}, @ref{XREFhidden,,hidden}} 5126@end deftypefn 5127 5128 5129@c ezmeshc scripts/plot/draw/ezmeshc.m 5130@anchor{XREFezmeshc} 5131@deftypefn {} {} ezmeshc (@var{f}) 5132@deftypefnx {} {} ezmeshc (@var{fx}, @var{fy}, @var{fz}) 5133@deftypefnx {} {} ezmeshc (@dots{}, @var{dom}) 5134@deftypefnx {} {} ezmeshc (@dots{}, @var{n}) 5135@deftypefnx {} {} ezmeshc (@dots{}, "circ") 5136@deftypefnx {} {} ezmeshc (@var{hax}, @dots{}) 5137@deftypefnx {} {@var{h} =} ezmeshc (@dots{}) 5138 5139Plot the mesh and contour lines defined by a function. 5140 5141@var{f} is a string, inline function, or function handle with two arguments 5142defining the function. By default the plot is over the meshed domain 5143@code{-2*pi <= @var{x} | @var{y} <= 2*pi} with 60 points in each dimension. 5144 5145If three functions are passed, then plot the parametrically defined 5146function @code{[@var{fx}(@var{s}, @var{t}), @var{fy}(@var{s}, @var{t}), 5147@var{fz}(@var{s}, @var{t})]}. 5148 5149If @var{dom} is a two element vector, it represents the minimum and maximum 5150values of both @var{x} and @var{y}. If @var{dom} is a four element vector, 5151then the minimum and maximum values are @code{[xmin xmax ymin ymax]}. 5152 5153@var{n} is a scalar defining the number of points to use in each dimension. 5154 5155If the argument @qcode{"circ"} is given, then the function is plotted over 5156a disk centered on the middle of the domain @var{dom}. 5157 5158If the first argument @var{hax} is an axes handle, then plot into this axes, 5159rather than the current axes returned by @code{gca}. 5160 5161The optional return value @var{h} is a 2-element vector with a graphics 5162handle for the created mesh plot and a second handle for the created contour 5163plot. 5164 5165Example: 2-argument function 5166 5167@example 5168@group 5169f = @@(x,y) sqrt (abs (x .* y)) ./ (1 + x.^2 + y.^2); 5170ezmeshc (f, [-3, 3]); 5171@end group 5172@end example 5173 5174@xseealso{@ref{XREFmeshc,,meshc}, @ref{XREFezmesh,,ezmesh}, @ref{XREFezplot,,ezplot}, @ref{XREFezsurf,,ezsurf}, @ref{XREFezsurfc,,ezsurfc}, @ref{XREFhidden,,hidden}} 5175@end deftypefn 5176 5177 5178@c ezsurf scripts/plot/draw/ezsurf.m 5179@anchor{XREFezsurf} 5180@deftypefn {} {} ezsurf (@var{f}) 5181@deftypefnx {} {} ezsurf (@var{fx}, @var{fy}, @var{fz}) 5182@deftypefnx {} {} ezsurf (@dots{}, @var{dom}) 5183@deftypefnx {} {} ezsurf (@dots{}, @var{n}) 5184@deftypefnx {} {} ezsurf (@dots{}, "circ") 5185@deftypefnx {} {} ezsurf (@var{hax}, @dots{}) 5186@deftypefnx {} {@var{h} =} ezsurf (@dots{}) 5187 5188Plot the surface defined by a function. 5189 5190@var{f} is a string, inline function, or function handle with two arguments 5191defining the function. By default the plot is over the meshed domain 5192@code{-2*pi <= @var{x} | @var{y} <= 2*pi} with 60 points in each dimension. 5193 5194If three functions are passed, then plot the parametrically defined 5195function @code{[@var{fx}(@var{s}, @var{t}), @var{fy}(@var{s}, @var{t}), 5196@var{fz}(@var{s}, @var{t})]}. 5197 5198If @var{dom} is a two element vector, it represents the minimum and maximum 5199values of both @var{x} and @var{y}. If @var{dom} is a four element vector, 5200then the minimum and maximum values are @code{[xmin xmax ymin ymax]}. 5201 5202@var{n} is a scalar defining the number of points to use in each dimension. 5203 5204If the argument @qcode{"circ"} is given, then the function is plotted over 5205a disk centered on the middle of the domain @var{dom}. 5206 5207If the first argument @var{hax} is an axes handle, then plot into this axes, 5208rather than the current axes returned by @code{gca}. 5209 5210The optional return value @var{h} is a graphics handle to the created 5211surface object. 5212 5213Example 1: 2-argument function 5214 5215@example 5216@group 5217f = @@(x,y) sqrt (abs (x .* y)) ./ (1 + x.^2 + y.^2); 5218ezsurf (f, [-3, 3]); 5219@end group 5220@end example 5221 5222Example 2: parametrically defined function 5223 5224@example 5225@group 5226fx = @@(s,t) cos (s) .* cos (t); 5227fy = @@(s,t) sin (s) .* cos (t); 5228fz = @@(s,t) sin (t); 5229ezsurf (fx, fy, fz, [-pi, pi, -pi/2, pi/2], 20); 5230@end group 5231@end example 5232 5233@xseealso{@ref{XREFsurf,,surf}, @ref{XREFezsurfc,,ezsurfc}, @ref{XREFezplot,,ezplot}, @ref{XREFezmesh,,ezmesh}, @ref{XREFezmeshc,,ezmeshc}, @ref{XREFshading,,shading}} 5234@end deftypefn 5235 5236 5237@c ezsurfc scripts/plot/draw/ezsurfc.m 5238@anchor{XREFezsurfc} 5239@deftypefn {} {} ezsurfc (@var{f}) 5240@deftypefnx {} {} ezsurfc (@var{fx}, @var{fy}, @var{fz}) 5241@deftypefnx {} {} ezsurfc (@dots{}, @var{dom}) 5242@deftypefnx {} {} ezsurfc (@dots{}, @var{n}) 5243@deftypefnx {} {} ezsurfc (@dots{}, "circ") 5244@deftypefnx {} {} ezsurfc (@var{hax}, @dots{}) 5245@deftypefnx {} {@var{h} =} ezsurfc (@dots{}) 5246 5247Plot the surface and contour lines defined by a function. 5248 5249@var{f} is a string, inline function, or function handle with two arguments 5250defining the function. By default the plot is over the meshed domain 5251@code{-2*pi <= @var{x} | @var{y} <= 2*pi} with 60 points in each dimension. 5252 5253If three functions are passed, then plot the parametrically defined 5254function @code{[@var{fx}(@var{s}, @var{t}), @var{fy}(@var{s}, @var{t}), 5255@var{fz}(@var{s}, @var{t})]}. 5256 5257If @var{dom} is a two element vector, it represents the minimum and maximum 5258values of both @var{x} and @var{y}. If @var{dom} is a four element vector, 5259then the minimum and maximum values are @code{[xmin xmax ymin ymax]}. 5260 5261@var{n} is a scalar defining the number of points to use in each dimension. 5262 5263If the argument @qcode{"circ"} is given, then the function is plotted over 5264a disk centered on the middle of the domain @var{dom}. 5265 5266If the first argument @var{hax} is an axes handle, then plot into this axes, 5267rather than the current axes returned by @code{gca}. 5268 5269The optional return value @var{h} is a 2-element vector with a graphics 5270handle for the created surface plot and a second handle for the created 5271contour plot. 5272 5273Example: 5274 5275@example 5276@group 5277f = @@(x,y) sqrt (abs (x .* y)) ./ (1 + x.^2 + y.^2); 5278ezsurfc (f, [-3, 3]); 5279@end group 5280@end example 5281 5282@xseealso{@ref{XREFsurfc,,surfc}, @ref{XREFezsurf,,ezsurf}, @ref{XREFezplot,,ezplot}, @ref{XREFezmesh,,ezmesh}, @ref{XREFezmeshc,,ezmeshc}, @ref{XREFshading,,shading}} 5283@end deftypefn 5284 5285 5286@node Three-dimensional Geometric Shapes 5287@subsubsection Three-dimensional Geometric Shapes 5288 5289@c cylinder scripts/plot/draw/cylinder.m 5290@anchor{XREFcylinder} 5291@deftypefn {} {} cylinder 5292@deftypefnx {} {} cylinder (@var{r}) 5293@deftypefnx {} {} cylinder (@var{r}, @var{n}) 5294@deftypefnx {} {} cylinder (@var{hax}, @dots{}) 5295@deftypefnx {} {[@var{x}, @var{y}, @var{z}] =} cylinder (@dots{}) 5296Plot a 3-D unit cylinder. 5297 5298The optional input @var{r} is a vector specifying the radius along the 5299unit z-axis. The default is [1 1] indicating radius 1 at @code{Z == 0} 5300and at @code{Z == 1}. 5301 5302The optional input @var{n} determines the number of faces around the 5303circumference of the cylinder. The default value is 20. 5304 5305If the first argument @var{hax} is an axes handle, then plot into this axes, 5306rather than the current axes returned by @code{gca}. 5307 5308If outputs are requested @code{cylinder} returns three matrices in 5309@code{meshgrid} format, such that @code{surf (@var{x}, @var{y}, @var{z})} 5310generates a unit cylinder. 5311 5312Example: 5313 5314@example 5315@group 5316[x, y, z] = cylinder (10:-1:0, 50); 5317surf (x, y, z); 5318title ("a cone"); 5319@end group 5320@end example 5321@xseealso{@ref{XREFellipsoid,,ellipsoid}, @ref{XREFrectangle,,rectangle}, @ref{XREFsphere,,sphere}} 5322@end deftypefn 5323 5324 5325@c sphere scripts/plot/draw/sphere.m 5326@anchor{XREFsphere} 5327@deftypefn {} {} sphere () 5328@deftypefnx {} {} sphere (@var{n}) 5329@deftypefnx {} {} sphere (@var{hax}, @dots{}) 5330@deftypefnx {} {[@var{x}, @var{y}, @var{z}] =} sphere (@dots{}) 5331Plot a 3-D unit sphere. 5332 5333The optional input @var{n} determines the number of faces around the 5334circumference of the sphere. The default value is 20. 5335 5336If the first argument @var{hax} is an axes handle, then plot into this axes, 5337rather than the current axes returned by @code{gca}. 5338 5339If outputs are requested @code{sphere} returns three matrices in 5340@code{meshgrid} format such that @code{surf (@var{x}, @var{y}, @var{z})} 5341generates a unit sphere. 5342 5343Example: 5344 5345@example 5346@group 5347[x, y, z] = sphere (40); 5348surf (3*x, 3*y, 3*z); 5349axis equal; 5350title ("sphere of radius 3"); 5351@end group 5352@end example 5353@xseealso{@ref{XREFcylinder,,cylinder}, @ref{XREFellipsoid,,ellipsoid}, @ref{XREFrectangle,,rectangle}} 5354@end deftypefn 5355 5356 5357@c ellipsoid scripts/plot/draw/ellipsoid.m 5358@anchor{XREFellipsoid} 5359@deftypefn {} {} ellipsoid (@var{xc}, @var{yc}, @var{zc}, @var{xr}, @var{yr}, @var{zr}, @var{n}) 5360@deftypefnx {} {} ellipsoid (@dots{}, @var{n}) 5361@deftypefnx {} {} ellipsoid (@var{hax}, @dots{}) 5362@deftypefnx {} {[@var{x}, @var{y}, @var{z}] =} ellipsoid (@dots{}) 5363Plot a 3-D ellipsoid. 5364 5365The inputs @var{xc}, @var{yc}, @var{zc} specify the center of the ellipsoid. 5366The inputs @var{xr}, @var{yr}, @var{zr} specify the semi-major axis lengths. 5367 5368The optional input @var{n} determines the number of faces around the 5369circumference of the cylinder. The default value is 20. 5370 5371If the first argument @var{hax} is an axes handle, then plot into this axes, 5372rather than the current axes returned by @code{gca}. 5373 5374If outputs are requested @code{ellipsoid} returns three matrices in 5375@code{meshgrid} format, such that @code{surf (@var{x}, @var{y}, @var{z})} 5376generates the ellipsoid. 5377@xseealso{@ref{XREFcylinder,,cylinder}, @ref{XREFrectangle,,rectangle}, @ref{XREFsphere,,sphere}} 5378@end deftypefn 5379 5380 5381@node Plot Annotations 5382@subsection Plot Annotations 5383 5384You can add titles, axis labels, legends, and arbitrary text to an 5385existing plot. For example: 5386 5387@example 5388@group 5389x = -10:0.1:10; 5390plot (x, sin (x)); 5391title ("sin(x) for x = -10:0.1:10"); 5392xlabel ("x"); 5393ylabel ("sin (x)"); 5394text (pi, 0.7, "arbitrary text"); 5395legend ("sin (x)"); 5396@end group 5397@end example 5398 5399The functions @code{grid} and @code{box} may also be used to add grid 5400and border lines to the plot. By default, the grid is off and the 5401border lines are on. 5402 5403Finally, arrows, text and rectangular or elliptic boxes can be added to 5404highlight parts of a plot using the @code{annotation} function. Those objects 5405are drawn in an invisible axes, on top of every other axes. 5406 5407@c title scripts/plot/appearance/title.m 5408@anchor{XREFtitle} 5409@deftypefn {} {} title (@var{string}) 5410@deftypefnx {} {} title (@var{string}, @var{prop}, @var{val}, @dots{}) 5411@deftypefnx {} {} title (@var{hax}, @dots{}) 5412@deftypefnx {} {@var{h} =} title (@dots{}) 5413Specify the string used as a title for the current axis. 5414 5415An optional list of @var{property}/@var{value} pairs can be used to change 5416the appearance of the created title text object. 5417 5418If the first argument @var{hax} is an axes or legend handle, then add a 5419title to this object, rather than the current axes returned by @code{gca}. 5420 5421The optional return value @var{h} is a graphics handle to the created text 5422object. 5423@xseealso{@ref{XREFxlabel,,xlabel}, @ref{XREFylabel,,ylabel}, @ref{XREFzlabel,,zlabel}, @ref{XREFtext,,text}} 5424@end deftypefn 5425 5426 5427@c legend scripts/plot/appearance/legend.m 5428@anchor{XREFlegend} 5429@deftypefn {} {} legend () 5430@deftypefnx {} {} legend @var{command} 5431@deftypefnx {} {} legend (@var{str1}, @var{str2}, @dots{}) 5432@deftypefnx {} {} legend (@var{charmat}) 5433@deftypefnx {} {} legend (@{@var{cellstr}@}) 5434@deftypefnx {} {} legend (@dots{}, @var{property}, @var{value}, @dots{}) 5435@deftypefnx {} {} legend (@var{hobjs}, @dots{}) 5436@deftypefnx {} {} legend ("@var{command}") 5437@deftypefnx {} {} legend (@var{hax}, @dots{}) 5438@deftypefnx {} {} legend (@var{hleg}, @dots{}) 5439@deftypefnx {} {@var{hleg, hplt} =} legend (@dots{}) 5440 5441Display a legend for the current axes using the specified strings as labels. 5442 5443Legend entries may be specified as individual character string arguments, 5444a character array, or a cell array of character strings. When label names 5445might be confused with legend properties, or @var{command} arguments, 5446the labels should be protected by specifying them as a cell array of 5447strings. 5448 5449If the first argument @var{hax} is an axes handle, then add a legend to this 5450axes, rather than the current axes returned by @code{gca}. 5451 5452If the first argument @var{hleg} is a legend handle, then operate on this 5453legend rather than the legend of the current axes. 5454 5455Legend labels are associated with the axes' children; The first label is 5456assigned to the first object that was plotted in the axes, the second label 5457to the next object plotted, etc. To label specific data objects, without 5458labeling all objects, provide their graphic handles in the input 5459@var{hobjs}. 5460 5461The following customizations are available using @var{command}: 5462 5463@table @asis 5464@item @qcode{"show"} 5465 Show legend on the plot 5466 5467@item @qcode{"hide"} 5468 Hide legend on the plot 5469 5470@item @qcode{"toggle"} 5471 Toggle between @qcode{"hide"} and @qcode{"show"} 5472 5473@item @qcode{"boxon"} 5474 Show a box around legend (default) 5475 5476@item @qcode{"boxoff"} 5477 Hide the box around legend 5478 5479@item @qcode{"right"} 5480 Place label text to the right of the keys (default) 5481 5482@item @qcode{"left"} 5483 Place label text to the left of the keys 5484 5485@item @qcode{"off"} 5486 Delete the legend object 5487@end table 5488 5489The @code{legend} function creates a graphics object which has various 5490properties that can be manipulated with @code{get}/@code{set}. 5491Alternatively, properties can be set directly when calling @code{legend} by 5492including @var{property}/@var{value} pairs. If using this calling form, the 5493labels must be specified as a cell array of strings. Graphics object 5494properties are documented in detail at @ref{Graphics Object Properties}. 5495 5496Following is a subset of supported legend properties: 5497@c The following table is obtained by copying the output of 5498@c genpropdoc ("legend", "", {"autoupdate", "box", "location", "numcolumns", "orientation", "string", "textcolor"}) 5499 5500@table @asis 5501 5502@item @code{autoupdate}: @qcode{"off"} | @{@qcode{"on"}@} 5503Control whether the number of legend items is updated automatically when 5504objects are added to (or deleted from) the peer axes. For example: 5505 5506@example 5507@group 5508## Create a single plot with its legend. 5509figure (); 5510plot (1:10); 5511legend ("Slope 1"); 5512## Add another plot and specify its displayname so that 5513## the legend is correctly updated. 5514hold on; 5515plot ((1:10) * 2, "displayname", "Slope 2"); 5516## Stop automatic updates for further plots. 5517legend ("autoupdate", "off"); 5518plot ((1:10) * 3); 5519@end group 5520@end example 5521 5522@item @code{box}: @qcode{"off"} | @{@qcode{"on"}@} 5523Control whether the legend has a surrounding box. 5524 5525@item @code{location}: @qcode{"best"} | @qcode{"bestoutside"} | 5526@qcode{"east"} | @qcode{"eastoutside"} | @qcode{"none"} | @qcode{"north"} | 5527@{@qcode{"northeast"}@} | @qcode{"northeastoutside"} | 5528@qcode{"northoutside"} | @qcode{"northwest"}| @qcode{"northwestoutside"} | 5529@qcode{"south"} | @qcode{"southeast"} | @qcode{"southeastoutside"} | 5530@qcode{"southoutside"} | @qcode{"southwest"} | @qcode{"southwestoutside"} | 5531@qcode{"west"} | @qcode{"westoutside"} 5532Control the location of the legend. 5533 5534@item @code{numcolumns}: scalar interger, def. @code{1} 5535Control the number of columns used in the layout of the legend items. 5536For example: 5537 5538@example 5539@group 5540figure (); 5541plot (rand (30)); 5542legend ("numcolumns", 3); 5543@end group 5544@end example 5545 5546Setting @code{numcolumns} also forces the @code{numcolumnsmode} property 5547to be set to @qcode{"manual"}. 5548 5549@item @code{orientation}: @qcode{"horizontal"} | @{@qcode{"vertical"}@} 5550Control whether the legend items are arranged vertically (column-wise) or 5551horizontally (row-wise). 5552 5553@item @code{string}: string | cell array of strings 5554List of labels for the legend items. For example: 5555 5556@example 5557@group 5558figure (); 5559plot (rand (20)); 5560## Let legend choose names automatically 5561hl = legend (); 5562## Selectively change some names 5563str = get (hl, "string"); 5564str(1:5:end) = "Garbage"; 5565set (hl, "string", str); 5566@end group 5567@end example 5568 5569@item @code{textcolor}: colorspec, def. @code{[0 0 0]} 5570Control the color of the text strings for legend item. 5571 5572@end table 5573 5574The full list of supported legend specific properties can be found at 5575@ref{Legend Properties, , Legend Properties}. 5576 5577A legend is implemented as an additional axes object with the @code{tag} 5578property set to @qcode{"legend"}. Properties of the legend object may be 5579manipulated directly by using @code{set}. 5580 5581The optional output value @var{hleg} is a handle to the legend object. 5582 5583Implementation Note: The legend label text is either provided in the call to 5584@code{legend} or is taken from the @code{DisplayName} property of the 5585graphics objects. Only data objects, such as line, patch, and surface, have 5586this property whereas axes, figures, etc.@: do not so they are never present 5587in a legend. If no labels or @code{DisplayName} properties are available, 5588then the label text is simply @qcode{"data1"}, @qcode{"data2"}, @dots{}, 5589@nospell{@qcode{"dataN"}}. 5590 5591The legend @code{FontSize} property is initially set to 90% of the axes 5592@code{FontSize} to which it is attached. Use @code{set} to override this 5593if necessary. 5594@end deftypefn 5595 5596 5597@c text scripts/plot/appearance/text.m 5598@anchor{XREFtext} 5599@deftypefn {} {} text (@var{x}, @var{y}, @var{string}) 5600@deftypefnx {} {} text (@var{x}, @var{y}, @var{z}, @var{string}) 5601@deftypefnx {} {} text (@dots{}, @var{prop}, @var{val}, @dots{}) 5602@deftypefnx {} {} text (@var{hax}, @dots{}) 5603@deftypefnx {} {@var{h} =} text (@dots{}) 5604Create a text object with text @var{string} at position @var{x}, @var{y}, 5605(@var{z}) on the current axes. 5606 5607Multiple locations can be specified if @var{x}, @var{y}, (@var{z}) are 5608vectors. Multiple strings can be specified with a character matrix or 5609a cell array of strings. 5610 5611Optional property/value pairs may be used to control the appearance of the 5612text. 5613 5614If the first argument @var{hax} is an axes handle, then add text to this 5615axes, rather than the current axes returned by @code{gca}. 5616 5617The optional return value @var{h} is a vector of graphics handles to the 5618created text objects. 5619 5620Example 1 : multi-line text via 3 different methods 5621 5622@example 5623@group 5624text (0.5, 0.8, @{"Line 1", "Line 2"@}) 5625text (0.5, 0.6, ["Line 1"; "Line 2"]) 5626text (0.5, 0.4, "Line 1\nLine 2") 5627@end group 5628@end example 5629 5630Example 2 : text at multiple locations 5631 5632@example 5633@group 5634text ([0.2, 0.2], [0.8, 0.6], "Same text at two locations") 5635text ([0.4, 0.4], [0.8, 0.6], @{"Point 1 Text", "Point 2 text"@}) 5636text ([0.6, 0.6], [0.8, 0.6], @{@{"Point 1 Line 1", "Point 1 Line 2@}, 5637 "Point 2 text"@}) 5638@end group 5639@end example 5640 5641Example 2 : adjust appearance using text properties 5642 5643@example 5644@group 5645ht = text (0.5, 0.5, "Hello World", "fontsize", 20); 5646set (ht, "color", "red"); 5647@end group 5648@end example 5649 5650Programming Notes: The full list of properties is documented at 5651@ref{Text Properties}. 5652 5653Any numeric entries in a cell array will be converted to text using 5654@code{sprintf ("%g")}. For more precise control of the appearance convert 5655any numeric entries to strings using @code{num2str}, @code{sprintf}, etc., 5656before calling @code{text}. 5657@xseealso{@ref{XREFgtext,,gtext}, @ref{XREFtitle,,title}, @ref{XREFxlabel,,xlabel}, @ref{XREFylabel,,ylabel}, @ref{XREFzlabel,,zlabel}} 5658@end deftypefn 5659 5660 5661@c Add cross-references and function index entries for other label functions. 5662@anchor{XREFylabel} 5663@anchor{XREFzlabel} 5664@findex ylabel 5665@findex zlabel 5666@c xlabel scripts/plot/appearance/xlabel.m 5667@anchor{XREFxlabel} 5668@deftypefn {} {} xlabel (@var{string}) 5669@deftypefnx {} {} xlabel (@var{string}, @var{property}, @var{val}, @dots{}) 5670@deftypefnx {} {} xlabel (@var{hax}, @dots{}) 5671@deftypefnx {} {@var{h} =} xlabel (@dots{}) 5672Specify the string used to label the x-axis of the current axis. 5673 5674An optional list of @var{property}/@var{value} pairs can be used to change 5675the properties of the created text label. 5676 5677The full list of text object properties is documented at 5678@ref{Text Properties}. 5679 5680If the first argument @var{hax} is an axes handle, then operate on 5681this axes rather than the current axes returned by @code{gca}. 5682 5683The optional return value @var{h} is a graphics handle to the created text 5684object. 5685@xseealso{@ref{XREFylabel,,ylabel}, @ref{XREFzlabel,,zlabel}, @ref{XREFdatetick,,datetick}, @ref{XREFtitle,,title}, @ref{XREFtext,,text}} 5686@end deftypefn 5687 5688 5689@c clabel scripts/plot/appearance/clabel.m 5690@anchor{XREFclabel} 5691@deftypefn {} {} clabel (@var{c}, @var{h}) 5692@deftypefnx {} {} clabel (@var{c}, @var{h}, @var{v}) 5693@deftypefnx {} {} clabel (@var{c}, @var{h}, "manual") 5694@deftypefnx {} {} clabel (@var{c}) 5695@deftypefnx {} {} clabel (@dots{}, @var{prop}, @var{val}, @dots{}) 5696@deftypefnx {} {@var{h} =} clabel (@dots{}) 5697Add labels to the contours of a contour plot. 5698 5699The contour levels are specified by the contour matrix @var{c} which is 5700returned by @code{contour}, @code{contourc}, @code{contourf}, and 5701@code{contour3}. Contour labels are rotated to match the local line 5702orientation and centered on the line. The position of labels along the 5703contour line is chosen randomly. 5704 5705If the argument @var{h} is a handle to a contour group object, then label 5706this plot rather than the one in the current axes returned by @code{gca}. 5707 5708By default, all contours are labeled. However, the contours to label can be 5709specified by the vector @var{v}. If the @qcode{"manual"} argument is 5710given then the contours to label can be selected with the mouse. 5711 5712Additional property/value pairs that are valid properties of text objects 5713can be given and are passed to the underlying text objects. Moreover, 5714the contour group property @qcode{"LabelSpacing"} is available which 5715determines the spacing between labels on a contour to be specified. The 5716default is 144 points, or 2 inches. 5717 5718The optional return value @var{h} is a vector of graphics handles to 5719the text objects representing each label. 5720The @qcode{"userdata"} property of the text objects contains the numerical 5721value of the contour label. 5722 5723The full list of text object properties is documented at 5724@ref{Text Properties}. 5725 5726@example 5727@group 5728[c, h] = contour (peaks (), -4 : 6); 5729clabel (c, h, -4:2:6, "fontsize", 12); 5730@end group 5731@end example 5732 5733@xseealso{@ref{XREFcontour,,contour}, @ref{XREFcontourf,,contourf}, @ref{XREFcontour3,,contour3}, @ref{XREFmeshc,,meshc}, @ref{XREFsurfc,,surfc}, @ref{XREFtext,,text}} 5734@end deftypefn 5735 5736 5737@c box scripts/plot/appearance/box.m 5738@anchor{XREFbox} 5739@deftypefn {} {} box 5740@deftypefnx {} {} box on 5741@deftypefnx {} {} box off 5742@deftypefnx {} {} box (@var{hax}, @dots{}) 5743Control display of the axes border. 5744 5745The argument may be either @qcode{"on"} or @qcode{"off"}. If it is 5746omitted, the current box state is toggled. 5747 5748If the first argument @var{hax} is an axes handle, then operate on this 5749axes rather than the current axes returned by @code{gca}. 5750@xseealso{@ref{XREFaxis,,axis}, @ref{XREFgrid,,grid}} 5751@end deftypefn 5752 5753 5754@c grid scripts/plot/appearance/grid.m 5755@anchor{XREFgrid} 5756@deftypefn {} {} grid 5757@deftypefnx {} {} grid on 5758@deftypefnx {} {} grid off 5759@deftypefnx {} {} grid minor 5760@deftypefnx {} {} grid minor on 5761@deftypefnx {} {} grid minor off 5762@deftypefnx {} {} grid (@var{hax}, @dots{}) 5763Control the display of plot grid lines. 5764 5765The function state input may be either @qcode{"on"} or @qcode{"off"}. 5766If it is omitted, the current grid state is toggled. 5767 5768When the first argument is @qcode{"minor"} all subsequent commands 5769modify the minor grid rather than the major grid. 5770 5771If the first argument @var{hax} is an axes handle, then operate on 5772this axes rather than the current axes returned by @code{gca}. 5773 5774To control the grid lines for an individual axes use the @code{set} 5775function. For example: 5776 5777@example 5778set (gca, "ygrid", "on"); 5779@end example 5780@xseealso{@ref{XREFaxis,,axis}, @ref{XREFbox,,box}} 5781@end deftypefn 5782 5783 5784@c colorbar scripts/plot/draw/colorbar.m 5785@anchor{XREFcolorbar} 5786@deftypefn {} {} colorbar 5787@deftypefnx {} {} colorbar (@dots{}, @var{loc}) 5788@deftypefnx {} {} colorbar (@var{delete_option}) 5789@deftypefnx {} {} colorbar (@var{hcb}, @dots{}) 5790@deftypefnx {} {} colorbar (@var{hax}, @dots{}) 5791@deftypefnx {} {} colorbar (@dots{}, "peer", @var{hax}, @dots{}) 5792@deftypefnx {} {} colorbar (@dots{}, "location", @var{loc}, @dots{}) 5793@deftypefnx {} {} colorbar (@dots{}, @var{prop}, @var{val}, @dots{}) 5794@deftypefnx {} {@var{h} =} colorbar (@dots{}) 5795Add a colorbar to the current axes. 5796 5797A colorbar displays the current colormap along with numerical rulings 5798so that the color scale can be interpreted. 5799 5800The optional input @nospell{@var{loc}} determines the location of the 5801colorbar. If present, it must be the last argument to @code{colorbar}. 5802Valid values for @nospell{@var{loc}} are 5803 5804@table @asis 5805@item @qcode{"EastOutside"} 5806Place the colorbar outside the plot to the right. This is the default. 5807 5808@item @qcode{"East"} 5809Place the colorbar inside the plot to the right. 5810 5811@item @qcode{"WestOutside"} 5812Place the colorbar outside the plot to the left. 5813 5814@item @qcode{"West"} 5815Place the colorbar inside the plot to the left. 5816 5817@item @qcode{"NorthOutside"} 5818Place the colorbar above the plot. 5819 5820@item @qcode{"North"} 5821Place the colorbar at the top of the plot. 5822 5823@item @qcode{"SouthOutside"} 5824Place the colorbar under the plot. 5825 5826@item @qcode{"South"} 5827Place the colorbar at the bottom of the plot. 5828@end table 5829 5830To remove a colorbar from a plot use any one of the following keywords for 5831the @var{delete_option}: @qcode{"off"}, @qcode{"delete"}, @qcode{"hide"}. 5832 5833If the first argument @var{hax} is an axes handle, then the colorbar is 5834added to this axes, rather than the current axes returned by @code{gca}. 5835Alternatively, If the argument @qcode{"peer"} is given, then the following 5836argument is treated as the axes handle in which to add the colorbar. The 5837@qcode{"peer"} calling syntax may be removed in the future and is not 5838recommended. 5839 5840If the first argument @var{hcb} is a handle to a colorbar object, then 5841operate on this colorbar directly. 5842 5843Additional property/value pairs are passed directly to the underlying axes 5844object. The full list of properties is documented at 5845@ref{Axes Properties}. 5846 5847The optional return value @var{h} is a graphics handle to the created 5848colorbar object. 5849 5850Implementation Note: A colorbar is created as an additional axes object 5851with the @qcode{"tag"} property set to @qcode{"colorbar"}. The created 5852object has the extra property @qcode{"location"} which controls the 5853positioning of the colorbar. 5854@xseealso{@ref{XREFcolormap,,colormap}} 5855@end deftypefn 5856 5857 5858@c annotation scripts/plot/appearance/annotation.m 5859@anchor{XREFannotation} 5860@deftypefn {} {} annotation (@var{type}) 5861@deftypefnx {} {} annotation ("line", @var{x}, @var{y}) 5862@deftypefnx {} {} annotation ("arrow", @var{x}, @var{y}) 5863@deftypefnx {} {} annotation ("doublearrow", @var{x}, @var{y}) 5864@deftypefnx {} {} annotation ("textarrow", @var{x}, @var{y}) 5865@deftypefnx {} {} annotation ("textbox", @var{pos}) 5866@deftypefnx {} {} annotation ("rectangle", @var{pos}) 5867@deftypefnx {} {} annotation ("ellipse", @var{pos}) 5868@deftypefnx {} {} annotation (@dots{}, @var{prop}, @var{val}) 5869@deftypefnx {} {} annotation (@var{hf}, @dots{}) 5870@deftypefnx {} {@var{h} =} annotation (@dots{}) 5871Draw annotations to emphasize parts of a figure. 5872 5873You may build a default annotation by specifying only the @var{type} 5874of the annotation. 5875 5876Otherwise you can select the type of annotation and then set its position 5877using either @var{x} and @var{y} coordinates for line-based annotations or a 5878position vector @var{pos} for others. In either case, coordinates are 5879interpreted using the @qcode{"units"} property of the annotation object. 5880The default is @qcode{"normalized"}, which means the lower left hand corner 5881of the figure has coordinates @samp{[0 0]} and the upper right hand corner 5882@samp{[1 1]}. 5883 5884If the first argument @var{hf} is a figure handle, then plot into this 5885figure, rather than the current figure returned by @code{gcf}. 5886 5887Further arguments can be provided in the form of @var{prop}/@var{val} pairs 5888to customize the annotation appearance. 5889 5890The optional return value @var{h} is a graphics handle to the created 5891annotation object. This can be used with the @code{set} function to 5892customize an existing annotation object. 5893 5894All annotation objects share two properties: 5895 5896@itemize 5897@item @qcode{"units"}: the units in which coordinates are interpreted.@* 5898Its value may be one of @qcode{"centimeters"} | @qcode{"characters"} | 5899@qcode{"inches"} | @qcode{"@{normalized@}"} | @qcode{"pixels"} | 5900@qcode{"points"}. 5901 5902@item @qcode{"position"}: a four-element vector [x0 y0 width height].@* 5903The vector specifies the coordinates (x0,y0) of the origin of the annotation 5904object, its width, and its height. The width and height may be negative, 5905depending on the orientation of the object. 5906 5907@end itemize 5908 5909Valid annotation types and their specific properties are described 5910below: 5911 5912@table @asis 5913@item @qcode{"line"} 5914Constructs a line. @var{x} and @var{y} must be two-element vectors 5915specifying the x and y coordinates of the two ends of the line. 5916 5917The line can be customized using @qcode{"linewidth"}, @qcode{"linestyle"}, 5918and @qcode{"color"} properties the same way as for @code{line} objects. 5919 5920@item @qcode{"arrow"} 5921Construct an arrow. The second point in vectors @var{x} and @var{y} 5922specifies the arrowhead coordinates. 5923 5924Besides line properties, the arrowhead can be customized using 5925@qcode{"headlength"}, @qcode{"headwidth"}, and @qcode{"headstyle"} 5926properties. Supported values for @qcode{"headstyle"} property are: 5927[@qcode{"diamond"} | @qcode{"ellipse"} | @qcode{"plain"} | 5928@qcode{"rectangle"} | @qcode{"vback1"} | @qcode{"@{vback2@}"} | 5929@qcode{"vback3"}] 5930 5931@item @qcode{"doublearrow"} 5932Construct a double arrow. Vectors @var{x} and @var{y} specify the 5933arrowhead coordinates. 5934 5935The line and the arrowhead can be customized as for arrow annotations, but 5936some property names are duplicated: 5937@qcode{"head1length"}/@qcode{"head2length"}, 5938@qcode{"head1width"}/@qcode{"head2width"}, etc. The index 1 marks the 5939properties of the arrowhead at the first point in @var{x} and @var{y} 5940coordinates. 5941 5942@item @qcode{"textarrow"} 5943Construct an arrow with a text label at the opposite end from the arrowhead. 5944 5945Use the @qcode{"string"} property to change the text string. 5946The line and the arrowhead can be customized as for arrow annotations, and 5947the text can be customized using the same properties as @code{text} graphics 5948objects. Note, however, that some text property names are prefixed with 5949"text" to distinguish them from arrow properties: 5950@qcode{"textbackgroundcolor"}, @qcode{"textcolor"}, 5951@qcode{"textedgecolor"}, @qcode{"textlinewidth"}, 5952@qcode{"textmargin"}, @qcode{"textrotation"}. 5953 5954@item @qcode{"textbox"} 5955Construct a box with text inside. @var{pos} specifies the 5956@qcode{"position"} property of the annotation. 5957 5958Use the @qcode{"string"} property to change the text string. 5959You may use @qcode{"backgroundcolor"}, @qcode{"edgecolor"}, 5960@qcode{"linestyle"}, and @qcode{"linewidth"} properties to customize 5961the box background color and edge appearance. A limited set of @code{text} 5962objects properties are also available; Besides @qcode{"font@dots{}"} 5963properties, you may also use @qcode{"horizontalalignment"} and 5964@qcode{"verticalalignment"} to position the text inside the box. 5965 5966Finally, the @qcode{"fitboxtotext"} property controls the actual extent of 5967the box. If @qcode{"on"} (the default) the box limits are fitted to the 5968text extent. 5969 5970@item @qcode{"rectangle"} 5971Construct a rectangle. @var{pos} specifies the @qcode{"position"} property 5972of the annotation. 5973 5974You may use @qcode{"facecolor"}, @qcode{"color"}, @qcode{"linestyle"}, and 5975@qcode{"linewidth"} properties to customize the rectangle background color 5976and edge appearance. 5977 5978@item @qcode{"ellipse"} 5979Construct an ellipse. @var{pos} specifies the @qcode{"position"} property 5980of the annotation. 5981 5982See @qcode{"rectangle"} annotations for customization. 5983@end table 5984 5985@xseealso{@ref{XREFxlabel,,xlabel}, @ref{XREFylabel,,ylabel}, @ref{XREFzlabel,,zlabel}, @ref{XREFtitle,,title}, @ref{XREFtext,,text}, @ref{XREFgtext,,gtext}, @ref{XREFlegend,,legend}, @ref{XREFcolorbar,,colorbar}} 5986@end deftypefn 5987 5988 5989@node Multiple Plots on One Page 5990@subsection Multiple Plots on One Page 5991@cindex plotting, multiple plots per figure 5992 5993Octave can display more than one plot in a single figure. The simplest 5994way to do this is to use the @code{subplot} function to divide the plot 5995area into a series of subplot windows that are indexed by an integer. 5996For example, 5997 5998@example 5999@group 6000subplot (2, 1, 1) 6001fplot (@@sin, [-10, 10]); 6002subplot (2, 1, 2) 6003fplot (@@cos, [-10, 10]); 6004@end group 6005@end example 6006 6007@noindent 6008creates a figure with two separate axes, one displaying a sine wave and the 6009other a cosine wave. The first call to subplot divides the figure into two 6010plotting areas (two rows and one column) and makes the first plot area active. 6011The grid of plot areas created by @code{subplot} is numbered in row-major order 6012(left to right, top to bottom). After plotting a sine wave, the next call to 6013subplot activates the second subplot area, but does not re-partition the 6014figure. 6015 6016@c subplot scripts/plot/util/subplot.m 6017@anchor{XREFsubplot} 6018@deftypefn {} {} subplot (@var{rows}, @var{cols}, @var{index}) 6019@deftypefnx {} {} subplot (@var{rows}, @var{cols}, @var{index}, @var{hax}) 6020@deftypefnx {} {} subplot (@var{rcn}) 6021@deftypefnx {} {} subplot (@var{hax}) 6022@deftypefnx {} {} subplot (@dots{}, "align") 6023@deftypefnx {} {} subplot (@dots{}, "replace") 6024@deftypefnx {} {} subplot ("position", @var{pos}) 6025@deftypefnx {} {} subplot (@dots{}, @var{prop}, @var{val}, @dots{}) 6026@deftypefnx {} {@var{hax} =} subplot (@dots{}) 6027Set up a plot grid with @var{rows} by @var{cols} subwindows and set the 6028current axes for plotting (@code{gca}) to the location given by @var{index}. 6029 6030If an axes handle @var{hax} is provided after the (@var{rows}, @var{cols}, 6031@var{index}) arguments, the corresponding axes is turned into a 6032subplot. 6033 6034If only one numeric argument is supplied, then it must be a three digit 6035value specifying the number of rows in digit 1, the number of columns in 6036digit 2, and the plot index in digit 3. 6037 6038The plot index runs row-wise; First, all columns in a row are numbered 6039and then the next row is filled. 6040 6041For example, a plot with 2x3 grid will have plot indices running as follows: 6042@tex 6043\vskip 10pt 6044\hfil\vbox{\offinterlineskip\hrule 6045\halign{\vrule#&&\qquad\hfil#\hfil\qquad\vrule\cr 6046height13pt&1&2&3\cr height12pt&&&\cr\noalign{\hrule} 6047height13pt&4&5&6\cr height12pt&&&\cr\noalign{\hrule}}} 6048\hfil 6049\vskip 10pt 6050@end tex 6051@ifnottex 6052 6053@example 6054@group 6055+-----+-----+-----+ 6056| 1 | 2 | 3 | 6057+-----+-----+-----+ 6058| 4 | 5 | 6 | 6059+-----+-----+-----+ 6060@end group 6061@end example 6062 6063@end ifnottex 6064 6065@var{index} may also be a vector. In this case, the new axes will enclose 6066the grid locations specified. The first demo illustrates this: 6067 6068@example 6069demo ("subplot", 1) 6070@end example 6071 6072The index of the subplot to make active may also be specified by its axes 6073handle, @var{hax}, returned from a previous @code{subplot} command. 6074 6075If the option @qcode{"align"} is given then the plot boxes of the subwindows 6076will align, but this may leave no room for axes tick marks or labels. 6077 6078If the option @qcode{"replace"} is given then the subplot axes will be 6079reset, rather than just switching the current axes for plotting to the 6080requested subplot. 6081 6082The @qcode{"position"} property can be used to exactly position the subplot 6083axes within the current figure. The option @var{pos} is a 4-element vector 6084[x, y, width, height] that determines the location and size of the axes. 6085The values in @var{pos} are normalized in the range [0,1]. 6086 6087Any property/value pairs are passed directly to the underlying axes object. 6088The full list of properties is documented at @ref{Axes Properties}. 6089 6090Any previously existing axes that would be (partly) covered by the newly 6091created axes are deleted. 6092 6093If the output @var{hax} is requested, subplot returns the axes handle for 6094the subplot. This is useful for modifying the properties of a subplot 6095using @code{set}. 6096 6097Under some circumstances, @code{subplot} might not be able to identify axes 6098that it could re-use and might replace them. If @code{subplot} axes 6099should be referenced repeatedly, consider creating and storing their axes 6100handles beforehand instead of calling @code{subplot} repeatedly for the same 6101position. 6102 6103Example: 6104 6105@example 6106@group 6107x = 1:10; 6108y = rand (16, 10); 6109for i_plot = 1:4 6110 hax(i_plot) = subplot (2, 2, i_plot); 6111 hold (hax(i_plot), "on"); 6112 grid (hax(i_plot), "on"); 6113endfor 6114for i_loop = 1:2 6115 for i_plot = 1:4 6116 iy = (i_loop - 1)*4 + i_plot; 6117 plotyy (hax(i_plot), x,y(iy,:), x,y(iy+1,:)); 6118 endfor 6119 endfor 6120@end group 6121@end example 6122 6123@xseealso{@ref{XREFaxes,,axes}, @ref{XREFplot,,plot}, @ref{XREFgca,,gca}, @ref{XREFset,,set}} 6124@end deftypefn 6125 6126 6127@node Multiple Plot Windows 6128@subsection Multiple Plot Windows 6129@cindex plotting, multiple plot windows 6130 6131You can open multiple plot windows using the @code{figure} function. 6132For example, 6133 6134@example 6135@group 6136figure (1); 6137fplot (@@sin, [-10, 10]); 6138figure (2); 6139fplot (@@cos, [-10, 10]); 6140@end group 6141@end example 6142 6143@noindent 6144creates two figures, with the first displaying a sine wave and 6145the second a cosine wave. Figure numbers must be positive integers. 6146 6147@c figure scripts/plot/util/figure.m 6148@anchor{XREFfigure} 6149@deftypefn {} {} figure 6150@deftypefnx {} {} figure @var{n} 6151@deftypefnx {} {} figure (@var{n}) 6152@deftypefnx {} {} figure (@dots{}, "@var{property}", @var{value}, @dots{}) 6153@deftypefnx {} {@var{h} =} figure (@dots{}) 6154Create a new figure window for plotting. 6155 6156If no arguments are specified, a new figure with the next available number 6157is created. 6158 6159If called with an integer @var{n}, and no such numbered figure exists, then 6160a new figure with the specified number is created. If the figure already 6161exists then it is made visible and becomes the current figure for plotting. 6162 6163Multiple property-value pairs may be specified for the figure object, but 6164they must appear in pairs. 6165 6166The optional return value @var{h} is a graphics handle to the created figure 6167object. 6168 6169Programming Note: The full list of properties is documented at 6170@ref{Figure Properties}. 6171@xseealso{@ref{XREFaxes,,axes}, @ref{XREFgcf,,gcf}, @ref{XREFshg,,shg}, @ref{XREFclf,,clf}, @ref{XREFclose,,close}} 6172@end deftypefn 6173 6174 6175@node Manipulation of Plot Objects 6176@subsection Manipulation of Plot Objects 6177@cindex plotting, object manipulation 6178 6179@c pan scripts/plot/util/pan.m 6180@anchor{XREFpan} 6181@deftypefn {} {} pan 6182@deftypefnx {} {} pan on 6183@deftypefnx {} {} pan off 6184@deftypefnx {} {} pan xon 6185@deftypefnx {} {} pan yon 6186@deftypefnx {} {} pan (@var{hfig}, @var{option}) 6187Control the interactive panning mode of a figure in the GUI. 6188 6189Given the option @qcode{"on"} or @qcode{"off"}, set the interactive 6190pan mode on or off. 6191 6192With no arguments, toggle the current pan mode on or off. 6193 6194Given the option @qcode{"xon"} or @qcode{"yon"}, enable pan mode 6195for the x or y axis only. 6196 6197If the first argument @var{hfig} is a figure, then operate on the given 6198figure rather than the current figure as returned by @code{gcf}. 6199 6200@xseealso{@ref{XREFrotate3d,,rotate3d}, @ref{XREFzoom,,zoom}} 6201@end deftypefn 6202 6203 6204@c rotate scripts/plot/util/rotate.m 6205@anchor{XREFrotate} 6206@deftypefn {} {} rotate (@var{h}, @var{direction}, @var{alpha}) 6207@deftypefnx {} {} rotate (@dots{}, @var{origin}) 6208Rotate the plot object @var{h} through @var{alpha} degrees around the line 6209with direction @var{direction} and origin @var{origin}. 6210 6211The default value of @var{origin} is the center of the axes object that is 6212the parent of @var{h}. 6213 6214If @var{h} is a vector of handles, they must all have the same parent axes 6215object. 6216 6217Graphics objects that may be rotated are lines, surfaces, patches, and 6218images. 6219@end deftypefn 6220 6221 6222@c rotate3d scripts/plot/util/rotate3d.m 6223@anchor{XREFrotate3d} 6224@deftypefn {} {} rotate3d 6225@deftypefnx {} {} rotate3d on 6226@deftypefnx {} {} rotate3d off 6227@deftypefnx {} {} rotate3d (@var{hfig}, @var{option}) 6228Control the interactive 3-D rotation mode of a figure in the GUI. 6229 6230Given the option @qcode{"on"} or @qcode{"off"}, set the interactive 6231rotate mode on or off. 6232 6233With no arguments, toggle the current rotate mode on or off. 6234 6235If the first argument @var{hfig} is a figure, then operate on the given 6236figure rather than the current figure as returned by @code{gcf}. 6237 6238@xseealso{@ref{XREFpan,,pan}, @ref{XREFzoom,,zoom}} 6239@end deftypefn 6240 6241 6242@c zoom scripts/plot/util/zoom.m 6243@anchor{XREFzoom} 6244@deftypefn {} {} zoom 6245@deftypefnx {} {} zoom (@var{factor}) 6246@deftypefnx {} {} zoom on 6247@deftypefnx {} {} zoom off 6248@deftypefnx {} {} zoom xon 6249@deftypefnx {} {} zoom yon 6250@deftypefnx {} {} zoom out 6251@deftypefnx {} {} zoom reset 6252@deftypefnx {} {} zoom (@var{hfig}, @var{option}) 6253Zoom the current axes object or control the interactive zoom mode of a 6254figure in the GUI. 6255 6256Given a numeric argument greater than zero, zoom by the given factor. If 6257the zoom factor is greater than one, zoom in on the plot. If the factor 6258is less than one, zoom out. If the zoom factor is a two- or three-element 6259vector, then the elements specify the zoom factors for the x, y, and z 6260axes respectively. 6261 6262Given the option @qcode{"on"} or @qcode{"off"}, set the interactive zoom 6263mode on or off. 6264 6265With no arguments, toggle the current zoom mode on or off. 6266 6267Given the option @qcode{"xon"} or @qcode{"yon"}, enable zoom mode for the 6268x or y-axis only. 6269 6270Given the option @qcode{"out"}, zoom to the initial zoom setting. 6271 6272Given the option @qcode{"reset"}, store the current zoom setting so that 6273@code{zoom out} will return to this zoom level. 6274 6275If the first argument @var{hfig} is a figure, then operate on the given 6276figure rather than the current figure as returned by @code{gcf}. 6277 6278@xseealso{@ref{XREFpan,,pan}, @ref{XREFrotate3d,,rotate3d}} 6279@end deftypefn 6280 6281 6282@node Manipulation of Plot Windows 6283@subsection Manipulation of Plot Windows 6284@cindex plotting, window manipulation 6285 6286By default, Octave refreshes the plot window when a prompt is printed, 6287or when waiting for input. The 6288@code{drawnow} function is used to cause a plot window to be updated. 6289 6290@c drawnow libinterp/corefcn/graphics.cc 6291@anchor{XREFdrawnow} 6292@deftypefn {} {} drawnow () 6293@deftypefnx {} {} drawnow ("expose") 6294@deftypefnx {} {} drawnow (@var{term}, @var{file}, @var{debug_file}) 6295Update figure windows and their children. 6296 6297The event queue is flushed and any callbacks generated are executed. 6298 6299With the optional argument @qcode{"expose"}, only graphic objects are 6300updated and no other events or callbacks are processed. 6301 6302The third calling form of @code{drawnow} is for debugging and is 6303undocumented. 6304@xseealso{@ref{XREFrefresh,,refresh}} 6305@end deftypefn 6306 6307 6308Only figures that are modified will be updated. The @code{refresh} 6309function can also be used to cause an update of the current figure, even if 6310it is not modified. 6311 6312@c refresh scripts/plot/util/refresh.m 6313@anchor{XREFrefresh} 6314@deftypefn {} {} refresh () 6315@deftypefnx {} {} refresh (@var{h}) 6316Refresh a figure, forcing it to be redrawn. 6317 6318When called without an argument the current figure is redrawn. Otherwise, 6319the figure with graphic handle @var{h} is redrawn. 6320@xseealso{@ref{XREFdrawnow,,drawnow}} 6321@end deftypefn 6322 6323 6324Normally, high-level plot functions like @code{plot} or @code{mesh} call 6325@code{newplot} to determine whether the state of the target axes should be 6326initialized (the default) or if subsequent plots should be drawn on top of 6327previous ones. To have two plots drawn over one another, use the @code{hold} 6328function or manually change the axes @ref{XREFaxesnextplot, ,nextplot} 6329property. For example, 6330 6331@example 6332@group 6333hold on; 6334x = -10:0.1:10; 6335plot (x, sin (x)); 6336plot (x, cos (x)); 6337hold off; 6338@end group 6339@end example 6340 6341@noindent 6342displays sine and cosine waves on the same axes. If the hold state is 6343off, consecutive plotting commands like this will only display the last 6344plot. 6345 6346@c newplot scripts/plot/util/newplot.m 6347@anchor{XREFnewplot} 6348@deftypefn {} {} newplot () 6349@deftypefnx {} {} newplot (@var{hfig}) 6350@deftypefnx {} {} newplot (@var{hax}) 6351@deftypefnx {} {@var{hax} =} newplot (@dots{}) 6352Prepare graphics engine to produce a new plot. 6353 6354This function is called at the beginning of all high-level plotting 6355functions. It is not normally required in user programs. @code{newplot} 6356queries the @qcode{"NextPlot"} field of the current figure and axes to 6357determine what to do. 6358 6359@multitable @columnfractions .25 .75 6360@headitem Figure NextPlot @tab Action 6361@item @qcode{"new"} @tab Create a new figure and make it the current figure. 6362 6363@item @qcode{"add"} (default) @tab Add new graphic objects to the current 6364figure. 6365 6366@item @qcode{"replacechildren"} @tab Delete child objects whose 6367HandleVisibility is set to @qcode{"on"}. Set NextPlot property to 6368@qcode{"add"}. This typically clears a figure, but leaves in place hidden 6369objects such as menubars. This is equivalent to @code{clf}. 6370 6371@item @qcode{"replace"} @tab Delete all child objects of the figure and 6372reset all figure properties to their defaults. However, the following 6373four properties are not reset: Position, Units, PaperPosition, PaperUnits. 6374This is equivalent to @code{clf reset}. 6375@end multitable 6376 6377@multitable @columnfractions .25 .75 6378@headitem Axes NextPlot @tab Action 6379@item @qcode{"add"} @tab Add new graphic objects to the current axes. This 6380is equivalent to @code{hold on}. 6381 6382@item @qcode{"replacechildren"} @tab Delete child objects whose 6383HandleVisibility is set to @qcode{"on"}, but leave axes properties 6384unmodified. This typically clears a plot, but preserves special settings 6385such as log scaling for axes. This is equivalent to @code{cla}. 6386 6387@item @qcode{"replace"} (default) @tab Delete all child objects of the 6388axes and reset all axes properties to their defaults. However, the 6389following properties are not reset: Position, Units. This is equivalent 6390to @code{cla reset}. 6391@end multitable 6392 6393If the optional input @var{hfig} or @var{hax} is given then prepare the 6394specified figure or axes rather than the current figure and axes. 6395 6396The optional return value @var{hax} is a graphics handle to the created 6397axes object (not figure). 6398 6399@strong{Caution:} Calling @code{newplot} may change the current figure and 6400current axes. 6401@end deftypefn 6402 6403 6404@c hold scripts/plot/util/hold.m 6405@anchor{XREFhold} 6406@deftypefn {} {} hold 6407@deftypefnx {} {} hold on 6408@deftypefnx {} {} hold off 6409@deftypefnx {} {} hold (@var{hax}, @dots{}) 6410Toggle or set the @qcode{"hold"} state of the plotting engine which 6411determines whether new graphic objects are added to the plot or replace 6412the existing objects. 6413 6414@table @code 6415@item hold on 6416Retain plot data and settings so that subsequent plot commands are displayed 6417on a single graph. Line color and line style are advanced for each new plot 6418added. 6419 6420@item hold all (deprecated) 6421Equivalent to @code{hold on}. 6422 6423@item hold off 6424Restore default graphics settings which clear the graph and reset axes 6425properties before each new plot command. (default). 6426 6427@item hold 6428Toggle the current hold state. 6429@end table 6430 6431When given the additional argument @var{hax}, the hold state is modified 6432for this axes rather than the current axes returned by @code{gca}. 6433 6434To query the current hold state use the @code{ishold} function. 6435@xseealso{@ref{XREFishold,,ishold}, @ref{XREFcla,,cla}, @ref{XREFclf,,clf}, @ref{XREFnewplot,,newplot}} 6436@end deftypefn 6437 6438 6439@c ishold scripts/plot/util/ishold.m 6440@anchor{XREFishold} 6441@deftypefn {} {} ishold 6442@deftypefnx {} {} ishold (@var{hax}) 6443@deftypefnx {} {} ishold (@var{hfig}) 6444Return true if the next plot will be added to the current plot, or 6445false if the plot device will be cleared before drawing the next plot. 6446 6447If the first argument is an axes handle @var{hax} or figure handle 6448@var{hfig} then operate on this plot rather than the current one. 6449@xseealso{@ref{XREFhold,,hold}, @ref{XREFnewplot,,newplot}} 6450@end deftypefn 6451 6452To clear the current figure, call the @code{clf} function. To clear the 6453current axis, call the @code{cla} function. To bring the current figure 6454to the top of the window stack, call the @code{shg} function. To delete 6455a graphics object, call @code{delete} on its index. To close the 6456figure window, call the @code{close} function. 6457 6458@c clf scripts/plot/util/clf.m 6459@anchor{XREFclf} 6460@deftypefn {} {} clf 6461@deftypefnx {} {} clf reset 6462@deftypefnx {} {} clf (@var{hfig}) 6463@deftypefnx {} {} clf (@var{hfig}, "reset") 6464@deftypefnx {} {@var{h} =} clf (@dots{}) 6465Clear the current figure window. 6466 6467@code{clf} operates by deleting child graphics objects with visible 6468handles (HandleVisibility = @qcode{"on"}). 6469 6470If the optional argument @qcode{"reset"} is specified, delete all child 6471objects including those with hidden handles and reset all figure 6472properties to their defaults. However, the following properties are not 6473reset: Position, Units, PaperPosition, PaperUnits. 6474 6475If the first argument @var{hfig} is a figure handle, then operate on 6476this figure rather than the current figure returned by @code{gcf}. 6477 6478The optional return value @var{h} is the graphics handle of the figure 6479window that was cleared. 6480@xseealso{@ref{XREFcla,,cla}, @ref{XREFclose,,close}, @ref{XREFdelete,,delete}, @ref{XREFreset,,reset}} 6481@end deftypefn 6482 6483 6484@c cla scripts/plot/util/cla.m 6485@anchor{XREFcla} 6486@deftypefn {} {} cla 6487@deftypefnx {} {} cla reset 6488@deftypefnx {} {} cla (@var{hax}) 6489@deftypefnx {} {} cla (@var{hax}, "reset") 6490Clear the current or specified (@var{hax}) axes object. 6491 6492@code{cla} operates by deleting child graphic objects with visible 6493handles (@code{HandleVisibility} = @qcode{"on"}). This typically clears the 6494axes of any visual objects, but leaves in place axes limits, tick marks and 6495labels, camera view, etc. In addition, the automatic coloring and styling 6496of lines is reset by changing the axes properties @code{ColorOrderIndex}, 6497@code{LinestyleOrderIndex} to 1. 6498 6499If the optional argument @qcode{"reset"} is specified, delete all child 6500objects, including those with hidden handles, and reset all axes properties 6501to their defaults. However, the following properties are not reset: 6502@code{Position}, @code{Units}. 6503 6504If the first argument @var{hax} is an axes handle, then operate on 6505this axes rather than the current axes returned by @code{gca}. 6506@xseealso{@ref{XREFclf,,clf}, @ref{XREFdelete,,delete}, @ref{XREFreset,,reset}} 6507@end deftypefn 6508 6509 6510@c shg scripts/plot/util/shg.m 6511@anchor{XREFshg} 6512@deftypefn {} {} shg 6513Show the graph window. 6514 6515This function makes the current figure visible, and places it on top of 6516of all other plot windows. 6517 6518Programming Note: @code{shg} is equivalent to @code{figure (gcf)} assuming 6519that a current figure exists. 6520@xseealso{@ref{XREFfigure,,figure}, @ref{XREFdrawnow,,drawnow}, @ref{XREFgcf,,gcf}} 6521@end deftypefn 6522 6523 6524@c delete scripts/miscellaneous/delete.m 6525@anchor{XREFdelete} 6526@deftypefn {} {} delete (@var{file}) 6527@deftypefnx {} {} delete (@var{file1}, @var{file2}, @dots{}) 6528@deftypefnx {} {} delete (@var{handle}) 6529Delete the named file or graphics handle. 6530 6531@var{file} may contain globbing patterns such as @samp{*}. Multiple files 6532to be deleted may be specified in the same function call. 6533 6534@var{handle} may be a scalar or vector of graphic handles to delete. 6535 6536Programming Note: Deleting graphics objects is the proper way to remove 6537features from a plot without clearing the entire figure. 6538@xseealso{@ref{XREFclf,,clf}, @ref{XREFcla,,cla}, @ref{XREFunlink,,unlink}, @ref{XREFrmdir,,rmdir}} 6539@end deftypefn 6540 6541 6542@c close scripts/plot/util/close.m 6543@anchor{XREFclose} 6544@deftypefn {} {} close 6545@deftypefnx {} {} close (@var{h}) 6546@deftypefnx {} {} close @var{figname} 6547@deftypefnx {} {} close all 6548@deftypefnx {} {} close all hidden 6549@deftypefnx {} {} close all force 6550Close figure window(s). 6551 6552When called with no arguments, close the current figure. This is equivalent 6553to @code{close (gcf)}. If the input @var{h} is a graphic handle, or vector 6554of graphics handles, then close each figure in @var{h}. The figure to 6555close may also be specified by name @var{figname} which is matched against 6556the @qcode{"Name"} property of all figures. 6557 6558If the argument @qcode{"all"} is given then all figures with visible handles 6559(HandleVisibility = @qcode{"on"}) are closed. 6560 6561If the additional argument @qcode{"hidden"} is given then all figures, 6562including hidden ones, are closed. 6563 6564If the additional argument @qcode{"force"} is given then figures are closed 6565even when @qcode{"closerequestfcn"} has been altered to prevent closing the 6566window. 6567 6568Implementation Note: @code{close} operates by making the handle @var{h} the 6569current figure, and then calling the function specified by the 6570@qcode{"closerequestfcn"} property of the figure. By default, the function 6571@code{closereq} is used. It is possible that the function invoked will 6572delay or abort removing the figure. To remove a figure without executing 6573any callback functions use @code{delete}. When writing a callback function 6574to close a window do not use @code{close} to avoid recursion. 6575 6576@xseealso{@ref{XREFclosereq,,closereq}, @ref{XREFdelete,,delete}} 6577@end deftypefn 6578 6579 6580@c closereq scripts/plot/util/closereq.m 6581@anchor{XREFclosereq} 6582@deftypefn {} {} closereq () 6583Close the current figure and delete all graphics objects associated with it. 6584 6585By default, the @qcode{"closerequestfcn"} property of a new plot figure 6586points to this function. 6587@xseealso{@ref{XREFclose,,close}, @ref{XREFdelete,,delete}} 6588@end deftypefn 6589 6590 6591@node Use of the @code{interpreter} Property 6592@subsection Use of the @code{interpreter} Property 6593@anchor{XREFinterpreterusage} 6594 6595All text objects---such as titles, labels, legends, and text---include 6596the property @qcode{"interpreter"} that determines the manner in 6597which special control sequences in the text are rendered. 6598 6599The interpreter property can take three values: @qcode{"none"}, @qcode{"tex"}, 6600@qcode{"latex"}. If the interpreter is set to @qcode{"none"} then no special 6601rendering occurs---the displayed text is a verbatim copy of the specified text. 6602Currently, the @qcode{"latex"} interpreter is not implemented for on-screen 6603display and is equivalent to @qcode{"none"}. Note that Octave does not parse 6604or validate the text strings when in @qcode{"latex"} mode---it is the 6605responsibility of the programmer to generate valid strings which may include 6606wrapping sections that should appear in Math mode with @qcode{'$'} characters. 6607 6608The @qcode{"tex"} option implements a subset of @TeX{} functionality when 6609rendering text. This allows the insertion of special glyphs such as Greek 6610characters or mathematical symbols. Special characters are inserted by using 6611a backslash (\) character followed by a code, as shown in @ref{tab:extended}. 6612 6613Besides special glyphs, the formatting of the text can be changed within the 6614string by using the codes 6615 6616@multitable @columnfractions .2 .2 .6 .2 6617@item @tab \bf @tab Bold font @tab 6618@item @tab \it @tab Italic font @tab 6619@item @tab \sl @tab Oblique Font @tab 6620@item @tab \rm @tab Normal font @tab 6621@end multitable 6622 6623These codes may be used in conjunction with the @{ and @} characters to limit 6624the change to a part of the string. For example, 6625 6626@example 6627xlabel ('@{\bf H@} = a @{\bf V@}') 6628@end example 6629 6630@noindent 6631where the character @qcode{'a'} will not appear in bold font. Note that to 6632avoid having Octave interpret the backslash character in the strings, 6633the strings themselves should be in single quotes. 6634 6635It is also possible to change the fontname and size within the text 6636 6637@multitable @columnfractions .1 .4 .6 .1 6638@item @tab \fontname@{@var{fontname}@} @tab Specify the font to use @tab 6639@item @tab \fontsize@{@var{size}@} @tab Specify the size of the font to 6640use @tab 6641@end multitable 6642 6643The color of the text may also be changed inline using either a string (e.g., 6644"red") or numerically with a Red-Green-Blue (RGB) specification (e.g., 6645[1 0 0], also red). 6646 6647@multitable @columnfractions .1 .4 .6 .1 6648@item @tab \color@{@var{color}@} @tab Specify the color as a string @tab 6649@item @tab \color[rgb]@{@var{R} @var{G} @var{B}@} @tab Specify the color 6650numerically @tab 6651@end multitable 6652 6653Finally, superscripting and subscripting can be controlled with the @qcode{'^'} 6654and @qcode{'_'} characters. If the @qcode{'^'} or @qcode{'_'} is followed by a 6655@{ character, then all of the block surrounded by the @w{@{ @}} pair is 6656superscripted or subscripted. Without the @w{@{ @}} pair, only the character 6657immediately following the @qcode{'^'} or @qcode{'_'} is changed. 6658 6659@float Table,tab:extended 6660@tex 6661\vskip 6pt 6662\newdimen\cola \cola=78pt 6663\newdimen\colb \colb=78pt 6664\newdimen\colc \colc=78pt 6665\def\symtable#1#2#3{ 6666\hbox to \hsize {\hfill\vbox{\offinterlineskip \tabskip=0pt 6667\hskip36pt #1 6668\vskip6pt 6669\halign{ 6670\vrule height2.0ex depth1.ex width 0.6pt #2\tabskip=0.3em & 6671#2 \hfil & \vrule #2 & #2 \hfil & #2 \vrule & 6672#2 \hfil & \vrule #2 & #2 \hfil & #2 \vrule & 6673#2 \hfil & \vrule #2 & #2 \hfil & #2 \vrule 6674width 0.6pt \tabskip=0pt\cr 6675\noalign{\hrule height 0.6pt} 6676& Code && Sym && Code && Sym && Code && Sym &\cr 6677\noalign{\hrule} 6678#3 6679\noalign{\hrule height 0.6pt} 6680} 6681}\hfill}} 6682\hoffset72pt 6683\symtable{Greek Lowercase Letters} {#} 6684{& \hbox to \cola{$\backslash$alpha } && $\alpha$ 6685&& \hbox to \colb{$\backslash$beta } && $\beta$ 6686&& \hbox to \colc{$\backslash$gamma} && $\gamma$ &\cr 6687& $\backslash$delta && $\delta$ 6688&& $\backslash$epsilon && $\epsilon$ 6689&& $\backslash$zeta && $\zeta$ &\cr 6690& $\backslash$eta && $\eta$ 6691&& $\backslash$theta && $\theta$ 6692&& $\backslash$vartheta && $\vartheta$ &\cr 6693& $\backslash$iota && $\iota$ 6694&& $\backslash$kappa && $\kappa$ 6695&& $\backslash$lambda && $\lambda$ &\cr 6696& $\backslash$mu && $\mu$ 6697&& $\backslash$nu && $\nu$ 6698&& $\backslash$xi && $\xi$ &\cr 6699& $\backslash$o && $o$ 6700&& $\backslash$pi && $\pi$ 6701&& $\backslash$varpi && $\varpi$ &\cr 6702& $\backslash$rho && $\rho$ 6703&& $\backslash$sigma && $\sigma$ 6704&& $\backslash$varsigma && $\varsigma$ &\cr 6705& $\backslash$tau && $\tau$ 6706&& $\backslash$upsilon && $\upsilon$ 6707&& $\backslash$phi && $\phi$ &\cr 6708& $\backslash$chi && $\chi$ 6709&& $\backslash$psi && $\psi$ 6710&& $\backslash$omega && $\omega$ &\cr} 6711\vskip12pt 6712\symtable{Greek Uppercase Letters} {#} 6713{& \hbox to \cola{$\backslash$Gamma} && $\Gamma$ 6714&& \hbox to \colb{$\backslash$Delta} && $\Delta$ 6715&& \hbox to \colc{$\backslash$Theta} && $\Theta$ &\cr 6716& $\backslash$Lambda && $\Lambda$ 6717&& $\backslash$Xi && $\Xi$ 6718&& $\backslash$Pi && $\Pi$ &\cr 6719& $\backslash$Sigma && $\Sigma$ 6720&& $\backslash$Upsilon && $\Upsilon$ 6721&& $\backslash$Phi && $\Phi$ &\cr 6722& $\backslash$Psi && $\Psi$ 6723&& $\backslash$Omega && $\Omega$ 6724&& && &\cr} 6725\vskip12pt 6726\symtable{Misc Symbols Type Ord} {#} 6727{& \hbox to \cola{$\backslash$aleph} && $\aleph$ 6728&& \hbox to \colb{$\backslash$wp} && $\wp$ 6729&& \hbox to \colc{$\backslash$Re} && $\Re$ &\cr 6730& $\backslash$Im && $\Im$ 6731&& $\backslash$partial && $\partial$ 6732&& $\backslash$infty && $\infty$ &\cr 6733& $\backslash$prime && $\prime$ 6734&& $\backslash$nabla && $\nabla$ 6735&& $\backslash$surd && $\surd$ &\cr 6736& $\backslash$angle && $\angle$ 6737&& $\backslash$forall && $\forall$ 6738&& $\backslash$exists && $\exists$ &\cr 6739& $\backslash$neg && $\neg$ 6740&& $\backslash$clubsuit && $\clubsuit$ 6741&& $\backslash$diamondsuit && $\diamondsuit$ &\cr 6742& $\backslash$heartsuit && $\heartsuit$ 6743&& $\backslash$spadesuit && $\spadesuit$ 6744&& && &\cr} 6745\vskip12pt 6746\symtable{``Large'' Operators} {#} 6747{& \hbox to \cola{$\backslash$int} && $\int$ 6748&& \hbox to \colb{} && 6749&& \hbox to \colc{} && &\cr} 6750\vskip12pt 6751\symtable{Binary operators} {#} 6752{& \hbox to \cola{$\backslash$pm} && $\pm$ 6753&& \hbox to \colb{$\backslash$cdot} && $\cdot$ 6754&& \hbox to \colc{$\backslash$times} && $\times$ &\cr 6755& $\backslash$ast && $\ast$ 6756&& $\backslash$circ && $\circ$ 6757&& $\backslash$bullet && $\bullet$ &\cr 6758& $\backslash$div && $\div$ 6759&& $\backslash$cap && $\cap$ 6760&& $\backslash$cup && $\cup$ &\cr 6761& $\backslash$vee && $\vee$ 6762&& $\backslash$wedge && $\wedge$ 6763&& $\backslash$oplus && $\oplus$ &\cr 6764& $\backslash$otimes && $\otimes$ 6765&& $\backslash$oslash && $\oslash$ 6766&& && &\cr} 6767@end tex 6768@ifnottex 6769@multitable @columnfractions .25 .25 .25 .25 6770@item Greek Lowercase Letters 6771@item @tab \alpha @tab \beta @tab \gamma 6772@item @tab \delta @tab \epsilon @tab \zeta 6773@item @tab \eta @tab \theta @tab \vartheta 6774@item @tab \iota @tab \kappa @tab \lambda 6775@item @tab \mu @tab \nu @tab \xi 6776@item @tab \o @tab \pi @tab \varpi 6777@item @tab \rho @tab \sigma @tab \varsigma 6778@item @tab \tau @tab \upsilon @tab \phi 6779@item @tab \chi @tab \psi @tab \omega 6780@item Greek Uppercase Letters 6781@item @tab \Gamma @tab \Delta @tab \Theta 6782@item @tab \Lambda @tab \Xi @tab \Pi 6783@item @tab \Sigma @tab \Upsilon @tab \Phi 6784@item @tab \Psi @tab \Omega @tab 6785@item Misc Symbols Type Ord 6786@item @tab \aleph @tab \wp @tab \Re 6787@item @tab \Im @tab \partial @tab \infty 6788@item @tab \prime @tab \nabla @tab \surd 6789@item @tab \angle @tab \forall @tab \exists 6790@item @tab \neg @tab \clubsuit @tab \diamondsuit 6791@item @tab \heartsuit @tab \spadesuit @tab 6792@item ``Large'' Operators 6793@item @tab \int 6794@item Binary Operators 6795@item @tab \pm @tab \cdot @tab \times 6796@item @tab \ast @tab \circ @tab \bullet 6797@item @tab \div @tab \cap @tab \cup 6798@item @tab \vee @tab \wedge @tab \oplus 6799@item @tab \otimes @tab \oslash @tab 6800@item Relations 6801@item @tab \leq @tab \subset @tab \subseteq 6802@item @tab \in @tab \geq @tab \supset 6803@item @tab \supseteq @tab \ni @tab \mid 6804@item @tab \equiv @tab \sim @tab \approx 6805@item @tab \cong @tab \propto @tab \perp 6806@item Arrows 6807@item @tab \leftarrow @tab \Leftarrow @tab \rightarrow 6808@item @tab \Rightarrow @tab \leftrightarrow @tab \uparrow 6809@item @tab \downarrow @tab @tab 6810@item Openings and Closings 6811@item @tab \lfloor @tab \langle @tab \lceil 6812@item @tab \rfloor @tab \rangle @tab \rceil 6813@item Alternate Names 6814@item @tab \neq 6815@item Other 6816@item @tab \ldots @tab \0 @tab \copyright 6817@item @tab \deg 6818@end multitable 6819@end ifnottex 6820@caption{Available special characters in @TeX{} mode} 6821@end float 6822@float 6823@tex 6824\vskip 6pt 6825\newdimen\cola \cola=78pt 6826\newdimen\colb \colb=78pt 6827\newdimen\colc \colc=78pt 6828\def\symtable#1#2#3{\hbox to \hsize {\hfill\vbox{\offinterlineskip \tabskip=0pt 6829\hskip36pt #1 6830\vskip6pt 6831\halign{ 6832\vrule height2.0ex depth1.ex width 0.6pt #2\tabskip=0.3em & 6833#2 \hfil & \vrule #2 & #2 \hfil & #2 \vrule & 6834#2 \hfil & \vrule #2 & #2 \hfil & #2 \vrule & 6835#2 \hfil & \vrule #2 & #2 \hfil & #2 \vrule 6836width 0.6pt \tabskip=0pt\cr 6837\noalign{\hrule height 0.6pt} 6838& Code && Sym && Code && Sym && Code && Sym &\cr 6839\noalign{\hrule} 6840#3 6841\noalign{\hrule height 0.6pt} 6842} 6843}\hfill}} 6844\hoffset72pt 6845\vskip12pt 6846\symtable{Relations} {#} 6847{& \hbox to \cola{$\backslash$leq} && $\leq$ 6848&& \hbox to \colb{$\backslash$subset} && $\subset$ 6849&& \hbox to \colc{$\backslash$subseteq} && $\subseteq$ &\cr 6850& $\backslash$in && $\in$ 6851&& $\backslash$geq && $\geq$ 6852&& $\backslash$supset && $\supset$ &\cr 6853& $\backslash$supseteq && $\supseteq$ 6854&& $\backslash$ni && $\ni$ 6855&& $\backslash$mid && $\mid$ &\cr 6856& $\backslash$equiv && $\equiv$ 6857&& $\backslash$sim && $\sim$ 6858&& $\backslash$approx && $\approx$ &\cr 6859& $\backslash$cong && $\cong$ 6860&& $\backslash$propto && $\propto$ 6861&& $\backslash$perp && $\perp$ &\cr} 6862\vskip12pt 6863\symtable{Arrows} {#} 6864{& \hbox to \cola{$\backslash$leftarrow} && $\leftarrow$ 6865&& \hbox to \colb{$\backslash$Leftarrow} && $\Leftarrow$ 6866&& \hbox to \colc{$\backslash$rightarrow} && $\rightarrow$ &\cr 6867& $\backslash$Rightarrow && $\Rightarrow$ 6868&& $\backslash$leftrightarrow && $\leftrightarrow$ 6869&& $\backslash$uparrow && $\uparrow$ &\cr 6870& $\backslash$downarrow && $\downarrow$ 6871&& && 6872&& && &\cr} 6873\vskip12pt 6874\symtable{Openings and Closings} {#} 6875{& \hbox to \cola{$\backslash$lfloor } && $\lfloor$ 6876&& \hbox to \colb{$\backslash$langle } && $\langle$ 6877&& \hbox to \colc{$\backslash$lceil } && $\lceil$ &\cr 6878& $\backslash$rfloor && $\rfloor$ 6879&& $\backslash$rangle && $\rangle$ 6880&& $\backslash$rceil && $\rceil$ &\cr} 6881\vskip12pt 6882\symtable{Alternate Names} {#} 6883{& \hbox to \cola{$\backslash$neq} && $\neq$ 6884&& \hbox to \colb{} && 6885&& \hbox to \colc{} && &\cr} 6886\vskip12pt 6887\symtable{Other (not in Appendix F Tables)} {#} 6888{& \hbox to \cola{$\backslash$ldots} && $\ldots$ 6889&& \hbox to \colb{$\backslash$0} && $\oslash$ 6890&& \hbox to \colc{$\backslash$copyright} && $\copyright$ &\cr 6891& $\backslash$deg && $^\circ$ 6892&& && 6893&& && &\cr} 6894\vskip12pt 6895\hskip36pt Table 15.1: Available special characters in \TeX\ mode (cont.) 6896@end tex 6897@end float 6898 6899@subsubsection Degree Symbol 6900@cindex Degree Symbol 6901 6902Conformance to both @TeX{} and @sc{matlab} with respect to the @code{\circ} 6903symbol is impossible. While @TeX{} translates this symbol to @w{Unicode 2218} 6904(U+2218), @sc{matlab} maps this to @w{Unicode 00B0} (U+00B0) instead. Octave 6905has chosen to follow the @TeX{} specification, but has added the additional 6906symbol @code{\deg} which maps to the degree symbol (U+00B0). 6907 6908@node Printing and Saving Plots 6909@subsection Printing and Saving Plots 6910@cindex plotting, saving and printing plots 6911@cindex printing plots 6912@cindex saving plots 6913 6914The @code{print} command allows you to send plots to you printer and 6915to save plots in a variety of formats. For example, 6916 6917@example 6918print -dpsc 6919@end example 6920 6921@noindent 6922prints the current figure to a color PostScript printer. And, 6923 6924@example 6925print -deps foo.eps 6926@end example 6927 6928@noindent 6929saves the current figure to an encapsulated PostScript file called 6930@file{foo.eps}. 6931 6932The current graphic toolkits produce very similar graphic displays, but differ 6933in their capability to display unusual text and in their ability to print 6934such text. In general, the @qcode{"tex"} interpreter (default) is the best 6935all-around performer for both on-screen display and printing. However, for the 6936reproduction of complicated text formulas the @qcode{"latex"} interpreter is 6937preferred. The @qcode{"latex"} interpreter will not display symbols on-screen, 6938but the printed output will be correct. When printing, use one of the 6939@code{standalone} options which provide full access to @LaTeX{} commands. 6940 6941A complete example showing the capabilities of text printing using the 6942@option{-dpdflatexstandalone} option is: 6943 6944@example 6945@group 6946x = 0:0.01:3; 6947hf = figure (); 6948plot (x, erf (x)); 6949hold on; 6950plot (x, x, "r"); 6951axis ([0, 3, 0, 1]); 6952text (0.65, 0.6175, ... 6953 ['$\displaystyle\leftarrow x = @{2 \over \sqrt@{\pi@}@}' ... 6954 '\int_@{0@}^@{x@} e^@{-t^2@} dt = 0.6175$'], 6955 "interpreter", "latex"); 6956xlabel ("x"); 6957ylabel ("erf (x)"); 6958title ("erf (x) with text annotation"); 6959print (hf, "plot15_7", "-dpdflatexstandalone"); 6960system ("pdflatex plot15_7"); 6961open plot15_7.pdf 6962@end group 6963@end example 6964 6965@ifnotinfo 6966@noindent 6967The result of this example can be seen in @ref{fig:extendedtext} 6968 6969@float Figure,fig:extendedtext 6970@center @image{extended,4in} 6971@caption{Example of inclusion of text with use of @option{-dpdflatexstandalone}} 6972@end float 6973@end ifnotinfo 6974 6975@c print scripts/plot/util/print.m 6976@anchor{XREFprint} 6977@deftypefn {} {} print () 6978@deftypefnx {} {} print (@var{options}) 6979@deftypefnx {} {} print (@var{filename}, @var{options}) 6980@deftypefnx {} {} print (@var{hfig}, @dots{}) 6981@deftypefnx {} {@var{rgb} =} print (@qcode{"-RGBImage"}, @dots{}) 6982Format a figure for printing and either save it to a file, send it to a 6983printer, or return an RGB image. 6984 6985@var{filename} defines the name of the output file. If the filename has 6986no suffix then one is inferred from the specified device and appended to the 6987filename. When neither a filename nor the @qcode{"-RGBImage"} option is 6988present, the output is sent to the printer. The various options and 6989filename arguments may be given in any order, except for the figure handle 6990argument @var{hfig} which must be first if it is present. 6991 6992Example: Print to a file using PDF and JPEG formats. 6993 6994@example 6995@group 6996figure (1); 6997clf (); 6998surf (peaks); 6999print figure1.pdf # The extension specifies the format 7000print -djpg figure1 # Will produce "figure1.jpg" file 7001@end group 7002@end example 7003 7004If the first argument is a handle @var{hfig} to a figure object then it 7005specifies the figure to print. By default, the current figure returned 7006by @code{gcf} is printed. 7007 7008For outputs to paged formats, for example, PostScript and PDF, the page size 7009is specified by the figure's @code{papersize} property together with the 7010@code{paperunits} property. The location and size of the plot on the page 7011are specified by the figure's @code{paperposition} property. The 7012orientation of the page is specified by the figure's @code{paperorientation} 7013property. 7014 7015For non-page formats---for example, image formats like JPEG---the width and 7016height of the output are specified by the figure's @code{paperposition(3:4)} 7017property values. 7018 7019The @code{print} command supports many @var{options}: 7020 7021@table @code 7022@item -f@var{h} 7023 Specify the handle, @var{h}, of the figure to be printed. 7024 7025Example: Print figure 1. 7026 7027@example 7028@group 7029figure (1); 7030clf (); 7031surf (peaks); 7032figure (2); 7033print -f1 figure1.pdf 7034## Equivalent functional form: 7035print (1, "figure1.pdf") 7036@end group 7037@end example 7038 7039@item -P@var{printer} 7040 Set the @var{printer} name to which the plot is sent if no @var{filename} 7041is specified. 7042 7043Example: Print to printer named PS_printer using PostScript format. 7044 7045@example 7046@group 7047clf (); 7048surf (peaks); 7049print -dpswrite -PPS_printer 7050@end group 7051@end example 7052 7053@item -RGBImage 7054 Return an M-by-N-by-3 RGB image of the figure. The size of the image 7055depends on the formatting options. This is similar to taking a screen 7056capture of the plot, but formatting options may be changed such as the 7057resolution or monochrome/color. 7058 7059Example: Get the pixels of a figure image. 7060 7061@example 7062@group 7063clf (); 7064surf (peaks); 7065@var{rgb} = print ("-RGBImage"); 7066@end group 7067@end example 7068 7069@item -opengl 7070@itemx -painters 7071 Specifies whether the opengl (pixel-based) or painters (vector-based) 7072renderer is used. This is equivalent to changing the figure's 7073@qcode{"Renderer"} property. When the figure 7074@nospell{@qcode{"RendererMode"}} property is @qcode{"auto"} (the default) 7075Octave will use the @qcode{"opengl"} renderer for raster formats (e.g., 7076JPEG) and @qcode{"painters"} for vector formats (e.g., PDF). Those options 7077are only supported for the "qt" graphics toolkit. 7078 7079@item -svgconvert 7080 When using the @option{-painters} renderer, this enables a different 7081backend toolchain with enhanced characteristics: 7082 7083@table @asis 7084@item Font handling: 7085The actual font is embedded in the output file which allows for printing 7086arbitrary characters and fonts in all vector formats. 7087 7088@item Output Simplification: 7089By default, the option @option{-painters} renders patch and surface objects 7090using assemblies of triangles. This may lead to anti-aliasing artifacts 7091when viewing the file. The @option{-svgconvert} option reconstructs 7092polygons in order to avoid those artifacts (particularly for 2-D figures). 7093 7094@item Transparency: 7095Allows for printing transparent graphics objects in PDF format. 7096For PostScript formats the presence of any transparent object will cause the 7097output to be rasterized. 7098@end table 7099 7100Caution: @option{-svgconvert} may lead to inaccurate rendering of image 7101objects. 7102 7103@item -portrait 7104@itemx -landscape 7105 Specify the orientation of the plot for printed output. 7106For non-printed output the aspect ratio of the output corresponds to the 7107plot area defined by the @qcode{"paperposition"} property in the 7108orientation specified. This option is equivalent to changing the figure's 7109@qcode{"paperorientation"} property. 7110 7111@item -fillpage 7112@itemx -bestfit 7113 When using a page-based format (PDF, PostScript, printer) ignore the 7114@qcode{"paperposition"} property and have the plot occupy the entire page. 7115The option @option{-fillpage} will stretch the plot to occupy the page with 71160.25 inch margins all around. The option @option{-bestfit} will expand the 7117plot to take up as much room as possible on the page @strong{without} 7118distorting the original aspect ratio of the plot. 7119 7120@item -color 7121@itemx -mono 7122 Color or monochrome output. 7123 7124@item -solid 7125@itemx -dashed 7126 Force all lines to be solid or dashed, respectively. 7127 7128@item -noui 7129 Don't print uicontrol objects such as pushbuttons which may overlay the 7130plot. This is the default behavior and it is not possible to include 7131uicontrol objects in the output without using an external screen capture 7132tool. 7133 7134@item -r@var{NUM} 7135 Resolution of bitmaps in dots per inch (DPI). For both metafiles and SVG 7136the default is the screen resolution; for other formats the default is 150 7137DPI@. To specify screen resolution, use @qcode{"-r0"}. 7138 7139Example: high resolution raster output. 7140 7141@example 7142@group 7143clf (); 7144surf (peaks (), "facelighting", "gouraud"); 7145light (); 7146print ("-r600", "lit_peaks.png"); 7147@end group 7148@end example 7149 7150@item -S@var{xsize},@var{ysize} 7151 Plot size in pixels for raster formats including PNG, JPEG, PNG, and 7152@emph{unusually} SVG@. For all vector formats, including PDF, PS, and EPS, 7153the plot size is specified in points. This option is equivalent to changing 7154the width and height of the output by setting the figure property 7155@code{paperposition(3:4)}. When using the command form of the print 7156function you must quote the @var{xsize},@var{ysize} option to prevent the 7157Octave interpreter from recognizing the embedded comma (','). For example, 7158by writing @w{"-S640,480"}. 7159 7160@item -tight 7161@itemx -loose 7162 Force a tight or loose bounding box for EPS files. The default is tight. 7163 7164@item -@var{preview} 7165 Add a preview to EPS files. Supported formats are: 7166 7167@table @code 7168@item -interchange 7169 Provide an interchange preview. 7170 7171@item -metafile 7172 Provide a metafile preview. 7173 7174@item -pict 7175 Provide a pict preview. 7176 7177@item -tiff 7178 Provide a TIFF preview. 7179@end table 7180 7181@item -append 7182 Append PostScript or PDF output to an existing file of the same type. 7183 7184@item -F@var{fontname} 7185@itemx -F@var{fontname}:@var{size} 7186@itemx -F:@var{size} 7187 Use @var{fontname} and/or @var{fontsize} for all text. 7188@var{fontname} is ignored for some devices: fig, etc. 7189 7190@item -d@var{device} 7191 The available output format is specified by the option @var{device}, and 7192is one of the following (devices marked with a @qcode{'*'} are only 7193available with the Gnuplot toolkit): 7194 7195Vector Formats 7196 7197@table @code 7198@item svg 7199 Scalable Vector Graphics. 7200 7201@item pdf 7202@itemx pdfcrop 7203 Portable Document Format. The @code{pdf} device formats the figure for 7204printing on paper. The size of the surrounding page and the position of the 7205figure inside the page are defined by the 7206@ref{XREFfigurepaperorientation,, paper* figure properties}. 7207 7208Use @code{pdfcrop} if you don't want the surrounding page. 7209 7210By default, PDF inherits the same limitations as PostScript. 7211For an enhanced output with complete text support and basic transparency, 7212use the @option{-svgconvert} option. 7213 7214@item eps(2) 7215@itemx epsc(2) 7216 Encapsulated PostScript (level 1 and 2, mono and color). 7217 7218The OpenGL-based graphics toolkits always generate PostScript level 3.0. 7219They have limited support for text unless using the @option{-svgconvert} 7220option. 7221Limitations include using only ASCII characters (e.g., no Greek letters) 7222and support for just three base PostScript fonts: Helvetica (the default), 7223Times, or Courier. Any other font will be replaced by Helvetica. 7224 7225@item ps(2) 7226@itemx psc(2) 7227 Same as @code{eps} except that the figure is formatted for printing on 7228paper. The size of the surrounding page and position of the figure inside 7229the page are defined by the 7230@ref{XREFfigurepaperorientation,, paper* figure properties}. 7231 7232@item pslatex 7233@itemx epslatex 7234@itemx pdflatex 7235@itemx pslatexstandalone 7236@itemx epslatexstandalone 7237@itemx pdflatexstandalone 7238 Generate a @LaTeX{} file @file{@var{filename}.tex} for the text portions 7239of a plot and a file @file{@var{filename}.(ps|eps|pdf)} for the remaining 7240graphics. The graphics file suffix .ps|eps|pdf is determined by the 7241specified device type. The @LaTeX{} file produced by the @samp{standalone} 7242option can be processed directly by @LaTeX{}. The file generated without 7243the @samp{standalone} option is intended to be included from another 7244@LaTeX{} document. In either case, the @LaTeX{} file contains an 7245@code{\includegraphics} command so that the generated graphics file is 7246automatically included when the @LaTeX{} file is processed. The text that 7247is written to the @LaTeX{} file contains the strings @strong{exactly} as 7248they were specified in the plot. If any special characters of the @TeX{} 7249mode interpreter were used, the file must be edited before @LaTeX{} 7250processing. Specifically, the special characters must be enclosed with 7251dollar signs @w{(@code{$ @dots{} $})}, and other characters that are 7252recognized by @LaTeX{} may also need editing (e.g., braces). The 7253@samp{pdflatex} device, and any of the @samp{standalone} formats, are not 7254available with the Gnuplot toolkit. 7255 7256@item epscairo* 7257@itemx pdfcairo* 7258@itemx epscairolatex* 7259@itemx pdfcairolatex* 7260@itemx epscairolatexstandalone* 7261@itemx pdfcairolatexstandalone* 7262 Generate output with Cairo renderer. The devices @code{epscairo} and 7263@code{pdfcairo} are synonymous with the @code{epsc} device. The @LaTeX{} 7264variants generate a @LaTeX{} file, @file{@var{filename}.tex}, for the text 7265portions of a plot, and an image file, @file{@var{filename}.(eps|pdf)}, for 7266the graph portion of the plot. The @samp{standalone} variants behave as 7267described for @samp{epslatexstandalone} above. 7268 7269@item canvas* 7270 Javascript-based drawing on an HTML5 canvas viewable in a web browser. 7271 7272@item emf 7273@itemx meta 7274 Microsoft Enhanced Metafile 7275 7276@item fig 7277 XFig. For the Gnuplot graphics toolkit, the additional options 7278@option{-textspecial} or @option{-textnormal} (default) can be used to 7279control whether the special flag should be set for the text in the figure. 7280 7281@item latex* 7282@itemx eepic* 7283@LaTeX{} picture environment and extended picture environment. 7284 7285@item tikz 7286@itemx tikzstandalone* 7287 Generate a @LaTeX{} file using PGF/TikZ format. The OpenGL-based 7288toolkits create a PGF file while Gnuplot creates a TikZ file. The 7289@samp{tikzstandalone} device produces a @LaTeX{} document which includes the 7290TikZ file. 7291 7292@end table 7293 7294Raster Formats 7295 7296@table @code 7297@item png 7298 Portable Network Graphics 7299 7300@item jpg 7301@itemx jpeg 7302 JPEG image 7303 7304@item tif 7305@itemx tiff 7306@itemx tiffn 7307 TIFF image with LZW compression (@nospell{tif}, tiff) or uncompressed 7308(@nospell{tiffn}). 7309 7310@item gif 7311 GIF image 7312 7313@item pbm 7314 PBMplus 7315 7316@item dumb* 7317 ASCII art 7318 7319@end table 7320 7321 If the device is omitted, it is inferred from the file extension, 7322or if there is no filename then it is sent to the printer as PostScript. 7323 7324@item -d@var{ghostscript_device} 7325 Additional devices are supported by Ghostscript. 7326Some examples are: 7327 7328@table @code 7329@item ljet2p 7330 HP LaserJet @nospell{IIP} 7331 7332@item pcx24b 7333 24-bit color PCX file format 7334 7335@item ppm 7336 Portable Pixel Map file format 7337@end table 7338 7339 For a complete list of available formats and devices type 7340@kbd{system ("gs -h")}. 7341 7342 When Ghostscript output is sent to a printer the size is determined by 7343the figure's @qcode{"papersize"} property. When the output is sent to a 7344file the size is determined by the plot box defined by the figure's 7345@qcode{"paperposition"} property. 7346 7347@item -G@var{ghostscript_command} 7348 Specify the command for calling Ghostscript. For Unix the default is 7349@qcode{"gs"} and for Windows it is @qcode{"gswin32c"}. 7350 7351@item -TextAlphaBits=@var{n} 7352@itemx -GraphicsAlphaBits=@var{n} 7353 Octave is able to produce output for various printers, bitmaps, and 7354vector formats by using Ghostscript. For bitmap and printer output 7355anti-aliasing is applied using Ghostscript's TextAlphaBits and 7356GraphicsAlphaBits options. The default number of bits are 4 and 1 7357respectively. Allowed values for @var{N} are 1, 2, or 4. 7358@end table 7359 7360@xseealso{@ref{XREFsaveas,,saveas}, @ref{XREFgetframe,,getframe}, @ref{XREFsavefig,,savefig}, @ref{XREFhgsave,,hgsave}, @ref{XREForient,,orient}, @ref{XREFfigure,,figure}} 7361@end deftypefn 7362 7363 7364@c saveas scripts/plot/util/saveas.m 7365@anchor{XREFsaveas} 7366@deftypefn {} {} saveas (@var{h}, @var{filename}) 7367@deftypefnx {} {} saveas (@var{h}, @var{filename}, @var{fmt}) 7368Save graphic object @var{h} to the file @var{filename} in graphic format 7369@var{fmt}. 7370 7371All device formats accepted by @code{print} may be used. Common formats 7372are: 7373 7374@table @code 7375@item ps 7376 PostScript 7377 7378@item eps 7379 Encapsulated PostScript 7380 7381@item pdf 7382 Portable Document Format 7383 7384@item jpg 7385 JPEG Image 7386 7387@item png 7388 Portable Network Graphics image 7389 7390@item emf 7391 Enhanced MetaFile 7392 7393@item tif 7394 TIFF Image, compressed 7395 7396@end table 7397 7398If @var{fmt} is omitted it is extracted from the extension of 7399@var{filename}. The default format when there is no extension is 7400@qcode{"pdf"}. 7401 7402@example 7403@group 7404clf (); 7405surf (peaks); 7406saveas (1, "figure1.png"); 7407@end group 7408@end example 7409 7410@xseealso{@ref{XREFprint,,print}, @ref{XREFhgsave,,hgsave}, @ref{XREForient,,orient}} 7411@end deftypefn 7412 7413 7414@c orient scripts/plot/appearance/orient.m 7415@anchor{XREForient} 7416@deftypefn {} {} orient (@var{orientation}) 7417@deftypefnx {} {} orient (@var{hfig}, @var{orientation}) 7418@deftypefnx {} {@var{orientation} =} orient () 7419@deftypefnx {} {@var{orientation} =} orient (@var{hfig}) 7420Query or set the print orientation for figure @var{hfig}. 7421 7422Valid values for @var{orientation} are @qcode{"portrait"}, 7423@qcode{"landscape"}, and @qcode{"tall"}. 7424 7425The @qcode{"landscape"} option changes the orientation so the plot width 7426is larger than the plot height. The @qcode{"paperposition"} is also 7427modified so that the plot fills the page, while leaving a 0.25 inch border. 7428 7429The @qcode{"tall"} option sets the orientation to @qcode{"portrait"} and 7430fills the page with the plot, while leaving a 0.25 inch border. 7431 7432The @qcode{"portrait"} option (default) changes the orientation so the plot 7433height is larger than the plot width. It also restores the default 7434@qcode{"paperposition"} property. 7435 7436When called with no arguments, return the current print orientation. 7437 7438If the argument @var{hfig} is omitted, then operate on the current figure 7439returned by @code{gcf}. 7440@xseealso{@ref{XREFprint,,print}, @ref{XREFsaveas,,saveas}} 7441@end deftypefn 7442 7443 7444@code{print} and @code{saveas} are used when work on a plot has finished 7445and the output must be in a publication-ready format. During intermediate 7446stages it is often better to save the graphics object and all of its 7447associated information so that changes---to colors, axis limits, marker styles, 7448etc.---can be made easily from within Octave. The @code{hgsave}/@code{hgload} 7449commands can be used to save and re-create a graphics object. 7450 7451@c hgsave scripts/plot/util/hgsave.m 7452@anchor{XREFhgsave} 7453@deftypefn {} {} hgsave (@var{filename}) 7454@deftypefnx {} {} hgsave (@var{h}, @var{filename}) 7455@deftypefnx {} {} hgsave (@var{h}, @var{filename}, @var{fmt}) 7456Save the graphics handle(s) @var{h} to the file @var{filename} in the format 7457@var{fmt}. 7458 7459If unspecified, @var{h} is the current figure as returned by @code{gcf}. 7460 7461When @var{filename} does not have an extension the default filename 7462extension @file{.ofig} will be appended. 7463 7464If present, @var{fmt} must be one of the following: 7465 7466@itemize @bullet 7467@item @option{-binary}, @option{-float-binary} 7468 7469@item @option{-hdf5}, @option{-float-hdf5} 7470 7471@item @option{-V7}, @option{-v7}, @option{-7}, @option{-mat7-binary} 7472 7473@item @option{-V6}, @option{-v6}, @option{-6}, @option{-mat6-binary} 7474 7475@item @option{-text} 7476 7477@item @option{-zip}, @option{-z} 7478@end itemize 7479 7480The default format is @option{-binary} to minimize storage. 7481 7482Programming Note: When producing graphics for final publication use 7483@code{print} or @code{saveas}. When it is important to be able to continue 7484to edit a figure as an Octave object, use @code{hgsave}/@code{hgload}. 7485@xseealso{@ref{XREFhgload,,hgload}, @ref{XREFhdl2struct,,hdl2struct}, @ref{XREFsavefig,,savefig}, @ref{XREFsaveas,,saveas}, @ref{XREFprint,,print}} 7486@end deftypefn 7487 7488 7489@c hgload scripts/plot/util/hgload.m 7490@anchor{XREFhgload} 7491@deftypefn {} {@var{h} =} hgload (@var{filename}) 7492@deftypefnx {} {[@var{h}, @var{old_prop}] =} hgload (@var{filename}, @var{prop_struct}) 7493Load the graphics objects in @var{filename} into a vector of graphics 7494handles @var{h}. 7495 7496If @var{filename} has no extension, Octave will try to find the file with 7497and without the default extension @file{.ofig}. 7498 7499If provided, the elements of structure @var{prop_struct} will be used to 7500override the properties of top-level objects stored in @var{filename}, and 7501the saved values from @var{filename} will be stored in @var{old_prop}. 7502@var{old_prop} is a cell array matching the size of @var{h}; each cell 7503contains a structure of the existing property names and values before being 7504overridden. 7505 7506@xseealso{@ref{XREFopenfig,,openfig}, @ref{XREFhgsave,,hgsave}, @ref{XREFstruct2hdl,,struct2hdl}} 7507@end deftypefn 7508 7509 7510@c openfig scripts/plot/util/openfig.m 7511@anchor{XREFopenfig} 7512@deftypefn {} {} openfig 7513@deftypefnx {} {} openfig (@var{filename}) 7514@deftypefnx {} {} openfig (@dots{}, @var{copies}) 7515@deftypefnx {} {} openfig (@dots{}, @var{visibility}) 7516@deftypefnx {} {@var{h} =} openfig (@dots{}) 7517Read saved figure window(s) from @var{filename} and return graphics 7518handle(s) @var{h}. 7519 7520By default, @var{filename} is @qcode{"Untitled.fig"}. If a full path is not 7521specified, the file opened will be the first one encountered in the load 7522path. If @var{filename} is not found and does not have an extension, a 7523search will take place for the first file in the load path with extension 7524@qcode{".fig"} or @qcode{".ofig"}, in that order. 7525 7526@var{copies} is an optional input indicating whether a new figure should 7527be created (@qcode{"new"}) or whether an existing figure may be reused 7528(@qcode{"reuse"}). An existing figure may be reused if the 7529@qcode{"FileName"} property matches the specified input @var{filename}. 7530When a figure is reused it becomes the active figure and is shown on top 7531of other figures. If the figure was offscreen, it is re-positioned to be 7532onscreen. The default value for @var{copies} is @qcode{"new"}. 7533 7534@var{visibility} is an optional input indicating whether to show the figure 7535(@qcode{"visible"}) or not (@qcode{"invisible"}). When @var{visibility} is 7536specified as an input to @code{openfig} it overrides the visibility setting 7537stored in @var{filename}. 7538 7539@xseealso{@ref{XREFopen,,open}, @ref{XREFhgload,,hgload}, @ref{XREFsavefig,,savefig}, @ref{XREFstruct2hdl,,struct2hdl}} 7540@end deftypefn 7541 7542 7543@c savefig scripts/plot/util/savefig.m 7544@anchor{XREFsavefig} 7545@deftypefn {} {} savefig () 7546@deftypefnx {} {} savefig (@var{h}) 7547@deftypefnx {} {} savefig (@var{filename}) 7548@deftypefnx {} {} savefig (@var{h}, @var{filename}) 7549@deftypefnx {} {} savefig (@var{h}, @var{filename}, @qcode{"compact"}) 7550Save figure windows specified by graphics handle(s) @var{h} to file 7551@var{filename}. 7552 7553If unspecified, @var{h} is the current figure returned by @code{gcf}. 7554 7555If unspecified, @var{filename} is set to @file{"Untitled.fig"}. If 7556@var{filename} does not have an extension then the default extension 7557@file{".fig"} will be added. 7558 7559If the optional third input @qcode{"compact"} is present then the data 7560will be compressed to save more space. 7561 7562@xseealso{@ref{XREFhgsave,,hgsave}, @ref{XREFhdl2struct,,hdl2struct}, @ref{XREFopenfig,,openfig}} 7563@end deftypefn 7564 7565 7566@node Interacting with Plots 7567@subsection Interacting with Plots 7568 7569The user can select points on a plot with the @code{ginput} function or 7570select the position at which to place text on the plot with the 7571@code{gtext} function using the mouse. 7572 7573@c ginput scripts/plot/util/ginput.m 7574@anchor{XREFginput} 7575@deftypefn {} {[@var{x}, @var{y}, @var{buttons}] =} ginput (@var{n}) 7576@deftypefnx {} {[@var{x}, @var{y}, @var{buttons}] =} ginput () 7577Return the position and type of mouse button clicks and/or key strokes 7578in the current figure window. 7579 7580If @var{n} is defined, then capture @var{n} events before returning. 7581When @var{n} is not defined @code{ginput} will loop until the return key 7582@key{RET} is pressed. 7583 7584The return values @var{x}, @var{y} are the coordinates where the mouse 7585was clicked in the units of the current axes. The return value @var{button} 7586is 1, 2, or 3 for the left, middle, or right button. If a key is pressed 7587the ASCII value is returned in @var{button}. 7588 7589Implementation Note: @code{ginput} is intenteded for 2-D plots. For 3-D 7590plots see the @var{currentpoint} property of the current axes which can be 7591transformed with knowledge of the current @code{view} into data units. 7592@xseealso{@ref{XREFgtext,,gtext}, @ref{XREFwaitforbuttonpress,,waitforbuttonpress}} 7593@end deftypefn 7594 7595 7596@c waitforbuttonpress scripts/gui/waitforbuttonpress.m 7597@anchor{XREFwaitforbuttonpress} 7598@deftypefn {} {} waitforbuttonpress () 7599@deftypefnx {} {@var{b} =} waitforbuttonpress () 7600Wait for mouse click or key press over the current figure window. 7601 7602The return value of @var{b} is 0 if a mouse button was pressed or 1 if a 7603key was pressed. 7604@xseealso{@ref{XREFwaitfor,,waitfor}, @ref{XREFginput,,ginput}, @ref{XREFkbhit,,kbhit}} 7605@end deftypefn 7606 7607 7608@c gtext scripts/plot/appearance/gtext.m 7609@anchor{XREFgtext} 7610@deftypefn {} {} gtext (@var{s}) 7611@deftypefnx {} {} gtext (@{@var{s1}, @var{s2}, @dots{}@}) 7612@deftypefnx {} {} gtext (@{@var{s1}; @var{s2}; @dots{}@}) 7613@deftypefnx {} {} gtext (@dots{}, @var{prop}, @var{val}, @dots{}) 7614@deftypefnx {} {@var{h} =} gtext (@dots{}) 7615Place text on the current figure using the mouse. 7616 7617The string argument @var{s} may be a character array or a cell array 7618of strings. If @var{s} has more than one row, each row is used 7619to create a separate text object after a mouse click. For example: 7620 7621Place a single string after one mouse click 7622 7623@example 7624gtext ("I clicked here") 7625@end example 7626 7627Place two strings after two mouse clicks 7628 7629@example 7630gtext (@{"I clicked here"; "and there"@}) 7631@end example 7632 7633Place two strings, each with two lines, after two mouse clicks 7634 7635@example 7636gtext (@{"I clicked", "here"; "and", "there"@}) 7637@end example 7638 7639Optional @var{property}/@var{value} pairs are passed directly to the 7640underlying text objects. 7641 7642The full list of text object properties is documented at 7643@ref{Text Properties}. 7644 7645The optional return value @var{h} holds the graphics handle(s) to the 7646created text object(s). 7647@xseealso{@ref{XREFginput,,ginput}, @ref{XREFtext,,text}} 7648@end deftypefn 7649 7650 7651More sophisticated user interaction mechanisms can be obtained using the 7652@nospell{ui*} family of functions, @pxref{UI Elements}. 7653 7654@node Test Plotting Functions 7655@subsection Test Plotting Functions 7656 7657The functions @code{sombrero} and @code{peaks} provide a way to check 7658that plotting is working. Typing either @code{sombrero} or @code{peaks} 7659at the Octave prompt should display a three-dimensional plot. 7660 7661@c sombrero scripts/plot/draw/sombrero.m 7662@anchor{XREFsombrero} 7663@deftypefn {} {} sombrero () 7664@deftypefnx {} {} sombrero (@var{n}) 7665@deftypefnx {} {@var{z} =} sombrero (@dots{}) 7666@deftypefnx {} {[@var{x}, @var{y}, @var{z}] =} sombrero (@dots{}) 7667Plot the familiar 3-D sombrero function. 7668 7669The function plotted is 7670@tex 7671$$z = { \rm{sin} (\sqrt {(x^2 + y^2)}) \over \sqrt {(x^2 + y^2)} }$$ 7672@end tex 7673@ifnottex 7674 7675@example 7676z = sin (sqrt (x^2 + y^2)) / (sqrt (x^2 + y^2)) 7677@end example 7678 7679@end ifnottex 7680Called without a return argument, @code{sombrero} plots the surface of the 7681above function over the meshgrid [-8,8] using @code{surf}. 7682 7683If @var{n} is a scalar the plot is made with @var{n} grid lines. 7684The default value for @var{n} is 41. 7685 7686When called with output arguments, return the data for the function 7687evaluated over the meshgrid. This can subsequently be plotted with 7688@code{surf (@var{x}, @var{y}, @var{z})}. 7689 7690@xseealso{@ref{XREFpeaks,,peaks}, @ref{XREFmeshgrid,,meshgrid}, @ref{XREFmesh,,mesh}, @ref{XREFsurf,,surf}} 7691@end deftypefn 7692 7693 7694@c peaks scripts/plot/draw/peaks.m 7695@anchor{XREFpeaks} 7696@deftypefn {} {} peaks () 7697@deftypefnx {} {} peaks (@var{n}) 7698@deftypefnx {} {} peaks (@var{x}, @var{y}) 7699@deftypefnx {} {@var{z} =} peaks (@dots{}) 7700@deftypefnx {} {[@var{x}, @var{y}, @var{z}] =} peaks (@dots{}) 7701Plot a function with lots of local maxima and minima. 7702 7703The function has the form 7704 7705@tex 7706$$f(x,y) = 3 (1 - x) ^ 2 e ^ {\left(-x^2 - (y+1)^2\right)} - 10 \left({x \over 5} - x^3 - y^5\right) - {1 \over 3} e^{\left(-(x+1)^2 - y^2\right)}$$ 7707@end tex 7708@ifnottex 7709@verbatim 7710f(x,y) = 3*(1-x)^2*exp(-x^2 - (y+1)^2) ... 7711 - 10*(x/5 - x^3 - y^5)*exp(-x^2-y^2) ... 7712 - 1/3*exp(-(x+1)^2 - y^2) 7713@end verbatim 7714@end ifnottex 7715 7716Called without a return argument, @code{peaks} plots the surface of the 7717above function using @code{surf}. 7718 7719If @var{n} is a scalar, @code{peaks} plots the value of the above 7720function on an @var{n}-by-@var{n} mesh over the range [-3,3]. The 7721default value for @var{n} is 49. 7722 7723If @var{n} is a vector, then it represents the grid values over which 7724to calculate the function. If @var{x} and @var{y} are specified then 7725the function value is calculated over the specified grid of vertices. 7726 7727When called with output arguments, return the data for the function 7728evaluated over the meshgrid. This can subsequently be plotted with 7729@code{surf (@var{x}, @var{y}, @var{z})}. 7730 7731@xseealso{@ref{XREFsombrero,,sombrero}, @ref{XREFmeshgrid,,meshgrid}, @ref{XREFmesh,,mesh}, @ref{XREFsurf,,surf}} 7732@end deftypefn 7733 7734@node Graphics Data Structures 7735@section Graphics Data Structures 7736@cindex graphics data structures 7737 7738@menu 7739* Introduction to Graphics Structures:: 7740* Graphics Objects:: 7741* Graphics Object Properties:: 7742* Searching Properties:: 7743* Managing Default Properties:: 7744@end menu 7745 7746@node Introduction to Graphics Structures 7747@subsection Introduction to Graphics Structures 7748@cindex introduction to graphics structures 7749@anchor{XREFgraphics structures} 7750 7751The graphics functions use pointers, which are of class graphics_handle, in 7752order to address the data structures which control visual display. A 7753graphics handle may point to any one of a number of different base object 7754types and these objects are the graphics data structures themselves. The 7755primitive graphic object types are: @code{figure}, @code{axes}, @code{line}, 7756@code{text}, @code{patch}, @code{surface}, @code{text}, @code{image}, and 7757@code{light}. 7758 7759Each of these objects has a function by the same name, and, each of these 7760functions returns a graphics handle pointing to an object of the corresponding 7761type. In addition there are several functions which operate on properties of 7762the graphics objects and which also return handles: the functions @code{plot} 7763and @code{plot3} return a handle pointing to an object of type line, the 7764function @code{subplot} returns a handle pointing to an object of type axes, 7765the function @code{fill} returns a handle pointing to an object of type patch, 7766the functions @code{area}, @code{bar}, @code{barh}, @code{contour}, 7767@code{contourf}, @code{contour3}, @code{surf}, @code{mesh}, @code{surfc}, 7768@code{meshc}, @code{errorbar}, @code{quiver}, @code{quiver3}, @code{scatter}, 7769@code{scatter3}, @code{stair}, @code{stem}, @code{stem3} each return a handle 7770to a complex data structure as documented in 7771@ref{XREFdatasources,,Data Sources}. 7772 7773The graphics objects are arranged in a hierarchy: 7774 77751. The root object is returned by @code{groot} (historically, equivalent to 7776the handle 0). In other words, @code{get (groot)} returns the properties of 7777the root object. 7778 77792. Below the root are @code{figure} objects. 7780 77813. Below the @code{figure} objects are @code{axes} or @code{hggroup} objects. 7782 77834. Below the @code{axes} objects are @code{line}, @code{text}, @code{patch}, 7784@code{surface}, @code{image}, and @code{light} objects. 7785 7786Graphics handles may be distinguished from function handles 7787(@pxref{Function Handles}) by means of the function @code{ishghandle}. 7788@code{ishghandle} returns true if its argument is a handle of a graphics 7789object. In addition, a figure or axes object may be tested using 7790@code{isfigure} or @code{isaxes} respectively. To test for a specific type of 7791graphics handle, such as a patch or line object, use @code{isgraphics}. The 7792more specific test functions return true only if the argument is both a 7793graphics handle and of the correct type (figure, axes, specified object type). 7794 7795The @code{get} and @code{set} commands are used to obtain and set the values of 7796properties of graphics objects. In addition, the @code{get} command may be 7797used to obtain property names. 7798 7799For example, the property @qcode{"type"} of the graphics object pointed to by 7800the graphics handle h may be displayed by: 7801 7802@example 7803get (h, "type") 7804@end example 7805 7806The properties and their current values may be obtained in the form of a 7807structure using @code{s = get (h)}, where @code{h} is the handle of a graphics 7808object. If only the names of the properties and the allowed values (for radio 7809properties only) are wanted, one may use @code{set (h)}. 7810 7811Thus, for example: 7812 7813@example 7814h = figure (); 7815get (h, "type") 7816@result{} ans = figure 7817set (h) 7818@result{} 7819 alphamap: 7820 beingdeleted: [ @{off@} | on ] 7821 busyaction: [ cancel | @{queue@} ] 7822 buttondownfcn: 7823 clipping: [ off | @{on@} ] 7824 closerequestfcn: 7825 color: 7826 colormap: 7827 createfcn: 7828 currentaxes: 7829 deletefcn: 7830 dockcontrols: [ @{off@} | on ] 7831 filename: 7832 graphicssmoothing: [ off | @{on@} ] 7833 handlevisibility: [ callback | off | @{on@} ] 7834 ... 7835@end example 7836 7837The uses of @code{get} and @code{set} are further explained in 7838@ref{XREFget,,get}, @ref{XREFset,,set}. 7839 7840@c isprop scripts/plot/util/isprop.m 7841@anchor{XREFisprop} 7842@deftypefn {} {@var{res} =} isprop (@var{obj}, "@var{prop}") 7843Return true if @var{prop} is a property of the object @var{obj}. 7844 7845@var{obj} may also be an array of objects in which case @var{res} will be a 7846logical array indicating whether each handle has the property @var{prop}. 7847 7848For plotting, @var{obj} is a handle to a graphics object. 7849 7850Programming Note: There is no support in Octave versions 6.X.X for @var{obj} 7851to be an instance of a class (i.e., a classdef object). This functionality 7852has already been added on the development branch which will become Octave 78537.1.0. 7854@xseealso{@ref{XREFget,,get}, @ref{XREFset,,set}, @ref{XREFismethod,,ismethod}, @ref{XREFisobject,,isobject}} 7855@end deftypefn 7856 7857 7858@node Graphics Objects 7859@subsection Graphics Objects 7860@cindex graphics objects 7861 7862The hierarchy of graphics objects was explained above. 7863@xref{Introduction to Graphics Structures}. Here the 7864specific objects are described, and the properties contained in 7865these objects are discussed. Keep in mind that 7866graphics objects are always referenced by @dfn{handle}. 7867 7868@table @asis 7869@c @group 7870 7871@item root 7872@cindex root graphics object 7873@cindex graphics object, root 7874The top level of the hierarchy and the parent of all figure objects. 7875Use @code{groot} to obtain the handle of the root graphics object. 7876 7877@item figure 7878@cindex figure graphics object 7879@cindex graphics object, figure 7880A figure window. 7881 7882@item axes 7883@cindex axes graphics object 7884@cindex graphics object, axes 7885A set of axes. This object is a child of a figure object and may be a 7886parent of line, text, image, patch, surface, or light objects. 7887 7888@item line 7889@cindex line graphics object 7890@cindex graphics object, line 7891A line in two or three dimensions. 7892 7893@item text 7894@cindex text graphics object 7895@cindex graphics object, text 7896Text annotations. 7897 7898@item image 7899@cindex image graphics object 7900@cindex graphics object, image 7901A bitmap image. 7902 7903@item patch 7904@cindex patch graphics object 7905@cindex graphics object, patch 7906A filled polygon, currently limited to two dimensions. 7907 7908@item surface 7909@cindex surface graphics object 7910@cindex graphics object, surface 7911A three-dimensional surface. 7912 7913@item light 7914@cindex light graphics object 7915@cindex graphics object, light 7916A light object used for lighting effects on patches and surfaces. 7917@c @end group 7918@end table 7919 7920@subsubsection Creating Graphics Objects 7921@cindex creating graphics objects 7922 7923You can create any graphics object primitive by calling the function of the 7924same name as the object; In other words, @code{figure}, @code{axes}, 7925@code{line}, @code{text}, @code{image}, @code{patch}, @code{surface}, and 7926@code{light} functions. These fundamental graphic objects automatically become 7927children of the current axes object as if @code{hold on} was in place. 7928Separately, axes will automatically become children of the current figure 7929object and figures will become children of the root object. 7930 7931If this auto-joining feature is not desired then it is important to call 7932@code{newplot} first to prepare a new figure and axes for plotting. 7933Alternatively, the easier way is to call a high-level graphics routine which 7934will both create the plot and then populate it with low-level graphics objects. 7935Instead of calling @code{line}, use @code{plot}. Or use @code{surf} instead of 7936@code{surface}. Or use @code{fill} instead of @code{patch}. 7937 7938@c axes scripts/plot/util/axes.m 7939@anchor{XREFaxes} 7940@deftypefn {} {} axes () 7941@deftypefnx {} {} axes (@var{property}, @var{value}, @dots{}) 7942@deftypefnx {} {} axes (@var{hpar}, @var{property}, @var{value}, @dots{}) 7943@deftypefnx {} {} axes (@var{hax}) 7944@deftypefnx {} {@var{h} =} axes (@dots{}) 7945Create a Cartesian axes object and return a handle to it, or set the current 7946axes to @var{hax}. 7947 7948Called without any arguments, or with @var{property}/@var{value} pairs, 7949construct a new axes. The optional argument @var{hpar} is a graphics handle 7950specifying the parent for the new axes and may be a figure, uipanel, or 7951uitab. 7952 7953Called with a single axes handle argument @var{hax}, the function makes 7954@var{hax} the current axes (as returned by @code{gca}). It also makes 7955the figure which contains @var{hax} the current figure (as returned by 7956@code{gcf}). Finally, it restacks the parent object's @code{children} 7957property so that the axes @var{hax} appears before all other axes handles 7958in the list. This causes @var{hax} to be displayed on top of any other axes 7959objects (Z-order stacking). In addition it restacks any legend or colorbar 7960objects associated with @var{hax} so that they are also visible. 7961 7962Programming Note: The full list of properties is documented at 7963@ref{Axes Properties}. 7964@xseealso{@ref{XREFgca,,gca}, @ref{XREFset,,set}, @ref{XREFget,,get}} 7965@end deftypefn 7966 7967 7968@c line scripts/plot/draw/line.m 7969@anchor{XREFline} 7970@deftypefn {} {} line () 7971@deftypefnx {} {} line (@var{x}, @var{y}) 7972@deftypefnx {} {} line (@var{x}, @var{y}, @var{z}) 7973@deftypefnx {} {} line ("xdata", @var{x}, "ydata", @var{y}) 7974@deftypefnx {} {} line ("xdata", @var{x}, "ydata", @var{y}, "zdata", @var{z}) 7975@deftypefnx {} {} line (@dots{}, @var{property}, @var{value}) 7976@deftypefnx {} {} line (@var{hax}, @dots{}) 7977@deftypefnx {} {@var{h} =} line (@dots{}) 7978Create a line object from @var{x} and @var{y} (and possibly @var{z}) and 7979insert it in the current axes. 7980 7981In the standard calling form the data @var{x}, @var{y}, and @var{z} may be 7982scalars, vectors, or matrices. In the case of matrix inputs, @code{line} 7983will attempt to orient scalars and vectors so the results can be plotted. 7984This requires that one of the dimensions of the vector match either the 7985number of rows or the number of columns of the matrix. 7986 7987In the low-level calling form (50% higher performance) where the data is 7988specified by name (@code{line ("xdata", @var{x}, @dots{})}) the data must be 7989vectors. If no data is specified (@code{line ()}) then 7990@w{@code{@var{x} == @var{y} = [0, 1]}}. 7991 7992Multiple property-value pairs may be specified for the line object, but they 7993must appear in pairs. 7994 7995If called with only @var{property}/@var{value} pairs then any unspecified 7996properties use their default values as specified on the root object. 7997 7998If the first argument @var{hax} is an axes handle, then plot into this axes, 7999rather than the current axes returned by @code{gca}. 8000 8001The optional return value @var{h} is a graphics handle (or vector of 8002handles) to the line objects created. 8003 8004Programming Note: The full list of properties is documented at 8005@ref{Line Properties}. 8006 8007The function @code{line} differs from @code{plot} in that line objects are 8008inserted in to the current axes without first clearing the plot. 8009@xseealso{@ref{XREFimage,,image}, @ref{XREFpatch,,patch}, @ref{XREFrectangle,,rectangle}, @ref{XREFsurface,,surface}, @ref{XREFtext,,text}} 8010@end deftypefn 8011 8012 8013@c patch scripts/plot/draw/patch.m 8014@anchor{XREFpatch} 8015@deftypefn {} {} patch () 8016@deftypefnx {} {} patch (@var{x}, @var{y}, @var{c}) 8017@deftypefnx {} {} patch (@var{x}, @var{y}, @var{z}, @var{c}) 8018@deftypefnx {} {} patch ("Faces", @var{faces}, "Vertices", @var{verts}, @dots{}) 8019@deftypefnx {} {} patch (@dots{}, @var{prop}, @var{val}, @dots{}) 8020@deftypefnx {} {} patch (@dots{}, @var{propstruct}, @dots{}) 8021@deftypefnx {} {} patch (@var{hax}, @dots{}) 8022@deftypefnx {} {@var{h} =} patch (@dots{}) 8023Create patch object in the current axes with vertices at locations 8024(@var{x}, @var{y}) and of color @var{c}. 8025 8026If the vertices are matrices of size @nospell{MxN} then each polygon patch 8027has M vertices and a total of N polygons will be created. If some polygons 8028do not have M vertices use NaN to represent "no vertex". If the @var{z} 8029input is present then 3-D patches will be created. 8030 8031The color argument @var{c} can take many forms. To create polygons 8032which all share a single color use a string value (e.g., @qcode{"r"} for 8033red), a scalar value which is scaled by @code{caxis} and indexed into the 8034current colormap, or a 3-element RGB vector with the precise TrueColor. 8035 8036If @var{c} is a vector of length N then the ith polygon will have a color 8037determined by scaling entry @var{c}(i) according to @code{caxis} and then 8038indexing into the current colormap. More complicated coloring situations 8039require directly manipulating patch property/value pairs. 8040 8041Instead of specifying polygons by matrices @var{x} and @var{y}, it is 8042possible to present a unique list of vertices and then a list of polygon 8043faces created from those vertices. In this case the 8044@qcode{"Vertices"} matrix will be an @nospell{Nx2} (2-D patch) or 8045@nospell{Nx3} (3-D patch). The @nospell{MxN} @qcode{"Faces"} matrix 8046describes M polygons having N vertices---each row describes a 8047single polygon and each column entry is an index into the 8048@qcode{"Vertices"} matrix to identify a vertex. The patch object 8049can be created by directly passing the property/value pairs 8050@qcode{"Vertices"}/@var{verts}, @qcode{"Faces"}/@var{faces} as 8051inputs. 8052 8053Instead of using property/value pairs, any property can be set by passing a 8054structure @var{propstruct} with the respective field names. 8055 8056If the first argument @var{hax} is an axes handle, then plot into this axes, 8057rather than the current axes returned by @code{gca}. 8058 8059The optional return value @var{h} is a graphics handle to the created patch 8060object. 8061 8062Programming Note: The full list of properties is documented at 8063@ref{Patch Properties}. Useful patch properties include: 8064@qcode{"cdata"}, @qcode{"edgecolor"}, @qcode{"facecolor"}, @qcode{"faces"}, 8065and @qcode{"facevertexcdata"}. 8066@xseealso{@ref{XREFfill,,fill}, @ref{XREFget,,get}, @ref{XREFset,,set}} 8067@end deftypefn 8068 8069 8070@c surface scripts/plot/draw/surface.m 8071@anchor{XREFsurface} 8072@deftypefn {} {} surface (@var{x}, @var{y}, @var{z}, @var{c}) 8073@deftypefnx {} {} surface (@var{x}, @var{y}, @var{z}) 8074@deftypefnx {} {} surface (@var{z}, @var{c}) 8075@deftypefnx {} {} surface (@var{z}) 8076@deftypefnx {} {} surface (@dots{}, @var{prop}, @var{val}, @dots{}) 8077@deftypefnx {} {} surface (@var{hax}, @dots{}) 8078@deftypefnx {} {@var{h} =} surface (@dots{}) 8079Create a surface graphic object given matrices @var{x} and @var{y} from 8080@code{meshgrid} and a matrix of values @var{z} corresponding to the 8081@var{x} and @var{y} coordinates of the surface. 8082 8083If @var{x} and @var{y} are vectors, then a typical vertex is 8084(@var{x}(j), @var{y}(i), @var{z}(i,j)). Thus, columns of @var{z} correspond 8085to different @var{x} values and rows of @var{z} correspond to different 8086@var{y} values. If only a single input @var{z} is given then @var{x} is 8087taken to be @code{1:columns (@var{z})} and @var{y} is 8088@code{1:rows (@var{z})}. 8089 8090Any property/value input pairs are assigned to the surface object. 8091 8092If the first argument @var{hax} is an axes handle, then plot into this axes, 8093rather than the current axes returned by @code{gca}. 8094 8095The optional return value @var{h} is a graphics handle to the created 8096surface object. 8097 8098Programming Note: The full list of properties is documented at 8099@ref{Surface Properties}. 8100@xseealso{@ref{XREFsurf,,surf}, @ref{XREFmesh,,mesh}, @ref{XREFpatch,,patch}, @ref{XREFline,,line}} 8101@end deftypefn 8102 8103 8104@c light scripts/plot/draw/light.m 8105@anchor{XREFlight} 8106@deftypefn {} {} light () 8107@deftypefnx {} {} light (@dots{}, "@var{prop}", @var{val}, @dots{}) 8108@deftypefnx {} {} light (@var{hax}, @dots{}) 8109@deftypefnx {} {@var{h} =} light (@dots{}) 8110Create a light object in the current axes or for axes @var{hax}. 8111 8112When a light object is present in an axes object, and the properties 8113@qcode{"EdgeLighting"} or @qcode{"FaceLighting"} of a @code{patch} or 8114@code{surface} object are set to a value other than @qcode{"none"}, these 8115objects are drawn with lighting effects. Supported values for Lighting 8116properties are @qcode{"none"} (no lighting effects), @qcode{"flat"} (faceted 8117look of the objects), and @qcode{"gouraud"} (linear interpolation of the 8118lighting effects between the vertices). If the lighting mode is set to 8119@qcode{"flat"}, the @qcode{"FaceNormals"} property is used for lighting. 8120For @qcode{"gouraud"}, the @qcode{"VertexNormals"} property is used. 8121 8122Up to eight light objects are supported per axes. (Implementation 8123dependent) 8124 8125Lighting is only supported for OpenGL graphic toolkits (i.e., @qcode{"fltk"} 8126and @qcode{"qt"}). 8127 8128A light object has the following properties which alter the appearance of 8129the plot. 8130 8131@table @asis 8132@item @qcode{"Color":} The color of the light can be passed as an 8133RGB-vector (e.g., @code{[1 0 0]} for red) or as a string (e.g., @qcode{"r"} 8134for red). The default color is white (@code{[1 1 1]}). 8135 8136@item @qcode{"Position":} The direction from which the light emanates as a 81371x3-vector. The default direction is @code{[1 0 1]}. 8138 8139@item @qcode{"Style":} This string defines whether the light emanates from a 8140light source at infinite distance (@qcode{"infinite"}) or from a local point 8141source (@qcode{"local"}). The default is @qcode{"infinite"}. 8142@end table 8143 8144If the first argument @var{hax} is an axes handle, then add the light object 8145to this axes, rather than the current axes returned by @code{gca}. 8146 8147The optional return value @var{h} is a graphics handle to the created light 8148object. 8149 8150Programming Note: The full list of properties is documented at 8151@ref{Light Properties}. 8152@xseealso{@ref{XREFlighting,,lighting}, @ref{XREFmaterial,,material}, @ref{XREFpatch,,patch}, @ref{XREFsurface,,surface}} 8153@end deftypefn 8154 8155 8156@subsubsection Handle Functions 8157@cindex handle functions 8158 8159To determine whether a variable is a graphics object index, or an index 8160to an axes or figure, use the functions @code{ishghandle}, @code{isgraphics}, 8161@code{isaxes}, and @code{isfigure}. 8162 8163@c ishghandle libinterp/corefcn/graphics.cc 8164@anchor{XREFishghandle} 8165@deftypefn {} {} ishghandle (@var{h}) 8166Return true if @var{h} is a graphics handle and false otherwise. 8167 8168@var{h} may also be a matrix of handles in which case a logical array is 8169returned that is true where the elements of @var{h} are graphics handles and 8170false where they are not. 8171@xseealso{@ref{XREFisgraphics,,isgraphics}, @ref{XREFisaxes,,isaxes}, @ref{XREFisfigure,,isfigure}, @ref{XREFishandle,,ishandle}} 8172@end deftypefn 8173 8174 8175@c isgraphics scripts/plot/util/isgraphics.m 8176@anchor{XREFisgraphics} 8177@deftypefn {} {} isgraphics (@var{h}) 8178@deftypefnx {} {} isgraphics (@var{h}, @var{type}) 8179Return true if @var{h} is a graphics handle (of type @var{type}) and false 8180otherwise. 8181 8182When no @var{type} is specified the function is equivalent to 8183@code{ishghandle}. 8184@xseealso{@ref{XREFishghandle,,ishghandle}, @ref{XREFishandle,,ishandle}, @ref{XREFisaxes,,isaxes}, @ref{XREFisfigure,,isfigure}} 8185@end deftypefn 8186 8187 8188@c ishandle scripts/plot/util/ishandle.m 8189@anchor{XREFishandle} 8190@deftypefn {} {} ishandle (@var{h}) 8191Return true if @var{h} is a handle to a graphics or Java object and false 8192otherwise. 8193 8194@var{h} may also be a matrix of handles in which case a logical array is 8195returned that is true where the elements of @var{h} are handles to graphics 8196or Java objects and false where they are not. 8197 8198Programming Note: It is often more useful to test for a specific object 8199type. To determine if a handle belongs to a graphics object use 8200@code{ishghandle} or @code{isgraphics}. To determine if a handle belongs 8201to a Java object use @code{isjava}. 8202@xseealso{@ref{XREFishghandle,,ishghandle}, @ref{XREFisgraphics,,isgraphics}, @ref{XREFisjava,,isjava}} 8203@end deftypefn 8204 8205 8206@c isaxes scripts/plot/util/isaxes.m 8207@anchor{XREFisaxes} 8208@deftypefn {} {} isaxes (@var{h}) 8209Return true if @var{h} is an axes graphics handle and false otherwise. 8210 8211If @var{h} is a matrix then return a logical array which is true where the 8212elements of @var{h} are axes graphics handles and false where they are not. 8213@xseealso{@ref{XREFisfigure,,isfigure}, @ref{XREFishghandle,,ishghandle}, @ref{XREFisgraphics,,isgraphics}} 8214@end deftypefn 8215 8216 8217@c isfigure scripts/plot/util/isfigure.m 8218@anchor{XREFisfigure} 8219@deftypefn {} {} isfigure (@var{h}) 8220Return true if @var{h} is a figure graphics handle and false otherwise. 8221 8222If @var{h} is a matrix then return a logical array which is true where the 8223elements of @var{h} are figure graphics handles and false where they are 8224not. 8225@xseealso{@ref{XREFisaxes,,isaxes}, @ref{XREFishghandle,,ishghandle}, @ref{XREFisgraphics,,isgraphics}} 8226@end deftypefn 8227 8228 8229The function @code{gcf} returns an index to the current figure object, 8230or creates one if none exists. Similarly, @code{gca} returns the 8231current axes object, or creates one (and its parent figure object) if 8232none exists. 8233 8234@c groot scripts/plot/util/groot.m 8235@anchor{XREFgroot} 8236@deftypefn {} {@var{h} =} groot () 8237Return a handle to the root graphics object. 8238 8239The root graphics object is the ultimate parent of all graphics objects. 8240 8241In addition, the root object contains information about the graphics 8242system as a whole such as the @code{ScreenSize}. Use @w{@code{get (groot)}} 8243to find out what information is available. 8244 8245Defaults for the graphic system as a whole are specified by setting 8246properties of the root graphics object that begin with @qcode{"Default"}. 8247For example, to set the default font for all text objects to FreeSans use 8248 8249@example 8250set (groot, "DefaultTextFontName", "FreeSans") 8251@end example 8252 8253Default properties can be deleted by using @code{set} with the special 8254property value of @qcode{"remove"}. To undo the default font assignment 8255above use 8256 8257@example 8258set (groot, "DefaultTextFontName", "remove") 8259@end example 8260 8261Programming Note: The root graphics object is identified by the special 8262handle value of 0. At some point this unique value may change, but code can 8263be made resistant to future changes by using @code{groot} which is 8264guaranteed to always return the root graphics object. 8265@xseealso{@ref{XREFgcf,,gcf}, @ref{XREFgca,,gca}, @ref{XREFget,,get}, @ref{XREFset,,set}} 8266@end deftypefn 8267 8268 8269@c gcf scripts/plot/util/gcf.m 8270@anchor{XREFgcf} 8271@deftypefn {} {@var{h} =} gcf () 8272Return a handle to the current figure. 8273 8274The current figure is the default target for graphics output. If multiple 8275figures exist, @code{gcf} returns the last created figure or the last figure 8276that was clicked on with the mouse. 8277 8278If a current figure does not exist, create one and return its handle. The 8279handle may then be used to examine or set properties of the figure. For 8280example, 8281 8282@example 8283@group 8284fplot (@@sin, [-10, 10]); 8285fig = gcf (); 8286set (fig, "numbertitle", "off", "name", "sin plot") 8287@end group 8288@end example 8289 8290@noindent 8291plots a sine wave, finds the handle of the current figure, and then 8292renames the figure window to describe the contents. 8293 8294Note: To find the current figure without creating a new one if it does not 8295exist, query the @qcode{"CurrentFigure"} property of the root graphics 8296object. 8297 8298@example 8299get (groot, "currentfigure"); 8300@end example 8301 8302@xseealso{@ref{XREFgca,,gca}, @ref{XREFgco,,gco}, @ref{XREFgcbf,,gcbf}, @ref{XREFgcbo,,gcbo}, @ref{XREFget,,get}, @ref{XREFset,,set}} 8303@end deftypefn 8304 8305 8306@c gca scripts/plot/util/gca.m 8307@anchor{XREFgca} 8308@deftypefn {} {@var{h} =} gca () 8309Return a handle to the current axes object. 8310 8311The current axes is the default target for graphics output. In the case 8312of a figure with multiple axes, @code{gca} returns the last created axes 8313or the last axes that was clicked on with the mouse. 8314 8315If no current axes object exists, create one and return its handle. The 8316handle may then be used to examine or set properties of the axes. For 8317example, 8318 8319@example 8320@group 8321ax = gca (); 8322set (ax, "position", [0.5, 0.5, 0.5, 0.5]); 8323@end group 8324@end example 8325 8326@noindent 8327creates an empty axes object and then changes its location and size in the 8328figure window. 8329 8330Note: To find the current axes without creating a new axes object if it 8331does not exist, query the @qcode{"CurrentAxes"} property of a figure. 8332 8333@example 8334get (gcf, "currentaxes"); 8335@end example 8336@xseealso{@ref{XREFgcf,,gcf}, @ref{XREFgco,,gco}, @ref{XREFgcbf,,gcbf}, @ref{XREFgcbo,,gcbo}, @ref{XREFget,,get}, @ref{XREFset,,set}} 8337@end deftypefn 8338 8339 8340@c gco scripts/plot/util/gco.m 8341@anchor{XREFgco} 8342@deftypefn {} {@var{h} =} gco () 8343@deftypefnx {} {@var{h} =} gco (@var{fig}) 8344Return a handle to the current object of the current figure, or a handle 8345to the current object of the figure with handle @var{fig}. 8346 8347The current object of a figure is the object that was last clicked on. It 8348is stored in the @qcode{"CurrentObject"} property of the target figure. 8349 8350If the last mouse click did not occur on any child object of the figure, 8351then the current object is the figure itself. 8352 8353If no mouse click occurred in the target figure, this function returns an 8354empty matrix. 8355 8356Programming Note: The value returned by this function is not necessarily the 8357same as the one returned by @code{gcbo} during callback execution. An 8358executing callback can be interrupted by another callback and the current 8359object may be changed. 8360 8361@xseealso{@ref{XREFgcbo,,gcbo}, @ref{XREFgca,,gca}, @ref{XREFgcf,,gcf}, @ref{XREFgcbf,,gcbf}, @ref{XREFget,,get}, @ref{XREFset,,set}} 8362@end deftypefn 8363 8364 8365The @code{get} and @code{set} functions may be used to examine and set 8366properties for graphics objects. For example, 8367 8368@example 8369@group 8370get (groot) 8371 @result{} ans = 8372 @{ 8373 type = root 8374 currentfigure = [](0x0) 8375 children = [](0x0) 8376 visible = on 8377 @dots{} 8378 @} 8379@end group 8380@end example 8381 8382@noindent 8383returns a structure containing all the properties of the root graphics object. 8384As with all functions in Octave, the structure is returned by value, so 8385modifying it will not modify the internal root object. To do that, you must 8386use the @code{set} function. Also, note that in this case, the 8387@code{currentfigure} property is empty, which indicates that there is no 8388current figure window. 8389 8390The @code{get} function may also be used to find the value of a single 8391property. For example, 8392 8393@example 8394@group 8395get (gca (), "xlim") 8396 @result{} [ 0 1 ] 8397@end group 8398@end example 8399 8400@noindent 8401returns the range of the x-axis for the current axes object in the 8402current figure. 8403 8404To set graphics object properties, use the set function. For example, 8405 8406@example 8407set (gca (), "xlim", [-10, 10]); 8408@end example 8409 8410@noindent 8411sets the range of the x-axis for the current axes object in the current 8412figure to @samp{[-10, 10]}. 8413 8414Default property values can also be queried if the @code{set} function is 8415called without a value argument. When only one argument is given (a graphic 8416handle) then a structure with defaults for all properties of the given object 8417type is returned. For example, 8418 8419@example 8420set (gca ()) 8421@end example 8422 8423@noindent 8424returns a structure containing the default property values for axes objects. 8425If @code{set} is called with two arguments (a graphic handle and a property 8426name) then only the defaults for the requested property are returned. 8427 8428@c get libinterp/corefcn/graphics.cc 8429@anchor{XREFget} 8430@deftypefn {} {@var{val} =} get (@var{h}) 8431@deftypefnx {} {@var{val} =} get (@var{h}, @var{p}) 8432Return the value of the named property @var{p} from the graphics handle 8433@var{h}. 8434 8435If @var{p} is omitted, return the complete property list for @var{h}. 8436 8437If @var{h} is a vector, return a cell array including the property values or 8438lists respectively. 8439@xseealso{@ref{XREFset,,set}} 8440@end deftypefn 8441 8442 8443@c set libinterp/corefcn/graphics.cc 8444@anchor{XREFset} 8445@deftypefn {} {} set (@var{h}, @var{property}, @var{value}, @dots{}) 8446@deftypefnx {} {} set (@var{h}, @var{properties}, @var{values}) 8447@deftypefnx {} {} set (@var{h}, @var{pv}) 8448@deftypefnx {} {@var{value_list} =} set (@var{h}, @var{property}) 8449@deftypefnx {} {@var{all_value_list} =} set (@var{h}) 8450Set named property values for the graphics handle (or vector of graphics 8451handles) @var{h}. 8452 8453There are three ways to give the property names and values: 8454 8455@itemize 8456@item as a comma separated list of @var{property}, @var{value} pairs 8457 8458Here, each @var{property} is a string containing the property name, each 8459@var{value} is a value of the appropriate type for the property. 8460 8461@item as a cell array of strings @var{properties} containing property names 8462and a cell array @var{values} containing property values. 8463 8464In this case, the number of columns of @var{values} must match the number of 8465elements in @var{properties}. The first column of @var{values} contains 8466values for the first entry in @var{properties}, etc. The number of rows of 8467@var{values} must be 1 or match the number of elements of @var{h}. In the 8468first case, each handle in @var{h} will be assigned the same values. In the 8469latter case, the first handle in @var{h} will be assigned the values from 8470the first row of @var{values} and so on. 8471 8472@item as a structure array @var{pv} 8473 8474Here, the field names of @var{pv} represent the property names, and the 8475field values give the property values. In contrast to the previous case, 8476all elements of @var{pv} will be set in all handles in @var{h} independent 8477of the dimensions of @var{pv}. 8478@end itemize 8479 8480@code{set} is also used to query the list of values a named property will 8481take. @code{@var{clist} = set (@var{h}, "property")} will return the list 8482of possible values for @qcode{"property"} in the cell list @var{clist}. 8483If no output variable is used then the list is formatted and printed to the 8484screen. 8485 8486If no property is specified (@code{@var{slist} = set (@var{h})}) then a 8487structure @var{slist} is returned where the fieldnames are the properties of 8488the object @var{h} and the fields are the list of possible values for each 8489property. If no output variable is used then the list is formatted and 8490printed to the screen. 8491 8492For example, 8493 8494@example 8495@group 8496hf = figure (); 8497set (hf, "paperorientation") 8498@result{} [ landscape | @{portrait@} ] 8499@end group 8500@end example 8501 8502@noindent 8503shows the paperorientation property can take two values with the default 8504being @qcode{"portrait"}. 8505@xseealso{@ref{XREFget,,get}} 8506@end deftypefn 8507 8508 8509@c ancestor scripts/plot/util/ancestor.m 8510@anchor{XREFancestor} 8511@deftypefn {} {@var{parent} =} ancestor (@var{h}, @var{type}) 8512@deftypefnx {} {@var{parent} =} ancestor (@var{h}, @var{type}, "toplevel") 8513Return the first ancestor of handle object @var{h} whose type matches 8514@var{type}, where @var{type} is a character string. 8515 8516If @var{type} is a cell array of strings, return the first parent whose 8517type matches any of the given type strings. 8518 8519If the handle object @var{h} itself is of type @var{type}, return @var{h}. 8520 8521If @qcode{"toplevel"} is given as a third argument, return the highest 8522parent in the object hierarchy that matches the condition, instead 8523of the first (nearest) one. 8524@xseealso{@ref{XREFfindobj,,findobj}, @ref{XREFfindall,,findall}, @ref{XREFallchild,,allchild}} 8525@end deftypefn 8526 8527 8528@c allchild scripts/plot/util/allchild.m 8529@anchor{XREFallchild} 8530@deftypefn {} {@var{h} =} allchild (@var{handles}) 8531Find all children, including hidden children, of a graphics object. 8532 8533This function is similar to @code{get (h, "children")}, but also returns 8534hidden objects (HandleVisibility = @qcode{"off"}). 8535 8536If @var{handles} is a scalar, @var{h} will be a vector. Otherwise, 8537@var{h} will be a cell matrix of the same size as @var{handles} and each 8538cell will contain a vector of handles. 8539@xseealso{@ref{XREFfindall,,findall}, @ref{XREFfindobj,,findobj}, @ref{XREFget,,get}, @ref{XREFset,,set}} 8540@end deftypefn 8541 8542 8543@c findfigs scripts/plot/util/findfigs.m 8544@anchor{XREFfindfigs} 8545@deftypefn {} {} findfigs () 8546Find all visible figures that are currently off the screen and move them 8547onto the screen. 8548@xseealso{@ref{XREFallchild,,allchild}, @ref{XREFfigure,,figure}, @ref{XREFget,,get}, @ref{XREFset,,set}} 8549@end deftypefn 8550 8551 8552@cindex saving graphics objects 8553@cindex graphics objects, saving 8554 8555Figures can be printed or saved in many graphics formats with @code{print} and 8556@code{saveas}. Occasionally, however, it may be useful to save the original 8557Octave handle graphic directly so that further modifications can be made such 8558as modifying a title or legend. 8559 8560This can be accomplished with the following functions by 8561 8562@example 8563@group 8564fig_struct = hdl2struct (gcf); 8565save myplot.fig -struct fig_struct; 8566@dots{} 8567fig_struct = load ("myplot.fig"); 8568struct2hdl (fig_struct); 8569@end group 8570@end example 8571 8572@c hdl2struct scripts/plot/util/hdl2struct.m 8573@anchor{XREFhdl2struct} 8574@deftypefn {} {@var{s} =} hdl2struct (@var{h}) 8575Return a structure, @var{s}, whose fields describe the properties 8576of the object, and its children, associated with the handle, @var{h}. 8577 8578The fields of the structure @var{s} are @qcode{"type"}, @qcode{"handle"}, 8579@qcode{"properties"}, @qcode{"children"}, and @qcode{"special"}. 8580@xseealso{@ref{XREFstruct2hdl,,struct2hdl}, @ref{XREFhgsave,,hgsave}, @ref{XREFfindobj,,findobj}} 8581@end deftypefn 8582 8583 8584@c struct2hdl scripts/plot/util/struct2hdl.m 8585@anchor{XREFstruct2hdl} 8586@deftypefn {} {@var{h} =} struct2hdl (@var{s}) 8587@deftypefnx {} {@var{h} =} struct2hdl (@var{s}, @var{p}) 8588@deftypefnx {} {@var{h} =} struct2hdl (@var{s}, @var{p}, @var{hilev}) 8589Construct a graphics handle object @var{h} from the structure @var{s}. 8590 8591The structure must contain the fields @qcode{"handle"}, @qcode{"type"}, 8592@qcode{"children"}, @qcode{"properties"}, and @qcode{"special"}. 8593 8594If the handle of an existing figure or axes is specified, @var{p}, the new 8595object will be created as a child of that object. If no parent handle is 8596provided then a new figure and the necessary children will be constructed 8597using the default values from the root object. 8598 8599A third boolean argument @var{hilev} can be passed to specify whether the 8600function should preserve listeners/callbacks, e.g., for legends or 8601hggroups. The default is false. 8602@xseealso{@ref{XREFhdl2struct,,hdl2struct}, @ref{XREFhgload,,hgload}, @ref{XREFfindobj,,findobj}} 8603@end deftypefn 8604 8605 8606@c copyobj scripts/plot/util/copyobj.m 8607@anchor{XREFcopyobj} 8608@deftypefn {} {@var{hnew} =} copyobj (@var{horig}) 8609@deftypefnx {} {@var{hnew} =} copyobj (@var{horig}, @var{hparent}) 8610Construct a copy of the graphic objects associated with the handles 8611@var{horig} and return new handles @var{hnew} to the new objects. 8612 8613If a parent handle @var{hparent} (root, figure, axes, or hggroup) is 8614specified, the copied object will be created as a child of @var{hparent}. 8615 8616If @var{horig} is a vector of handles, and @var{hparent} is a scalar, 8617then each handle in the vector @var{hnew} has its @qcode{"Parent"} property 8618set to @var{hparent}. Conversely, if @var{horig} is a scalar and 8619@var{hparent} a vector, then each parent object will receive a copy of 8620@var{horig}. If @var{horig} and @var{hparent} are both vectors with the 8621same number of elements then @code{@var{hnew}(i)} will have parent 8622@code{@var{hparent}(i)}. 8623@xseealso{@ref{XREFstruct2hdl,,struct2hdl}, @ref{XREFhdl2struct,,hdl2struct}, @ref{XREFfindobj,,findobj}} 8624@end deftypefn 8625 8626 8627@node Graphics Object Properties 8628@subsection Graphics Object Properties 8629@cindex graphics object properties 8630 8631@menu 8632* Root Properties:: 8633* Figure Properties:: 8634* Axes Properties:: 8635* Legend Properties:: 8636* Line Properties:: 8637* Text Properties:: 8638* Image Properties:: 8639* Patch Properties:: 8640* Surface Properties:: 8641* Light Properties:: 8642* Uimenu Properties:: 8643* Uibuttongroup Properties:: 8644* Uicontextmenu Properties:: 8645* Uipanel Properties:: 8646* Uicontrol Properties:: 8647* Uitable Properties:: 8648* Uitoolbar Properties:: 8649* Uipushtool Properties:: 8650* Uitoggletool Properties:: 8651@end menu 8652 8653In this section the graphics object properties are discussed in detail, 8654starting with the root properties and continuing through the object hierarchy. 8655The documentation about a specific graphics object can be displayed using 8656@code{doc} function, e.g., @code{doc ("axes properties")} will show 8657@ref{Axes Properties}. 8658 8659The allowed values for radio (string) properties can be retrieved 8660programmatically or displayed using the one or two argument calling form of the 8661@code{set} function. @xref{XREFset, , set}. 8662 8663In the following documentation default values are enclosed in @{ @}. 8664 8665@node Root Properties 8666@subsubsection Root Properties 8667@prindex @sortas{@ Root Properties} Root Properties 8668 8669@include plot-rootproperties.texi 8670 8671 8672@node Figure Properties 8673@subsubsection Figure Properties 8674@prindex @sortas{@ Figure Properties} Figure Properties 8675 8676@include plot-figureproperties.texi 8677 8678 8679@node Axes Properties 8680@subsubsection Axes Properties 8681@prindex @sortas{@ Axes Properties} Axes Properties 8682 8683@include plot-axesproperties.texi 8684 8685 8686@node Legend Properties 8687@subsubsection Legend Properties 8688@prindex @sortas{@ Legend Properties} Legend Properties 8689 8690@include plot-legendproperties.texi 8691 8692 8693@node Line Properties 8694@subsubsection Line Properties 8695@prindex @sortas{@ Line Properties} Line Properties 8696 8697@include plot-lineproperties.texi 8698 8699 8700@node Text Properties 8701@subsubsection Text Properties 8702@prindex @sortas{@ Text Properties} Text Properties 8703 8704@include plot-textproperties.texi 8705 8706 8707@node Image Properties 8708@subsubsection Image Properties 8709@prindex @sortas{@ Image Properties} Image Properties 8710 8711@include plot-imageproperties.texi 8712 8713 8714@node Patch Properties 8715@subsubsection Patch Properties 8716@prindex @sortas{@ Patch Properties} Patch Properties 8717 8718@include plot-patchproperties.texi 8719 8720 8721@node Surface Properties 8722@subsubsection Surface Properties 8723@prindex @sortas{@ Surface Properties} Surface Properties 8724 8725@include plot-surfaceproperties.texi 8726 8727 8728@node Light Properties 8729@subsubsection Light Properties 8730@prindex @sortas{@ Light Properties} Light Properties 8731 8732@include plot-lightproperties.texi 8733 8734 8735@node Uimenu Properties 8736@subsubsection Uimenu Properties 8737@prindex @sortas{@ Uimenu Properties} Uimenu Properties 8738 8739@include plot-uimenuproperties.texi 8740 8741 8742@node Uibuttongroup Properties 8743@subsubsection Uibuttongroup Properties 8744@prindex @sortas{@ Uibuttongroup Properties} Uibuttongroup Properties 8745 8746@include plot-uibuttongroupproperties.texi 8747 8748 8749@node Uicontextmenu Properties 8750@subsubsection Uicontextmenu Properties 8751@prindex @sortas{@ Uicontextmenu Properties} Uicontextmenu Properties 8752 8753@include plot-uicontextmenuproperties.texi 8754 8755 8756@node Uipanel Properties 8757@subsubsection Uipanel Properties 8758@prindex @sortas{@ Uipanel Properties} Uipanel Properties 8759 8760@include plot-uipanelproperties.texi 8761 8762 8763@node Uicontrol Properties 8764@subsubsection Uicontrol Properties 8765@prindex @sortas{@ Uicontrol Properties} Uicontrol Properties 8766 8767@include plot-uicontrolproperties.texi 8768 8769 8770@node Uitable Properties 8771@subsubsection Uitable Properties 8772@cindex uitable properties 8773 8774@include plot-uitableproperties.texi 8775 8776 8777@node Uitoolbar Properties 8778@subsubsection Uitoolbar Properties 8779@prindex @sortas{@ Uitoolbar Properties} Uitoolbar Properties 8780 8781@include plot-uitoolbarproperties.texi 8782 8783 8784@node Uipushtool Properties 8785@subsubsection Uipushtool Properties 8786@prindex @sortas{@ Uipushtool Properties} Uipushtool Properties 8787 8788@include plot-uipushtoolproperties.texi 8789 8790 8791@node Uitoggletool Properties 8792@subsubsection Uitoggletool Properties 8793@prindex @sortas{@ Uitoggletool Properties} Uitoggletool Properties 8794 8795@include plot-uitoggletoolproperties.texi 8796 8797 8798@node Searching Properties 8799@subsection Searching Properties 8800 8801@c findobj scripts/plot/util/findobj.m 8802@anchor{XREFfindobj} 8803@deftypefn {} {@var{h} =} findobj () 8804@deftypefnx {} {@var{h} =} findobj (@var{prop_name}, @var{prop_value}, @dots{}) 8805@deftypefnx {} {@var{h} =} findobj (@var{prop_name}, @var{prop_value}, "-@var{logical_op}", @var{prop_name}, @var{prop_value}) 8806@deftypefnx {} {@var{h} =} findobj ("-property", @var{prop_name}) 8807@deftypefnx {} {@var{h} =} findobj ("-regexp", @var{prop_name}, @var{pattern}) 8808@deftypefnx {} {@var{h} =} findobj (@var{hlist}, @dots{}) 8809@deftypefnx {} {@var{h} =} findobj (@var{hlist}, "flat", @dots{}) 8810@deftypefnx {} {@var{h} =} findobj (@var{hlist}, "-depth", @var{d}, @dots{}) 8811Find graphics objects with specified properties. 8812 8813When called without arguments, return all graphic objects beginning with the 8814root object (0) and including all of its descendants. 8815 8816The simplest form for narrowing the results is 8817 8818@example 8819findobj (@var{prop_name}, @var{prop_value}) 8820@end example 8821 8822@noindent 8823which returns the handles of all objects which have a property named 8824@var{prop_name} that has the value @var{prop_value}. If multiple 8825property/value pairs are specified then only objects meeting all of the 8826conditions (equivalent to @code{-and}) are returned. 8827 8828The search can be limited to a particular set of objects and their 8829descendants, by passing a handle or set of handles @var{hlist} as the first 8830argument. 8831 8832The depth of the object hierarchy to search can be limited with the 8833@qcode{"-depth"} argument. An example of searching through only three 8834generations of children is: 8835 8836@example 8837findobj (@var{hlist}, "-depth", 3, @var{prop_name}, @var{prop_value}) 8838@end example 8839 8840Specifying a depth @var{d} of 0 limits the search to the set of objects 8841passed in @var{hlist}. A depth of 0 is also equivalent to the 8842@qcode{"flat"} argument. The default depth value is @code{Inf} which 8843includes all descendants. 8844 8845A specified logical operator may be used between @var{prop_name}, 8846@var{prop_value} pairs. The supported logical operators are: 8847@qcode{"-and"}, @qcode{"-or"}, @qcode{"-xor"}, @qcode{"-not"}. Example code 8848to locate all figure and axes objects is 8849 8850@example 8851findobj ("type", "figure", "-or", "type", "axes") 8852@end example 8853 8854Objects may also be matched by comparing a regular expression to the 8855property values, where property values that match 8856@code{regexp (@var{prop_value}, @var{pattern})} are returned. 8857 8858Finally, objects which have a property name can be found with the 8859@qcode{"-property"} option. For example, code to locate objects with a 8860@qcode{"meshstyle"} property is 8861 8862@example 8863findobj ("-property", "meshstyle") 8864@end example 8865 8866Implementation Note: The search only includes objects with visible 8867handles (@w{HandleVisibility} = @qcode{"on"}). @xref{XREFfindall,,findall}, 8868to search for all objects including hidden ones. 8869@xseealso{@ref{XREFfindall,,findall}, @ref{XREFallchild,,allchild}, @ref{XREFget,,get}, @ref{XREFset,,set}} 8870@end deftypefn 8871 8872 8873@c findall scripts/plot/util/findall.m 8874@anchor{XREFfindall} 8875@deftypefn {} {@var{h} =} findall () 8876@deftypefnx {} {@var{h} =} findall (@var{prop_name}, @var{prop_value}, @dots{}) 8877@deftypefnx {} {@var{h} =} findall (@var{prop_name}, @var{prop_value}, "-@var{logical_op}", @var{prop_name}, @var{prop_value}) 8878@deftypefnx {} {@var{h} =} findall ("-property", @var{prop_name}) 8879@deftypefnx {} {@var{h} =} findall ("-regexp", @var{prop_name}, @var{pattern}) 8880@deftypefnx {} {@var{h} =} findall (@var{hlist}, @dots{}) 8881@deftypefnx {} {@var{h} =} findall (@var{hlist}, "flat", @dots{}) 8882@deftypefnx {} {@var{h} =} findall (@var{hlist}, "-depth", @var{d}, @dots{}) 8883Find graphics object, including hidden ones, with specified properties. 8884 8885The return value @var{h} is a list of handles to the found graphic objects. 8886 8887@code{findall} performs the same search as @code{findobj}, but it 8888includes hidden objects (HandleVisibility = @qcode{"off"}). For full 8889documentation, @pxref{XREFfindobj,,findobj}. 8890@xseealso{@ref{XREFfindobj,,findobj}, @ref{XREFallchild,,allchild}, @ref{XREFget,,get}, @ref{XREFset,,set}} 8891@end deftypefn 8892 8893@node Managing Default Properties 8894@subsection Managing Default Properties 8895@cindex default graphics properties 8896@cindex graphics properties, default 8897 8898Object properties have two classes of default values, @dfn{factory 8899defaults} (the initial values) and @dfn{user-defined defaults}, which 8900may override the factory defaults. 8901 8902Although default values may be set for any object, they are set in 8903parent objects and apply to child objects, of the specified object type. 8904For example, setting the default @code{color} property of @code{line} 8905objects to @qcode{"green"}, for the @code{root} object, will result in all 8906@code{line} objects inheriting the @code{color} @qcode{"green"} as the default 8907value. 8908 8909@example 8910set (groot, "defaultlinecolor", "green"); 8911@end example 8912 8913@noindent 8914sets the default line color for all objects. The rule for constructing 8915the property name to set a default value is 8916 8917@example 8918default + @var{object-type} + @var{property-name} 8919@end example 8920 8921This rule can lead to some strange looking names, for example 8922@code{defaultlinelinewidth"} specifies the default @code{linewidth} 8923property for @code{line} objects. 8924 8925The example above used the root object so the default property value will apply 8926to all line objects. However, default values are hierarchical, so defaults set 8927in a figure objects override those set in the root object. Likewise, defaults 8928set in an axes object override those set in figure or root objects. For 8929example, 8930 8931@example 8932@group 8933subplot (2, 1, 1); 8934set (groot, "defaultlinecolor", "red"); 8935set (1, "defaultlinecolor", "green"); 8936set (gca (), "defaultlinecolor", "blue"); 8937line (1:10, rand (1, 10)); 8938subplot (2, 1, 2); 8939line (1:10, rand (1, 10)); 8940figure (2) 8941line (1:10, rand (1, 10)); 8942@end group 8943@end example 8944 8945@noindent 8946produces two figures. The line in first subplot window of the first 8947figure is blue because it inherits its color from its parent axes 8948object. The line in the second subplot window of the first figure is 8949green because it inherits its color from its parent figure object. The 8950line in the second figure window is red because it inherits its color 8951from the global root object. 8952 8953To remove a user-defined default setting, set the default property to 8954the value @qcode{"remove"}. For example, 8955 8956@example 8957set (gca (), "defaultlinecolor", "remove"); 8958@end example 8959 8960@noindent 8961removes the user-defined default line color setting from the current axes 8962object. To quickly remove all user-defined defaults use the @code{reset} 8963function. 8964 8965By default, high level plotting functions such as @code{plot} reset and 8966redefine axes properties independently from the defaults. An example of such 8967property is the axes @code{box} property: it is set @code{on} by high level 2-D 8968graphics functions regardless of the property @qcode{"defaultaxesbox"}. Use 8969the @code{hold} function to prevent this behavior: 8970 8971@example 8972@group 8973set (groot, "defaultaxesbox", "off"); 8974subplot (2, 1, 1); 8975plot (1:10) 8976title ("Box is on anyway") 8977subplot (2, 1, 2); 8978hold on 8979plot (1:10) 8980title ("Box is off") 8981@end group 8982@end example 8983 8984@c reset libinterp/corefcn/graphics.cc 8985@anchor{XREFreset} 8986@deftypefn {} {} reset (@var{h}) 8987Reset the properties of the graphic object @var{h} to their default values. 8988 8989For figures, the properties @qcode{"position"}, @qcode{"units"}, 8990@qcode{"windowstyle"}, and @qcode{"paperunits"} are not affected. 8991For axes, the properties @qcode{"position"} and @qcode{"units"} are 8992not affected. 8993 8994The input @var{h} may also be a vector of graphic handles in which case 8995each individual object will be reset. 8996@xseealso{@ref{XREFcla,,cla}, @ref{XREFclf,,clf}, @ref{XREFnewplot,,newplot}} 8997@end deftypefn 8998 8999 9000Getting the @qcode{"default"} property of an object returns a list of 9001user-defined defaults set for the object. For example, 9002 9003@example 9004get (gca (), "default"); 9005@end example 9006 9007@noindent 9008returns a list of user-defined default values for the current axes 9009object. 9010 9011Factory default values are stored in the root object. The command 9012 9013@example 9014get (groot, "factory"); 9015@end example 9016 9017@noindent 9018returns a list of factory defaults. 9019 9020@node Advanced Plotting 9021@section Advanced Plotting 9022 9023 9024@menu 9025* Colors:: 9026* Line Styles:: 9027* Marker Styles:: 9028* Callbacks:: 9029* Application-defined Data:: 9030* Object Groups:: 9031* Transform Groups:: 9032* Graphics Toolkits:: 9033@end menu 9034 9035 9036@node Colors 9037@subsection Colors 9038@cindex graphics colors 9039@cindex colors, graphics 9040 9041Colors may be specified as RGB triplets with values ranging from zero to 9042one, or by name. Recognized color names include @qcode{"blue"}, 9043@qcode{"black"}, @qcode{"cyan"}, @qcode{"green"}, @qcode{"magenta"}, 9044@qcode{"red"}, @qcode{"white"}, and @qcode{"yellow"}. 9045 9046@node Line Styles 9047@subsection Line Styles 9048@cindex line styles, graphics 9049@cindex graphics line styles 9050 9051Line styles are specified by the following properties: 9052 9053@table @code 9054@item linestyle 9055May be one of 9056 9057@table @asis 9058@item @qcode{"-"} 9059Solid line. [default] 9060 9061@c Special handling required to avoid '--' becoming single en-dash in Info 9062@ifnottex 9063 9064@item @verb{|"--"|} 9065@end ifnottex 9066@iftex 9067 9068@item @code{"--"} 9069@end iftex 9070Dashed line. 9071 9072@item @qcode{":"} 9073Dotted line. 9074 9075@item @qcode{"-."} 9076A dash-dot line. 9077 9078@item @qcode{"none"} 9079No line. Points will still be marked using the current Marker Style. 9080@end table 9081 9082@item linewidth 9083A number specifying the width of the line. The default is 1. A value 9084of 2 is twice as wide as the default, etc. 9085@end table 9086 9087@node Marker Styles 9088@subsection Marker Styles 9089@cindex graphics marker styles 9090@cindex marker styles, graphics 9091 9092Marker styles are specified by the following properties: 9093 9094@table @code 9095@item marker 9096A character indicating a plot marker to be place at each data point, or 9097@qcode{"none"}, meaning no markers should be displayed. 9098 9099@item markeredgecolor 9100The color of the edge around the marker, or @qcode{"auto"}, meaning that 9101the edge color is the same as the face color. @xref{Colors}. 9102 9103@item markerfacecolor 9104The color of the marker, or @qcode{"none"} to indicate that the marker 9105should not be filled. @xref{Colors}. 9106 9107@item markersize 9108A number specifying the size of the marker. The default is 1. A value 9109of 2 is twice as large as the default, etc. 9110@end table 9111 9112The @code{colstyle} function will parse a @code{plot}-style specification 9113and will return the color, line, and marker values that would result. 9114 9115@c colstyle scripts/plot/util/colstyle.m 9116@anchor{XREFcolstyle} 9117@deftypefn {} {[@var{style}, @var{color}, @var{marker}, @var{msg}] =} colstyle (@var{style}) 9118Parse the line specification @var{style} and return the line style, color, 9119and markers given. 9120 9121In the case of an error, the string @var{msg} will return the text of the 9122error. 9123@end deftypefn 9124 9125 9126@node Callbacks 9127@subsection Callbacks 9128@cindex callbacks 9129 9130Callback functions can be associated with graphics objects and triggered 9131after certain events occur. The basic structure of all callback function 9132is 9133 9134@example 9135@group 9136function mycallback (hsrc, evt) 9137 @dots{} 9138endfunction 9139@end group 9140@end example 9141 9142@noindent 9143where @code{hsrc} is a handle to the source of the callback, and @code{evt} 9144gives some event specific data. 9145 9146The function can be provided as a function handle to a plain Octave function, 9147as an anonymous function, or as a string representing an Octave command. The 9148latter syntax is not recommended since syntax errors will only occur when the 9149string is evaluated. 9150@xref{Function Handles and Anonymous Functions, , Function Handles section}. 9151 9152This can then be associated with an object either at the object's creation, or 9153later with the @code{set} function. For example, 9154 9155@example 9156plot (x, "DeleteFcn", @@(h, e) disp ("Window Deleted")) 9157@end example 9158 9159@noindent 9160where at the moment that the plot is deleted, the message 9161@qcode{"Window Deleted"} will be displayed. 9162 9163Additional user arguments can be passed to callback functions, and will be 9164passed after the two default arguments. For example: 9165 9166@example 9167@group 9168plot (x, "DeleteFcn", @{@@mycallback, "1"@}) 9169@dots{} 9170function mycallback (h, evt, arg1) 9171 fprintf ("Closing plot %d\n", arg1); 9172endfunction 9173@end group 9174@end example 9175 9176@strong{Caution:} The second argument in callback functions---@code{evt}---is 9177only partially implemented in the Qt graphics toolkit: 9178 9179@itemize @bullet 9180@item Mouse click events: 9181@code{evt} is a class @code{double} value: 1 for left, 2 for middle, and 3 for 9182right click. 9183 9184@item Key press events: 9185@code{evt} is a structure with fields @code{Key} (string), @code{Character} 9186(string), and @code{Modifier} (cell array of strings). 9187 9188@item Other events: 9189@code{evt} is a class @code{double} empty matrix. 9190@end itemize 9191 9192The basic callback functions that are available for all graphics objects are 9193 9194@itemize @bullet 9195@item CreateFcn: 9196called at the moment of the objects creation. It is not called if the 9197object is altered in any way, and so it only makes sense to define this 9198callback in the function call that defines the object. Callbacks that 9199are added to @code{CreateFcn} later with the @code{set} function will 9200never be executed. 9201 9202@item DeleteFcn: 9203called at the moment an object is deleted. 9204 9205@item ButtonDownFcn: 9206called if a mouse button is pressed while the pointer is over this 9207object. Note, that the gnuplot interface does not implement this 9208callback. 9209@end itemize 9210 9211By default callback functions are queued (they are executed one after the other 9212in the event queue) unless the @code{drawnow}, @code{figure}, @code{waitfor}, 9213@code{getframe}, or @code{pause} functions are used. If an executing callback 9214invokes one of those functions, it causes Octave to flush the event queue, 9215which results in the executing callback being interrupted. 9216 9217It is possible to specify that an object's callbacks should not be interrupted 9218by setting the object's @code{interruptible} property to @qcode{"off"}. In 9219this case, Octave decides what to do based on the @code{busyaction} property of 9220the @strong{interrupting} callback object: 9221 9222@table @asis 9223@item @code{queue} (the default) 9224The interrupting callback is executed after the executing callback has 9225returned. 9226 9227@item @code{cancel} 9228The interrupting callback is discarded. 9229@end table 9230 9231The @code{interruptible} property has no effect when the interrupting callback 9232is a @code{deletefcn}, or a figure @code{resizefcn} or @code{closerequestfcn}. 9233Those callbacks always interrupt the executing callback. 9234 9235The handle to the object that holds the callback being executed can be 9236obtained with the @code{gcbo} function. The handle to the ancestor figure 9237of this object may be obtained using the @code{gcbf} function. 9238 9239@c gcbo scripts/plot/util/gcbo.m 9240@anchor{XREFgcbo} 9241@deftypefn {} {@var{h} =} gcbo () 9242@deftypefnx {} {[@var{h}, @var{fig}] =} gcbo () 9243Return a handle to the object whose callback is currently executing. 9244 9245If no callback is executing, this function returns the empty matrix. This 9246handle is obtained from the root object property @qcode{"CallbackObject"}. 9247 9248When called with a second output argument, return the handle of the figure 9249containing the object whose callback is currently executing. If no callback 9250is executing the second output is also set to the empty matrix. 9251 9252@xseealso{@ref{XREFgcbf,,gcbf}, @ref{XREFgco,,gco}, @ref{XREFgca,,gca}, @ref{XREFgcf,,gcf}, @ref{XREFget,,get}, @ref{XREFset,,set}} 9253@end deftypefn 9254 9255 9256@c gcbf scripts/plot/util/gcbf.m 9257@anchor{XREFgcbf} 9258@deftypefn {} {@var{fig} =} gcbf () 9259Return a handle to the figure containing the object whose callback is 9260currently executing. 9261 9262If no callback is executing, this function returns the empty matrix. The 9263handle returned by this function is the same as the second output argument 9264of @code{gcbo}. 9265 9266@xseealso{@ref{XREFgcbo,,gcbo}, @ref{XREFgcf,,gcf}, @ref{XREFgco,,gco}, @ref{XREFgca,,gca}, @ref{XREFget,,get}, @ref{XREFset,,set}} 9267@end deftypefn 9268 9269 9270Callbacks can equally be added to properties with the @code{addlistener} 9271function described below. 9272 9273@node Application-defined Data 9274@subsection Application-defined Data 9275@cindex application-defined data 9276 9277Octave has a provision for attaching application-defined data to a graphics 9278handle. The data can be anything which is meaningful to the application, and 9279will be completely ignored by Octave. 9280 9281@c setappdata scripts/gui/setappdata.m 9282@anchor{XREFsetappdata} 9283@deftypefn {} {} setappdata (@var{h}, @var{name}, @var{value}) 9284@deftypefnx {} {} setappdata (@var{h}, @var{name1}, @var{value1}, @var{name2}, @var{value3}, @dots{}) 9285@deftypefnx {} {} setappdata (@var{h}, @{@var{name1}, @var{name2}, @dots{}@}, @{@var{value1}, @var{value2}, @dots{}@}) 9286Set the application data @var{name} to @var{value} for the graphics object 9287with handle @var{h}. 9288 9289@var{h} may also be a vector of graphics handles. If the application data 9290with the specified @var{name} does not exist, it is created. 9291 9292Multiple @var{name}/@var{value} pairs can be specified. Alternatively, a 9293cell array of @var{names} and a corresponding cell array of @var{values} can 9294be specified. Details on obtaining a list of valid application data 9295properties can be found in @ref{XREFgetappdata, ,getappdata}. 9296 9297@xseealso{@ref{XREFgetappdata,,getappdata}, @ref{XREFisappdata,,isappdata}, @ref{XREFrmappdata,,rmappdata}, @ref{XREFguidata,,guidata}, @ref{XREFget,,get}, @ref{XREFset,,set}, @ref{XREFgetpref,,getpref}, @ref{XREFsetpref,,setpref}} 9298@end deftypefn 9299 9300 9301@c getappdata scripts/gui/getappdata.m 9302@anchor{XREFgetappdata} 9303@deftypefn {} {@var{value} =} getappdata (@var{h}, @var{name}) 9304@deftypefnx {} {@var{appdata} =} getappdata (@var{h}) 9305Return the @var{value} of the application data @var{name} for the graphics 9306object with handle @var{h}. 9307 9308@var{h} may also be a vector of graphics handles. If no second argument 9309@var{name} is given then @code{getappdata} returns a structure, 9310@var{appdata}, whose fields correspond to the appdata properties. 9311 9312@xseealso{@ref{XREFsetappdata,,setappdata}, @ref{XREFisappdata,,isappdata}, @ref{XREFrmappdata,,rmappdata}, @ref{XREFguidata,,guidata}, @ref{XREFget,,get}, @ref{XREFset,,set}, @ref{XREFgetpref,,getpref}, @ref{XREFsetpref,,setpref}} 9313@end deftypefn 9314 9315 9316@c rmappdata scripts/gui/rmappdata.m 9317@anchor{XREFrmappdata} 9318@deftypefn {} {} rmappdata (@var{h}, @var{name}) 9319@deftypefnx {} {} rmappdata (@var{h}, @var{name1}, @var{name2}, @dots{}) 9320Delete the application data @var{name} from the graphics object with handle 9321@var{h}. 9322 9323@var{h} may also be a vector of graphics handles. Multiple application data 9324names may be supplied to delete several properties at once. 9325 9326@xseealso{@ref{XREFsetappdata,,setappdata}, @ref{XREFgetappdata,,getappdata}, @ref{XREFisappdata,,isappdata}} 9327@end deftypefn 9328 9329 9330@c isappdata scripts/gui/isappdata.m 9331@anchor{XREFisappdata} 9332@deftypefn {} {@var{valid} =} isappdata (@var{h}, @var{name}) 9333Return true if the named application data, @var{name}, exists for the 9334graphics object with handle @var{h}. 9335 9336@var{h} may also be a vector of graphics handles. 9337@xseealso{@ref{XREFgetappdata,,getappdata}, @ref{XREFsetappdata,,setappdata}, @ref{XREFrmappdata,,rmappdata}, @ref{XREFguidata,,guidata}, @ref{XREFget,,get}, @ref{XREFset,,set}, @ref{XREFgetpref,,getpref}, @ref{XREFsetpref,,setpref}} 9338@end deftypefn 9339 9340 9341@node Object Groups 9342@subsection Object Groups 9343@cindex object groups 9344 9345A number of Octave high level plot functions return groups of other 9346graphics objects or they return graphics objects that have their 9347properties linked in such a way that changes to one of the properties 9348results in changes in the others. A graphic object that groups other 9349objects is an @code{hggroup} 9350 9351@c hggroup scripts/plot/util/hggroup.m 9352@anchor{XREFhggroup} 9353@deftypefn {} {} hggroup () 9354@deftypefnx {} {} hggroup (@var{hax}) 9355@deftypefnx {} {} hggroup (@dots{}, @var{property}, @var{value}, @dots{}) 9356@deftypefnx {} {@var{h} =} hggroup (@dots{}) 9357Create handle graphics group object with axes parent @var{hax}. 9358 9359If no parent is specified, the group is created in the current axes. 9360 9361Multiple property/value pairs may be specified for the hggroup, but they 9362must appear in pairs. The full list of properties is documented at 9363@ref{Axes Properties}. 9364 9365The optional return value @var{h} is a graphics handle to the created 9366hggroup object. 9367 9368Programming Note: An hggroup is a way to group base graphics objects such 9369as line objects or patch objects into a single unit which can react 9370appropriately. For example, the individual lines of a contour plot are 9371collected into a single hggroup so that they can be made visible/invisible 9372with a single command, @code{set (hg_handle, "visible", "off")}. 9373 9374@xseealso{@ref{XREFaddproperty,,addproperty}, @ref{XREFaddlistener,,addlistener}} 9375@end deftypefn 9376 9377 9378For example a simple use of a @code{hggroup} might be 9379 9380@example 9381@group 9382x = 0:0.1:10; 9383hg = hggroup (); 9384plot (x, sin (x), "color", [1, 0, 0], "parent", hg); 9385hold on 9386plot (x, cos (x), "color", [0, 1, 0], "parent", hg); 9387set (hg, "visible", "off"); 9388@end group 9389@end example 9390 9391@noindent 9392which groups the two plots into a single object and controls their 9393visibility directly. The default properties of an @code{hggroup} are 9394the same as the set of common properties for the other graphics 9395objects. Additional properties can be added with the @code{addproperty} 9396function. 9397 9398@c addproperty libinterp/corefcn/graphics.cc 9399@anchor{XREFaddproperty} 9400@deftypefn {} {} addproperty (@var{name}, @var{h}, @var{type}) 9401@deftypefnx {} {} addproperty (@var{name}, @var{h}, @var{type}, @var{arg}, @dots{}) 9402Create a new property named @var{name} in graphics object @var{h}. 9403 9404@var{type} determines the type of the property to create. @var{args} 9405usually contains the default value of the property, but additional 9406arguments might be given, depending on the type of the property. 9407 9408The supported property types are: 9409 9410@table @code 9411@item string 9412A string property. @var{arg} contains the default string value. 9413 9414@item any 9415An @nospell{un-typed} property. This kind of property can hold any octave 9416value. @var{args} contains the default value. 9417 9418@item radio 9419A string property with a limited set of accepted values. The first 9420argument must be a string with all accepted values separated by 9421a vertical bar ('|'). The default value can be marked by enclosing 9422it with a '@{' '@}' pair. The default value may also be given as 9423an optional second string argument. 9424 9425@item boolean 9426A boolean property. This property type is equivalent to a radio 9427property with "on|off" as accepted values. @var{arg} contains 9428the default property value. 9429 9430@item double 9431A scalar double property. @var{arg} contains the default value. 9432 9433@item handle 9434A handle property. This kind of property holds the handle of a 9435graphics object. @var{arg} contains the default handle value. 9436When no default value is given, the property is initialized to 9437the empty matrix. 9438 9439@item data 9440A data (matrix) property. @var{arg} contains the default data 9441value. When no default value is given, the data is initialized to 9442the empty matrix. 9443 9444@item color 9445A color property. @var{arg} contains the default color value. 9446When no default color is given, the property is set to black. 9447An optional second string argument may be given to specify an 9448additional set of accepted string values (like a radio property). 9449@end table 9450 9451@var{type} may also be the concatenation of a core object type and 9452a valid property name for that object type. The property created 9453then has the same characteristics as the referenced property (type, 9454possible values, hidden state@dots{}). This allows one to clone an 9455existing property into the graphics object @var{h}. 9456 9457Examples: 9458 9459@example 9460@group 9461addproperty ("my_property", gcf, "string", "a string value"); 9462addproperty ("my_radio", gcf, "radio", "val_1|val_2|@{val_3@}"); 9463addproperty ("my_style", gcf, "linelinestyle", "--"); 9464@end group 9465@end example 9466 9467@xseealso{@ref{XREFaddlistener,,addlistener}, @ref{XREFhggroup,,hggroup}} 9468@end deftypefn 9469 9470 9471Once a property in added to an @code{hggroup}, it is not linked to any 9472other property of either the children of the group, or any other 9473graphics object. Add so to control the way in which this newly added 9474property is used, the @code{addlistener} function is used to define a 9475callback function that is executed when the property is altered. 9476 9477@c addlistener libinterp/corefcn/graphics.cc 9478@anchor{XREFaddlistener} 9479@deftypefn {} {} addlistener (@var{h}, @var{prop}, @var{fcn}) 9480Register @var{fcn} as listener for the property @var{prop} of the graphics 9481object @var{h}. 9482 9483Property listeners are executed (in order of registration) when the property 9484is set. The new value is already available when the listeners are executed. 9485 9486@var{prop} must be a string naming a valid property in @var{h}. 9487 9488@var{fcn} can be a function handle, a string or a cell array whose first 9489element is a function handle. If @var{fcn} is a function handle, the 9490corresponding function should accept at least 2 arguments, that will be 9491set to the object handle and the empty matrix respectively. If @var{fcn} 9492is a string, it must be any valid octave expression. If @var{fcn} is a cell 9493array, the first element must be a function handle with the same signature 9494as described above. The next elements of the cell array are passed 9495as additional arguments to the function. 9496 9497Example: 9498 9499@example 9500@group 9501function my_listener (h, dummy, p1) 9502 fprintf ("my_listener called with p1=%s\n", p1); 9503endfunction 9504 9505addlistener (gcf, "position", @{@@my_listener, "my string"@}) 9506@end group 9507@end example 9508 9509@xseealso{@ref{XREFdellistener,,dellistener}, @ref{XREFaddproperty,,addproperty}, @ref{XREFhggroup,,hggroup}} 9510@end deftypefn 9511 9512 9513@c dellistener libinterp/corefcn/graphics.cc 9514@anchor{XREFdellistener} 9515@deftypefn {} {} dellistener (@var{h}, @var{prop}, @var{fcn}) 9516Remove the registration of @var{fcn} as a listener for the property 9517@var{prop} of the graphics object @var{h}. 9518 9519The function @var{fcn} must be the same variable (not just the same value), 9520as was passed to the original call to @code{addlistener}. 9521 9522If @var{fcn} is not defined then all listener functions of @var{prop} 9523are removed. 9524 9525Example: 9526 9527@example 9528@group 9529function my_listener (h, dummy, p1) 9530 fprintf ("my_listener called with p1=%s\n", p1); 9531endfunction 9532 9533c = @{@@my_listener, "my string"@}; 9534addlistener (gcf, "position", c); 9535dellistener (gcf, "position", c); 9536@end group 9537@end example 9538 9539@xseealso{@ref{XREFaddlistener,,addlistener}} 9540@end deftypefn 9541 9542 9543An example of the use of these two functions might be 9544 9545@example 9546@group 9547x = 0:0.1:10; 9548hg = hggroup (); 9549h = plot (x, sin (x), "color", [1, 0, 0], "parent", hg); 9550addproperty ("linestyle", hg, "linelinestyle", get (h, "linestyle")); 9551addlistener (hg, "linestyle", @@update_props); 9552hold on 9553plot (x, cos (x), "color", [0, 1, 0], "parent", hg); 9554 9555function update_props (h, d) 9556 set (get (h, "children"), "linestyle", get (h, "linestyle")); 9557endfunction 9558@end group 9559@end example 9560 9561@noindent 9562that adds a @code{linestyle} property to the @code{hggroup} and 9563propagating any changes its value to the children of the group. The 9564@code{linkprop} function can be used to simplify the above to be 9565 9566@example 9567@group 9568x = 0:0.1:10; 9569hg = hggroup (); 9570h1 = plot (x, sin (x), "color", [1, 0, 0], "parent", hg); 9571addproperty ("linestyle", hg, "linelinestyle", get (h, "linestyle")); 9572hold on 9573h2 = plot (x, cos (x), "color", [0, 1, 0], "parent", hg); 9574hlink = linkprop ([hg, h1, h2], "color"); 9575@end group 9576@end example 9577 9578@c linkprop scripts/plot/util/linkprop.m 9579@anchor{XREFlinkprop} 9580@deftypefn {} {@var{hlink} =} linkprop (@var{h}, "@var{prop}") 9581@deftypefnx {} {@var{hlink} =} linkprop (@var{h}, @{"@var{prop1}", "@var{prop2}", @dots{}@}) 9582Link graphic object properties, such that a change in one is propagated to 9583the others. 9584 9585The input @var{h} is a vector of graphic handles to link. 9586 9587@var{prop} may be a string when linking a single property, or a cell array 9588of strings for multiple properties. During the linking process all 9589properties in @var{prop} will initially be set to the values that exist on 9590the first object in the list @var{h}. 9591 9592The function returns @var{hlink} which is a special object describing the 9593link. As long as the reference @var{hlink} exists, the link between graphic 9594objects will be active. This means that @var{hlink} must be preserved in 9595a workspace variable, a global variable, or otherwise stored using a 9596function such as @code{setappdata} or @code{guidata}. To unlink properties, 9597execute @code{clear @var{hlink}}. 9598 9599An example of the use of @code{linkprop} is 9600 9601@example 9602@group 9603x = 0:0.1:10; 9604subplot (1,2,1); 9605h1 = plot (x, sin (x)); 9606subplot (1,2,2); 9607h2 = plot (x, cos (x)); 9608hlink = linkprop ([h1, h2], @{"color","linestyle"@}); 9609set (h1, "color", "green"); 9610set (h2, "linestyle", "--"); 9611@end group 9612@end example 9613 9614@xseealso{@ref{XREFlinkaxes,,linkaxes}, @ref{XREFaddlistener,,addlistener}} 9615@end deftypefn 9616 9617 9618@c linkaxes scripts/plot/util/linkaxes.m 9619@anchor{XREFlinkaxes} 9620@deftypefn {} {} linkaxes (@var{hax}) 9621@deftypefnx {} {} linkaxes (@var{hax}, @var{optstr}) 9622Link the axis limits of 2-D plots such that a change in one is propagated 9623to the others. 9624 9625The axes handles to be linked are passed as the first argument @var{hax}. 9626 9627The optional second argument is a string which defines which axis limits 9628will be linked. The possible values for @var{optstr} are: 9629 9630@table @asis 9631@item @qcode{"x"} 9632Link x-axes 9633 9634@item @qcode{"y"} 9635Link y-axes 9636 9637@item @qcode{"xy"} (default) 9638Link both axes 9639 9640@item @qcode{"off"} 9641Turn off linking 9642@end table 9643 9644If unspecified the default is to link both X and Y axes. 9645 9646When linking, the limits from the first axes in @var{hax} are applied to the 9647other axes in the list. Subsequent changes to any one of the axes will be 9648propagated to the others. 9649 9650@xseealso{@ref{XREFlinkprop,,linkprop}, @ref{XREFaddproperty,,addproperty}} 9651@end deftypefn 9652 9653 9654These capabilities are used in a number of basic graphics objects. 9655The @code{hggroup} objects created by the functions of Octave contain 9656one or more graphics object and are used to: 9657 9658@itemize @bullet 9659@item group together multiple graphics objects, 9660 9661@item create linked properties between different graphics objects, and 9662 9663@item to hide the nominal user data, from the actual data of the objects. 9664@end itemize 9665 9666@noindent 9667For example the @code{stem} function creates a stem series where each 9668@code{hggroup} of the stem series contains two line objects representing 9669the body and head of the stem. The @code{ydata} property of the 9670@code{hggroup} of the stem series represents the head of the stem, 9671whereas the body of the stem is between the baseline and this value. For 9672example 9673 9674@example 9675@group 9676h = stem (1:4) 9677get (h, "xdata") 9678@result{} [ 1 2 3 4]' 9679get (get (h, "children")(1), "xdata") 9680@result{} [ 1 1 NaN 2 2 NaN 3 3 NaN 4 4 NaN]' 9681@end group 9682@end example 9683 9684@noindent 9685shows the difference between the @code{xdata} of the @code{hggroup} 9686of a stem series object and the underlying line. 9687 9688The basic properties of such group objects is that they consist of one 9689or more linked @code{hggroup}, and that changes in certain properties of 9690these groups are propagated to other members of the group. Whereas, 9691certain properties of the members of the group only apply to the current 9692member. 9693 9694In addition the members of the group can also be linked to other 9695graphics objects through callback functions. For example the baseline of 9696the @code{bar} or @code{stem} functions is a line object, whose length 9697and position are automatically adjusted, based on changes to the 9698corresponding hggroup elements. 9699 9700@menu 9701* Data Sources in Object Groups:: 9702* Area Series:: 9703* Bar Series:: 9704* Contour Groups:: 9705* Error Bar Series:: 9706* Line Series:: 9707* Quiver Group:: 9708* Scatter Group:: 9709* Stair Group:: 9710* Stem Series:: 9711* Surface Group:: 9712@end menu 9713 9714@node Data Sources in Object Groups 9715@subsubsection Data Sources in Object Groups 9716@cindex data sources in object groups 9717@anchor{XREFdatasources} 9718All of the group objects contain data source parameters. There are 9719string parameters that contain an expression that is evaluated to update 9720the relevant data property of the group when the @code{refreshdata} 9721function is called. 9722 9723@c refreshdata scripts/plot/util/refreshdata.m 9724@anchor{XREFrefreshdata} 9725@deftypefn {} {} refreshdata () 9726@deftypefnx {} {} refreshdata (@var{h}) 9727@deftypefnx {} {} refreshdata (@var{h}, @var{workspace}) 9728Evaluate any @samp{datasource} properties of the current figure and update 9729the plot if the corresponding data has changed. 9730 9731If the first argument @var{h} is a list of graphic handles, then operate 9732on these objects rather than the current figure returned by @code{gcf}. 9733 9734The optional second argument @var{workspace} can take the following values: 9735 9736@table @asis 9737@item @qcode{"base"} 9738Evaluate the datasource properties in the base workspace. (default). 9739 9740@item @qcode{"caller"} 9741Evaluate the datasource properties in the workspace of the function 9742that called @code{refreshdata}. 9743@end table 9744 9745An example of the use of @code{refreshdata} is: 9746 9747@example 9748@group 9749x = 0:0.1:10; 9750y = sin (x); 9751plot (x, y, "ydatasource", "y"); 9752for i = 1 : 100 9753 pause (0.1); 9754 y = sin (x + 0.1*i); 9755 refreshdata (); 9756endfor 9757@end group 9758@end example 9759@end deftypefn 9760 9761 9762@anchor{XREFlinkdata} 9763@c add the description of the linkdata function here when it is written 9764@c remove the explicit anchor when you add the corresponding @DOCSTRING 9765@c command 9766 9767@node Area Series 9768@subsubsection Area Series 9769@cindex series objects 9770@cindex area series 9771 9772Area series objects are created by the @code{area} function. Each of the 9773@code{hggroup} elements contains a single patch object. The properties 9774of the area series are 9775 9776@table @code 9777@item basevalue 9778The value where the base of the area plot is drawn. 9779 9780@item linewidth 9781@itemx linestyle 9782The line width and style of the edge of the patch objects making up the 9783areas. @xref{Line Styles}. 9784 9785@item edgecolor 9786@itemx facecolor 9787The line and fill color of the patch objects making up the areas. 9788@xref{Colors}. 9789 9790@item xdata 9791@itemx ydata 9792The x and y coordinates of the original columns of the data passed to 9793@code{area} prior to the cumulative summation used in the @code{area} 9794function. 9795 9796@item xdatasource 9797@itemx ydatasource 9798Data source variables. 9799@end table 9800 9801@node Bar Series 9802@subsubsection Bar Series 9803@cindex series objects 9804@cindex bar series 9805 9806Bar series objects are created by the @code{bar} or @code{barh} 9807functions. Each @code{hggroup} element contains a single patch object. 9808The properties of the bar series are 9809 9810@table @code 9811@item showbaseline 9812@itemx baseline 9813@itemx basevalue 9814The property @code{showbaseline} flags whether the baseline of the bar 9815series is displayed (default is @qcode{"on"}). The handle of the graphics 9816object representing the baseline is given by the @code{baseline} property and 9817the y-value of the baseline by the @code{basevalue} property. 9818 9819Changes to any of these properties are propagated to the other members of 9820the bar series and to the baseline itself. Equally, changes in the 9821properties of the base line itself are propagated to the members of the 9822corresponding bar series. 9823 9824@item barwidth 9825@itemx barlayout 9826@itemx horizontal 9827The property @code{barwidth} is the width of the bar corresponding to 9828the @var{width} variable passed to @code{bar} or @var{barh}. Whether the 9829bar series is @qcode{"grouped"} or @qcode{"stacked"} is determined by the 9830@code{barlayout} property and whether the bars are horizontal or 9831vertical by the @code{horizontal} property. 9832 9833Changes to any of these property are propagated to the other members of 9834the bar series. 9835 9836@item linewidth 9837@itemx linestyle 9838The line width and style of the edge of the patch objects making up the 9839bars. @xref{Line Styles}. 9840 9841@item edgecolor 9842@itemx facecolor 9843The line and fill color of the patch objects making up the bars. 9844@xref{Colors}. 9845 9846@item xdata 9847The nominal x positions of the bars. Changes in this property and 9848propagated to the other members of the bar series. 9849 9850@item ydata 9851The y value of the bars in the @code{hggroup}. 9852 9853@item xdatasource 9854@itemx ydatasource 9855Data source variables. 9856@end table 9857 9858@node Contour Groups 9859@subsubsection Contour Groups 9860@cindex series objects 9861@cindex contour series 9862 9863Contour group objects are created by the @code{contour}, @code{contourf}, and 9864@code{contour3} functions. They are also one of the handles returned by the 9865@code{surfc} and @code{meshc} functions. The properties of the contour group 9866are 9867 9868@table @code 9869@item contourmatrix 9870A read only property that contains the data return by @code{contourc} used to 9871create the contours of the plot. 9872 9873@item fill 9874A radio property that can have the values @qcode{"on"} or @qcode{"off"} that 9875flags whether the contours to plot are to be filled. 9876 9877@item zlevelmode 9878@itemx zlevel 9879The radio property @code{zlevelmode} can have the values @qcode{"none"}, 9880@qcode{"auto"}, or @qcode{"manual"}. When its value is @qcode{"none"} there is 9881no z component to the plotted contours. When its value is @qcode{"auto"} the z 9882value of the plotted contours is at the same value as the contour itself. If 9883the value is @qcode{"manual"}, then the z value at which to plot the contour is 9884determined by the @code{zlevel} property. 9885 9886@item levellistmode 9887@itemx levellist 9888@itemx levelstepmode 9889@itemx levelstep 9890If @code{levellistmode} is @qcode{"manual"}, then the levels at which to plot 9891the contours is determined by @code{levellist}. If @code{levellistmode} is set 9892to @qcode{"auto"}, then the distance between contours is determined by 9893@code{levelstep}. If both @code{levellistmode} and @code{levelstepmode} are 9894set to @qcode{"auto"}, then there are assumed to be 10 equal spaced contours. 9895 9896@item textlistmode 9897@itemx textlist 9898@itemx textstepmode 9899@itemx textstep 9900If @code{textlistmode} is @qcode{"manual"}, then the labeled contours 9901is determined by @code{textlist}. If @code{textlistmode} is set to 9902@qcode{"auto"}, then the distance between labeled contours is determined by 9903@code{textstep}. If both @code{textlistmode} and @code{textstepmode} 9904are set to @qcode{"auto"}, then there are assumed to be 10 equal spaced 9905labeled contours. 9906 9907@item showtext 9908Flag whether the contour labels are shown or not. 9909 9910@item labelspacing 9911The distance between labels on a single contour in points. 9912 9913@item linewidth 9914 9915@item linestyle 9916 9917@item linecolor 9918The properties of the contour lines. The properties @code{linewidth} and 9919@code{linestyle} are similar to the corresponding properties for lines. The 9920property @code{linecolor} is a color property (@pxref{Colors}), that can also 9921have the values of @qcode{"none"} or @qcode{"auto"}. If @code{linecolor} is 9922@qcode{"none"}, then no contour line is drawn. If @code{linecolor} is 9923@qcode{"auto"} then the line color is determined by the colormap. 9924 9925@item xdata 9926@itemx ydata 9927@itemx zdata 9928The original x, y, and z data of the contour lines. 9929 9930@item xdatasource 9931@itemx ydatasource 9932@itemx zdatasource 9933Data source variables. 9934@end table 9935 9936@node Error Bar Series 9937@subsubsection Error Bar Series 9938@cindex series objects 9939@cindex error bar series 9940 9941Error bar series are created by the @code{errorbar} function. Each 9942@code{hggroup} element contains two line objects representing the data and 9943the errorbars separately. The properties of the error bar series are 9944 9945@table @code 9946@item color 9947The RGB color or color name of the line objects of the error bars. 9948@xref{Colors}. 9949 9950@item linewidth 9951@itemx linestyle 9952The line width and style of the line objects of the error bars. @xref{Line 9953Styles}. 9954 9955@item marker 9956@itemx markeredgecolor 9957@itemx markerfacecolor 9958@itemx markersize 9959The line and fill color of the markers on the error bars. @xref{Colors}. 9960 9961@item xdata 9962@itemx ydata 9963@itemx ldata 9964@itemx udata 9965@itemx xldata 9966@itemx xudata 9967The original x, y, l, u, @nospell{xl, xu} data of the error bars. 9968 9969@item xdatasource 9970@itemx ydatasource 9971@itemx ldatasource 9972@itemx udatasource 9973@itemx xldatasource 9974@itemx xudatasource 9975Data source variables. 9976@end table 9977 9978@node Line Series 9979@subsubsection Line Series 9980@cindex series objects 9981@cindex line series 9982 9983Line series objects are created by the @code{plot} and @code{plot3} 9984functions and are of the type @code{line}. The properties of the 9985line series with the ability to add data sources. 9986 9987@table @code 9988@item color 9989The RGB color or color name of the line objects. @xref{Colors}. 9990 9991@item linewidth 9992@itemx linestyle 9993The line width and style of the line objects. @xref{Line Styles}. 9994 9995@item marker 9996@itemx markeredgecolor 9997@itemx markerfacecolor 9998@itemx markersize 9999The line and fill color of the markers. @xref{Colors}. 10000 10001@item xdata 10002@itemx ydata 10003@itemx zdata 10004The original x, y and z data. 10005 10006@item xdatasource 10007@itemx ydatasource 10008@itemx zdatasource 10009Data source variables. 10010@end table 10011 10012@node Quiver Group 10013@subsubsection Quiver Group 10014@cindex group objects 10015@cindex quiver group 10016 10017Quiver series objects are created by the @code{quiver} or @code{quiver3} 10018functions. Each @code{hggroup} element of the series contains three line 10019objects as children representing the body and head of the arrow, 10020together with a marker as the point of origin of the arrows. The 10021properties of the quiver series are 10022 10023@table @code 10024@item autoscale 10025@itemx autoscalefactor 10026Flag whether the length of the arrows is scaled or defined directly from 10027the @var{u}, @var{v} and @var{w} data. If the arrow length is flagged 10028as being scaled by the @code{autoscale} property, then the length of the 10029autoscaled arrow is controlled by the @code{autoscalefactor}. 10030 10031@item maxheadsize 10032This property controls the size of the head of the arrows in the quiver 10033series. The default value is 0.2. 10034 10035@item showarrowhead 10036Flag whether the arrow heads are displayed in the quiver plot. 10037 10038@item color 10039The RGB color or color name of the line objects of the quiver. @xref{Colors}. 10040 10041@item linewidth 10042@itemx linestyle 10043The line width and style of the line objects of the quiver. @xref{Line 10044Styles}. 10045 10046@item marker 10047@itemx markerfacecolor 10048@itemx markersize 10049The line and fill color of the marker objects at the original of the 10050arrows. @xref{Colors}. 10051 10052@item xdata 10053@itemx ydata 10054@itemx zdata 10055The origins of the values of the vector field. 10056 10057@item udata 10058@itemx vdata 10059@itemx wdata 10060The values of the vector field to plot. 10061 10062@item xdatasource 10063@itemx ydatasource 10064@itemx zdatasource 10065@itemx udatasource 10066@itemx vdatasource 10067@itemx wdatasource 10068Data source variables. 10069@end table 10070 10071@node Scatter Group 10072@subsubsection Scatter Group 10073@cindex group objects 10074@cindex scatter group 10075 10076Scatter series objects are created by the @code{scatter} or @code{scatter3} 10077functions. A single hggroup element contains as many children as there are 10078points in the scatter plot, with each child representing one of the points. 10079The properties of the stem series are 10080 10081@table @code 10082@item linewidth 10083The line width of the line objects of the points. @xref{Line Styles}. 10084 10085@item marker 10086@itemx markeredgecolor 10087@itemx markerfacecolor 10088The line and fill color of the markers of the points. @xref{Colors}. 10089 10090@item xdata 10091@itemx ydata 10092@itemx zdata 10093The original x, y and z data of the stems. 10094 10095@item cdata 10096The color data for the points of the plot. Each point can have a separate 10097color, or a unique color can be specified. 10098 10099@item sizedata 10100The size data for the points of the plot. Each point can its own size or a 10101unique size can be specified. 10102 10103@item xdatasource 10104@itemx ydatasource 10105@itemx zdatasource 10106@itemx cdatasource 10107@itemx sizedatasource 10108Data source variables. 10109@end table 10110 10111@node Stair Group 10112@subsubsection Stair Group 10113@cindex group objects 10114@cindex stair group 10115 10116Stair series objects are created by the @code{stair} function. Each 10117@code{hggroup} element of the series contains a single line object as a 10118child representing the stair. The properties of the stair series are 10119 10120@table @code 10121@item color 10122The RGB color or color name of the line objects of the stairs. @xref{Colors}. 10123 10124@item linewidth 10125@itemx linestyle 10126The line width and style of the line objects of the stairs. @xref{Line 10127Styles}. 10128 10129@item marker 10130@itemx markeredgecolor 10131@itemx markerfacecolor 10132@itemx markersize 10133The line and fill color of the markers on the stairs. @xref{Colors}. 10134 10135@item xdata 10136@itemx ydata 10137The original x and y data of the stairs. 10138 10139@item xdatasource 10140@itemx ydatasource 10141Data source variables. 10142@end table 10143 10144@node Stem Series 10145@subsubsection Stem Series 10146@cindex series objects 10147@cindex stem series 10148 10149Stem series objects are created by the @code{stem} or @code{stem3} 10150functions. Each @code{hggroup} element contains a single line object 10151as a child representing the stems. The properties of the stem series 10152are 10153 10154@table @code 10155@item showbaseline 10156@itemx baseline 10157@itemx basevalue 10158The property @code{showbaseline} flags whether the baseline of the 10159stem series is displayed (default is @qcode{"on"}). The handle of the graphics 10160object representing the baseline is given by the @code{baseline} 10161property and the y-value (or z-value for @code{stem3}) of the baseline 10162by the @code{basevalue} property. 10163 10164Changes to any of these property are propagated to the other members of 10165the stem series and to the baseline itself. Equally changes in the 10166properties of the base line itself are propagated to the members of the 10167corresponding stem series. 10168 10169@item color 10170The RGB color or color name of the line objects of the stems. @xref{Colors}. 10171 10172@item linewidth 10173@itemx linestyle 10174The line width and style of the line objects of the stems. @xref{Line Styles}. 10175 10176@item marker 10177@itemx markeredgecolor 10178@itemx markerfacecolor 10179@itemx markersize 10180The line and fill color of the markers on the stems. @xref{Colors}. 10181 10182@item xdata 10183@itemx ydata 10184@itemx zdata 10185The original x, y and z data of the stems. 10186 10187@item xdatasource 10188@itemx ydatasource 10189@itemx zdatasource 10190Data source variables. 10191@end table 10192 10193@node Surface Group 10194@subsubsection Surface Group 10195@cindex group objects 10196@cindex surface group 10197 10198Surface group objects are created by the @code{surf} or @code{mesh} 10199functions, but are equally one of the handles returned by the @code{surfc} 10200or @code{meshc} functions. The surface group is of the type @code{surface}. 10201 10202The properties of the surface group are 10203 10204@table @code 10205@item edgecolor 10206 10207@item facecolor 10208The RGB color or color name of the edges or faces of the surface. 10209@xref{Colors}. 10210 10211@item linewidth 10212@itemx linestyle 10213The line width and style of the lines on the surface. @xref{Line Styles}. 10214 10215@item marker 10216@itemx markeredgecolor 10217@itemx markerfacecolor 10218@itemx markersize 10219The line and fill color of the markers on the surface. @xref{Colors}. 10220 10221@item xdata 10222@itemx ydata 10223@itemx zdata 10224@itemx cdata 10225The original x, y, z and c data. 10226 10227@item xdatasource 10228@itemx ydatasource 10229@itemx zdatasource 10230@itemx cdatasource 10231Data source variables. 10232@end table 10233 10234@node Transform Groups 10235@subsection Transform Groups 10236@cindex transform groups 10237 10238@c FIXME: Need to add documentation on transforms. 10239 10240@c hgtransform scripts/plot/util/hgtransform.m 10241@anchor{XREFhgtransform} 10242@deftypefn {} {@var{h} =} hgtransform () 10243@deftypefnx {} {@var{h} =} hgtransform (@var{property}, @var{value}, @dots{}) 10244@deftypefnx {} {@var{h} =} hgtransform (@var{hax}, @dots{}) 10245 10246Create a graphics transform object. 10247 10248FIXME: Need to write documentation. 10249FIXME: Add <makehgtform> to seealso list when it is implemented. 10250@xseealso{@ref{XREFhggroup,,hggroup}} 10251@end deftypefn 10252 10253 10254@c @DOCSTRING(makehgtform) 10255 10256@node Graphics Toolkits 10257@subsection Graphics Toolkits 10258@cindex graphics toolkits 10259@cindex toolkits, graphics 10260 10261@c graphics_toolkit scripts/plot/util/graphics_toolkit.m 10262@anchor{XREFgraphics_toolkit} 10263@deftypefn {} {@var{name} =} graphics_toolkit () 10264@deftypefnx {} {@var{name} =} graphics_toolkit (@var{hlist}) 10265@deftypefnx {} {} graphics_toolkit (@var{name}) 10266@deftypefnx {} {} graphics_toolkit (@var{hlist}, @var{name}) 10267Query or set the default graphics toolkit which is assigned to new figures. 10268 10269With no inputs, return the current default graphics toolkit. If the input 10270is a list of figure graphic handles, @var{hlist}, then return the name 10271of the graphics toolkit in use for each figure. 10272 10273When called with a single input @var{name} set the default graphics toolkit 10274to @var{name}. If the toolkit is not already loaded, it is initialized by 10275calling the function @code{__init_@var{name}__}. If the first input 10276is a list of figure handles, @var{hlist}, then the graphics toolkit is set 10277to @var{name} for these figures only. 10278 10279@xseealso{@ref{XREFavailable_graphics_toolkits,,available_graphics_toolkits}} 10280@end deftypefn 10281 10282 10283@c available_graphics_toolkits libinterp/corefcn/graphics.cc 10284@anchor{XREFavailable_graphics_toolkits} 10285@deftypefn {} {} available_graphics_toolkits () 10286Return a cell array of registered graphics toolkits. 10287@xseealso{@ref{XREFgraphics_toolkit,,graphics_toolkit}, @ref{XREFregister_graphics_toolkit,,register_graphics_toolkit}} 10288@end deftypefn 10289 10290 10291@c loaded_graphics_toolkits libinterp/corefcn/graphics.cc 10292@anchor{XREFloaded_graphics_toolkits} 10293@deftypefn {} {} loaded_graphics_toolkits () 10294Return a cell array of the currently loaded graphics toolkits. 10295@xseealso{@ref{XREFavailable_graphics_toolkits,,available_graphics_toolkits}} 10296@end deftypefn 10297 10298 10299@c register_graphics_toolkit libinterp/corefcn/graphics.cc 10300@anchor{XREFregister_graphics_toolkit} 10301@deftypefn {} {} register_graphics_toolkit (@var{toolkit}) 10302List @var{toolkit} as an available graphics toolkit. 10303@xseealso{@ref{XREFavailable_graphics_toolkits,,available_graphics_toolkits}} 10304@end deftypefn 10305 10306 10307@menu 10308* Customizing Toolkit Behavior:: 10309* Hardware vs. Software Rendering:: 10310* Precision issues:: 10311@end menu 10312 10313@node Customizing Toolkit Behavior 10314@subsubsection Customizing Toolkit Behavior 10315@cindex toolkit customization 10316 10317The specific behavior of the backend toolkit may be modified using the 10318following utility functions. Note: Not all functions apply to every 10319graphics toolkit. 10320 10321@c gnuplot_binary scripts/plot/util/gnuplot_binary.in.m 10322@anchor{XREFgnuplot_binary} 10323@deftypefn {} {[@var{prog}, @var{args}] =} gnuplot_binary () 10324@deftypefnx {} {[@var{old_prog}, @var{old_args}] =} gnuplot_binary (@var{new_prog}) 10325@deftypefnx {} {[@var{old_prog}, @var{old_args}] =} gnuplot_binary (@var{new_prog}, @var{arg1}, @dots{}) 10326Query or set the name of the program invoked by the plot command when the 10327graphics toolkit is set to @qcode{"gnuplot"}. 10328 10329Additional arguments to pass to the external plotting program may also be 10330given. The default value is @qcode{"gnuplot"} with no additional arguments. 10331@xref{Installation}. 10332@xseealso{@ref{XREFgraphics_toolkit,,graphics_toolkit}} 10333@end deftypefn 10334 10335 10336@cindex GNUTERM 10337 10338In addition, the gnuplot program usually provides a number of different 10339interfaces, known as terminals. Octave normally chooses a default terminal, 10340but you can override this with the environment variable @env{GNUTERM}. This 10341variable may be set in the shell before starting Octave or from within Octave 10342before plotting for the first time. For example: 10343 10344@example 10345@group 10346setenv ("GNUTERM", "wxt") 10347graphics_toolkit ("gnuplot") 10348plot (1:10) 10349@end group 10350@end example 10351 10352@node Hardware vs. Software Rendering 10353@subsubsection Hardware vs. Software Rendering 10354@cindex opengl rendering slow windows 10355 10356On Windows platforms, Octave uses software rendering for the OpenGL graphics 10357toolkits (@qcode{"qt"} and @qcode{"fltk"}) by default. This is done to avoid 10358rendering and printing issues due to imperfect OpenGL driver implementations 10359for diverse graphic cards from different vendors. As a down-side, software 10360rendering might be considerably slower than hardware accelerated rendering. 10361To permanently switch back to hardware accelerated rendering with your graphic 10362card drivers, rename the following file while Octave is closed: 10363 10364@file{@var{octave-home}\bin\opengl32.dll} 10365@*where @var{octave-home} is the directory in which Octave is installed (the 10366default is @file{C:\Octave\Octave-@var{version}}). 10367 10368@node Precision issues 10369@subsubsection Precision issues 10370@cindex opengl single precision date time 10371 10372The OpenGL graphics toolkits (@qcode{"qt"} and @qcode{"fltk"}) use single 10373precision for rendering. This limitation in particular applies to plots of 10374time series against serial dates as used by the @code{datenum}, @code{datestr}, 10375@code{datestruct}, and @code{datetick} functions. 10376 10377Serial dates encode timestamps as days elapsed since the year zero with hours, 10378minutes, seconds as the fractional part. On December 31st 1999, the serial 10379date representation was 730485. A double precision variable with this integer 10380part allows for a resolution in its fractional part of 1.2e-10, representing 10381about 5 microseconds. But with single precision, the resolution is reduced to 10382about 0.06, representing 45 minutes. Any attempt to plot timestamped data 10383with finer granularity will result in a distorted graph. 10384 10385As a workaround, it is possible to use the @qcode{"gnuplot"} graphics toolkit 10386or subtract 2000 years---i.e., @code{datenum (2000, 0, 0)} or 730485---from the 10387time values. Due to the fact that the calendar structure repeats every 2000 10388years, the relation between year, month, day of month and day of week will stay 10389unchanged and the ticks and ticklabels produced by the @code{datetick} function 10390will still be correct. Only years will lack the millennium digit. Thus, 10391"2020" will be printed as "20". For example: 10392 10393@example 10394@group 10395# timestamps of 24 hours in one minute steps 10396t = datenum (2020, 1, 1):(1/1440):datenum (2020, 1, 2); 10397 10398# some example time series data 10399x = -cos (2*pi*t) + rand (size (t)) / 10; 10400 10401subplot (1, 2, 1); 10402plot (t, x); 10403datetick ("x"); 10404xlabel ("serial date"); 10405title ("problem"); 10406 10407subplot (1, 2, 2); 10408plot (t - 730485, x); 10409datetick ("x"); 10410xlabel ("2000 years off"); 10411title ("workaround"); 10412@end group 10413@end example 10414 10415@ifnotinfo 10416@noindent 10417The result of which can be seen in @ref{fig:precisiondate}. 10418 10419@float Figure,fig:precisiondate 10420@center @image{precisiondate,4in} 10421@caption{Single precision issues with OpenGL graphics toolkits} 10422@end float 10423@end ifnotinfo 10424 10425Similarly, other data can be translated or re-scaled to work around this issue. 10426
