surface

A function of the plane, shaded; in space, the surface itself.

surfaceNode
Only withxyargandpolarxyzplane
On this page
The field x·y painted on the blue-to-red temperature ramp, blue in two opposite quadrants and red in the others.The field x·y painted on the blue-to-red temperature ramp, blue in two opposite quadrants and red in the others.

#On a flat plane

On a flat plane a surface paints a function of the plane over the visible window, surface(f: x^2 - y^2), sampled again as the reader pans. Its letters are the plane's coordinates, x and y (or r and theta on the polar plane), and any other letter is a parameter. On the argand plane it is a function of z, coloured by domain under the default ramp.

colour is a ramp, a hue or a list of stops: multicolour, the default, runs violet at the lowest value to red at the highest; temperature runs blue through white to red; a hue shades from bare to full; teal, yellow, red runs through its stops, low end first. The ramp spans the values in the window, and moves as a parameter does; #self.value applied to an interval and a ramp pins it, colour: #self.value -> -1..1 -> temperature, and with temperature a symmetric window puts white at 0. invert flips it. A contour of the same expression draws its level sets over the wash, and @let keeps the expression written once.

The field sin x · cos y painted on the blue-to-red temperature ramp, with its zero contour in grey.The field sin x · cos y painted on the blue-to-red temperature ramp, with its zero contour in grey.
graph{
    surface(expression: sin(x) * cos(y); colour: temperature)
    contour(expression: sin(x) * cos(y); levels: 0; colour: grey)
}

A heatmap is a grid of cells holding the values given; a surface is a function sampled everywhere in the window. An equation is a surface only in space; on a flat plane, surface(f: x^2 + y^2 = 4) is refused: 'surface' as an equation is an implicit surface, in space on graph:xyz — on the xy plane it is a value over the plane: 'surface: x^2 - y^2'.

#In space

In space a surface is the surface itself: a height, surface(f: 16 - x^2 - y^2), or an equation in x, y and z, surface(f: x^2 + y^2 + z^2 = 9). Its faces are shaded by how they meet the light, in one blue unless colour says otherwise; a ramp colours it by height, across the box's z domain or the window #self.value -> lo..hi -> ramp pins. One linear in x, y and z is a plane, drawn exactly where it crosses the box, green and translucent unless told otherwise, and cutting cleanly through any surface it meets: surface(f: 4x + 2y - 3) is a tangent plane, surface(f: x = 1) a vertical slice. mesh draws the hairlines over a height's faces, resolution sets the cells along each side, and label, which only space takes, sets words at the surface's highest point.

#Attributes

expressionImplicitAnimatable
The surface. On the ordinary and polar planes, a value over the plane, painted: surface(f: x^2 - y^2); on the argand plane, a function of z, domain coloured. In space, a height, surface(f: 16 - x^2 - y^2), or an equation in x, y and z, meshed where its two sides agree: surface(f: x^2 + y^2 + z^2 = 9). An equation is a surface only in space.
parametised-surface-expression
Also written: exp, f, func, function, equation, eqCan be written as shorthand: surface:value
meshAnimatable
Space only: the hairline mesh over the faces of a height.
boolean
Defaulttrue
resolution
Space only: how many cells the surface is sampled at along each side — 32 for a height, 24 for an equation.
number
invertAnimatable
Flip the ramp, putting deep colour at low values rather than high.
boolean
Defaultfalse
colour
multicolour (the default) runs the full spectrum, violet low to red high; temperature is the blue → white → red wash; any ordinary hue shades its own intensity ramp instead. Both ramps are fixed colours, identical in light and dark mode. Unset, it is multicolour on a flat plane and one blue hue, shaded, in space. A list of hues is the ramp's stops, low end first. The ramp spans the sampled extrema, which re-normalise as a parameter drags; applying #self.value pins the window, values outside it taking the ramp's ends: colour: #self.value -> -1..1 -> temperature puts white at zero.
value-colour-style
Also written: color
opacityAnimatable
How heavy the wash sits over the plot — 0.75 when unset. In space, how solid the surface is, opaque when unset.
number
label
In space, words naming the surface, set at its highest point — or at a corner of a flat one. Space only: on the flat planes a surface is a wash under the other marks.
rich-text
hiddenAnimatable
Declared but not drawn — animatable, so hidden: true !cue.to{false}(at: 2) is its reveal.
boolean
Defaultfalse
lock
A reader may not edit it on an editable graph.
boolean
Also written: locked
Defaultfalse
layerAnimatable
Paint order among the marks: a higher layer is drawn later, on top; equal or omitted, the marks stack in document order, later on top.
parametised-number
group
The groups this mark belongs to, comma-separated: group: Early sown, Projected. It is drawn in the colour of the first that has one and the style of the first the graph's key: gives one, unless it writes its own colour: or style, and the footer's key names every group.
string

