[manual] suggested addition to pcolor description

[Ben Abbott]

On Sep 20, 2008, at 12:07 PM, Francesco Potorti` wrote:

>> Regarding the interpolation of the color values across the mesh, this
>> is controlled by the "shading" command.
>
> By the way, I do not understand what shading() does.  As far as I
> understood by experimenting, "flat" removes the black lines between  
> mesh
> elements, and "faceted" does the opposite.  I did not understand what
> "interp" does.  These are purely aesthetic effects, and have nothing  
> to
> do with the choice of the color to use.

Try

	figure(1)
	pcolor(peaks)
	shading flat

	figure(2)
	pcolor(peaks)
	shading faceted

	figure(3)
	pcolor(peaks)
	shading interp

The difference between 1 and 2 is clear. For faceted the mesh lines  
are drawn. For "flat" only the face color of the patches is seen.

Using octave/gnuplot, I don't think there is a difference between (2)  
and (3).

However, in Matlab there clearly is (as the color interpolates across  
each patch). Each rectangle of the mesh is interpreted as a pair of  
triangles and the color is linearly interpolated across it. The  
triangles are visible in the attached pdf.

A simpler example is

	[x,y] = meshgrid (0:1, 0:1);
	c = x.^2 + y.^2;
	pcolor (x, y, c)
	shading interp
	colormap (jet)

Unfortunately, in Octave/gnuplot and usign the result is a single  
"Tahoe Blue" patch. I've attached the result from Matlab using the

> So either I did not manage to guess what shading() does, or it has
> nothing to do with the choice of color, or some mix in between :)
>
>> Perhaps what should be mentioned is that "C" is interpreted by the
>> current color map and that "shading" controls whether the mesh is
>> flat, faceted, or interpolated.
>
> Yes, but what is essential, and is not mentioned, is that if C is 3x3,
> pcolor draws a picture with 4 (2x2) rectangles, because the 3x3 values
> of C are intended to be at the mesh vertices.  This is not documented
> anywhere.  On the other hand, imagesc, which does a very similar job,
> draws instead a picture with 9 (3x3) rectangles, because the values of
> its argument are intended to be in the middle of the mesh rectangles
> (not at the vertices).  In my opinion, it is well worth noting the
> similarities and differences between the two in the manual; I only
> discovered them after quite some time doing experiments.

I was unware of those features. Can you post a simple example? Perhaps  
you can modify the one I provided above?

>> On another note, I am pleased to see the interest of you and others
>> are taking to improve Octave's documentation. I'd encourage you to
>> install mercurial and pull the sources from jwe's repository. Even if
>> you aren't interested in building Octave from its sources, having the
>> repository local permits you to create and submit changesets  
>> directly.
>
> The fact is, I have just switched to 3.0 and at the same time have  
> just
> started to fiddle with multidim arrays and 2d plotting, so I am  
> doing a
> lot of experimenting and manual reading just now, but the rate of my  
> bug
> reports is going to reduce soon, I suspect, because I have read most  
> of
> the new topics by now.  Anyway, I'll consider mercurial if I manage to
> find the time, thanks for your suggestion.
>
>> In any event, what of the change below?
> ...
>>     The values of C are linearly mapped to the mesh using the current
>>     colormap. The method of  interpolation of the colors across the
>>     mesh is determined by the state of shading.
>
> This language is obscure to me.  Does "linearly mapped" refer to how  
> the
> values are geometrically arranged in the plot or how they are mapped  
> to
> colors?  In any case, the type of mapping is not explained.  Same for
> the "method of interpolation", because the doc for shading does not
> explain what is the meaning of its argument.

Respecting "shading interp",; for each rectangle is divided into a  
pair of triangles and the color is linearly interpolated across the  
patch. Take a look at the attached example.

The value for the color is mapped linear across the UL or LR triangles.

The result is mapped to a color by the active colormap. The colormap  
is not linearly interpolated. Instead, the nearest value is used.

You may also want to look at "caxis", which determines how the the  
values for "c" map to the colormap.

Ben

-------------- next part --------------
A non-text attachment was scrubbed...
Name: interp.pdf
Type: application/pdf
Size: 4386 bytes
Desc: not available
Url : https://www-old.cae.wisc.edu/pipermail/bug-octave/attachments/20080920/4ce272c2/attachment.pdf 
-------------- next part --------------