This is octave.info, produced by makeinfo version 6.5 from octave.texi.

INFO-DIR-SECTION Math
START-INFO-DIR-ENTRY
* Octave: (octave).             Interactive language for numerical computations.
END-INFO-DIR-ENTRY

Copyright © 1996-2019 John W. Eaton.

   Permission is granted to make and distribute verbatim copies of this
manual provided the copyright notice and this permission notice are
preserved on all copies.

   Permission is granted to copy and distribute modified versions of
this manual under the conditions for verbatim copying, provided that the
entire resulting derived work is distributed under the terms of a
permission notice identical to this one.

   Permission is granted to copy and distribute translations of this
manual into another language, under the above conditions for modified
versions.


File: octave.info,  Node: Paging Screen Output,  Up: Terminal Output

14.1.1.1 Paging Screen Output
.............................

When running interactively, Octave normally sends all output directly to
the Command Window.  However, when using the CLI version of Octave this
can create a problem because large volumes of data will stream by before
you can read them.  In such cases, it is better to use a paging program
such as ‘less’ or ‘more’ which displays just one screenful at a time.
With ‘less’ (and some versions of ‘more’) you can also scan forward and
backward, and search for specific items.  The pager is enabled by the
command ‘more on’.

   Normally, no output is displayed by the pager until just before
Octave is ready to print the top level prompt, or read from the standard
input (for example, by using the ‘fscanf’ or ‘scanf’ functions).  This
means that there may be some delay before any output appears on your
screen if you have asked Octave to perform a significant amount of work
with a single command statement.  The function ‘fflush’ may be used to
force output to be sent to the pager (or any other stream) immediately.

   You can select the program to run as the pager with the ‘PAGER’
function, and configure the pager itself with the ‘PAGER_FLAGS’
function.

 -- : more
 -- : more on
 -- : more off
     Turn output pagination on or off.

     Without an argument, ‘more’ toggles the current state.

     The current state can be determined via ‘page_screen_output’.

     See also: *note page_screen_output: XREFpage_screen_output, *note
     page_output_immediately: XREFpage_output_immediately, *note PAGER:
     XREFPAGER, *note PAGER_FLAGS: XREFPAGER_FLAGS.

 -- : VAL = PAGER ()
 -- : OLD_VAL = PAGER (NEW_VAL)
 -- : PAGER (NEW_VAL, "local")
     Query or set the internal variable that specifies the program to
     use to display terminal output on your system.

     The default value is normally "less", "more", or "pg", depending on
     what programs are installed on your system.  *Note Installation::.

     When called from inside a function with the "local" option, the
     variable is changed locally for the function and any subroutines it
     calls.  The original variable value is restored when exiting the
     function.

     See also: *note PAGER_FLAGS: XREFPAGER_FLAGS, *note
     page_output_immediately: XREFpage_output_immediately, *note more:
     XREFmore, *note page_screen_output: XREFpage_screen_output.

 -- : VAL = PAGER_FLAGS ()
 -- : OLD_VAL = PAGER_FLAGS (NEW_VAL)
 -- : PAGER_FLAGS (NEW_VAL, "local")
     Query or set the internal variable that specifies the options to
     pass to the pager.

     When called from inside a function with the "local" option, the
     variable is changed locally for the function and any subroutines it
     calls.  The original variable value is restored when exiting the
     function.

     See also: *note PAGER: XREFPAGER, *note more: XREFmore, *note
     page_screen_output: XREFpage_screen_output, *note
     page_output_immediately: XREFpage_output_immediately.

 -- : VAL = page_screen_output ()
 -- : OLD_VAL = page_screen_output (NEW_VAL)
 -- : page_screen_output (NEW_VAL, "local")
     Query or set the internal variable that controls whether output
     intended for the terminal window that is longer than one page is
     sent through a pager.

     This allows you to view one screenful at a time.  Some pagers (such
     as ‘less’—see *note Installation::) are also capable of moving
     backward on the output.

     When called from inside a function with the "local" option, the
     variable is changed locally for the function and any subroutines it
     calls.  The original variable value is restored when exiting the
     function.

     See also: *note more: XREFmore, *note page_output_immediately:
     XREFpage_output_immediately, *note PAGER: XREFPAGER, *note
     PAGER_FLAGS: XREFPAGER_FLAGS.

 -- : VAL = page_output_immediately ()
 -- : OLD_VAL = page_output_immediately (NEW_VAL)
 -- : page_output_immediately (NEW_VAL, "local")
     Query or set the internal variable that controls whether Octave
     sends output to the pager as soon as it is available.

     When the value is ‘false’, Octave buffers its output and waits
     until just before the prompt is printed to flush it to the pager.
     This is the default.

     When ‘page_screen_output’ is ‘false’, this variable has no effect.

     When called from inside a function with the "local" option, the
     variable is changed locally for the function and any subroutines it
     calls.  The original variable value is restored when exiting the
     function.

     See also: *note page_screen_output: XREFpage_screen_output, *note
     more: XREFmore, *note PAGER: XREFPAGER, *note PAGER_FLAGS:
     XREFPAGER_FLAGS.

 -- : fflush (FID)
     Flush output to file descriptor FID.

     ‘fflush’ returns 0 on success and an OS dependent error value (−1
     on Unix) on error.

     Programming Note: Flushing is useful for ensuring that all pending
     output makes it to the screen before some other event occurs.  For
     example, it is always a good idea to flush the standard output
     stream before calling ‘input’.

     See also: *note fopen: XREFfopen, *note fclose: XREFfclose.


File: octave.info,  Node: Terminal Input,  Next: Simple File I/O,  Prev: Terminal Output,  Up: Basic Input and Output

14.1.2 Terminal Input
---------------------

Octave has three functions that make it easy to prompt users for input.
The ‘input’ and ‘menu’ functions are normally used for managing an
interactive dialog with a user, and the ‘keyboard’ function is normally
used for doing simple debugging.

 -- : ANS = input (PROMPT)
 -- : ANS = input (PROMPT, "s")
     Print PROMPT and wait for user input.

     For example,

          input ("Pick a number, any number! ")

     prints the prompt

          Pick a number, any number!

     and waits for the user to enter a value.  The string entered by the
     user is evaluated as an expression, so it may be a literal
     constant, a variable name, or any other valid Octave code.

     The number of return arguments, their size, and their class depend
     on the expression entered.

     If you are only interested in getting a literal string value, you
     can call ‘input’ with the character string "s" as the second
     argument.  This tells Octave to return the string entered by the
     user directly, without evaluating it first.

     Because there may be output waiting to be displayed by the pager,
     it is a good idea to always call ‘fflush (stdout)’ before calling
     ‘input’.  This will ensure that all pending output is written to
     the screen before your prompt.

     See also: *note yes_or_no: XREFyes_or_no, *note kbhit: XREFkbhit,
     *note pause: XREFpause, *note menu: XREFmenu, *note listdlg:
     XREFlistdlg.

 -- : CHOICE = menu (TITLE, OPT1, ...)
 -- : CHOICE = menu (TITLE, {OPT1, ...})
     Display a menu with heading TITLE and options OPT1, ..., and wait
     for user input.

     If the GUI is running, the menu is displayed graphically using
     ‘listdlg’.  Otherwise, the title and menu options are printed on
     the console.

     TITLE is a string and the options may be input as individual
     strings or as a cell array of strings.

     The return value CHOICE is the number of the option selected by the
     user counting from 1.  If the user aborts the dialog or makes an
     invalid selection then 0 is returned.

     This function is useful for interactive programs.  There is no
     limit to the number of options that may be passed in, but it may be
     confusing to present more than will fit easily on one screen.

     See also: *note input: XREFinput, *note listdlg: XREFlistdlg.

 -- : ANS = yes_or_no ("PROMPT")
     Ask the user a yes-or-no question.

     Return logical true if the answer is yes or false if the answer is
     no.

     Takes one argument, PROMPT, which is the string to display when
     asking the question.  PROMPT should end in a space; ‘yes-or-no’
     adds the string ‘(yes or no) ’ to it.  The user must confirm the
     answer with <RET> and can edit it until it has been confirmed.

     See also: *note input: XREFinput.

   For ‘input’, the normal command line history and editing functions
are available at the prompt.

   Octave also has a function that makes it possible to get a single
character from the keyboard without requiring the user to type a
carriage return.

 -- : kbhit ()
 -- : kbhit (1)
     Read a single keystroke from the keyboard.

     If called with an argument, don’t wait for a keypress.

     For example,

          x = kbhit ();

     will set X to the next character typed at the keyboard as soon as
     it is typed.

          x = kbhit (1);

     is identical to the above example, but doesn’t wait for a keypress,
     returning the empty string if no key is available.

     See also: *note input: XREFinput, *note pause: XREFpause.


File: octave.info,  Node: Simple File I/O,  Prev: Terminal Input,  Up: Basic Input and Output

14.1.3 Simple File I/O
----------------------

The ‘save’ and ‘load’ commands allow data to be written to and read from
disk files in various formats.  The default format of files written by
the ‘save’ command can be controlled using the functions
‘save_default_options’ and ‘save_precision’.

   As an example the following code creates a 3-by-3 matrix and saves it
to the file ‘myfile.mat’.

     A = [ 1:3; 4:6; 7:9 ];
     save myfile.mat A

   Once one or more variables have been saved to a file, they can be
read into memory using the ‘load’ command.

     load myfile.mat
     A
          ⊣ A =
          ⊣
          ⊣    1   2   3
          ⊣    4   5   6
          ⊣    7   8   9

 -- : save file
 -- : save options file
 -- : save options file V1 V2 ...
 -- : save options file -struct STRUCT
 -- : save options file -struct STRUCT F1 F2 ...
 -- : save - V1 V2 ...
 -- : STR = save ("-", "V1", "V2", ...)
     Save the named variables V1, V2, ..., in the file FILE.

     The special filename ‘-’ may be used to return the content of the
     variables as a string.  If no variable names are listed, Octave
     saves all the variables in the current scope.  Otherwise, full
     variable names or pattern syntax can be used to specify the
     variables to save.  If the ‘-struct’ modifier is used then the
     fields of the *scalar* struct are saved as if they were variables
     with the corresponding field names.  The ‘-struct’ option can be
     combined with specific field names F1, F2, ... to write only
     certain fields to the file.

     Valid options for the ‘save’ command are listed in the following
     table.  Options that modify the output format override the format
     specified by ‘save_default_options’.

     If save is invoked using the functional form

          save ("-option1", ..., "file", "v1", ...)

     then the OPTIONS, FILE, and variable name arguments (V1, ...) must
     be specified as character strings.

     If called with a filename of "-", write the output to stdout if
     nargout is 0, otherwise return the output in a character string.

     ‘-append’
          Append to the destination instead of overwriting.

     ‘-ascii’
          Save a matrix in a text file without a header or any other
          information.  The matrix must be 2-D and only the real part of
          any complex value is written to the file.  Numbers are stored
          in single-precision format and separated by spaces.
          Additional options for the ‘-ascii’ format are

          ‘-double’
               Store numbers in double-precision format.

          ‘-tabs’
               Separate numbers with tabs.

     ‘-binary’
          Save the data in Octave’s binary data format.

     ‘-float-binary’
          Save the data in Octave’s binary data format but using only
          single precision.  Use this format *only* if you know that all
          the values to be saved can be represented in single precision.

     ‘-hdf5’
          Save the data in HDF5 format.  (HDF5 is a free, portable,
          binary format developed by the National Center for
          Supercomputing Applications at the University of Illinois.)
          This format is only available if Octave was built with a link
          to the HDF5 libraries.

     ‘-float-hdf5’
          Save the data in HDF5 format but using only single precision.
          Use this format *only* if you know that all the values to be
          saved can be represented in single precision.

     ‘-V7’
     ‘-v7’
     ‘-7’
     ‘-mat7-binary’
          Save the data in MATLAB’s v7 binary data format.

     ‘-V6’
     ‘-v6’
     ‘-6’
     ‘-mat’
     ‘-mat-binary’
          Save the data in MATLAB’s v6 binary data format.

     ‘-V4’
     ‘-v4’
     ‘-4’
     ‘-mat4-binary’
          Save the data in the binary format written by MATLAB version
          4.

     ‘-text’
          Save the data in Octave’s text data format.  (default).

     ‘-zip’
     ‘-z’
          Use the gzip algorithm to compress the file.  This works on
          files that are compressed with gzip outside of Octave, and
          gzip can also be used to convert the files for backward
          compatibility.  This option is only available if Octave was
          built with a link to the zlib libraries.

     The list of variables to save may use wildcard patterns containing
     the following special characters:

     ‘?’
          Match any single character.

     ‘*’
          Match zero or more characters.

     ‘[ LIST ]’
          Match the list of characters specified by LIST.  If the first
          character is ‘!’ or ‘^’, match all characters except those
          specified by LIST.  For example, the pattern ‘[a-zA-Z]’ will
          match all lower and uppercase alphabetic characters.

          Wildcards may also be used in the field name specifications
          when using the ‘-struct’ modifier (but not in the struct name
          itself).

     Except when using the MATLAB binary data file format or the
     ‘-ascii’ format, saving global variables also saves the global
     status of the variable.  If the variable is restored at a later
     time using ‘load’, it will be restored as a global variable.

     The command

          save -binary data a b*

     saves the variable ‘a’ and all variables beginning with ‘b’ to the
     file ‘data’ in Octave’s binary format.

     See also: *note load: XREFload, *note save_default_options:
     XREFsave_default_options, *note save_header_format_string:
     XREFsave_header_format_string, *note save_precision:
     XREFsave_precision, *note dlmread: XREFdlmread, *note csvread:
     XREFcsvread, *note fread: XREFfread.

   There are three functions that modify the behavior of ‘save’.

 -- : VAL = save_default_options ()
 -- : OLD_VAL = save_default_options (NEW_VAL)
 -- : save_default_options (NEW_VAL, "local")
     Query or set the internal variable that specifies the default
     options for the ‘save’ command, and defines the default format.

     The default value is "-text" (Octave’s own text-based file format).
     See the documentation of the ‘save’ command for other choices.

     When called from inside a function with the "local" option, the
     variable is changed locally for the function and any subroutines it
     calls.  The original variable value is restored when exiting the
     function.

     See also: *note save: XREFsave, *note save_header_format_string:
     XREFsave_header_format_string, *note save_precision:
     XREFsave_precision.

 -- : VAL = save_precision ()
 -- : OLD_VAL = save_precision (NEW_VAL)
 -- : save_precision (NEW_VAL, "local")
     Query or set the internal variable that specifies the number of
     digits to keep when saving data in text format.

     The default value is 17 which is the minimum necessary for the
     lossless saving and restoring of IEEE-754 double values; For
     IEEE-754 single values the minimum value is 9.  If file size is a
     concern, it is probably better to choose a binary format for saving
     data rather than to reduce the precision of the saved values.

     When called from inside a function with the "local" option, the
     variable is changed locally for the function and any subroutines it
     calls.  The original variable value is restored when exiting the
     function.

     See also: *note save_default_options: XREFsave_default_options.

 -- : VAL = save_header_format_string ()
 -- : OLD_VAL = save_header_format_string (NEW_VAL)
 -- : save_header_format_string (NEW_VAL, "local")
     Query or set the internal variable that specifies the format string
     used for the comment line written at the beginning of text-format
     data files saved by Octave.

     The format string is passed to ‘strftime’ and must begin with the
     character ‘#’ and contain no newline characters.  If the value of
     ‘save_header_format_string’ is the empty string, the header comment
     is omitted from text-format data files.  The default value is

          "# Created by Octave VERSION, %a %b %d %H:%M:%S %Y %Z <USER@HOST>"

     When called from inside a function with the "local" option, the
     variable is changed locally for the function and any subroutines it
     calls.  The original variable value is restored when exiting the
     function.

     See also: *note strftime: XREFstrftime, *note save_default_options:
     XREFsave_default_options.

 -- : load file
 -- : load options file
 -- : load options file v1 v2 ...
 -- : S = load ("options", "file", "v1", "v2", ...)
 -- : load file options
 -- : load file options v1 v2 ...
 -- : S = load ("file", "options", "v1", "v2", ...)
     Load the named variables V1, V2, ..., from the file FILE.

     If no variables are specified then all variables found in the file
     will be loaded.  As with ‘save’, the list of variables to extract
     can be full names or use a pattern syntax.  The format of the file
     is automatically detected but may be overridden by supplying the
     appropriate option.

     If load is invoked using the functional form

          load ("-option1", ..., "file", "v1", ...)

     then the OPTIONS, FILE, and variable name arguments (V1, ...) must
     be specified as character strings.

     If a variable that is not marked as global is loaded from a file
     when a global symbol with the same name already exists, it is
     loaded in the global symbol table.  Also, if a variable is marked
     as global in a file and a local symbol exists, the local symbol is
     moved to the global symbol table and given the value from the file.

     If invoked with a single output argument, Octave returns data
     instead of inserting variables in the symbol table.  If the data
     file contains only numbers (TAB- or space-delimited columns), a
     matrix of values is returned.  Otherwise, ‘load’ returns a
     structure with members corresponding to the names of the variables
     in the file.

     The ‘load’ command can read data stored in Octave’s text and binary
     formats, and MATLAB’s binary format.  If compiled with zlib
     support, it can also load gzip-compressed files.  It will
     automatically detect the type of file and do conversion from
     different floating point formats (currently only IEEE big and
     little endian, though other formats may be added in the future).

     Valid options for ‘load’ are listed in the following table.

     ‘-force’
          This option is accepted for backward compatibility but is
          ignored.  Octave now overwrites variables currently in memory
          with those of the same name found in the file.

     ‘-ascii’
          Force Octave to assume the file contains columns of numbers in
          text format without any header or other information.  Data in
          the file will be loaded as a single numeric matrix with the
          name of the variable derived from the name of the file.

     ‘-binary’
          Force Octave to assume the file is in Octave’s binary format.

     ‘-hdf5’
          Force Octave to assume the file is in HDF5 format.  (HDF5 is a
          free, portable binary format developed by the National Center
          for Supercomputing Applications at the University of
          Illinois.)  Note that Octave can only read HDF5 files that
          were created by itself with ‘save’.  This format is only
          available if Octave was built with a link to the HDF5
          libraries.

     ‘-import’
          This option is accepted for backward compatibility but is
          ignored.  Octave can now support multi-dimensional HDF data
          and automatically modifies variable names if they are invalid
          Octave identifiers.

     ‘-mat’
     ‘-mat-binary’
     ‘-6’
     ‘-v6’
     ‘-7’
     ‘-v7’
          Force Octave to assume the file is in MATLAB’s version 6 or 7
          binary format.

     ‘-mat4-binary’
     ‘-4’
     ‘-v4’
     ‘-V4’
          Force Octave to assume the file is in the binary format
          written by MATLAB version 4.

     ‘-text’
          Force Octave to assume the file is in Octave’s text format.

     See also: *note save: XREFsave, *note dlmwrite: XREFdlmwrite, *note
     csvwrite: XREFcsvwrite, *note fwrite: XREFfwrite.

 -- : STR = fileread (FILENAME)
     Read the contents of FILENAME and return it as a string.

     See also: *note fread: XREFfread, *note fscanf: XREFfscanf, *note
     importdata: XREFimportdata, *note textscan: XREFtextscan, *note
     type: XREFtype.

 -- : native_float_format ()
     Return the native floating point format as a string.

   It is possible to write data to a file in a similar way to the ‘disp’
function for writing data to the screen.  The ‘fdisp’ works just like
‘disp’ except its first argument is a file pointer as created by
‘fopen’.  As an example, the following code writes to data ‘myfile.txt’.

     fid = fopen ("myfile.txt", "w");
     fdisp (fid, "3/8 is ");
     fdisp (fid, 3/8);
     fclose (fid);

*Note Opening and Closing Files::, for details on how to use ‘fopen’ and
‘fclose’.

 -- : fdisp (FID, X)
     Display the value of X on the stream FID.

     For example:

          fdisp (stdout, "The value of pi is:"), fdisp (stdout, pi)

               ⊣ the value of pi is:
               ⊣ 3.1416

     Note that the output from ‘fdisp’ always ends with a newline.

     See also: *note disp: XREFdisp.

   Octave can also read and write matrices text files such as comma
separated lists.

 -- : dlmwrite (FILE, M)
 -- : dlmwrite (FILE, M, DELIM, R, C)
 -- : dlmwrite (FILE, M, KEY, VAL ...)
 -- : dlmwrite (FILE, M, "-append", ...)
 -- : dlmwrite (FID, ...)
     Write the numeric matrix M to the text file FILE using a delimiter.

     FILE should be a filename or a writable file ID given by ‘fopen’.

     The parameter DELIM specifies the delimiter to use to separate
     values on a row.  If no delimiter is specified the comma character
     ‘,’ is used.

     The value of R specifies the number of delimiter-only lines to add
     to the start of the file.

     The value of C specifies the number of delimiters to prepend to
     each line of data.

     If the argument "-append" is given, append to the end of FILE.

     In addition, the following keyword value pairs may appear at the
     end of the argument list:

     "append"
          Either "on" or "off".  See "-append" above.

     "delimiter"
          See DELIM above.

     "newline"
          The character(s) to separate each row.  Three special cases
          exist for this option.  "unix" is changed into "\n", "pc" is
          changed into "\r\n", and "mac" is changed into "\r".  Any
          other value is used directly as the newline separator.

     "roffset"
          See R above.

     "coffset"
          See C above.

     "precision"
          The precision to use when writing the file.  It can either be
          a format string (as used by fprintf) or a number of
          significant digits.

          dlmwrite ("file.csv", reshape (1:16, 4, 4));

          dlmwrite ("file.tex", a, "delimiter", "&", "newline", "\n")

     See also: *note dlmread: XREFdlmread, *note csvread: XREFcsvread,
     *note csvwrite: XREFcsvwrite.

 -- : DATA = dlmread (FILE)
 -- : DATA = dlmread (FILE, SEP)
 -- : DATA = dlmread (FILE, SEP, R0, C0)
 -- : DATA = dlmread (FILE, SEP, RANGE)
 -- : DATA = dlmread (..., "emptyvalue", EMPTYVAL)
     Read numeric data from the text file FILE which uses the delimiter
     SEP between data values.

     If SEP is not defined the separator between fields is determined
     from the file itself.

     The optional scalar arguments R0 and C0 define the starting row and
     column of the data to be read.  These values are indexed from zero,
     i.e., the first data row corresponds to an index of zero.

     The RANGE parameter specifies exactly which data elements are read.
     The first form of the parameter is a 4-element vector containing
     the upper left and lower right corners ‘[R0,C0,R1,C1]’ where the
     indices are zero-based.  Alternatively, a spreadsheet style form
     such as "A2..Q15" or "T1:AA5" can be used.  The lowest alphabetical
     index ’A’ refers to the first column.  The lowest row index is 1.

     FILE should be a filename or a file id given by ‘fopen’.  In the
     latter case, the file is read until end of file is reached.

     The "emptyvalue" option may be used to specify the value used to
     fill empty fields.  The default is zero.  Note that any non-numeric
     values, such as text, are also replaced by the "emptyvalue".

     See also: *note csvread: XREFcsvread, *note textscan: XREFtextscan,
     *note dlmwrite: XREFdlmwrite.

 -- : csvwrite (FILENAME, X)
 -- : csvwrite (FILENAME, X, DLM_OPT1, ...)
     Write the numeric matrix X to the file FILENAME in
     comma-separated-value (CSV) format.

     This function is equivalent to

          dlmwrite (FILENAME, X, ",", DLM_OPT1, ...)

     Any optional arguments are passed directly to ‘dlmwrite’ (*note
     dlmwrite: XREFdlmwrite.).

     See also: *note csvread: XREFcsvread, *note dlmwrite: XREFdlmwrite,
     *note dlmread: XREFdlmread.

 -- : X = csvread (FILENAME)
 -- : X = csvread (FILENAME, DLM_OPT1, ...)
     Read the comma-separated-value (CSV) file FILENAME into the matrix
     X.

     Note: only CSV files containing numeric data can be read.

     This function is equivalent to

          X = dlmread (FILENAME, "," , DLM_OPT1, ...)

     Any optional arguments are passed directly to ‘dlmread’ (*note
     dlmread: XREFdlmread.).

     See also: *note dlmread: XREFdlmread, *note textscan: XREFtextscan,
     *note csvwrite: XREFcsvwrite, *note dlmwrite: XREFdlmwrite.

   Formatted data from can be read from, or written to, text files as
well.

 -- : [A, ...] = textread (FILENAME)
 -- : [A, ...] = textread (FILENAME, FORMAT)
 -- : [A, ...] = textread (FILENAME, FORMAT, N)
 -- : [A, ...] = textread (FILENAME, FORMAT, PROP1, VALUE1, ...)
 -- : [A, ...] = textread (FILENAME, FORMAT, N, PROP1, VALUE1, ...)

     This function is obsolete.  Use ‘textscan’ instead.

     Read data from a text file.

     The file FILENAME is read and parsed according to FORMAT.  The
     function behaves like ‘strread’ except it works by parsing a file
     instead of a string.  See the documentation of ‘strread’ for
     details.

     In addition to the options supported by ‘strread’, this function
     supports two more:

        • "headerlines": The first VALUE number of lines of FILENAME are
          skipped.

        • "endofline": Specify a single character or "\r\n".  If no
          value is given, it will be inferred from the file.  If set to
          "" (empty string) EOLs are ignored as delimiters.

     The optional input N (format repeat count) specifies the number of
     times the format string is to be used or the number of lines to be
     read, whichever happens first while reading.  The former is
     equivalent to requesting that the data output vectors should be of
     length N.  Note that when reading files with format strings
     referring to multiple lines, N should rather be the number of lines
     to be read than the number of format string uses.

     If the format string is empty (not just omitted) and the file
     contains only numeric data (excluding headerlines), textread will
     return a rectangular matrix with the number of columns matching the
     number of numeric fields on the first data line of the file.  Empty
     fields are returned as zero values.

     Examples:

            Assume a data file like:
            1 a 2 b
            3 c 4 d
            5 e

            [a, b] = textread (f, "%f %s")
            returns two columns of data, one with doubles, the other a
            cellstr array:
            a = [1; 2; 3; 4; 5]
            b = {"a"; "b"; "c"; "d"; "e"}

            [a, b] = textread (f, "%f %s", 3)
            (read data into two culumns, try to use the format string
            three times)
            returns
            a = [1; 2; 3]
            b = {"a"; "b"; "c"}


            With a data file like:
            1
            a
            2
            b

            [a, b] = textread (f, "%f %s", 2)
            returns a = 1 and b = {"a"}; i.e., the format string is used
            only once because the format string refers to 2 lines of the
            data file.  To obtain 2x1 data output columns, specify N = 4
            (number of data lines containing all requested data) rather
            than 2.

     See also: *note textscan: XREFtextscan, *note load: XREFload, *note
     dlmread: XREFdlmread, *note fscanf: XREFfscanf, *note strread:
     XREFstrread.

 -- : C = textscan (FID, FORMAT)
 -- : C = textscan (FID, FORMAT, REPEAT)
 -- : C = textscan (FID, FORMAT, PARAM, VALUE, ...)
 -- : C = textscan (FID, FORMAT, REPEAT, PARAM, VALUE, ...)
 -- : C = textscan (STR, ...)
 -- : [C, POSITION, ERRMSG] = textscan (...)
     Read data from a text file or string.

     The string STR or file associated with FID is read from and parsed
     according to FORMAT.  The function is an extension of ‘strread’ and
     ‘textread’.  Differences include: the ability to read from either a
     file or a string, additional options, and additional format
     specifiers.

     The input is interpreted as a sequence of words, delimiters (such
     as whitespace), and literals.  The characters that form delimiters
     and whitespace are determined by the options.  The format consists
     of format specifiers interspersed between literals.  In the format,
     whitespace forms a delimiter between consecutive literals, but is
     otherwise ignored.

     The output C is a cell array where the number of columns is
     determined by the number of format specifiers.

     The first word of the input is matched to the first specifier of
     the format and placed in the first column of the output; the second
     is matched to the second specifier and placed in the second column
     and so forth.  If there are more words than specifiers then the
     process is repeated until all words have been processed or the
     limit imposed by REPEAT has been met (see below).

     The string FORMAT describes how the words in STR should be parsed.
     As in FSCANF, any (non-whitespace) text in the format that is not
     one of these specifiers is considered a literal.  If there is a
     literal between two format specifiers then that same literal must
     appear in the input stream between the matching words.

     The following specifiers are valid:

     ‘%f’
     ‘%f64’
     ‘%n’
          The word is parsed as a number and converted to double.

     ‘%f32’
          The word is parsed as a number and converted to single
          (float).

     ‘%d’
     ‘%d8’
     ‘%d16’
     ‘%d32’
     ‘%d64’
          The word is parsed as a number and converted to int8, int16,
          int32, or int64.  If no size is specified then int32 is used.

     ‘%u’
     ‘%u8’
     ‘%u16’
     ‘%u32’
     ‘%u64’
          The word is parsed as a number and converted to uint8, uint16,
          uint32, or uint64.  If no size is specified then uint32 is
          used.

     ‘%s’
          The word is parsed as a string ending at the last character
          before whitespace, an end-of-line, or a delimiter specified in
          the options.

     ‘%q’
          The word is parsed as a "quoted string".  If the first
          character of the string is a double quote (") then the string
          includes everything until a matching double quote—including
          whitespace, delimiters, and end-of-line characters.  If a pair
          of consecutive double quotes appears in the input, it is
          replaced in the output by a single double quote.  For
          examples, the input "He said ""Hello""" would return the value
          ’He said "Hello"’.

     ‘%c’
          The next character of the input is read.  This includes
          delimiters, whitespace, and end-of-line characters.

     ‘%[...]’
     ‘%[^...]’
          In the first form, the word consists of the longest run
          consisting of only characters between the brackets.  Ranges of
          characters can be specified by a hyphen; for example,
          %[0-9a-zA-Z] matches all alphanumeric characters (if the
          underlying character set is ASCII). Since MATLAB treats
          hyphens literally, this expansion only applies to alphanumeric
          characters.  To include ’-’ in the set, it should appear first
          or last in the brackets; to include ’]’, it should be the
          first character.  If the first character is ’^’ then the word
          consists of characters *not* listed.

     ‘%N...’
          For %s, %c %d, %f, %n, %u, an optional width can be specified
          as %Ns, etc.  where N is an integer > 1.  For %c, this causes
          exactly N characters to be read instead of a single character.
          For the other specifiers, it is an upper bound on the number
          of characters read; normal delimiters can cause fewer
          characters to be read.  For complex numbers, this limit
          applies to the real and imaginary components individually.
          For %f and %n, format specifiers like %N.Mf are allowed, where
          M is an upper bound on number of characters after the decimal
          point to be considered; subsequent digits are skipped.  For
          example, the specifier %8.2f would read 12.345e6 as 1.234e7.

     ‘%*...’
          The word specified by the remainder of the conversion
          specifier is skipped.

     ‘literals’
          In addition the format may contain literal character strings;
          these will be skipped during reading.  If the input string
          does not match this literal, the processing terminates.

     Parsed words corresponding to the first specifier are returned in
     the first output argument and likewise for the rest of the
     specifiers.

     By default, if there is only one input argument, FORMAT is "%f".
     This means that numbers are read from the input into a single
     column vector.  If FORMAT is explicitly empty ("") then textscan
     will return data in a number of columns matching the number of
     fields on the first data line of the input.  Either of these is
     suitable only when the input is exclusively numeric.

     For example, the string

          STR = "\
          Bunny Bugs   5.5\n\
          Duck Daffy  -7.5e-5\n\
          Penguin Tux   6"

     can be read using

          A = textscan (STR, "%s %s %f");

     The optional numeric argument REPEAT can be used for limiting the
     number of items read:

     -1
          Read all of the string or file until the end (default).

     N
          Read until the first of two conditions occurs: 1) the format
          has been processed N times, or 2) N lines of the input have
          been processed.  Zero (0) is an acceptable value for REPEAT.
          Currently, end-of-line characters inside %q, %c, and %[...]$
          conversions do not contribute to the line count.  This is
          incompatible with MATLAB and may change in future.

     The behavior of ‘textscan’ can be changed via property/value pairs.
     The following properties are recognized:

     "BufSize"
          This specifies the number of bytes to use for the internal
          buffer.  A modest speed improvement may be obtained by setting
          this to a large value when reading a large file, especially if
          the input contains long strings.  The default is 4096, or a
          value dependent on N if that is specified.

     "CollectOutput"
          A value of 1 or true instructs ‘textscan’ to concatenate
          consecutive columns of the same class in the output cell
          array.  A value of 0 or false (default) leaves output in
          distinct columns.

     "CommentStyle"
          Specify parts of the input which are considered comments and
          will be skipped.  VALUE is the comment style and can be either
          (1) A string or 1x1 cell string, to skip everything to the
          right of it; (2) A cell array of two strings, to skip
          everything between the first and second strings.  Comments are
          only parsed where whitespace is accepted and do not act as
          delimiters.

     "Delimiter"
          If VALUE is a string, any character in VALUE will be used to
          split the input into words.  If VALUE is a cell array of
          strings, any string in the array will be used to split the
          input into words.  (default value = any whitespace.)

     "EmptyValue"
          Value to return for empty numeric values in non-whitespace
          delimited data.  The default is NaN.  When the data type does
          not support NaN (int32 for example), then the default is zero.

     "EndOfLine"
          VALUE can be either an emtpy or one character specifying the
          end-of-line character, or the pair "\r\n" (CRLF). In the
          latter case, any of "\r", "\n" or "\r\n" is counted as a
          (single) newline.  If no value is given, "\r\n" is used.

     "HeaderLines"
          The first VALUE number of lines of FID are skipped.  Note that
          this does not refer to the first non-comment lines, but the
          first lines of any type.

     "MultipleDelimsAsOne"
          If VALUE is nonzero, treat a series of consecutive delimiters,
          without whitespace in between, as a single delimiter.
          Consecutive delimiter series need not be vertically aligned.
          Without this option, a single delimiter before the end of the
          line does not cause the line to be considered to end with an
          empty value, but a single delimiter at the start of a line
          causes the line to be considered to start with an empty value.

     "TreatAsEmpty"
          Treat single occurrences (surrounded by delimiters or
          whitespace) of the string(s) in VALUE as missing values.

     "ReturnOnError"
          If set to numerical 1 or true, return normally as soon as an
          error is encountered, such as trying to read a string using
          ‘%f’.  If set to 0 or false, return an error and no data.

     "Whitespace"
          Any character in VALUE will be interpreted as whitespace and
          trimmed; The default value for whitespace is " \b\r\n\t" (note
          the space).  Unless whitespace is set to "" (empty) AND at
          least one "%s" format conversion specifier is supplied, a
          space is always part of whitespace.

     When the number of words in STR or FID doesn’t match an exact
     multiple of the number of format conversion specifiers,
     ‘textscan’’s behavior depends on whether the last character of the
     string or file is an end-of-line as specified by the ‘EndOfLine’
     option:

     last character = end-of-line
          Data columns are padded with empty fields, NaN or 0 (for
          integer fields) so that all columns have equal length

     last character is not end-of-line
          Data columns are not padded; ‘textscan’ returns columns of
          unequal length

     The second output POSITION provides the location, in characters
     from the beginning of the file or string, where processing stopped.

     See also: *note dlmread: XREFdlmread, *note fscanf: XREFfscanf,
     *note load: XREFload, *note strread: XREFstrread, *note textread:
     XREFtextread.

   The ‘importdata’ function has the ability to work with a wide variety
