# Documentation

### This is machine translation

Translated by
Mouseover text to see original. Click the button below to return to the English verison of the page.

# `plot`::`Surface`

Parametrized surfaces in 3D

MATLAB live scripts support most MuPAD functionality, though there are some differences. For more information, see Convert MuPAD Notebooks to MATLAB Live Scripts.

## Syntax

```plot::Surface(`[x, y, z]`, `u = umin .. umax`, `v = vmin .. vmax`, <`a = amin .. amax`>, `options`)
plot::Surface(`xyz`, `u = umin .. umax`, `v = vmin .. vmax`, <`a = amin .. amax`>, `options`)
plot::Surface(`A`, `u = umin .. umax`, `v = vmin .. vmax`, <`a = amin .. amax`>, `options`)
```

## Description

`plot::Surface` creates a parametrized surface in 3D.

The surface given by a mapping (“parametrization”) is the set of all image points

`$\left\{\text{\hspace{0.17em}}\left(\begin{array}{c}x\left(u,v\right)\\ y\left(u,v\right)\\ z\left(u,v\right)\end{array}\right)\text{\hspace{0.17em}}|\text{\hspace{0.17em}}u\in \left[{u}_{\mathrm{min}},{u}_{\mathrm{max}}\right],\text{\hspace{0.17em}}v\in \left[{v}_{\mathrm{min}},{v}_{\mathrm{max}}\right]\text{ }\right\}\in {ℝ}^{3}$`

The expressions/functions `x`, `y`, `z` may have singularities in the plot range. Although a heuristics is used to find a reasonable viewing range when singularities are present, it is highly recommended to specify a viewing box via the attribute ```ViewingBox = [xmin..xmax, ymin..ymax, zmin..zmax]``` with suitable numerical real values `xmin,…,zmax`. See Example 3.

Animations are triggered by specifying a range ```a = amin..amax``` for a parameter `a` that is different from the surface parameters `u`, `v`. See Example 5.

The functions `x`, `y`, `z` are evaluated on a regular equidistant mesh of sample points in the u-v plane. This mesh is determined by the attributes `UMesh`, `VMesh`. By default, the attribute `AdaptiveMesh = 0` is set, i.e., no adaptive refinement of the equidistant mesh is used.

If the standard mesh does not suffice to produce a sufficiently detailed plot, one may either increase the value of `UMesh`, `VMesh` or `USubmesh`, `VSubmesh`, or set `AdaptiveMesh = n` with some (small) positive integer `n`. If necessary, up to 2n - 1 additional points are placed in each direction of the u-v plane between adjacent points of the initial equidistant mesh. See Example 6.

The “coordinate lines” (“parameter lines”) are curves on the surface.

The phrase “`ULines`” refers to the curves (x(u, v0), y(u, v0), z(u, v0)) with the parameter u running from `umin` to `umax`, while v0 is some fixed value from the interval ```[vmin, vmax]```.

The phrase “`VLines`” refers to the curves (x(u0, v), y(u0, v), z(u0, v)) with the parameter v running from `vmin` to `vmax`, while u0 is some fixed value from the interval ```[umin, umax]```.

By default, the parameter curves are visible. They may be “switched off” by specifying `ULinesVisible = FALSE` and ```VLinesVisible = FALSE```, respectively.

The coordinate lines controlled by ```ULinesVisible = TRUE/FALSE``` and `VLinesVisible = TRUE/FALSE` indicate the equidistant mesh in the u-v plane set via the `UMesh`, `VMesh` attributes. If the mesh is refined by the `USubmesh`, `VSubmesh` attributes, or by the adaptive mechanism controlled by ```AdaptiveMesh = n```, no additional parameter lines are drawn.

