Surface

Back to documentation index.

new Surface(surface)

A surface evaluator object for a parametric surface.

A parametric surface is a surface whose points are based on a parametric surface function. A surface function takes two numbers (U and V) and returns a point (in 1, 2, 3 or more dimensions, but usually 2 or 3) that lies on the surface. For example, in 3 dimensions, a surface function has the following form:

F(u, v) = [ x(u, v), y(u, v), z(u, v) ]

where x(u, v) returns an x-coordinate, y(u, v) a y-coordinate, and z(u, v) returns a z-coordinate.

Classes or JavaScript objects defining parametric surfaces should implement the evaluate method and, optionally, the other methods mentioned in the “surface” parameter below.

A note on trimming regions

A trimming region is a set of (u, v) points where a surface will be evaluated (“drawn”). Normally, the surface is “drawn” in the entire area where the surface is defined, for example, the rectangular area in (u, v) space where 0≤u≤1 and 0≤v≤1. But with a trimming region, the surface is “drawn” only where the u- and v-coordinates are inside that region.

The OpenGL Utility Library (GLU), as well as IRIS GL, implements a trimming region as a set of closed loops that don’t intersect themselves or each other. Each loop is made of one or more 2-D B-spline curves, rational or not. The orientation of each loop determines whether it helps set the inside of the trimming region or whether it “punches a hole” out of that region. (In GLU and IRIS GL, loops of the former kind run counterclockwise and others clockwise, assuming the positive u-axis runs to the right and the positive v-axis up.)

One way to approximate a surface using a trimming region is to “flatten” the curves on the region (approximate them with line segments), then break the resulting shape into triangles, then evaluate (“draw”) the surface within each triangle. This library currently does not have explicit support for trimming regions.

Parameters

Methods

Surface#bitangent(u, v)

Finds an approximate bitangent vector of this surface at the specified u- and v-coordinates.

The implementation in Surface calls the evaluator’s bitangent method if it implements it; otherwise, does a numerical differentiation with respect to the v-axis using the evaluate method.

The bitangent vector is the vector pointing in the direction of the v-axis, or alternatively, the partial derivative of the evaluate method with respect to v. The bitangent vector returned by this method should not be “normalized” to a unit vector.

Parameters

Return Value

An array describing a bitangent vector. It should have at least as many elements as the number of dimensions of the underlying surface. (Type: Array.<number>)

Examples

<caption> The following code is a very simple surface evaluator object.
var evaluator = new Surface({
"evaluate":function(u, v) {
// Take the U parameter as the x-coordinate,
// the V parameter as the y-coordinate, and 0 as
// the z-coordinate.
return [u, v, 0];
}
});

Surface#endPoints()

Returns the starting and ending u- and v-coordinates of this surface. This method calls the evaluator’s endPoints method if it implements it; otherwise, returns [0, 1, 0, 1]

Return Value

A four-element array. The first and second elements are the starting and ending u-coordinates, respectively, of the surface, and the third and fourth elements are its starting and ending v-coordinates. Returns [0, 1, 0, 1] if the evaluator doesn’t implement an endPoints method.

Surface#evaluate(u, v)

Finds the position of this surface at the specified u- and v-coordinates.

Parameters

Return Value

An array describing a position. It should have at least as many elements as the number of dimensions of the underlying surface. (Type: Array.<number>)

Surface#gradient(u, v)

Finds an approximate gradient vector of this surface at the specified u- and v-coordinates.

The implementation in Surface calls the evaluator’s gradient method if it implements it; otherwise uses the surface’s tangent and bitangent vectors to implement the gradient (however, this approach is generally only meaningful for a surface in three-dimensional space).

The gradient is a vector pointing up and away from the surface. If the evaluator describes a regular three-dimensional surface (usually a continuous, unbroken surface such as a sphere, an open cylinder, or a disk rotated in three dimensions), this can be the cross product of the tangent vector and bitangent vector, in that order. The gradient returned by this method should not be “normalized” to a unit vector.

Parameters

Return Value

An array describing a gradient vector. It should have at least as many elements as the number of dimensions of the underlying surface. (Type: Array.<number>)

Examples

The following example is a surface evaluator object for a parametric surface with a gradient method. To illustrate how the gradient method is derived from the vector calculation method, that method is also given later. To derive the normal calculation, first look at the vector function:

F(u, v) = (cos(u), sin(u), sin(u)*cos(v))

Then, find the partial derivatives with respect to u and to v:

∂F/∂u = (-sin(u), cos(u), cos(u)*cos(v))
∂F/∂v = (0, 0, -sin(v)*sin(u))

Next, take their cross product:

&Del;F(u, v) = (-sin(v)*cos(u)*sin(u), -sin(v)*sin(u)*sin(u), 0)

The result is the gradient, which will point up and away from the surface.

var surface=new Surface({"evaluate":function(u,v) {
"use strict";
return [Math.cos(u),Math.sin(u),Math.sin(u)*Math.cos(v)];
},
"gradient":function(u,v) {
"use strict";
return [
Math.cos(u)*-Math.sin(v)*Math.sin(u),
Math.sin(u)*-Math.sin(v)*Math.sin(u),
0];
}})

Surface#normal(u, v)

Convenience method for finding an approximate normal vector of this surface at the specified u- and v-coordinates. The normal vector is the same as the gradient vector, but “normalized” to a unit vector.

Parameters

Return Value

An array describing a normal vector. It should have at least as many elements as the number of dimensions of the underlying surface. (Type: Array.<number>)

Surface#tangent(u, v)

Finds an approximate tangent vector of this surface at the specified u- and v-coordinates. The implementation in Surface calls the evaluator’s tangent method if it implements it; otherwise, does a numerical differentiation with respect to the u-axis using the evaluate method.

The tangent vector is the vector pointing in the direction of the u-axis, or alternatively, the partial derivative of the evaluate method with respect to u. The tangent vector returned by this method should not be “normalized” to a unit vector.

Parameters

Return Value

An array describing a tangent vector. It should have at least as many elements as the number of dimensions of the underlying surface. (Type: Array.<number>)

Back to documentation index.