1######################################################################## 2## 3## Copyright (C) 2007-2021 The Octave Project Developers 4## 5## See the file COPYRIGHT.md in the top-level directory of this 6## distribution or <https://octave.org/copyright/>. 7## 8## This file is part of Octave. 9## 10## Octave is free software: you can redistribute it and/or modify it 11## under the terms of the GNU General Public License as published by 12## the Free Software Foundation, either version 3 of the License, or 13## (at your option) any later version. 14## 15## Octave is distributed in the hope that it will be useful, but 16## WITHOUT ANY WARRANTY; without even the implied warranty of 17## MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 18## GNU General Public License for more details. 19## 20## You should have received a copy of the GNU General Public License 21## along with Octave; see the file COPYING. If not, see 22## <https://www.gnu.org/licenses/>. 23## 24######################################################################## 25 26## -*- texinfo -*- 27## @deftypefn {} {} pcolor (@var{x}, @var{y}, @var{c}) 28## @deftypefnx {} {} pcolor (@var{c}) 29## @deftypefnx {} {} pcolor (@var{hax}, @dots{}) 30## @deftypefnx {} {@var{h} =} pcolor (@dots{}) 31## Produce a 2-D density plot. 32## 33## A @code{pcolor} plot draws rectangles with colors from the matrix @var{c} 34## over the two-dimensional region represented by the matrices @var{x} and 35## @var{y}. @var{x} and @var{y} are the coordinates of the mesh's vertices 36## and are typically the output of @code{meshgrid}. If @var{x} and @var{y} are 37## vectors, then a typical vertex is (@var{x}(j), @var{y}(i), @var{c}(i,j)). 38## Thus, columns of @var{c} correspond to different @var{x} values and rows 39## of @var{c} correspond to different @var{y} values. 40## 41## The values in @var{c} are scaled to span the range of the current 42## colormap. Limits may be placed on the color axis by the command 43## @code{caxis}, or by setting the @code{clim} property of the parent axis. 44## 45## The face color of each cell of the mesh is determined by interpolating 46## the values of @var{c} for each of the cell's vertices; Contrast this with 47## @code{imagesc} which renders one cell for each element of @var{c}. 48## 49## @code{shading} modifies an attribute determining the manner by which the 50## face color of each cell is interpolated from the values of @var{c}, 51## and the visibility of the cells' edges. By default the attribute is 52## @qcode{"faceted"}, which renders a single color for each cell's face with 53## the edge visible. 54## 55## If the first argument @var{hax} is an axes handle, then plot into this axes, 56## rather than the current axes returned by @code{gca}. 57## 58## The optional return value @var{h} is a graphics handle to the created 59## surface object. 60## 61## @seealso{caxis, shading, meshgrid, contour, imagesc} 62## @end deftypefn 63 64function h = pcolor (varargin) 65 66 [hax, varargin, nargin] = __plt_get_axis_arg__ ("pcolor", varargin{:}); 67 68 if (nargin == 1) 69 c = varargin{1}; 70 [nr, nc] = size (c); 71 x = 1:nc; 72 y = 1:nr; 73 z = zeros (nr, nc); 74 elseif (nargin == 3) 75 x = varargin{1}; 76 y = varargin{2}; 77 c = varargin{3}; 78 z = zeros (size (c)); 79 else 80 print_usage (); 81 endif 82 83 oldfig = []; 84 if (! isempty (hax)) 85 oldfig = get (0, "currentfigure"); 86 endif 87 unwind_protect 88 hax = newplot (hax); 89 htmp = surface (x, y, z, c); 90 91 set (htmp, "facecolor", "flat"); 92 if (! ishold ()) 93 set (hax, "view", [0, 90], "box", "on"); 94 ## FIXME: Maybe this should be in the general axis limit setting routine? 95 ## When values are integers (such as from meshgrid), we want to 96 ## use tight limits for pcolor, mesh, surf, etc. Situation is 97 ## complicated immensely by vector or matrix input and meshgrid() 98 ## or ndgrid() format. 99 meshgrid_fmt = true; 100 if (isvector (x)) 101 xrng = x(isfinite (x)); 102 else 103 xrng = x(1, isfinite (x(1,:))); # meshgrid format (default) 104 if (all (xrng == xrng(1))) 105 xrng = x(isfinite (x(:,1)), 1); # ndgrid format 106 meshgrid_fmt = false; 107 endif 108 endif 109 if (isvector (y)) 110 yrng = y(isfinite (y)); 111 else 112 if (meshgrid_fmt) 113 yrng = y(isfinite (y(:,1)), 1); 114 else 115 yrng = y(1, isfinite (y(1,:))); 116 endif 117 endif 118 if (all (xrng == fix (xrng))) 119 xmin = min (xrng); 120 xmax = max (xrng); 121 if (xmin < xmax) 122 xlim ([xmin, xmax]); 123 endif 124 endif 125 if (all (yrng == fix (yrng))) 126 ymin = min (yrng); 127 ymax = max (yrng); 128 if (ymin < ymax) 129 ylim ([ymin, ymax]); 130 endif 131 endif 132 endif 133 134 unwind_protect_cleanup 135 if (! isempty (oldfig)) 136 set (0, "currentfigure", oldfig); 137 endif 138 end_unwind_protect 139 140 if (nargout > 0) 141 h = htmp; 142 endif 143 144endfunction 145 146 147%!demo 148%! clf; 149%! colormap ("default"); 150%! Z = peaks (); 151%! pcolor (Z); 152%! title ("pcolor() of peaks with facet shading"); 153 154%!demo 155%! clf; 156%! colormap ("default"); 157%! [X,Y,Z] = sombrero (); 158%! [Fx,Fy] = gradient (Z); 159%! pcolor (X,Y,Fx+Fy); 160%! shading interp; 161%! axis tight; 162%! title ("pcolor() of peaks with interp shading"); 163