As far as the numerical approximation of the surface is concerned, the settings `UMesh = nu`, ```VMesh = nv```, `USubmesh = mu`, ```VSubmesh = mv``` and ```UMesh = (nu - 1) (mu + 1) + 1```, ```VMesh = (nv - 1) (mv + 1) + 1```, `USubmesh = 0`, ```VSubmesh = 0``` are equivalent. However, in the first setting, `nu` parameter lines are visible in the u direction, while in the latter setting ```(nu - 1) (mu + 1) + 1``` parameter lines are visible. See Example 7.

Use `Filled = FALSE` to render the surface as a wireframe.

## Attributes

AttributePurposeDefault Value
`AdaptiveMesh`adaptive sampling`0`
`AffectViewingBox`influence of objects on the `ViewingBox` of a scene`TRUE`
`Color`the main color`RGB::Red`
`Filled`filled or transparent areas and surfaces`TRUE`
`FillColor`color of areas and surfaces`RGB::Red`
`FillColor2`second color of areas and surfaces for color blends`RGB::CornflowerBlue`
`FillColorType`surface filling types`Dichromatic`
`FillColorFunction`functional area/surface coloring
`FillColorDirection`the direction of color transitions on surfaces[`0`, `0`, `1`]
`FillColorDirectionX`x-component of the direction of color transitions on surfaces`0`
`FillColorDirectionY`y-component of the direction of color transitions on surfaces`0`
`FillColorDirectionZ`z-component of the direction of color transitions on surfaces`1`
`Frames`the number of frames in an animation`50`
`Legend`makes a legend entry
`LegendText`short explanatory text for legend
`LegendEntry`add this object to the legend?`TRUE`
`LineColor`color of lines`RGB::Black.[0.25]`
`LineWidth`width of lines`0.35`
`LineColor2`color of lines`RGB::DeepPink`
`LineStyle`solid, dashed or dotted lines?`Solid`
`LineColorType`line coloring types`Flat`
`LineColorFunction`functional line coloring
`LineColorDirection`the direction of color transitions on lines[`0`, `0`, `1`]
`LineColorDirectionX`x-component of the direction of color transitions on lines`0`
`LineColorDirectionY`y-component of the direction of color transitions on lines`0`
`LineColorDirectionZ`z-component of the direction of color transitions on lines`1`
`Mesh`number of sample points[`25`, `25`]
`MeshVisible`visibility of irregular mesh lines in 3D`FALSE`
`Name`the name of a plot object (for browser and legend)
`ParameterEnd`end value of the animation parameter
`ParameterName`name of the animation parameter
`ParameterBegin`initial value of the animation parameter
`ParameterRange`range of the animation parameter
`PointSize`the size of points`1.5`
`PointStyle`the presentation style of points`FilledCircles`
`PointsVisible`visibility of mesh points`FALSE`
`Shading`smooth color blend of surfaces`Smooth`
`Submesh`density of submesh (additional sample points)[`0`, `0`]
`TimeEnd`end time of the animation`10.0`
`TimeBegin`start time of the animation`0.0`
`TimeRange`the real time span of an animation`0.0` .. `10.0`
`Title`object title
`TitleFont`font of object titles[`" sans-serif "`, `11`]
`TitlePosition`position of object titles
`TitleAlignment`horizontal alignment of titles w.r.t. their coordinates`Center`
`TitlePositionX`position of object titles, x component
`TitlePositionY`position of object titles, y component
`TitlePositionZ`position of object titles, z component
`ULinesVisible`visibility of parameter lines (u lines)`TRUE`
`UMax`final value of parameter “u”
`UMesh`number of sample points for parameter “u”`25`
`UMin`initial value of parameter “u”
`UName`name of parameter “u”
`URange`range of parameter “u”
`USubmesh`density of additional sample points for parameter “u”`0`
`VLinesVisible`visibility of parameter lines (v lines)`TRUE`
`VMax`final value of parameter “v”
`VMesh`number of sample points for parameter “v”`25`
`VMin`initial value of parameter “v”
`VName`name of parameter “v”
`VRange`range of parameter “v”
`VSubmesh`density of additional sample points for parameter “v”`0`
`Visible`visibility`TRUE`
`VisibleAfter`object visible after this time value
`VisibleBefore`object visible until this time value
`VisibleFromTo`object visible during this time range
`VisibleAfterEnd`object visible after its animation time ended?`TRUE`
`VisibleBeforeBegin`object visible before its animation time starts?`TRUE`
`XContours`contour lines at constant x values[]
`XFunction`function for x values
`YContours`contour lines at constant y values[]
`YFunction`function for y values
`ZContours`contour lines at constant z values[]
`ZFunction`function for z values

