This is Info file octave, produced by Makeinfo-1.64 from the input file
octave.tex.

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

   Copyright (C) 1996 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,  Node: Signal Processing,  Next: Sets,  Prev: Control Theory,  Up: Top

Signal Processing
*****************

   I hope that someday Octave will include more signal processing
functions.  If you would like to help improve Octave in this area,
please contact `bug-octave@bevo.che.wisc.edu'.

 - Function:  fft (A [, N])
     Compute the FFT of A using subroutines from FFTPACK.  If A is a
     matrix, `fft' computes the FFT for each column of A.

     If called with two arguments, N is expected to be an integer
     specifying the number of elements of A to use.  If A is a matrix,
     N specifies the number of rows of A to use.  If N is larger than
     the size of A, A is resized and padded with zeros.

 - Loadable Function:  ifft (A [, N])
     Compute the inverse FFT of A using subroutines from FFTPACK.  If A
     is a matrix, `fft' computes the inverse FFT for each column of A.

     If called with two arguments, N is expected to be an integer
     specifying the number of elements of A to use.  If A is a matrix,
     N specifies the number of rows of A to use.  If N is larger than
     the size of A, A is resized and padded with zeros.

 - Loadable Function:  fft2 (A [, N [, M]])
     Compute the two dimensional FFT of A.

     The optional arguments N and M may be used specify the number of
     rows and columns of A to use.  If either of these is larger than
     the size of A, A is resized and padded with zeros.

 - Loadable Function:  ifft2 (A [, N [, M]])
     Compute the two dimensional inverse FFT of A.

     The optional arguments N and M may be used specify the number of
     rows and columns of A to use.  If either of these is larger than
     the size of A, A is resized and padded with zeros.

 - Built-in Function:  fftconv (A, B, N)
     This function returns the convolution of the vectors A and B, a
     vector with length equal to the `length (a) + length (b) - 1'.  If
     A and B are the coefficient vectors of two polynomials, the
     returned value is the coefficient vector of the product polynomial.

     The computation uses the FFT by calling the function `fftfilt'.  If
     the optional argument N is specified, an N-point FFT is used.

 - Function File:  fftfilt (B, X, N)
     With two arguments, `fftfilt' filters X with the FIR filter B
     using the FFT.

     Given the optional third argument, N, `fftfilt' uses the
     overlap-add method to filter X with B using an N-point FFT.

 - Loadable Function: y = filter (B, A, X)
     This function returns the solution to the following linear,
     time-invariant difference equation:

             N                   M
            SUM a(k+1) y(n-k) = SUM b(k+1) x(n-k)      for 1<=n<=length(x)
            k=0                 k=0

     where  N=length(a)-1 and M=length(b)-1.  An equivalent form of
     this equation is:

                      N                   M
            y(n) = - SUM c(k+1) y(n-k) + SUM d(k+1) x(n-k)  for 1<=n<=length(x)
                     k=1                 k=0

     where  c = a/a(1) and d = b/a(1).

     In terms of the z-transform, y is the result of passing the
     discrete- time signal x through a system characterized by the
     following rational system function:

                       M
                      SUM d(k+1) z^(-k)
                      k=0
            H(z) = ----------------------
                         N
                    1 + SUM c(k+1) z(-k)
                        k=1

 - Loadable Function: [Y, SF] = filter (B, A, X, SI)
     This is the same as the `filter' function described above, except
     that SI is taken as the initial state of the system and the final
     state is returned as SF.  The state vector is a column vector
     whose length is equal to the length of the longest coefficient
     vector minus one.  If SI is not set, the initial state vector is
     set to all zeros.

 - Function File:  freqz
     Compute the frequency response of a filter.

     `[H, W] = freqz (B)' returns the complex frequency response H of
     the FIR filter with coefficients B. The response is evaluated at
     512 angular frequencies between 0 and  pi.

     The output value W is a vector containing the 512 frequencies.

     `[H, W] = freqz (B, A)' returns the complex frequency response of
     the rational IIR filter whose numerator has coefficients B and
     denominator coefficients A.

     `[H, W] = freqz (B, A, N)' returns the response evaluated at N
     angular frequencies.  For fastest computation n should factor into
     a small number of small primes.

     `[H, W] = freqz (B, A, N, "whole")' evaluates the response at n
     frequencies between 0 and  2*pi.

 - Function File:  sinc (X)
     Returns  sin(pi*x)/(pi*x).


File: octave,  Node: Sets,  Next: Statistics,  Prev: Signal Processing,  Up: Top

Sets
****

   Octave has a limited set of functions for managing sets of data,
where a set is defined as a collection unique elements.

 - Function File:  create_set (X)
     Given a matrix or vector of values, the function `create_set'
     returns a row vector containing unique values, sorted in ascending
     order.  For example,

          create_set ([ 1, 2; 3, 4; 4, 2 ])

     returns the vector

          [ 1, 2, 3, 4 ]

 - Function File:  union (X, Y)
     Return the set of elements that are in either of the sets X and Y.
     For example,

          union ([ 1, 2, 3 ], [ 2, 3, 5 ])

     returns the vector

          [ 1, 2, 5 ]

 - Function File:  intersection (X, Y)
     Return the set of elements that are in both sets X and Y.

 - Function File:  complement (X, Y)
     Returns the elements of set Y that are not in set X.  For example,

          complement ([ 1, 2, 3 ], [ 2, 3, 5 ])

     returns the value `5'.


