%# fields  is a package for analysis of spatial data written for
%# the R software environment .
%# Copyright (C) 2018
%# University Corporation for Atmospheric Research (UCAR)
%# Contact: Douglas Nychka, nychka@mines.edu,
%# National Center for Atmospheric Research, PO Box 3000, Boulder, CO 80307-3000
%#
%# This program is free software; you can redistribute it and/or modify
%# it under the terms of the GNU General Public License as published by
%# the Free Software Foundation; either version 2 of the License, or
%# (at your option) any later version.
%# This program is distributed in the hope that it will be useful,
%# but WITHOUT ANY WARRANTY; without even the implied warranty of
%# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
%# GNU General Public License for more details.
%#
%# You should have received a copy of the GNU General Public License
%# along with the R software environment if not, write to the Free Software
%# Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
%# or see http://www.r-project.org/Licenses/GPL-2    

\name{as.surface}
\alias{as.surface}
\title{
  Creates an "surface" object from grid values. 
}
\description{
Reformats the vector from evaluating  a function on a grid of points into 
a list for use with surface plotting function. The list has the
usual components x,y and z and is suitable for use with persp, contour,
image and image.plot.
 
}
\usage{
as.surface(obj, z, location=NULL, order.variables="xy")
}
\arguments{
\item{obj}{
A description of the grid used to evaluate the function. This can 
either be in the form of a grid.list 
( see help file for grid.list) or the matrix of grid of points produced 
by make.surface.grid. In the later case obj is a matrix with 
the grid.list as an attribute. 
}
\item{z}{
The value of the function evaluated at the gridded points. 
}
\item{location}{A logical or two column matrix of indices indicating 
                 the location of the z values within the image matrix.}
\item{order.variables}{
Either "xy" or "yx" specifies how the x and y variables used to 
evaluate the function are matched with the x and y grids in the surface 
object. 
}
}
\value{
A list of class surface. This object is a modest generalization of the 
list input format (x,y,z,) for the S functions contour, image or persp.  

\item{x}{
The grid values in the  X-axis
}
\item{y}{
The grid values in the  Y-axis
}
\item{z}{
A matrix of dimensions nrow= length of x and ncol= length of y with
entries being the  grid point value reformatted from z. 
}
}
\details{
This function was written to simply to go back and forth between a
matrix of gridded values and the stacked vector obtained by stacking
columns. The main application is evaluating a function at each grid point
and then reforming the results for plotting. (See example below.)

If zimage is matrix of values then the input vector is c( zimage).
To go from the stacked vector to the matrix one needs the the nrow ncol
and explains why grid information must also be specified.
 
Note that the z input argument must be in the order 
values in order of stacking columns of the image. This is also the
order of the grid points generated by make.surface.grid.

To convert irregular 2-d data to a surface object where there are missing
cells see the function as.image. 
}
\seealso{
 grid.list, make.surface.grid, surface, contour,
image.plot, as.image 
}
\examples{
 

# Make a perspective of the surface Z= X**2 -Y**2 
# Do this by evaluating quadratic function on a 25 X 25 grid
  
grid.l<-list( abcissa= seq( -2,2,,15), ordinate= seq( -2,2,,20)) 
xg<-make.surface.grid( grid.l)
# xg is a 300X2 matrix that has all pairs of X and Y grid values 
z<- xg[,1]**2 - xg[,2]**2  
# now fold z in the matrix format needed for persp 
out.p<-as.surface( xg, z) 
persp( out.p) 
# also try  plot( out.p) to see the default plot for a surface object 
}
\keyword{manip}
% docclass is function
% Converted by Sd2Rd version 1.21.