## Examples

### Example 1

Using standard spherical coordinates, a parametrization of a sphere of radius r by the azimuth angle u ∈ [0, 2 π] and the polar angle v ∈ [0, π] is given by:

```x := r*cos(u)*sin(v): y := r*sin(u)*sin(v): z := r*cos(v):```

We fix r = 1 and create the surface object:

```r := 1: s := plot::Surface([x, y, z], u = 0 .. 2*PI, v = 0 .. PI)```

We call `plot` to plot the surface:

`plot(s, Scaling = Constrained):`

`delete x, y, z, r, s:`

### Example 2

The parametrization can also be specified by `piecewise` objects or procedures:

```x := u*cos(v): y := piecewise([u <= 1, u*sin(v)], [u >= 1, u^2*sin(v)]): z := proc(u, v) begin if u <= 1 then 0 else cos(4*v) end_if: end_proc: plot(plot::Surface([x, y, z], u = 0 .. sqrt(2), v = 0 .. 2*PI)):```

We enable adaptive sampling to get a smoother graphical result:

```plot(plot::Surface([x, y, z], u = 0 .. sqrt(2), v = 0 .. 2*PI), AdaptiveMesh = 3):```

`delete x, y, z, s, r:`

### Example 3

We plot a surface with singularities:

```s := plot::Surface([u*cos(v), u*sin(v), 1/u^2], u = 0 .. 1, v = 0 .. 2*PI): plot(s):```

We specify an explicit viewing range for the z coordinate:

`plot(s, ViewingBox = [Automatic, Automatic, 0 .. 10]):`

`delete s:`

### Example 4

By introducing non-real function evaluations, we can plot surfaces with holes:

```chi := piecewise([sin(4*u) < cos(3*v)+0.5, 1]): plot(plot::Surface([cos(u)*sin(v), sin(u)*sin(v), chi*cos(v)], u = 0 .. 2*PI, v = 0 .. PI, AdaptiveMesh=2), Scaling = Constrained)```

### Example 5

We generate an animation of a surface of revolution. The graph of the function is rotated around the x-axis:

```f := u -> 1/(1 + u^2): plot(plot::Surface([u, f(u)*sin(v), f(u)*cos(v)], u = -2 .. 2, v = 0 .. a*2*PI, a = 0 .. 1)):```

See `plot::XRotate`, `plot::ZRotate` for an alternative way to create surfaces of revolution.

`delete f:`

### Example 6

The standard mesh for the numerical evaluation of a surface does not suffice to generate a satisfying plot in the following case:

```r := 2 + sin(7*u + 5*v): x := r*cos(u)*sin(v): y := r*sin(u)*sin(v): z:= r*cos(v): plot(plot::Surface([x, y, z], u = 0 .. 2*PI, v = 0 .. PI)):```

We increase the number of mesh points. Here, we use `USubmesh`, `VSubmesh` to place 2 additional points in each direction between each pair of neighboring points of the default mesh. This increases the runtime for computing the plot by a factor of 9:

```plot(plot::Surface([x, y, z], u = 0 .. 2*PI, v = 0 .. PI, USubmesh = 2, VSubmesh = 2)):```

Alternatively, we enable adaptive sampling by setting the value of `AdaptiveMesh` to some positive value:

```plot(plot::Surface([x, y, z], u = 0 .. 2*PI, v = 0 .. PI, AdaptiveMesh = 2)):```

`delete r, x, y, z:`