File: octave,  Node: Statistics,  Next: Plotting,  Prev: Sets,  Up: Top

Statistics
**********

   I hope that someday Octave will include more statistics functions.
If you would like to help improve Octave in this area, please contact
`bug-octave@bevo.che.wisc.edu'.

 - Function File:  mean (X)
     If X is a vector, compute the mean of the elements of X

          mean (x) = SUM_i x(i) / N
     If X is a matrix, compute the mean for each column and return them
     in a row vector.

 - Function File:  median (X)
     If X is a vector, compute the median value of the elements of X.

                      x(ceil(N/2)),             N odd
          median(x) =
                      (x(N/2) + x((N/2)+1))/2,  N even
     If X is a matrix, compute the median value for each column
     and return them in a row vector.

 - Function File:  std (X)
     If X is a vector, compute the standard deviation of the elements
     of X.

          std (x) = sqrt (sumsq (x - mean (x)) / (n - 1))
     If X is a matrix, compute the standard deviation for each
     column and return them in a row vector.

 - Function File:  cov (X [, Y])
     If each row of X and Y is an observation and each column is a
     variable, the (I,J)-th entry of `cov (X, Y)' is the covariance
     between the I-th variable in X and the J-th variable in Y.  If
     called with one argument, compute `cov (X, X)'.

 - Function File:  corrcoef (X [, Y])
     If each row of X and Y is an observation and each column is a
     variable, the (I,J)-th entry of `corrcoef (X, Y)' is the
     correlation between the I-th variable in X and the J-th variable
     in Y.  If called with one argument, compute `corrcoef (X, X)'.

 - Function File:  kurtosis (X)
     If X is a vector of length N, return the kurtosis

          kurtosis (x) = N^(-1) std(x)^(-4) sum ((x - mean(x)).^4) - 3

     of X.  If X is a matrix, return the row vector containing the
     kurtosis of each column.

 - Function File:  mahalanobis (X, Y)
     Returns Mahalanobis' D-square distance between the multivariate
     samples X and Y, which must have the same number of components
     (columns), but may have a different number of observations (rows).

 - Function File:  skewness (X)
     If X is a vector of length N, return the skewness

          skewness (x) = N^(-1) std(x)^(-3) sum ((x - mean(x)).^3)

     of X.  If X is a matrix, return the row vector containing the
     skewness of each column.


File: octave,  Node: Plotting,  Next: Image Processing,  Prev: Statistics,  Up: Top

Plotting
********

   All of Octave's plotting functions use `gnuplot' to handle the
actual graphics.  There are two low-level functions, `gplot' and
`gsplot', that behave almost exactly like the corresponding `gnuplot'
functions `plot' and `splot'.  A number of other higher level plotting
functions, patterned after the graphics functions found in MATLAB
version 3.5, are also available.  These higher level functions are all
implemented in terms of the two low-level plotting functions.

* Menu:

* Two-Dimensional Plotting::
* Three-Dimensional Plotting::
* Miscellaneous Plotting Functions::


File: octave,  Node: Two-Dimensional Plotting,  Next: Three-Dimensional Plotting,  Prev: Plotting,  Up: Plotting