of data.

 -- : A = importdata (FNAME)
 -- : A = importdata (FNAME, DELIMITER)
 -- : A = importdata (FNAME, DELIMITER, HEADER_ROWS)
 -- : [A, DELIMITER] = importdata (...)
 -- : [A, DELIMITER, HEADER_ROWS] = importdata (...)
     Import data from the file FNAME.

     Input parameters:

        • FNAME The name of the file containing data.

        • DELIMITER The character separating columns of data.  Use ‘\t’
          for tab.  (Only valid for ASCII files)

        • HEADER_ROWS The number of header rows before the data begins.
          (Only valid for ASCII files)

     Different file types are supported:

        • ASCII table

          Import ASCII table using the specified number of header rows
          and the specified delimiter.

        • Image file

        • MATLAB file

        • Spreadsheet files (depending on external software)

        • WAV file

     See also: *note textscan: XREFtextscan, *note dlmread: XREFdlmread,
     *note csvread: XREFcsvread, *note load: XREFload.

* Menu:

* Saving Data on Unexpected Exits::


File: octave.info,  Node: Saving Data on Unexpected Exits,  Up: Simple File I/O

14.1.3.1 Saving Data on Unexpected Exits
........................................

If Octave for some reason exits unexpectedly it will by default save the
variables available in the workspace to a file in the current directory.
By default this file is named ‘octave-workspace’ and can be loaded into
memory with the ‘load’ command.  While the default behavior most often
is reasonable it can be changed through the following functions.

 -- : VAL = crash_dumps_octave_core ()
 -- : OLD_VAL = crash_dumps_octave_core (NEW_VAL)
 -- : crash_dumps_octave_core (NEW_VAL, "local")
     Query or set the internal variable that controls whether Octave
     tries to save all current variables to the file ‘octave-workspace’
     if it crashes or receives a hangup, terminate or similar signal.

     When called from inside a function with the "local" option, the
     variable is changed locally for the function and any subroutines it
     calls.  The original variable value is restored when exiting the
     function.

     See also: *note octave_core_file_limit: XREFoctave_core_file_limit,
     *note octave_core_file_name: XREFoctave_core_file_name, *note
     octave_core_file_options: XREFoctave_core_file_options.

 -- : VAL = sighup_dumps_octave_core ()
 -- : OLD_VAL = sighup_dumps_octave_core (NEW_VAL)
 -- : sighup_dumps_octave_core (NEW_VAL, "local")
     Query or set the internal variable that controls whether Octave
     tries to save all current variables to the file ‘octave-workspace’
     if it receives a hangup signal.

     When called from inside a function with the "local" option, the
     variable is changed locally for the function and any subroutines it
     calls.  The original variable value is restored when exiting the
     function.

 -- : VAL = sigquit_dumps_octave_core ()
 -- : OLD_VAL = sigquit_dumps_octave_core (NEW_VAL)
 -- : sigquit_dumps_octave_core (NEW_VAL, "local")
     Query or set the internal variable that controls whether Octave
     tries to save all current variables to the file ‘octave-workspace’
     if it receives a quit signal.

     When called from inside a function with the "local" option, the
     variable is changed locally for the function and any subroutines it
     calls.  The original variable value is restored when exiting the
     function.

 -- : VAL = sigterm_dumps_octave_core ()
 -- : OLD_VAL = sigterm_dumps_octave_core (NEW_VAL)
 -- : sigterm_dumps_octave_core (NEW_VAL, "local")
     Query or set the internal variable that controls whether Octave
     tries to save all current variables to the file ‘octave-workspace’
     if it receives a terminate signal.

     When called from inside a function with the "local" option, the
     variable is changed locally for the function and any subroutines it
     calls.  The original variable value is restored when exiting the
     function.

 -- : VAL = octave_core_file_options ()
 -- : OLD_VAL = octave_core_file_options (NEW_VAL)
 -- : octave_core_file_options (NEW_VAL, "local")
     Query or set the internal variable that specifies the options used
     for saving the workspace data if Octave aborts.

     The value of ‘octave_core_file_options’ should follow the same
     format as the options for the ‘save’ function.  The default value
     is Octave’s binary format.

     When called from inside a function with the "local" option, the
     variable is changed locally for the function and any subroutines it
     calls.  The original variable value is restored when exiting the
     function.

     See also: *note crash_dumps_octave_core:
     XREFcrash_dumps_octave_core, *note octave_core_file_name:
     XREFoctave_core_file_name, *note octave_core_file_limit:
     XREFoctave_core_file_limit.

 -- : VAL = octave_core_file_limit ()
 -- : OLD_VAL = octave_core_file_limit (NEW_VAL)
 -- : octave_core_file_limit (NEW_VAL, "local")
     Query or set the internal variable that specifies the maximum
     amount of memory that Octave will save when writing a crash dump
     file.

     The limit is measured in kilobytes and is applied to the top-level
     workspace.  The name of the crash dump file is specified by
     OCTAVE_CORE_FILE_NAME.

     If OCTAVE_CORE_FILE_OPTIONS flags specify a binary format, then
     OCTAVE_CORE_FILE_LIMIT will be approximately the maximum size of
     the file.  If a text file format is used, then the file could be
     much larger than the limit.  The default value is -1 (unlimited).

     When called from inside a function with the "local" option, the
     variable is changed locally for the function and any subroutines it
     calls.  The original variable value is restored when exiting the
     function.

     See also: *note crash_dumps_octave_core:
     XREFcrash_dumps_octave_core, *note octave_core_file_name:
     XREFoctave_core_file_name, *note octave_core_file_options:
     XREFoctave_core_file_options.

 -- : VAL = octave_core_file_name ()
 -- : OLD_VAL = octave_core_file_name (NEW_VAL)
 -- : octave_core_file_name (NEW_VAL, "local")
     Query or set the internal variable that specifies the name of the
     file used for saving data from the top-level workspace if Octave
     aborts.

     The default value is "octave-workspace"

     When called from inside a function with the "local" option, the
     variable is changed locally for the function and any subroutines it
     calls.  The original variable value is restored when exiting the
     function.

     See also: *note crash_dumps_octave_core:
     XREFcrash_dumps_octave_core, *note octave_core_file_name:
     XREFoctave_core_file_name, *note octave_core_file_options:
     XREFoctave_core_file_options.


File: octave.info,  Node: C-Style I/O Functions,  Prev: Basic Input and Output,  Up: Input and Output

14.2 C-Style I/O Functions
==========================

Octave’s C-style input and output functions provide most of the
functionality of the C programming language’s standard I/O library.  The
argument lists for some of the input functions are slightly different,
however, because Octave has no way of passing arguments by reference.

   In the following, FILE refers to a filename and ‘fid’ refers to an
integer file number, as returned by ‘fopen’.

   There are three files that are always available.  Although these
files can be accessed using their corresponding numeric file ids, you
should always use the symbolic names given in the table below, since it
will make your programs easier to understand.

 -- : stdin ()
     Return the numeric value corresponding to the standard input
     stream.

     When Octave is used interactively, stdin is filtered through the
     command line editing functions.

     See also: *note stdout: XREFstdout, *note stderr: XREFstderr.

 -- : stdout ()
     Return the numeric value corresponding to the standard output
     stream.

     Data written to the standard output may be filtered through the
     pager.

     See also: *note stdin: XREFstdin, *note stderr: XREFstderr, *note
     page_screen_output: XREFpage_screen_output.

 -- : stderr ()
     Return the numeric value corresponding to the standard error
     stream.

     Even if paging is turned on, the standard error is not sent to the
     pager.  It is useful for error messages and prompts.

     See also: *note stdin: XREFstdin, *note stdout: XREFstdout.

* Menu:

* Opening and Closing Files::
* Simple Output::
* Line-Oriented Input::
* Formatted Output::
* Output Conversion for Matrices::
* Output Conversion Syntax::
* Table of Output Conversions::
* Integer Conversions::
* Floating-Point Conversions::
* Other Output Conversions::
* Formatted Input::
* Input Conversion Syntax::
* Table of Input Conversions::
* Numeric Input Conversions::
* String Input Conversions::
* Binary I/O::
* Temporary Files::
* EOF and Errors::
* File Positioning::


File: octave.info,  Node: Opening and Closing Files,  Next: Simple Output,  Up: C-Style I/O Functions

14.2.1 Opening and Closing Files
--------------------------------

When reading data from a file it must be opened for reading first, and
likewise when writing to a file.  The ‘fopen’ function returns a pointer
to an open file that is ready to be read or written.  Once all data has
been read from or written to the opened file it should be closed.  The
‘fclose’ function does this.  The following code illustrates the basic
pattern for writing to a file, but a very similar pattern is used when
reading a file.

     filename = "myfile.txt";
     fid = fopen (filename, "w");
     # Do the actual I/O here...
     fclose (fid);

 -- : FID = fopen (NAME)
 -- : FID = fopen (NAME, MODE)
 -- : FID = fopen (NAME, MODE, ARCH)
 -- : [FID, MSG] = fopen (...)
 -- : FID_LIST = fopen ("all")
 -- : [FILE, MODE, ARCH] = fopen (FID)
     Open a file for low-level I/O or query open files and file
     descriptors.

     The first form of the ‘fopen’ function opens the named file with
     the specified mode (read-write, read-only, etc.) and architecture
     interpretation (IEEE big endian, IEEE little endian, etc.), and
     returns an integer value that may be used to refer to the file
     later.  If an error occurs, FID is set to −1 and MSG contains the
     corresponding system error message.  The MODE is a one or two
     character string that specifies whether the file is to be opened
     for reading, writing, or both.

     The second form of the ‘fopen’ function returns a vector of file
     ids corresponding to all the currently open files, excluding the
     ‘stdin’, ‘stdout’, and ‘stderr’ streams.

     The third form of the ‘fopen’ function returns information about
     the open file given its file id.

     For example,

          myfile = fopen ("splat.dat", "r", "ieee-le");

     opens the file ‘splat.dat’ for reading.  If necessary, binary
     numeric values will be read assuming they are stored in IEEE format
     with the least significant bit first, and then converted to the
     native representation.

     Opening a file that is already open simply opens it again and
     returns a separate file id.  It is not an error to open a file
     several times, though writing to the same file through several
     different file ids may produce unexpected results.

     The possible values of MODE are

     ‘r’ (default)
          Open a file for reading.

     ‘w’
          Open a file for writing.  The previous contents are discarded.

     ‘a’
          Open or create a file for writing at the end of the file.

     ‘r+’
          Open an existing file for reading and writing.

     ‘w+’
          Open a file for reading or writing.  The previous contents are
          discarded.

     ‘a+’
          Open or create a file for reading or writing at the end of the
          file.

     Append a "t" to the mode string to open the file in text mode or a
     "b" to open in binary mode.  On Windows systems, text mode reading
     and writing automatically converts linefeeds to the appropriate
     line end character for the system (carriage-return linefeed on
     Windows).  The default when no mode is specified is binary.

     Additionally, you may append a "z" to the mode string to open a
     gzipped file for reading or writing.  For this to be successful,
     you must also open the file in binary mode.

     The parameter ARCH is a string specifying the default data format
     for the file.  Valid values for ARCH are:

     "native" or "n" (default)
          The format of the current machine.

     "ieee-be" or "b"
          IEEE big endian format.

     "ieee-le" or "l"
          IEEE little endian format.

     However, conversions are currently only supported for ‘native’,
     ‘ieee-be’, and ‘ieee-le’ formats.

     When opening a new file that does not yet exist, permissions will
     be set to ‘0666 - UMASK’.

     Compatibility Note: Octave opens files using buffered I/O. Small
     writes are accumulated until an internal buffer is filled, and then
     everything is written in a single operation.  This is very
     efficient and improves performance.  MATLAB, however, opens files
     using flushed I/O where every write operation is immediately
     performed.  If the write operation must be performed immediately
     after data has been written then the write should be followed by a
     call to ‘fflush’ to flush the internal buffer.

     See also: *note fclose: XREFfclose, *note fgets: XREFfgets, *note
     fgetl: XREFfgetl, *note fscanf: XREFfscanf, *note fread: XREFfread,
     *note fputs: XREFfputs, *note fdisp: XREFfdisp, *note fprintf:
     XREFfprintf, *note fwrite: XREFfwrite, *note fskipl: XREFfskipl,
     *note fseek: XREFfseek, *note frewind: XREFfrewind, *note ftell:
     XREFftell, *note feof: XREFfeof, *note ferror: XREFferror, *note
     fclear: XREFfclear, *note fflush: XREFfflush, *note freport:
     XREFfreport, *note umask: XREFumask.

 -- : fclose (FID)
 -- : fclose ("all")
 -- : STATUS = fclose ("all")
     Close the file specified by the file descriptor FID.

     If successful, ‘fclose’ returns 0, otherwise, it returns -1.  The
     second form of the ‘fclose’ call closes all open files except
     ‘stdin’, ‘stdout’, ‘stderr’, and any FIDs associated with gnuplot.

     See also: *note fopen: XREFfopen, *note fflush: XREFfflush, *note
     freport: XREFfreport.

 -- : is_valid_file_id (FID)
     Return true if FID refers to an open file.

     See also: *note freport: XREFfreport, *note fopen: XREFfopen.


File: octave.info,  Node: Simple Output,  Next: Line-Oriented Input,  Prev: Opening and Closing Files,  Up: C-Style I/O Functions

14.2.2 Simple Output
--------------------

Once a file has been opened for writing a string can be written to the
file using the ‘fputs’ function.  The following example shows how to
write the string ‘Free Software is needed for Free Science’ to the file
‘free.txt’.

     filename = "free.txt";
     fid = fopen (filename, "w");
     fputs (fid, "Free Software is needed for Free Science");
     fclose (fid);

 -- : fputs (FID, STRING)
 -- : STATUS = fputs (FID, STRING)
     Write the string STRING to the file with file descriptor FID.

     The string is written to the file with no additional formatting.
     Use ‘fdisp’ instead to automatically append a newline character
     appropriate for the local machine.

     Return a non-negative number on success or EOF on error.

     See also: *note fdisp: XREFfdisp, *note fprintf: XREFfprintf, *note
     fwrite: XREFfwrite, *note fopen: XREFfopen.

   A function much similar to ‘fputs’ is available for writing data to
the screen.  The ‘puts’ function works just like ‘fputs’ except it
doesn’t take a file pointer as its input.

 -- : puts (STRING)
 -- : STATUS = puts (STRING)
     Write a string to the standard output with no formatting.

     The string is written verbatim to the standard output.  Use ‘disp’
     to automatically append a newline character appropriate for the
     local machine.

     Return a non-negative number on success and EOF on error.

     See also: *note fputs: XREFfputs, *note disp: XREFdisp.


File: octave.info,  Node: Line-Oriented Input,  Next: Formatted Output,  Prev: Simple Output,  Up: C-Style I/O Functions

14.2.3 Line-Oriented Input
--------------------------

To read from a file it must be opened for reading using ‘fopen’.  Then a
line can be read from the file using ‘fgetl’ as the following code
illustrates

     fid = fopen ("free.txt");
     txt = fgetl (fid)
          ⊣ Free Software is needed for Free Science
     fclose (fid);

This of course assumes that the file ‘free.txt’ exists and contains the
line ‘Free Software is needed for Free Science’.

 -- : STR = fgetl (FID)
 -- : STR = fgetl (FID, LEN)
     Read characters from a file, stopping after a newline, or EOF, or
     LEN characters have been read.

     The characters read, excluding the possible trailing newline, are
     returned as a string.

     If LEN is omitted, ‘fgetl’ reads until the next newline character.

     If there are no more characters to read, ‘fgetl’ returns −1.

     To read a line and return the terminating newline see ‘fgets’.

     See also: *note fgets: XREFfgets, *note fscanf: XREFfscanf, *note
     fread: XREFfread, *note fopen: XREFfopen.

 -- : STR = fgets (FID)
 -- : STR = fgets (FID, LEN)
     Read characters from a file, stopping after a newline, or EOF, or
     LEN characters have been read.

     The characters read, including the possible trailing newline, are
     returned as a string.

     If LEN is omitted, ‘fgets’ reads until the next newline character.

     If there are no more characters to read, ‘fgets’ returns −1.

     To read a line and discard the terminating newline see ‘fgetl’.

     See also: *note fputs: XREFfputs, *note fgetl: XREFfgetl, *note
     fscanf: XREFfscanf, *note fread: XREFfread, *note fopen: XREFfopen.

 -- : NLINES = fskipl (FID)
 -- : NLINES = fskipl (FID, COUNT)
 -- : NLINES = fskipl (FID, Inf)
     Read and skip COUNT lines from the file specified by the file
     descriptor FID.

     ‘fskipl’ discards characters until an end-of-line is encountered
     exactly COUNT-times, or until the end-of-file marker is found.

     If COUNT is omitted, it defaults to 1.  COUNT may also be ‘Inf’, in
     which case lines are skipped until the end of the file.  This form
     is suitable for counting the number of lines in a file.

     Returns the number of lines skipped (end-of-line sequences
     encountered).

     See also: *note fgetl: XREFfgetl, *note fgets: XREFfgets, *note
     fscanf: XREFfscanf, *note fopen: XREFfopen.


File: octave.info,  Node: Formatted Output,  Next: Output Conversion for Matrices,  Prev: Line-Oriented Input,  Up: C-Style I/O Functions

14.2.4 Formatted Output
-----------------------

This section describes how to call ‘printf’ and related functions.

   The following functions are available for formatted output.  They are
modeled after the C language functions of the same name, but they
interpret the format template differently in order to improve the
performance of printing vector and matrix values.

   Implementation Note: For compatibility with MATLAB, escape sequences
in the template string (e.g., "\n" => newline) are expanded even when
the template string is defined with single quotes.

 -- : printf (TEMPLATE, ...)
     Print optional arguments under the control of the template string
     TEMPLATE to the stream ‘stdout’ and return the number of characters
     printed.

     See the Formatted Output section of the GNU Octave manual for a
     complete description of the syntax of the template string.

     Implementation Note: For compatibility with MATLAB, escape
     sequences in the template string (e.g., "\n" => newline) are
     expanded even when the template string is defined with single
     quotes.

     See also: *note fprintf: XREFfprintf, *note sprintf: XREFsprintf,
     *note scanf: XREFscanf.

 -- : fprintf (FID, TEMPLATE, ...)
 -- : fprintf (TEMPLATE, ...)
 -- : NUMBYTES = fprintf (...)
     This function is equivalent to ‘printf’, except that the output is
     written to the file descriptor FID instead of ‘stdout’.

     If FID is omitted, the output is written to ‘stdout’ making the
     function exactly equivalent to ‘printf’.

     The optional output returns the number of bytes written to the
     file.

     Implementation Note: For compatibility with MATLAB, escape
     sequences in the template string (e.g., "\n" => newline) are
     expanded even when the template string is defined with single
     quotes.

     See also: *note fputs: XREFfputs, *note fdisp: XREFfdisp, *note
     fwrite: XREFfwrite, *note fscanf: XREFfscanf, *note printf:
     XREFprintf, *note sprintf: XREFsprintf, *note fopen: XREFfopen.

 -- : sprintf (TEMPLATE, ...)
     This is like ‘printf’, except that the output is returned as a
     string.

     Unlike the C library function, which requires you to provide a
     suitably sized string as an argument, Octave’s ‘sprintf’ function
     returns the string, automatically sized to hold all of the items
     converted.

     Implementation Note: For compatibility with MATLAB, escape
     sequences in the template string (e.g., "\n" => newline) are
     expanded even when the template string is defined with single
     quotes.

     See also: *note printf: XREFprintf, *note fprintf: XREFfprintf,
     *note sscanf: XREFsscanf.

   The ‘printf’ function can be used to print any number of arguments.
The template string argument you supply in a call provides information
not only about the number of additional arguments, but also about their
types and what style should be used for printing them.

   Ordinary characters in the template string are simply written to the
output stream as-is, while “conversion specifications” introduced by a
‘%’ character in the template cause subsequent arguments to be formatted
and written to the output stream.  For example,

     pct = 37;
     filename = "foo.txt";
     printf ("Processed %d%% of '%s'.\nPlease be patient.\n",
             pct, filename);

produces output like

     Processed 37% of 'foo.txt'.
     Please be patient.

   This example shows the use of the ‘%d’ conversion to specify that a
scalar argument should be printed in decimal notation, the ‘%s’
conversion to specify printing of a string argument, and the ‘%%’
conversion to print a literal ‘%’ character.

   There are also conversions for printing an integer argument as an
unsigned value in octal, decimal, or hexadecimal radix (‘%o’, ‘%u’, or
‘%x’, respectively); or as a character value (‘%c’).

   Floating-point numbers can be printed in normal, fixed-point notation
using the ‘%f’ conversion or in exponential notation using the ‘%e’
conversion.  The ‘%g’ conversion uses either ‘%e’ or ‘%f’ format,
depending on what is more appropriate for the magnitude of the
particular number.

   You can control formatting more precisely by writing “modifiers”
between the ‘%’ and the character that indicates which conversion to
apply.  These slightly alter the ordinary behavior of the conversion.
For example, most conversion specifications permit you to specify a
minimum field width and a flag indicating whether you want the result
left- or right-justified within the field.

   The specific flags and modifiers that are permitted and their
interpretation vary depending on the particular conversion.  They’re all
described in more detail in the following sections.


File: octave.info,  Node: Output Conversion for Matrices,  Next: Output Conversion Syntax,  Prev: Formatted Output,  Up: C-Style I/O Functions

14.2.5 Output Conversion for Matrices
-------------------------------------

When given a matrix value, Octave’s formatted output functions cycle
through the format template until all the values in the matrix have been
printed.  For example:

     printf ("%4.2f %10.2e %8.4g\n", hilb (3));

          ⊣ 1.00   5.00e-01   0.3333
          ⊣ 0.50   3.33e-01     0.25
          ⊣ 0.33   2.50e-01      0.2

   If more than one value is to be printed in a single call, the output
functions do not return to the beginning of the format template when
moving on from one value to the next.  This can lead to confusing output
if the number of elements in the matrices are not exact multiples of the
number of conversions in the format template.  For example:

     printf ("%4.2f %10.2e %8.4g\n", [1, 2], [3, 4]);

          ⊣ 1.00   2.00e+00        3
          ⊣ 4.00

   If this is not what you want, use a series of calls instead of just
one.


File: octave.info,  Node: Output Conversion Syntax,  Next: Table of Output Conversions,  Prev: Output Conversion for Matrices,  Up: C-Style I/O Functions

14.2.6 Output Conversion Syntax
-------------------------------

This section provides details about the precise syntax of conversion
specifications that can appear in a ‘printf’ template string.

   Characters in the template string that are not part of a conversion
specification are printed as-is to the output stream.

   The conversion specifications in a ‘printf’ template string have the
general form:

     % FLAGS WIDTH [ . PRECISION ] TYPE CONVERSION

   For example, in the conversion specifier ‘%-10.8ld’, the ‘-’ is a
flag, ‘10’ specifies the field width, the precision is ‘8’, the letter
‘l’ is a type modifier, and ‘d’ specifies the conversion style.  (This
particular type specifier says to print a numeric argument in decimal
notation, with a minimum of 8 digits left-justified in a field at least
10 characters wide.)

   In more detail, output conversion specifications consist of an
initial ‘%’ character followed in sequence by:

   • Zero or more “flag characters” that modify the normal behavior of
     the conversion specification.

   • An optional decimal integer specifying the “minimum field width”.
     If the normal conversion produces fewer characters than this, the
     field is padded with spaces to the specified width.  This is a
     _minimum_ value; if the normal conversion produces more characters
     than this, the field is _not_ truncated.  Normally, the output is
     right-justified within the field.

     You can also specify a field width of ‘*’.  This means that the
     next argument in the argument list (before the actual value to be
     printed) is used as the field width.  The value is rounded to the
     nearest integer.  If the value is negative, this means to set the
     ‘-’ flag (see below) and to use the absolute value as the field
     width.

   • An optional “precision” to specify the number of digits to be
     written for the numeric conversions.  If the precision is
     specified, it consists of a period (‘.’) followed optionally by a
     decimal integer (which defaults to zero if omitted).

     You can also specify a precision of ‘*’.  This means that the next
     argument in the argument list (before the actual value to be
     printed) is used as the precision.  The value must be an integer,
     and is ignored if it is negative.

   • An optional “type modifier character”.  This character is ignored
     by Octave’s ‘printf’ function, but is recognized to provide
     compatibility with the C language ‘printf’.

   • A character that specifies the conversion to be applied.

   The exact options that are permitted and how they are interpreted
vary between the different conversion specifiers.  See the descriptions
of the individual conversions for information about the particular
options that they use.


File: octave.info,  Node: Table of Output Conversions,  Next: Integer Conversions,  Prev: Output Conversion Syntax,  Up: C-Style I/O Functions

14.2.7 Table of Output Conversions
----------------------------------

Here is a table summarizing what all the different conversions do:

‘%d’, ‘%i’
     Print an integer as a signed decimal number.  *Note Integer
     Conversions::, for details.  ‘%d’ and ‘%i’ are synonymous for
     output, but are different when used with ‘scanf’ for input (*note
     Table of Input Conversions::).

‘%o’
     Print an integer as an unsigned octal number.  *Note Integer
     Conversions::, for details.

‘%u’
     Print an integer as an unsigned decimal number.  *Note Integer
     Conversions::, for details.

‘%x’, ‘%X’
     Print an integer as an unsigned hexadecimal number.  ‘%x’ uses
     lowercase letters and ‘%X’ uses uppercase.  *Note Integer
     Conversions::, for details.

‘%f’
     Print a floating-point number in normal (fixed-point) notation.
     *Note Floating-Point Conversions::, for details.

‘%e’, ‘%E’
     Print a floating-point number in exponential notation.  ‘%e’ uses
     lowercase letters and ‘%E’ uses uppercase.  *Note Floating-Point
     Conversions::, for details.

‘%g’, ‘%G’
     Print a floating-point number in either normal (fixed-point) or
     exponential notation, whichever is more appropriate for its
     magnitude.  ‘%g’ uses lowercase letters and ‘%G’ uses uppercase.
     *Note Floating-Point Conversions::, for details.

‘%c’
     Print a single character.  *Note Other Output Conversions::.

‘%s’
     Print a string.  *Note Other Output Conversions::.

‘%%’
     Print a literal ‘%’ character.  *Note Other Output Conversions::.

   If the syntax of a conversion specification is invalid, unpredictable
things will happen, so don’t do this.  In particular, MATLAB allows a
bare percentage sign ‘%’ with no subsequent conversion character.
Octave will emit an error and stop if it sees such code.  When the
string variable to be processed cannot be guaranteed to be free of
potential format codes it is better to use the two argument form of any
of the ‘printf’ functions and set the format string to ‘%s’.
Alternatively, for code which is not required to be backwards-compatible
with MATLAB the Octave function ‘puts’ or ‘disp’ can be used.

     printf (strvar);        # Unsafe if strvar contains format codes
     printf ("%s", strvar);  # Safe
     puts (strvar);          # Safe

   If there aren’t enough function arguments provided to supply values
for all the conversion specifications in the template string, or if the
arguments are not of the correct types, the results are unpredictable.
If you supply more arguments than conversion specifications, the extra
argument values are simply ignored; this is sometimes useful.


File: octave.info,  Node: Integer Conversions,  Next: Floating-Point Conversions,  Prev: Table of Output Conversions,  Up: C-Style I/O Functions

14.2.8 Integer Conversions
--------------------------

This section describes the options for the ‘%d’, ‘%i’, ‘%o’, ‘%u’, ‘%x’,
and ‘%X’ conversion specifications.  These conversions print integers in
various formats.

   The ‘%d’ and ‘%i’ conversion specifications both print an numeric
argument as a signed decimal number; while ‘%o’, ‘%u’, and ‘%x’ print
the argument as an unsigned octal, decimal, or hexadecimal number
(respectively).  The ‘%X’ conversion specification is just like ‘%x’
except that it uses the characters ‘ABCDEF’ as digits instead of
‘abcdef’.

   The following flags are meaningful:

‘-’
     Left-justify the result in the field (instead of the normal
     right-justification).

‘+’
     For the signed ‘%d’ and ‘%i’ conversions, print a plus sign if the
     value is positive.

‘ ’
     For the signed ‘%d’ and ‘%i’ conversions, if the result doesn’t
     start with a plus or minus sign, prefix it with a space character
     instead.  Since the ‘+’ flag ensures that the result includes a
     sign, this flag is ignored if you supply both of them.

‘#’
     For the ‘%o’ conversion, this forces the leading digit to be ‘0’,
     as if by increasing the precision.  For ‘%x’ or ‘%X’, this prefixes
     a leading ‘0x’ or ‘0X’ (respectively) to the result.  This doesn’t
     do anything useful for the ‘%d’, ‘%i’, or ‘%u’ conversions.

‘0’
     Pad the field with zeros instead of spaces.  The zeros are placed
     after any indication of sign or base.  This flag is ignored if the
     ‘-’ flag is also specified, or if a precision is specified.

   If a precision is supplied, it specifies the minimum number of digits
to appear; leading zeros are produced if necessary.  If you don’t
specify a precision, the number is printed with as many digits as it
needs.  If you convert a value of zero with an explicit precision of
zero, then no characters at all are produced.


File: octave.info,  Node: Floating-Point Conversions,  Next: Other Output Conversions,  Prev: Integer Conversions,  Up: C-Style I/O Functions

14.2.9 Floating-Point Conversions
---------------------------------

This section discusses the conversion specifications for floating-point
numbers: the ‘%f’, ‘%e’, ‘%E’, ‘%g’, and ‘%G’ conversions.

   The ‘%f’ conversion prints its argument in fixed-point notation,
producing output of the form [‘-’]DDD‘.’DDD, where the number of digits
following the decimal point is controlled by the precision you specify.

   The ‘%e’ conversion prints its argument in exponential notation,
producing output of the form [‘-’]D‘.’DDD‘e’[‘+’|‘-’]DD.  Again, the
number of digits following the decimal point is controlled by the
precision.  The exponent always contains at least two digits.  The ‘%E’
conversion is similar but the exponent is marked with the letter ‘E’
instead of ‘e’.

   The ‘%g’ and ‘%G’ conversions print the argument in the style of ‘%e’
or ‘%E’ (respectively) if the exponent would be less than -4 or greater
than or equal to the precision; otherwise they use the ‘%f’ style.
Trailing zeros are removed from the fractional portion of the result and
a decimal-point character appears only if it is followed by a digit.

   The following flags can be used to modify the behavior:

‘-’
     Left-justify the result in the field.  Normally the result is
     right-justified.

‘+’
     Always include a plus or minus sign in the result.

‘ ’
     If the result doesn’t start with a plus or minus sign, prefix it
     with a space instead.  Since the ‘+’ flag ensures that the result
     includes a sign, this flag is ignored if you supply both of them.

‘#’
     Specifies that the result should always include a decimal point,
     even if no digits follow it.  For the ‘%g’ and ‘%G’ conversions,
     this also forces trailing zeros after the decimal point to be left
     in place where they would otherwise be removed.

‘0’
     Pad the field with zeros instead of spaces; the zeros are placed
     after any sign.  This flag is ignored if the ‘-’ flag is also
     specified.

   The precision specifies how many digits follow the decimal-point
character for the ‘%f’, ‘%e’, and ‘%E’ conversions.  For these
conversions, the default precision is ‘6’.  If the precision is
explicitly ‘0’, this suppresses the decimal point character entirely.
For the ‘%g’ and ‘%G’ conversions, the precision specifies how many
significant digits to print.  Significant digits are the first digit
before the decimal point, and all the digits after it.  If the precision
is ‘0’ or not specified for ‘%g’ or ‘%G’, it is treated like a value of
‘1’.  If the value being printed cannot be expressed precisely in the
specified number of digits, the value is rounded to the nearest number
that fits.


File: octave.info,  Node: Other Output Conversions,  Next: Formatted Input,  Prev: Floating-Point Conversions,  Up: C-Style I/O Functions

14.2.10 Other Output Conversions
--------------------------------

This section describes miscellaneous conversions for ‘printf’.

   The ‘%c’ conversion prints a single character.  The ‘-’ flag can be
used to specify left-justification in the field, but no other flags are
defined, and no precision or type modifier can be given.  For example:

     printf ("%c%c%c%c%c", "h", "e", "l", "l", "o");

prints ‘hello’.

   The ‘%s’ conversion prints a string.  The corresponding argument must
be a string.  A precision can be specified to indicate the maximum
number of characters to write; otherwise characters in the string up to
but not including the terminating null character are written to the
output stream.  The ‘-’ flag can be used to specify left-justification
in the field, but no other flags or type modifiers are defined for this
conversion.  For example:

     printf ("%3s%-6s", "no", "where");

prints ‘ nowhere ’ (note the leading and trailing spaces).


File: octave.info,  Node: Formatted Input,  Next: Input Conversion Syntax,  Prev: Other Output Conversions,  Up: C-Style I/O Functions

14.2.11 Formatted Input
-----------------------

