This is octave.info, produced by makeinfo version 5.2 from octave.texi. START-INFO-DIR-ENTRY * Octave: (octave). Interactive language for numerical computations. END-INFO-DIR-ENTRY Copyright (C) 1996-2013 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: 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'. -- Built-in Function: [VAL, COUNT, ERRMSG] = fscanf (FID, TEMPLATE, SIZE) -- Built-in Function: [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. -- Built-in Function: [VAL, COUNT, ERRMSG] = scanf (TEMPLATE, SIZE) -- Built-in Function: [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. -- Built-in Function: [VAL, COUNT, ERRMSG, POS] = sscanf (STRING, TEMPLATE, SIZE) -- Built-in Function: [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. Unlike the C language 'scanf', Octave ignores the 'h', 'l', and 'L' modifiers.  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. -- Built-in Function: VAL = fread (FID) -- Built-in Function: VAL = fread (FID, SIZE) -- Built-in Function: VAL = fread (FID, SIZE, PRECISION) -- Built-in Function: VAL = fread (FID, SIZE, PRECISION, SKIP) -- Built-in Function: VAL = fread (FID, SIZE, PRECISION, SKIP, ARCH) -- Built-in Function: [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 "schar" "signed char" Signed character. "uchar" "unsigned char" Unsigned character. "int8" "integer*1" 8-bit signed integer. "int16" "integer*2" 16-bit signed integer. "int32" "integer*4" 32-bit signed integer. "int64" "integer*8" 64-bit signed integer. "uint8" 8-bit unsigned integer. "uint16" 16-bit unsigned integer. "uint32" 32-bit unsigned integer. "uint64" 64-bit unsigned integer. "single" "float32" "real*4" 32-bit floating point number. "double" "float64" "real*8" 64-bit floating point number. "char" "char*1" Single character. "short" Short integer (size is platform dependent). "int" Integer (size is platform dependent). "long" Long integer (size is platform dependent). "ushort" "unsigned short" Unsigned short integer (size is platform dependent). "uint" "unsigned int" Unsigned integer (size is platform dependent). "ulong" "unsigned long" Unsigned long integer (size is platform dependent). "float" Single precision floating point number (size is platform dependent). The default precision is "uchar". 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" The format of the current machine. "ieee-be" IEEE big endian. "ieee-le" IEEE little endian. 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. -- Built-in Function: fwrite (FID, DATA) -- Built-in Function: fwrite (FID, DATA, PRECISION) -- Built-in Function: fwrite (FID, DATA, PRECISION, SKIP) -- Built-in Function: fwrite (FID, DATA, PRECISION, SKIP, ARCH) -- Built-in Function: 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. -- Built-in Function: [FID, NAME, MSG] = mkstemp ("TEMPLATE") -- Built-in Function: [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. -- Built-in Function: [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. -- Built-in Function: FNAME = tempname () -- Built-in Function: FNAME = tempname (DIR) -- Built-in Function: FNAME = tempname (DIR, PREFIX) Return a unique temporary file name 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. -- Function File: 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. -- Built-in Function: 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. -- Built-in Function: 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. -- Built-in Function: MSG = ferror (FID) -- Built-in Function: [MSG, ERR] = ferror (FID) -- Built-in Function: [DOTS] = 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. -- Built-in Function: fclear (FID) Clear the stream state for the file specified by the file descriptor FID. See also: *note ferror: XREFferror, *note fopen: XREFfopen. -- Built-in Function: 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. -- Built-in Function: 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. -- Built-in Function: fseek (FID, OFFSET) -- Built-in Function: fseek (FID, OFFSET, ORIGIN) -- Built-in Function: 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_CUR' (current position), 'SEEK_SET' (beginning), or 'SEEK_END' (end of file) or strings "cof", "bof" 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. -- Built-in Function: SEEK_SET () -- Built-in Function: SEEK_CUR () -- Built-in Function: SEEK_END () Return the numerical value to pass to 'fseek' to perform one of the following actions: 'SEEK_SET' Position file relative to the beginning. 'SEEK_CUR' Position file relative to the current position. 'SEEK_END' Position file relative to the end. See also: *note fseek: XREFfseek. -- Built-in Function: frewind (FID) -- Built-in Function: 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 ("fltk")' selects the FLTK/OpenGL system, and 'graphics_toolkit ("gnuplot")' selects the gnuplot system. The two 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 FLTK toolkit uses 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)); 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 src="plot.png" text=" +---------------------------------+ | Image unavailable in text mode. | +---------------------------------+"] Figure 15.1: Simple Two-Dimensional Plot. -- Function File: plot (Y) -- Function File: plot (X, Y) -- Function File: plot (X, Y, FMT) -- Function File: plot (..., PROPERTY, VALUE, ...) -- Function File: plot (X1, Y1, ..., XN, YN) -- Function File: plot (HAX, ...) -- Function File: 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". The FMT format argument can also be used to control the plot style. The format is composed of three parts: linestyle, markerstyle, color. When a markerstyle is specified, but no linestyle, only the markers are plotted. Similarly, if a linestyle is specified, but no markerstyle, 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. markerstyle '+' 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 'm' Magenta 'c' Cyan 'w' White ";key;" Here "key" is the label to use for the plot legend. The FMT argument may also be used to assign legend keys. 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 axis, 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. -- Function File: plotyy (X1, Y1, X2, Y2) -- Function File: plotyy (..., FUN) -- Function File: plotyy (..., FUN1, FUN2) -- Function File: plotyy (HAX, ...) -- Function File: [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 axis in which to plot the X1 and Y1 data. The return value AX is a vector with the axis 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. -- Function File: semilogx (Y) -- Function File: semilogx (X, Y) -- Function File: semilogx (X, Y, PROPERTY, VALUE, ...) -- Function File: semilogx (X, Y, FMT) -- Function File: semilogx (HAX, ...) -- Function File: 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 axis, 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. -- Function File: semilogy (Y) -- Function File: semilogy (X, Y) -- Function File: semilogy (X, Y, PROPERTY, VALUE, ...) -- Function File: semilogy (X, Y, FMT) -- Function File: semilogy (H, ...) -- Function File: 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 axis, 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. -- Function File: loglog (Y) -- Function File: loglog (X, Y) -- Function File: loglog (X, Y, PROP, VALUE, ...) -- Function File: loglog (X, Y, FMT) -- Function File: loglog (HAX, ...) -- Function File: 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 axis, 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, hist (randn (10000, 1), 30); produces the histogram of 10,000 normally distributed random numbers shown in *note Figure 15.2: fig:hist. [image src="hist.png" text=" +---------------------------------+ | Image unavailable in text mode. | +---------------------------------+"] Figure 15.2: Histogram. -- Function File: bar (Y) -- Function File: bar (X, Y) -- Function File: bar (..., W) -- Function File: bar (..., STYLE) -- Function File: bar (..., PROP, VAL, ...) -- Function File: bar (HAX, ...) -- Function File: 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 axis, 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. -- Function File: barh (Y) -- Function File: barh (X, Y) -- Function File: barh (..., W) -- Function File: barh (..., STYLE) -- Function File: barh (..., PROP, VAL, ...) -- Function File: barh (HAX, ...) -- Function File: 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 axis, 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. -- Function File: hist (Y) -- Function File: hist (Y, X) -- Function File: hist (Y, NBINS) -- Function File: hist (Y, X, NORM) -- Function File: hist (..., PROP, VAL, ...) -- Function File: hist (HAX, ...) -- Function File: [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. With one matrix input argument, Y, plot a histogram where each bin contains a bar per input column. Given a second vector argument, X, use that as the centers of the bins, with the width of the bins determined from the adjacent values in the vector. If scalar, the second argument, NBINS, defines the number of bins. If a third argument is provided, the histogram is normalized such that the sum of the bars is equal to NORM. Extreme values are lumped into the first and last bins. 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 axis, rather than the current axes returned by 'gca'. With two output arguments, produce 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. -- Function File: stemleaf (X, CAPTION) -- Function File: stemleaf (X, CAPTION, STEM_SZ) -- Function File: 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: Ch. 3, 'Exploratory Data Analysis' by J. W. Tukey, Addison-Wesley, 1977. See also: *note hist: XREFhist, *note printd: XREFprintd. -- Function File: printd (OBJ, FILENAME) -- Function File: 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. -- Function File: stairs (Y) -- Function File: stairs (X, Y) -- Function File: stairs (..., STYLE) -- Function File: stairs (..., PROP, VAL, ...) -- Function File: stairs (HAX, ...) -- Function File: H = stairs (...) -- Function File: [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. 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 axis handle, then plot into this axis, rather than the current axis handle 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. -- Function File: stem (Y) -- Function File: stem (X, Y) -- Function File: stem (..., LINESPEC) -- Function File: stem (..., "filled") -- Function File: stem (..., PROP, VAL, ...) -- Function File: stem (HAX, ...) -- Function File: 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 axis, 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. -- Function File: stem3 (X, Y, Z) -- Function File: stem3 (..., LINESPEC) -- Function File: stem3 (..., "filled") -- Function File: stem3 (..., PROP, VAL, ...) -- Function File: stem3 (HAX, ...) -- Function File: 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 axis, 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. -- Function File: scatter (X, Y) -- Function File: scatter (X, Y, S) -- Function File: scatter (X, Y, S, C) -- Function File: scatter (..., STYLE) -- Function File: scatter (..., "filled") -- Function File: scatter (..., PROP, VAL, ...) -- Function File: scatter (HAX, ...) -- Function File: 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 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 axis, rather than the current axes returned by 'gca'. The optional return value H is a graphics handle to the created patch 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. -- Function File: plotmatrix (X, Y) -- Function File: plotmatrix (X) -- Function File: plotmatrix (..., STYLE) -- Function File: plotmatrix (HAX, ...) -- Function File: [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 axis, 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 axis objects. BIGAX is a hidden axis object that surrounds the other axes, such that the commands 'xlabel', 'title', etc., will be associated with this hidden axis. 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. -- Function File: pareto (Y) -- Function File: pareto (Y, X) -- Function File: pareto (HAX, ...) -- Function File: 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 axis, 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. -- Function File: rose (TH) -- Function File: rose (TH, NBINS) -- Function File: rose (TH, BINS) -- Function File: rose (HAX, ...) -- Function File: H = rose (...) -- Function File: [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 of 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 axis, 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. [th, r] = rose ([2*randn(1e5,1), pi + 2*randn(1e5,1)]); polar (th, r); See also: *note hist: XREFhist, *note polar: XREFpolar. The 'contour', 'contourf' and 'contourc' functions produce two-dimensional contour plots from three-dimensional data. -- Function File: contour (Z) -- Function File: contour (Z, VN) -- Function File: contour (X, Y, Z) -- Function File: contour (X, Y, Z, VN) -- Function File: contour (..., STYLE) -- Function File: contour (HAX, ...) -- Function File: [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 axis, 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:2; y = x; z = x' * y; 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. -- Function File: contourf (Z) -- Function File: contourf (Z, VN) -- Function File: contourf (X, Y, Z) -- Function File: contourf (X, Y, Z, VN) -- Function File: contourf (..., STYLE) -- Function File: contourf (HAX, ...) -- Function File: [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 axis, 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. -- Function File: [C, LEV] = contourc (Z) -- Function File: [C, LEV] = contourc (Z, VN) -- Function File: [C, LEV] = contourc (X, Y, Z) -- Function File: [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:rows (Z)' and Y is taken to be '1:columns (Z)'. 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; contourc (x, y, z, 2:3) => 2.0000 2.0000 1.0000 3.0000 1.5000 2.0000 2.0000 1.0000 2.0000 2.0000 2.0000 1.5000 See also: *note contour: XREFcontour, *note contourf: XREFcontourf, *note contour3: XREFcontour3, *note clabel: XREFclabel. -- Function File: contour3 (Z) -- Function File: contour3 (Z, VN) -- Function File: contour3 (X, Y, Z) -- Function File: contour3 (X, Y, Z, VN) -- Function File: contour3 (..., STYLE) -- Function File: contour3 (HAX, ...) -- Function File: [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 axis, 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, x = 0:0.1:10; y = sin (x); yp = 0.1 .* randn (size (x)); ym = -0.1 .* randn (size (x)); errorbar (x, sin (x), ym, yp); produces the figure shown in *note Figure 15.3: fig:errorbar. [image src="errorbar.png" text=" +---------------------------------+ | Image unavailable in text mode. | +---------------------------------+"] Figure 15.3: Errorbar plot. -- Function File: errorbar (Y, EY) -- Function File: errorbar (Y, ..., FMT) -- Function File: errorbar (X, Y, EY) -- Function File: errorbar (X, Y, ERR, FMT) -- Function File: errorbar (X, Y, LERR, UERR, FMT) -- Function File: errorbar (X, Y, EX, EY, FMT) -- Function File: errorbar (X, Y, LX, UX, LY, UY, FMT) -- Function File: errorbar (X1, Y1, ..., FMT, XN, YN, ...) -- Function File: errorbar (HAX, ...) -- Function File: 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 axis, 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. -- Function File: semilogxerr (Y, EY) -- Function File: semilogxerr (Y, ..., FMT) -- Function File: semilogxerr (X, Y, EY) -- Function File: semilogxerr (X, Y, ERR, FMT) -- Function File: semilogxerr (X, Y, LERR, UERR, FMT) -- Function File: semilogxerr (X, Y, EX, EY, FMT) -- Function File: semilogxerr (X, Y, LX, UX, LY, UY, FMT) -- Function File: semilogxerr (X1, Y1, ..., FMT, XN, YN, ...) -- Function File: semilogxerr (HAX, ...) -- Function File: 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 axis, rather than the current axes returned by 'gca'. See also: *note errorbar: XREFerrorbar, *note semilogyerr: XREFsemilogyerr, *note loglogerr: XREFloglogerr. -- Function File: semilogyerr (Y, EY) -- Function File: semilogyerr (Y, ..., FMT) -- Function File: semilogyerr (X, Y, EY) -- Function File: semilogyerr (X, Y, ERR, FMT) -- Function File: semilogyerr (X, Y, LERR, UERR, FMT) -- Function File: semilogyerr (X, Y, EX, EY, FMT) -- Function File: semilogyerr (X, Y, LX, UX, LY, UY, FMT) -- Function File: semilogyerr (X1, Y1, ..., FMT, XN, YN, ...) -- Function File: semilogyerr (HAX, ...) -- Function File: 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 axis, rather than the current axes returned by 'gca'. See also: *note errorbar: XREFerrorbar, *note semilogxerr: XREFsemilogxerr, *note loglogerr: XREFloglogerr. -- Function File: loglogerr (Y, EY) -- Function File: loglogerr (Y, ..., FMT) -- Function File: loglogerr (X, Y, EY) -- Function File: loglogerr (X, Y, ERR, FMT) -- Function File: loglogerr (X, Y, LERR, UERR, FMT) -- Function File: loglogerr (X, Y, EX, EY, FMT) -- Function File: loglogerr (X, Y, LX, UX, LY, UY, FMT) -- Function File: loglogerr (X1, Y1, ..., FMT, XN, YN, ...) -- Function File: loglogerr (HAX, ...) -- Function File: 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 axis, 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); produces the spiral plot shown in *note Figure 15.4: fig:polar. [image src="polar.png" text=" +---------------------------------+ | Image unavailable in text mode. | +---------------------------------+"] Figure 15.4: Polar plot. -- Function File: polar (THETA, RHO) -- Function File: polar (THETA, RHO, FMT) -- Function File: polar (CPLX) -- Function File: polar (CPLX, FMT) -- Function File: polar (HAX, ...) -- Function File: H = polar (...) Create a 2-D plot from polar coordinates THETA and RHO. 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 axis, 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. -- Function File: pie (X) -- Function File: pie (..., EXPLODE) -- Function File: pie (..., LABELS) -- Function File: pie (HAX, ...); -- Function File: 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 axis, 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. -- Function File: pie3 (X) -- Function File: pie3 (..., EXPLODE) -- Function File: pie3 (..., LABELS) -- Function File: pie3 (HAX, ...); -- Function File: 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 axis, 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. -- Function File: quiver (U, V) -- Function File: quiver (X, Y, U, V) -- Function File: quiver (..., S) -- Function File: quiver (..., STYLE) -- Function File: quiver (..., "filled") -- Function File: quiver (HAX, ...) -- Function File: H = quiver (...) Plot a 2-D vector field with arrows. Plot the (U, V) components of a vector field in an (X, Y) meshgrid. If the grid is uniform then X and Y can be specified as vectors. If X and Y are undefined they are assumed to be '(1:M, 1:N)' where '[M, N] = size (U)'. The variable S is a scalar defining a scaling factor to use for the arrows of the field relative to the mesh spacing. 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 markers at the grid points of the vectors are drawn rather than arrows. If the argument "filled" is given then the markers are filled. If the first argument HAX is an axes handle, then plot into this axis, 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. -- Function File: quiver3 (U, V, W) -- Function File: quiver3 (X, Y, Z, U, V, W) -- Function File: quiver3 (..., S) -- Function File: quiver3 (..., STYLE) -- Function File: quiver3 (..., "filled") -- Function File: quiver3 (HAX, ...) -- Function File: H = quiver3 (...) Plot a 3-D vector field with arrows. Plot the (U, V, W) components of a vector field in an (X, Y, Z) meshgrid. If the grid is uniform then X, Y, and Z can be specified as vectors. If X, Y, and Z are undefined they are assumed to be '(1:M, 1:N, 1:P)' where '[M, N] = size (U)' and 'P = max (size (W))'. The variable S is a scalar defining a scaling factor to use for the arrows of the field relative to the mesh spacing. 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 markers at the grid points of the vectors are drawn rather than arrows. If the argument "filled" is given then the markers are filled. If the first argument HAX is an axes handle, then plot into this axis, 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. -- Function File: compass (U, V) -- Function File: compass (Z) -- Function File: compass (..., STYLE) -- Function File: compass (HAX, ...) -- Function File: 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 axis, 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. -- Function File: feather (U, V) -- Function File: feather (Z) -- Function File: feather (..., STYLE) -- Function File: feather (HAX, ...) -- Function File: 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 axis, 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. -- Function File: pcolor (X, Y, C) -- Function File: pcolor (C) -- Function File: pcolor (HAX, ...) -- Function File: 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 axis, 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. -- Function File: area (Y) -- Function File: area (X, Y) -- Function File: area (..., LVL) -- Function File: area (..., PROP, VAL, ...) -- Function File: area (HAX, ...) -- Function File: 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 axis, 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. -- Function File: fill (X, Y, C) -- Function File: fill (X1, Y1, C1, X2, Y2, C2) -- Function File: fill (..., PROP, VAL) -- Function File: fill (HAX, ...) -- Function File: 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 axis, 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. -- Function File: comet (Y) -- Function File: comet (X, Y) -- Function File: comet (X, Y, P) -- Function File: 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 axis, rather than the current axes returned by 'gca'. See also: *note comet3: XREFcomet3. -- Function File: comet3 (Z) -- Function File: comet3 (X, Y, Z) -- Function File: comet3 (X, Y, Z, P) -- Function File: 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 axis, rather than the current axes returned by 'gca'. See also: *note comet: XREFcomet. -- Function File: [X, MAP] = frame2im (F) Convert movie frame to indexed image. A movie frame is simply a struct with the fields "cdata" and "colormap". Support for N-dimensional images or movies is given when F is a struct array. In such cases, X will be a MxNx1xK or MxNx3xK for indexed and RGB movies respectively, with each frame concatenated along the 4th dimension. See also: *note im2frame: XREFim2frame. -- Function File: im2frame (RGB) -- Function File: im2frame (X, MAP) Convert image to movie frame. A movie frame is simply a struct with the fields "cdata" and "colormap". Support for N-dimensional images is given when each image projection, matrix sizes of MxN and MxNx3 for RGB images, is concatenated along the fourth dimension. In such cases, the returned value is a struct array. See also: *note frame2im: XREFframe2im.  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. -- Function File: axis () -- Function File: axis ([X_lo X_hi]) -- Function File: axis ([X_lo X_hi Y_lo Y_hi]) -- Function File: axis ([X_lo X_hi Y_lo Y_hi Z_lo Z_hi]) -- Function File: axis (OPTION) -- Function File: axis (..., OPTION) -- Function File: axis (HAX, ...) -- Function File: LIMITS = axis () Set axis limits and appearance. The argument LIMITS should be a 2-, 4-, or 6-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, and the fifth and sixth specify the limits for the z-axis. The special values -Inf and Inf may be used to indicate that the limit should automatically be computed based on the data in the axis. 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. For example, axis ([1, 2, 3, 4], "square"); forces a square aspect ratio, and axis ("tic", "labely"); turns tic marks on for all axes and tic mark labels on for the y-axis only. The following options control the aspect ratio of the axes. "square" Force a square aspect ratio. "equal" Force x distance to equal y-distance. "normal" Restore default aspect ratio. The following options control the way axis limits are interpreted. "auto" 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". The following options affect the appearance of tic marks. "on" Turn tic marks and labels on for all axes. "off" Turn tic marks off for all axes. "tic[xyz]" Turn tic marks on for all axes, or turn them on for the specified axes and off for the remainder. "label[xyz]" Turn tic labels on for all axes, or turn them on for the specified axes and off for the remainder. "nolabel" Turn tic labels off for all axes. Note, if there are no tic marks for an axis, there can be no labels. The following options affect the direction of increasing values on the axes. "ij" Reverse y-axis, so lower values are nearer the top. "xy" Restore y-axis, so higher values are nearer the top. 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 xlim: XREFxlim, *note ylim: XREFylim, *note zlim: XREFzlim, *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. -- Function File: caxis ([cmin cmax]) -- Function File: caxis ("auto") -- Function File: caxis ("manual") -- Function File: caxis (HAX, ...) -- Function File: 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 axis rather than the current axes returned by 'gca'. Called without arguments the current color axis limits are returned. See also: *note colormap: XREFcolormap. The 'xlim', 'ylim', and 'zlim' functions may be used to get or set individual axis limits. Each has the same form. -- Function File: XLIMITS = xlim () -- Function File: XMODE = xlim ("mode") -- Function File: xlim ([X_LO X_HI]) -- Function File: xlim ("auto") -- Function File: xlim ("manual") -- Function File: 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 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 axis rather than the current axes returned by 'gca'. See also: *note ylim: XREFylim, *note zlim: XREFzlim, *note axis: XREFaxis, *note set: XREFset, *note get: XREFget, *note gca: XREFgca.  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. -- Function File: fplot (FN, LIMITS) -- Function File: fplot (..., TOL) -- Function File: fplot (..., N) -- Function File: fplot (..., FMT) -- Function File: [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]'. 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. If the first argument HAX is an axes handle, then plot into this axis, 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' requires that the function accept and return a vector argument. Consider this when writing user-defined functions and use '.*', './', 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'. -- Function File: ezplot (F) -- Function File: ezplot (F2V) -- Function File: ezplot (FX, FY) -- Function File: ezplot (..., DOM) -- Function File: ezplot (..., N) -- Function File: ezplot (HAX, ...) -- Function File: 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 axis, 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. -- Function File: ezcontour (F) -- Function File: ezcontour (..., DOM) -- Function File: ezcontour (..., N) -- Function File: ezcontour (HAX, ...) -- Function File: 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 axis, 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. -- Function File: ezcontourf (F) -- Function File: ezcontourf (..., DOM) -- Function File: ezcontourf (..., N) -- Function File: ezcontourf (HAX, ...) -- Function File: 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 axis, 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. -- Function File: ezpolar (F) -- Function File: ezpolar (..., DOM) -- Function File: ezpolar (..., N) -- Function File: ezpolar (HAX, ...) -- Function File: 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 axis, 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 ......................................... -- Function File: rectangle () -- Function File: rectangle (..., "Position", POS) -- Function File: rectangle (..., "Curvature", CURV) -- Function File: rectangle (..., "EdgeColor", EC) -- Function File: rectangle (..., "FaceColor", FC) -- Function File: rectangle (HAX, ...) -- Function File: 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 axis, 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); 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 src="mesh.png" text=" +---------------------------------+ | 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); displays the spiral in three dimensions shown in *note Figure 15.6: fig:plot3. [image src="plot3.png" text=" +---------------------------------+ | Image unavailable in text mode. | +---------------------------------+"] Figure 15.6: Three-dimensional spiral. Finally, the 'view' function changes the viewpoint for three-dimensional plots. -- Function File: mesh (X, Y, Z) -- Function File: mesh (Z) -- Function File: mesh (..., C) -- Function File: mesh (..., PROP, VAL, ...) -- Function File: mesh (HAX, ...) -- Function File: 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 axis, 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. -- Function File: meshc (X, Y, Z) -- Function File: meshc (Z) -- Function File: meshc (..., C) -- Function File: meshc (..., PROP, VAL, ...) -- Function File: meshc (HAX, ...) -- Function File: 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 axis, 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. -- Function File: meshz (X, Y, Z) -- Function File: meshz (Z) -- Function File: meshz (..., C) -- Function File: meshz (..., PROP, VAL, ...) -- Function File: meshz (HAX, ...) -- Function File: 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 = 0:columns (Z) - 1, Y = 0:rows (Z) - 1'. 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 axis, 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. -- Command: hidden -- Command: hidden on -- Command: hidden off -- Function File: 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. -- Function File: surf (X, Y, Z) -- Function File: surf (Z) -- Function File: surf (..., C) -- Function File: surf (..., PROP, VAL, ...) -- Function File: surf (HAX, ...) -- Function File: 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 axis, 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. -- Function File: surfc (X, Y, Z) -- Function File: surfc (Z) -- Function File: surfc (..., C) -- Function File: surfc (..., PROP, VAL, ...) -- Function File: surfc (HAX, ...) -- Function File: 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 axis, 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. -- Function File: surfl (Z) -- Function File: surfl (X, Y, Z) -- Function File: surfl (..., LSRC) -- Function File: surfl (X, Y, Z, LSRC, P) -- Function File: surfl (..., "cdata") -- Function File: surfl (..., "light") -- Function File: surfl (HAX, ...) -- Function File: 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. *Warning:* The alternative mode "light" mode which creates a light object to illuminate the surface is not implemented (yet). The light source location can be specified using LSRC. It can be given as a 2-element vector [azimuth, elevation] in degrees, or as 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 axis, 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. -- Function File: surfnorm (X, Y, Z) -- Function File: surfnorm (Z) -- Function File: surfnorm (..., PROP, VAL, ...) -- Function File: surfnorm (HAX, ...) -- Function File: [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:rows (Z)' and Y is '1:columns (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 axis, 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. 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 quadrilaterals in the meshgrid to find the normal vectors of the centers of these quadrilaterals. The four nearest normal vectors to the meshgrid points are then averaged to obtain the normal to the surface at the meshgridded points. See also: *note isonormals: XREFisonormals, *note quiver3: XREFquiver3, *note surf: XREFsurf, *note meshgrid: XREFmeshgrid. -- Function File: [FV] = isosurface (VAL, ISO) -- Function File: [FV] = isosurface (X, Y, Z, VAL, ISO) -- Function File: [FV] = isosurface (..., "noshare", "verbose") -- Function File: [FVC] = isosurface (..., COL) -- Function File: [F, V] = isosurface (X, Y, Z, VAL, ISO) -- Function File: [F, V, C] = isosurface (X, Y, Z, VAL, ISO, COL) -- Function File: isosurface (X, Y, Z, VAL, ISO, COL, OPT) Calculate isosurface of 3-D data. If called with one output argument and the first input argument VAL is a three-dimensional array that contains the data of an isosurface geometry and the second input argument ISO keeps the isovalue as a scalar value then return a structure array FV that contains the fields FACES and VERTICES at computed points '[x, y, z] = meshgrid (1:l, 1:m, 1:n)'. The output argument FV can directly be taken as an input argument for the 'patch' function. If called with further input arguments X, Y and Z which are three-dimensional arrays with the same size than VAL then the volume data is taken at those given points. The string input argument "noshare" is only for compatibility and has no effect. If given the string input argument "verbose" then print messages to the command line interface about the current progress. If called with the input argument COL which is a three-dimensional array of the same size than VAL then take those values for the interpolation of coloring the isosurface geometry. Add the field FACEVERTEXCDATA to the structure array FV. If called with two or three output arguments then 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 then directly process the isosurface geometry with the 'patch' command. For example, [x, y, z] = meshgrid (1:5, 1:5, 1:5); val = rand (5, 5, 5); isosurface (x, y, z, val, .5); will directly draw a random isosurface geometry in a graphics window. Another example for 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); c = abs ((x-.5).^2 + (y-.5).^2 + (z-.5).^2); figure (); # Open another figure window subplot (2,2,1); view (-38, 20); [f, v] = isosurface (x, y, z, c, iso); p = patch ("Faces", f, "Vertices", v, "EdgeColor", "none"); set (gca, "PlotBoxAspectRatioMode", "manual", ... "PlotBoxAspectRatio", [1 1 1]); # set (p, "FaceColor", "green", "FaceLighting", "phong"); # light ("Position", [1 1 5]); # Available with the JHandles package subplot (2,2,2); view (-38, 20); p = patch ("Faces", f, "Vertices", v, "EdgeColor", "blue"); set (gca, "PlotBoxAspectRatioMode", "manual", ... "PlotBoxAspectRatio", [1 1 1]); # set (p, "FaceColor", "none", "FaceLighting", "phong"); # light ("Position", [1 1 5]); subplot (2,2,3); view (-38, 20); [f, v, c] = isosurface (x, y, z, c, iso, y); p = patch ("Faces", f, "Vertices", v, "FaceVertexCData", c, ... "FaceColor", "interp", "EdgeColor", "none"); set (gca, "PlotBoxAspectRatioMode", "manual", ... "PlotBoxAspectRatio", [1 1 1]); # set (p, "FaceLighting", "phong"); # light ("Position", [1 1 5]); subplot (2,2,4); view (-38, 20); p = patch ("Faces", f, "Vertices", v, "FaceVertexCData", c, ... "FaceColor", "interp", "EdgeColor", "blue"); set (gca, "PlotBoxAspectRatioMode", "manual", ... "PlotBoxAspectRatio", [1 1 1]); # set (p, "FaceLighting", "phong"); # light ("Position", [1 1 5]); See also: *note isonormals: XREFisonormals, *note isocolors: XREFisocolors. -- Function File: [N] = isonormals (VAL, V) -- Function File: [N] = isonormals (VAL, P) -- Function File: [N] = isonormals (X, Y, Z, VAL, V) -- Function File: [N] = isonormals (X, Y, Z, VAL, P) -- Function File: [N] = isonormals (..., "negate") -- Function File: isonormals (..., P) Calculate normals to an isosurface. If called with one output argument and the first input argument VAL is a three-dimensional array that contains the data for an isosurface geometry and the second input argument V keeps the vertices of an isosurface then return the normals N in form of a matrix with the same size than V at computed points '[x, y, z] = meshgrid (1:l, 1:m, 1:n)'. The output argument N can be taken to manually set VERTEXNORMALS of a patch. If called with further input arguments X, Y and Z which are three-dimensional arrays with the same size than VAL then the volume data is taken at those given points. Instead of the vertices data V a patch handle P can be passed to this function. If given the string input argument "negate" as last input argument then compute the reverse vector normals of an isosurface geometry. If no output argument is given then directly redraw the patch that is given by the patch handle P. For example: function [] = isofinish (p) set (gca, "PlotBoxAspectRatioMode", "manual", ... "PlotBoxAspectRatio", [1 1 1]); set (p, "VertexNormals", -get (p,"VertexNormals")); # Revert normals set (p, "FaceColor", "interp"); ## set (p, "FaceLighting", "phong"); ## light ("Position", [1 1 5]); # Available with JHandles endfunction 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); c = abs ((x-.5).^2 + (y-.5).^2 + (z-.5).^2); figure (); # Open another figure window subplot (2,2,1); view (-38, 20); [f, v, cdat] = isosurface (x, y, z, c, iso, y); p = patch ("Faces", f, "Vertices", v, "FaceVertexCData", cdat, ... "FaceColor", "interp", "EdgeColor", "none"); isofinish (p); # Call user function isofinish subplot (2,2,2); view (-38, 20); p = patch ("Faces", f, "Vertices", v, "FaceVertexCData", cdat, ... "FaceColor", "interp", "EdgeColor", "none"); isonormals (x, y, z, c, p); # Directly modify patch isofinish (p); subplot (2,2,3); view (-38, 20); p = patch ("Faces", f, "Vertices", v, "FaceVertexCData", cdat, ... "FaceColor", "interp", "EdgeColor", "none"); n = isonormals (x, y, z, c, v); # Compute normals of isosurface set (p, "VertexNormals", n); # Manually set vertex normals isofinish (p); subplot (2,2,4); view (-38, 20); p = patch ("Faces", f, "Vertices", v, "FaceVertexCData", cdat, ... "FaceColor", "interp", "EdgeColor", "none"); isonormals (x, y, z, c, v, "negate"); # Use reverse directly isofinish (p); See also: *note isosurface: XREFisosurface, *note isocolors: XREFisocolors. -- Function File: [CD] = isocolors (C, V) -- Function File: [CD] = isocolors (X, Y, Z, C, V) -- Function File: [CD] = isocolors (X, Y, Z, R, G, B, V) -- Function File: [CD] = isocolors (R, G, B, V) -- Function File: [CD] = isocolors (..., P) -- Function File: isocolors (...) Compute isosurface colors. If called with one output argument and the first input argument C is a three-dimensional array that contains color values and the second input argument V keeps the vertices of a geometry then return a matrix CD with color data information for the geometry at computed points '[x, y, z] = meshgrid (1:l, 1:m, 1:n)'. The output argument CD can be taken to manually set FaceVertexCData of a patch. If called with further input arguments X, Y and Z which are three-dimensional arrays of the same size than C then the color data is taken at those given points. Instead of the color data C this function can also be called with RGB values R, G, B. If input argumnets X, Y, Z are not given then again 'meshgrid' computed values are taken. Optionally, the patch handle P can be given as the last input argument to all variations of function calls instead of the vertices data V. Finally, if no output argument is given then directly change the colors of a patch that is given by the patch handle P. For example: function [] = isofinish (p) set (gca, "PlotBoxAspectRatioMode", "manual", ... "PlotBoxAspectRatio", [1 1 1]); set (p, "FaceColor", "interp"); ## set (p, "FaceLighting", "flat"); ## light ("Position", [1 1 5]); # Available with JHandles endfunction 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); c = abs ((x-.5).^2 + (y-.5).^2 + (z-.5).^2); figure (); # Open another figure window subplot (2,2,1); view (-38, 20); [f, v] = isosurface (x, y, z, c, iso); p = patch ("Faces", f, "Vertices", v, "EdgeColor", "none"); cdat = rand (size (c)); # Compute random patch color data isocolors (x, y, z, cdat, p); # Directly set colors of patch isofinish (p); # Call user function isofinish subplot (2,2,2); view (-38, 20); p = patch ("Faces", f, "Vertices", v, "EdgeColor", "none"); [r, g, b] = meshgrid (lin, 2-lin, 2-lin); cdat = isocolors (x, y, z, c, v); # Compute color data vertices set (p, "FaceVertexCData", cdat); # Set color data manually isofinish (p); subplot (2,2,3); view (-38, 20); p = patch ("Faces", f, "Vertices", v, "EdgeColor", "none"); cdat = isocolors (r, g, b, c, p); # Compute color data patch set (p, "FaceVertexCData", cdat); # Set color data manually isofinish (p); subplot (2,2,4); view (-38, 20); p = patch ("Faces", f, "Vertices", v, "EdgeColor", "none"); r = g = b = repmat ([1:N] / N, [N, 1, N]); # Black to white cdat = isocolors (x, y, z, r, g, b, v); set (p, "FaceVertexCData", cdat); isofinish (p); See also: *note isosurface: XREFisosurface, *note isonormals: XREFisonormals. -- Function File: shrinkfaces (P, SF) -- Function File: NFV = shrinkfaces (P, SF) -- Function File: NFV = shrinkfaces (FV, SF) -- Function File: NFV = shrinkfaces (F, V, SF) -- Function File: [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. -- Function File: 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. -- Function File: specular (SX, SY, SZ, LV, VV) -- Function File: 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. -- Function File: [XX, YY] = meshgrid (X, Y) -- Function File: [XX, YY, ZZ] = meshgrid (X, Y, Z) -- Function File: [XX, YY] = meshgrid (X) -- Function File: [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. '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. -- Function File: [Y1, Y2, ..., Yn] = ndgrid (X1, X2, ..., Xn) -- Function File: [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. -- Function File: plot3 (X, Y, Z) -- Function File: plot3 (X, Y, Z, PROP, VALUE, ...) -- Function File: plot3 (X, Y, Z, FMT) -- Function File: plot3 (X, CPLX) -- Function File: plot3 (CPLX) -- Function File: plot3 (HAX, ...) -- Function File: 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 axis, 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. -- Function File: view (AZIMUTH, ELEVATION) -- Function File: view ([AZIMUTH ELEVATION]) -- Function File: view ([X Y Z]) -- Function File: view (2) -- Function File: view (3) -- Function File: view (HAX, ...) -- Function File: [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 axis rather than the current axes returned by 'gca'. If no inputs are given, return the current AZIMUTH and ELEVATION. -- Function File: slice (X, Y, Z, V, SX, SY, SZ) -- Function File: slice (X, Y, Z, V, XI, YI, ZI) -- Function File: slice (V, SX, SY, SZ) -- Function File: slice (V, XI, YI, ZI) -- Function File: slice (..., METHOD) -- Function File: slice (HAX, ...) -- Function File: 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 axis, 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. -- Function File: ribbon (Y) -- Function File: ribbon (X, Y) -- Function File: ribbon (X, Y, WIDTH) -- Function File: ribbon (HAX, ...) -- Function File: H = ribbon (...) Draw a ribbon plot for the columns of Y vs. X. The optional parameter WIDTH specifies the width of a single ribbon (default is 0.75). If X is omitted, a vector containing the row numbers is assumed ('1:rows (Y)'). If the first argument HAX is an axes handle, then plot into this axis, 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. -- Function File: shading (TYPE) -- Function File: 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 visible edges. "interp" Color between patch vertices are interpolated and the patch edges are invisible. If the first argument HAX is an axes handle, then plot into this axis, 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. -- Function File: scatter3 (X, Y, Z) -- Function File: scatter3 (X, Y, Z, S) -- Function File: scatter3 (X, Y, Z, S, C) -- Function File: scatter3 (..., STYLE) -- Function File: scatter3 (..., "filled") -- Function File: scatter3 (..., PROP, VAL) -- Function File: scatter3 (HAX, ...) -- Function File: 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 axis, 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. -- Function File: waterfall (X, Y, Z) -- Function File: waterfall (Z) -- Function File: waterfall (..., C) -- Function File: waterfall (..., PROP, VAL, ...) -- Function File: waterfall (HAX, ...) -- Function File: 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 axis, 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. -- Function File: DATA_ASPECT_RATIO = daspect () -- Function File: daspect (DATA_ASPECT_RATIO) -- Function File: daspect (MODE) -- Function File: DATA_ASPECT_RATIO_MODE = daspect ("mode") -- Function File: 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. -- Function File: PLOT_BOX_ASPECT_RATIO = pbaspect ( ) -- Function File: pbaspect (PLOT_BOX_ASPECT_RATIO) -- Function File: pbaspect (MODE) -- Function File: PLOT_BOX_ASPECT_RATIO_MODE = pbaspect ("mode") -- Function File: 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 ............................................ -- Function File: ezplot3 (FX, FY, FZ) -- Function File: ezplot3 (..., DOM) -- Function File: ezplot3 (..., N) -- Function File: ezplot3 (HAX, ...) -- Function File: 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 first argument HAX is an axes handle, then plot into this axis, 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 ezplot: XREFezplot, *note ezmesh: XREFezmesh, *note ezsurf: XREFezsurf. -- Function File: ezmesh (F) -- Function File: ezmesh (FX, FY, FZ) -- Function File: ezmesh (..., DOM) -- Function File: ezmesh (..., N) -- Function File: ezmesh (..., "circ") -- Function File: ezmesh (HAX, ...) -- Function File: 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 axis, 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. -- Function File: ezmeshc (F) -- Function File: ezmeshc (FX, FY, FZ) -- Function File: ezmeshc (..., DOM) -- Function File: ezmeshc (..., N) -- Function File: ezmeshc (..., "circ") -- Function File: ezmeshc (HAX, ...) -- Function File: 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 axis, 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. -- Function File: ezsurf (F) -- Function File: ezsurf (FX, FY, FZ) -- Function File: ezsurf (..., DOM) -- Function File: ezsurf (..., N) -- Function File: ezsurf (..., "circ") -- Function File: ezsurf (HAX, ...) -- Function File: 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 axis, 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. -- Function File: ezsurfc (F) -- Function File: ezsurfc (FX, FY, FZ) -- Function File: ezsurfc (..., DOM) -- Function File: ezsurfc (..., N) -- Function File: ezsurfc (..., "circ") -- Function File: ezsurfc (HAX, ...) -- Function File: 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 axis, 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 ........................................... -- Command: cylinder -- Function File: cylinder (R) -- Function File: cylinder (R, N) -- Function File: cylinder (HAX, ...) -- Function File: [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 axis, 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. -- Function File: sphere () -- Function File: sphere (N) -- Function File: sphere (HAX, ...) -- Function File: [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 axis, 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. -- Function File: ellipsoid (XC, YC, ZC, XR, YR, ZR, N) -- Function File: ellipsoid (..., N) -- Function File: ellipsoid (HAX, ...) -- Function File: [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 axis, 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. -- Function File: title (STRING) -- Function File: title (STRING, PROP, VAL, ...) -- Function File: title (HAX, ...) -- Function File: 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 axis, 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. -- Function File: legend (STR1, STR2, ...) -- Function File: legend (MATSTR) -- Function File: legend (CELLSTR) -- Function File: legend (..., "location", POS) -- Function File: legend (..., "orientation", ORIENT) -- Function File: legend (HAX, ...) -- Function File: legend (HOBJS, ...) -- Function File: legend (HAX, HOBJS, ...) -- Function File: legend ("OPTION") -- Function File: [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. If the first argument HAX is an axes handle, then plot into this axis, rather than the current axes returned by 'gca'. If the handles, HOBJS, are not specified then the legend's strings will be associated with the axes' descendants. 'legend' works on line graphs, bar graphs, etc. A plot must exist before legend is called. 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 The optional parameter ORIENT determines if the key 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" Toggles 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 optional output values are HLEG The graphics handle of the legend object. HLEG_OBJ Graphics handles to the text and line objects which make up 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. The legend label text is either provided in the call to 'legend' or is taken from the DisplayName property of graphics objects. If no labels or DisplayNames are available, then the label text is simply "data1", "data2", ..., "dataN". Implementation Note: A legend is implemented as an additional axes object of the current figure with the "tag" set to "legend". Properties of the legend object may be manipulated directly by using 'set'. -- Function File: text (X, Y, STRING) -- Function File: text (X, Y, Z, STRING) -- Function File: text (..., PROP, VAL, ...) -- Function File: 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. 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. -- Function File: xlabel (STRING) -- Function File: xlabel (STRING, PROPERTY, VAL, ...) -- Function File: xlabel (HAX, ...) -- Function File: 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 axis 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. -- Function File: clabel (C, H) -- Function File: clabel (C, H, V) -- Function File: clabel (C, H, "manual") -- Function File: clabel (C) -- Function File: clabel (..., PROP, VAL, ...) -- Function File: 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. -- Command: box -- Command: box on -- Command: box off -- Function File: box (HAX, ...) Control display of the axis 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 axis rather than the current axes returned by 'gca'. See also: *note axis: XREFaxis, *note grid: XREFgrid. -- Command: grid -- Command: grid on -- Command: grid off -- Command: grid minor -- Command: grid minor on -- Command: grid minor off -- Function File: 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 axis rather than the current axes returned by 'gca'. To control the grid lines for an individual axis use the 'set' function. For example: set (gca, "ygrid", "on"); See also: *note axis: XREFaxis, *note box: XREFbox. -- Command: colorbar -- Function File: colorbar (LOC) -- Function File: colorbar (DELETE_OPTION) -- Function File: colorbar (HCB, ...) -- Function File: colorbar (HAX, ...) -- Function File: colorbar (..., "peer", HAX, ...) -- Function File: colorbar (..., "location", LOC, ...) -- Function File: colorbar (..., PROP, VAL, ...) -- Function File: 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. 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: "delete", "hide", "off". If the argument "peer" is given, then the following argument is treated as the axes handle in which to add the colorbar. Alternatively, If the first argument HAX is an axes handle, then the colorbar is added to this axis, rather than the current axes returned by 'gca'. 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 to the current figure with the "tag" property set to "colorbar". The created axes object has the extra property "location" which controls the positioning of the colorbar. See also: *note colormap: XREFcolormap. -- Function File: annotation (TYPE) -- Function File: annotation ("line", X, Y) -- Function File: annotation ("arrow", X, Y) -- Function File: annotation ("doublearrow", X, Y) -- Function File: annotation ("textarrow", X, Y) -- Function File: annotation ("textbox", POS) -- Function File: annotation ("rectangle", POS) -- Function File: annotation ("ellipse", POS) -- Function File: annotation (..., PROP, VAL) -- Function File: annotation (HF, ...) -- Function File: 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. 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. 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 column-major order (top to bottom, left to right). -- Function File: subplot (ROWS, COLS, INDEX) -- Function File: subplot (RCN) -- Function File: subplot (HAX) -- Function File: subplot (..., "align") -- Function File: subplot (..., "replace") -- Function File: subplot (..., "position", POS) -- Function File: subplot (..., PROP, VAL, ...) -- Function File: 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 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 axis 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 axis tick marks or labels. If the option "replace" is given then the subplot axis will be reset, rather than just switching the current axis 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 axis 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. -- Command: figure -- Command: figure N -- Function File: figure (N) -- Function File: figure (..., "PROPERTY", VALUE, ...) -- Function File: 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. See also: *note axes: XREFaxes, *note gcf: XREFgcf, *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 ----------------------------------- -- Command: pan -- Command: pan on -- Command: pan off -- Command: pan xon -- Command: pan yon -- Function File: 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. -- Function File: rotate (H, DIR, ALPHA) -- Function File: rotate (..., ORIGIN) Rotate the plot object H through ALPHA degrees around the line with direction DIR 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. -- Command: rotate3d -- Command: rotate3d on -- Command: rotate3d off -- Function File: 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. -- Command: zoom -- Command: zoom (FACTOR) -- Command: zoom on -- Command: zoom off -- Command: zoom xon -- Command: zoom yon -- Command: zoom out -- Command: zoom reset -- Command: 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. -- Built-in Function: drawnow () -- Built-in Function: drawnow ("expose") -- Built-in Function: drawnow (TERM, FILE, MONO, 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. -- Function File: refresh () -- Function File: 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 initialize the state of the current axes so that the next plot is drawn in a blank window with default property settings. To have two plots superimposed over one another, use the 'hold' function. 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. -- Function File: newplot () -- Function File: newplot (HFIG) -- Function File: newplot (HAX) -- Function File: 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 axis 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'. Axis 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 axis 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 axis and reset all (default) axis 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 axis. -- Command: hold -- Command: hold on -- Command: hold off -- Command: hold all -- Function File: 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. 'hold all' Retain plot line color, line style, data, and settings so that subsequent plot commands are displayed on a single graph with the next line color and style. 'hold off' Restore default graphics settings which clear the graph and reset axis 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 axis 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. -- Command: ishold -- Function File: ishold (HAX) -- Function File: 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. -- Command: clf -- Command: clf reset -- Function File: clf (HFIG) -- Function File: clf (HFIG, "reset") -- Function File: 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. -- Command: cla -- Command: cla reset -- Function File: cla (HAX) -- Function File: cla (HAX, "reset") Clear the current axes. 'cla' operates by deleting child graphic 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 axis 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 axis rather than the current axes returned by 'gca'. See also: *note clf: XREFclf, *note delete: XREFdelete, *note reset: XREFreset. -- Command: shg Show the graph window. Currently, this is the same as executing 'drawnow'. See also: *note drawnow: XREFdrawnow, *note figure: XREFfigure. -- Function File: delete (FILE) -- Function File: delete (FILE1, FILE2, ...) -- Function File: 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. -- Command: close -- Command: close (H) -- Command: close H -- Command: close all -- Command: close all hidden -- Command: 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. If the argument "all" is given then all figures with visible handles (HandleVisibility = "on") are closed. If the argument "all hidden" is given then all figures, including hidden ones, are closed. If the argument "all force" is given then all figures are closed even when "closerequestfcn" has been altered to prevent closing the window. Implementation Note: 'close' operates by calling the function specified by the "closerequestfcn" property for each 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. -- Function File: 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.  File: octave.info, Node: Use of the 'interpreter' Property, Next: Printing and Saving Plots, Prev: Manipulation of Plot Windows, Up: High-Level Plotting 15.2.8 Use of the 'interpreter' Property ---------------------------------------- All text objects--such as titles, labels, legends, and text--include the property "interpreter" that determines the manner in which special control sequences in the text are rendered. The interpreter property can take three values: "none", "tex", "latex". If the interpreter is set to "none" then no special rendering occurs--the displayed text is a verbatim copy of the specified text. Currently, the "latex" interpreter is not implemented and is equivalent to "none". The "tex" option implements a subset of TeX functionality when rendering text. This allows the insertion of special glyphs such as Greek characters or mathematical symbols. The special characters are inserted with a code following a backslash (\) character, as shown in *note Table 15.1: tab:extended. Note that for on-screen display the interpreter property is honored by all graphics toolkits. However for printing, *only* the "gnuplot" toolkit renders TeX instructions. Besides special glyphs, the formatting of text can be changed within the string by using the codes \bf Bold font \it Italic font \sl Oblique Font \rm Normal font These codes may be used in conjunction with the { and } characters to limit the change to just a part of the string. For example, xlabel ('{\bf H} = a {\bf V}') where the character 'a' will not appear in a bold font. Note that to avoid having Octave interpret the backslash characters in the strings, the strings should be in single quotes. It is also possible to change the fontname and size within the text \fontname{FONTNAME} Specify the font to use \fontsize{SIZE} Specify the size of the font to use Finally, superscripting and subscripting can be controlled with the '^' and '_' characters. If the '^' or '_' is followed by a { character, then all of the block surrounded by the { } pair is super- or sub-scripted. Without the { } pair, only the character immediately following the '^' or '_' is super- or sub-scripted. Greek Lowercase Letters \alpha \beta \gamma \delta \epsilon \zeta \eta \theta \vartheta \iota \kappa \lambda \mu \nu \xi \o \pi \varpi \rho \sigma \varsigma \tau \upsilon \phi \chi \psi \omega Greek Uppercase Letters \Gamma \Delta \Theta \Lambda \Xi \Pi \Sigma \Upsilon \Phi \Psi \Omega Misc Symbols Type Ord \aleph \wp \Re \Im \partial \infty \prime \nabla \surd \angle \forall \exists \neg \clubsuit \diamondsuit \heartsuit \spadesuit "Large" Operators \int Binary Operators \pm \cdot \times \ast \circ \bullet \div \cap \cup \vee \wedge \oplus \otimes \oslash Relations \leq \subset \subseteq \in \geq \supset \supseteq \ni \mid \equiv \sim \approx \cong \propto \perp Arrows \leftarrow \Leftarrow \rightarrow \Rightarrow \leftrightarrow \uparrow \downarrow Openings and Closings \lfloor \langle \lceil \rfloor \rangle \rceil Alternate Names \neq Other \ldots \0 \copyright \deg Table 15.1: Available special characters in TeX mode A complete example showing the capabilities of the extended text is x = 0:0.01:3; plot (x, erf (x)); hold on; plot (x,x,"r"); axis ([0, 3, 0, 1]); text (0.65, 0.6175, strcat ('\leftarrow x = {2/\surd\pi', ' {\fontsize{16}\int_{\fontsize{8}0}^{\fontsize{8}x}}', ' e^{-t^2} dt} = 0.6175'))  File: octave.info, Node: Printing and Saving Plots, Next: Interacting with Plots, Prev: Use of the 'interpreter' Property, Up: High-Level Plotting 15.2.9 Printing and Saving Plots -------------------------------- The 'print' command allows you to send plots to you printer and to save plots in a variety of formats. For example, print -dpsc prints the current figure to a color PostScript printer. And, print -deps foo.eps saves the current figure to an encapsulated PostScript file called 'foo.eps'. The different graphic toolkits have different print capabilities. In particular, the OpenGL based toolkits such as 'fltk' do not support the "interpreter" property of text objects. This means special symbols drawn with the "tex" interpreter will appear correctly on-screen but will be rendered with interpreter "none" when printing. Switch graphics toolkits for printing if this is a concern. -- Function File: print () -- Function File: print (OPTIONS) -- Function File: print (FILENAME, OPTIONS) -- Function File: print (H, FILENAME, OPTIONS) Print a plot, or save it to a file. Both output formatted for printing (PDF and PostScript), and many bitmapped and vector image formats are supported. FILENAME defines the name of the output file. If the file name has no suffix, one is inferred from the specified device and appended to the file name. If no filename is specified, the output is sent to the printer. H specifies the handle of the figure to print. If no handle is specified the current figure is used. For output to a printer, PostScript file, or PDF file, the paper size is specified by the figure's 'papersize' property. The location and size of the image on the page are specified by the figure's 'paperposition' property. The orientation of the page is specified by the figure's 'paperorientation' property. The width and height of images are specified by the figure's 'paperpositon(3:4)' property values. The 'print' command supports many OPTIONS: '-fH' Specify the handle, H, of the figure to be printed. The default is the current figure. '-PPRINTER' Set the PRINTER name to which the plot is sent if no FILENAME is specified. '-GGHOSTSCRIPT_COMMAND' Specify the command for calling Ghostscript. For Unix and Windows the defaults are "gs" and "gswin32c", respectively. '-color' '-mono' Color or monochrome output. '-solid' '-dashed' Force all lines to be solid or dashed, respectively. '-portrait' '-landscape' Specify the orientation of the plot for printed output. For non-printed output the aspect ratio of the output corresponds to the plot area defined by the "paperposition" property in the orientation specified. This option is equivalent to changing the figure's "paperorientation" property. '-TextAlphaBits=N' '-GraphicsAlphaBits=N' Octave is able to produce output for various printers, bitmaps, and vector formats by using Ghostscript. For bitmap and printer output anti-aliasing is applied using Ghostscript's TextAlphaBits and GraphicsAlphaBits options. The default number of bits for each is 4. Allowed values for N are 1, 2, or 4. '-dDEVICE' The available output format is specified by the option DEVICE, and is one of: 'ps' 'ps2' 'psc' 'psc2' PostScript (level 1 and 2, mono and color). The FLTK graphics toolkit generates PostScript level 3.0. 'eps' 'eps2' 'epsc' 'epsc2' Encapsulated PostScript (level 1 and 2, mono and color). The FLTK graphic toolkit generates PostScript level 3.0. 'pslatex' 'epslatex' 'pdflatex' 'pslatexstandalone' 'epslatexstandalone' 'pdflatexstandalone' Generate a LaTeX file 'FILENAME.tex' for the text portions of a plot and a file 'FILENAME.(ps|eps|pdf)' for the remaining graphics. The graphics file suffix .ps|eps|pdf is determined by the specified device type. The LaTeX file produced by the 'standalone' option can be processed directly by LaTeX. The file generated without the 'standalone' option is intended to be included from another LaTeX document. In either case, the LaTeX file contains an '\includegraphics' command so that the generated graphics file is automatically included when the LaTeX file is processed. The text that is written to the LaTeX file contains the strings *exactly* as they were specified in the plot. If any special characters of the TeX mode interpreter were used, the file must be edited before LaTeX processing. Specifically, the special characters must be enclosed with dollar signs ('$ ... $'), and other characters that are recognized by LaTeX may also need editing (.e.g., braces). The 'pdflatex' device, and any of the 'standalone' formats, are not available with the Gnuplot toolkit. 'tikz' Generate a LaTeX file using PGF/TikZ. For the FLTK toolkit the result is PGF. 'ill' 'aifm' Adobe Illustrator (Obsolete for Gnuplot versions > 4.2) 'cdr' 'corel' CorelDraw 'dxf' AutoCAD 'emf' 'meta' Microsoft Enhanced Metafile 'fig' XFig. For the Gnuplot graphics toolkit, the additional options '-textspecial' or '-textnormal' can be used to control whether the special flag should be set for the text in the figure. (default is '-textnormal') 'hpgl' HP plotter language 'mf' Metafont 'png' Portable network graphics 'jpg' 'jpeg' JPEG image 'gif' GIF image (only available for the Gnuplot graphics toolkit) 'pbm' PBMplus 'svg' Scalable vector graphics 'pdf' Portable document format If the device is omitted, it is inferred from the file extension, or if there is no filename it is sent to the printer as PostScript. '-dGHOSTSCRIPT_DEVICE' Additional devices are supported by Ghostscript. Some examples are; 'pdfwrite' Produces pdf output from eps 'ljet2p' HP LaserJet IIP 'pcx24b' 24-bit color PCX file format 'ppm' Portable Pixel Map file format For a complete list, type 'system ("gs -h")' to see what formats and devices are available. When Ghostscript output is sent to a printer the size is determined by the figure's "papersize" property. When the output is sent to a file the size is determined by the plot box defined by the figure's "paperposition" property. '-append' Append PostScript or PDF output to a pre-existing file of the same type. '-rNUM' Resolution of bitmaps in pixels per inch. For both metafiles and SVG the default is the screen resolution; for other formats it is 150 dpi. To specify screen resolution, use "-r0". '-loose' '-tight' Force a tight or loose bounding box for eps files. The default is loose. '-PREVIEW' Add a preview to eps files. Supported formats are: '-interchange' Provide an interchange preview. '-metafile' Provide a metafile preview. '-pict' Provide pict preview. '-tiff' Provide a tiff preview. '-SXSIZE,YSIZE' Plot size in pixels for EMF, GIF, JPEG, PBM, PNG, and SVG. For PS, EPS, PDF, and other vector formats the plot size is in points. This option is equivalent to changing the size of the plot box associated with the "paperposition" property. When using the command form of the print function you must quote the XSIZE,YSIZE option. For example, by writing "-S640,480". '-FFONTNAME' '-FFONTNAME:SIZE' '-F:SIZE' Use FONTNAME and/or FONTSIZE for all text. FONTNAME is ignored for some devices: dxf, fig, hpgl, etc. The filename and options can be given in any order. Example: Print to a file using the pdf device. figure (1); clf (); surf (peaks); print figure1.pdf Example: Print to a file using jpg device. clf (); surf (peaks); print -djpg figure2.jpg Example: Print to printer named PS_printer using ps format. clf (); surf (peaks); print -dpswrite -PPS_printer See also: *note saveas: XREFsaveas, *note hgsave: XREFhgsave, *note orient: XREForient, *note figure: XREFfigure. -- Function File: saveas (H, FILENAME) -- Function File: saveas (H, FILENAME, FMT) Save graphic object H to the file FILENAME in graphic format FMT. FMT should be one of the following formats: 'ps' PostScript 'eps' Encapsulated PostScript 'jpg' JPEG Image 'png' PNG Image 'emf' Enhanced Meta File 'pdf' Portable Document Format All device formats specified in 'print' may also be used. If FMT is omitted it is extracted from the extension of FILENAME. The default format is "pdf". clf (); surf (peaks); saveas (1, "figure1.png"); See also: *note print: XREFprint, *note hgsave: XREFhgsave, *note orient: XREForient. -- Function File: orient (ORIENTATION) -- Function File: orient (HFIG, ORIENTATION) -- Function File: ORIENTATION = orient () -- Function File: ORIENTATION = orient (HFIG) Query or set the print orientation for figure HFIG. Valid values for ORIENTATION are "portrait", "landscape", and "tall". The "landscape" option changes the orientation so the plot width is larger than the plot height. The "paperposition" is also modified so that the plot fills the page, while leaving a 0.25 inch border. The "tall" option sets the orientation to "portrait" and fills the page with the plot, while leaving a 0.25 inch border. The "portrait" option (default) changes the orientation so the plot height is larger than the plot width. It also restores the default "paperposition" property. When called with no arguments, return the current print orientation. If the argument HFIG is omitted, then operate on the current figure returned by 'gcf'. See also: *note print: XREFprint, *note saveas: XREFsaveas. 'print' and 'saveas' are used when work on a plot has finished and the output must be in a publication-ready format. During intermediate stages it is often better to save the graphics object and all of its associated information so that changes--to colors, axis limits, marker styles, etc.--can be made easily from within Octave. The 'hgsave'/'hgload' commands can be used to save and re-create a graphics object. -- Function File: hgsave (FILENAME) -- Function File: hgsave (H, FILENAME) -- Function File: hgsave (H, FILENAME, FMT) Save the graphics handle H to the file FILENAME in the format FMT. If unspecified, H is the current figure as returned by 'gcf'. When FILENAME does not have an extension the default filename extension '.ofig' will be appended. If present, FMT should be one of the following: * '-binary', '-float-binary' * '-hdf5', '-float-hdf5' * '-V7', '-v7', '-7', '-mat7-binary' * '-V6', '-v6', '-6', '-mat6-binary' * '-text' * '-zip', '-z' When producing graphics for final publication use 'print' or 'saveas'. When it is important to be able to continue to edit a figure as an Octave object, use 'hgsave'/'hgload'. See also: *note hgload: XREFhgload, *note hdl2struct: XREFhdl2struct, *note saveas: XREFsaveas, *note print: XREFprint. -- Function File: H = hgload (FILENAME) Load the graphics object in FILENAME into the graphics handle H. If FILENAME has no extension, Octave will try to find the file with and without the standard extension of '.ofig'. See also: *note hgsave: XREFhgsave, *note struct2hdl: XREFstruct2hdl.  File: octave.info, Node: Interacting with Plots, Next: Test Plotting Functions, Prev: Printing and Saving Plots, Up: High-Level Plotting 15.2.10 Interacting with Plots ------------------------------ The user can select points on a plot with the 'ginput' function or selection the position at which to place text on the plot with the 'gtext' function using the mouse. Menus may also be created and populated with specific user commands via the 'uimenu' function. -- Function File: [X, Y, BUTTONS] = ginput (N) -- Function File: [X, Y, BUTTONS] = ginput () Return the position and type of mouse button clicks and/or key strokes in the current figure window. If N is defined, then capture N events before returning. When N is not defined 'ginput' will loop until the return key is pressed. The return values X, Y are the coordinates where the mouse was clicked in the units of the current axes. The return value BUTTON is 1, 2, or 3 for the left, middle, or right button. If a key is pressed the ASCII value is returned in BUTTON. Implementation Note: 'ginput' is intenteded for 2-D plots. For 3-D plots see the CURRENTPOINT property of the current axes which can be transformed with knowledge of the current 'view' into data units. See also: *note gtext: XREFgtext, *note waitforbuttonpress: XREFwaitforbuttonpress. -- Function File: waitforbuttonpress () -- Function File: B = waitforbuttonpress () Wait for mouse click or key press over the current figure window. The return value of B is 0 if a mouse button was pressed or 1 if a key was pressed. See also: *note waitfor: XREFwaitfor, *note ginput: XREFginput, *note kbhit: XREFkbhit. -- Function File: gtext (S) -- Function File: gtext ({S1, S2, ...}) -- Function File: gtext ({S1; S2; ...}) -- Function File: gtext (..., PROP, VAL, ...) -- Function File: H = gtext (...) Place text on the current figure using the mouse. The text is defined by the string S. If S is a cell string organized as a row vector then each string of the cell array is written to a separate line. If S is organized as a column vector then one string element of the cell array is placed for every mouse click. Optional property/value pairs are passed directly to the underlying text objects. The optional return value H is a graphics handle to the created text object(s). See also: *note ginput: XREFginput, *note text: XREFtext. -- Function File: HUI = uimenu (PROPERTY, VALUE, ...) -- Function File: HUI = uimenu (H, PROPERTY, VALUE, ...) Create a uimenu object and return a handle to it. If H is omitted then a top-level menu for the current figure is created. If H is given then a submenu relative to H is created. uimenu objects have the following specific properties: "accelerator" A string containing the key combination together with CTRL to execute this menu entry (e.g., "x" for CTRL+x). "callback" Is the function called when this menu entry is executed. It can be either a function string (e.g., "myfun"), a function handle (e.g., @myfun) or a cell array containing the function handle and arguments for the callback function (e.g., {@myfun, arg1, arg2}). "checked" Can be set "on" or "off". Sets a mark at this menu entry. "enable" Can be set "on" or "off". If disabled the menu entry cannot be selected and it is grayed out. "foregroundcolor" A color value setting the text color for this menu entry. "label" A string containing the label for this menu entry. A "&"-symbol can be used to mark the "accelerator" character (e.g., "E&xit") "position" An scalar value containing the relative menu position. The entry with the lowest value is at the first position starting from left or top. "separator" Can be set "on" or "off". If enabled it draws a separator line above the current position. It is ignored for top level entries. Examples: f = uimenu ("label", "&File", "accelerator", "f"); e = uimenu ("label", "&Edit", "accelerator", "e"); uimenu (f, "label", "Close", "accelerator", "q", ... "callback", "close (gcf)"); uimenu (e, "label", "Toggle &Grid", "accelerator", "g", ... "callback", "grid (gca)"); See also: *note figure: XREFfigure.  File: octave.info, Node: Test Plotting Functions, Prev: Interacting with Plots, Up: High-Level Plotting 15.2.11 Test Plotting Functions ------------------------------- The functions 'sombrero' and 'peaks' provide a way to check that plotting is working. Typing either 'sombrero' or 'peaks' at the Octave prompt should display a three-dimensional plot. -- Function File: sombrero () -- Function File: sombrero (N) -- Function File: Z = sombrero (...) -- Function File: [X, Y, Z] = sombrero (...) Plot the familiar 3-D sombrero function. The function plotted is z = sin (sqrt (x^2 + y^2)) / (sqrt (x^2 + y^2)) Called without a return argument, 'sombrero' plots the surface of the above function over the meshgrid [-8,8] using 'surf'. If N is a scalar the plot is made with N grid lines. The default value for N is 41. When called with output arguments, return the data for the function evaluated over the meshgrid. This can subsequently be plotted with 'surf (X, Y, Z)'. See also: *note peaks: XREFpeaks, *note meshgrid: XREFmeshgrid, *note mesh: XREFmesh, *note surf: XREFsurf. -- Function File: peaks () -- Function File: peaks (N) -- Function File: peaks (X, Y) -- Function File: Z = peaks (...) -- Function File: [X, Y, Z] = peaks (...) Plot a function with lots of local maxima and minima. The function has the form f(x,y) = 3*(1-x)^2*exp(-x^2 - (y+1)^2) ... - 10*(x/5 - x^3 - y^5)*exp(-x^2-y^2) ... - 1/3*exp(-(x+1)^2 - y^2) Called without a return argument, 'peaks' plots the surface of the above function using 'surf'. If N is a scalar, 'peaks' plots the value of the above function on an N-by-N mesh over the range [-3,3]. The default value for N is 49. If N is a vector, then it represents the grid values over which to calculate the function. If X and Y are specified then the function value is calculated over the specified grid of vertices. When called with output arguments, return the data for the function evaluated over the meshgrid. This can subsequently be plotted with 'surf (X, Y, Z)'. See also: *note sombrero: XREFsombrero, *note meshgrid: XREFmeshgrid, *note mesh: XREFmesh, *note surf: XREFsurf.  File: octave.info, Node: Graphics Data Structures, Next: Advanced Plotting, Prev: High-Level Plotting, Up: Plotting 15.3 Graphics Data Structures ============================= * Menu: * Introduction to Graphics Structures:: * Graphics Objects:: * Graphics Object Properties:: * Searching Properties:: * Managing Default Properties::  File: octave.info, Node: Introduction to Graphics Structures, Next: Graphics Objects, Up: Graphics Data Structures 15.3.1 Introduction to Graphics Structures ------------------------------------------ The graphics functions use pointers, which are of class graphics_handle, in order to address the data structures which control visual display. A graphics handle may point to any one of a number of different base object types and these objects are the graphics data structures themselves. The primitive graphic object types are: 'figure', 'axes', 'line', 'text', 'patch', 'surface', 'text', and 'image'. Each of these objects has a function by the same name, and, each of these functions returns a graphics handle pointing to an object of the corresponding type. In addition there are several functions which operate on properties of the graphics objects and which also return handles: the functions 'plot' and 'plot3' return a handle pointing to an object of type line, the function 'subplot' returns a handle pointing to an object of type axes, the function 'fill' returns a handle pointing to an object of type patch, the functions 'area', 'bar', 'barh', 'contour', 'contourf', 'contour3', 'surf', 'mesh', 'surfc', 'meshc', 'errorbar', 'quiver', 'quiver3', 'scatter', 'scatter3', 'stair', 'stem', 'stem3' each return a handle to a complex data structure as documented in *note Data Sources: XREFdatasources. The graphics objects are arranged in a hierarchy: 1. The root is at 0. In other words, 'get (0)' returns the properties of the root object. 2. Below the root are 'figure' objects. 3. Below the 'figure' objects are 'axes' objects. 4. Below the 'axes' objects are 'line', 'text', 'patch', 'surface', and 'image' objects. Graphics handles may be distinguished from function handles (*note Function Handles::) by means of the function 'ishandle'. 'ishandle' returns true if its argument is a handle of a graphics object. In addition, a figure or axes object may be tested using 'isfigure' or 'isaxes' respectively. The test functions return true only if the argument is both a handle and of the correct type (figure or axes). The 'whos' function can be used to show the object type of each currently defined graphics handle. (Note: this is not true today, but it is, I hope, considered an error in whos. It may be better to have whos just show graphics_handle as the class, and provide a new function which, given a graphics handle, returns its object type. This could generalize the ishandle() functions and, in fact, replace them.) The 'get' and 'set' commands are used to obtain and set the values of properties of graphics objects. In addition, the 'get' command may be used to obtain property names. For example, the property "type" of the graphics object pointed to by the graphics handle h may be displayed by: get (h, "type") The properties and their current values are returned by 'get (h)' where h is a handle of a graphics object. If only the names of the allowed properties are wanted they may be displayed by: 'get (h, "")'. Thus, for example: h = figure (); get (h, "type") ans = figure get (h, ""); error: get: ambiguous figure property name ; possible matches: __enhanced__ hittest resize __graphics_toolkit__ integerhandle resizefcn __guidata__ interruptible selected __modified__ inverthardcopy selectionhighlight __myhandle__ keypressfcn selectiontype __plot_stream__ keyreleasefcn tag alphamap menubar toolbar beingdeleted mincolormap type busyaction name uicontextmenu buttondownfcn nextplot units children numbertitle userdata clipping outerposition visible closerequestfcn paperorientation windowbuttondownfcn color paperposition windowbuttonmotionfcn colormap paperpositionmode windowbuttonupfcn createfcn papersize windowkeypressfcn currentaxes papertype windowkeyreleasefcn currentcharacter paperunits windowscrollwheelfcn currentobject parent windowstyle currentpoint pointer wvisual deletefcn pointershapecdata wvisualmode dockcontrols pointershapehotspot xdisplay doublebuffer position xvisual filename renderer xvisualmode handlevisibility renderermode The root figure has index 0. Its properties may be displayed by: 'get (0, "")'. The uses of 'get' and 'set' are further explained in *note get: XREFget, *note set: XREFset. -- Function File: RES = isprop (OBJ, "PROP") Return true if PROP is a property of the object OBJ. OBJ may also be an array of objects in which case RES will be a logical array indicating whether each handle has the property PROP. For plotting, OBJ is a handle to a graphics object. Otherwise, OBJ should be an instance of a class. See also: *note get: XREFget, *note set: XREFset, *note ismethod: XREFismethod, *note isobject: XREFisobject.  File: octave.info, Node: Graphics Objects, Next: Graphics Object Properties, Prev: Introduction to Graphics Structures, Up: Graphics Data Structures 15.3.2 Graphics Objects ----------------------- The hierarchy of graphics objects was explained above. *Note Introduction to Graphics Structures::. Here the specific objects are described, and the properties contained in these objects are discussed. Keep in mind that graphics objects are always referenced by "handle". root figure the top level of the hierarchy and the parent of all figure objects. The handle index of the root figure is 0. figure A figure window. axes A set of axes. This object is a child of a figure object and may be a parent of line, text, image, patch, or surface objects. line A line in two or three dimensions. text Text annotations. image A bitmap image. patch A filled polygon, currently limited to two dimensions. surface A three-dimensional surface. 15.3.2.1 Creating Graphics Objects .................................. You can create any graphics object primitive by calling the function of the same name as the object; In other words, 'figure', 'axes', 'line', 'text', 'image', 'patch', and 'surface' functions. These fundamental graphic objects automatically become children of the current axes object as if 'hold on' was in place. Seperately, axes will automatically become children of the current figure object and figures will become children of the root object 0. If this auto-joining feature is not desired then it is important to call 'newplot' first to prepare a new figure and axes for plotting. Alternatively, the easier way is to call a high-level graphics routine which will both create the plot and then populate it with low-level graphics objects. Instead of calling 'line', use 'plot'. Or use 'surf' instead of 'surface'. Or use 'fill' instead of 'patch'. -- Function File: axes () -- Function File: axes (PROPERTY, VALUE, ...) -- Function File: axes (HAX) -- Function File: H = axes (...) Create an axes object and return a handle to it, or set the current axes to HAX. Called without any arguments, or with PROPERTY/VALUE pairs, construct a new axes. For accepted properties and corresponding values, *note set: XREFset. Called with a single axes handle argument HAX, the function makes HAX the current axis. It also restacks the axes in the corresponding figure so that HAX is the first entry in the list of children. This causes HAX to be displayed on top of any other axes objects (Z-order stacking). See also: *note gca: XREFgca, *note set: XREFset, *note get: XREFget. -- Function File: line () -- Function File: line (X, Y) -- Function File: line (X, Y, PROPERTY, VALUE, ...) -- Function File: line (X, Y, Z) -- Function File: line (X, Y, Z, PROPERTY, VALUE, ...) -- Function File: line (PROPERTY, VALUE, ...) -- Function File: line (HAX, ...) -- Function File: H = line (...) Create line object from X and Y (and possibly Z) and insert in the current axes. Multiple property-value pairs may be specified for the line object, but they must appear in pairs. If the first argument HAX is an axes handle, then plot into this axis, rather than the current axes returned by 'gca'. The optional return value H is a graphics handle (or vector of handles) to the line objects created. See also: *note image: XREFimage, *note patch: XREFpatch, *note rectangle: XREFrectangle, *note surface: XREFsurface, *note text: XREFtext. -- Function File: patch () -- Function File: patch (X, Y, C) -- Function File: patch (X, Y, Z, C) -- Function File: patch (FV) -- Function File: patch ("Faces", FACES, "Vertices", VERTS, ...) -- Function File: patch (..., PROP, VAL, ...) -- Function File: patch (HAX, ...) -- Function File: H = patch (...) Create patch object in the current axes with vertices at locations (X, Y) and of color C. If the vertices are matrices of size MxN then each polygon patch has M vertices and a total of N polygons will be created. If some polygons do not have M vertices use NaN to represent "no vertex". If the Z input is present then 3-D patches will be created. The color argument C can take many forms. To create polygons which all share a single color use a string value (e.g., "r" for red), a scalar value which is scaled by 'caxis' and indexed into the current colormap, or a 3-element RGB vector with the precise TrueColor. If C is a vector of length N then the ith polygon will have a color determined by scaling entry C(i) according to 'caxis' and then indexing into the current colormap. More complicated coloring situations require directly manipulating patch property/value pairs. Instead of specifying polygons by matrices X and Y, it is possible to present a unique list of vertices and then a list of polygon faces created from those vertices. In this case the "Vertices" matrix will be an Nx2 (2-D patch) or Nx3 (3-D path). The MxN "Faces" matrix describes M polygons having N vertices--each row describes a single polygon and each column entry is an index into the "Vertices" matrix to identify a vertex. The patch object can be created by directly passing the property/value pairs "Vertices"/VERTS, "Faces"/FACES as inputs. A third input form is to create a structure FV with the fields "vertices", "faces", and optionally "facevertexcdata". If the first argument HAX is an axes handle, then plot into this axis, rather than the current axes returned by 'gca'. The optional return value H is a graphics handle to the created patch object. Implementation Note: Patches are highly configurable objects. To truly customize them requires setting patch properties directly. Useful patch properties are: "cdata", "edgecolor", "facecolor", "faces", "facevertexcdata". See also: *note fill: XREFfill, *note get: XREFget, *note set: XREFset. -- Function File: surface (X, Y, Z, C) -- Function File: surface (X, Y, Z) -- Function File: surface (Z, C) -- Function File: surface (Z) -- Function File: surface (..., PROP, VAL, ...) -- Function File: surface (HAX, ...) -- Function File: H = surface (...) Create a surface graphic object given matrices X and Y from 'meshgrid' and a matrix of values Z corresponding to the X and Y coordinates of the 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:rows (Z)' and Y is '1:columns (Z)'. Any property/value input pairs are assigned to the surface object. If the first argument HAX is an axes handle, then plot into this axis, 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 surf: XREFsurf, *note mesh: XREFmesh, *note patch: XREFpatch, *note line: XREFline. 15.3.2.2 Handle Functions ......................... To determine whether a variable is a graphics object index, or an index to an axes or figure, use the functions 'ishandle', 'isaxes', and 'isfigure'. -- Built-in Function: ishandle (H) Return true if H is a graphics handle and false otherwise. H may also be a matrix of handles in which case a logical array is returned that is true where the elements of H are graphics handles and false where they are not. See also: *note isaxes: XREFisaxes, *note isfigure: XREFisfigure. -- Function File: ishghandle (H) Return true if H is a graphics handle and false otherwise. This function is equivalent to 'ishandle' and is provided for compatibility with MATLAB. See also: *note ishandle: XREFishandle. -- Function File: isaxes (H) Return true if H is an axes graphics handle and false otherwise. If H is a matrix then return a logical array which is true where the elements of H are axes graphics handles and false where they are not. See also: *note isaxes: XREFisaxes, *note ishandle: XREFishandle. -- Function File: isfigure (H) Return true if H is a figure graphics handle and false otherwise. If H is a matrix then return a logical array which is true where the elements of H are figure graphics handles and false where they are not. See also: *note isaxes: XREFisaxes, *note ishandle: XREFishandle. The function 'gcf' returns an index to the current figure object, or creates one if none exists. Similarly, 'gca' returns the current axes object, or creates one (and its parent figure object) if none exists. -- Function File: H = gcf () Return a handle to the current figure. The current figure is the default target for graphics output. If multiple figures exist, 'gcf' returns the last created figure or the last figure that was clicked on with the mouse. If a current figure does not exist, create one and return its handle. The handle may then be used to examine or set properties of the figure. For example, fplot (@sin, [-10, 10]); fig = gcf (); set (fig, "numbertitle", "off", "name", "sin plot") plots a sine wave, finds the handle of the current figure, and then renames the figure window to describe the contents. Note: To find the current figure without creating a new one if it does not exist, query the "CurrentFigure" property of the root graphics object. get (0, "currentfigure"); See also: *note gca: XREFgca, *note gco: XREFgco, *note gcbf: XREFgcbf, *note gcbo: XREFgcbo, *note get: XREFget, *note set: XREFset. -- Function File: H = gca () Return a handle to the current axis object. The current axis is the default target for graphics output. In the case of a figure with multiple axes, 'gca' returns the last created axes or the last axes that was clicked on with the mouse. If no current axes object exists, create one and return its handle. The handle may then be used to examine or set properties of the axes. For example, ax = gca (); set (ax, "position", [0.5, 0.5, 0.5, 0.5]); creates an empty axes object and then changes its location and size in the figure window. Note: To find the current axis without creating a new axes object if it does not exist, query the "CurrentAxes" property of a figure. get (gcf, "currentaxes"); See also: *note gcf: XREFgcf, *note gco: XREFgco, *note gcbf: XREFgcbf, *note gcbo: XREFgcbo, *note get: XREFget, *note set: XREFset. -- Function File: H = gco () -- Function File: H = gco (FIG) Return a handle to the current object of the current figure, or a handle to the current object of the figure with handle FIG. The current object of a figure is the object that was last clicked on. It is stored in the "CurrentObject" property of the target figure. If the last mouse click did not occur on any child object of the figure, then the current object is the figure itself. If no mouse click occurred in the target figure, this function returns an empty matrix. Programming Note: The value returned by this function is not necessarily the same as the one returned by 'gcbo' during callback execution. An executing callback can be interrupted by another callback and the current object may be changed. See also: *note gcbo: XREFgcbo, *note gca: XREFgca, *note gcf: XREFgcf, *note gcbf: XREFgcbf, *note get: XREFget, *note set: XREFset. The 'get' and 'set' functions may be used to examine and set properties for graphics objects. For example, get (0) => ans = { type = root currentfigure = [](0x0) children = [](0x0) visible = on ... } returns a structure containing all the properties of the root figure. As with all functions in Octave, the structure is returned by value, so modifying it will not modify the internal root figure plot object. To do that, you must use the 'set' function. Also, note that in this case, the 'currentfigure' property is empty, which indicates that there is no current figure window. The 'get' function may also be used to find the value of a single property. For example, get (gca (), "xlim") => [ 0 1 ] returns the range of the x-axis for the current axes object in the current figure. To set graphics object properties, use the set function. For example, set (gca (), "xlim", [-10, 10]); sets the range of the x-axis for the current axes object in the current figure to '[-10, 10]'. Default property values can also be queried if the 'set' function is called without a value argument. When only one argument is given (a graphic handle) then a structure with defaults for all properties of the given object type is returned. For example, set (gca ()) returns a structure containing the default property values for axes objects. If 'set' is called with two arguments (a graphic handle and a property name) then only the defaults for the requested property are returned. -- Built-in Function: VAL = get (H) -- Built-in Function: VAL = get (H, P) Return the value of the named property P from the graphics handle H. If P is omitted, return the complete property list for H. If H is a vector, return a cell array including the property values or lists respectively. See also: *note set: XREFset. -- Built-in Function: set (H, PROPERTY, VALUE, ...) -- Built-in Function: set (H, PROPERTIES, VALUES) -- Built-in Function: set (H, PV) -- Built-in Function: VALUE_LIST = set (H, PROPERTY) -- Built-in Function: ALL_VALUE_LIST = set (H) Set named property values for the graphics handle (or vector of graphics handles) H. There are three ways to give the property names and values: * as a comma separated list of PROPERTY, VALUE pairs Here, each PROPERTY is a string containing the property name, each VALUE is a value of the appropriate type for the property. * as a cell array of strings PROPERTIES containing property names and a cell array VALUES containing property values. In this case, the number of columns of VALUES must match the number of elements in PROPERTIES. The first column of VALUES contains values for the first entry in PROPERTIES, etc. The number of rows of VALUES must be 1 or match the number of elements of H. In the first case, each handle in H will be assigned the same values. In the latter case, the first handle in H will be assigned the values from the first row of VALUES and so on. * as a structure array PV Here, the field names of PV represent the property names, and the field values give the property values. In contrast to the previous case, all elements of PV will be set in all handles in H independent of the dimensions of PV. 'set' is also used to query the list of values a named property will take. 'CLIST = set (H, "property")' will return the list of possible values for "property" in the cell list CLIST. If no output variable is used then the list is formatted and printed to the screen. If no property is specified ('SLIST = set (H)') then a structure SLIST is returned where the fieldnames are the properties of the object H and the fields are the list of possible values for each property. If no output variable is used then the list is formatted and printed to the screen. For example, hf = figure (); set (hf, "paperorientation") => paperorientation: [ landscape | {portrait} | rotated ] shows the paperorientation property can take three values with the default being "portrait". See also: *note get: XREFget. -- Function File: PARENT = ancestor (H, TYPE) -- Function File: PARENT = ancestor (H, TYPE, "toplevel") Return the first ancestor of handle object H whose type matches TYPE, where TYPE is a character string. If TYPE is a cell array of strings, return the first parent whose type matches any of the given type strings. If the handle object H itself is of type TYPE, return H. If "toplevel" is given as a third argument, return the highest parent in the object hierarchy that matches the condition, instead of the first (nearest) one. See also: *note findobj: XREFfindobj, *note findall: XREFfindall, *note allchild: XREFallchild. -- Function File: H = allchild (HANDLES) Find all children, including hidden children, of a graphics object. This function is similar to 'get (h, "children")', but also returns hidden objects (HandleVisibility = "off"). If HANDLES is a scalar, H will be a vector. Otherwise, H will be a cell matrix of the same size as HANDLES and each cell will contain a vector of handles. See also: *note findall: XREFfindall, *note findobj: XREFfindobj, *note get: XREFget, *note set: XREFset. -- Function File: findfigs () Find all visible figures that are currently off the screen and move them onto the screen. See also: *note allchild: XREFallchild, *note figure: XREFfigure, *note get: XREFget, *note set: XREFset. Figures can be printed or saved in many graphics formats with 'print' and 'saveas'. Occasionally, however, it may be useful to save the original Octave handle graphic directly so that further modifications can be made such as modifying a title or legend. This can be accomplished with the following functions by fig_struct = hdl2struct (gcf); save myplot.fig -struct fig_struct; ... fig_struct = load ("myplot.fig"); struct2hdl (fig_struct); -- Function File: S = hdl2struct (H) Return a structure, S, whose fields describe the properties of the object, and its children, associated with the handle, H. The fields of the structure S are "type", "handle", "properties", "children", and "special". See also: *note struct2hdl: XREFstruct2hdl, *note hgsave: XREFhgsave, *note findobj: XREFfindobj. -- Function File: H = struct2hdl (S) -- Function File: H = struct2hdl (S, P) -- Function File: H = struct2hdl (S, P, HILEV) Construct a graphics handle object H from the structure S. The structure must contain the fields "handle", "type", "children", "properties", and "special". If the handle of an existing figure or axes is specified, P, the new object will be created as a child of that object. If no parent handle is provided then a new figure and the necessary children will be constructed using the default values from the root figure. A third boolean argument HILEV can be passed to specify whether the function should preserve listeners/callbacks, e.g., for legends or hggroups. The default is false. See also: *note hdl2struct: XREFhdl2struct, *note hgload: XREFhgload, *note findobj: XREFfindobj. -- Function File: HNEW = copyobj (HORIG) -- Function File: HNEW = copyobj (HORIG, HPARENT) Construct a copy of the graphic object associated with handle HORIG and return a handle HNEW to the new object. If a parent handle HPARENT (root, figure, axes, or hggroup) is specified, the copied object will be created as a child of HPARENT. See also: *note struct2hdl: XREFstruct2hdl, *note hdl2struct: XREFhdl2struct, *note findobj: XREFfindobj.  File: octave.info, Node: Graphics Object Properties, Next: Searching Properties, Prev: Graphics Objects, Up: Graphics Data Structures 15.3.3 Graphics Object Properties --------------------------------- * Menu: * Root Figure Properties:: * Figure Properties:: * Axes Properties:: * Line Properties:: * Text Properties:: * Image Properties:: * Patch Properties:: * Surface Properties:: In this Section the graphics object properties are discussed in detail, starting with the root figure properties and continuing through the objects hierarchy. The documentation about a specific graphics object can be displayed using 'doc' function, e.g., 'doc ("axes properties")' will show *note Axes Properties::. The allowed values for radio (string) properties can be retrieved programmatically or displayed using the one or two arguments call to 'set' function. *Note set: XREFset. In the following documentation, default values are enclosed in { }.  File: octave.info, Node: Root Figure Properties, Next: Figure Properties, Up: Graphics Object Properties 15.3.3.1 Root Figure Properties ............................... The 'root figure' properties are: '__modified__': "off" | {"on"} 'beingdeleted': {"off"} | "on" 'beingdeleted' is unused. 'busyaction': "cancel" | {"queue"} 'busyaction' is unused. 'buttondownfcn': string | function handle, def. '[](0x0)' 'buttondownfcn' is unused. 'callbackobject' (read-only): graphics handle, def. '[](0x0)' 'children' (read-only): vector of graphics handles, def. '[](0x1)' Graphics handles of the root's children. 'clipping': "off" | {"on"} 'clipping' is unused. 'commandwindowsize' (read-only): def. '[0 0]' 'createfcn': string | function handle, def. '[](0x0)' 'createfcn' is unused. 'currentfigure': graphics handle, def. '[](0x0)' Graphics handle of the current figure. 'deletefcn': string | function handle, def. '[](0x0)' 'deletefcn' is unused. 'diary': {"off"} | "on" If 'diary' is "on", the Octave command window session is saved to file. *Note diaryfile property: XREFrootdiaryfile. 'diaryfile': string, def. "diary" The name of the diary file. *Note diary function: XREFdiary. 'echo': {"off"} | "on" Control whether Octave displays commands executed from scripts. *Note echo function: XREFecho. 'errormessage' (read-only): string, def. "" The last error message raised. *Note lasterr function: XREFlasterr. 'fixedwidthfontname': string, def. "Courier" 'format': "+" | "bank" | "bit" | "hex" | "long" | "longe" | "longeng" | "longg" | "native-bit" | "native-hex" | "none" | "rat" | {"short"} | "shorte" | "shorteng" | "shortg" This property is a wrapper around the 'format' function. *Note format function: XREFformat. 'formatspacing': "compact" | {"loose"} This property is a wrapper around the 'format' function. *Note format function: XREFformat. 'handlevisibility': "callback" | "off" | {"on"} 'handlevisibility' is unused. 'hittest': "off" | {"on"} 'hittest' is unused. 'interruptible': "off" | {"on"} 'interruptible' is unused. 'language': string, def. "ascii" 'monitorpositions': 'monitorpositions' is unused. 'parent': graphics handle, def. '[](0x0)' Root figure has no parent graphics object. 'parent' is always empty. 'pointerlocation': two-element vector, def. '[0 0]' 'pointerlocation' is unused. 'pointerwindow' (read-only): graphics handle, def. '0' 'pointerwindow' is unused. 'recursionlimit': double, def. '256' The maximum number of times a function can be called recursively. *Note max_recursion_depth function: XREFmax_recursion_depth. 'screendepth' (read-only): double 'screenpixelsperinch' (read-only): double 'screensize' (read-only): four-element vector 'selected': {"off"} | "on" 'selected' is unused. 'selectionhighlight': "off" | {"on"} 'selectionhighlight' is unused. 'showhiddenhandles': {"off"} | "on" If 'showhiddenhandles' is "on", all graphics objects handles are visible in their parents' children list, regardless of the value of their 'handlevisibility' property. 'tag': string, def. "" A user-defined string to label the graphics object. 'type' (read-only): string Class name of the graphics object. 'type' is always "root" 'uicontextmenu': graphics handle, def. '[](0x0)' 'uicontextmenu' is unused. 'units': "centimeters" | "inches" | "normalized" | {"pixels"} | "points" 'userdata': Any Octave data, def. '[](0x0)' User-defined data to associate with the graphics object. 'visible': "off" | {"on"} 'visible' is unused.  File: octave.info, Node: Figure Properties, Next: Axes Properties, Prev: Root Figure Properties, Up: Graphics Object Properties 15.3.3.2 Figure Properties .......................... The 'figure' properties are: '__modified__': "off" | {"on"} 'alphamap': def. 64-by-1 double Transparency is not yet implemented for figure objects. 'alphamap' is unused. 'beingdeleted': {"off"} | "on" 'busyaction': "cancel" | {"queue"} 'buttondownfcn': string | function handle, def. '[](0x0)' 'children' (read-only): vector of graphics handles, def. '[](0x1)' Graphics handles of the figure's children. 'clipping': "off" | {"on"} 'clipping' is unused. 'closerequestfcn': string | function handle, def. "closereq" 'color': colorspec, def. '[1 1 1]' Color of the figure background. *Note colorspec: Colors. 'colormap': N-by-3 matrix, def. 64-by-3 double A matrix containing the RGB color map for the current axes. 'createfcn': string | function handle, def. '[](0x0)' Callback function executed immediately after figure has been created. Function is set by using default property on root object, e.g., 'set (0, "defaultfigurecreatefcn", 'disp ("figure created!")')'. 'currentaxes': graphics handle, def. '[](0x0)' Handle to the graphics object of the current axes. 'currentcharacter' (read-only): def. "" 'currentcharacter' is unused. 'currentobject' (read-only): graphics handle, def. '[](0x0)' 'currentpoint' (read-only): two-element vector, def. '[0; 0]' A 1-by-2 matrix which holds the coordinates of the point over which the mouse pointer was when a mouse event occurred. The X and Y coordinates are in units defined by the figure's 'units' property and their origin is the lower left corner of the plotting area. Events which set 'currentpoint' are A mouse button was pressed always A mouse button was released only if the figure's callback 'windowbuttonupfcn' is defined The pointer was moved while pressing the mouse button (drag) only if the figure's callback 'windowbuttonmotionfcn' is defined 'deletefcn': string | function handle, def. '[](0x0)' Callback function executed immediately before figure is deleted. 'dockcontrols': {"off"} | "on" 'dockcontrols' is unused. 'doublebuffer': "off" | {"on"} 'filename': string, def. "" The filename used when saving the plot figure 'handlevisibility': "callback" | "off" | {"on"} If 'handlevisibility' is "off", the figure's handle is not visible in its parent's "children" property. 'hittest': "off" | {"on"} 'integerhandle': "off" | {"on"} Assign the next lowest unused integer as the Figure number. 'interruptible': "off" | {"on"} 'inverthardcopy': {"off"} | "on" 'keypressfcn': string | function handle, def. '[](0x0)' 'keyreleasefcn': string | function handle, def. '[](0x0)' With 'keypressfcn', the keyboard callback functions. These callback functions are called when a key is pressed/released respectively. The functions are called with two input arguments. The first argument holds the handle of the calling figure. The second argument holds an event structure which has the following members: 'Character:' The ASCII value of the key 'Key:' Lowercase value of the key 'Modifier:' A cell array containing strings representing the modifiers pressed with the key. 'menubar': {"figure"} | "none" Control the display of the figure menu bar in the upper left of the figure. 'mincolormap': def. '64' 'name': string, def. "" Name to be displayed in the figure title bar. The name is displayed to the right of any title determined by the 'numbertitle' property. 'nextplot': {"add"} | "new" | "replace" | "replacechildren" 'numbertitle': "off" | {"on"} Display "Figure" followed by the numerical figure handle value in the figure title bar. 'outerposition': four-element vector, def. '[-1 -1 -1 -1]' 'paperorientation': "landscape" | {"portrait"} | "rotated" 'paperposition': four-element vector, def. '[0.25000 2.50000 8.00000 6.00000]' Vector '[x0 y0 width height]' defining the position of the figure (in 'paperunits' units) on the printed page. Setting 'paperposition' also forces the 'paperpositionmode' property to be set to "manual". 'paperpositionmode': "auto" | {"manual"} If 'paperpositionmode' is set to "auto", the 'paperposition' property is automatically computed: the printed figure will have the same size as the on-screen figure and will be centered on the output page. 'papersize': two-element vector, def. '[8.5000 11.0000]' Vector '[width height]' defining the size of the paper for printing. Setting this property forces the 'papertype' property to be set to "". 'papertype': "" | "a" | "a0" | "a1" | "a2" | "a3" | "a4" | "a5" | "arch-a" | "arch-b" | "arch-c" | "arch-d" | "arch-e" | "b" | "b0" | "b1" | "b2" | "b3" | "b4" | "b5" | "c" | "d" | "e" | "tabloid" | "uslegal" | {"usletter"} Name of the paper used for printed output. Setting 'papertype' also changes 'papersize' accordingly. 'paperunits': "centimeters" | {"inches"} | "normalized" | "points" The unit used to compute the 'paperposition' property. 'parent': graphics handle, def. '0' Handle of the parent graphics object. 'pointer': {"arrow"} | "botl" | "botr" | "bottom" | "circle" | "cross" | "crosshair" | "custom" | "fleur" | "fullcrosshair" | "hand" | "ibeam" | "left" | "right" | "top" | "topl" | "topr" | "watch" 'pointer' is unused. 'pointershapecdata': def. 16-by-16 double 'pointershapecdata' is unused. 'pointershapehotspot': def. '[0 0]' 'pointershapehotspot' is unused. 'position': four-element vector, def. '[300 200 560 420]' 'renderer': "none" | "opengl" | {"painters"} | "zbuffer" 'renderermode': {"auto"} | "manual" 'resize': "off" | {"on"} 'resizefcn': string | function handle, def. '[](0x0)' 'selected': {"off"} | "on" 'selectionhighlight': "off" | {"on"} 'selectiontype': "alt" | "extend" | {"normal"} | "open" 'selectiontype' is unused. 'tag': string, def. "" A user-defined string to label the graphics object. 'toolbar': {"auto"} | "figure" | "none" 'toolbar' is unused. 'type' (read-only): string Class name of the graphics object. 'type' is always "figure" 'uicontextmenu': graphics handle, def. '[](0x0)' Graphics handle of the uicontextmenu object that is currently associated to this figure object. 'units': "centimeters" | "characters" | "inches" | "normalized" | {"pixels"} | "points" The unit used to compute the 'position' and 'outerposition' properties. 'userdata': Any Octave data, def. '[](0x0)' User-defined data to associate with the graphics object. 'visible': "off" | {"on"} If 'visible' is "off", the figure is not rendered on screen. 'windowbuttondownfcn': string | function handle, def. '[](0x0)' *Note windowbuttonupfcn property: XREFfigurewindowbuttonupfcn. 'windowbuttonmotionfcn': string | function handle, def. '[](0x0)' *Note windowbuttonupfcn property: XREFfigurewindowbuttonupfcn. 'windowbuttonupfcn': string | function handle, def. '[](0x0)' With 'windowbuttondownfcn' and 'windowbuttonmotionfcn', the mouse callback functions. These callback functions are called when a mouse button is pressed, dragged, or released respectively. When these callback functions are executed, the 'currentpoint' property holds the current coordinates of the cursor. 'windowkeypressfcn': string | function handle, def. '[](0x0)' 'windowkeyreleasefcn': string | function handle, def. '[](0x0)' 'windowscrollwheelfcn': string | function handle, def. '[](0x0)' 'windowstyle': "docked" | "modal" | {"normal"} 'wvisual': def. "" 'wvisualmode': {"auto"} | "manual" 'xdisplay': def. "" 'xvisual': def. "" 'xvisualmode': {"auto"} | "manual"  File: octave.info, Node: Axes Properties, Next: Line Properties, Prev: Figure Properties, Up: Graphics Object Properties 15.3.3.3 Axes Properties ........................ The 'axes' properties are: '__modified__': "off" | {"on"} 'activepositionproperty': {"outerposition"} | "position" 'alim': def. '[0 1]' Transparency is not yet implemented for axes objects. 'alim' is unused. 'alimmode': {"auto"} | "manual" 'ambientlightcolor': def. '[1 1 1]' Light is not yet implemented for axes objects. 'ambientlightcolor' is unused. 'beingdeleted': {"off"} | "on" 'box': "off" | {"on"} Control whether the axes has a surrounding box. 'busyaction': "cancel" | {"queue"} 'buttondownfcn': string | function handle, def. '[](0x0)' 'cameraposition': three-element vector, def. '[0.50000 0.50000 9.16025]' 'camerapositionmode': {"auto"} | "manual" 'cameratarget': three-element vector, def. '[0.50000 0.50000 0.50000]' 'cameratargetmode': {"auto"} | "manual" 'cameraupvector': three-element vector, def. '[-0 1 0]' 'cameraupvectormode': {"auto"} | "manual" 'cameraviewangle': scalar, def. '6.6086' 'cameraviewanglemode': {"auto"} | "manual" 'children' (read-only): vector of graphics handles, def. '[](0x1)' Graphics handles of the axes's children. 'clim': two-element vector, def. '[0 1]' Define the limits for the color axis of image children. Setting 'clim' also forces the 'climmode' property to be set to "manual". *Note pcolor function: XREFpcolor. 'climmode': {"auto"} | "manual" 'clipping': "off" | {"on"} 'clipping' is unused. 'color': colorspec, def. '[1 1 1]' Color of the axes background. *Note colorspec: Colors. 'colororder': N-by-3 RGB matrix, def. 7-by-3 double RGB values used by plot function for automatic line coloring. 'createfcn': string | function handle, def. '[](0x0)' Callback function executed immediately after axes has been created. Function is set by using default property on root object, e.g., 'set (0, "defaultaxescreatefcn", 'disp ("axes created!")')'. 'currentpoint': 2-by-3 matrix, def. 2-by-3 double Matrix '[xf, yf, zf; xb, yb, zb]' which holds the coordinates (in axes data units) of the point over which the mouse pointer was when the mouse button was pressed. If a mouse callback function is defined, 'currentpoint' holds the pointer coordinates at the time the mouse button was pressed. For 3-D plots, the first row of the returned matrix specifies the point nearest to the current camera position and the second row the furthest point. The two points forms a line which is perpendicular to the screen. 'dataaspectratio': three-element vector, def. '[1 1 1]' Specify the relative height and width of the data displayed in the axes. Setting 'dataaspectratio' to '[1, 2]' causes the length of one unit as displayed on the x-axis to be the same as the length of 2 units on the y-axis. Setting 'dataaspectratio' also forces the 'dataaspectratiomode' property to be set to "manual". 'dataaspectratiomode': {"auto"} | "manual" 'deletefcn': string | function handle, def. '[](0x0)' Callback function executed immediately before axes is deleted. 'drawmode': "fast" | {"normal"} 'fontangle': "italic" | {"normal"} | "oblique" 'fontname': string, def. "*" Name of the font used for axes annotations. 'fontsize': scalar, def. '10' Size of the font used for axes annotations. *Note fontunits property: XREFaxesfontunits. 'fontunits': "centimeters" | "inches" | "normalized" | "pixels" | {"points"} Unit used to interpret 'fontsize' property. 'fontweight': "bold" | "demi" | "light" | {"normal"} 'gridlinestyle': "-" | "-" | "-." | {":"} | "none" 'handlevisibility': "callback" | "off" | {"on"} If 'handlevisibility' is "off", the axes's handle is not visible in its parent's "children" property. 'hittest': "off" | {"on"} 'interpreter': "latex" | {"none"} | "tex" 'interruptible': "off" | {"on"} 'layer': {"bottom"} | "top" Control whether the axes is drawn below child graphics objects (ticks, labels, etc. covered by plotted objects) or above. 'linestyleorder': def. "-" 'linewidth': def. '0.50000' 'minorgridlinestyle': "-" | "-" | "-." | {":"} | "none" 'mousewheelzoom': scalar in the range (0, 1), def. '0.50000' Fraction of axes limits to zoom for each wheel movement. 'nextplot': "add" | {"replace"} | "replacechildren" 'outerposition': four-element vector, def. '[0 0 1 1]' Specify the position of the plot including titles, axes, and legend. The four elements of the vector are the coordinates of the lower left corner and width and height of the plot, in units normalized to the width and height of the plot window. For example, '[0.2, 0.3, 0.4, 0.5]' sets the lower left corner of the axes at (0.2, 0.3) and the width and height to be 0.4 and 0.5 respectively. *Note position property: XREFaxesposition. 'parent': graphics handle Handle of the parent graphics object. 'plotboxaspectratio': def. '[1 1 1]' 'plotboxaspectratiomode': {"auto"} | "manual" 'position': four-element vector, def. '[0.13000 0.11000 0.77500 0.81500]' Specify the position of the plot excluding titles, axes, and legend. The four elements of the vector are the coordinates of the lower left corner and width and height of the plot, in units normalized to the width and height of the plot window. For example, '[0.2, 0.3, 0.4, 0.5]' sets the lower left corner of the axes at (0.2, 0.3) and the width and height to be 0.4 and 0.5 respectively. *Note outerposition property: XREFaxesouterposition. 'projection': {"orthographic"} | "perspective" 'selected': {"off"} | "on" 'selectionhighlight': "off" | {"on"} 'tag': string, def. "" A user-defined string to label the graphics object. 'tickdir': {"in"} | "out" Control whether axes tick marks project "in" to the plot box or "out". 'tickdirmode': {"auto"} | "manual" 'ticklength': two-element vector, def. '[0.010000 0.025000]' Two-element vector '[2Dlen 3Dlen]' specifying the length of the tickmarks relative to the longest visible axis. 'tightinset' (read-only): def. '[0.042857 0.038106 0.000000 0.023810]' 'title': graphics handle Graphics handle of the title text object. 'type' (read-only): string Class name of the graphics object. 'type' is always "axes" 'uicontextmenu': graphics handle, def. '[](0x0)' Graphics handle of the uicontextmenu object that is currently associated to this axes object. 'units': "centimeters" | "characters" | "inches" | {"normalized"} | "pixels" | "points" 'userdata': Any Octave data, def. '[](0x0)' User-defined data to associate with the graphics object. 'view': two-element vector, def. '[0 90]' Two-element vector '[azimuth elevation]' specifying the viewpoint for three-dimensional plots 'visible': "off" | {"on"} If 'visible' is "off", the axes is not rendered on screen. 'xaxislocation': {"bottom"} | "top" | "zero" 'xcolor': {colorspec} | "none", def. '[0 0 0]' Color of the x-axis. *Note colorspec: Colors. 'xdir': {"normal"} | "reverse" 'xgrid': {"off"} | "on" Control whether major x grid lines are displayed. 'xlabel': graphics handle Graphics handle of the x label text object. 'xlim': two-element vector, def. '[0 1]' Two-element vector '[xmin xmax]' specifying the limits for the x-axis. Setting 'xlim' also forces the 'xlimmode' property to be set to "manual". *Note xlim function: XREFxlim. 'xlimmode': {"auto"} | "manual" 'xminorgrid': {"off"} | "on" Control whether minor x grid lines are displayed. 'xminortick': {"off"} | "on" 'xscale': {"linear"} | "log" 'xtick': vector, def. 1-by-6 double Position of x tick marks. Setting 'xtick' also forces the 'xtickmode' property to be set to "manual". 'xticklabel': string | cell array of strings, def. 1-by-6 cell Labels of x tick marks. Setting 'xticklabel' also forces the 'xticklabelmode' property to be set to "manual". 'xticklabelmode': {"auto"} | "manual" 'xtickmode': {"auto"} | "manual" 'yaxislocation': {"left"} | "right" | "zero" 'ycolor': {colorspec} | "none", def. '[0 0 0]' Color of the y-axis. *Note colorspec: Colors. 'ydir': {"normal"} | "reverse" 'ygrid': {"off"} | "on" Control whether major y grid lines are displayed. 'ylabel': graphics handle Graphics handle of the y label text object. 'ylim': two-element vector, def. '[0 1]' Two-element vector '[ymin ymax]' specifying the limits for the y-axis. Setting 'ylim' also forces the 'ylimmode' property to be set to "manual". *Note ylim function: XREFylim. 'ylimmode': {"auto"} | "manual" 'yminorgrid': {"off"} | "on" Control whether minor y grid lines are displayed. 'yminortick': {"off"} | "on" 'yscale': {"linear"} | "log" 'ytick': vector, def. 1-by-6 double Position of y tick marks. Setting 'ytick' also forces the 'ytickmode' property to be set to "manual". 'yticklabel': string | cell array of strings, def. 1-by-6 cell Labels of y tick marks. Setting 'yticklabel' also forces the 'yticklabelmode' property to be set to "manual". 'yticklabelmode': {"auto"} | "manual" 'ytickmode': {"auto"} | "manual" 'zcolor': {colorspec} | "none", def. '[0 0 0]' Color of the z-axis. *Note colorspec: Colors. 'zdir': {"normal"} | "reverse" 'zgrid': {"off"} | "on" Control whether major z grid lines are displayed. 'zlabel': graphics handle Graphics handle of the z label text object. 'zlim': two-element vector, def. '[0 1]' Two-element vector '[zmin zmaz]' specifying the limits for the z-axis. Setting 'zlim' also forces the 'zlimmode' property to be set to "manual". *Note zlim function: XREFzlim. 'zlimmode': {"auto"} | "manual" 'zminorgrid': {"off"} | "on" Control whether minor z grid lines are displayed. 'zminortick': {"off"} | "on" 'zscale': {"linear"} | "log" 'ztick': vector, def. 1-by-6 double Position of z tick marks. Setting 'ztick' also forces the 'ztickmode' property to be set to "manual". 'zticklabel': string | cell array of strings, def. 1-by-6 cell Labels of z tick marks. Setting 'zticklabel' also forces the 'zticklabelmode' property to be set to "manual". 'zticklabelmode': {"auto"} | "manual" 'ztickmode': {"auto"} | "manual"  File: octave.info, Node: Line Properties, Next: Text Properties, Prev: Axes Properties, Up: Graphics Object Properties 15.3.3.4 Line Properties ........................ The 'line' properties are: '__modified__': "off" | {"on"} 'beingdeleted': {"off"} | "on" 'busyaction': "cancel" | {"queue"} 'buttondownfcn': string | function handle, def. '[](0x0)' 'children' (read-only): vector of graphics handles, def. '[](0x1)' 'children' is unused. 'clipping': "off" | {"on"} If 'clipping' is "on", the line is clipped in its parent axes limits. 'color': colorspec, def. '[0 0 0]' Color of the line object. *Note colorspec: Colors. 'createfcn': string | function handle, def. '[](0x0)' Callback function executed immediately after line has been created. Function is set by using default property on root object, e.g., 'set (0, "defaultlinecreatefcn", 'disp ("line created!")')'. 'deletefcn': string | function handle, def. '[](0x0)' Callback function executed immediately before line is deleted. 'displayname': string | cell array of strings, def. "" Text for the legend entry corresponding to this line. 'erasemode': "background" | "none" | {"normal"} | "xor" 'erasemode' is unused. 'handlevisibility': "callback" | "off" | {"on"} If 'handlevisibility' is "off", the line's handle is not visible in its parent's "children" property. 'hittest': "off" | {"on"} 'interpreter': "latex" | "none" | {"tex"} 'interruptible': "off" | {"on"} 'linestyle': {"-"} | "-" | "-." | ":" | "none" *Note Line Styles::. 'linewidth': def. '0.50000' Width of the line object measured in points. 'marker': "*" | "+" | "." | "<" | ">" | "^" | "d" | "diamond" | "h" | "hexagram" | {"none"} | "o" | "p" | "pentagram" | "s" | "square" | "v" | "x" Shape of the marker for each data point. *Note Marker Styles::. 'markeredgecolor': {"auto"} | "none" Color of the edge of the markers. When set to "auto", the marker edges have the same color as the line. If set to "none", no marker edges are displayed. This property can also be set to any color. *Note colorspec: Colors. 'markerfacecolor': "auto" | {"none"} Color of the face of the markers. When set to "auto", the marker faces have the same color as the line. If set to "none", the marker faces are not displayed. This property can also be set to any color. *Note colorspec: Colors. 'markersize': scalar, def. '6' Size of the markers measured in points. 'parent': graphics handle Handle of the parent graphics object. 'selected': {"off"} | "on" 'selectionhighlight': "off" | {"on"} 'tag': string, def. "" A user-defined string to label the graphics object. 'type' (read-only): string Class name of the graphics object. 'type' is always "line" 'uicontextmenu': graphics handle, def. '[](0x0)' Graphics handle of the uicontextmenu object that is currently associated to this line object. 'userdata': Any Octave data, def. '[](0x0)' User-defined data to associate with the graphics object. 'visible': "off" | {"on"} If 'visible' is "off", the line is not rendered on screen. 'xdata': vector, def. '[0 1]' Vector of x data to be plotted. 'xdatasource': string, def. "" Name of a vector in the current base workspace to use as x data. 'ydata': vector, def. '[0 1]' Vector of y data to be plotted. 'ydatasource': string, def. "" Name of a vector in the current base workspace to use as y data. 'zdata': vector, def. '[](0x0)' Vector of z data to be plotted. 'zdatasource': string, def. "" Name of a vector in the current base workspace to use as z data.  File: octave.info, Node: Text Properties, Next: Image Properties, Prev: Line Properties, Up: Graphics Object Properties 15.3.3.5 Text Properties ........................ The 'text' properties are: '__modified__': "off" | {"on"} 'backgroundcolor': colorspec, def. "none" Background area is not yet implemented for text objects. 'backgroundcolor' is unused. 'beingdeleted': {"off"} | "on" 'busyaction': "cancel" | {"queue"} 'buttondownfcn': string | function handle, def. '[](0x0)' 'children' (read-only): vector of graphics handles, def. '[](0x1)' 'children' is unused. 'clipping': "off" | {"on"} If 'clipping' is "on", the text is clipped in its parent axes limits. 'color': colorspec, def. '[0 0 0]' Color of the text. *Note colorspec: Colors. 'createfcn': string | function handle, def. '[](0x0)' Callback function executed immediately after text has been created. Function is set by using default property on root object, e.g., 'set (0, "defaulttextcreatefcn", 'disp ("text created!")')'. 'deletefcn': string | function handle, def. '[](0x0)' Callback function executed immediately before text is deleted. 'displayname': def. "" 'edgecolor': colorspec, def. "none" Background area is not yet implemented for text objects. 'edgecolor' is unused. 'editing': {"off"} | "on" 'erasemode': "background" | "none" | {"normal"} | "xor" 'erasemode' is unused. 'extent' (read-only): def. '[0.000000 -0.005843 0.000000 0.032136]' 'fontangle': "italic" | {"normal"} | "oblique" Flag whether the font is italic or normal. 'fontangle' is currently unused. 'fontname': string, def. "*" The font used for the text. 'fontsize': scalar, def. '10' The font size of the text as measured in 'fontunits'. 'fontunits': "centimeters" | "inches" | "normalized" | "pixels" | {"points"} The units used to interpret 'fontsize' property. 'fontweight': "bold" | "demi" | "light" | {"normal"} Control variant of base font used: bold, light, normal, etc. 'handlevisibility': "callback" | "off" | {"on"} If 'handlevisibility' is "off", the text's handle is not visible in its parent's "children" property. 'hittest': "off" | {"on"} 'horizontalalignment': "center" | {"left"} | "right" 'interpreter': "latex" | "none" | {"tex"} 'interruptible': "off" | {"on"} 'linestyle': {"-"} | "-" | "-." | ":" | "none" Background area is not yet implemented for text objects. 'linestyle' is unused. 'linewidth': scalar, def. '0.50000' Background area is not yet implemented for text objects. 'linewidth' is unused. 'margin': scalar, def. '2' Background area is not yet implemented for text objects. 'margin' is unused. 'parent': graphics handle Handle of the parent graphics object. 'position': four-element vector, def. '[0 0 0]' Vector '[X0 Y0 Z0]' where X0, Y0 and Z0 indicate the position of the text anchor as defined by 'verticalalignment' and 'horizontalalignment'. 'rotation': scalar, def. '0' The angle of rotation for the displayed text, measured in degrees. 'selected': {"off"} | "on" 'selectionhighlight': "off" | {"on"} 'string': string, def. "" The text object string content. 'tag': string, def. "" A user-defined string to label the graphics object. 'type' (read-only): string Class name of the graphics object. 'type' is always "text" 'uicontextmenu': graphics handle, def. '[](0x0)' Graphics handle of the uicontextmenu object that is currently associated to this text object. 'units': "centimeters" | {"data"} | "inches" | "normalized" | "pixels" | "points" 'userdata': Any Octave data, def. '[](0x0)' User-defined data to associate with the graphics object. 'verticalalignment': "baseline" | "bottom" | "cap" | {"middle"} | "top" 'visible': "off" | {"on"} If 'visible' is "off", the text is not rendered on screen.  File: octave.info, Node: Image Properties, Next: Patch Properties, Prev: Text Properties, Up: Graphics Object Properties 15.3.3.6 Image Properties ......................... The 'image' properties are: '__modified__': "off" | {"on"} 'alphadata': scalar | matrix, def. '1' Transparency is not yet implemented for image objects. 'alphadata' is unused. 'alphadatamapping': "direct" | {"none"} | "scaled" Transparency is not yet implemented for image objects. 'alphadatamapping' is unused. 'beingdeleted': {"off"} | "on" 'busyaction': "cancel" | {"queue"} 'buttondownfcn': string | function handle, def. '[](0x0)' 'cdata': matrix, def. 64-by-64 double 'cdatamapping': {"direct"} | "scaled" 'children' (read-only): vector of graphics handles, def. '[](0x1)' 'children' is unused. 'clipping': "off" | {"on"} If 'clipping' is "on", the image is clipped in its parent axes limits. 'createfcn': string | function handle, def. '[](0x0)' Callback function executed immediately after image has been created. Function is set by using default property on root object, e.g., 'set (0, "defaultimagecreatefcn", 'disp ("image created!")')'. 'deletefcn': string | function handle, def. '[](0x0)' Callback function executed immediately before image is deleted. 'displayname': string | cell array of strings, def. "" Text for the legend entry corresponding to this image. 'erasemode': "background" | "none" | {"normal"} | "xor" 'erasemode' is unused. 'handlevisibility': "callback" | "off" | {"on"} If 'handlevisibility' is "off", the image's handle is not visible in its parent's "children" property. 'hittest': "off" | {"on"} 'interruptible': "off" | {"on"} 'parent': graphics handle Handle of the parent graphics object. 'selected': {"off"} | "on" 'selectionhighlight': "off" | {"on"} 'tag': string, def. "" A user-defined string to label the graphics object. 'type' (read-only): string Class name of the graphics object. 'type' is always "image" 'uicontextmenu': graphics handle, def. '[](0x0)' Graphics handle of the uicontextmenu object that is currently associated to this image object. 'userdata': Any Octave data, def. '[](0x0)' User-defined data to associate with the graphics object. 'visible': "off" | {"on"} If 'visible' is "off", the image is not rendered on screen. 'xdata': two-element vector, def. '[1 64]' Two-element vector '[xmin xmax]' specifying the x coordinates of the first and last columns of the image. Setting 'xdata' to the empty matrix ([]) will restore the default value of '[1 columns(image)]'. 'ydata': two-element vector, def. '[1 64]' Two-element vector '[ymin ymax]' specifying the y coordinates of the first and last rows of the image. Setting 'ydata' to the empty matrix ([]) will restore the default value of '[1 rows(image)]'.  File: octave.info, Node: Patch Properties, Next: Surface Properties, Prev: Image Properties, Up: Graphics Object Properties 15.3.3.7 Patch Properties ......................... The 'patch' properties are: '__modified__': "off" | {"on"} 'alphadatamapping': "direct" | "none" | {"scaled"} Transparency is not yet implemented for patch objects. 'alphadatamapping' is unused. 'ambientstrength': scalar, def. '0.30000' Light is not yet implemented for patch objects. 'ambientstrength' is unused. 'backfacelighting': "lit" | {"reverselit"} | "unlit" Light is not yet implemented for patch objects. 'backfacelighting' is unused. 'beingdeleted': {"off"} | "on" 'busyaction': "cancel" | {"queue"} 'buttondownfcn': string | function handle, def. '[](0x0)' 'cdata': scalar | matrix, def. '[](0x0)' Data defining the patch object color. Patch color can be defined for faces or for vertices. If 'cdata' is a scalar index into the current colormap or a RGB triplet, it defines the color of all faces. If 'cdata' is an N-by-1 vector of indices or an N-by-3 (RGB) matrix, it defines the color of each one of the N faces. If 'cdata' is an N-by-M or an N-by-M-by-3 (RGB) matrix, it defines the color at each vertex. 'cdatamapping': "direct" | {"scaled"} 'children' (read-only): vector of graphics handles, def. '[](0x1)' 'children' is unused. 'clipping': "off" | {"on"} If 'clipping' is "on", the patch is clipped in its parent axes limits. 'createfcn': string | function handle, def. '[](0x0)' Callback function executed immediately after patch has been created. Function is set by using default property on root object, e.g., 'set (0, "defaultpatchcreatefcn", 'disp ("patch created!")')'. 'deletefcn': string | function handle, def. '[](0x0)' Callback function executed immediately before patch is deleted. 'diffusestrength': scalar, def. '0.60000' Light is not yet implemented for patch objects. 'diffusestrength' is unused. 'displayname': def. "" Text of the legend entry corresponding to this patch. 'edgealpha': scalar | matrix, def. '1' Transparency is not yet implemented for patch objects. 'edgealpha' is unused. 'edgecolor': def. '[0 0 0]' 'edgelighting': "flat" | "gouraud" | {"none"} | "phong" Light is not yet implemented for patch objects. 'edgelighting' is unused. 'erasemode': "background" | "none" | {"normal"} | "xor" 'erasemode' is unused. 'facealpha': scalar | matrix, def. '1' Transparency is not yet implemented for patch objects. 'facealpha' is unused. 'facecolor': {colorspec} | "none" | "flat" | "interp", def. '[0 0 0]' 'facelighting': "flat" | "gouraud" | {"none"} | "phong" Light is not yet implemented for patch objects. 'facelighting' is unused. 'faces': def. '[1 2 3]' 'facevertexalphadata': scalar | matrix, def. '[](0x0)' Transparency is not yet implemented for patch objects. 'facevertexalphadata' is unused. 'facevertexcdata': def. '[](0x0)' 'handlevisibility': "callback" | "off" | {"on"} If 'handlevisibility' is "off", the patch's handle is not visible in its parent's "children" property. 'hittest': "off" | {"on"} 'interpreter': "latex" | "none" | {"tex"} 'interpreter' is unused. 'interruptible': "off" | {"on"} 'linestyle': {"-"} | "-" | "-." | ":" | "none" 'linewidth': def. '0.50000' 'marker': "*" | "+" | "." | "<" | ">" | "^" | "d" | "diamond" | "h" | "hexagram" | {"none"} | "o" | "p" | "pentagram" | "s" | "square" | "v" | "x" *Note line marker property: XREFlinemarker. 'markeredgecolor': {"auto"} | "flat" | "none" *Note line markeredgecolor property: XREFlinemarkeredgecolor. 'markerfacecolor': "auto" | "flat" | {"none"} *Note line markerfacecolor property: XREFlinemarkerfacecolor. 'markersize': scalar, def. '6' *Note line markersize property: XREFlinemarkersize. 'normalmode': {"auto"} | "manual" 'parent': graphics handle Handle of the parent graphics object. 'selected': {"off"} | "on" 'selectionhighlight': "off" | {"on"} 'specularcolorreflectance': scalar, def. '1' Light is not yet implemented for patch objects. 'specularcolorreflectance' is unused. 'specularexponent': scalar, def. '10' Light is not yet implemented for patch objects. 'specularexponent' is unused. 'specularstrength': scalar, def. '0.90000' Light is not yet implemented for patch objects. 'specularstrength' is unused. 'tag': string, def. "" A user-defined string to label the graphics object. 'type' (read-only): string Class name of the graphics object. 'type' is always "patch" 'uicontextmenu': graphics handle, def. '[](0x0)' Graphics handle of the uicontextmenu object that is currently associated to this patch object. 'userdata': Any Octave data, def. '[](0x0)' User-defined data to associate with the graphics object. 'vertexnormals': def. '[](0x0)' 'vertices': vector | matrix, def. 3-by-2 double 'visible': "off" | {"on"} If 'visible' is "off", the patch is not rendered on screen. 'xdata': vector | matrix, def. '[0; 1; 0]' 'ydata': vector | matrix, def. '[1; 1; 0]' 'zdata': vector | matrix, def. '[](0x0)'