Two-Dimensional Plotting
========================

 - Command: gplot RANGES EXPRESSION USING TITLE STYLE
     Generate a 2-dimensional plot.

     The RANGES, USING, TITLE, and STYLE arguments are optional, and
     the USING, TITLE and STYLE qualifiers may appear in any order
     after the expression.  You may plot multiple expressions with a
     single command by separating them with commas.  Each expression
     may have its own set of qualifiers.

     The optional item RANGES has the syntax

          [ x_lo : x_up ] [ y_lo : y_up ]

     and may be used to specify the ranges for the axes of the plot,
     independent of the actual range of the data.  The range for the y
     axes and any of the individual limits may be omitted.  A range
     `[:]' indicates that the default limits should be used.  This
     normally means that a range just large enough to include all the
     data points will be used.

     The expression to be plotted must not contain any literal matrices
     (e.g. `[ 1, 2; 3, 4 ]') since it is nearly impossible to
     distinguish a plot range from a matrix of data.

     See the help for `gnuplot' for a description of the syntax for the
     optional items.

     By default, the `gplot' command plots the second column of a matrix
     versus the first.  If the matrix only has one column, it is taken
     as a vector of y-coordinates and the x-coordinate is taken as the
     element index, starting with zero.  For example,

          gplot rand (100,1) with linespoints

     will plot 100 random values and connect them with lines.  When
     `gplot' is used to plot a column vector, the indices of the
     elements are taken as x values.

     If there are more than two columns, you can choose which columns
     to plot with the USING qualifier. For example, given the data

          x = (-10:0.1:10)';
          data = [x, sin(x), cos(x)];

     the command

          gplot [-11:11] [-1.1:1.1] data with lines, data using 1:3 with impulses

     will plot two lines.  The first line is generated by the command
     `data with lines', and is a graph of the sine function over the
     range -10 to 10.  The data is taken from the first two columns of
     the matrix because columns to plot were not specified with the
     USING qualifier.

     The clause `using 1:3' in the second part of this plot command
     specifies that the first and third columns of the matrix `data'
     should be taken as the values to plot.

     In this example, the ranges have been explicitly specified to be a
     bit larger than the actual range of the data so that the curves do
     not touch the border of the plot.

 - Command: set OPTIONS
 - Command: show OPTIONS
 - Command: replot OPTIONS
     In addition to the basic plotting commands, the whole range of
     `set' and `show' commands from `gnuplot' are available, as is
     `replot'.

     The `set' and `show' commands allow you to set and show `gnuplot'
     parameters.  For more information about the set and show commands,
     see the `gnuplot' user's guide (also available on line if you run
     `gnuplot' directly, instead of running it from Octave).

     The `replot' command allows you to force the plot to be
     redisplayed.  This is useful if you have changed something about
     the plot, such as the title or axis labels.  The `replot' command
     also accepts the same arguments as `gplot' or `gsplot' (except for
     data ranges) so you can add additional lines to existing plots.

     For example,

          set term tek40
          set output "/dev/plotter"
          set title "sine with lines and cosine with impulses"
          replot "sin (x) w l"

     will change the terminal type for plotting, add a title to the
     current plot, add a graph of sin (x) to the plot, and force the
     new plot to be sent to the plot device.  This last step is
     normally required in order to update the plot.  This default is
     reasonable for slow terminals or hardcopy output devices because
     even when you are adding additional lines with a replot command,
     gnuplot always redraws the entire plot, and you probably don't
     want to have a completely new plot generated every time something
     as minor as an axis label changes.

 - Built-in Variable: automatic_replot
     You can tell Octave to redisplay the plot each time anything about
     it changes by setting the value of the builtin variable
     `automatic_replot' to a nonzero value.  Since this is fairly
     inefficient, the default value is 0.

   Note that NaN values in the plot data are automatically omitted, and
Inf values are converted to a very large value before calling gnuplot.

   The MATLAB-style two-dimensional plotting commands are:

 - Function File:  plot (ARGS)
     This function produces two-dimensional 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 indices of the elements, starting
     with 1.

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

          plot (x [, y] [, fmt] ...)

     where Y and FMT are optional, and 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 the first argument is a vector and the second is a matrix,
          the the vector is plotted versus the columns (or rows) of the
          matrix.  (using whichever combination matches, with columns
          tried first.)

        * If the first argument is a matrix and the second is a vector,
          the the columns (or rows) of the matrix are plotted versus
          the vector.  (using whichever combination matches, with
          columns tried first.)

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

        * 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.

          If both arguments are scalars, a single point is plotted.

     The FMT argument, if present is interpreted as follows.  If FMT is
     missing, the default gnuplot line style is assumed.

    `-'
          Set lines plot style (default).

    `.'
          Set dots plot style.

    `@'
          Set points plot style.

    `-@'
          Set linespoints plot style.

    `^'
          Set impulses plot style.

    `L'
          Set steps plot style.

    `#'
          Set boxes plot style.

    `~'
          Set errorbars plot style.

    `#~'
          Set boxerrorbars plot style.

    `n'
          Interpreted as the plot color if N is an integer in the range
          1 to 6.

    `nm'
          If NM is a two digit integer and M is an integer in the range
          1 to 6, M is interpreted as the point style.  This is only
          valid in combination with the `@' or `-@' specifiers.

    `c'
          If C is one of "R", "G", "B", "M", "C", or "W", it is
          interpreted as the plot color (red, green, blue, magenta,
          cyan, or white).

    `+'
    `*'
    `o'
    `x'
          Used in combination with the points or linespoints styles,
          set the point style.

     The color line styles have the following meanings on terminals that
     support color.

          Number  Gnuplot colors  (lines)points style
            1       red                   *
            2       green                 +
            3       blue                  o
            4       magenta               x
            5       cyan                house
            6       brown            there exists

     Here are some plot examples:

          plot (x, y, "@12", x, y2, x, y3, "4", x, y4, "+")

     This command will plot Y with points of type 2 (displayed as `+')
     and color 1 (red), Y2 with lines, Y3 with lines of color 4
     (magenta) and Y4 with points displayed as `+'.

          plot (b, "*")

     This command will plot the data in B will be plotted with points
     displayed as `*'.

 - Function File:  hold ARGS
     Tell Octave to `hold' the current data on the plot when executing
     subsequent plotting commands.  This allows you to execute a series
     of plot commands and have all the lines end up on the same figure.
     The default is for each new plot command to clear the plot device
     first.  For example, the command

          hold on

     turns the hold state on.  An argument of `off' turns the hold state
     off, and `hold' with no arguments toggles the current hold state.

 - Function File:  ishold
     Returns 1 if the next line will be added to the current plot, or 0
     if the plot device will be cleared before drawing the next line.

 - Function File:  loglog (ARGS)
     Make a two-dimensional plot using log scales for both axes.  See
     the description of `plot' above for a description of the arguments
     that `loglog' will accept.

 - Function File:  semilogx (ARGS)
     Make a two-dimensional plot using a log scale for the X axis.  See
     the description of `plot' above for a description of the arguments
     that `semilogx' will accept.

 - Function File:  semilogy (ARGS)
     Make a two-dimensional plot using a log scale for the Y axis.  See
     the description of `plot' above for a description of the arguments
     that `semilogy' will accept.

 - Function File:  contour (Z, N, X, Y)
     Make a contour plot of the three-dimensional surface described by
     Z.  Someone needs to improve `gnuplot''s contour routines before
     this will be very useful.

 - Function File:  polar (THETA, RHO)
     Make a two-dimensional plot given polar the coordinates THETA and
     RHO.


File: octave,  Node: Three-Dimensional Plotting,  Next: Miscellaneous Plotting Functions,  Prev: Two-Dimensional Plotting,  Up: Plotting

Three-Dimensional Plotting
==========================

 - Command: gsplot RANGES EXPRESSION USING TITLE STYLE
     Generate a 3-dimensional plot.

     The RANGES, USING, TITLE, and STYLE arguments are optional, and
     the USING, TITLE and STYLE qualifiers may appear in any order
     after the expression.  You may plot multiple expressions with a
     single command by separating them with commas.  Each expression
     may have its own set of qualifiers.

     The optional item RANGES has the syntax

          [ x_lo : x_up ] [ y_lo : y_up ] [ z_lo : z_up ]

     and may be used to specify the ranges for the axes of the plot,
     independent of the actual range of the data.  The range for the y
     and z axes and any of the individual limits may be omitted.  A
     range `[:]' indicates that the default limits should be used.  This
     normally means that a range just large enough to include all the
     data points will be used.

     The expression to be plotted must not contain any literal matrices
     (e.g.  `[ 1, 2; 3, 4 ]') since it is nearly impossible to
     distinguish a plot range from a matrix of data.

     See the help for `gnuplot' for a description of the syntax for the
     optional items.

     By default, the `gsplot' command plots each column of the
     expression as the z value, using the row index as the x value, and
     the column index as the y value.  The indices are counted from
     zero, not one.  For example,

          gsplot rand (5, 2)

     will plot a random surface, with the x and y values taken from the
     row and column indices of the matrix.

     If parametric plotting mode is set (using the command `set
     parametric', then `gsplot' takes the columns of the matrix three
     at a time as the x, y and z values that define a line in three
     space.  Any extra columns are ignored, and the x and y values are
     expected to be sorted.  For example, with `parametric' set, it
     makes sense to plot a matrix like

          1 1 3 2 1 6 3 1 9
          1 2 2 2 2 5 3 2 8
          1 3 1 2 3 4 3 3 7

     but not `rand (5, 30)'.

   The MATLAB-style three-dimensional plotting commands are:

 - Function File:  mesh (X, Y, Z)
     Plot a mesh given matrices `x', and Y from `meshdom' and a matrix
     Z corresponding to the X and Y coordinates of the mesh.

 - Function File:  meshdom (X, Y)
     Given vectors of X and Y coordinates, return two matrices
     corresponding to the X and Y coordinates of the mesh.

     See the file `sombrero.m' for an example of using `mesh' and
     `meshdom'.

 - Built-in Variable: gnuplot_binary
     The name of the program invoked by the plot command.  The default
     value is `"gnuplot"'.  *Note Installation::.

 - Built-in Variable: gnuplot_has_frames
     If the value of this variable is nonzero, Octave assumes that your
     copy of gnuplot has support for multiple frames that is included
     in recent 3.6beta releases.  It's initial value is determined by
     configure, but it can be changed in your startup script or at the
     command line in case configure got it wrong, or if you upgrade
     your gnuplot installation.

 - Built-in Variable: gnuplot_has_multiplot
     If the value of this variable is nonzero, Octave assumes that your
     copy of gnuplot has the multiplot support that is included in
     recent 3.6beta releases.  It's initial value is determined by
     configure, but it can be changed in your startup script or at the
     command line in case configure got it wrong, or if you upgrade
     your gnuplot installation.


File: octave,  Node: Miscellaneous Plotting Functions,  Prev: Three-Dimensional Plotting,  Up: Plotting

Miscellaneous Plotting Functions
================================

 - Function File:  bar (X, Y)
     Given two vectors of x-y data, `bar' produces a bar graph.

     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.

     If two output arguments are specified, the data are generated but
     not plotted.  For example,

          bar (x, y);

     and

          [xb, yb] = bar (x, y);
          plot (xb, yb);

     are equivalent.

 - Function File:  grid
     For two-dimensional plotting, force the display of a grid on the
     plot.

 - Function File:  stairs (X, Y)
     Given two vectors of x-y data, bar produces a `stairstep' plot.

     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.

     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.

 - Function File:  title (STRING)
     Specify a title for the plot.  If you already have a plot
     displayed, use the command `replot' to redisplay it with the new
     title.

 - Function File:  xlabel (STRING)
 - Function File:  ylabel (STRING)
     Specify x and y axis labels for the plot.  If you already have a
     plot displayed, use the command `replot' to redisplay it with the
     new labels.

 - Function File:  sombrero (N)
     Display a classic three-dimensional mesh plot.  The parameter N
     allows you to increase the resolution.

 - Function File:  clearplot
 - Function File:  clg
     Clear the plot window and any titles or axis labels.  The name
     `clg' is aliased to `clearplot' for compatibility with MATLAB.

     The commands `gplot clear', `gsplot clear', and `replot clear' are
     equivalent to `clearplot'.  (Previously, commands like `gplot
     clear' would evaluate `clear' as an ordinary expression and clear
     all the visible variables.)

 - Function File:  closeplot
     Close stream to the `gnuplot' subprocess.  If you are using X11,
     this will close the plot window.

 - Function File:  purge_tmp_files
     Delete the temporary files created by the plotting commands.

     Octave creates temporary data files for `gnuplot' and then sends
     commands to `gnuplot' through a pipe.  Octave will delete the
     temporary files on exit, but if you are doing a lot of plotting
     you may want to clean up in the middle of a session.

     A future version of Octave will eliminate the need to use temporary
     files to hold the plot data.

 - Function File:  axis (LIMITS)
     Sets the axis limits for plots.

     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.

     With no arguments, `axis' turns autoscaling on.

     If your plot is already drawn, then you need to use `replot' before
     the new axis limits will take effect.  You can get this to happen
     automatically by setting the built-in variable `automatic_replot'
     to a nonzero value.

 - Function File:  hist (Y, X)
     Produce histogram counts or plots.

     With one vector input argument, plot a histogram of the values with
     10 bins.  The range of the histogram bins is determined by the
     range of the data.

     Given a second scalar argument, use that as the number of bins.

     Given a second vector argument, use that as the centers of the
     bins, with the width of the bins determined from the adjacent
     values in the vector.

     Extreme values are lumped in the first and last bins.

     With two output arguments, produce the values NN and XX such that
     `bar (XX, NN)' will plot the histogram.


File: octave,  Node: Image Processing,  Next: Audio Processing,  Prev: Plotting,  Up: Top

Image Processing
****************

   To display images using these functions, you must be using Octave
with the X Window System, and you must have either `xloadimage' or `xv'
installed.  You do not need to be running X in order to manipulate
images, however, so some of these functions may be useful even if you
are not able to view the results.

 - Function File:  colormap
     Set the current colormap.

     `colormap (MAP)' sets the current colormap to MAP.  The color map
     should be an N row by 3 column matrix.  The columns contain red,
     green, and blue intensities respectively.  All entries should be
     between 0 and 1 inclusive.  The new colormap is returned.

     `colormap ("default")' restores the default colormap (a gray scale
     colormap with 64 entries).  The default colormap is returned.

     With no arguments, `colormap' returns the current color map.

 - Function File:  gray (N)
     Create a gray colormap with values from 0 to N.  The argument N
     should be a scalar.  If it is omitted, 64 is assumed.

 - Function File:  gray2ind
     Convert a gray scale intensity image to an Octave indexed image.

 - Function File:  image
     Display an Octave image matrix.

     `image (X)' displays a matrix as a color image.  The elements of X
     are indices into the current colormap and should have values
     between 1 and the length of the colormap.

     `image (X, ZOOM)' changes the zoom factor.  The default value is 4.

 - Function File:  imagesc
     Scale and display a matrix as an image.

     `imagesc (X)' displays a scaled version of the matrix X.  The
     matrix is scaled so that its entries are indices into the current
     colormap.  The scaled matrix is returned.

     `imagesc (X, ZOOM)' sets the magnification, the default value is 4.

 - Function File:  imshow
     Display images.

     `imshow (X)' displays an indexed image using the current colormap.

     `imshow (X, MAP)' displays an indexed image using the specified
     colormap.

     `imshow (I, N)' displays a gray scale intensity image.

     `imshow (R, G, B)' displays an RGB image.

 - Function File:  ind2gray
     Convert an Octave indexed image to a gray scale intensity image.

     `Y = ind2gray (X)' converts an indexed image to a gray scale
     intensity image.  The current colormap is used to determine the
     intensities.  The intensity values lie between 0 and 1 inclusive.

     `Y = ind2gray (X, MAP)' uses the specified colormap instead of the
     current one in the conversion process.

 - Function File:  ind2rgb
     Convert an indexed image to red, green, and blue color components.

     `[R, G, B] = ind2rgb (X)' uses the current colormap for the
     conversion.

     `[R, G, B] = ind2rgb (X, MAP)' uses the specified colormap.

 - Function File:  loadimage
     Load an image file.

     `[X, MAP] = loadimage (FILE)' loads an image and it's associated
     color map from the specified FILE.  The image must be stored in
     Octave's image format.

 - Function File:  ocean (N)
     Create color colormap.  The argument N should be a scalar.  If it
     is omitted, 64 is assumed.

 - Function File:  rgb2ind
     Convert and RGB image to an Octave indexed image.

     `[X, MAP] = rgb2ind (R, G, B)'

 - Function File:  saveimage
     Save a matrix to disk in image format.

     `saveimage (FILE, X)' saves matrix X to FILE in Octave's image
     format.  The current colormap is also saved in the file.

     `saveimage (FILE, X, "img")' saves the image in the default format
     and is the same as `saveimage (FILE, X)'.

     `saveimage (FILE, X, "ppm")' saves the image in ppm format instead
     of the default Octave image format.

     `saveimage (FILE, X, "ps")' saves the image in PostScript format
     instead of the default Octave image format.  (Note: images saved
     in PostScript format can not be read back into Octave with
     loadimage.)

     `saveimage (FILE, X, FMT, MAP)' saves the image along with the
     specified colormap in the specified format.

     Note: if the colormap contains only two entries and these entries
     are black and white, the bitmap ppm and PostScript formats are
     used.  If the image is a gray scale image (the entries within each
     row of the colormap are equal) the gray scale ppm and PostScript
     image formats are used, otherwise the full color formats are used.

 - Built-in Variable: IMAGEPATH
     A colon separated list of directories in which to search for image
     files.


File: octave,  Node: Audio Processing,  Next: Input and Output,  Prev: Image Processing,  Up: Top

Audio Processing
****************

   Octave provides a few functions for dealing with audio data.  An
audio `sample' is a single output value from an A/D converter, i.e., a
small integer number (usually 8 or 16 bits), and audio data is just a
series of such samples.  It can be characterized by three parameters:
the sampling rate (measured in samples per second or Hz, e.g. 8000 or
44100), the number of bits per sample (e.g. 8 or 16), and the number of
channels (1 for mono, 2 for stereo, etc.).

   There are many different formats for representing such data.
