1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
|
%#
%# fields is a package for analysis of spatial data written for
%# the R software environment.
%# Copyright (C) 2024 Colorado School of Mines
%# 1500 Illinois St., Golden, CO 80401
%# Contact: Douglas Nychka, douglasnychka@gmail.edu,
%#
%# 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
%##END HEADER
\name{poly.image}
\alias{poly.image}
\alias{poly.image.regrid}
\title{Image plot for cells that are irregular quadrilaterals.}
\description{
Creates an image using polygon filling based on a grid of irregular
quadrilaterals. This function is useful for a regular grid that has
been transformed to another nonlinear or rotated coordinate system. This
situation comes up in lon-lat grids created under different map projections.
Unlike the usual image format this function requires the grid to be
specified as two matrices x and y that given the grid x and y coordinates
explicitly for every grid point.
}
\usage{
poly.image(x, y, z, col = tim.colors(64), breaks,
transparent.color = "white", midpoint = FALSE, zlim =
range(z, na.rm = TRUE), xlim = range(x), ylim =
range(y), add = FALSE, border = NA, lwd.poly = 1, asp
= NA, ...)
poly.image.regrid(x)
}
%- maybe also 'usage' for other objects documented here.
\arguments{
\item{x}{A matrix of the x locations of the grid. }
\item{y}{A matrix of the y locations of the grid. }
\item{z}{Values for each grid cell. Can either be the value at the
grid points or interpreted as the midpoint of the grid cell. }
\item{col}{ Color scale for plotting. }
\item{breaks}{Numerical breaks to match to the colors. If missing breaks are
equally spaced on the range \code{zlim}.}
\item{transparent.color}{ Color to plot cells that are outside the
range specified in the function call. }
\item{midpoint}{
Only relevant if the dimensions of x,y, and z are the same. If TRUE
the z values will be averaged and then used as the cell midpoints. If
FALSE the x/y grid will be expanded and shifted to represent grid cells
corners. (See poly.image.regrid.) }
\item{zlim}{ Plotting limits for z. }
\item{xlim}{Plotting limits for x. }
\item{ylim}{Plotting limits for y.}
\item{add}{ If TRUE will add image onto current plot. }
\item{border}{Color of the edges of the quadrilaterals, the default is
no color.}
\item{lwd.poly}{Line width for the mesh surface. i.e. the outlines of the
quadrilateral facets. This might have to be set smaller than one if rounded
corners on the facets are visible. }
\item{asp}{The plot aspect with similar function to that in the \code{plot}
function. }
\item{\dots}{ If add is FALSE, additional graphical arguments that
will be supplied to the plot function. }
}
\details{
This function is straightforward except in the case when the dimensions
of x,y, and z are equal. In this case the relationship of the values to
the grid cells is ambigious and the switch midpoint gives two possible
solutions. The z values at 4 neighboring grid cells can be averaged to
estimate a new value interpreted to be at the center of the grid. This
is done when midpoint is TRUE. Alternatively the full set of z values
can be retained by redefining the grid. This is accomplisehd by finding
the midpoints of x and y grid points and adding two outside rows and
cols to complete the grid. The new result is a new grid that is is
(M+1)X (N+1) if z is MXN. These new grid points define cells that
contain each of the original grid points as their midpoints. Of course
the advantage of this alternative is that the values of z are preserved
in the image plot; a feature that may be important for some uses.
The function image.plot uses this function internally when image
information is passed in this format and can add a legend. In most cases
just use image.plot.
The function \code{poly.image.regrid} does a simple averaging and
extrapolation of the grid locations to shift from midpoints to
corners. In the interior grid corners are found by the average of the
4 closest midpoints. For the edges the corners are just extrapolated
based on the separation of nieghboring grid cells.
}
\author{Doug Nychka }
\seealso{image.plot}
\examples{
data(RCMexample)
set.panel( 1,2)
par(pty="s")
# plot with grid modified
poly.image( RCMexample$x, RCMexample$y, RCMexample$z[,,1])
# use midpoints of z
poly.image( RCMexample$x, RCMexample$y, RCMexample$z[,,1],midpoint=TRUE)
set.panel()
# an example with quantile breaks
brk<- quantile( RCMexample$z[,,1], c( 0, .9,.95,.99,1.0) )
poly.image( RCMexample$x, RCMexample$y, RCMexample$z[,,1], breaks=brk, col=
rainbow(4))
# images are very similar.
set.panel()
# Regridding of x and y
l1<- poly.image.regrid( RCMexample$x)
l2<- poly.image.regrid( RCMexample$y)
# test that this works
i<- 1:10
plot( l1[i,i], l2[i,i])
points( RCMexample$x[i,i], RCMexample$y[i,i],col="red")
}
% Add one or more standard keywords, see file 'KEYWORDS' in the
% R documentation directory.
\keyword{spatial}
|