Octave provides the ‘scanf’, ‘fscanf’, and ‘sscanf’ functions to read
formatted input.  There are two forms of each of these functions.  One
can be used to extract vectors of data from a file, and the other is
more ‘C-like’.

 -- : [VAL, COUNT, ERRMSG] = fscanf (FID, TEMPLATE, SIZE)
 -- : [V1, V2, ..., COUNT, ERRMSG] = fscanf (FID, TEMPLATE, "C")
     In the first form, read from FID according to TEMPLATE, returning
     the result in the matrix VAL.

     The optional argument SIZE specifies the amount of data to read and
     may be one of

     ‘Inf’
          Read as much as possible, returning a column vector.

     ‘NR’
          Read up to NR elements, returning a column vector.

     ‘[NR, Inf]’
          Read as much as possible, returning a matrix with NR rows.  If
          the number of elements read is not an exact multiple of NR,
          the last column is padded with zeros.

     ‘[NR, NC]’
          Read up to ‘NR * NC’ elements, returning a matrix with NR
          rows.  If the number of elements read is not an exact multiple
          of NR, the last column is padded with zeros.

     If SIZE is omitted, a value of ‘Inf’ is assumed.

     A string is returned if TEMPLATE specifies only character
     conversions.

     The number of items successfully read is returned in COUNT.

     If an error occurs, ERRMSG contains a system-dependent error
     message.

     In the second form, read from FID according to TEMPLATE, with each
     conversion specifier in TEMPLATE corresponding to a single scalar
     return value.  This form is more “C-like”, and also compatible with
     previous versions of Octave.  The number of successful conversions
     is returned in COUNT

     See the Formatted Input section of the GNU Octave manual for a
     complete description of the syntax of the template string.

     See also: *note fgets: XREFfgets, *note fgetl: XREFfgetl, *note
     fread: XREFfread, *note scanf: XREFscanf, *note sscanf: XREFsscanf,
     *note fopen: XREFfopen.

 -- : [VAL, COUNT, ERRMSG] = scanf (TEMPLATE, SIZE)
 -- : [V1, V2, ..., COUNT, ERRMSG] = scanf (TEMPLATE, "C")
     This is equivalent to calling ‘fscanf’ with FID = ‘stdin’.

     It is currently not useful to call ‘scanf’ in interactive programs.

     See also: *note fscanf: XREFfscanf, *note sscanf: XREFsscanf, *note
     printf: XREFprintf.

 -- : [VAL, COUNT, ERRMSG, POS] = sscanf (STRING, TEMPLATE, SIZE)
 -- : [V1, V2, ..., COUNT, ERRMSG] = sscanf (STRING, TEMPLATE, "C")
     This is like ‘fscanf’, except that the characters are taken from
     the string STRING instead of from a stream.

     Reaching the end of the string is treated as an end-of-file
     condition.  In addition to the values returned by ‘fscanf’, the
     index of the next character to be read is returned in POS.

     See also: *note fscanf: XREFfscanf, *note scanf: XREFscanf, *note
     sprintf: XREFsprintf.

   Calls to ‘scanf’ are superficially similar to calls to ‘printf’ in
that arbitrary arguments are read under the control of a template
string.  While the syntax of the conversion specifications in the
template is very similar to that for ‘printf’, the interpretation of the
template is oriented more towards free-format input and simple pattern
matching, rather than fixed-field formatting.  For example, most ‘scanf’
conversions skip over any amount of “white space” (including spaces,
tabs, and newlines) in the input file, and there is no concept of
precision for the numeric input conversions as there is for the
corresponding output conversions.  Ordinarily, non-whitespace characters
in the template are expected to match characters in the input stream
exactly.

   When a “matching failure” occurs, ‘scanf’ returns immediately,
leaving the first non-matching character as the next character to be
read from the stream, and ‘scanf’ returns all the items that were
successfully converted.

   The formatted input functions are not used as frequently as the
formatted output functions.  Partly, this is because it takes some care
to use them properly.  Another reason is that it is difficult to recover
from a matching error.


File: octave.info,  Node: Input Conversion Syntax,  Next: Table of Input Conversions,  Prev: Formatted Input,  Up: C-Style I/O Functions

14.2.12 Input Conversion Syntax
-------------------------------

A ‘scanf’ template string is a string that contains ordinary multibyte
characters interspersed with conversion specifications that start with
‘%’.

   Any whitespace character in the template causes any number of
whitespace characters in the input stream to be read and discarded.  The
whitespace characters that are matched need not be exactly the same
whitespace characters that appear in the template string.  For example,
write ‘ , ’ in the template to recognize a comma with optional
whitespace before and after.

   Other characters in the template string that are not part of
conversion specifications must match characters in the input stream
exactly; if this is not the case, a matching failure occurs.

   The conversion specifications in a ‘scanf’ template string have the
general form:

     % FLAGS WIDTH TYPE CONVERSION

   In more detail, an input conversion specification consists of an
initial ‘%’ character followed in sequence by:

   • An optional “flag character” ‘*’, which says to ignore the text
     read for this specification.  When ‘scanf’ finds a conversion
     specification that uses this flag, it reads input as directed by
     the rest of the conversion specification, but it discards this
     input, does not return any value, and does not increment the count
     of successful assignments.

   • An optional decimal integer that specifies the “maximum field
     width”.  Reading of characters from the input stream stops either
     when this maximum is reached or when a non-matching character is
     found, whichever happens first.  Most conversions discard initial
     whitespace characters, and these discarded characters don’t count
     towards the maximum field width.  Conversions that do not discard
     initial whitespace are explicitly documented.

   • An optional type modifier character.  This character is ignored by
     Octave’s ‘scanf’ function, but is recognized to provide
     compatibility with the C language ‘scanf’.

   • A character that specifies the conversion to be applied.

   The exact options that are permitted and how they are interpreted
vary between the different conversion specifiers.  See the descriptions
of the individual conversions for information about the particular
options that they allow.


File: octave.info,  Node: Table of Input Conversions,  Next: Numeric Input Conversions,  Prev: Input Conversion Syntax,  Up: C-Style I/O Functions

14.2.13 Table of Input Conversions
----------------------------------

Here is a table that summarizes the various conversion specifications:

‘%d’
     Matches an optionally signed integer written in decimal.  *Note
     Numeric Input Conversions::.

‘%i’
     Matches an optionally signed integer in any of the formats that the
     C language defines for specifying an integer constant.  *Note
     Numeric Input Conversions::.

‘%o’
     Matches an unsigned integer written in octal radix.  *Note Numeric
     Input Conversions::.

‘%u’
     Matches an unsigned integer written in decimal radix.  *Note
     Numeric Input Conversions::.

‘%x’, ‘%X’
     Matches an unsigned integer written in hexadecimal radix.  *Note
     Numeric Input Conversions::.

‘%e’, ‘%f’, ‘%g’, ‘%E’, ‘%G’
     Matches an optionally signed floating-point number.  *Note Numeric
     Input Conversions::.

‘%s’
     Matches a string containing only non-whitespace characters.  *Note
     String Input Conversions::.

‘%c’
     Matches a string of one or more characters; the number of
     characters read is controlled by the maximum field width given for
     the conversion.  *Note String Input Conversions::.

‘%%’
     This matches a literal ‘%’ character in the input stream.  No
     corresponding argument is used.

   If the syntax of a conversion specification is invalid, the behavior
is undefined.  If there aren’t enough function arguments provided to
supply addresses for all the conversion specifications in the template
strings that perform assignments, or if the arguments are not of the
correct types, the behavior is also undefined.  On the other hand, extra
arguments are simply ignored.


File: octave.info,  Node: Numeric Input Conversions,  Next: String Input Conversions,  Prev: Table of Input Conversions,  Up: C-Style I/O Functions

14.2.14 Numeric Input Conversions
---------------------------------

This section describes the ‘scanf’ conversions for reading numeric
values.

   The ‘%d’ conversion matches an optionally signed integer in decimal
radix.

   The ‘%i’ conversion matches an optionally signed integer in any of
the formats that the C language defines for specifying an integer
constant.

   For example, any of the strings ‘10’, ‘0xa’, or ‘012’ could be read
in as integers under the ‘%i’ conversion.  Each of these specifies a
number with decimal value ‘10’.

   The ‘%o’, ‘%u’, and ‘%x’ conversions match unsigned integers in
octal, decimal, and hexadecimal radices, respectively.

   The ‘%X’ conversion is identical to the ‘%x’ conversion.  They both
permit either uppercase or lowercase letters to be used as digits.

   By default, integers are read as 32-bit quantities.  With the ‘h’
modifier, 16-bit integers are used, and with the ‘l’ modifier, 64-bit
integers are used.


File: octave.info,  Node: String Input Conversions,  Next: Binary I/O,  Prev: Numeric Input Conversions,  Up: C-Style I/O Functions

14.2.15 String Input Conversions
--------------------------------

This section describes the ‘scanf’ input conversions for reading string
and character values: ‘%s’ and ‘%c’.

   The ‘%c’ conversion is the simplest: it matches a fixed number of
characters, always.  The maximum field with says how many characters to
read; if you don’t specify the maximum, the default is 1.  This
conversion does not skip over initial whitespace characters.  It reads
precisely the next N characters, and fails if it cannot get that many.

   The ‘%s’ conversion matches a string of non-whitespace characters.
It skips and discards initial whitespace, but stops when it encounters
more whitespace after having read something.

   For example, reading the input:

      hello, world

with the conversion ‘%10c’ produces " hello, wo", but reading the same
input with the conversion ‘%10s’ produces "hello,".


File: octave.info,  Node: Binary I/O,  Next: Temporary Files,  Prev: String Input Conversions,  Up: C-Style I/O Functions

14.2.16 Binary I/O
------------------

Octave can read and write binary data using the functions ‘fread’ and
‘fwrite’, which are patterned after the standard C functions with the
same names.  They are able to automatically swap the byte order of
integer data and convert among the supported floating point formats as
the data are read.

 -- : VAL = fread (FID)
 -- : VAL = fread (FID, SIZE)
 -- : VAL = fread (FID, SIZE, PRECISION)
 -- : VAL = fread (FID, SIZE, PRECISION, SKIP)
 -- : VAL = fread (FID, SIZE, PRECISION, SKIP, ARCH)
 -- : [VAL, COUNT] = fread (...)
     Read binary data from the file specified by the file descriptor
     FID.

     The optional argument SIZE specifies the amount of data to read and
     may be one of

     ‘Inf’
          Read as much as possible, returning a column vector.

     ‘NR’
          Read up to NR elements, returning a column vector.

     ‘[NR, Inf]’
          Read as much as possible, returning a matrix with NR rows.  If
          the number of elements read is not an exact multiple of NR,
          the last column is padded with zeros.

     ‘[NR, NC]’
          Read up to ‘NR * NC’ elements, returning a matrix with NR
          rows.  If the number of elements read is not an exact multiple
          of NR, the last column is padded with zeros.

     If SIZE is omitted, a value of ‘Inf’ is assumed.

     The optional argument PRECISION is a string specifying the type of
     data to read and may be one of

     "uint8" (default)
          8-bit unsigned integer.

     "int8"
     "integer*1"
          8-bit signed integer.

     "uint16"
     "ushort"
     "unsigned short"
          16-bit unsigned integer.

     "int16"
     "integer*2"
     "short"
          16-bit signed integer.

     "uint"
     "uint32"
     "unsigned int"
     "ulong"
     "unsigned long"
          32-bit unsigned integer.

     "int"
     "int32"
     "integer*4"
     "long"
          32-bit signed integer.

     "uint64"
          64-bit unsigned integer.

     "int64"
     "integer*8"
          64-bit signed integer.

     "single"
     "float"
     "float32"
     "real*4"
          32-bit floating point number.

     "double"
     "float64"
     "real*8"
          64-bit floating point number.

     "char"
     "char*1"
          8-bit single character.

     "uchar"
     "unsigned char"
          8-bit unsigned character.

     "schar"
     "signed char"
          8-bit signed character.

     The default precision is "uint8".

     The PRECISION argument may also specify an optional repeat count.
     For example, ‘32*single’ causes ‘fread’ to read a block of 32
     single precision floating point numbers.  Reading in blocks is
     useful in combination with the SKIP argument.

     The PRECISION argument may also specify a type conversion.  For
     example, ‘int16=>int32’ causes ‘fread’ to read 16-bit integer
     values and return an array of 32-bit integer values.  By default,
     ‘fread’ returns a double precision array.  The special form ‘*TYPE’
     is shorthand for ‘TYPE=>TYPE’.

     The conversion and repeat counts may be combined.  For example, the
     specification ‘32*single=>single’ causes ‘fread’ to read blocks of
     single precision floating point values and return an array of
     single precision values instead of the default array of double
     precision values.

     The optional argument SKIP specifies the number of bytes to skip
     after each element (or block of elements) is read.  If it is not
     specified, a value of 0 is assumed.  If the final block read is not
     complete, the final skip is omitted.  For example,

          fread (f, 10, "3*single=>single", 8)

     will omit the final 8-byte skip because the last read will not be a
     complete block of 3 values.

     The optional argument ARCH is a string specifying the data format
     for the file.  Valid values are

     "native" or "n"
          The format of the current machine.

     "ieee-be" or "b"
          IEEE big endian.

     "ieee-le" or "l"
          IEEE little endian.

     If no ARCH is given the value used in the call to ‘fopen’ which
     created the file descriptor is used.  Otherwise, the value
     specified with ‘fread’ overrides that of ‘fopen’ and determines the
     data format.

     The output argument VAL contains the data read from the file.

     The optional return value COUNT contains the number of elements
     read.

     See also: *note fwrite: XREFfwrite, *note fgets: XREFfgets, *note
     fgetl: XREFfgetl, *note fscanf: XREFfscanf, *note fopen: XREFfopen.

 -- : fwrite (FID, DATA)
 -- : fwrite (FID, DATA, PRECISION)
 -- : fwrite (FID, DATA, PRECISION, SKIP)
 -- : fwrite (FID, DATA, PRECISION, SKIP, ARCH)
 -- : COUNT = fwrite (...)
     Write data in binary form to the file specified by the file
     descriptor FID, returning the number of values COUNT successfully
     written to the file.

     The argument DATA is a matrix of values that are to be written to
     the file.  The values are extracted in column-major order.

     The remaining arguments PRECISION, SKIP, and ARCH are optional, and
     are interpreted as described for ‘fread’.

     The behavior of ‘fwrite’ is undefined if the values in DATA are too
     large to fit in the specified precision.

     See also: *note fread: XREFfread, *note fputs: XREFfputs, *note
     fprintf: XREFfprintf, *note fopen: XREFfopen.


File: octave.info,  Node: Temporary Files,  Next: EOF and Errors,  Prev: Binary I/O,  Up: C-Style I/O Functions

14.2.17 Temporary Files
-----------------------

Sometimes one needs to write data to a file that is only temporary.
This is most commonly used when an external program launched from within
Octave needs to access data.  When Octave exits all temporary files will
be deleted, so this step need not be executed manually.

 -- : [FID, NAME, MSG] = mkstemp ("TEMPLATE")
 -- : [FID, NAME, MSG] = mkstemp ("TEMPLATE", DELETE)
     Return the file descriptor FID corresponding to a new temporary
     file with a unique name created from TEMPLATE.

     The last six characters of TEMPLATE must be "XXXXXX" and these are
     replaced with a string that makes the filename unique.  The file is
     then created with mode read/write and permissions that are system
     dependent (on GNU/Linux systems, the permissions will be 0600 for
     versions of glibc 2.0.7 and later).  The file is opened in binary
     mode and with the ‘O_EXCL’ flag.

     If the optional argument DELETE is supplied and is true, the file
     will be deleted automatically when Octave exits.

     If successful, FID is a valid file ID, NAME is the name of the
     file, and MSG is an empty string.  Otherwise, FID is -1, NAME is
     empty, and MSG contains a system-dependent error message.

     See also: *note tempname: XREFtempname, *note tempdir: XREFtempdir,
     *note P_tmpdir: XREFP_tmpdir, *note tmpfile: XREFtmpfile, *note
     fopen: XREFfopen.

 -- : [FID, MSG] = tmpfile ()
     Return the file ID corresponding to a new temporary file with a
     unique name.

     The file is opened in binary read/write ("w+b") mode and will be
     deleted automatically when it is closed or when Octave exits.

     If successful, FID is a valid file ID and MSG is an empty string.
     Otherwise, FID is -1 and MSG contains a system-dependent error
     message.

     See also: *note tempname: XREFtempname, *note mkstemp: XREFmkstemp,
     *note tempdir: XREFtempdir, *note P_tmpdir: XREFP_tmpdir.

 -- : FNAME = tempname ()
 -- : FNAME = tempname (DIR)
 -- : FNAME = tempname (DIR, PREFIX)
     Return a unique temporary filename as a string.

     If PREFIX is omitted, a value of "oct-" is used.

     If DIR is also omitted, the default directory for temporary files
     (‘P_tmpdir’) is used.  If DIR is provided, it must exist, otherwise
     the default directory for temporary files is used.

     Programming Note: Because the named file is not opened by
     ‘tempname’, it is possible, though relatively unlikely, that it
     will not be available by the time your program attempts to open it.
     If this is a concern, see ‘tmpfile’.

     See also: *note mkstemp: XREFmkstemp, *note tempdir: XREFtempdir,
     *note P_tmpdir: XREFP_tmpdir, *note tmpfile: XREFtmpfile.

 -- : DIR = tempdir ()
     Return the name of the host system’s directory for temporary files.

     The directory name is taken first from the environment variable
     ‘TMPDIR’.  If that does not exist the system default returned by
     ‘P_tmpdir’ is used.

     See also: *note P_tmpdir: XREFP_tmpdir, *note tempname:
     XREFtempname, *note mkstemp: XREFmkstemp, *note tmpfile:
     XREFtmpfile.

 -- : P_tmpdir ()
     Return the name of the host system’s *default* directory for
     temporary files.

     Programming Note: The value returned by ‘P_tmpdir’ is always the
     default location.  This value may not agree with that returned from
     ‘tempdir’ if the user has overridden the default with the ‘TMPDIR’
     environment variable.

     See also: *note tempdir: XREFtempdir, *note tempname: XREFtempname,
     *note mkstemp: XREFmkstemp, *note tmpfile: XREFtmpfile.


File: octave.info,  Node: EOF and Errors,  Next: File Positioning,  Prev: Temporary Files,  Up: C-Style I/O Functions

14.2.18 End of File and Errors
------------------------------

Once a file has been opened its status can be acquired.  As an example
the ‘feof’ functions determines if the end of the file has been reached.
This can be very useful when reading small parts of a file at a time.
The following example shows how to read one line at a time from a file
until the end has been reached.

     filename = "myfile.txt";
     fid = fopen (filename, "r");
     while (! feof (fid) )
       text_line = fgetl (fid);
     endwhile
     fclose (fid);

Note that in some situations it is more efficient to read the entire
contents of a file and then process it, than it is to read it line by
line.  This has the potential advantage of removing the loop in the
above code.

 -- : STATUS = feof (FID)
     Return 1 if an end-of-file condition has been encountered for the
     file specified by file descriptor FID and 0 otherwise.

     Note that ‘feof’ will only return 1 if the end of the file has
     already been encountered, not if the next read operation will
     result in an end-of-file condition.

     See also: *note fread: XREFfread, *note frewind: XREFfrewind, *note
     fseek: XREFfseek, *note fclear: XREFfclear, *note fopen: XREFfopen.

 -- : MSG = ferror (FID)
 -- : [MSG, ERR] = ferror (FID)
 -- : [...] = ferror (FID, "clear")
     Query the error status of the stream specified by file descriptor
     FID.

     If an error condition exists then return a string MSG describing
     the error.  Otherwise, return an empty string "".

     The second input "clear" is optional.  If supplied, the error state
     on the stream will be cleared.

     The optional second output is a numeric indication of the error
     status.  ERR is 1 if an error condition has been encountered and 0
     otherwise.

     Note that ‘ferror’ indicates if an error has already occurred, not
     whether the next operation will result in an error condition.

     See also: *note fclear: XREFfclear, *note fopen: XREFfopen.

 -- : fclear (FID)
     Clear the stream state for the file specified by the file
     descriptor FID.

     See also: *note ferror: XREFferror, *note fopen: XREFfopen.

 -- : freport ()
     Print a list of which files have been opened, and whether they are
     open for reading, writing, or both.

     For example:

          freport ()

               ⊣  number  mode  arch       name
               ⊣  ------  ----  ----       ----
               ⊣     0     r    ieee-le    stdin
               ⊣     1     w    ieee-le    stdout
               ⊣     2     w    ieee-le    stderr
               ⊣     3     r    ieee-le    myfile

     See also: *note fopen: XREFfopen, *note fclose: XREFfclose, *note
     is_valid_file_id: XREFis_valid_file_id.


File: octave.info,  Node: File Positioning,  Prev: EOF and Errors,  Up: C-Style I/O Functions

14.2.19 File Positioning
------------------------

Three functions are available for setting and determining the position
of the file pointer for a given file.

 -- : POS = ftell (FID)
     Return the position of the file pointer as the number of characters
     from the beginning of the file specified by file descriptor FID.

     See also: *note fseek: XREFfseek, *note frewind: XREFfrewind, *note
     feof: XREFfeof, *note fopen: XREFfopen.

 -- : fseek (FID, OFFSET)
 -- : fseek (FID, OFFSET, ORIGIN)
 -- : STATUS = fseek (...)
     Set the file pointer to the location OFFSET within the file FID.

     The pointer is positioned OFFSET characters from the ORIGIN, which
     may be one of the predefined variables SEEK_SET (beginning),
     SEEK_CUR (current position), or SEEK_END (end of file) or strings
     "bof", "cof", or "eof".  If ORIGIN is omitted, SEEK_SET is assumed.
     OFFSET may be positive, negative, or zero but not all combinations
     of ORIGIN and OFFSET can be realized.

     ‘fseek’ returns 0 on success and -1 on error.

     See also: *note fskipl: XREFfskipl, *note frewind: XREFfrewind,
     *note ftell: XREFftell, *note fopen: XREFfopen, *note SEEK_SET:
     XREFSEEK_SET, *note SEEK_CUR: XREFSEEK_CUR, *note SEEK_END:
     XREFSEEK_END.

 -- : SEEK_SET ()
     Return the numerical value to pass to ‘fseek’ to position the file
     pointer relative to the beginning of the file.

     See also: *note SEEK_CUR: XREFSEEK_CUR, *note SEEK_END:
     XREFSEEK_END, *note fseek: XREFfseek.

 -- : SEEK_CUR ()
     Return the numerical value to pass to ‘fseek’ to position the file
     pointer relative to the current position.

     See also: *note SEEK_SET: XREFSEEK_SET, *note SEEK_END:
     XREFSEEK_END, *note fseek: XREFfseek.

 -- : SEEK_END ()
     Return the numerical value to pass to ‘fseek’ to position the file
     pointer relative to the end of the file.

     See also: *note SEEK_SET: XREFSEEK_SET, *note SEEK_CUR:
     XREFSEEK_CUR, *note fseek: XREFfseek.

 -- : frewind (FID)
 -- : STATUS = frewind (FID)
     Move the file pointer to the beginning of the file specified by
     file descriptor FID.

     ‘frewind’ returns 0 for success, and -1 if an error is encountered.
     It is equivalent to ‘fseek (FID, 0, SEEK_SET)’.

     See also: *note fseek: XREFfseek, *note ftell: XREFftell, *note
     fopen: XREFfopen.

   The following example stores the current file position in the
variable ‘marker’, moves the pointer to the beginning of the file, reads
four characters, and then returns to the original position.

     marker = ftell (myfile);
     frewind (myfile);
     fourch = fgets (myfile, 4);
     fseek (myfile, marker, SEEK_SET);


File: octave.info,  Node: Plotting,  Next: Matrix Manipulation,  Prev: Input and Output,  Up: Top

15 Plotting
***********

* Menu:

* Introduction to Plotting::
* High-Level Plotting::
* Graphics Data Structures::
* Advanced Plotting::


File: octave.info,  Node: Introduction to Plotting,  Next: High-Level Plotting,  Up: Plotting

15.1 Introduction to Plotting
=============================

Earlier versions of Octave provided plotting through the use of gnuplot.
This capability is still available.  But, a newer plotting capability is
provided by access to OpenGL.  Which plotting system is used is
controlled by the ‘graphics_toolkit’ function.  *Note Graphics
Toolkits::.

   The function call ‘graphics_toolkit ("qt")’ selects the Qt/OpenGL
system, ‘graphics_toolkit ("fltk")’ selects the FLTK/OpenGL system, and
‘graphics_toolkit ("gnuplot")’ selects the gnuplot system.  The three
systems may be used selectively through the use of the
‘graphics_toolkit’ property of the graphics handle for each figure.
This is explained in *note Graphics Data Structures::.  *Caution:* The
OpenGL-based toolkits use single precision variables internally which
limits the maximum value that can be displayed to approximately 10^{38}.
If your data contains larger values you must use the gnuplot toolkit
which supports values up to 10^{308}.


File: octave.info,  Node: High-Level Plotting,  Next: Graphics Data Structures,  Prev: Introduction to Plotting,  Up: Plotting

15.2 High-Level Plotting
========================

Octave provides simple means to create many different types of two- and
three-dimensional plots using high-level functions.

   If you need more detailed control, see *note Graphics Data
Structures:: and *note Advanced Plotting::.

* Menu:

* Two-Dimensional Plots::
* Three-Dimensional Plots::
* Plot Annotations::
* Multiple Plots on One Page::
* Multiple Plot Windows::
* Manipulation of Plot Objects::
* Manipulation of Plot Windows::
* Use of the interpreter Property::
* Printing and Saving Plots::
* Interacting with Plots::
* Test Plotting Functions::


File: octave.info,  Node: Two-Dimensional Plots,  Next: Three-Dimensional Plots,  Up: High-Level Plotting

15.2.1 Two-Dimensional Plots
----------------------------

* Menu:

* Axis Configuration::
* Two-dimensional Function Plotting::
* Two-dimensional Geometric Shapes::

The ‘plot’ function allows you to create simple x-y plots with linear
axes.  For example,

     x = -10:0.1:10;
     plot (x, sin (x));
     xlabel ("x");
     ylabel ("sin (x)");
     title ("Simple 2-D Plot");

displays a sine wave shown in *note Figure 15.1: fig:plot.  On most
systems, this command will open a separate plot window to display the
graph.

                 
                 +---------------------------------+
                 | Image unavailable in text mode. |
                 +---------------------------------+

Figure 15.1: Simple Two-Dimensional Plot.

 -- : plot (Y)
 -- : plot (X, Y)
 -- : plot (X, Y, FMT)
 -- : plot (..., PROPERTY, VALUE, ...)
 -- : plot (X1, Y1, ..., XN, YN)
 -- : plot (HAX, ...)
 -- : H = plot (...)
     Produce 2-D plots.

     Many different combinations of arguments are possible.  The
     simplest form is

          plot (Y)

     where the argument is taken as the set of Y coordinates and the X
     coordinates are taken to be the range ‘1:numel (Y)’.

     If more than one argument is given, they are interpreted as

          plot (Y, PROPERTY, VALUE, ...)

     or

          plot (X, Y, PROPERTY, VALUE, ...)

     or

          plot (X, Y, FMT, ...)

     and so on.  Any number of argument sets may appear.  The X and Y
     values are interpreted as follows:

        • If a single data argument is supplied, it is taken as the set
          of Y coordinates and the X coordinates are taken to be the
          indices of the elements, starting with 1.

        • If X and Y are scalars, a single point is plotted.

        • ‘squeeze()’ is applied to arguments with more than two
          dimensions, but no more than two singleton dimensions.

        • If both arguments are vectors, the elements of Y are plotted
          versus the elements of X.

        • If X is a vector and Y is a matrix, then the columns (or rows)
          of Y are plotted versus X.  (using whichever combination
          matches, with columns tried first.)

        • If the X is a matrix and Y is a vector, Y is plotted versus
          the columns (or rows) of X.  (using whichever combination
          matches, with columns tried first.)

        • If both arguments are matrices, the columns of Y are plotted
          versus the columns of X.  In this case, both matrices must
          have the same number of rows and columns and no attempt is
          made to transpose the arguments to make the number of rows
          match.

     Multiple property-value pairs may be specified, but they must
     appear in pairs.  These arguments are applied to the line objects
     drawn by ‘plot’.  Useful properties to modify are "linestyle",
     "linewidth", "color", "marker", "markersize", "markeredgecolor",
     "markerfacecolor".  *Note Line Properties::.

     The FMT format argument can also be used to control the plot style.
     It is a string composed of four optional parts:
     "<linestyle><marker><color><;displayname;>".  When a marker is
     specified, but no linestyle, only the markers are plotted.
     Similarly, if a linestyle is specified, but no marker, then only
     lines are drawn.  If both are specified then lines and markers will
     be plotted.  If no FMT and no PROPERTY/VALUE pairs are given, then
     the default plot style is solid lines with no markers and the color
     determined by the "colororder" property of the current axes.

     Format arguments:

     linestyle

          ‘-’  Use solid lines (default).
          ‘--’ Use dashed lines.
          ‘:’  Use dotted lines.
          ‘-.’ Use dash-dotted lines.

     marker

          ‘+’  crosshair
          ‘o’  circle
          ‘*’  star
          ‘.’  point
          ‘x’  cross
          ‘s’  square
          ‘d’  diamond
          ‘^’  upward-facing triangle
          ‘v’  downward-facing triangle
          ‘>’  right-facing triangle
          ‘<’  left-facing triangle
          ‘p’  pentagram
          ‘h’  hexagram

     color

          ‘k’  blacK
          ‘r’  Red
          ‘g’  Green
          ‘b’  Blue
          ‘y’  Yellow
          ‘m’  Magenta
          ‘c’  Cyan
          ‘w’  White

     ";displayname;"
          Here "displayname" is the label to use for the plot legend.

     The FMT argument may also be used to assign legend labels.  To do
     so, include the desired label between semicolons after the
     formatting sequence described above, e.g., "+b;Key Title;".  Note
     that the last semicolon is required and Octave will generate an
     error if it is left out.

     Here are some plot examples:

          plot (x, y, "or", x, y2, x, y3, "m", x, y4, "+")

     This command will plot ‘y’ with red circles, ‘y2’ with solid lines,
     ‘y3’ with solid magenta lines, and ‘y4’ with points displayed as
     ‘+’.

          plot (b, "*", "markersize", 10)

     This command will plot the data in the variable ‘b’, with points
     displayed as ‘*’ and a marker size of 10.

          t = 0:0.1:6.3;
          plot (t, cos(t), "-;cos(t);", t, sin(t), "-b;sin(t);");

     This will plot the cosine and sine functions and label them
     accordingly in the legend.

     If the first argument HAX is an axes handle, then plot into this
     axes, rather than the current axes returned by ‘gca’.

     The optional return value H is a vector of graphics handles to the
     created line objects.

     To save a plot, in one of several image formats such as PostScript
     or PNG, use the ‘print’ command.

     See also: *note axis: XREFaxis, *note box: XREFbox, *note grid:
     XREFgrid, *note hold: XREFhold, *note legend: XREFlegend, *note
     title: XREFtitle, *note xlabel: XREFxlabel, *note ylabel:
     XREFylabel, *note xlim: XREFxlim, *note ylim: XREFylim, *note
     ezplot: XREFezplot, *note errorbar: XREFerrorbar, *note fplot:
     XREFfplot, *note line: XREFline, *note plot3: XREFplot3, *note
     polar: XREFpolar, *note loglog: XREFloglog, *note semilogx:
     XREFsemilogx, *note semilogy: XREFsemilogy, *note subplot:
     XREFsubplot.

   The ‘plotyy’ function may be used to create a plot with two
independent y axes.

 -- : plotyy (X1, Y1, X2, Y2)
 -- : plotyy (..., FUN)
 -- : plotyy (..., FUN1, FUN2)
 -- : plotyy (HAX, ...)
 -- : [AX, H1, H2] = plotyy (...)
     Plot two sets of data with independent y-axes and a common x-axis.

     The arguments X1 and Y1 define the arguments for the first plot and
     X1 and Y2 for the second.

     By default the arguments are evaluated with ‘feval (@plot, X, Y)’.
     However the type of plot can be modified with the FUN argument, in
     which case the plots are generated by ‘feval (FUN, X, Y)’.  FUN can
     be a function handle, an inline function, or a string of a function
     name.

     The function to use for each of the plots can be independently
     defined with FUN1 and FUN2.

     If the first argument HAX is an axes handle, then it defines the
     principal axes in which to plot the X1 and Y1 data.

     The return value AX is a vector with the axes handles of the two
     y-axes.  H1 and H2 are handles to the objects generated by the plot
     commands.

          x = 0:0.1:2*pi;
          y1 = sin (x);
          y2 = exp (x - 1);
          ax = plotyy (x, y1, x - 1, y2, @plot, @semilogy);
          xlabel ("X");
          ylabel (ax(1), "Axis 1");
          ylabel (ax(2), "Axis 2");

     See also: *note plot: XREFplot.

   The functions ‘semilogx’, ‘semilogy’, and ‘loglog’ are similar to the
‘plot’ function, but produce plots in which one or both of the axes use
log scales.

 -- : semilogx (Y)
 -- : semilogx (X, Y)
 -- : semilogx (X, Y, PROPERTY, VALUE, ...)
 -- : semilogx (X, Y, FMT)
 -- : semilogx (HAX, ...)
 -- : H = semilogx (...)
     Produce a 2-D plot using a logarithmic scale for the x-axis.

     See the documentation of ‘plot’ for a description of the arguments
     that ‘semilogx’ will accept.

     If the first argument HAX is an axes handle, then plot into this
     axes, rather than the current axes returned by ‘gca’.

     The optional return value H is a graphics handle to the created
     plot.

     See also: *note plot: XREFplot, *note semilogy: XREFsemilogy, *note
     loglog: XREFloglog.

 -- : semilogy (Y)
 -- : semilogy (X, Y)
 -- : semilogy (X, Y, PROPERTY, VALUE, ...)
 -- : semilogy (X, Y, FMT)
 -- : semilogy (H, ...)
 -- : H = semilogy (...)
     Produce a 2-D plot using a logarithmic scale for the y-axis.

     See the documentation of ‘plot’ for a description of the arguments
     that ‘semilogy’ will accept.

     If the first argument HAX is an axes handle, then plot into this
     axes, rather than the current axes returned by ‘gca’.

     The optional return value H is a graphics handle to the created
     plot.

     See also: *note plot: XREFplot, *note semilogx: XREFsemilogx, *note
     loglog: XREFloglog.

 -- : loglog (Y)
 -- : loglog (X, Y)
 -- : loglog (X, Y, PROP, VALUE, ...)
 -- : loglog (X, Y, FMT)
 -- : loglog (HAX, ...)
 -- : H = loglog (...)
     Produce a 2-D plot using logarithmic scales for both axes.

     See the documentation of ‘plot’ for a description of the arguments
     that ‘loglog’ will accept.

     If the first argument HAX is an axes handle, then plot into this
     axes, rather than the current axes returned by ‘gca’.

     The optional return value H is a graphics handle to the created
     plot.

     See also: *note plot: XREFplot, *note semilogx: XREFsemilogx, *note
     semilogy: XREFsemilogy.

   The functions ‘bar’, ‘barh’, ‘stairs’, and ‘stem’ are useful for
displaying discrete data.  For example,

     randn ("state", 1);
     hist (randn (10000, 1), 30);
     xlabel ("Value");
     ylabel ("Count");
     title ("Histogram of 10,000 normally distributed random numbers");