Currently, only the two most popular, *linear encoding* and *mu-law
encoding*, are supported by Octave.  There is an excellent FAQ on audio
formats by Guido van Rossum <guido@cwi.nl> which can be found at any
FAQ ftp site, in particular in the directory
`/pub/usenet/news.answers/audio-fmts' of the archive site
`rtfm.mit.edu'.

   Octave simply treats audio data as vectors of samples (non-mono data
are not supported yet).  It is assumed that audio files using linear
encoding have one of the extensions `lin' or `raw', and that files
holding data in mu-law encoding end in `au', `mu', or `snd'.

 - Function File:  lin2mu (X)
     If the vector X represents mono audio data in 8- or 16-bit linear
     encoding, `lin2mu (X)' is the correspoding mu-law encoding.

 - Function File:  mu2lin (X, BPS)
     If the vector X represents mono audio data in mu-law encoding,
     `mu2lin (X [, BPS])' converts it to linear encoding.  The optional
     argument BPS specifies whether the input data uses 8 bit per
     sample (default) or 16 bit.

 - Function File:  loadaudio (NAME, EXT, BPS)
     Loads audio data from the file `NAME.EXT' into the vector X.

     The extension EXT determines how the data in the audio file is
     interpreted;  the extensions `lin' (default) and `raw' correspond
     to linear, the extensions `au', `mu', or `snd' to mu-law encoding.

     The argument BPS can be either 8 (default) or 16, and specifies
     the number of bits per sample used in the audio file.

 - Function File:  saveaudio (NAME, X, EXT, BPS)
     Saves a vector X of audio data to the file `NAME.EXT'.  The
     optional parameters EXT and BPS determine the encoding and the
     number of bits per sample used in the audio file (see
     `loadaudio');  defaults are `lin' and 8, respectively.

   The following functions for audio I/O require special A/D hardware
