8.4.1 Surface coloring

A surface is colored at draw time by passing a function to the vertexPen parameter of draw(surface,...). The function is called once for each patch corner and returns the pen to be used there. Its type, also called vertexPen, is defined in the palette module as an abbreviation for a function type:

using vertexPen=pen(surfaceVertex);

The structure surfaceVertex provides the following information about the patch corner:

struct surfaceVertex {
  triple z;      // vertex position in user coordinates
  pair uv;       // parametric coordinates (structured surfaces only)
  int patch;     // index of patch (see below)
  int corner;    // index of corner in patch (0-3 or 0-2)
  int U, V;      // mesh cell of patch (structured surfaces only)
}

The fields uv, U, and V are meaningful only for structured surfaces (see Surface parametrization); for unstructured surfaces (such as unitsphere) they are zero. A simple pen function of a single triple argument is automatically converted to a vertexPen, so the following are equivalent:

draw(s, vertexPen=new pen(triple v) {return hsv(360*zpart(v),1,1);});
draw(s, vertexPen=new pen(surfaceVertex sv) {
  return hsv(360*zpart(sv.z),1,1);
});

Color is thus a property of how a surface is drawn, rather than of the surface itself: drawing does not modify the surface, and the same surface can be drawn again with a different vertexPen. The vertex colors replace the color of surfacepen3: if surfacepen is red, the surface is no longer red. They also replace any colors stored in the surface when it was constructed. Other attributes of a material, such as its shininess, still apply. When the colors convey data, it is often preferable to show them exactly as specified, by turning the lighting off:

draw(s,s.palette(zpart,Rainbow()),nolight);

The convenience function cornerPen (defined in three_surface.asy) constructs a vertexPen that assigns a pen to each corner of each patch, using sv.patch and sv.corner for indexing:

vertexPen cornerPen(...pen[] p);
vertexPen cornerPen(pen[][] p);

The first form applies the same list of pens to every patch; it must supply a pen for every corner (four for a Bezier patch, three for a Bezier triangle). In the second form, corner j of patch i is drawn with pen j of the row p[i % p.length]. If that row is a cyclic array, j is likewise reduced modulo the length of the row; otherwise, it is an error for a patch to have more corners than the row has pens:

draw(s,cornerPen(red,green,blue,black));   // four pens per patch

pen[] p={red,blue};
p.cyclic=true;
draw(s,cornerPen(new pen[][] {p}));        // red,blue,red,blue

Corner j of a patch is node j of the boundary path of the patch, as returned by the patch method external(). For a surface constructed from a single cyclic path of length at most 4, this is node j of that path. The array p is copied, so subsequent changes to it do not affect the surface colors.

For a structured surface, sv.uv holds the parametric coordinates of the vertex, with the domain described in Surface parametrization. Since these vary continuously from one patch to the next, a pen that depends on sv.uv colors the surface smoothly:

draw(s, vertexPen=new pen(surfaceVertex sv) {
  return hsv(360*sv.uv.x/(2pi), 1, 1);
});

Both limits of the domain occur as values of sv.uv, even in a direction in which the surface is cyclic.

The integer fields sv.U and sv.V identify the mesh cell containing the patch, with 0 <= sv.U < nu and 0 <= sv.V < nv. All corners of a patch are assigned the same cell, so a pen that depends only on sv.U and sv.V gives each patch a single flat color:

pen checkerboard(surfaceVertex sv) {
  return (sv.U+sv.V) % 2 == 0 ? white : black;
}
draw(s, checkerboard);

The field sv.patch is the position of the patch in the array s.s of patches that make up the surface s. It is available for every surface, but the order of this array is an internal detail of how the surface was constructed, which most users need not be aware of. Coloring by sv.patch (including cornerPen with a different row of pens for each patch) should therefore be a last resort, appropriate mainly for a surface that was assembled patch by patch, so that the order is known. Wherever possible, use the position sv.z, the parametric coordinates sv.uv, or the mesh cell sv.U, sv.V instead.

The function palette (in the palette module) constructs a vertexPen that colors each vertex according to the value of a function f there:

vertexPen palette(real f(triple), real Min, real Max, pen[] palette);

The value Min is mapped to the first pen of the palette, Max to the last, and the values in between to the pens in between. For example, to color a surface by height:4

real height(triple v) {return v.z;}
draw(s,palette(height,0,1,Gradient(blue,red)));

Here a vertex at height 0 is blue, a vertex at height 1 is red, and a vertex at height 0.5 is halfway between the two. The value of f at every vertex must lie between Min and Max.

When the range of f is not known in advance, the surface method palette finds it, using the least and greatest values of f at the vertices of the surface:

draw(s,s.palette(height,Gradient(blue,red)));

Now the lowest vertex of s is blue and the highest is red. The resulting vertexPen should be used to draw that same surface. Here is a complete example, drawn with nolight so that the colors appear exactly as specified:

import graph3;
import palette;

size(200,0);

currentprojection=perspective(10,8,4);

real f(pair z) {return 0.5+exp(-abs(z)^2);}

real height(triple v) {return v.z;}

surface s=surface(f,(-1,-1),(1,1),nx=5,Spline);

draw(s,s.palette(height,Gradient(blue,red)),meshpen=black+thick(),nolight);

xaxis3(Label("$x$"),red,Arrow3);
yaxis3(Label("$y$"),red,Arrow3);
zaxis3(XYZero(extend=true),red,Arrow3);

./colorsurface

The function fitColors (also in the palette module) constructs a vertexPen from the colors at a few points, such as the corners of a square or a box, blending smoothly between them; the pen colors[i] is the color at the point coords[i]:

vertexPen fitColors(triple[] coords, pen[] colors);

Each color component of the resulting vertexPen is a cubic polynomial in the position, chosen by least squares to fit the given colors, with a preference for polynomials of low degree. The fit works equally well whether or not the square or box is aligned with the coordinate axes. Since such a polynomial has only twenty coefficients, the given colors are closely approximated only when there are few of them; fitColors cannot produce an intricate pattern from a large number of points. If any of the pens is not opaque, the opacity is fit in the same way, using the blend mode of the first pen; otherwise the surface is opaque. If the pens are in different colorspaces, they are converted to that of the first pen colors[0].

Surface coloring is illustrated in the examples smoothelevation.asy and sphericalharmonic.asy (coloring by height or radius with surface.palette), vertexshading.asy (cornerPen), interlockedtori.asy and mobiustorus.asy (coloring by parametric coordinates and by mesh cell), and fitcolors.asy (fitColors).


Footnotes

(3)

Strictly, its diffuse color: a pen used as a surfacepen becomes the diffuse pen of a material (see material).

(4)

The built-in function zpart does the same as height, so it can be passed to palette directly, with nothing to define.