produces the histogram of 10,000 normally distributed random numbers
shown in *note Figure 15.2: fig:hist.  Note that, ‘randn ("state", 1);’,
initializes the random number generator for ‘randn’ to a known value so
that the returned values are reproducible; This guarantees that the
figure produced is identical to the one in this manual.

                 
                 +---------------------------------+
                 | Image unavailable in text mode. |
                 +---------------------------------+

Figure 15.2: Histogram.

 -- : bar (Y)
 -- : bar (X, Y)
 -- : bar (..., W)
 -- : bar (..., STYLE)
 -- : bar (..., PROP, VAL, ...)
 -- : bar (HAX, ...)
 -- : H = bar (..., PROP, VAL, ...)
     Produce a bar graph from two vectors of X-Y data.

     If only one argument is given, Y, it is taken as a vector of Y
     values and the X coordinates are the range ‘1:numel (Y)’.

     The optional input W controls the width of the bars.  A value of
     1.0 will cause each bar to exactly touch any adjacent bars.  The
     default width is 0.8.

     If Y is a matrix, then each column of Y is taken to be a separate
     bar graph plotted on the same graph.  By default the columns are
     plotted side-by-side.  This behavior can be changed by the STYLE
     argument which can take the following values:

     "grouped" (default)
          Side-by-side bars with a gap between bars and centered over
          the X-coordinate.

     "stacked"
          Bars are stacked so that each X value has a single bar
          composed of multiple segments.

     "hist"
          Side-by-side bars with no gap between bars and centered over
          the X-coordinate.

     "histc"
          Side-by-side bars with no gap between bars and left-aligned to
          the X-coordinate.

     Optional property/value pairs are passed directly to the underlying
     patch objects.

     If the first argument HAX is an axes handle, then plot into this
     axes, rather than the current axes returned by ‘gca’.

     The optional return value H is a vector of handles to the created
     "bar series" hggroups with one handle per column of the variable Y.
     This series makes it possible to change a common element in one bar
     series object and have the change reflected in the other "bar
     series".  For example,

          h = bar (rand (5, 10));
          set (h(1), "basevalue", 0.5);

     changes the position on the base of all of the bar series.

     The following example modifies the face and edge colors using
     property/value pairs.

          bar (randn (1, 100), "facecolor", "r", "edgecolor", "b");

     The color of the bars is taken from the figure’s colormap, such
     that

          bar (rand (10, 3));
          colormap (summer (64));

     will change the colors used for the bars.  The color of bars can
     also be set manually using the "facecolor" property as shown below.

          h = bar (rand (10, 3));
          set (h(1), "facecolor", "r")
          set (h(2), "facecolor", "g")
          set (h(3), "facecolor", "b")

     See also: *note barh: XREFbarh, *note hist: XREFhist, *note pie:
     XREFpie, *note plot: XREFplot, *note patch: XREFpatch.

 -- : barh (Y)
 -- : barh (X, Y)
 -- : barh (..., W)
 -- : barh (..., STYLE)
 -- : barh (..., PROP, VAL, ...)
 -- : barh (HAX, ...)
 -- : H = barh (..., PROP, VAL, ...)
     Produce a horizontal bar graph from two vectors of X-Y data.

     If only one argument is given, it is taken as a vector of Y values
     and the X coordinates are the range ‘1:numel (Y)’.

     The optional input W controls the width of the bars.  A value of
     1.0 will cause each bar to exactly touch any adjacent bars.  The
     default width is 0.8.

     If Y is a matrix, then each column of Y is taken to be a separate
     bar graph plotted on the same graph.  By default the columns are
     plotted side-by-side.  This behavior can be changed by the STYLE
     argument which can take the following values:

     "grouped" (default)
          Side-by-side bars with a gap between bars and centered over
          the Y-coordinate.

     "stacked"
          Bars are stacked so that each Y value has a single bar
          composed of multiple segments.

     "hist"
          Side-by-side bars with no gap between bars and centered over
          the Y-coordinate.

     "histc"
          Side-by-side bars with no gap between bars and left-aligned to
          the Y-coordinate.

     Optional property/value pairs are passed directly to the underlying
     patch objects.

     If the first argument HAX is an axes handle, then plot into this
     axes, rather than the current axes returned by ‘gca’.

     The optional return value H is a graphics handle to the created bar
     series hggroup.  For a description of the use of the bar series,
     *note bar: XREFbar.

     See also: *note bar: XREFbar, *note hist: XREFhist, *note pie:
     XREFpie, *note plot: XREFplot, *note patch: XREFpatch.

 -- : hist (Y)
 -- : hist (Y, NBINS)
 -- : hist (Y, X)
 -- : hist (Y, X, NORM)
 -- : hist (..., PROP, VAL, ...)
 -- : hist (HAX, ...)
 -- : [NN, XX] = hist (...)
     Produce histogram counts or plots.

     With one vector input argument, Y, plot a histogram of the values
     with 10 bins.  The range of the histogram bins is determined by the
     range of the data (difference between maximum and minimum value in
     Y).  Extreme values are lumped into the first and last bins.  If Y
     is a matrix then plot a histogram where each bin contains one bar
     per input column of Y.

     If the optional second argument is a scalar, NBINS, it defines the
     number of bins.

     If the optional second argument is a vector, X, it defines the
     centers of the bins.  The width of the bins is determined from the
     adjacent values in the vector.  The total number of bins is ‘numel
     (X)’.

     If a third argument is provided, the histogram is normalized such
     that the sum of the bars is equal to NORM.

     The histogram’s appearance may be modified by specifying
     property/value pairs.  For example, the face and edge color may be
     modified:

          hist (randn (1, 100), 25, "facecolor", "r", "edgecolor", "b");

     The histogram’s colors also depend upon the current colormap.

          hist (rand (10, 3));
          colormap (summer ());

     If the first argument HAX is an axes handle, then plot into this
     axes, rather than the current axes returned by ‘gca’.

     If an output is requested then no plot is made.  Instead, return
     the values NN (numbers of elements) and XX (bin centers) such that
     ‘bar (XX, NN)’ will plot the histogram.

     See also: *note histc: XREFhistc, *note bar: XREFbar, *note pie:
     XREFpie, *note rose: XREFrose.

 -- : stemleaf (X, CAPTION)
 -- : stemleaf (X, CAPTION, STEM_SZ)
 -- : PLOTSTR = stemleaf (...)
     Compute and display a stem and leaf plot of the vector X.

     The input X should be a vector of integers.  Any non-integer values
     will be converted to integer by ‘X = fix (X)’.  By default each
     element of X will be plotted with the last digit of the element as
     a leaf value and the remaining digits as the stem.  For example,
     123 will be plotted with the stem ‘12’ and the leaf ‘3’.  The
     second argument, CAPTION, should be a character array which
     provides a description of the data.  It is included as a heading
     for the output.

     The optional input STEM_SZ sets the width of each stem.  The stem
     width is determined by ‘10^(STEM_SZ + 1)’.  The default stem width
     is 10.

     The output of ‘stemleaf’ is composed of two parts: a "Fenced Letter
     Display," followed by the stem-and-leaf plot itself.  The Fenced
     Letter Display is described in ‘Exploratory Data Analysis’.
     Briefly, the entries are as shown:


                  Fenced Letter Display
          #% nx|___________________     nx = numel (x)
          M% mi|       md         |     mi median index, md median
          H% hi|hl              hu| hs  hi lower hinge index, hl,hu hinges,
          1    |x(1)         x(nx)|     hs h_spreadx(1), x(nx) first
                     _______            and last data value.
               ______|step |_______     step 1.5*h_spread
              f|ifl            ifh|     inner fence, lower and higher
               |nfl            nfh|     no.\ of data points within fences
              F|ofl            ofh|     outer fence, lower and higher
               |nFl            nFh|     no.\ of data points outside outer
                                        fences

     The stem-and-leaf plot shows on each line the stem value followed
     by the string made up of the leaf digits.  If the STEM_SZ is not 1
     the successive leaf values are separated by ",".

     With no return argument, the plot is immediately displayed.  If an
     output argument is provided, the plot is returned as an array of
     strings.

     The leaf digits are not sorted.  If sorted leaf values are desired,
     use ‘XS = sort (X)’ before calling ‘stemleaf (XS)’.

     The stem and leaf plot and associated displays are described in:
     Chapter 3, ‘Exploratory Data Analysis’ by J. W. Tukey,
     Addison-Wesley, 1977.

     See also: *note hist: XREFhist, *note printd: XREFprintd.

 -- : printd (OBJ, FILENAME)
 -- : OUT_FILE = printd (...)

     Convert any object acceptable to ‘disp’ into the format selected by
     the suffix of FILENAME.

     If the return argument OUT_FILE is given, the name of the created
     file is returned.

     This function is intended to facilitate manipulation of the output
     of functions such as ‘stemleaf’.

     See also: *note stemleaf: XREFstemleaf.

 -- : stairs (Y)
 -- : stairs (X, Y)
 -- : stairs (..., STYLE)
 -- : stairs (..., PROP, VAL, ...)
 -- : stairs (HAX, ...)
 -- : H = stairs (...)
 -- : [XSTEP, YSTEP] = stairs (...)
     Produce a stairstep plot.

     The arguments X and Y may be vectors or matrices.  If only one
     argument is given, it is taken as a vector of Y values and the X
     coordinates are taken to be the indices of the elements (‘X =
     1:numel (Y)’).

     The style to use for the plot can be defined with a line style
     STYLE of the same format as the ‘plot’ command.

     Multiple property/value pairs may be specified, but they must
     appear in pairs.

     If the first argument HAX is an axes handle, then plot into this
     axes, rather than the current axes returned by ‘gca’.

     If one output argument is requested, return a graphics handle to
     the created plot.  If two output arguments are specified, the data
     are generated but not plotted.  For example,

          stairs (x, y);

     and

          [xs, ys] = stairs (x, y);
          plot (xs, ys);

     are equivalent.

     See also: *note bar: XREFbar, *note hist: XREFhist, *note plot:
     XREFplot, *note stem: XREFstem.

 -- : stem (Y)
 -- : stem (X, Y)
 -- : stem (..., LINESPEC)
 -- : stem (..., "filled")
 -- : stem (..., PROP, VAL, ...)
 -- : stem (HAX, ...)
 -- : H = stem (...)
     Plot a 2-D stem graph.

     If only one argument is given, it is taken as the y-values and the
     x-coordinates are taken from the indices of the elements.

     If Y is a matrix, then each column of the matrix is plotted as a
     separate stem graph.  In this case X can either be a vector, the
     same length as the number of rows in Y, or it can be a matrix of
     the same size as Y.

     The default color is "b" (blue), the default line style is "-", and
     the default marker is "o".  The line style can be altered by the
     LINESPEC argument in the same manner as the ‘plot’ command.  If the
     "filled" argument is present the markers at the top of the stems
     will be filled in.  For example,

          x = 1:10;
          y = 2*x;
          stem (x, y, "r");

     plots 10 stems with heights from 2 to 20 in red;

     Optional property/value pairs may be specified to control the
     appearance of the plot.

     If the first argument HAX is an axes handle, then plot into this
     axes, rather than the current axes returned by ‘gca’.

     The optional return value H is a handle to a "stem series" hggroup.
     The single hggroup handle has all of the graphical elements
     comprising the plot as its children; This allows the properties of
     multiple graphics objects to be changed by modifying just a single
     property of the "stem series" hggroup.

     For example,

          x = [0:10]';
          y = [sin(x), cos(x)]
          h = stem (x, y);
          set (h(2), "color", "g");
          set (h(1), "basevalue", -1)

     changes the color of the second "stem series" and moves the base
     line of the first.

     Stem Series Properties

     linestyle
          The linestyle of the stem.  (Default: "-")

     linewidth
          The width of the stem.  (Default: 0.5)

     color
          The color of the stem, and if not separately specified, the
          marker.  (Default: "b" [blue])

     marker
          The marker symbol to use at the top of each stem.  (Default:
          "o")

     markeredgecolor
          The edge color of the marker.  (Default: "color" property)

     markerfacecolor
          The color to use for "filling" the marker.  (Default: "none"
          [unfilled])

     markersize
          The size of the marker.  (Default: 6)

     baseline
          The handle of the line object which implements the baseline.
          Use ‘set’ with the returned handle to change graphic
          properties of the baseline.

     basevalue
          The y-value where the baseline is drawn.  (Default: 0)

     See also: *note stem3: XREFstem3, *note bar: XREFbar, *note hist:
     XREFhist, *note plot: XREFplot, *note stairs: XREFstairs.

 -- : stem3 (X, Y, Z)
 -- : stem3 (..., LINESPEC)
 -- : stem3 (..., "filled")
 -- : stem3 (..., PROP, VAL, ...)
 -- : stem3 (HAX, ...)
 -- : H = stem3 (...)
     Plot a 3-D stem graph.

     Stems are drawn from the height Z to the location in the x-y plane
     determined by X and Y.  The default color is "b" (blue), the
     default line style is "-", and the default marker is "o".

     The line style can be altered by the LINESPEC argument in the same
     manner as the ‘plot’ command.  If the "filled" argument is present
     the markers at the top of the stems will be filled in.

     Optional property/value pairs may be specified to control the
     appearance of the plot.

     If the first argument HAX is an axes handle, then plot into this
     axes, rather than the current axes returned by ‘gca’.

     The optional return value H is a handle to the "stem series"
     hggroup containing the line and marker objects used for the plot.
     *Note stem: XREFstem, for a description of the "stem series"
     object.

     Example:

          theta = 0:0.2:6;
          stem3 (cos (theta), sin (theta), theta);

     plots 31 stems with heights from 0 to 6 lying on a circle.

     Implementation Note: Color definitions with RGB-triples are not
     valid.

     See also: *note stem: XREFstem, *note bar: XREFbar, *note hist:
     XREFhist, *note plot: XREFplot.

 -- : scatter (X, Y)
 -- : scatter (X, Y, S)
 -- : scatter (X, Y, S, C)
 -- : scatter (..., STYLE)
 -- : scatter (..., "filled")
 -- : scatter (..., PROP, VAL, ...)
 -- : scatter (HAX, ...)
 -- : H = scatter (...)
     Draw a 2-D scatter plot.

     A marker is plotted at each point defined by the coordinates in the
     vectors X and Y.

     The size of the markers is determined by S, which can be a scalar
     or a vector of the same length as X and Y.  If S is not given, or
     is an empty matrix, then a default value of 36 square points is
     used (The marker size itself is ‘sqrt (s)’).

     The color of the markers is determined by C, which can be a string
     defining a fixed color; a 3-element vector giving the red, green,
     and blue components of the color; a vector of the same length as X
     that gives a scaled index into the current colormap; or an Nx3
     matrix defining the RGB color of each marker individually.

     The marker to use can be changed with the STYLE argument; it is a
     string defining a marker in the same manner as the ‘plot’ command.
     If no marker is specified it defaults to "o" or circles.  If the
     argument "filled" is given then the markers are filled.

     Additional property/value pairs are passed directly to the
     underlying patch object.

     If the first argument HAX is an axes handle, then plot into this
     axes, rather than the current axes returned by ‘gca’.

     The optional return value H is a graphics handle to the created
     scatter object.

     Example:

          x = randn (100, 1);
          y = randn (100, 1);
          scatter (x, y, [], sqrt (x.^2 + y.^2));

     See also: *note scatter3: XREFscatter3, *note patch: XREFpatch,
     *note plot: XREFplot.

 -- : plotmatrix (X, Y)
 -- : plotmatrix (X)
 -- : plotmatrix (..., STYLE)
 -- : plotmatrix (HAX, ...)
 -- : [H, AX, BIGAX, P, PAX] = plotmatrix (...)
     Scatter plot of the columns of one matrix against another.

     Given the arguments X and Y that have a matching number of rows,
     ‘plotmatrix’ plots a set of axes corresponding to

          plot (X(:, i), Y(:, j))

     When called with a single argument X this is equivalent to

          plotmatrix (X, X)

     except that the diagonal of the set of axes will be replaced with
     the histogram ‘hist (X(:, i))’.

     The marker to use can be changed with the STYLE argument, that is a
     string defining a marker in the same manner as the ‘plot’ command.

     If the first argument HAX is an axes handle, then plot into this
     axes, rather than the current axes returned by ‘gca’.

     The optional return value H provides handles to the individual
     graphics objects in the scatter plots, whereas AX returns the
     handles to the scatter plot axes objects.

     BIGAX is a hidden axes object that surrounds the other axes, such
     that the commands ‘xlabel’, ‘title’, etc., will be associated with
     this hidden axes.

     Finally, P returns the graphics objects associated with the
     histogram and PAX the corresponding axes objects.

     Example:

          plotmatrix (randn (100, 3), "g+")

     See also: *note scatter: XREFscatter, *note plot: XREFplot.

 -- : pareto (Y)
 -- : pareto (Y, X)
 -- : pareto (HAX, ...)
 -- : H = pareto (...)
     Draw a Pareto chart.

     A Pareto chart is a bar graph that arranges information in such a
     way that priorities for process improvement can be established; It
     organizes and displays information to show the relative importance
     of data.  The chart is similar to the histogram or bar chart,
     except that the bars are arranged in decreasing magnitude from left
     to right along the x-axis.

     The fundamental idea (Pareto principle) behind the use of Pareto
     diagrams is that the majority of an effect is due to a small subset
     of the causes.  For quality improvement, the first few contributing
     causes (leftmost bars as presented on the diagram) to a problem
     usually account for the majority of the result.  Thus, targeting
     these "major causes" for elimination results in the most
     cost-effective improvement scheme.

     Typically only the magnitude data Y is present in which case X is
     taken to be the range ‘1 : length (Y)’.  If X is given it may be a
     string array, a cell array of strings, or a numerical vector.

     If the first argument HAX is an axes handle, then plot into this
     axes, rather than the current axes returned by ‘gca’.

     The optional return value H is a 2-element vector with a graphics
     handle for the created bar plot and a second handle for the created
     line plot.

     An example of the use of ‘pareto’ is

          Cheese = {"Cheddar", "Swiss", "Camembert", ...
                    "Munster", "Stilton", "Blue"};
          Sold = [105, 30, 70, 10, 15, 20];
          pareto (Sold, Cheese);

     See also: *note bar: XREFbar, *note barh: XREFbarh, *note hist:
     XREFhist, *note pie: XREFpie, *note plot: XREFplot.

 -- : rose (TH)
 -- : rose (TH, NBINS)
 -- : rose (TH, BINS)
 -- : rose (HAX, ...)
 -- : H = rose (...)
 -- : [THOUT ROUT] = rose (...)
     Plot an angular histogram.

     With one vector argument, TH, plot the histogram with 20 angular
     bins.  If TH is a matrix then each column of TH produces a separate
     histogram.

     If NBINS is given and is a scalar, then the histogram is produced
     with NBIN bins.  If BINS is a vector, then the center of each bin
     is defined by the values in BINS and the number of bins is given by
     the number of elements in BINS.

     If the first argument HAX is an axes handle, then plot into this
     axes, rather than the current axes returned by ‘gca’.

     The optional return value H is a vector of graphics handles to the
     line objects representing each histogram.

     If two output arguments are requested then no plot is made and the
     polar vectors necessary to plot the histogram are returned instead.

     Example

          [th, r] = rose ([2*randn(1e5,1), pi + 2*randn(1e5,1)]);
          polar (th, r);

     Programming Note: When specifying bin centers with the BINS input,
     the edges for bins 2 to N-1 are spaced so that ‘BINS(i)’ is
     centered between the edges.  The final edge is drawn halfway
     between bin N and bin 1.  This guarantees that all input TH will be
     placed into one of the bins, but also means that for some
     combinations bin 1 and bin N may not be centered on the user’s
     given values.

     See also: *note hist: XREFhist, *note polar: XREFpolar.

   The ‘contour’, ‘contourf’ and ‘contourc’ functions produce
two-dimensional contour plots from three-dimensional data.

 -- : contour (Z)
 -- : contour (Z, VN)
 -- : contour (X, Y, Z)
 -- : contour (X, Y, Z, VN)
 -- : contour (..., STYLE)
 -- : contour (HAX, ...)
 -- : [C, H] = contour (...)
     Create a 2-D contour plot.

     Plot level curves (contour lines) of the matrix Z, using the
     contour matrix C computed by ‘contourc’ from the same arguments;
     see the latter for their interpretation.

     The appearance of contour lines can be defined with a line style
     STYLE in the same manner as ‘plot’.  Only line style and color are
     used; Any markers defined by STYLE are ignored.

     If the first argument HAX is an axes handle, then plot into this
     axes, rather than the current axes returned by ‘gca’.

     The optional output C contains the contour levels in ‘contourc’
     format.

     The optional return value H is a graphics handle to the hggroup
     comprising the contour lines.

     Example:

          x = 0:3;
          y = 0:2;
          z = y' * x;
          contour (x, y, z, 2:3)

     See also: *note ezcontour: XREFezcontour, *note contourc:
     XREFcontourc, *note contourf: XREFcontourf, *note contour3:
     XREFcontour3, *note clabel: XREFclabel, *note meshc: XREFmeshc,
     *note surfc: XREFsurfc, *note caxis: XREFcaxis, *note colormap:
     XREFcolormap, *note plot: XREFplot.

 -- : contourf (Z)
 -- : contourf (Z, VN)
 -- : contourf (X, Y, Z)
 -- : contourf (X, Y, Z, VN)
 -- : contourf (..., STYLE)
 -- : contourf (HAX, ...)
 -- : [C, H] = contourf (...)
     Create a 2-D contour plot with filled intervals.

     Plot level curves (contour lines) of the matrix Z and fill the
     region between lines with colors from the current colormap.

     The level curves are taken from the contour matrix C computed by
     ‘contourc’ for the same arguments; see the latter for their
     interpretation.

     The appearance of contour lines can be defined with a line style
     STYLE in the same manner as ‘plot’.  Only line style and color are
     used; Any markers defined by STYLE are ignored.

     If the first argument HAX is an axes handle, then plot into this
     axes, rather than the current axes returned by ‘gca’.

     The optional output C contains the contour levels in ‘contourc’
     format.

     The optional return value H is a graphics handle to the hggroup
     comprising the contour lines.

     The following example plots filled contours of the ‘peaks’
     function.

          [x, y, z] = peaks (50);
          contourf (x, y, z, -7:9)

     See also: *note ezcontourf: XREFezcontourf, *note contour:
     XREFcontour, *note contourc: XREFcontourc, *note contour3:
     XREFcontour3, *note clabel: XREFclabel, *note meshc: XREFmeshc,
     *note surfc: XREFsurfc, *note caxis: XREFcaxis, *note colormap:
     XREFcolormap, *note plot: XREFplot.

 -- : [C, LEV] = contourc (Z)
 -- : [C, LEV] = contourc (Z, VN)
 -- : [C, LEV] = contourc (X, Y, Z)
 -- : [C, LEV] = contourc (X, Y, Z, VN)
     Compute contour lines (isolines of constant Z value).

     The matrix Z contains height values above the rectangular grid
     determined by X and Y.  If only a single input Z is provided then X
     is taken to be ‘1:columns (Z)’ and Y is taken to be ‘1:rows (Z)’.
     The minimum data size is 2x2.

     The optional input VN is either a scalar denoting the number of
     contour lines to compute or a vector containing the Z values where
     lines will be computed.  When VN is a vector the number of contour
     lines is ‘numel (VN)’.  However, to compute a single contour line
     at a given value use ‘VN = [val, val]’.  If VN is omitted it
     defaults to 10.

     The return value C is a 2xN matrix containing the contour lines in
     the following format

          C = [lev1, x1, x2, ..., levn, x1, x2, ...
               len1, y1, y2, ..., lenn, y1, y2, ...]

     in which contour line N has a level (height) of LEVN and length of
     LENN.

     The optional return value LEV is a vector with the Z values of the
     contour levels.

     Example:

          x = 0:2;
          y = x;
          z = x' * y;
          c = contourc (x, y, z, 2:3)
            ⇒ c =
                  2.0000   1.0000   1.0000   2.0000   2.0000   3.0000   1.5000   2.0000
                  4.0000   2.0000   2.0000   1.0000   1.0000   2.0000   2.0000   1.5000

     See also: *note contour: XREFcontour, *note contourf: XREFcontourf,
     *note contour3: XREFcontour3, *note clabel: XREFclabel.

 -- : contour3 (Z)
 -- : contour3 (Z, VN)
 -- : contour3 (X, Y, Z)
 -- : contour3 (X, Y, Z, VN)
 -- : contour3 (..., STYLE)
 -- : contour3 (HAX, ...)
 -- : [C, H] = contour3 (...)
     Create a 3-D contour plot.

     ‘contour3’ plots level curves (contour lines) of the matrix Z at a
     Z level corresponding to each contour.  This is in contrast to
     ‘contour’ which plots all of the contour lines at the same Z level
     and produces a 2-D plot.

     The level curves are taken from the contour matrix C computed by
     ‘contourc’ for the same arguments; see the latter for their
     interpretation.

     The appearance of contour lines can be defined with a line style
     STYLE in the same manner as ‘plot’.  Only line style and color are
     used; Any markers defined by STYLE are ignored.

     If the first argument HAX is an axes handle, then plot into this
     axes, rather than the current axes returned by ‘gca’.

     The optional output C are the contour levels in ‘contourc’ format.

     The optional return value H is a graphics handle to the hggroup
     comprising the contour lines.

     Example:

          contour3 (peaks (19));
          colormap cool;
          hold on;
          surf (peaks (19), "facecolor", "none", "edgecolor", "black");

     See also: *note contour: XREFcontour, *note contourc: XREFcontourc,
     *note contourf: XREFcontourf, *note clabel: XREFclabel, *note
     meshc: XREFmeshc, *note surfc: XREFsurfc, *note caxis: XREFcaxis,
     *note colormap: XREFcolormap, *note plot: XREFplot.

   The ‘errorbar’, ‘semilogxerr’, ‘semilogyerr’, and ‘loglogerr’
functions produce plots with error bar markers.  For example,

     rand ("state", 2);
     x = 0:0.1:10;
     y = sin (x);
     lerr = 0.1 .* rand (size (x));
     uerr = 0.1 .* rand (size (x));
     errorbar (x, y, lerr, uerr);
     axis ([0, 10, -1.1, 1.1]);
     xlabel ("x");
     ylabel ("sin (x)");
     title ("Errorbar plot of sin (x)");

produces the figure shown in *note Figure 15.3: fig:errorbar.

                 
                 +---------------------------------+
                 | Image unavailable in text mode. |
                 +---------------------------------+

Figure 15.3: Errorbar plot.

 -- : errorbar (Y, EY)
 -- : errorbar (Y, ..., FMT)
 -- : errorbar (X, Y, EY)
 -- : errorbar (X, Y, ERR, FMT)
 -- : errorbar (X, Y, LERR, UERR, FMT)
 -- : errorbar (X, Y, EX, EY, FMT)
 -- : errorbar (X, Y, LX, UX, LY, UY, FMT)
 -- : errorbar (X1, Y1, ..., FMT, XN, YN, ...)
 -- : errorbar (HAX, ...)
 -- : H = errorbar (...)
     Create a 2-D plot with errorbars.

     Many different combinations of arguments are possible.  The
     simplest form is

          errorbar (Y, EY)

     where the first argument is taken as the set of Y coordinates, the
     second argument EY are the errors around the Y values, and the X
     coordinates are taken to be the indices of the elements (‘1:numel
     (Y)’).

     The general form of the function is

          errorbar (X, Y, ERR1, ..., FMT, ...)

     After the X and Y arguments there can be 1, 2, or 4 parameters
     specifying the error values depending on the nature of the error
     values and the plot format FMT.

     ERR (scalar)
          When the error is a scalar all points share the same error
          value.  The errorbars are symmetric and are drawn from
          DATA-ERR to DATA+ERR.  The FMT argument determines whether ERR
          is in the x-direction, y-direction (default), or both.

     ERR (vector or matrix)
          Each data point has a particular error value.  The errorbars
          are symmetric and are drawn from DATA(n)-ERR(n) to
          DATA(n)+ERR(n).

     LERR, UERR (scalar)
          The errors have a single low-side value and a single
          upper-side value.  The errorbars are not symmetric and are
          drawn from DATA-LERR to DATA+UERR.

     LERR, UERR (vector or matrix)
          Each data point has a low-side error and an upper-side error.
          The errorbars are not symmetric and are drawn from
          DATA(n)-LERR(n) to DATA(n)+UERR(n).

     Any number of data sets (X1,Y1, X2,Y2, ...) may appear as long as
     they are separated by a format string FMT.

     If Y is a matrix, X and the error parameters must also be matrices
     having the same dimensions.  The columns of Y are plotted versus
     the corresponding columns of X and errorbars are taken from the
     corresponding columns of the error parameters.

     If FMT is missing, the yerrorbars ("~") plot style is assumed.

     If the FMT argument is supplied then it is interpreted, as in
     normal plots, to specify the line style, marker, and color.  In
     addition, FMT may include an errorbar style which *must precede*
     the ordinary format codes.  The following errorbar styles are
     supported:

     ‘~’
          Set yerrorbars plot style (default).

     ‘>’
          Set xerrorbars plot style.

     ‘~>’
          Set xyerrorbars plot style.

     ‘#~’
          Set yboxes plot style.

     ‘#’
          Set xboxes plot style.

     ‘#~>’
          Set xyboxes plot style.

     If the first argument HAX is an axes handle, then plot into this
     axes, rather than the current axes returned by ‘gca’.

     The optional return value H is a handle to the hggroup object
     representing the data plot and errorbars.

     Note: For compatibility with MATLAB a line is drawn through all
     data points.  However, most scientific errorbar plots are a scatter
     plot of points with errorbars.  To accomplish this, add a marker
     style to the FMT argument such as ".".  Alternatively, remove the
     line by modifying the returned graphic handle with ‘set (h,
     "linestyle", "none")’.

     Examples:

          errorbar (X, Y, EX, ">.r")

     produces an xerrorbar plot of Y versus X with X errorbars drawn
     from X-EX to X+EX.  The marker "."  is used so no connecting line
     is drawn and the errorbars appear in red.

          errorbar (X, Y1, EY, "~",
                    X, Y2, LY, UY)

     produces yerrorbar plots with Y1 and Y2 versus X.  Errorbars for Y1
     are drawn from Y1-EY to Y1+EY, errorbars for Y2 from Y2-LY to
     Y2+UY.

          errorbar (X, Y, LX, UX,
                    LY, UY, "~>")

     produces an xyerrorbar plot of Y versus X in which X errorbars are
     drawn from X-LX to X+UX and Y errorbars from Y-LY to Y+UY.

     See also: *note semilogxerr: XREFsemilogxerr, *note semilogyerr:
     XREFsemilogyerr, *note loglogerr: XREFloglogerr, *note plot:
     XREFplot.

 -- : semilogxerr (Y, EY)
 -- : semilogxerr (Y, ..., FMT)
 -- : semilogxerr (X, Y, EY)
 -- : semilogxerr (X, Y, ERR, FMT)
 -- : semilogxerr (X, Y, LERR, UERR, FMT)
 -- : semilogxerr (X, Y, EX, EY, FMT)
 -- : semilogxerr (X, Y, LX, UX, LY, UY, FMT)
 -- : semilogxerr (X1, Y1, ..., FMT, XN, YN, ...)
 -- : semilogxerr (HAX, ...)
 -- : H = semilogxerr (...)
     Produce 2-D plots using a logarithmic scale for the x-axis and
     errorbars at each data point.

     Many different combinations of arguments are possible.  The most
     common form is

          semilogxerr (X, Y, EY, FMT)

     which produces a semi-logarithmic plot of Y versus X with errors in
     the Y-scale defined by EY and the plot format defined by FMT.
     *Note errorbar: XREFerrorbar, for available formats and additional
     information.

     If the first argument HAX is an axes handle, then plot into this
     axes, rather than the current axes returned by ‘gca’.

     See also: *note errorbar: XREFerrorbar, *note semilogyerr:
     XREFsemilogyerr, *note loglogerr: XREFloglogerr.

 -- : semilogyerr (Y, EY)
 -- : semilogyerr (Y, ..., FMT)
 -- : semilogyerr (X, Y, EY)
 -- : semilogyerr (X, Y, ERR, FMT)
 -- : semilogyerr (X, Y, LERR, UERR, FMT)
 -- : semilogyerr (X, Y, EX, EY, FMT)
 -- : semilogyerr (X, Y, LX, UX, LY, UY, FMT)
 -- : semilogyerr (X1, Y1, ..., FMT, XN, YN, ...)
 -- : semilogyerr (HAX, ...)
 -- : H = semilogyerr (...)
     Produce 2-D plots using a logarithmic scale for the y-axis and
     errorbars at each data point.

     Many different combinations of arguments are possible.  The most
     common form is

          semilogyerr (X, Y, EY, FMT)

     which produces a semi-logarithmic plot of Y versus X with errors in
     the Y-scale defined by EY and the plot format defined by FMT.
     *Note errorbar: XREFerrorbar, for available formats and additional
     information.

     If the first argument HAX is an axes handle, then plot into this
     axes, rather than the current axes returned by ‘gca’.

     See also: *note errorbar: XREFerrorbar, *note semilogxerr:
     XREFsemilogxerr, *note loglogerr: XREFloglogerr.

 -- : loglogerr (Y, EY)
 -- : loglogerr (Y, ..., FMT)
 -- : loglogerr (X, Y, EY)
 -- : loglogerr (X, Y, ERR, FMT)
 -- : loglogerr (X, Y, LERR, UERR, FMT)
 -- : loglogerr (X, Y, EX, EY, FMT)
 -- : loglogerr (X, Y, LX, UX, LY, UY, FMT)
 -- : loglogerr (X1, Y1, ..., FMT, XN, YN, ...)
 -- : loglogerr (HAX, ...)
 -- : H = loglogerr (...)
     Produce 2-D plots on a double logarithm axis with errorbars.

     Many different combinations of arguments are possible.  The most
     common form is

          loglogerr (X, Y, EY, FMT)

     which produces a double logarithm plot of Y versus X with errors in
     the Y-scale defined by EY and the plot format defined by FMT.
     *Note errorbar: XREFerrorbar, for available formats and additional
     information.

     If the first argument HAX is an axes handle, then plot into this
     axes, rather than the current axes returned by ‘gca’.

     See also: *note errorbar: XREFerrorbar, *note semilogxerr:
     XREFsemilogxerr, *note semilogyerr: XREFsemilogyerr.

   Finally, the ‘polar’ function allows you to easily plot data in polar
coordinates.  However, the display coordinates remain rectangular and
linear.  For example,

     polar (0:0.1:10*pi, 0:0.1:10*pi);
     title ("Example polar plot from 0 to 10*pi");

produces the spiral plot shown in *note Figure 15.4: fig:polar.

                 
                 +---------------------------------+
                 | Image unavailable in text mode. |
                 +---------------------------------+