and operating system support.  It is assumed that audio data in linear
encoding can be played and recorded by reading from and writing to
`/dev/dsp', and that similarly `/dev/audio' is used for mu-law
encoding.  This definitely works on Linux systems, and should also work
on Suns.  If your hardware is accessed differently, please contact
Andreas Weingessel <Andreas.Weingessel@ci.tuwien.ac.at>.

 - Function File:  playaudio (NAME, EXT)
 - Function File:  playaudio (X)
     Plays the audio file `NAME.EXT' or in the vector X.

 - Function File:  record (SEC, SAMPLING_RATE)
     Records SEC seconds of audio input into the vector X.  The default
     value for SAMPLING_RATE is 8000 samples per second, or 8kHz.  The
     program waits until the ENTER key is hit, and then immediately
     starts to record.

 - Function File:  setaudio (TYPE)
 - Function File:  setaudio (TYPE, VALUE)
     Set or display various properties of your mixer hardware.

     For example, if `vol' corresponds to the volume property, you can
     set it to 50 (percent) by `setaudio ("vol", 50)'.

     This is an simple experimental program to control the audio
     hardware settings.  It assumes that there is a `mixer' program
     which can be used as `mixer TYPE VALUE', and simply executes
     `system ("mixer TYPE VALUE")'.  Future releases might get rid of
     this assumption by using the `fcntl' interface.


File: octave,  Node: Input and Output,  Next: Special Matrices,  Prev: Audio Processing,  Up: Top

Input and Output
****************

   There are two distinct classes of input and output functions.  The
first set are modeled after the functions available in MATLAB.  The
second set are modeled after the standard I/O library used by the C
programming language.  The C-style I/O functions offer more flexibility
and control over the output, but are not quite as easy to use as the
simpler MATLAB-style I/O functions.

   When running interactively, Octave normally sends any output intended
for your terminal that is more than one screen long to a paging program,
such as `less' or `more'.  This avoids the problem of having a large
volume of output stream by before you can read it.  With `less' (and
some versions of `more') it also allows you to scan forward and
backward, and search for specific items.

   No output is displayed by the pager until just before Octave is