#Derived attributes

Computed while the element renders — read one with #id.name in attribute position or {{#id.name}} in prose, never set.

valueDerived
The surface's value at each sample, which colour: follows as #self.value: colour: #self.value -> -1..1 -> temperature pins the window the ramp spans.
minDerived
The smallest value the surface takes over the sampled window — in space, over the box's floor, and a dash for a surface given by an equation. Cite it with {{#id.min}}.
maxDerived
The largest value the surface takes over the sampled window — in space, over the box's floor, and a dash for a surface given by an equation.

#Allowed in

graph { }cue { }cue.draw { }cue.trace { }cue.highlight { }cue.spotlight { }

#Examples

The bowl x² + y² shaded from its low centre outwards.The bowl x² + y² shaded from its low centre outwards.
graph{
    surface(expression: x^2 + y^2)
}
The bowl centred on (2, 3), shaded red with the ramp inverted, so its lowest point is darkest.The bowl centred on (2, 3), shaded red with the ramp inverted, so its lowest point is darkest.
graph{
    surface(expression: (x - 2)^2 + (y - 3)^2; colour: red; invert: true)
}
A sum-of-squares valley shaded at half opacity, with its contours at 1, 2, 4, 8 and 16 drawn over it.A sum-of-squares valley shaded at half opacity, with its contours at 1, 2, 4, 8 and 16 drawn over it.
graph{
    surface(expression: {{sse}}; opacity: 0.5)
    contour(expression: {{sse}}; levels: 1, 2, 4, 8, 16)
}
In space: the dome z = 4 − x² − y² over the floor, shaded blue by how its faces meet the light, with a hairline mesh.In space: the dome z = 4 − x² − y² over the floor, shaded blue by how its faces meet the light, with a hairline mesh.
graph:xyz{
    surface(expression: 4 - x^2 - y^2)
}(
    x domain: [-2, 2]
    y domain: [-2, 2]
    z domain: [-4, 4]
    axis position: edges
)
In space: the sphere x² + y² + z² = 4 written as an equation, shaded purple, in a box with equal units.In space: the sphere x² + y² + z² = 4 written as an equation, shaded purple, in a box with equal units.
graph:xyz{
    surface(f: x^2 + y^2 + z^2 = 4; colour: purple)
}(
    x domain: [-2.5, 2.5]
    y domain: [-2.5, 2.5]
    z domain: [-2.5, 2.5]
    aspect: equal
)
The bowl z = 2x² + y² with its tangent plane z = 4x + 2y − 3 touching it at P = (1, 1, 3).The bowl z = 2x² + y² with its tangent plane z = 4x + 2y − 3 touching it at P = (1, 1, 3).
graph:xyz{
    surface(expression: 2 * x^2 + y^2)
    surface(expression: 4x + 2y - 3)
    point(x: 1; y: 1; z: 3; label: $P$)
}(
    x domain: [-2, 2]
    y domain: [-2, 2]
    z domain: [0, 12]
    view: (35, 25)
)
The plane x + 2y + 3z = 6 cut to the box, and the vertical plane x = 1 crossing it.The plane x + 2y + 3z = 6 cut to the box, and the vertical plane x = 1 crossing it.
graph:xyz{
    surface(f: x + 2y + 3z = 6)
    surface(f: x = 1; colour: orange)
}(
    x domain: [-3, 3]
    y domain: [-3, 3]
    z domain: [-3, 3]
)

Last updated