Figure 15.4: Polar plot.

 -- : polar (THETA, RHO)
 -- : polar (THETA, RHO, FMT)
 -- : polar (CPLX)
 -- : polar (CPLX, FMT)
 -- : polar (HAX, ...)
 -- : H = polar (...)
     Create a 2-D plot from polar coordinates THETA and RHO.

     The input THETA is assumed to be radians and is converted to
     degrees for plotting.  If you have degrees then you must convert
     (*note cart2pol: XREFcart2pol.) to radians before passing the data
     to this function.

     If a single complex input CPLX is given then the real part is used
     for THETA and the imaginary part is used for RHO.

     The optional argument FMT specifies the line format in the same way
     as ‘plot’.

     If the first argument HAX is an axes handle, then plot into this
     axes, rather than the current axes returned by ‘gca’.

     The optional return value H is a graphics handle to the created
     plot.

     Implementation Note: The polar axis is drawn using line and text
     objects encapsulated in an hggroup.  The hggroup properties are
     linked to the original axes object such that altering an appearance
     property, for example ‘fontname’, will update the polar axis.  Two
     new properties are added to the original axes–‘rtick’,
     ‘ttick’–which replace ‘xtick’, ‘ytick’.  The first is a list of
     tick locations in the radial (rho) direction; The second is a list
     of tick locations in the angular (theta) direction specified in
     degrees, i.e., in the range 0–359.

     See also: *note rose: XREFrose, *note compass: XREFcompass, *note
     plot: XREFplot, *note cart2pol: XREFcart2pol.

 -- : pie (X)
 -- : pie (..., EXPLODE)
 -- : pie (..., LABELS)
 -- : pie (HAX, ...)
 -- : H = pie (...)
     Plot a 2-D pie chart.

     When called with a single vector argument, produce a pie chart of
     the elements in X.  The size of the ith slice is the percentage
     that the element Xi represents of the total sum of X: ‘pct = X(i) /
     sum (X)’.

     The optional input EXPLODE is a vector of the same length as X
     that, if nonzero, "explodes" the slice from the pie chart.

     The optional input LABELS is a cell array of strings of the same
     length as X specifying the label for each slice.

     If the first argument HAX is an axes handle, then plot into this
     axes, rather than the current axes returned by ‘gca’.

     The optional return value H is a list of handles to the patch and
     text objects generating the plot.

     Note: If ‘sum (X) ≤ 1’ then the elements of X are interpreted as
     percentages directly and are not normalized by ‘sum (x)’.
     Furthermore, if the sum is less than 1 then there will be a missing
     slice in the pie plot to represent the missing, unspecified
     percentage.

     See also: *note pie3: XREFpie3, *note bar: XREFbar, *note hist:
     XREFhist, *note rose: XREFrose.

 -- : pie3 (X)
 -- : pie3 (..., EXPLODE)
 -- : pie3 (..., LABELS)
 -- : pie3 (HAX, ...)
 -- : H = pie3 (...)
     Plot a 3-D pie chart.

     Called with a single vector argument, produces a 3-D pie chart of
     the elements in X.  The size of the ith slice is the percentage
     that the element Xi represents of the total sum of X: ‘pct = X(i) /
     sum (X)’.

     The optional input EXPLODE is a vector of the same length as X
     that, if nonzero, "explodes" the slice from the pie chart.

     The optional input LABELS is a cell array of strings of the same
     length as X specifying the label for each slice.

     If the first argument HAX is an axes handle, then plot into this
     axes, rather than the current axes returned by ‘gca’.

     The optional return value H is a list of graphics handles to the
     patch, surface, and text objects generating the plot.

     Note: If ‘sum (X) ≤ 1’ then the elements of X are interpreted as
     percentages directly and are not normalized by ‘sum (x)’.
     Furthermore, if the sum is less than 1 then there will be a missing
     slice in the pie plot to represent the missing, unspecified
     percentage.

     See also: *note pie: XREFpie, *note bar: XREFbar, *note hist:
     XREFhist, *note rose: XREFrose.

 -- : quiver (U, V)
 -- : quiver (X, Y, U, V)
 -- : quiver (..., S)
 -- : quiver (..., STYLE)
 -- : quiver (..., "filled")
 -- : quiver (HAX, ...)
 -- : H = quiver (...)

     Plot a 2-D vector field with arrows.

     Plot the (U, V) components of a vector field at the grid points
     defined by (X, Y).  If the grid is uniform then X and Y can be
     specified as vectors and ‘meshgrid’ is used to create the 2-D grid.

     If X and Y are not given they are assumed to be ‘(1:M, 1:N)’ where
     ‘[M, N] = size (U)’.

     The optional input S is a scalar defining a scaling factor to use
     for the arrows of the field relative to the mesh spacing.  A value
     of 1.0 will result in the longest vector exactly filling one grid
     square.  A value of 0 disables all scaling.  The default value is
     0.9.

     The style to use for the plot can be defined with a line style
     STYLE of the same format as the ‘plot’ command.  If a marker is
     specified then the markers are drawn at the origin of the vectors
     (which are the grid points defined by X and Y).  When a marker is
     specified, the arrowhead is not drawn.  If the argument "filled" is
     given then the markers are filled.

     If the first argument HAX is an axes handle, then plot into this
     axes, rather than the current axes returned by ‘gca’.

     The optional return value H is a graphics handle to a quiver
     object.  A quiver object regroups the components of the quiver plot
     (body, arrow, and marker), and allows them to be changed together.

     Example:

          [x, y] = meshgrid (1:2:20);
          h = quiver (x, y, sin (2*pi*x/10), sin (2*pi*y/10));
          set (h, "maxheadsize", 0.33);

     See also: *note quiver3: XREFquiver3, *note compass: XREFcompass,
     *note feather: XREFfeather, *note plot: XREFplot.

 -- : quiver3 (X, Y, Z, U, V, W)
 -- : quiver3 (Z, U, V, W)
 -- : quiver3 (..., S)
 -- : quiver3 (..., STYLE)
 -- : quiver3 (..., "filled")
 -- : quiver3 (HAX, ...)
 -- : H = quiver3 (...)

     Plot a 3-D vector field with arrows.

     Plot the (U, V, W) components of a vector field at the grid points
     defined by (X, Y, Z).  If the grid is uniform then X, Y, and Z can
     be specified as vectors and ‘meshgrid’ is used to create the 3-D
     grid.

     If X and Y are not given they are assumed to be ‘(1:M, 1:N)’ where
     ‘[M, N] = size (U)’.

     The optional input S is a scalar defining a scaling factor to use
     for the arrows of the field relative to the mesh spacing.  A value
     of 1.0 will result in the longest vector exactly filling one grid
     cube.  A value of 0 disables all scaling.  The default value is
     0.9.

     The style to use for the plot can be defined with a line style
     STYLE of the same format as the ‘plot’ command.  If a marker is
     specified then the markers are drawn at the origin of the vectors
     (which are the grid points defined by X, Y, Z).  When a marker is
     specified, the arrowhead is not drawn.  If the argument "filled" is
     given then the markers are filled.

     If the first argument HAX is an axes handle, then plot into this
     axes, rather than the current axes returned by ‘gca’.

     The optional return value H is a graphics handle to a quiver
     object.  A quiver object regroups the components of the quiver plot
     (body, arrow, and marker), and allows them to be changed together.

          [x, y, z] = peaks (25);
          surf (x, y, z);
          hold on;
          [u, v, w] = surfnorm (x, y, z / 10);
          h = quiver3 (x, y, z, u, v, w);
          set (h, "maxheadsize", 0.33);

     See also: *note quiver: XREFquiver, *note compass: XREFcompass,
     *note feather: XREFfeather, *note plot: XREFplot.

 -- : compass (U, V)
 -- : compass (Z)
 -- : compass (..., STYLE)
 -- : compass (HAX, ...)
 -- : H = compass (...)

     Plot the ‘(U, V)’ components of a vector field emanating from the
     origin of a polar plot.

     The arrow representing each vector has one end at the origin and
     the tip at [U(i), V(i)].  If a single complex argument Z is given,
     then ‘U = real (Z)’ and ‘V = imag (Z)’.

     The style to use for the plot can be defined with a line style
     STYLE of the same format as the ‘plot’ command.

     If the first argument HAX is an axes handle, then plot into this
     axes, rather than the current axes returned by ‘gca’.

     The optional return value H is a vector of graphics handles to the
     line objects representing the drawn vectors.

          a = toeplitz ([1;randn(9,1)], [1,randn(1,9)]);
          compass (eig (a));

     See also: *note polar: XREFpolar, *note feather: XREFfeather, *note
     quiver: XREFquiver, *note rose: XREFrose, *note plot: XREFplot.

 -- : feather (U, V)
 -- : feather (Z)
 -- : feather (..., STYLE)
 -- : feather (HAX, ...)
 -- : H = feather (...)

     Plot the ‘(U, V)’ components of a vector field emanating from
     equidistant points on the x-axis.

     If a single complex argument Z is given, then ‘U = real (Z)’ and ‘V
     = imag (Z)’.

     The style to use for the plot can be defined with a line style
     STYLE of the same format as the ‘plot’ command.

     If the first argument HAX is an axes handle, then plot into this
     axes, rather than the current axes returned by ‘gca’.

     The optional return value H is a vector of graphics handles to the
     line objects representing the drawn vectors.

          phi = [0 : 15 : 360] * pi/180;
          feather (sin (phi), cos (phi));

     See also: *note plot: XREFplot, *note quiver: XREFquiver, *note
     compass: XREFcompass.

 -- : pcolor (X, Y, C)
 -- : pcolor (C)
 -- : pcolor (HAX, ...)
 -- : H = pcolor (...)
     Produce a 2-D density plot.

     A ‘pcolor’ plot draws rectangles with colors from the matrix C over
     the two-dimensional region represented by the matrices X and Y.  X
     and Y are the coordinates of the mesh’s vertices and are typically
     the output of ‘meshgrid’.  If X and Y are vectors, then a typical
     vertex is (X(j), Y(i), C(i,j)).  Thus, columns of C correspond to
     different X values and rows of C correspond to different Y values.

     The values in C are scaled to span the range of the current
     colormap.  Limits may be placed on the color axis by the command
     ‘caxis’, or by setting the ‘clim’ property of the parent axis.

     The face color of each cell of the mesh is determined by
     interpolating the values of C for each of the cell’s vertices;
     Contrast this with ‘imagesc’ which renders one cell for each
     element of C.

     ‘shading’ modifies an attribute determining the manner by which the
     face color of each cell is interpolated from the values of C, and
     the visibility of the cells’ edges.  By default the attribute is
     "faceted", which renders a single color for each cell’s face with
     the edge visible.

     If the first argument HAX is an axes handle, then plot into this
     axes, rather than the current axes returned by ‘gca’.

     The optional return value H is a graphics handle to the created
     surface object.

     See also: *note caxis: XREFcaxis, *note shading: XREFshading, *note
     meshgrid: XREFmeshgrid, *note contour: XREFcontour, *note imagesc:
     XREFimagesc.

 -- : area (Y)
 -- : area (X, Y)
 -- : area (..., LVL)
 -- : area (..., PROP, VAL, ...)
 -- : area (HAX, ...)
 -- : H = area (...)
     Area plot of the columns of Y.

     This plot shows the contributions of each column value to the row
     sum.  It is functionally similar to ‘plot (X, cumsum (Y, 2))’,
     except that the area under the curve is shaded.

     If the X argument is omitted it defaults to ‘1:rows (Y)’.  A value
     LVL can be defined that determines where the base level of the
     shading under the curve should be defined.  The default level is 0.

     Additional property/value pairs are passed directly to the
     underlying patch object.

     If the first argument HAX is an axes handle, then plot into this
     axes, rather than the current axes returned by ‘gca’.

     The optional return value H is a graphics handle to the hggroup
     object comprising the area patch objects.  The "BaseValue" property
     of the hggroup can be used to adjust the level where shading
     begins.

     Example: Verify identity sin^2 + cos^2 = 1

          t = linspace (0, 2*pi, 100)';
          y = [sin(t).^2, cos(t).^2];
          area (t, y);
          legend ("sin^2", "cos^2", "location", "NorthEastOutside");

     See also: *note plot: XREFplot, *note patch: XREFpatch.

 -- : fill (X, Y, C)
 -- : fill (X1, Y1, C1, X2, Y2, C2)
 -- : fill (..., PROP, VAL)
 -- : fill (HAX, ...)
 -- : H = fill (...)
     Create one or more filled 2-D polygons.

     The inputs X and Y are the coordinates of the polygon vertices.  If
     the inputs are matrices then the rows represent different vertices
     and each column produces a different polygon.  ‘fill’ will close
     any open polygons before plotting.

     The input C determines the color of the polygon.  The simplest form
     is a single color specification such as a ‘plot’ format or an
     RGB-triple.  In this case the polygon(s) will have one unique
     color.  If C is a vector or matrix then the color data is first
     scaled using ‘caxis’ and then indexed into the current colormap.  A
     row vector will color each polygon (a column from matrices X and Y)
     with a single computed color.  A matrix C of the same size as X and
     Y will compute the color of each vertex and then interpolate the
     face color between the vertices.

     Multiple property/value pairs for the underlying patch object may
     be specified, but they must appear in pairs.

     If the first argument HAX is an axes handle, then plot into this
     axes, rather than the current axes returned by ‘gca’.

     The optional return value H is a vector of graphics handles to the
     created patch objects.

     Example: red square

          vertices = [0 0
                      1 0
                      1 1
                      0 1];
          fill (vertices(:,1), vertices(:,2), "r");
          axis ([-0.5 1.5, -0.5 1.5])
          axis equal

     See also: *note patch: XREFpatch, *note caxis: XREFcaxis, *note
     colormap: XREFcolormap.

 -- : comet (Y)
 -- : comet (X, Y)
 -- : comet (X, Y, P)
 -- : comet (HAX, ...)
     Produce a simple comet style animation along the trajectory
     provided by the input coordinate vectors (X, Y).

     If X is not specified it defaults to the indices of Y.

     The speed of the comet may be controlled by P, which represents the
     time each point is displayed before moving to the next one.  The
     default for P is 0.1 seconds.

     If the first argument HAX is an axes handle, then plot into this
     axes, rather than the current axes returned by ‘gca’.

     See also: *note comet3: XREFcomet3.

 -- : comet3 (Z)
 -- : comet3 (X, Y, Z)
 -- : comet3 (X, Y, Z, P)
 -- : comet3 (HAX, ...)
     Produce a simple comet style animation along the trajectory
     provided by the input coordinate vectors (X, Y, Z).

     If only Z is specified then X, Y default to the indices of Z.

     The speed of the comet may be controlled by P, which represents the
     time each point is displayed before moving to the next one.  The
     default for P is 0.1 seconds.

     If the first argument HAX is an axes handle, then plot into this
     axes, rather than the current axes returned by ‘gca’.

     See also: *note comet: XREFcomet.


File: octave.info,  Node: Axis Configuration,  Next: Two-dimensional Function Plotting,  Up: Two-Dimensional Plots

15.2.1.1 Axis Configuration
...........................

The axis function may be used to change the axis limits of an existing
plot and various other axis properties, such as the aspect ratio and the
appearance of tic marks.  By default, high level plotting functions such
as ‘plot’ reset axes properties.  Any customization of properties, for
example by calling ‘axis’, ‘xlim’, etc., should happen after the plot is
done or, alternatively, after calling the *note hold function: XREFhold.

 -- : axis ()
 -- : axis ([X_LO X_HI])
 -- : axis ([X_LO X_HI Y_LO Y_HI])
 -- : axis ([X_LO X_HI Y_LO Y_HI Z_LO Z_HI])
 -- : axis ([X_LO X_HI Y_LO Y_HI Z_LO Z_HI C_LO C_HI])
 -- : axis (OPTION)
 -- : axis (OPTION1, OPTION2, ...)
 -- : axis (HAX, ...)
 -- : LIMITS = axis ()
     Set axis limits and appearance.

     The argument LIMITS should be a 2-, 4-, 6-, or 8-element vector.
     The first and second elements specify the lower and upper limits
     for the x-axis.  The third and fourth specify the limits for the
     y-axis, the fifth and sixth specify the limits for the z-axis, and
     the seventh and eighth specify the limits for the color axis.  The
     special values -Inf and Inf may be used to indicate that the limit
     should be automatically computed based on the data in the axes.

     Without any arguments, ‘axis’ turns autoscaling on.

     With one output argument, ‘LIMITS = axis’ returns the current axis
     limits.

     The vector argument specifying limits is optional, and additional
     string arguments may be used to specify various axis properties.

     The following options control the aspect ratio of the axes.

     "square"
          Force a square axis aspect ratio.

     "equal"
          Force x-axis unit distance to equal y-axis (and z-axis) unit
          distance.

     "normal"
          Restore default aspect ratio.

     The following options control the way axis limits are interpreted.

     "auto"
     "auto[xyz]"
          Set the specified axes to have nice limits around the data or
          all if no axes are specified.

     "manual"
          Fix the current axes limits.

     "tight"
          Fix axes to the limits of the data.

     "image"
          Equivalent to "tight" and "equal".

     "vis3d"
          Set aspect ratio modes to "manual" for rotation without
          stretching.

     The following options affect the appearance of tick marks.

     "tic[xyz]"
          Turn tick marks on for all axes, or turn them on for the
          specified axes and off for the remainder.

     "label[xyz]"
          Turn tick labels on for all axes, or turn them on for the
          specified axes and off for the remainder.

     "nolabel"
          Turn tick labels off for all axes.

     Note: If there are no tick marks for an axes then there can be no
     labels.

     The following options affect the direction of increasing values on
     the axes.

     "xy"
          Default y-axis, larger values are near the top.

     "ij"
          Reverse y-axis, smaller values are near the top.

     The following options affects the visibility of the axes.

     "on"
          Make the axes visible.

     "off"
          Hide the axes.

     If the first argument HAX is an axes handle, then operate on this
     axes rather than the current axes returned by ‘gca’.

     Example 1: set X/Y limits and force a square aspect ratio

          axis ([1, 2, 3, 4], "square");

     Example 2: enable tick marks on all axes, enable tick mark labels
     only on the y-axis

          axis ("tic", "labely");

     See also: *note xlim: XREFxlim, *note ylim: XREFylim, *note zlim:
     XREFzlim, *note caxis: XREFcaxis, *note daspect: XREFdaspect, *note
     pbaspect: XREFpbaspect, *note box: XREFbox, *note grid: XREFgrid.

   Similarly the axis limits of the colormap can be changed with the
caxis function.

 -- : caxis ([cmin cmax])
 -- : caxis ("auto")
 -- : caxis ("manual")
 -- : caxis (HAX, ...)
 -- : LIMITS = caxis ()
     Query or set color axis limits for plots.

     The limits argument should be a 2-element vector specifying the
     lower and upper limits to assign to the first and last value in the
     colormap.  Data values outside this range are clamped to the first
     and last colormap entries.

     If the "auto" option is given then automatic colormap limits are
     applied.  The automatic algorithm sets CMIN to the minimum data
     value and CMAX to the maximum data value.  If "manual" is specified
     then the "climmode" property is set to "manual" and the numeric
     values in the "clim" property are used for limits.

     If the first argument HAX is an axes handle, then operate on this
     axes rather than the current axes returned by ‘gca’.

     Called without arguments the current color axis limits are
     returned.

     Programming Note: The color axis affects the display of image,
     patch, and surface graphics objects, but *only* if the "cdata"
     property has indexed data and the "cdatamapping" property is set to
     "scaled".  Graphic objects with true color ‘cdata’, or "direct"
     ‘cdatamapping’ are not affected.

     See also: *note colormap: XREFcolormap, *note axis: XREFaxis.

   The ‘xlim’, ‘ylim’, and ‘zlim’ functions may be used to get or set
individual axis limits.  Each has the same form.

 -- : XLIMITS = xlim ()
 -- : XMODE = xlim ("mode")
 -- : xlim ([X_LO X_HI])
 -- : xlim ("auto")
 -- : xlim ("manual")
 -- : xlim (HAX, ...)
     Query or set the limits of the x-axis for the current plot.

     Called without arguments ‘xlim’ returns the x-axis limits of the
     current plot.

     With the input query "mode", return the current x-limit calculation
     mode which is either "auto" or "manual".

     If passed a 2-element vector [X_LO X_HI], the limits of the x-axis
     are set to these values and the mode is set to "manual".  The
     special values -Inf and Inf can be used to indicate that either the
     lower axis limit or upper axis limit should be automatically
     calculated.

     The current plotting mode can be changed by using either "auto" or
     "manual" as the argument.

     If the first argument HAX is an axes handle, then operate on this
     axes rather than the current axes returned by ‘gca’.

     Programming Note: The ‘xlim’ function operates by modifying the
     "xlim" and "xlimmode" properties of an axes object.  These
     properties can be directly inspected and altered with ‘get’/‘set’.

     See also: *note ylim: XREFylim, *note zlim: XREFzlim, *note axis:
     XREFaxis, *note set: XREFset, *note get: XREFget, *note gca:
     XREFgca.

   The ‘xticks’, ‘yticks’, ‘zticks’, ‘rticks’, and ‘thetaticks’
functions may be used to get or set the tick mark locations and modes on
the respective axis.  Each has the same form, although mode options are
not currently available for ‘rticks’, and ‘thetaticks’.

 -- : TICKVAL = xticks
 -- : MODE = xticks ("mode")
 -- : xticks (TICKVAL)
 -- : xticks ("auto")
 -- : xticks ("manual")
 -- : ... = xticks (HAX, ...)
     Query or set the tick values on the x-axis of the current axis.

     When called without an argument, return the current tick locations
     as specified in the "xtick" axes property.  These locations can be
     changed by calling ‘xticks’ with a vector of tick values.  Note:
     ascending order is not required.

     When called with argument "mode", ‘xticks’ returns the current
     value of the axes property "xtickmode".  This property can be
     changed by calling ‘xticks’ with either "auto" (algorithm
     determines tick positions) or "manual" (tick values remain fixed
     regardless of axes resizing or rotation).  Note: Specifying xtick
     values will also set the property "xtickmode" to "manual".

     If the first argument HAX is an axes handle, then operate on this
     axis rather than the current axes returned by ‘gca’.

     Requesting a return value when calling ‘xticks’ to set a property
     value will result in an error.

     See also: *note xticklabels: XREFxticklabels, *note yticks:
     XREFyticks, *note zticks: XREFzticks, *note rticks: XREFrticks,
     *note thetaticks: XREFthetaticks, *note get: XREFget, *note set:
     XREFset.

   The ‘xticklabels’, ‘yticklabels’, and ‘zticklabels’ functions may be
used to get or set the label assigned to each tick location and the
labeling mode on the respective axis.  Each has the same form.

 -- : TICKVAL = xticklabels
 -- : MODE = xticklabels ("mode")
 -- : xticklabels (TICKVAL)
 -- : xticklabels ("auto")
 -- : xticklabels ("manual")
 -- : ... = xticklabels (HAX, ...)
     Query or set the tick labels on the x-axis of the current axis.

     When called without an argument, return a cell array of strings of
     the current tick labels as specified in the "xticklabel" axes
     property.  These labels can be changed by calling ‘xticklabels’
     with a cell array of strings.  Note: a vector of numbers will be
     mapped to a cell array of strings.  If fewer labels are specified
     than the current number of ticks, blank labels will be appended to
     the array.

     When called with argument "mode", ‘xticklabels’ returns the current
     value of the axes property "xticklabelmode".  This property can be
     changed by calling ‘xticklabels’ with either "auto" (algorithm
     determines tick labels) or "manual" (tick labels remain fixed).
     Note: Specifying xticklabel values will also set the
     "xticklabelmode" and "xticks" properties to "manual".

     If the first argument HAX is an axes handle, then operate on this
     axis rather than the current axes returned by ‘gca’.

     Requesting a return value when calling ‘xticklabels’ to set a
     property value will result in an error.

     See also: *note xticks: XREFxticks, *note yticklabels:
     XREFyticklabels, *note zticklabels: XREFzticklabels, *note get:
     XREFget, *note set: XREFset.


File: octave.info,  Node: Two-dimensional Function Plotting,  Next: Two-dimensional Geometric Shapes,  Prev: Axis Configuration,  Up: Two-Dimensional Plots

15.2.1.2 Two-dimensional Function Plotting
..........................................

Octave can plot a function from a function handle, inline function, or
string defining the function without the user needing to explicitly
create the data to be plotted.  The function ‘fplot’ also generates
two-dimensional plots with linear axes using a function name and limits
for the range of the x-coordinate instead of the x and y data.  For
example,

     fplot (@sin, [-10, 10], 201);

produces a plot that is equivalent to the one above, but also includes a
legend displaying the name of the plotted function.

 -- : fplot (FN)
 -- : fplot (FN, LIMITS)
 -- : fplot (..., TOL)
 -- : fplot (..., N)
 -- : fplot (..., FMT)
 -- : fplot (..., PROPERTY, VALUE, ...)
 -- : fplot (HAX, ...)
 -- : [X, Y] = fplot (...)
     Plot a function FN within the range defined by LIMITS.

     FN is a function handle, inline function, or string containing the
     name of the function to evaluate.

     The limits of the plot are of the form ‘[XLO, XHI]’ or
     ‘[XLO, XHI, YLO, YHI]’.  If no limits are specified the default is
     ‘[-5, 5]’.

     The next three arguments are all optional and any number of them
     may be given in any order.

     TOL is the relative tolerance to use for the plot and defaults to
     2e-3 (.2%).

     N is the minimum number of points to use.  When N is specified, the
     maximum stepsize will be ‘(XHI - XLO) / N’.  More than N points may
     still be used in order to meet the relative tolerance requirement.

     The FMT argument specifies the linestyle to be used by the plot
     command.

     Multiple property-value pairs may also be specified, but they must
     appear in pairs.  These arguments are applied to the line objects
     drawn by ‘plot’.

     If the first argument HAX is an axes handle, then plot into this
     axes, rather than the current axes returned by ‘gca’.

     With no output arguments, the results are immediately plotted.
     With two output arguments, the 2-D plot data is returned.  The data
     can subsequently be plotted manually with ‘plot (X, Y)’.

     Example:

          fplot (@cos, [0, 2*pi])
          fplot ("[cos(x), sin(x)]", [0, 2*pi])

     Programming Notes:

     ‘fplot’ works best with continuous functions.  Functions with
     discontinuities are unlikely to plot well.  This restriction may be
     removed in the future.

     ‘fplot’ performance is better when the function accepts and returns
     a vector argument.  Consider this when writing user-defined
     functions and use element-by-element operators such as ‘.*’, ‘./’,
     etc.  See the function ‘vectorize’ for potentially converting
     inline or anonymous functions to vectorized versions.

     See also: *note ezplot: XREFezplot, *note plot: XREFplot, *note
     vectorize: XREFvectorize.

   Other functions that can create two-dimensional plots directly from a
function include ‘ezplot’, ‘ezcontour’, ‘ezcontourf’ and ‘ezpolar’.

 -- : ezplot (F)
 -- : ezplot (F2V)
 -- : ezplot (FX, FY)
 -- : ezplot (..., DOM)
 -- : ezplot (..., N)
 -- : ezplot (HAX, ...)
 -- : H = ezplot (...)

     Plot the 2-D curve defined by the function F.

     The function F may be a string, inline function, or function handle
     and can have either one or two variables.  If F has one variable,
     then the function is plotted over the domain ‘-2*pi < X < 2*pi’
     with 500 points.

     If F2V is a function of two variables then the implicit function
     ‘F(X,Y) = 0’ is calculated over the meshed domain ‘-2*pi <= X | Y
     <= 2*pi’ with 60 points in each dimension.

     For example:

          ezplot (@(X, Y) X.^2 - Y.^2 - 1)

     If two functions are passed as inputs then the parametric function

          X = FX (T)
          Y = FY (T)

     is plotted over the domain ‘-2*pi <= T <= 2*pi’ with 500 points.

     If DOM is a two element vector, it represents the minimum and
     maximum values of both X and Y, or T for a parametric plot.  If DOM
     is a four element vector, then the minimum and maximum values are
     ‘[xmin xmax ymin ymax]’.

     N is a scalar defining the number of points to use in plotting the
     function.

     If the first argument HAX is an axes handle, then plot into this
     axes, rather than the current axes returned by ‘gca’.

     The optional return value H is a vector of graphics handles to the
     created line objects.

     See also: *note plot: XREFplot, *note ezplot3: XREFezplot3, *note
     ezpolar: XREFezpolar, *note ezcontour: XREFezcontour, *note
     ezcontourf: XREFezcontourf, *note ezmesh: XREFezmesh, *note
     ezmeshc: XREFezmeshc, *note ezsurf: XREFezsurf, *note ezsurfc:
     XREFezsurfc.

 -- : ezcontour (F)
 -- : ezcontour (..., DOM)
 -- : ezcontour (..., N)
 -- : ezcontour (HAX, ...)
 -- : H = ezcontour (...)

     Plot the contour lines of a function.

     F is a string, inline function, or function handle with two
     arguments defining the function.  By default the plot is over the
     meshed domain ‘-2*pi <= X | Y <= 2*pi’ with 60 points in each
     dimension.

     If DOM is a two element vector, it represents the minimum and
     maximum values of both X and Y.  If DOM is a four element vector,
     then the minimum and maximum values are ‘[xmin xmax ymin ymax]’.

     N is a scalar defining the number of points to use in each
     dimension.

     If the first argument HAX is an axes handle, then plot into this
     axes, rather than the current axes returned by ‘gca’.

     The optional return value H is a graphics handle to the created
     plot.

     Example:

          f = @(x,y) sqrt (abs (x .* y)) ./ (1 + x.^2 + y.^2);
          ezcontour (f, [-3, 3]);

     See also: *note contour: XREFcontour, *note ezcontourf:
     XREFezcontourf, *note ezplot: XREFezplot, *note ezmeshc:
     XREFezmeshc, *note ezsurfc: XREFezsurfc.

 -- : ezcontourf (F)
 -- : ezcontourf (..., DOM)
 -- : ezcontourf (..., N)
 -- : ezcontourf (HAX, ...)
 -- : H = ezcontourf (...)

     Plot the filled contour lines of a function.

     F is a string, inline function, or function handle with two
     arguments defining the function.  By default the plot is over the
     meshed domain ‘-2*pi <= X | Y <= 2*pi’ with 60 points in each
     dimension.

     If DOM is a two element vector, it represents the minimum and
     maximum values of both X and Y.  If DOM is a four element vector,
     then the minimum and maximum values are ‘[xmin xmax ymin ymax]’.

     N is a scalar defining the number of points to use in each
     dimension.

     If the first argument HAX is an axes handle, then plot into this
     axes, rather than the current axes returned by ‘gca’.

     The optional return value H is a graphics handle to the created
     plot.

     Example:

          f = @(x,y) sqrt (abs (x .* y)) ./ (1 + x.^2 + y.^2);
          ezcontourf (f, [-3, 3]);

     See also: *note contourf: XREFcontourf, *note ezcontour:
     XREFezcontour, *note ezplot: XREFezplot, *note ezmeshc:
     XREFezmeshc, *note ezsurfc: XREFezsurfc.

 -- : ezpolar (F)
 -- : ezpolar (..., DOM)
 -- : ezpolar (..., N)
 -- : ezpolar (HAX, ...)
 -- : H = ezpolar (...)

     Plot a 2-D function in polar coordinates.

     The function F is a string, inline function, or function handle
     with a single argument.  The expected form of the function is ‘RHO
     = F(THETA)’.  By default the plot is over the domain ‘0 <= THETA <=
     2*pi’ with 500 points.

     If DOM is a two element vector, it represents the minimum and
     maximum values of THETA.

     N is a scalar defining the number of points to use in plotting the
     function.

     If the first argument HAX is an axes handle, then plot into this
     axes, rather than the current axes returned by ‘gca’.

     The optional return value H is a graphics handle to the created
     plot.

     Example:

          ezpolar (@(t) sin (5/4 * t), [0, 8*pi]);

     See also: *note polar: XREFpolar, *note ezplot: XREFezplot.


File: octave.info,  Node: Two-dimensional Geometric Shapes,  Prev: Two-dimensional Function Plotting,  Up: Two-Dimensional Plots

15.2.1.3 Two-dimensional Geometric Shapes
.........................................

 -- : rectangle ()
 -- : rectangle (..., "Position", POS)
 -- : rectangle (..., "Curvature", CURV)
 -- : rectangle (..., "EdgeColor", EC)
 -- : rectangle (..., "FaceColor", FC)
 -- : rectangle (HAX, ...)
 -- : H = rectangle (...)
     Draw a rectangular patch defined by POS and CURV.

     The variable ‘POS(1:2)’ defines the lower left-hand corner of the
     patch and ‘POS(3:4)’ defines its width and height.  By default, the
     value of POS is ‘[0, 0, 1, 1]’.

     The variable CURV defines the curvature of the sides of the
     rectangle and may be a scalar or two-element vector with values
     between 0 and 1.  A value of 0 represents no curvature of the side,
     whereas a value of 1 means that the side is entirely curved into
     the arc of a circle.  If CURV is a two-element vector, then the
     first element is the curvature along the x-axis of the patch and
     the second along y-axis.

     If CURV is a scalar, it represents the curvature of the shorter of
     the two sides of the rectangle and the curvature of the other side
     is defined by

          min (pos(1:2)) / max (pos(1:2)) * curv

     Additional property/value pairs are passed to the underlying patch
     command.

     If the first argument HAX is an axes handle, then plot into this
     axes, rather than the current axes returned by ‘gca’.

     The optional return value H is a graphics handle to the created
     rectangle object.

     See also: *note patch: XREFpatch, *note line: XREFline, *note
     cylinder: XREFcylinder, *note ellipsoid: XREFellipsoid, *note
     sphere: XREFsphere.


File: octave.info,  Node: Three-Dimensional Plots,  Next: Plot Annotations,  Prev: Two-Dimensional Plots,  Up: High-Level Plotting

15.2.2 Three-Dimensional Plots
------------------------------

The function ‘mesh’ produces mesh surface plots.  For example,

     tx = ty = linspace (-8, 8, 41)';
     [xx, yy] = meshgrid (tx, ty);
     r = sqrt (xx .^ 2 + yy .^ 2) + eps;
     tz = sin (r) ./ r;
     mesh (tx, ty, tz);
     xlabel ("tx");
     ylabel ("ty");
     zlabel ("tz");
     title ("3-D Sombrero plot");

produces the familiar “sombrero” plot shown in *note Figure 15.5:
fig:mesh.  Note the use of the function ‘meshgrid’ to create matrices of
X and Y coordinates to use for plotting the Z data.  The ‘ndgrid’
function is similar to ‘meshgrid’, but works for N-dimensional matrices.

                 
                 +---------------------------------+
                 | Image unavailable in text mode. |
                 +---------------------------------+