ready to print the top level prompt, or read from the standard input
(for example, by using the `fscanf' or `scanf' functions).  This means
that there may be some delay before any output appears on your screen
if you have asked Octave to perform a significant amount of work with a
single command statement.  The function `fflush' may be used to force
output to be sent to the pager immediately.  *Note C-Style I/O
Functions::.

   You can select the program to run as the pager by setting the
variable `PAGER', and you can turn paging off by setting the value of
the variable `page_screen_output' to 0.

 - Command: more
     Turn output pagination on or off.

 - Built-in Variable: PAGER
     The default value is `"less"', or, if `less' is not available on
     your system, `"more"'.  *Note Installation::.

 - Built-in Variable: page_screen_output
     If the value of `page_screen_output' is nonzero, all output
     intended for the screen that is longer than one page is sent
     through a pager.  This allows you to view one screenful at a time.
     Some pagers (such as `less'--see *Note Installation::) are also
     capable of moving backward on the output.  The default value is 1.

 - Built-in Variable: page_output_immediately
     If the value of `page_output_immediately' is nonzero, Octave sends
     output to the pager as soon as it is available.  Otherwise, Octave
     buffers its output and waits until just before the prompt is
     printed to flush it to the pager.  The default value is 0.

* Menu:

* Basic Input and Output::
* C-Style I/O Functions::


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

Basic Input and Output
======================

* Menu:

* Terminal Output::
* Terminal Input::
* Simple File I/O::


File: octave,  Node: Terminal Output,  Next: Terminal Input,  Prev: Basic Input and Output,  Up: Basic Input and Output

Terminal Output
---------------

   Since Octave normally prints the value of an expression as soon as it
has been evaluated, the simplest of all I/O functions is a simple
expression.  For example, the following expression will display the
value of pi

     octave:13> pi
     pi = 3.1416

   This works well as long as it is acceptable to have the name of the
variable (or `ans') printed along with the value.  To print the value
of a variable without printing its name, use the function `disp'.

   The `format' command offers some control over the way Octave prints
values with `disp' and through the normal echoing mechanism.

 - Built-in Function:  disp (X)
     Display the value of X.  For example, the following expression

          disp ("The value of pi is:"), disp (pi)

     will print

          The value of pi is:
          3.1416

     Note that the output from `disp' always ends with a newline.

 - Command: format OPTIONS
     Control the format of the output produced by `disp' and Octave's
     normal echoing mechanism.  Valid options are listed in the
     following table.

    `short'
          This is the default format.  Octave will try to print numbers
          with at least 5 significant figures within a field that is a
          maximum of 10 characters wide.

          If Octave is unable to format a matrix so that columns line
          up on the decimal point and all the numbers fit within the
          maximum field width, it switches to an `e' format.

    `long'
          Octave will try to print numbers with at least 15 significant
          figures within a field that is a maximum of 24 characters
          wide.

          As will the `short' format, Octave will switch to an `e'
          format if it is unable to format a matrix so that columns
          line up on the decimal point and all the numbers fit within
          the maximum field width.

    `long e'
    `short e'
          The same as `format long' or `format short' but always display
          output with an `e' format.  For example, with the `short e'
          format, pi is displayed as

                3.14e+00

    `long E'
    `short E'
          The same as `format long e' or `format short e' but always
          display output with an uppercase `E' format.  For example,
          with the `long E' format, pi is displayed as

                3.14159265358979E+00

    `free'
    `none'
          Print output in free format, without trying to line up
          columns of matrices on the decimal point.  This also causes
          complex numbers to be formatted like this `(0.604194,
          0.607088)' instead of like this `0.60419 + 0.60709i'.

    `bank'
          Print in a fixed format with two places to the right of the
          decimal point.

    `+'
          Print a `+' symbol for nonzero matrix elements and a space
          for zero matrix elements.  This format can be very useful for
          examining the structure of a large matrix.

    `hex'
          Print the hexadecimal representation numbers as they are
          stored in memory.  For example, on a workstation which stores
          8 byte real values in IEEE format with the least significant
          byte first, the value of `pi' when printed in `hex' format is
          `400921fb54442d18'.  This format only works for numeric
          values.

    `bit'
          Print the bit representation of numbers as stored in memory.
          For example, the value of `pi' is

               01000000000010010010000111111011
               01010100010001000010110100011000

          (shown here in two 32 bit sections for typesetting purposes)
          when printed in bit format on a workstation which stores 8
          byte real values in IEEE format with the least significant
          byte first.  This format only works for numeric types.


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

Terminal Input
--------------

 - Built-in Function:  input (PROMPT)
 - Built-in Function:  input (PROMPT, "s")
     Print a prompt and wait for user input.  For example,

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

     prints the prompt

          Pick a number, any number!

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

     Currently, `input' only returns one value, regardless of the number
     of values produced by the evaluation of the expression.

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

     Because there may be output waiting to be displayed by the pager,
     it is a good idea to always call `fflush (stdout)' before calling
     `input'.  This will ensure that all pending output is written to
     the screen before your prompt.  *Note C-Style I/O Functions::.

 - Built-in Function:  keyboard (PROMPT)
     This function is normally used for simple debugging.  When the
     `keyboard' function is executed, Octave prints a prompt and waits
     for user input.  The input strings are then evaluated and the
     results are printed.  This makes it possible to examine the values
     of variables within a function, and to assign new values to
     variables.  No value is returned from the `keyboard' function, and
     it continues to prompt for input until the user types `quit', or
     `exit'.

     If `keyboard' is invoked without any arguments, a default prompt of
     `debug> ' is used.

   For both `input' and `keyboard', the normal command line history and
editing functions are available at the prompt.


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

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

   The `save' and `load' commands allow data to be written to and read
from disk files in various formats.

 - Command: save OPTIONS FILE V1 V2 ...
     Save the named variables V1, V2, ... in the file FILE.  The
     special filename `-' can be used to write the output to your
     terminal.  If no variable names are listed, Octave saves all the
     variables in the current scope.  Valid options for the `save'
     command are listed in the following table.

    `-ascii'
          Save the data in Octave's text data format.  Using this flag
          overrides the value of the built-in variable
          `default_save_format'.

    `-binary'
          Save the data in Octave's binary data format.  Using this
          flag overrides the value of the built-in variable
          `default_save_format'.

    `-float-binary'
          Save the data in Octave's binary data format but only using
          single precision.  Using this flag overrides the value of the
          built-in variable `default_save_format'.  You should use this
          format only if you know that all the values to be saved can
          be represented in single precision.

    `-mat-binary'
          Save the data in MATLAB's binary data format.  Using this
          flag overrides the value of the built-in variable
          `default_save_format'.

    `-save-builtins'
          Force Octave to save the values of built-in variables too.
          By default, Octave does not save built-in variables.

     The list of variables to save may include wildcard patterns
     containing the following special characters:
    `?'
          Match any single character.

    `*'
          Match zero or more characters.

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

     Saving global variables also saves the global status of the
     variable, so that if it is restored at a later time using `load',
     it will be restored as a global variable.

     The command

          save -binary data a b*

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

   There are two variables that modify the behavior of `save'.

 - Built-in Variable: default_save_format
     This variable specifies the default format for the `save' command.
     It should have one of the following values: `"ascii"', `"binary"',
     `float-binary', or `"mat-binary"'.  The initial default save
     format is Octave's text format.

 - Built-in Variable: save_precision
     This variable specifies the number of digits to keep when saving
     data in text format.  The default value is 17.

 - Command: load OPTIONS FILE V1 V2 ...
     To restore the values from a file, use the `load' command.  As with
     `save', you may specify a list of variables and `load' will only
     extract those variables with names that match.  For example, to
     restore the variables saved in the file `data', use the command

          load data

     Octave will refuse to overwrite existing variables unless you use
     the option `-force'.

     If a variable that is not marked as global is loaded from a file
     when a global symbol with the same name already exists, it is
     loaded in the global symbol table.  Also, if a variable is marked
     as global in a file and a local symbol exists, the local symbol is
     moved to the global symbol table and given the value from the
     file.  Since it seems that both of these cases are likely to be
     the result of some sort of error, they will generate warnings.

     The `load' command can read data stored in Octave's text and
     binary formats, and MATLAB's binary format.  It will automatically
     detect the type of file and do conversion from different floating
     point formats (currently only IEEE big and little endian, though
     other formats may added in the future).

     Valid options for `load' are listed in the following table.

    `-force'
          Force variables currently in memory to be overwritten by
          variables with the same name found in the file.

    `-ascii'
          Force Octave to assume the file is in Octave's text format.

    `-binary'
          Force Octave to assume the file is in Octave's binary format.

    `-mat-binary'
          Force Octave to assume the file is in MATLAB's binary format.