### Example 7

By default, the parameter lines of a parametrized surface are “switched on”:

```x := r*cos(phi): y := r*sin(phi): z := r^2: plot(plot::Surface([x, y, z], r = 1/3 .. 1, phi = 0 .. 2*PI)):```

The parameter lines are “switched off”:

```plot(plot::Surface([x, y, z], r = 1/3 .. 1, phi = 0 .. 2*PI, ULinesVisible = FALSE, VLinesVisible = FALSE)):```

The number of parameter lines are determined by the attributes `UMesh` and `VMesh`:

```plot(plot::Surface([x, y, z], r = 1/3 .. 1, phi = 0 .. 2*PI, UMesh = 5, VMesh = 12)):```

When the mesh is refined via the attributes `USubmesh`, `VSubmesh`, the numerical approximation of the surface becomes smoother. However, the number of parameter lines is determined by the values of `UMesh`, `VMesh` and is not increased:

```plot(plot::Surface([x, y, z], r = 1/3 .. 1, phi = 0 .. 2*PI, UMesh = 5, VMesh = 12, USubmesh = 1, VSubmesh = 2)):```

### Example 8

Klein's bottle is a surface without orientation. There is no “inside” and no “outside” of the following object:

```bx := u -> -6*cos(u)*(1 + sin(u)): by := u -> -14*sin(u): r := u -> 4 - 2*cos(u): x := (u, v) -> piecewise([u <= PI, bx(u) - r(u)*cos(u)*cos(v)], [PI < u, bx(u) + r(u)*cos(v)]): y := (u, v) -> r(u)*sin(v): z := (u, v) -> piecewise([u <= PI, by(u) - r(u)*sin(u)*cos(v)], [PI < u, by(u)]): KleinBottle:= plot::Surface( [x, y, z], u = 0 .. 2*PI, v = 0 .. 2*PI, Mesh = [35, 31], LineColor = RGB::Black.[0.2], FillColorFunction = RGB::MuPADGold): plot(KleinBottle, Axes = None, Scaling = Constrained, Width = 60*unit::mm, Height = 72*unit::mm, BackgroundStyle = Pyramid):```

`delete bx, by, r, x, y, z, KleinBottle:`

### Example 9

Finally we create an animated surface plot of where a is the animation parameter:

```plot( plot::Surface( [sin(u),sin(v),a*sin(u+v)], u=0..2*PI, v=0..2*PI, a=1..0, AnimationStyle = BackAndForth ) )```

## Parameters

 `x`, `y`, `z` The coordinate functions: arithmetical expressions or `piecewise` objects depending on the surface parameters u, v and the animation parameter `a`. Alternatively, procedures that accept 2 input parameters u, v or 3 input parameters u, v, a and return a numerical value when the input parameters are numerical. `x`, `y`, `z` are equivalent to the attributes `XFunction`, `YFunction`, `ZFunction`. `xyz` The parametrization: a procedure that accepts 2 input parameters u, v or 3 input parameters u, v, a and returns a list of 3 numerical values [x, y, z]. `A` A matrix of category `Cat::Matrix` with three entries that provide the parametrization `x`, `y`, `z` `u` The first surface parameter: an identifier or an indexed identifier. `u` is equivalent to the attribute `UName`. `umin .. umax` The plot range for the parameter u: `umin`, `umax` must be numerical real values or expressions of the animation parameter a. `umin` .. `umax` is equivalent to the attributes `URange`, `UMin`, `UMax`. `v` The second surface parameter: an identifier or an indexed identifier. `v` is equivalent to the attribute `VName`. `vmin .. vmax` The plot range for the parameter v: `vmin`, `vmax` must be numerical real values or expressions of the animation parameter a. `vmin` .. `vmax` is equivalent to the attributes `VRange`, `VMin`, `VMax`. `a` Animation parameter, specified as `a```` = amin..amax```, where `amin` is the initial parameter value, and `amax` is the final parameter value.