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);
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).
Strictly, its diffuse color: a pen used as a
surfacepen becomes the diffuse pen of a material
(see material).
The built-in function zpart does the same as
height, so it can be passed to palette directly, with
nothing to define.