Figure 15.5: Mesh plot.

   The ‘meshc’ function is similar to ‘mesh’, but also produces a plot
of contours for the surface.

   The ‘plot3’ function displays arbitrary three-dimensional data,
without requiring it to form a surface.  For example,

     t = 0:0.1:10*pi;
     r = linspace (0, 1, numel (t));
     z = linspace (0, 1, numel (t));
     plot3 (r.*sin (t), r.*cos (t), z);
     xlabel ("r.*sin (t)");
     ylabel ("r.*cos (t)");
     zlabel ("z");
     title ("plot3 display of 3-D helix");

displays the spiral in three dimensions shown in *note Figure 15.6:
fig:plot3.

                 
                 +---------------------------------+
                 | Image unavailable in text mode. |
                 +---------------------------------+

Figure 15.6: Three-dimensional spiral.

   Finally, the ‘view’ function changes the viewpoint for
three-dimensional plots.

 -- : mesh (X, Y, Z)
 -- : mesh (Z)
 -- : mesh (..., C)
 -- : mesh (..., PROP, VAL, ...)
 -- : mesh (HAX, ...)
 -- : H = mesh (...)
     Plot a 3-D wireframe mesh.

     The wireframe mesh is plotted using rectangles.  The vertices of
     the rectangles [X, Y] are typically the output of ‘meshgrid’.  over
     a 2-D rectangular region in the x-y plane.  Z determines the height
     above the plane of each vertex.  If only a single Z matrix is
     given, then it is plotted over the meshgrid ‘X = 1:columns (Z), Y =
     1:rows (Z)’.  Thus, columns of Z correspond to different X values
     and rows of Z correspond to different Y values.

     The color of the mesh is computed by linearly scaling the Z values
     to fit the range of the current colormap.  Use ‘caxis’ and/or
     change the colormap to control the appearance.

     Optionally, the color of the mesh can be specified independently of
     Z by supplying a color matrix, C.

     Any property/value pairs are passed directly to the underlying
     surface object.

     If the first argument HAX is an axes handle, then plot into this
     axes, rather than the current axes returned by ‘gca’.

     The optional return value H is a graphics handle to the created
     surface object.

     See also: *note ezmesh: XREFezmesh, *note meshc: XREFmeshc, *note
     meshz: XREFmeshz, *note trimesh: XREFtrimesh, *note contour:
     XREFcontour, *note surf: XREFsurf, *note surface: XREFsurface,
     *note meshgrid: XREFmeshgrid, *note hidden: XREFhidden, *note
     shading: XREFshading, *note colormap: XREFcolormap, *note caxis:
     XREFcaxis.

 -- : meshc (X, Y, Z)
 -- : meshc (Z)
 -- : meshc (..., C)
 -- : meshc (..., PROP, VAL, ...)
 -- : meshc (HAX, ...)
 -- : H = meshc (...)
     Plot a 3-D wireframe mesh with underlying contour lines.

     The wireframe mesh is plotted using rectangles.  The vertices of
     the rectangles [X, Y] are typically the output of ‘meshgrid’.  over
     a 2-D rectangular region in the x-y plane.  Z determines the height
     above the plane of each vertex.  If only a single Z matrix is
     given, then it is plotted over the meshgrid ‘X = 1:columns (Z), Y =
     1:rows (Z)’.  Thus, columns of Z correspond to different X values
     and rows of Z correspond to different Y values.

     The color of the mesh is computed by linearly scaling the Z values
     to fit the range of the current colormap.  Use ‘caxis’ and/or
     change the colormap to control the appearance.

     Optionally the color of the mesh can be specified independently of
     Z by supplying a color matrix, C.

     Any property/value pairs are passed directly to the underlying
     surface object.

     If the first argument HAX is an axes handle, then plot into this
     axes, rather than the current axes returned by ‘gca’.

     The optional return value H is a 2-element vector with a graphics
     handle to the created surface object and to the created contour
     plot.

     See also: *note ezmeshc: XREFezmeshc, *note mesh: XREFmesh, *note
     meshz: XREFmeshz, *note contour: XREFcontour, *note surfc:
     XREFsurfc, *note surface: XREFsurface, *note meshgrid:
     XREFmeshgrid, *note hidden: XREFhidden, *note shading: XREFshading,
     *note colormap: XREFcolormap, *note caxis: XREFcaxis.

 -- : meshz (X, Y, Z)
 -- : meshz (Z)
 -- : meshz (..., C)
 -- : meshz (..., PROP, VAL, ...)
 -- : meshz (HAX, ...)
 -- : H = meshz (...)
     Plot a 3-D wireframe mesh with a surrounding curtain.

     The wireframe mesh is plotted using rectangles.  The vertices of
     the rectangles [X, Y] are typically the output of ‘meshgrid’.  over
     a 2-D rectangular region in the x-y plane.  Z determines the height
     above the plane of each vertex.  If only a single Z matrix is
     given, then it is plotted over the meshgrid ‘X = 1:columns (Z), Y =
     1:rows (Z)’.  Thus, columns of Z correspond to different X values
     and rows of Z correspond to different Y values.

     The color of the mesh is computed by linearly scaling the Z values
     to fit the range of the current colormap.  Use ‘caxis’ and/or
     change the colormap to control the appearance.

     Optionally the color of the mesh can be specified independently of
     Z by supplying a color matrix, C.

     Any property/value pairs are passed directly to the underlying
     surface object.

     If the first argument HAX is an axes handle, then plot into this
     axes, rather than the current axes returned by ‘gca’.

     The optional return value H is a graphics handle to the created
     surface object.

     See also: *note mesh: XREFmesh, *note meshc: XREFmeshc, *note
     contour: XREFcontour, *note surf: XREFsurf, *note surface:
     XREFsurface, *note waterfall: XREFwaterfall, *note meshgrid:
     XREFmeshgrid, *note hidden: XREFhidden, *note shading: XREFshading,
     *note colormap: XREFcolormap, *note caxis: XREFcaxis.

 -- : hidden
 -- : hidden on
 -- : hidden off
 -- : MODE = hidden (...)
     Control mesh hidden line removal.

     When called with no argument the hidden line removal state is
     toggled.

     When called with one of the modes "on" or "off" the state is set
     accordingly.

     The optional output argument MODE is the current state.

     Hidden Line Removal determines what graphic objects behind a mesh
     plot are visible.  The default is for the mesh to be opaque and
     lines behind the mesh are not visible.  If hidden line removal is
     turned off then objects behind the mesh can be seen through the
     faces (openings) of the mesh, although the mesh grid lines are
     still opaque.

     See also: *note mesh: XREFmesh, *note meshc: XREFmeshc, *note
     meshz: XREFmeshz, *note ezmesh: XREFezmesh, *note ezmeshc:
     XREFezmeshc, *note trimesh: XREFtrimesh, *note waterfall:
     XREFwaterfall.

 -- : surf (X, Y, Z)
 -- : surf (Z)
 -- : surf (..., C)
 -- : surf (..., PROP, VAL, ...)
 -- : surf (HAX, ...)
 -- : H = surf (...)
     Plot a 3-D surface mesh.

     The surface mesh is plotted using shaded rectangles.  The vertices
     of the rectangles [X, Y] are typically the output of ‘meshgrid’.
     over a 2-D rectangular region in the x-y plane.  Z determines the
     height above the plane of each vertex.  If only a single Z matrix
     is given, then it is plotted over the meshgrid ‘X = 1:columns (Z),
     Y = 1:rows (Z)’.  Thus, columns of Z correspond to different X
     values and rows of Z correspond to different Y values.

     The color of the surface is computed by linearly scaling the Z
     values to fit the range of the current colormap.  Use ‘caxis’
     and/or change the colormap to control the appearance.

     Optionally, the color of the surface can be specified independently
     of Z by supplying a color matrix, C.

     Any property/value pairs are passed directly to the underlying
     surface object.

     If the first argument HAX is an axes handle, then plot into this
     axes, rather than the current axes returned by ‘gca’.

     The optional return value H is a graphics handle to the created
     surface object.

     Note: The exact appearance of the surface can be controlled with
     the ‘shading’ command or by using ‘set’ to control surface object
     properties.

     See also: *note ezsurf: XREFezsurf, *note surfc: XREFsurfc, *note
     surfl: XREFsurfl, *note surfnorm: XREFsurfnorm, *note trisurf:
     XREFtrisurf, *note contour: XREFcontour, *note mesh: XREFmesh,
     *note surface: XREFsurface, *note meshgrid: XREFmeshgrid, *note
     hidden: XREFhidden, *note shading: XREFshading, *note colormap:
     XREFcolormap, *note caxis: XREFcaxis.

 -- : surfc (X, Y, Z)
 -- : surfc (Z)
 -- : surfc (..., C)
 -- : surfc (..., PROP, VAL, ...)
 -- : surfc (HAX, ...)
 -- : H = surfc (...)
     Plot a 3-D surface mesh with underlying contour lines.

     The surface mesh is plotted using shaded rectangles.  The vertices
     of the rectangles [X, Y] are typically the output of ‘meshgrid’.
     over a 2-D rectangular region in the x-y plane.  Z determines the
     height above the plane of each vertex.  If only a single Z matrix
     is given, then it is plotted over the meshgrid ‘X = 1:columns (Z),
     Y = 1:rows (Z)’.  Thus, columns of Z correspond to different X
     values and rows of Z correspond to different Y values.

     The color of the surface is computed by linearly scaling the Z
     values to fit the range of the current colormap.  Use ‘caxis’
     and/or change the colormap to control the appearance.

     Optionally, the color of the surface can be specified independently
     of Z by supplying a color matrix, C.

     Any property/value pairs are passed directly to the underlying
     surface object.

     If the first argument HAX is an axes handle, then plot into this
     axes, rather than the current axes returned by ‘gca’.

     The optional return value H is a graphics handle to the created
     surface object.

     Note: The exact appearance of the surface can be controlled with
     the ‘shading’ command or by using ‘set’ to control surface object
     properties.

     See also: *note ezsurfc: XREFezsurfc, *note surf: XREFsurf, *note
     surfl: XREFsurfl, *note surfnorm: XREFsurfnorm, *note trisurf:
     XREFtrisurf, *note contour: XREFcontour, *note mesh: XREFmesh,
     *note surface: XREFsurface, *note meshgrid: XREFmeshgrid, *note
     hidden: XREFhidden, *note shading: XREFshading, *note colormap:
     XREFcolormap, *note caxis: XREFcaxis.

 -- : surfl (Z)
 -- : surfl (X, Y, Z)
 -- : surfl (..., LSRC)
 -- : surfl (X, Y, Z, LSRC, P)
 -- : surfl (..., "cdata")
 -- : surfl (..., "light")
 -- : surfl (HAX, ...)
 -- : H = surfl (...)
     Plot a 3-D surface using shading based on various lighting models.

     The surface mesh is plotted using shaded rectangles.  The vertices
     of the rectangles [X, Y] are typically the output of ‘meshgrid’.
     over a 2-D rectangular region in the x-y plane.  Z determines the
     height above the plane of each vertex.  If only a single Z matrix
     is given, then it is plotted over the meshgrid ‘X = 1:columns (Z),
     Y = 1:rows (Z)’.  Thus, columns of Z correspond to different X
     values and rows of Z correspond to different Y values.

     The default lighting mode "cdata", changes the cdata property of
     the surface object to give the impression of a lighted surface.

     The alternate mode "light" creates a light object to illuminate the
     surface.

     The light source location may be specified using LSRC which can be
     a 2-element vector [azimuth, elevation] in degrees, or a 3-element
     vector [lx, ly, lz].  The default value is rotated 45 degrees
     counterclockwise to the current view.

     The material properties of the surface can specified using a
     4-element vector P = [AM D SP EXP] which defaults to P = [0.55 0.6
     0.4 10].

     "AM" strength of ambient light

     "D" strength of diffuse reflection

     "SP" strength of specular reflection

     "EXP" specular exponent

     If the first argument HAX is an axes handle, then plot into this
     axes, rather than the current axes returned by ‘gca’.

     The optional return value H is a graphics handle to the created
     surface object.

     Example:

          colormap (bone (64));
          surfl (peaks);
          shading interp;

     See also: *note diffuse: XREFdiffuse, *note specular: XREFspecular,
     *note surf: XREFsurf, *note shading: XREFshading, *note colormap:
     XREFcolormap, *note caxis: XREFcaxis.

 -- : surfnorm (X, Y, Z)
 -- : surfnorm (Z)
 -- : surfnorm (..., PROP, VAL, ...)
 -- : surfnorm (HAX, ...)
 -- : [NX, NY, NZ] = surfnorm (...)
     Find the vectors normal to a meshgridded surface.

     If X and Y are vectors, then a typical vertex is (X(j), Y(i),
     Z(i,j)).  Thus, columns of Z correspond to different X values and
     rows of Z correspond to different Y values.  If only a single input
     Z is given then X is taken to be ‘1:columns (Z)’ and Y is ‘1:rows
     (Z)’.

     If no return arguments are requested, a surface plot with the
     normal vectors to the surface is plotted.

     Any property/value input pairs are assigned to the surface object.

     If the first argument HAX is an axes handle, then plot into this
     axes, rather than the current axes returned by ‘gca’.

     If output arguments are requested then the components of the normal
     vectors are returned in NX, NY, and NZ and no plot is made.  The
     normal vectors are unnormalized (magnitude != 1).  To normalize,
     use

          len = sqrt (nx.^2 + ny.^2 + nz.^2);
          nx ./= len;  ny ./= len;  nz ./= len;

     An example of the use of ‘surfnorm’ is

          surfnorm (peaks (25));

     Algorithm: The normal vectors are calculated by taking the cross
     product of the diagonals of each of the quadrilateral faces in the
     meshgrid to find the normal vectors at the center of each face.
     Next, for each meshgrid point the four nearest normal vectors are
     averaged to obtain the final normal to the surface at the meshgrid
     point.

     For surface objects, the "VertexNormals" property contains
     equivalent information, except possibly near the boundary of the
     surface where different interpolation schemes may yield slightly
     different values.

     See also: *note isonormals: XREFisonormals, *note quiver3:
     XREFquiver3, *note surf: XREFsurf, *note meshgrid: XREFmeshgrid.

 -- : FV = isosurface (V, ISOVAL)
 -- : FV = isosurface (V)
 -- : FV = isosurface (X, Y, Z, V, ISOVAL)
 -- : FV = isosurface (X, Y, Z, V)
 -- : FVC = isosurface (..., COL)
 -- : FV = isosurface (..., "noshare")
 -- : FV = isosurface (..., "verbose")
 -- : [F, V] = isosurface (...)
 -- : [F, V, C] = isosurface (...)
 -- : isosurface (...)

     Calculate isosurface of 3-D volume data.

     An isosurface connects points with the same value and is analogous
     to a contour plot, but in three dimensions.

     The input argument V is a three-dimensional array that contains
     data sampled over a volume.

     The input ISOVAL is a scalar that specifies the value for the
     isosurface.  If ISOVAL is omitted or empty, a "good" value for an
     isosurface is determined from V.

     When called with a single output argument ‘isosurface’ returns a
     structure array FV that contains the fields FACES and VERTICES
     computed at the points ‘[X, Y, Z] = meshgrid (1:l, 1:m, 1:n)’ where
     ‘[l, m, n] = size (V)’.  The output FV can be used directly as
     input to the ‘patch’ function.

     If called with additional input arguments X, Y, and Z that are
     three-dimensional arrays with the same size as V or vectors with
     lengths corresponding to the dimensions of V, then the volume data
     is taken at the specified points.  If X, Y, or Z are empty, the
     grid corresponds to the indices (‘1:n’) in the respective direction
     (*note meshgrid: XREFmeshgrid.).

     The optional input argument COL, which is a three-dimensional array
     of the same size as V, specifies coloring of the isosurface.  The
     color data is interpolated, as necessary, to match ISOVAL.  The
     output structure array, in this case, has the additional field
     FACEVERTEXCDATA.

     If given the string input argument "noshare", vertices may be
     returned multiple times for different faces.  The default behavior
     is to eliminate vertices shared by adjacent faces with ‘unique’
     which may be time consuming.

     The string input argument "verbose" is supported for MATLAB
     compatibility, but has no effect.

     Any string arguments must be passed after the other arguments.

     If called with two or three output arguments, return the
     information about the faces F, vertices V, and color data C as
     separate arrays instead of a single structure array.

     If called with no output argument, the isosurface geometry is
     directly plotted with the ‘patch’ command and a light object is
     added to the axes if not yet present.

     For example,

          [x, y, z] = meshgrid (1:5, 1:5, 1:5);
          v = rand (5, 5, 5);
          isosurface (x, y, z, v, .5);

     will directly draw a random isosurface geometry in a graphics
     window.

     An example of an isosurface geometry with different additional
     coloring:

          N = 15;    # Increase number of vertices in each direction
          iso = .4;  # Change isovalue to .1 to display a sphere
          lin = linspace (0, 2, N);
          [x, y, z] = meshgrid (lin, lin, lin);
          v = abs ((x-.5).^2 + (y-.5).^2 + (z-.5).^2);
          figure ();

          subplot (2,2,1); view (-38, 20);
          [f, vert] = isosurface (x, y, z, v, iso);
          p = patch ("Faces", f, "Vertices", vert, "EdgeColor", "none");
          pbaspect ([1 1 1]);
          isonormals (x, y, z, v, p)
          set (p, "FaceColor", "green", "FaceLighting", "gouraud");
          light ("Position", [1 1 5]);

          subplot (2,2,2); view (-38, 20);
          p = patch ("Faces", f, "Vertices", vert, "EdgeColor", "blue");
          pbaspect ([1 1 1]);
          isonormals (x, y, z, v, p)
          set (p, "FaceColor", "none", "EdgeLighting", "gouraud");
          light ("Position", [1 1 5]);

          subplot (2,2,3); view (-38, 20);
          [f, vert, c] = isosurface (x, y, z, v, iso, y);
          p = patch ("Faces", f, "Vertices", vert, "FaceVertexCData", c, ...
                     "FaceColor", "interp", "EdgeColor", "none");
          pbaspect ([1 1 1]);
          isonormals (x, y, z, v, p)
          set (p, "FaceLighting", "gouraud");
          light ("Position", [1 1 5]);

          subplot (2,2,4); view (-38, 20);
          p = patch ("Faces", f, "Vertices", vert, "FaceVertexCData", c, ...
                     "FaceColor", "interp", "EdgeColor", "blue");
          pbaspect ([1 1 1]);
          isonormals (x, y, z, v, p)
          set (p, "FaceLighting", "gouraud");
          light ("Position", [1 1 5]);

     See also: *note isonormals: XREFisonormals, *note isocolors:
     XREFisocolors, *note isocaps: XREFisocaps, *note smooth3:
     XREFsmooth3, *note reducevolume: XREFreducevolume, *note
     reducepatch: XREFreducepatch, *note patch: XREFpatch.

 -- : VN = isonormals (VAL, VERT)
 -- : VN = isonormals (VAL, HP)
 -- : VN = isonormals (X, Y, Z, VAL, VERT)
 -- : VN = isonormals (X, Y, Z, VAL, HP)
 -- : VN = isonormals (..., "negate")
 -- : isonormals (VAL, HP)
 -- : isonormals (X, Y, Z, VAL, HP)
 -- : isonormals (..., "negate")

     Calculate normals to an isosurface.

     The vertex normals VN are calculated from the gradient of the
     3-dimensional array VAL (size: lxmxn) containing the data for an
     isosurface geometry.  The normals point towards smaller values in
     VAL.

     If called with one output argument VN, and the second input
     argument VERT holds the vertices of an isosurface, then the normals
     VN are calculated at the vertices VERT on a grid given by ‘[x, y,
     z] = meshgrid (1:l, 1:m, 1:n)’.  The output argument VN has the
     same size as VERT and can be used to set the "VertexNormals"
     property of the corresponding patch.

     If called with additional input arguments X, Y, and Z, which are
     3-dimensional arrays with the same size as VAL, then the volume
     data is taken at these points.  Instead of the vertex data VERT, a
     patch handle HP can be passed to the function.

     If the last input argument is the string "negate", compute the
     reverse vector normals of an isosurface geometry (i.e., pointed
     towards larger values in VAL).

     If no output argument is given, the property "VertexNormals" of the
     patch associated with the patch handle HP is changed directly.

     See also: *note isosurface: XREFisosurface, *note isocolors:
     XREFisocolors, *note smooth3: XREFsmooth3.

 -- : FVC = isocaps (V, ISOVAL)
 -- : FVC = isocaps (V)
 -- : FVC = isocaps (X, Y, Z, V, ISOVAL)
 -- : FVC = isocaps (X, Y, Z, V)
 -- : FVC = isocaps (..., WHICH_CAPS)
 -- : FVC = isocaps (..., WHICH_PLANE)
 -- : FVC = isocaps (..., "verbose")
 -- : [FACES, VERTICES, FVCDATA] = isocaps (...)
 -- : isocaps (...)

     Create end-caps for isosurfaces of 3-D data.

     This function places caps at the open ends of isosurfaces.

     The input argument V is a three-dimensional array that contains
     data sampled over a volume.

     The input ISOVAL is a scalar that specifies the value for the
     isosurface.  If ISOVAL is omitted or empty, a "good" value for an
     isosurface is determined from V.

     When called with a single output argument, ‘isocaps’ returns a
     structure array FVC with the fields: ‘faces’, ‘vertices’, and
     ‘facevertexcdata’.  The results are computed at the points ‘[X, Y,
     Z] = meshgrid (1:l, 1:m, 1:n)’ where ‘[l, m, n] = size (V)’.  The
     output FVC can be used directly as input to the ‘patch’ function.

     If called with additional input arguments X, Y, and Z that are
     three-dimensional arrays with the same size as V or vectors with
     lengths corresponding to the dimensions of V, then the volume data
     is taken at the specified points.  If X, Y, or Z are empty, the
     grid corresponds to the indices (‘1:n’) in the respective direction
     (*note meshgrid: XREFmeshgrid.).

     The optional parameter WHICH_CAPS can have one of the following
     string values which defines how the data will be enclosed:

     "above", "a" (default)
          for end-caps that enclose the data above ISOVAL.

     "below", "b"
          for end-caps that enclose the data below ISOVAL.

     The optional parameter WHICH_PLANE can have one of the following
     string values to define which end-cap should be drawn:

     "all" (default)
          for all of the end-caps.

     "xmin"
          for end-caps at the lower x-plane of the data.

     "xmax"
          for end-caps at the upper x-plane of the data.

     "ymin"
          for end-caps at the lower y-plane of the data.

     "ymax"
          for end-caps at the upper y-plane of the data.

     "zmin"
          for end-caps at the lower z-plane of the data.

     "zmax"
          for end-caps at the upper z-plane of the data.

     The string input argument "verbose" is supported for MATLAB
     compatibility, but has no effect.

     If called with two or three output arguments, the data for faces
     FACES, vertices VERTICES, and the color data FACEVERTEXCDATA are
     returned in separate arrays instead of a single structure.

     If called with no output argument, the end-caps are drawn directly
     in the current figure with the ‘patch’ command.

     See also: *note isosurface: XREFisosurface, *note isonormals:
     XREFisonormals, *note patch: XREFpatch.

 -- : CDAT = isocolors (C, V)
 -- : CDAT = isocolors (X, Y, Z, C, V)
 -- : CDAT = isocolors (X, Y, Z, R, G, B, V)
 -- : CDAT = isocolors (R, G, B, V)
 -- : CDAT = isocolors (..., P)
 -- : isocolors (...)

     Compute isosurface colors.

     If called with one output argument, and the first input argument C
     is a three-dimensional array that contains indexed color values,
     and the second input argument V are the vertices of an isosurface
     geometry, then return a matrix CDAT with color data information for
     the geometry at computed points ‘[x, y, z] = meshgrid (1:l, 1:m,
     1:n)’.  The output argument CDAT can be used to manually set the
     "FaceVertexCData" property of an isosurface patch object.

     If called with additional input arguments X, Y and Z which are
     three-dimensional arrays of the same size as C then the color data
     is taken at those specified points.

     Instead of indexed color data C, ‘isocolors’ can also be called
     with RGB values R, G, B.  If input arguments X, Y, Z are not given
     then ‘meshgrid’ computed values are used.

     Optionally, a patch handle P can be given as the last input
     argument to all function call variations and the vertex data will
     be extracted from the isosurface patch object.  Finally, if no
     output argument is given then the colors of the patch given by the
     patch handle P are changed.

     See also: *note isosurface: XREFisosurface, *note isonormals:
     XREFisonormals.

 -- : SMOOTHED_DATA = smooth3 (DATA)
 -- : SMOOTHED_DATA = smooth3 (DATA, METHOD)
 -- : SMOOTHED_DATA = smooth3 (DATA, METHOD, SZ)
 -- : SMOOTHED_DATA = smooth3 (DATA, METHOD, SZ, STD_DEV)
     Smooth values of 3-dimensional matrix DATA.

     This function can be used, for example, to reduce the impact of
     noise in DATA before calculating isosurfaces.

     DATA must be a non-singleton 3-dimensional matrix.  The smoothed
     data from this matrix is returned in SMOOTHED_DATA which is of the
     same size as DATA.

     The option input METHOD determines which convolution kernel is used
     for the smoothing process.  Possible choices:

     "box", "b" (default)
          to use a convolution kernel with sharp edges.

     "gaussian", "g"
          to use a convolution kernel that is represented by a
          non-correlated trivariate normal distribution function.

     SZ is either a vector of 3 elements representing the size of the
     convolution kernel in x-, y- and z-direction or a scalar, in which
     case the same size is used in all three dimensions.  The default
     value is 3.

     When METHOD is "gaussian", STD_DEV defines the standard deviation
     of the trivariate normal distribution function.  STD_DEV is either
     a vector of 3 elements representing the standard deviation of the
     Gaussian convolution kernel in x-, y- and z-directions or a scalar,
     in which case the same value is used in all three dimensions.  The
     default value is 0.65.

     See also: *note isosurface: XREFisosurface, *note isonormals:
     XREFisonormals, *note patch: XREFpatch.

 -- : [NX, NY, NZ, NV] = reducevolume (V, R)
 -- : [NX, NY, NZ, NV] = reducevolume (X, Y, Z, V, R)
 -- : NV = reducevolume (...)

     Reduce the volume of the dataset in V according to the values in R.

     V is a matrix that is non-singleton in the first 3 dimensions.

     R can either be a vector of 3 elements representing the reduction
     factors in the x-, y-, and z-directions or a scalar, in which case
     the same reduction factor is used in all three dimensions.

     ‘reducevolume’ reduces the number of elements of V by taking only
     every R-th element in the respective dimension.

     Optionally, X, Y, and Z can be supplied to represent the set of
     coordinates of V.  They can either be matrices of the same size as
     V or vectors with sizes according to the dimensions of V, in which
     case they are expanded to matrices (*note meshgrid: XREFmeshgrid.).

     If ‘reducevolume’ is called with two arguments then X, Y, and Z are
     assumed to match the respective indices of V.

     The reduced matrix is returned in NV.

     Optionally, the reduced set of coordinates are returned in NX, NY,
     and NZ, respectively.

     Examples:

          V = reshape (1:6*8*4, [6 8 4]);
          NV = reducevolume (V, [4 3 2]);

          V = reshape (1:6*8*4, [6 8 4]);
          X = 1:3:24;  Y = -14:5:11;  Z = linspace (16, 18, 4);
          [NX, NY, NZ, NV] = reducevolume (X, Y, Z, V, [4 3 2]);

     See also: *note isosurface: XREFisosurface, *note isonormals:
     XREFisonormals.

 -- : REDUCED_FV = reducepatch (FV)
 -- : REDUCED_FV = reducepatch (FACES, VERTICES)
 -- : REDUCED_FV = reducepatch (PATCH_HANDLE)
 -- : reducepatch (PATCH_HANDLE)
 -- : REDUCED_FV = reducepatch (..., REDUCTION_FACTOR)
 -- : REDUCED_FV = reducepatch (..., "fast")
 -- : REDUCED_FV = reducepatch (..., "verbose")
 -- : [REDUCED_FACES, REDUCES_VERTICES] = reducepatch (...)

     Reduce the number of faces and vertices in a patch object while
     retaining the overall shape of the patch.

     The input patch can be represented by a structure FV with the
     fields ‘faces’ and ‘vertices’, by two matrices FACES and VERTICES
     (see, e.g., the result of ‘isosurface’), or by a handle to a patch
     object PATCH_HANDLE (*note patch: XREFpatch.).

     The number of faces and vertices in the patch is reduced by
     iteratively collapsing the shortest edge of the patch to its
     midpoint (as discussed, e.g., here:
     <https://libigl.github.io/libigl/tutorial/tutorial.html#meshdecimation>).

     Currently, only patches consisting of triangles are supported.  The
     resulting patch also consists only of triangles.

     If ‘reducepatch’ is called with a handle to a valid patch
     PATCH_HANDLE, and without any output arguments, then the given
     patch is updated immediately.

     If the REDUCTION_FACTOR is omitted, the resulting structure
     REDUCED_FV includes approximately 50% of the faces of the original
     patch.  If REDUCTION_FACTOR is a fraction between 0 (excluded) and
     1 (excluded), a patch with approximately the corresponding fraction
     of faces is determined.  If REDUCTION_FACTOR is an integer greater
     than or equal to 1, the resulting patch has approximately
     REDUCTION_FACTOR faces.  Depending on the geometry of the patch,
     the resulting number of faces can differ from the given value of
     REDUCTION_FACTOR.  This is especially true when many shared
     vertices are detected.

     For the reduction, it is necessary that vertices of touching faces
     are shared.  Shared vertices are detected automatically.  This
     detection can be skipped by passing the optional string argument
     "fast".

     With the optional string arguments "verbose", additional status
     messages are printed to the command window.

     Any string input arguments must be passed after all other
     arguments.

     If called with one output argument, the reduced faces and vertices
     are returned in a structure REDUCED_FV with the fields ‘faces’ and
     ‘vertices’ (see the one output option of ‘isosurface’).

     If called with two output arguments, the reduced faces and vertices
     are returned in two separate matrices REDUCED_FACES and
     REDUCED_VERTICES.

     See also: *note isosurface: XREFisosurface, *note isonormals:
     XREFisonormals, *note reducevolume: XREFreducevolume, *note patch:
     XREFpatch.

 -- : shrinkfaces (P, SF)
 -- : NFV = shrinkfaces (P, SF)
 -- : NFV = shrinkfaces (FV, SF)
 -- : NFV = shrinkfaces (F, V, SF)
 -- : [NF, NV] = shrinkfaces (...)

     Reduce the size of faces in a patch by the shrink factor SF.

     The patch object can be specified by a graphics handle (P), a patch
     structure (FV) with the fields "faces" and "vertices", or as two
     separate matrices (F, V) of faces and vertices.

     The shrink factor SF is a positive number specifying the percentage
     of the original area the new face will occupy.  If no factor is
     given the default is 0.3 (a reduction to 30% of the original size).
     A factor greater than 1.0 will result in the expansion of faces.

     Given a patch handle as the first input argument and no output
     parameters, perform the shrinking of the patch faces in place and
     redraw the patch.

     If called with one output argument, return a structure with fields
     "faces", "vertices", and "facevertexcdata" containing the data
     after shrinking.  This structure can be used directly as an input
     argument to the ‘patch’ function.

     *Caution:*: Performing the shrink operation on faces which are not
     convex can lead to undesirable results.

     Example: a triangulated 3/4 circle and the corresponding shrunken
     version.

          [phi r] = meshgrid (linspace (0, 1.5*pi, 16), linspace (1, 2, 4));
          tri = delaunay (phi(:), r(:));
          v = [r(:).*sin(phi(:)) r(:).*cos(phi(:))];
          clf ()
          p = patch ("Faces", tri, "Vertices", v, "FaceColor", "none");
          fv = shrinkfaces (p);
          patch (fv)
          axis equal
          grid on

     See also: *note patch: XREFpatch.

 -- : diffuse (SX, SY, SZ, LV)
     Calculate the diffuse reflection strength of a surface defined by
     the normal vector elements SX, SY, SZ.

     The light source location vector LV can be given as a 2-element
     vector [azimuth, elevation] in degrees or as a 3-element vector [x,
     y, z].

     See also: *note specular: XREFspecular, *note surfl: XREFsurfl.

 -- : specular (SX, SY, SZ, LV, VV)
 -- : specular (SX, SY, SZ, LV, VV, SE)
     Calculate the specular reflection strength of a surface defined by
     the normal vector elements SX, SY, SZ using Phong’s approximation.

     The light source location and viewer location vectors are specified
     using parameters LV and VV respectively.  The location vectors can
     given as 2-element vectors [azimuth, elevation] in degrees or as
     3-element vectors [x, y, z].

     An optional sixth argument specifies the specular exponent (spread)
     SE.  If not given, SE defaults to 10.

     See also: *note diffuse: XREFdiffuse, *note surfl: XREFsurfl.

 -- : lighting (TYPE)
 -- : lighting (HAX, TYPE)
     Set the lighting of patch or surface graphic objects.

     Valid arguments for TYPE are

     "flat"
          Draw objects with faceted lighting effects.

     "gouraud"
          Draw objects with linear interpolation of the lighting effects
          between the vertices.

     "none"
          Draw objects without light and shadow effects.

     If the first argument HAX is an axes handle, then change the
     lighting effects of objects in this axes, rather than the current
     axes returned by ‘gca’.

     The lighting effects are only visible if at least one light object
     is present and visible in the same axes.

     See also: *note light: XREFlight, *note fill: XREFfill, *note mesh:
     XREFmesh, *note patch: XREFpatch, *note pcolor: XREFpcolor, *note
     surf: XREFsurf, *note surface: XREFsurface, *note shading:
     XREFshading.

 -- : material shiny
 -- : material dull
 -- : material metal
 -- : material default
 -- : material ([AS, DS, SS])
 -- : material ([AS, DS, SS, SE])
 -- : material ([AS, DS, SS, SE, SCR])
 -- : material (HLIST, ...)
 -- : MTYPES = material ()
 -- : REFL_PROPS = material (MTYPE_STRING)
     Set reflectance properties for the lighting of surfaces and
     patches.

     This function changes the ambient, diffuse, and specular strengths,
     as well as the specular exponent and specular color reflectance, of
     all ‘patch’ and ‘surface’ objects in the current axes.  This can be
     used to simulate, to some extent, the reflectance properties of
     certain materials when used with ‘light’.

     When called with a string, the aforementioned properties are set
     according to the values in the following table:

      MTYPE          ambient-    diffuse-    specular-   specular-   specular-
                     strength    strength    strength    exponent    color-
                                                                     reflectance
     -----------------------------------------------------------------------------
      "shiny"        0.3         0.6         0.9         20          1.0
      "dull"         0.3         0.8         0.0         10          1.0
      "metal"        0.3         0.3         1.0         25          0.5
      "default"      "default"   "default"   "default"   "default"   "default"

     When called with a vector of three elements, the ambient, diffuse,
     and specular strengths of all ‘patch’ and ‘surface’ objects in the
     current axes are updated.  An optional fourth vector element
     updates the specular exponent, and an optional fifth vector element
     updates the specular color reflectance.

     A list of graphic handles can also be passed as the first argument.
     In this case, the properties of these handles and all child ‘patch’
     and ‘surface’ objects will be updated.

     Additionally, ‘material’ can be called with a single output
     argument.  If called without input arguments, a column cell vector
     MTYPES with the strings for all available materials is returned.
     If the one input argument MTYPE_STRING is the name of a material, a
     1x5 cell vector REFL_PROPS with the reflectance properties of that
     material is returned.  In both cases, no graphic properties are
     changed.

     See also: *note light: XREFlight, *note fill: XREFfill, *note mesh:
     XREFmesh, *note patch: XREFpatch, *note pcolor: XREFpcolor, *note
     surf: XREFsurf, *note surface: XREFsurface.

 -- : camlight
 -- : camlight right
 -- : camlight left
 -- : camlight headlight
 -- : camlight (AZ, EL)
 -- : camlight (..., STYLE)
 -- : camlight (HL, ...)
 -- : camlight (HAX, ...)
 -- : H = camlight (...)
     Add a light object to a figure using a simple interface.

     When called with no arguments, a light object is added to the
     current plot and is placed slightly above and to the right of the
     camera’s current position: this is equivalent to ‘camlight right’.
     The commands ‘camlight left’ and ‘camlight headlight’ behave
     similarly with the placement being either left of the camera
     position or centered on the camera position.

     For more control, the light position can be specified by an
     azimuthal rotation AZ and an elevation angle EL, both in degrees,
     relative to the current properties of the camera.

     The optional string STYLE specifies whether the light is a local
     point source ("local", the default) or placed at infinite distance
     ("infinite").

     If the first argument HL is a handle to a light object, then act on
     this light object rather than creating a new object.

     If the first argument HAX is an axes handle, then create a new
     light object in this axes, rather than the current axes returned by
     ‘gca’.

     The optional return value H is a graphics handle to the light
     object.  This can be used to move or further change properties of
     the light object.

     Examples:

     Add a light object to a plot

          sphere (36);
          camlight

     Position the light source exactly

          camlight (45, 30);

     Here the light is first pitched upwards (*note camup: XREFcamup.)
     from the camera position (*note campos: XREFcampos.) by 30 degrees.
     It is then yawed by 45 degrees to the right.  Both rotations are
     centered around the camera target (*note camtarget:
     XREFcamtarget.).

     Return a handle to further manipulate the light object

          clf
          sphere (36);
          hl = camlight ("left");
          set (hl, "color", "r");

     See also: *note light: XREFlight.

 -- : [XX, YY] = meshgrid (X, Y)
 -- : [XX, YY, ZZ] = meshgrid (X, Y, Z)
 -- : [XX, YY] = meshgrid (X)
 -- : [XX, YY, ZZ] = meshgrid (X)
     Given vectors of X and Y coordinates, return matrices XX and YY
     corresponding to a full 2-D grid.

     The rows of XX are copies of X, and the columns of YY are copies of
     Y.  If Y is omitted, then it is assumed to be the same as X.

     If the optional Z input is given, or ZZ is requested, then the
     output will be a full 3-D grid.  If Z is omitted and ZZ is
     requested, it is assumed to be the same as Y.

     ‘meshgrid’ is most frequently used to produce input for a 2-D or
     3-D function that will be plotted.  The following example creates a
     surface plot of the “sombrero” function.

          f = @(x,y) sin (sqrt (x.^2 + y.^2)) ./ sqrt (x.^2 + y.^2);
          range = linspace (-8, 8, 41);
          [X, Y] = meshgrid (range, range);
          Z = f (X, Y);
          surf (X, Y, Z);

     Programming Note: ‘meshgrid’ is restricted to 2-D or 3-D grid
     generation.  The ‘ndgrid’ function will generate 1-D through N-D
     grids.  However, the functions are not completely equivalent.  If X
     is a vector of length M and Y is a vector of length N, then
     ‘meshgrid’ will produce an output grid which is NxM.  ‘ndgrid’ will
     produce an output which is MxN (transpose) for the same input.
     Some core functions expect ‘meshgrid’ input and others expect
     ‘ndgrid’ input.  Check the documentation for the function in
     question to determine the proper input format.

     See also: *note ndgrid: XREFndgrid, *note mesh: XREFmesh, *note
     contour: XREFcontour, *note surf: XREFsurf.

 -- : [Y1, Y2, ..., Yn] = ndgrid (X1, X2, ..., Xn)
 -- : [Y1, Y2, ..., Yn] = ndgrid (X)
     Given n vectors X1, ..., Xn, ‘ndgrid’ returns n arrays of dimension
     n.

     The elements of the i-th output argument contains the elements of
     the vector Xi repeated over all dimensions different from the i-th
     dimension.  Calling ndgrid with only one input argument X is
     equivalent to calling ndgrid with all n input arguments equal to X:

     [Y1, Y2, ..., Yn] = ndgrid (X, ..., X)

     Programming Note: ‘ndgrid’ is very similar to the function
     ‘meshgrid’ except that the first two dimensions are transposed in
     comparison to ‘meshgrid’.  Some core functions expect ‘meshgrid’
     input and others expect ‘ndgrid’ input.  Check the documentation
     for the function in question to determine the proper input format.

     See also: *note meshgrid: XREFmeshgrid.

 -- : plot3 (X, Y, Z)
 -- : plot3 (X, Y, Z, PROP, VALUE, ...)
 -- : plot3 (X, Y, Z, FMT)
 -- : plot3 (X, CPLX)
 -- : plot3 (CPLX)
 -- : plot3 (HAX, ...)
 -- : H = plot3 (...)
     Produce 3-D plots.

     Many different combinations of arguments are possible.  The
     simplest form is

          plot3 (X, Y, Z)

     in which the arguments are taken to be the vertices of the points
     to be plotted in three dimensions.  If all arguments are vectors of
     the same length, then a single continuous line is drawn.  If all
     arguments are matrices, then each column of is treated as a
     separate line.  No attempt is made to transpose the arguments to
     make the number of rows match.

     If only two arguments are given, as

          plot3 (X, CPLX)

     the real and imaginary parts of the second argument are used as the
     Y and Z coordinates, respectively.

     If only one argument is given, as

          plot3 (CPLX)

     the real and imaginary parts of the argument are used as the Y and
     Z values, and they are plotted versus their index.

     Arguments may also be given in groups of three as

          plot3 (X1, Y1, Z1, X2, Y2, Z2, ...)

     in which each set of three arguments is treated as a separate line
     or set of lines in three dimensions.

     To plot multiple one- or two-argument groups, separate each group
     with an empty format string, as

          plot3 (X1, C1, "", C2, "", ...)

     Multiple property-value pairs may be specified which will affect
     the line objects drawn by ‘plot3’.  If the FMT argument is supplied
     it will format the line objects in the same manner as ‘plot’.

     If the first argument HAX is an axes handle, then plot into this
     axes, rather than the current axes returned by ‘gca’.

     The optional return value H is a graphics handle to the created
     plot.

     Example:

          z = [0:0.05:5];
          plot3 (cos (2*pi*z), sin (2*pi*z), z, ";helix;");
          plot3 (z, exp (2i*pi*z), ";complex sinusoid;");

     See also: *note ezplot3: XREFezplot3, *note plot: XREFplot.

 -- : view (AZIMUTH, ELEVATION)
 -- : view ([AZIMUTH ELEVATION])
 -- : view ([X Y Z])
 -- : view (2)
 -- : view (3)
 -- : view (HAX, ...)
 -- : [AZIMUTH, ELEVATION] = view ()
     Query or set the viewpoint for the current axes.

     The parameters AZIMUTH and ELEVATION can be given as two arguments
     or as 2-element vector.  The viewpoint can also be specified with
     Cartesian coordinates X, Y, and Z.

     The call ‘view (2)’ sets the viewpoint to AZIMUTH = 0 and
     ELEVATION = 90, which is the default for 2-D graphs.

     The call ‘view (3)’ sets the viewpoint to AZIMUTH = -37.5 and
     ELEVATION = 30, which is the default for 3-D graphs.

     If the first argument HAX is an axes handle, then operate on this
     axes rather than the current axes returned by ‘gca’.

     If no inputs are given, return the current AZIMUTH and ELEVATION.

 -- : camlookat ()
 -- : camlookat (H)
 -- : camlookat (HANDLE_LIST)
 -- : camlookat (HAX)
     Move the camera and adjust its properties to look at objects.

     When the input is a handle H, the camera is set to point toward the
     center of the bounding box of H.  The camera’s position is adjusted
     so the bounding box approximately fills the field of view.

     This command fixes the camera’s viewing direction (‘camtarget() -
     campos()’), camera up vector (*note camup: XREFcamup.) and viewing
     angle (*note camva: XREFcamva.).  The camera target (*note
     camtarget: XREFcamtarget.) and camera position (*note campos:
     XREFcampos.) are changed.

     If the argument is a list HANDLE_LIST, then a single bounding box
     for all the objects is computed and the camera is then adjusted as
     above.

     If the argument is an axis object HAX, then the children of the
     axis are used as HANDLE_LIST.  When called with no inputs, it uses
     the current axis (*note gca: XREFgca.).

     See also: *note camorbit: XREFcamorbit, *note camzoom: XREFcamzoom,
     *note camroll: XREFcamroll.

 -- : P = campos ()
 -- : campos ([X Y Z])
 -- : MODE = campos ("mode")
 -- : campos (MODE)
 -- : campos (AX, ...)
     Set or get the camera position.

     The default camera position is determined automatically based on
     the scene.  For example, to get the camera position:

          hf = figure();
          peaks()
          p = campos ()
            ⇒ p =
                -27.394  -35.701   64.079

     We can then move the camera further up the z-axis:

          campos (p + [0 0 10])
          campos ()
            ⇒ ans =
                -27.394  -35.701   74.079

     Having made that change, the camera position MODE is now manual:

          campos ("mode")
            ⇒ manual

     We can set it back to automatic:

          campos ("auto")
          campos ()
            ⇒ ans =
                -27.394  -35.701   64.079
          close (hf)

     By default, these commands affect the current axis; alternatively,
     an axis can be specified by the optional argument AX.

     See also: *note camup: XREFcamup, *note camtarget: XREFcamtarget,
     *note camva: XREFcamva.

 -- : camorbit (THETA, PHI)
 -- : camorbit (THETA, PHI, COORSYS)
 -- : camorbit (THETA, PHI, COORSYS, DIR)
 -- : camorbit (THETA, PHI, "data")
 -- : camorbit (THETA, PHI, "data", "z")
 -- : camorbit (THETA, PHI, "data", "x")
 -- : camorbit (THETA, PHI, "data", "y")
 -- : camorbit (THETA, PHI, "data", [X Y Z])
 -- : camorbit (THETA, PHI, "camera")
 -- : camorbit (HAX, ...)
     Rotate the camera up/down and left/right around its target.

     Move the camera PHI degrees up and THETA degrees to the right, as
     if it were in an orbit around its target.  Example:

          sphere ()
          camorbit (30, 20)

     These rotations are centered around the camera target (*note
     camtarget: XREFcamtarget.).  First the camera position is pitched
     up or down by rotating it PHI degrees around an axis orthogonal to
     both the viewing direction (specifically ‘camtarget() - campos()’)
     and the camera “up vector” (*note camup: XREFcamup.).  Example:

          camorbit (0, 20)

     The second rotation depends on the coordinate system COORSYS and
     direction DIR inputs.  The default for COORSYS is "data".  In this
     case, the camera is yawed left or right by rotating it THETA
     degrees around an axis specified by DIR.  The default for DIR is
     "z", corresponding to the vector ‘[0, 0, 1]’.  Example:

          camorbit (30, 0)

     When COORSYS is set to "camera", the camera is moved left or right
     by rotating it around an axis parallel to the camera up vector
     (*note camup: XREFcamup.).  The input DIR should not be specified
     in this case.  Example:

          camorbit (30, 0, "camera")

     (Note: the rotation by PHI is unaffected by "camera".)

     The ‘camorbit’ command modifies two camera properties: *note
     campos: XREFcampos. and *note camup: XREFcamup.

     By default, this command affects the current axis; alternatively,
     an axis can be specified by the optional argument HAX.

     See also: *note camzoom: XREFcamzoom, *note camroll: XREFcamroll,
     *note camlookat: XREFcamlookat.

 -- : camroll (THETA)
 -- : camroll (AX, THETA)
     Roll the camera.

     Roll the camera clockwise by THETA degrees.  For example, the
     following command will roll the camera by 30 degrees clockwise (to
     the right); this will cause the scene to appear to roll by 30
     degrees to the left:

          peaks ()
          camroll (30)

     Roll the camera back:

          camroll (-30)

     The following command restores the default camera roll:

          camup ("auto")

     By default, these commands affect the current axis; alternatively,
     an axis can be specified by the optional argument AX.

     See also: *note camzoom: XREFcamzoom, *note camorbit: XREFcamorbit,
     *note camlookat: XREFcamlookat, *note camup: XREFcamup.

 -- : T = camtarget ()
 -- : camtarget ([X Y Z])
 -- : MODE = camtarget ("mode")
 -- : camtarget (MODE)
 -- : camtarget (AX, ...)
     Set or get where the camera is pointed.

     The camera target is a point in space where the camera is pointing.
     Usually, it is determined automatically based on the scene:

          hf = figure();
          sphere (36)
          v = camtarget ()
            ⇒ v =
                0   0   0

     We can turn the camera to point at a new target:

          camtarget ([1 1 1])
          camtarget ()
            ⇒   1   1   1

     Having done so, the camera target MODE is manual:

          camtarget ("mode")
            ⇒ manual

     This means, for example, adding new objects to the scene will not
     retarget the camera:

          hold on;
          peaks ()
          camtarget ()
            ⇒   1   1   1

     We can reset it to be automatic:

          camtarget ("auto")
          camtarget ()
            ⇒   0   0   0.76426
          close (hf)

     By default, these commands affect the current axis; alternatively,
     an axis can be specified by the optional argument AX.

     See also: *note campos: XREFcampos, *note camup: XREFcamup, *note
     camva: XREFcamva.

 -- : UP = camup ()
 -- : camup ([X Y Z])
 -- : MODE = camup ("mode")
 -- : camup (MODE)
 -- : camup (AX, ...)
     Set or get the camera up vector.

     By default, the camera is oriented so that “up” corresponds to the
     positive z-axis:

          hf = figure ();
          sphere (36)
          v = camup ()
            ⇒ v =
                0   0   1

     Specifying a new “up vector” rolls the camera and sets the mode to
     manual:

          camup ([1 1 0])
          camup ()
            ⇒   1   1   0
          camup ("mode")
            ⇒ manual

     Modifying the up vector does not modify the camera target (*note
     camtarget: XREFcamtarget.).  Thus, the camera up vector might not
     be orthogonal to the direction of the camera’s view:

          camup ([1 2 3])
          dot (camup (), camtarget () - campos ())
            ⇒ 6...

     A consequence is that “pulling back” on the up vector does not
     pitch the camera view (as that would require changing the target).
     Setting the up vector is thus typically used only to roll the
     camera.  A more intuitive command for this purpose is *note
     camroll: XREFcamroll.

     Finally, we can reset the up vector to automatic mode:

          camup ("auto")
          camup ()
            ⇒   0   0   1
          close (hf)

     By default, these commands affect the current axis; alternatively,
     an axis can be specified by the optional argument AX.

     See also: *note campos: XREFcampos, *note camtarget: XREFcamtarget,
     *note camva: XREFcamva.

 -- : A = camva ()
 -- : camva (A)
 -- : MODE = camva ("mode")
 -- : camva (MODE)
 -- : camva (AX, ...)
     Set or get the camera viewing angle.

     The camera has a viewing angle which determines how much can be
     seen.  By default this is:

          hf = figure();
          sphere (36)
          a = camva ()
            ⇒ a =  10.340

     To get a wider-angle view, we could double the viewing angle.  This
     will also set the mode to manual:

          camva (2*a)
          camva ("mode")
            ⇒ manual

     We can set it back to automatic:

          camva ("auto")
          camva ("mode")
            ⇒ auto
          camva ()
            ⇒ ans =  10.340
          close (hf)

     By default, these commands affect the current axis; alternatively,
     an axis can be specified by the optional argument AX.

     See also: *note campos: XREFcampos, *note camtarget: XREFcamtarget,
     *note camup: XREFcamup.

 -- : camzoom (ZF)
 -- : camzoom (AX, ZF)
     Zoom the camera in or out.

     A value of ZF larger than 1 “zooms in” such that the scene appears
     magnified:

          hf = figure ();
          sphere (36)
          camzoom (1.2)

     A value smaller than 1 “zooms out” so the camera can see more of
     the scene:

          camzoom (0.5)

     Technically speaking, zooming affects the “viewing angle”.  The
     following command resets to the default zoom:

          camva ("auto")
          close (hf)

     By default, these commands affect the current axis; alternatively,
     an axis can be specified by the optional argument AX.

     See also: *note camroll: XREFcamroll, *note camorbit: XREFcamorbit,
     *note camlookat: XREFcamlookat, *note camva: XREFcamva.

 -- : slice (X, Y, Z, V, SX, SY, SZ)
 -- : slice (X, Y, Z, V, XI, YI, ZI)
 -- : slice (V, SX, SY, SZ)
 -- : slice (V, XI, YI, ZI)
 -- : slice (..., METHOD)
 -- : slice (HAX, ...)
 -- : H = slice (...)
     Plot slices of 3-D data/scalar fields.

     Each element of the 3-dimensional array V represents a scalar value
     at a location given by the parameters X, Y, and Z.  The parameters
     X, X, and Z are either 3-dimensional arrays of the same size as the
     array V in the "meshgrid" format or vectors.  The parameters XI,
     etc. respect a similar format to X, etc., and they represent the
     points at which the array VI is interpolated using interp3.  The
     vectors SX, SY, and SZ contain points of orthogonal slices of the
     respective axes.

     If X, Y, Z are omitted, they are assumed to be ‘x = 1:size (V, 2)’,
     ‘y = 1:size (V, 1)’ and ‘z = 1:size (V, 3)’.

     METHOD is one of:

     "nearest"
          Return the nearest neighbor.

     "linear"
          Linear interpolation from nearest neighbors.

     "cubic"
          Cubic interpolation from four nearest neighbors (not
          implemented yet).

     "spline"
          Cubic spline interpolation—smooth first and second derivatives
          throughout the curve.

     The default method is "linear".

     If the first argument HAX is an axes handle, then plot into this
     axes, rather than the current axes returned by ‘gca’.

     The optional return value H is a graphics handle to the created
     surface object.

     Examples:

          [x, y, z] = meshgrid (linspace (-8, 8, 32));
          v = sin (sqrt (x.^2 + y.^2 + z.^2)) ./ (sqrt (x.^2 + y.^2 + z.^2));
          slice (x, y, z, v, [], 0, []);

          [xi, yi] = meshgrid (linspace (-7, 7));
          zi = xi + yi;
          slice (x, y, z, v, xi, yi, zi);

     See also: *note interp3: XREFinterp3, *note surface: XREFsurface,
     *note pcolor: XREFpcolor.

 -- : ribbon (Y)
 -- : ribbon (X, Y)
 -- : ribbon (X, Y, WIDTH)
 -- : ribbon (HAX, ...)
 -- : H = ribbon (...)
     Draw a ribbon plot for the columns of Y vs.  X.

     If X is omitted, a vector containing the row numbers is assumed
     (‘1:rows (Y)’).  Alternatively, X can also be a vector with same
     number of elements as rows of Y in which case the same X is used
     for each column of Y.

     The optional parameter WIDTH specifies the width of a single ribbon
     (default is 0.75).

     If the first argument HAX is an axes handle, then plot into this
     axes, rather than the current axes returned by ‘gca’.

     The optional return value H is a vector of graphics handles to the
     surface objects representing each ribbon.

     See also: *note surface: XREFsurface, *note waterfall:
     XREFwaterfall.

 -- : shading (TYPE)
 -- : shading (HAX, TYPE)
     Set the shading of patch or surface graphic objects.

     Valid arguments for TYPE are

     "flat"
          Single colored patches with invisible edges.

     "faceted"
          Single colored patches with black edges.

     "interp"
          Colors between patch vertices are interpolated and the patch
          edges are invisible.

     If the first argument HAX is an axes handle, then plot into this
     axes, rather than the current axes returned by ‘gca’.

     See also: *note fill: XREFfill, *note mesh: XREFmesh, *note patch:
     XREFpatch, *note pcolor: XREFpcolor, *note surf: XREFsurf, *note
     surface: XREFsurface, *note hidden: XREFhidden, *note lighting:
     XREFlighting.

 -- : scatter3 (X, Y, Z)
 -- : scatter3 (X, Y, Z, S)
 -- : scatter3 (X, Y, Z, S, C)
 -- : scatter3 (..., STYLE)
 -- : scatter3 (..., "filled")
 -- : scatter3 (..., PROP, VAL)
 -- : scatter3 (HAX, ...)
 -- : H = scatter3 (...)
     Draw a 3-D scatter plot.

     A marker is plotted at each point defined by the coordinates in the
     vectors X, Y, and Z.

     The size of the markers is determined by S, which can be a scalar
     or a vector of the same length as X, Y, and Z.  If S is not given,
     or is an empty matrix, then a default value of 8 points is used.

     The color of the markers is determined by C, which can be a string
     defining a fixed color; a 3-element vector giving the red, green,
     and blue components of the color; a vector of the same length as X
     that gives a scaled index into the current colormap; or an Nx3
     matrix defining the RGB color of each marker individually.

     The marker to use can be changed with the STYLE argument, that is a
     string defining a marker in the same manner as the ‘plot’ command.
     If no marker is specified it defaults to "o" or circles.  If the
     argument "filled" is given then the markers are filled.

     Additional property/value pairs are passed directly to the
     underlying patch object.

     If the first argument HAX is an axes handle, then plot into this
     axes, rather than the current axes returned by ‘gca’.

     The optional return value H is a graphics handle to the hggroup
     object representing the points.

          [x, y, z] = peaks (20);
          scatter3 (x(:), y(:), z(:), [], z(:));

     See also: *note scatter: XREFscatter, *note patch: XREFpatch, *note
     plot: XREFplot.

 -- : waterfall (X, Y, Z)
 -- : waterfall (Z)
 -- : waterfall (..., C)
 -- : waterfall (..., PROP, VAL, ...)
 -- : waterfall (HAX, ...)
 -- : H = waterfall (...)
     Plot a 3-D waterfall plot.

     A waterfall plot is similar to a ‘meshz’ plot except only mesh
     lines for the rows of Z (x-values) are shown.

     The wireframe mesh is plotted using rectangles.  The vertices of
     the rectangles [X, Y] are typically the output of ‘meshgrid’.  over
     a 2-D rectangular region in the x-y plane.  Z determines the height
     above the plane of each vertex.  If only a single Z matrix is
     given, then it is plotted over the meshgrid ‘X = 1:columns (Z), Y =
     1:rows (Z)’.  Thus, columns of Z correspond to different X values
     and rows of Z correspond to different Y values.

     The color of the mesh is computed by linearly scaling the Z values
     to fit the range of the current colormap.  Use ‘caxis’ and/or
     change the colormap to control the appearance.

     Optionally the color of the mesh can be specified independently of
     Z by supplying a color matrix, C.

     Any property/value pairs are passed directly to the underlying
     surface object.

     If the first argument HAX is an axes handle, then plot into this
     axes, rather than the current axes returned by ‘gca’.

     The optional return value H is a graphics handle to the created
     surface object.

     See also: *note meshz: XREFmeshz, *note mesh: XREFmesh, *note
     meshc: XREFmeshc, *note contour: XREFcontour, *note surf: XREFsurf,
     *note surface: XREFsurface, *note ribbon: XREFribbon, *note
     meshgrid: XREFmeshgrid, *note hidden: XREFhidden, *note shading:
     XREFshading, *note colormap: XREFcolormap, *note caxis: XREFcaxis.

* Menu:

* Aspect Ratio::
* Three-dimensional Function Plotting::
* Three-dimensional Geometric Shapes::


File: octave.info,  Node: Aspect Ratio,  Next: Three-dimensional Function Plotting,  Up: Three-Dimensional Plots

15.2.2.1 Aspect Ratio
.....................

For three-dimensional plots the aspect ratio can be set for data with
‘daspect’ and for the plot box with ‘pbaspect’.  *Note Axis
Configuration::, for controlling the x-, y-, and z-limits for plotting.

 -- : DATA_ASPECT_RATIO = daspect ()
 -- : daspect (DATA_ASPECT_RATIO)
 -- : daspect (MODE)
 -- : DATA_ASPECT_RATIO_MODE = daspect ("mode")
 -- : daspect (HAX, ...)
     Query or set the data aspect ratio of the current axes.

     The aspect ratio is a normalized 3-element vector representing the
     span of the x, y, and z-axis limits.

     ‘daspect (MODE)’

     Set the data aspect ratio mode of the current axes.  MODE is either
     "auto" or "manual".

     ‘daspect ("mode")’

     Return the data aspect ratio mode of the current axes.

     ‘daspect (HAX, ...)’

     Operate on the axes in handle HAX instead of the current axes.

     See also: *note axis: XREFaxis, *note pbaspect: XREFpbaspect, *note
     xlim: XREFxlim, *note ylim: XREFylim, *note zlim: XREFzlim.

 -- : PLOT_BOX_ASPECT_RATIO = pbaspect ( )
 -- : pbaspect (PLOT_BOX_ASPECT_RATIO)
 -- : pbaspect (MODE)
 -- : PLOT_BOX_ASPECT_RATIO_MODE = pbaspect ("mode")
 -- : pbaspect (HAX, ...)

     Query or set the plot box aspect ratio of the current axes.

     The aspect ratio is a normalized 3-element vector representing the
     rendered lengths of the x, y, and z axes.

     ‘pbaspect(MODE)’

     Set the plot box aspect ratio mode of the current axes.  MODE is
     either "auto" or "manual".

     ‘pbaspect ("mode")’

     Return the plot box aspect ratio mode of the current axes.

     ‘pbaspect (HAX, ...)’

     Operate on the axes in handle HAX instead of the current axes.

     See also: *note axis: XREFaxis, *note daspect: XREFdaspect, *note
     xlim: XREFxlim, *note ylim: XREFylim, *note zlim: XREFzlim.


File: octave.info,  Node: Three-dimensional Function Plotting,  Next: Three-dimensional Geometric Shapes,  Prev: Aspect Ratio,  Up: Three-Dimensional Plots

15.2.2.2 Three-dimensional Function Plotting
............................................

 -- : ezplot3 (FX, FY, FZ)
 -- : ezplot3 (..., DOM)
 -- : ezplot3 (..., N)
 -- : ezplot3 (..., "animate")
 -- : ezplot3 (HAX, ...)
 -- : H = ezplot3 (...)

     Plot a parametrically defined curve in three dimensions.

     FX, FY, and FZ are strings, inline functions, or function handles
     with one argument defining the function.  By default the plot is
     over the domain ‘0 <= T <= 2*pi’ with 500 points.

     If DOM is a two element vector, it represents the minimum and
     maximum values of T.

     N is a scalar defining the number of points to use in plotting the
     function.

     If the "animate" option is given then the plotting is animated in
     the style of ‘comet3’.

     If the first argument HAX is an axes handle, then plot into this
     axes, rather than the current axes returned by ‘gca’.

     The optional return value H is a graphics handle to the created
     plot.

          fx = @(t) cos (t);
          fy = @(t) sin (t);
          fz = @(t) t;
          ezplot3 (fx, fy, fz, [0, 10*pi], 100);

     See also: *note plot3: XREFplot3, *note comet3: XREFcomet3, *note
     ezplot: XREFezplot, *note ezmesh: XREFezmesh, *note ezsurf:
     XREFezsurf.

 -- : ezmesh (F)
 -- : ezmesh (FX, FY, FZ)
 -- : ezmesh (..., DOM)
 -- : ezmesh (..., N)
 -- : ezmesh (..., "circ")
 -- : ezmesh (HAX, ...)
 -- : H = ezmesh (...)

     Plot the mesh defined by a function.

     F is a string, inline function, or function handle with two
     arguments defining the function.  By default the plot is over the
     meshed domain ‘-2*pi <= X | Y <= 2*pi’ with 60 points in each
     dimension.

     If three functions are passed, then plot the parametrically defined
     function ‘[FX(S, T), FY(S, T), FZ(S, T)]’.

     If DOM is a two element vector, it represents the minimum and
     maximum values of both X and Y.  If DOM is a four element vector,
     then the minimum and maximum values are ‘[xmin xmax ymin ymax]’.

     N is a scalar defining the number of points to use in each
     dimension.

     If the argument "circ" is given, then the function is plotted over
     a disk centered on the middle of the domain DOM.

     If the first argument HAX is an axes handle, then plot into this
     axes, rather than the current axes returned by ‘gca’.

     The optional return value H is a graphics handle to the created
     surface object.

     Example 1: 2-argument function

          f = @(x,y) sqrt (abs (x .* y)) ./ (1 + x.^2 + y.^2);
          ezmesh (f, [-3, 3]);

     Example 2: parametrically defined function

          fx = @(s,t) cos (s) .* cos (t);
          fy = @(s,t) sin (s) .* cos (t);
          fz = @(s,t) sin (t);
          ezmesh (fx, fy, fz, [-pi, pi, -pi/2, pi/2], 20);

     See also: *note mesh: XREFmesh, *note ezmeshc: XREFezmeshc, *note
     ezplot: XREFezplot, *note ezsurf: XREFezsurf, *note ezsurfc:
     XREFezsurfc, *note hidden: XREFhidden.

 -- : ezmeshc (F)
 -- : ezmeshc (FX, FY, FZ)
 -- : ezmeshc (..., DOM)
 -- : ezmeshc (..., N)
 -- : ezmeshc (..., "circ")
 -- : ezmeshc (HAX, ...)
 -- : H = ezmeshc (...)

     Plot the mesh and contour lines defined by a function.

     F is a string, inline function, or function handle with two
     arguments defining the function.  By default the plot is over the
     meshed domain ‘-2*pi <= X | Y <= 2*pi’ with 60 points in each
     dimension.

     If three functions are passed, then plot the parametrically defined
     function ‘[FX(S, T), FY(S, T), FZ(S, T)]’.

     If DOM is a two element vector, it represents the minimum and
     maximum values of both X and Y.  If DOM is a four element vector,
     then the minimum and maximum values are ‘[xmin xmax ymin ymax]’.

     N is a scalar defining the number of points to use in each
     dimension.

     If the argument "circ" is given, then the function is plotted over
     a disk centered on the middle of the domain DOM.

     If the first argument HAX is an axes handle, then plot into this
     axes, rather than the current axes returned by ‘gca’.

     The optional return value H is a 2-element vector with a graphics
     handle for the created mesh plot and a second handle for the
     created contour plot.

     Example: 2-argument function

          f = @(x,y) sqrt (abs (x .* y)) ./ (1 + x.^2 + y.^2);
          ezmeshc (f, [-3, 3]);

     See also: *note meshc: XREFmeshc, *note ezmesh: XREFezmesh, *note
     ezplot: XREFezplot, *note ezsurf: XREFezsurf, *note ezsurfc:
     XREFezsurfc, *note hidden: XREFhidden.

 -- : ezsurf (F)
 -- : ezsurf (FX, FY, FZ)
 -- : ezsurf (..., DOM)
 -- : ezsurf (..., N)
 -- : ezsurf (..., "circ")
 -- : ezsurf (HAX, ...)
 -- : H = ezsurf (...)

     Plot the surface defined by a function.

     F is a string, inline function, or function handle with two
     arguments defining the function.  By default the plot is over the
     meshed domain ‘-2*pi <= X | Y <= 2*pi’ with 60 points in each
     dimension.

     If three functions are passed, then plot the parametrically defined
     function ‘[FX(S, T), FY(S, T), FZ(S, T)]’.

     If DOM is a two element vector, it represents the minimum and
     maximum values of both X and Y.  If DOM is a four element vector,
     then the minimum and maximum values are ‘[xmin xmax ymin ymax]’.

     N is a scalar defining the number of points to use in each
     dimension.

     If the argument "circ" is given, then the function is plotted over
     a disk centered on the middle of the domain DOM.

     If the first argument HAX is an axes handle, then plot into this
     axes, rather than the current axes returned by ‘gca’.

     The optional return value H is a graphics handle to the created
     surface object.

     Example 1: 2-argument function

          f = @(x,y) sqrt (abs (x .* y)) ./ (1 + x.^2 + y.^2);
          ezsurf (f, [-3, 3]);

     Example 2: parametrically defined function

          fx = @(s,t) cos (s) .* cos (t);
          fy = @(s,t) sin (s) .* cos (t);
          fz = @(s,t) sin (t);
          ezsurf (fx, fy, fz, [-pi, pi, -pi/2, pi/2], 20);

     See also: *note surf: XREFsurf, *note ezsurfc: XREFezsurfc, *note
     ezplot: XREFezplot, *note ezmesh: XREFezmesh, *note ezmeshc:
     XREFezmeshc, *note shading: XREFshading.

 -- : ezsurfc (F)
 -- : ezsurfc (FX, FY, FZ)
 -- : ezsurfc (..., DOM)
 -- : ezsurfc (..., N)
 -- : ezsurfc (..., "circ")
 -- : ezsurfc (HAX, ...)
 -- : H = ezsurfc (...)

     Plot the surface and contour lines defined by a function.

     F is a string, inline function, or function handle with two
     arguments defining the function.  By default the plot is over the
     meshed domain ‘-2*pi <= X | Y <= 2*pi’ with 60 points in each
     dimension.

     If three functions are passed, then plot the parametrically defined
     function ‘[FX(S, T), FY(S, T), FZ(S, T)]’.

     If DOM is a two element vector, it represents the minimum and
     maximum values of both X and Y.  If DOM is a four element vector,
     then the minimum and maximum values are ‘[xmin xmax ymin ymax]’.

     N is a scalar defining the number of points to use in each
     dimension.

     If the argument "circ" is given, then the function is plotted over
     a disk centered on the middle of the domain DOM.

     If the first argument HAX is an axes handle, then plot into this
     axes, rather than the current axes returned by ‘gca’.

     The optional return value H is a 2-element vector with a graphics
     handle for the created surface plot and a second handle for the
     created contour plot.

     Example:

          f = @(x,y) sqrt (abs (x .* y)) ./ (1 + x.^2 + y.^2);
          ezsurfc (f, [-3, 3]);

     See also: *note surfc: XREFsurfc, *note ezsurf: XREFezsurf, *note
     ezplot: XREFezplot, *note ezmesh: XREFezmesh, *note ezmeshc:
     XREFezmeshc, *note shading: XREFshading.


File: octave.info,  Node: Three-dimensional Geometric Shapes,  Prev: Three-dimensional Function Plotting,  Up: Three-Dimensional Plots

15.2.2.3 Three-dimensional Geometric Shapes
...........................................

 -- : cylinder
 -- : cylinder (R)
 -- : cylinder (R, N)
 -- : cylinder (HAX, ...)
 -- : [X, Y, Z] = cylinder (...)
     Plot a 3-D unit cylinder.

     The optional input R is a vector specifying the radius along the
     unit z-axis.  The default is [1 1] indicating radius 1 at ‘Z == 0’
     and at ‘Z == 1’.

     The optional input N determines the number of faces around the
     circumference of the cylinder.  The default value is 20.

     If the first argument HAX is an axes handle, then plot into this
     axes, rather than the current axes returned by ‘gca’.

     If outputs are requested ‘cylinder’ returns three matrices in
     ‘meshgrid’ format, such that ‘surf (X, Y, Z)’ generates a unit
     cylinder.

     Example:

          [x, y, z] = cylinder (10:-1:0, 50);
          surf (x, y, z);
          title ("a cone");

     See also: *note ellipsoid: XREFellipsoid, *note rectangle:
     XREFrectangle, *note sphere: XREFsphere.

 -- : sphere ()
 -- : sphere (N)
 -- : sphere (HAX, ...)
 -- : [X, Y, Z] = sphere (...)
     Plot a 3-D unit sphere.

     The optional input N determines the number of faces around the
     circumference of the sphere.  The default value is 20.

     If the first argument HAX is an axes handle, then plot into this
     axes, rather than the current axes returned by ‘gca’.

     If outputs are requested ‘sphere’ returns three matrices in
     ‘meshgrid’ format such that ‘surf (X, Y, Z)’ generates a unit
     sphere.

     Example:

          [x, y, z] = sphere (40);
          surf (3*x, 3*y, 3*z);
          axis equal;
          title ("sphere of radius 3");

     See also: *note cylinder: XREFcylinder, *note ellipsoid:
     XREFellipsoid, *note rectangle: XREFrectangle.

 -- : ellipsoid (XC, YC, ZC, XR, YR, ZR, N)
 -- : ellipsoid (..., N)
 -- : ellipsoid (HAX, ...)
 -- : [X, Y, Z] = ellipsoid (...)
     Plot a 3-D ellipsoid.

     The inputs XC, YC, ZC specify the center of the ellipsoid.  The
     inputs XR, YR, ZR specify the semi-major axis lengths.

     The optional input N determines the number of faces around the
     circumference of the cylinder.  The default value is 20.

     If the first argument HAX is an axes handle, then plot into this
     axes, rather than the current axes returned by ‘gca’.

     If outputs are requested ‘ellipsoid’ returns three matrices in
     ‘meshgrid’ format, such that ‘surf (X, Y, Z)’ generates the
     ellipsoid.

     See also: *note cylinder: XREFcylinder, *note rectangle:
     XREFrectangle, *note sphere: XREFsphere.


File: octave.info,  Node: Plot Annotations,  Next: Multiple Plots on One Page,  Prev: Three-Dimensional Plots,  Up: High-Level Plotting

15.2.3 Plot Annotations
-----------------------

You can add titles, axis labels, legends, and arbitrary text to an
existing plot.  For example:

     x = -10:0.1:10;
     plot (x, sin (x));
     title ("sin(x) for x = -10:0.1:10");
     xlabel ("x");
     ylabel ("sin (x)");
     text (pi, 0.7, "arbitrary text");
     legend ("sin (x)");

   The functions ‘grid’ and ‘box’ may also be used to add grid and
border lines to the plot.  By default, the grid is off and the border
lines are on.

   Finally, arrows, text and rectangular or elliptic boxes can be added
to highlight parts of a plot using the ‘annotation’ function.  Those
objects are drawn in an invisible axes, on top of every other axes.

 -- : title (STRING)
 -- : title (STRING, PROP, VAL, ...)
 -- : title (HAX, ...)
 -- : H = title (...)
     Specify the string used as a title for the current axis.

     An optional list of PROPERTY/VALUE pairs can be used to change the
     appearance of the created title text object.

     If the first argument HAX is an axes handle, then plot into this
     axes, rather than the current axes returned by ‘gca’.

     The optional return value H is a graphics handle to the created
     text object.

     See also: *note xlabel: XREFxlabel, *note ylabel: XREFylabel, *note
     zlabel: XREFzlabel, *note text: XREFtext.

 -- : legend ()
 -- : legend (STR1, STR2, ...)
 -- : legend (CHARMAT)
 -- : legend ({CELLSTR})
 -- : legend (..., "location", POS)
 -- : legend (..., "orientation", ORIENT)
 -- : legend (HAX, ...)
 -- : legend (HOBJS, ...)
 -- : legend (HAX, HOBJS, ...)
 -- : legend ("OPTION")
 -- : legend (..., {CELLSTR}, PROPERTY, VALUE, ...)
 -- : [HLEG, HLEG_OBJ, HPLOT, LABELS] = legend (...)

     Display a legend for the current axes using the specified strings
     as labels.

     Legend entries may be specified as individual character string
     arguments, a character array, or a cell array of character strings.
     When label names might be confused with options to ‘legend’, the
     labels should be protected by specifying them as a cell array of
     strings.

     If the first argument HAX is an axes handle, then add a legend to
     this axes, rather than the current axes returned by ‘gca’.

     Legend labels are associated with the axes’ children; The first
     label is assigned to the first object that was plotted in the axes,
     the second label to the next object plotted, etc.  To label
     specific data objects, without labeling all objects, provide their
     graphic handles in the input HOBJS.

     The optional parameter POS specifies the location of the legend as
     follows:

          pos        location of the legend
     ---------------------------------------------------------------------------
          north      center top
          south      center bottom
          east       right center
          west       left center
          northeast  right top (default)
          northwest  left top
          southeast  right bottom
          southwest  left bottom
                     
          outside    can be appended to any location string
                     which will place the legend outside the axes

     The optional parameter ORIENT determines if the legend elements are
     placed vertically or horizontally.  The allowed values are
     "vertical" (default) or "horizontal".

     The following customizations are available using OPTION:

     "show"
          Show legend on the plot

     "hide"
          Hide legend on the plot

     "toggle"
          Toggle between "hide" and "show"

     "boxon"
          Show a box around legend (default)

     "boxoff"
          Hide the box around legend

     "right"
          Place label text to the right of the keys (default)

     "left"
          Place label text to the left of the keys

     "off"
          Delete the legend object

     The ‘legend’ function creates a graphics object which has various
     properties that can be manipulated with ‘get’/‘set’.
     Alternatively, properties can be set directly when calling ‘legend’
     by including PROPERTY/VALUE pairs.  If using this calling form, the
     labels must be specified as a cell array of strings.

     The optional output values are

     HLEG
          The graphics handle of the legend object.

     HLEG_OBJ
          Graphics handles to the text, patch, and line objects which
          form the legend.

     HPLOT
          Graphics handles to the plot objects which were used in making
          the legend.

     LABELS
          A cell array of strings of the labels in the legend.

     Implementation Note: The legend label text is either provided in
     the call to ‘legend’ or is taken from the ‘DisplayName’ property of
     the graphics objects.  Only data objects, such as line, patch, and
     surface, have this property whereas axes, figures, etc. do not so
     they are never present in a legend.  If no labels or ‘DisplayName’
     properties are available, then the label text is simply "data1",
     "data2", ..., "dataN". No more than 20 data labels will be
     automatically generated.  To label more, call ‘legend’ explicitly
     and provide all labels.

     The legend ‘FontSize’ property is initially set to 90% of the axes
     ‘FontSize’ to which it is attached.  Use ‘set’ to override this if
     necessary.

     A legend is implemented as an additional axes object with the ‘tag’
     property set to "legend".  Properties of the legend object may be
     manipulated directly by using ‘set’.

 -- : text (X, Y, STRING)
 -- : text (X, Y, Z, STRING)
 -- : text (..., PROP, VAL, ...)
 -- : H = text (...)
     Create a text object with text STRING at position X, Y, (Z) on the
     current axes.

     Multiple locations can be specified if X, Y, (Z) are vectors.
     Multiple strings can be specified with a character matrix or a cell
     array of strings.

     Optional property/value pairs may be used to control the appearance
     of the text.

     The optional return value H is a vector of graphics handles to the
     created text objects.

     Programming Note: The full list of properties is documented at
     *note Text Properties: Text Properties.

     See also: *note gtext: XREFgtext, *note title: XREFtitle, *note
     xlabel: XREFxlabel, *note ylabel: XREFylabel, *note zlabel:
     XREFzlabel.

   See *note Text Properties:: for the properties that you can set.

 -- : xlabel (STRING)
 -- : xlabel (STRING, PROPERTY, VAL, ...)
 -- : xlabel (HAX, ...)
 -- : H = xlabel (...)
     Specify the string used to label the x-axis of the current axis.

     An optional list of PROPERTY/VALUE pairs can be used to change the
     properties of the created text label.

     If the first argument HAX is an axes handle, then operate on this
     axes rather than the current axes returned by ‘gca’.

     The optional return value H is a graphics handle to the created
     text object.

     See also: *note ylabel: XREFylabel, *note zlabel: XREFzlabel, *note
     datetick: XREFdatetick, *note title: XREFtitle, *note text:
     XREFtext.

 -- : clabel (C, H)
 -- : clabel (C, H, V)
 -- : clabel (C, H, "manual")
 -- : clabel (C)
 -- : clabel (..., PROP, VAL, ...)
 -- : H = clabel (...)
     Add labels to the contours of a contour plot.

     The contour levels are specified by the contour matrix C which is
     returned by ‘contour’, ‘contourc’, ‘contourf’, and ‘contour3’.
     Contour labels are rotated to match the local line orientation and
     centered on the line.  The position of labels along the contour
     line is chosen randomly.

     If the argument H is a handle to a contour group object, then label
     this plot rather than the one in the current axes returned by
     ‘gca’.

     By default, all contours are labeled.  However, the contours to
     label can be specified by the vector V.  If the "manual" argument
     is given then the contours to label can be selected with the mouse.

     Additional property/value pairs that are valid properties of text
     objects can be given and are passed to the underlying text objects.
     Moreover, the contour group property "LabelSpacing" is available
     which determines the spacing between labels on a contour to be
     specified.  The default is 144 points, or 2 inches.

     The optional return value H is a vector of graphics handles to the
     text objects representing each label.  The "userdata" property of
     the text objects contains the numerical value of the contour label.

     An example of the use of ‘clabel’ is

          [c, h] = contour (peaks (), -4 : 6);
          clabel (c, h, -4:2:6, "fontsize", 12);

     See also: *note contour: XREFcontour, *note contourf: XREFcontourf,
     *note contour3: XREFcontour3, *note meshc: XREFmeshc, *note surfc:
     XREFsurfc, *note text: XREFtext.

 -- : box
 -- : box on
 -- : box off
 -- : box (HAX, ...)
     Control display of the axes border.

     The argument may be either "on" or "off".  If it is omitted, the
     current box state is toggled.

     If the first argument HAX is an axes handle, then operate on this
     axes rather than the current axes returned by ‘gca’.

     See also: *note axis: XREFaxis, *note grid: XREFgrid.

 -- : grid
 -- : grid on
 -- : grid off
 -- : grid minor
 -- : grid minor on
 -- : grid minor off
 -- : grid (HAX, ...)
     Control the display of plot grid lines.

     The function state input may be either "on" or "off".  If it is
     omitted, the current grid state is toggled.

     When the first argument is "minor" all subsequent commands modify
     the minor grid rather than the major grid.

     If the first argument HAX is an axes handle, then operate on this
     axes rather than the current axes returned by ‘gca’.

     To control the grid lines for an individual axes use the ‘set’
     function.  For example:

          set (gca, "ygrid", "on");

     See also: *note axis: XREFaxis, *note box: XREFbox.

 -- : colorbar
 -- : colorbar (..., LOC)
 -- : colorbar (DELETE_OPTION)
 -- : colorbar (HCB, ...)
 -- : colorbar (HAX, ...)
 -- : colorbar (..., "peer", HAX, ...)
 -- : colorbar (..., "location", LOC, ...)
 -- : colorbar (..., PROP, VAL, ...)
 -- : H = colorbar (...)
     Add a colorbar to the current axes.

     A colorbar displays the current colormap along with numerical
     rulings so that the color scale can be interpreted.

     The optional input LOC determines the location of the colorbar.  If
     present, it must be the last argument to ‘colorbar’.  Valid values
     for LOC are

     "EastOutside"
          Place the colorbar outside the plot to the right.  This is the
          default.

     "East"
          Place the colorbar inside the plot to the right.

     "WestOutside"
          Place the colorbar outside the plot to the left.

     "West"
          Place the colorbar inside the plot to the left.

     "NorthOutside"
          Place the colorbar above the plot.

     "North"
          Place the colorbar at the top of the plot.

     "SouthOutside"
          Place the colorbar under the plot.

     "South"
          Place the colorbar at the bottom of the plot.

     To remove a colorbar from a plot use any one of the following
     keywords for the DELETE_OPTION: "off", "delete", "hide".

     If the first argument HAX is an axes handle, then the colorbar is
     added to this axes, rather than the current axes returned by ‘gca’.
     Alternatively, If the argument "peer" is given, then the following
     argument is treated as the axes handle in which to add the
     colorbar.  The "peer" calling syntax may be removed in the future
     and is not recommended.

     If the first argument HCB is a handle to a colorbar object, then
     operate on this colorbar directly.

     Additional property/value pairs are passed directly to the
     underlying axes object.

     The optional return value H is a graphics handle to the created
     colorbar object.

     Implementation Note: A colorbar is created as an additional axes
     object with the "tag" property set to "colorbar".  The created
     object has the extra property "location" which controls the
     positioning of the colorbar.

     See also: *note colormap: XREFcolormap.

 -- : annotation (TYPE)
 -- : annotation ("line", X, Y)
 -- : annotation ("arrow", X, Y)
 -- : annotation ("doublearrow", X, Y)
 -- : annotation ("textarrow", X, Y)
 -- : annotation ("textbox", POS)
 -- : annotation ("rectangle", POS)
 -- : annotation ("ellipse", POS)
 -- : annotation (..., PROP, VAL)
 -- : annotation (HF, ...)
 -- : H = annotation (...)
     Draw annotations to emphasize parts of a figure.

     You may build a default annotation by specifying only the TYPE of
     the annotation.

     Otherwise you can select the type of annotation and then set its
     position using either X and Y coordinates for line-based
     annotations or a position vector POS for others.  In either case,
     coordinates are interpreted using the "units" property of the
     annotation object.  The default is "normalized", which means the
     lower left hand corner of the figure has coordinates ‘[0 0]’ and
     the upper right hand corner ‘[1 1]’.

     If the first argument HF is a figure handle, then plot into this
     figure, rather than the current figure returned by ‘gcf’.

     Further arguments can be provided in the form of PROP/VAL pairs to
     customize the annotation appearance.

     The optional return value H is a graphics handle to the created
     annotation object.  This can be used with the ‘set’ function to
     customize an existing annotation object.

     All annotation objects share two properties:

        • "units": the units in which coordinates are interpreted.
          Its value may be one of "centimeters" | "characters" |
          "inches" | "{normalized}" | "pixels" | "points".

        • "position": a four-element vector [x0 y0 width height].
          The vector specifies the coordinates (x0,y0) of the origin of
          the annotation object, its width, and its height.  The width
          and height may be negative, depending on the orientation of
          the object.

     Valid annotation types and their specific properties are described
     below:

     "line"
          Constructs a line.  X and Y must be two-element vectors
          specifying the x and y coordinates of the two ends of the
          line.

          The line can be customized using "linewidth", "linestyle", and
          "color" properties the same way as for ‘line’ objects.

     "arrow"
          Construct an arrow.  The second point in vectors X and Y
          specifies the arrowhead coordinates.

          Besides line properties, the arrowhead can be customized using
          "headlength", "headwidth", and "headstyle" properties.
          Supported values for "headstyle" property are: ["diamond" |
          "ellipse" | "plain" | "rectangle" | "vback1" | "{vback2}" |
          "vback3"]

     "doublearrow"
          Construct a double arrow.  Vectors X and Y specify the
          arrowhead coordinates.

          The line and the arrowhead can be customized as for arrow
          annotations, but some property names are duplicated:
          "head1length"/"head2length", "head1width"/"head2width", etc.
          The index 1 marks the properties of the arrowhead at the first
          point in X and Y coordinates.

     "textarrow"
          Construct an arrow with a text label at the opposite end from
          the arrowhead.

          Use the "string" property to change the text string.  The line
          and the arrowhead can be customized as for arrow annotations,
          and the text can be customized using the same properties as
          ‘text’ graphics objects.  Note, however, that some text
          property names are prefixed with "text" to distinguish them
          from arrow properties: "textbackgroundcolor", "textcolor",
          "textedgecolor", "textlinewidth", "textmargin",
          "textrotation".

     "textbox"
          Construct a box with text inside.  POS specifies the
          "position" property of the annotation.

          Use the "string" property to change the text string.  You may
          use "backgroundcolor", "edgecolor", "linestyle", and
          "linewidth" properties to customize the box background color
          and edge appearance.  A limited set of ‘text’ objects
          properties are also available; Besides "font..." properties,
          you may also use "horizontalalignment" and "verticalalignment"
          to position the text inside the box.

          Finally, the "fitboxtotext" property controls the actual
          extent of the box.  If "on" (the default) the box limits are
          fitted to the text extent.

     "rectangle"
          Construct a rectangle.  POS specifies the "position" property
          of the annotation.

          You may use "facecolor", "color", "linestyle", and "linewidth"
          properties to customize the rectangle background color and
          edge appearance.

     "ellipse"
          Construct an ellipse.  POS specifies the "position" property
          of the annotation.

          See "rectangle" annotations for customization.

     See also: *note xlabel: XREFxlabel, *note ylabel: XREFylabel, *note
     zlabel: XREFzlabel, *note title: XREFtitle, *note text: XREFtext,
     *note gtext: XREFgtext, *note legend: XREFlegend, *note colorbar:
     XREFcolorbar.


File: octave.info,  Node: Multiple Plots on One Page,  Next: Multiple Plot Windows,  Prev: Plot Annotations,  Up: High-Level Plotting

15.2.4 Multiple Plots on One Page
---------------------------------

Octave can display more than one plot in a single figure.  The simplest
way to do this is to use the ‘subplot’ function to divide the plot area
into a series of subplot windows that are indexed by an integer.  For
example,

     subplot (2, 1, 1)
     fplot (@sin, [-10, 10]);
     subplot (2, 1, 2)
     fplot (@cos, [-10, 10]);

creates a figure with two separate axes, one displaying a sine wave and
the other a cosine wave.  The first call to subplot divides the figure
into two plotting areas (two rows and one column) and makes the first
plot area active.  The grid of plot areas created by ‘subplot’ is
numbered in row-major order (left to right, top to bottom).  After
plotting a sine wave, the next call to subplot activates the second
subplot area, but does not re-partition the figure.

 -- : subplot (ROWS, COLS, INDEX)
 -- : subplot (ROWS, COLS, INDEX, HAX)
 -- : subplot (RCN)
 -- : subplot (HAX)
 -- : subplot (..., "align")
 -- : subplot (..., "replace")
 -- : subplot (..., "position", POS)
 -- : subplot (..., PROP, VAL, ...)
 -- : HAX = subplot (...)
     Set up a plot grid with ROWS by COLS subwindows and set the current
     axes for plotting (‘gca’) to the location given by INDEX.

     If an axes handle HAX is provided after the (ROWS, COLS, INDEX)
     arguments, the corresponding axes is turned into a subplot.

     If only one numeric argument is supplied, then it must be a three
     digit value specifying the number of rows in digit 1, the number of
     columns in digit 2, and the plot index in digit 3.

     The plot index runs row-wise; First, all columns in a row are
     numbered and then the next row is filled.

     For example, a plot with 2x3 grid will have plot indices running as
     follows:

          +-----+-----+-----+
          |  1  |  2  |  3  |
          +-----+-----+-----+
          |  4  |  5  |  6  |
          +-----+-----+-----+

     INDEX may also be a vector.  In this case, the new axes will
     enclose the grid locations specified.  The first demo illustrates
     this:

          demo ("subplot", 1)

     The index of the subplot to make active may also be specified by
     its axes handle, HAX, returned from a previous ‘subplot’ command.

     If the option "align" is given then the plot boxes of the
     subwindows will align, but this may leave no room for axes tick
     marks or labels.

     If the option "replace" is given then the subplot axes will be
     reset, rather than just switching the current axes for plotting to
     the requested subplot.

     The "position" property can be used to exactly position the subplot
     axes within the current figure.  The option POS is a 4-element
     vector [x, y, width, height] that determines the location and size
     of the axes.  The values in POS are normalized in the range [0,1].

     Any property/value pairs are passed directly to the underlying axes
     object.

     If the output HAX is requested, subplot returns the axes handle for
     the subplot.  This is useful for modifying the properties of a
     subplot using ‘set’.

     See also: *note axes: XREFaxes, *note plot: XREFplot, *note gca:
     XREFgca, *note set: XREFset.


File: octave.info,  Node: Multiple Plot Windows,  Next: Manipulation of Plot Objects,  Prev: Multiple Plots on One Page,  Up: High-Level Plotting

15.2.5 Multiple Plot Windows
----------------------------

You can open multiple plot windows using the ‘figure’ function.  For
example,

     figure (1);
     fplot (@sin, [-10, 10]);
     figure (2);
     fplot (@cos, [-10, 10]);

creates two figures, with the first displaying a sine wave and the
second a cosine wave.  Figure numbers must be positive integers.

 -- : figure
 -- : figure N
 -- : figure (N)
 -- : figure (..., "PROPERTY", VALUE, ...)
 -- : H = figure (...)
     Create a new figure window for plotting.

     If no arguments are specified, a new figure with the next available
     number is created.

     If called with an integer N, and no such numbered figure exists,
     then a new figure with the specified number is created.  If the
     figure already exists then it is made visible and becomes the
     current figure for plotting.

     Multiple property-value pairs may be specified for the figure
     object, but they must appear in pairs.

     The optional return value H is a graphics handle to the created
     figure object.

     Programming Note: The full list of properties is documented at
     *note Figure Properties: Figure Properties.

     See also: *note axes: XREFaxes, *note gcf: XREFgcf, *note shg:
     XREFshg, *note clf: XREFclf, *note close: XREFclose.


File: octave.info,  Node: Manipulation of Plot Objects,  Next: Manipulation of Plot Windows,  Prev: Multiple Plot Windows,  Up: High-Level Plotting

15.2.6 Manipulation of Plot Objects
-----------------------------------

 -- : pan
 -- : pan on
 -- : pan off
 -- : pan xon
 -- : pan yon
 -- : pan (HFIG, OPTION)
     Control the interactive panning mode of a figure in the GUI.

     Given the option "on" or "off", set the interactive pan mode on or
     off.

     With no arguments, toggle the current pan mode on or off.

     Given the option "xon" or "yon", enable pan mode for the x or y
     axis only.

     If the first argument HFIG is a figure, then operate on the given
     figure rather than the current figure as returned by ‘gcf’.

     See also: *note rotate3d: XREFrotate3d, *note zoom: XREFzoom.

 -- : rotate (H, DIRECTION, ALPHA)
 -- : rotate (..., ORIGIN)
     Rotate the plot object H through ALPHA degrees around the line with
     direction DIRECTION and origin ORIGIN.

     The default value of ORIGIN is the center of the axes object that
     is the parent of H.

     If H is a vector of handles, they must all have the same parent
     axes object.

     Graphics objects that may be rotated are lines, surfaces, patches,
     and images.

 -- : rotate3d
 -- : rotate3d on
 -- : rotate3d off
 -- : rotate3d (HFIG, OPTION)
     Control the interactive 3-D rotation mode of a figure in the GUI.

     Given the option "on" or "off", set the interactive rotate mode on
     or off.

     With no arguments, toggle the current rotate mode on or off.

     If the first argument HFIG is a figure, then operate on the given
     figure rather than the current figure as returned by ‘gcf’.

     See also: *note pan: XREFpan, *note zoom: XREFzoom.

 -- : zoom
 -- : zoom (FACTOR)
 -- : zoom on
 -- : zoom off
 -- : zoom xon
 -- : zoom yon
 -- : zoom out
 -- : zoom reset
 -- : zoom (HFIG, OPTION)
     Zoom the current axes object or control the interactive zoom mode
     of a figure in the GUI.

     Given a numeric argument greater than zero, zoom by the given
     factor.  If the zoom factor is greater than one, zoom in on the
     plot.  If the factor is less than one, zoom out.  If the zoom
     factor is a two- or three-element vector, then the elements specify
     the zoom factors for the x, y, and z axes respectively.

     Given the option "on" or "off", set the interactive zoom mode on or
     off.

     With no arguments, toggle the current zoom mode on or off.

     Given the option "xon" or "yon", enable zoom mode for the x or
     y-axis only.

     Given the option "out", zoom to the initial zoom setting.

     Given the option "reset", store the current zoom setting so that
     ‘zoom out’ will return to this zoom level.

     If the first argument HFIG is a figure, then operate on the given
     figure rather than the current figure as returned by ‘gcf’.

     See also: *note pan: XREFpan, *note rotate3d: XREFrotate3d.


File: octave.info,  Node: Manipulation of Plot Windows,  Next: Use of the interpreter Property,  Prev: Manipulation of Plot Objects,  Up: High-Level Plotting

15.2.7 Manipulation of Plot Windows
-----------------------------------

By default, Octave refreshes the plot window when a prompt is printed,
or when waiting for input.  The ‘drawnow’ function is used to cause a
plot window to be updated.

 -- : drawnow ()
 -- : drawnow ("expose")
 -- : drawnow (TERM, FILE, DEBUG_FILE)
     Update figure windows and their children.

     The event queue is flushed and any callbacks generated are
     executed.

     With the optional argument "expose", only graphic objects are
     updated and no other events or callbacks are processed.

     The third calling form of ‘drawnow’ is for debugging and is
     undocumented.

     See also: *note refresh: XREFrefresh.

   Only figures that are modified will be updated.  The ‘refresh’
function can also be used to cause an update of the current figure, even
if it is not modified.

 -- : refresh ()
 -- : refresh (H)
     Refresh a figure, forcing it to be redrawn.

     When called without an argument the current figure is redrawn.
     Otherwise, the figure with graphic handle H is redrawn.

     See also: *note drawnow: XREFdrawnow.

   Normally, high-level plot functions like ‘plot’ or ‘mesh’ call
‘newplot’ to determine whether the state of the target axes should be
initialized (the default) or if subsequent plots should be drawn on top
of previous ones.  To have two plots drawn over one another, use the
‘hold’ function or manually change the axes *note nextplot:
XREFaxesnextplot. property.  For example,

     hold on;
     x = -10:0.1:10;
     plot (x, sin (x));
     plot (x, cos (x));
     hold off;

displays sine and cosine waves on the same axes.  If the hold state is
off, consecutive plotting commands like this will only display the last
plot.

 -- : newplot ()
 -- : newplot (HFIG)
 -- : newplot (HAX)
 -- : HAX = newplot (...)
     Prepare graphics engine to produce a new plot.

     This function is called at the beginning of all high-level plotting
     functions.  It is not normally required in user programs.
     ‘newplot’ queries the "NextPlot" field of the current figure and
     axes to determine what to do.

     Figure NextPlot    Action
     --------------------------------------------------------------------------
     "new"              Create a new figure and make it the current figure.
                        
     "add" (default)    Add new graphic objects to the current figure.
                        
     "replacechildren"  Delete child objects whose HandleVisibility is set
                        to "on".  Set NextPlot property to "add".  This
                        typically clears a figure, but leaves in place
                        hidden objects such as menubars.  This is equivalent
                        to ‘clf’.
                        
     "replace"          Delete all child objects of the figure and reset all
                        figure properties to their defaults.  However, the
                        following four properties are not reset: Position,
                        Units, PaperPosition, PaperUnits.  This is
                        equivalent to ‘clf reset’.

     Axes NextPlot      Action
     --------------------------------------------------------------------------
     "add"              Add new graphic objects to the current axes.  This
                        is equivalent to ‘hold on’.
                        
     "replacechildren"  Delete child objects whose HandleVisibility is set
                        to "on", but leave axes properties unmodified.  This
                        typically clears a plot, but preserves special
                        settings such as log scaling for axes.  This is
                        equivalent to ‘cla’.
                        
     "replace"          Delete all child objects of the axes and reset all
     (default)          axes properties to their defaults.  However, the
                        following properties are not reset: Position, Units.
                        This is equivalent to ‘cla reset’.

     If the optional input HFIG or HAX is given then prepare the
     specified figure or axes rather than the current figure and axes.

     The optional return value HAX is a graphics handle to the created
     axes object (not figure).

     *Caution:* Calling ‘newplot’ may change the current figure and
     current axes.

 -- : hold
 -- : hold on
 -- : hold off
 -- : hold (HAX, ...)
     Toggle or set the "hold" state of the plotting engine which
     determines whether new graphic objects are added to the plot or
     replace the existing objects.

     ‘hold on’
          Retain plot data and settings so that subsequent plot commands
          are displayed on a single graph.  Line color and line style
          are advanced for each new plot added.

     ‘hold all (deprecated)’
          Equivalent to ‘hold on’.

     ‘hold off’
          Restore default graphics settings which clear the graph and
          reset axes properties before each new plot command.
          (default).

     ‘hold’
          Toggle the current hold state.

     When given the additional argument HAX, the hold state is modified
     for this axes rather than the current axes returned by ‘gca’.

     To query the current hold state use the ‘ishold’ function.

     See also: *note ishold: XREFishold, *note cla: XREFcla, *note clf:
     XREFclf, *note newplot: XREFnewplot.

 -- : ishold
 -- : ishold (HAX)
 -- : ishold (HFIG)
     Return true if the next plot will be added to the current plot, or
     false if the plot device will be cleared before drawing the next
     plot.

     If the first argument is an axes handle HAX or figure handle HFIG
     then operate on this plot rather than the current one.

     See also: *note hold: XREFhold, *note newplot: XREFnewplot.

   To clear the current figure, call the ‘clf’ function.  To clear the
current axis, call the ‘cla’ function.  To bring the current figure to
the top of the window stack, call the ‘shg’ function.  To delete a
graphics object, call ‘delete’ on its index.  To close the figure
window, call the ‘close’ function.

 -- : clf
 -- : clf reset
 -- : clf (HFIG)
 -- : clf (HFIG, "reset")
 -- : H = clf (...)
     Clear the current figure window.

     ‘clf’ operates by deleting child graphics objects with visible
     handles (HandleVisibility = "on").

     If the optional argument "reset" is specified, delete all child
     objects including those with hidden handles and reset all figure
     properties to their defaults.  However, the following properties
     are not reset: Position, Units, PaperPosition, PaperUnits.

     If the first argument HFIG is a figure handle, then operate on this
     figure rather than the current figure returned by ‘gcf’.

     The optional return value H is the graphics handle of the figure
     window that was cleared.

     See also: *note cla: XREFcla, *note close: XREFclose, *note delete:
     XREFdelete, *note reset: XREFreset.

 -- : cla
 -- : cla reset
 -- : cla (HAX)
 -- : cla (HAX, "reset")
     Clear the current or specified (HAX) axes object.

     ‘cla’ operates by deleting child graphic objects with visible
     handles (‘HandleVisibility’ = "on").  This typically clears the
     axes of any visual objects, but leaves in place axes limits, tick
     marks and labels, camera view, etc.  In addition, the automatic
     coloring and styling of lines is reset by changing the axes
     properties ‘ColorOrderIndex’, ‘LinestyleOrderIndex’ to 1.

     If the optional argument "reset" is specified, delete all child
     objects, including those with hidden handles, and reset all axes
     properties to their defaults.  However, the following properties
     are not reset: ‘Position’, ‘Units’.

     If the first argument HAX is an axes handle, then operate on this
     axes rather than the current axes returned by ‘gca’.

     See also: *note clf: XREFclf, *note delete: XREFdelete, *note
     reset: XREFreset.

 -- : shg
     Show the graph window.

     This function makes the current figure visible, and places it on
     top of of all other plot windows.

     Programming Note: ‘shg’ is equivalent to ‘figure (gcf)’ assuming
     that a current figure exists.

     See also: *note figure: XREFfigure, *note drawnow: XREFdrawnow,
     *note gcf: XREFgcf.

 -- : delete (FILE)
 -- : delete (FILE1, FILE2, ...)
 -- : delete (HANDLE)
     Delete the named file or graphics handle.

     FILE may contain globbing patterns such as ‘*’.  Multiple files to
     be deleted may be specified in the same function call.

     HANDLE may be a scalar or vector of graphic handles to delete.

     Programming Note: Deleting graphics objects is the proper way to
     remove features from a plot without clearing the entire figure.

     See also: *note clf: XREFclf, *note cla: XREFcla, *note unlink:
     XREFunlink, *note rmdir: XREFrmdir.

 -- : close
 -- : close (H)
 -- : close FIGNAME
 -- : close all
 -- : close all hidden
 -- : close all force
     Close figure window(s).

     When called with no arguments, close the current figure.  This is
     equivalent to ‘close (gcf)’.  If the input H is a graphic handle,
     or vector of graphics handles, then close each figure in H.  The
     figure to close may also be specified by name FIGNAME which is
     matched against the "Name" property of all figures.

     If the argument "all" is given then all figures with visible
     handles (HandleVisibility = "on") are closed.

     If the additional argument "hidden" is given then all figures,
     including hidden ones, are closed.

     If the additional argument "force" is given then figures are closed
     even when "closerequestfcn" has been altered to prevent closing the
     window.

     Implementation Note: ‘close’ operates by making the handle H the
     current figure, and then calling the function specified by the
     "closerequestfcn" property of the figure.  By default, the function
     ‘closereq’ is used.  It is possible that the function invoked will
     delay or abort removing the figure.  To remove a figure without
     executing any callback functions use ‘delete’.  When writing a
     callback function to close a window do not use ‘close’ to avoid
     recursion.

     See also: *note closereq: XREFclosereq, *note delete: XREFdelete.

 -- : closereq ()
     Close the current figure and delete all graphics objects associated
     with it.

     By default, the "closerequestfcn" property of a new plot figure
     points to this function.

     See also: *note close: XREFclose, *note delete: XREFdelete.

