# `plot`::`Function3d`

3D function graphs

MuPAD® notebooks will be removed in a future release. Use MATLAB® live scripts instead.

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

For a 3–D function plot in MATLAB®, see `surf`.

## Syntax

```plot::Function3d(`f`, `options`)
plot::Function3d(`f`, `x = xmin .. xmax`, `y = ymin .. ymax`, <`a = amin .. amax`>, `options`)
```

## Description

`plot::Function3d` creates the 3D graph of a function in 2 variables.

The expression `f(x, y)` is evaluated at finitely many points x, y in the plot range. There may be singularities. Although a heuristics is used to find a reasonable z range when singularities are present, it is highly recommended to specify a z range via `ViewingBoxZRange = `z_{min}` .. `z_{max}`` with suitable numerical real values `zmin`, `zmax`. See Example 2.

Animations are triggered by specifying a range ```a = `a_{min}` .. `a_{max}```` for a parameter `a` that is different from the indedependent variables `x`, `y`. Thus, in animations, the x-range ```x = `x_{min}` .. `x_{max}````, the y-range ```y = `y_{min}` .. `y_{max}```` as well as the animation range ```a = `a_{min}` .. `a_{max}```` must be specified. See Example 3.

The function `f` is evaluated on a regular equidistant mesh of sample points determined by the attributes `XMesh` and `YMesh` (or the shorthand-notation for both, `Mesh`). 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 `XMesh` and `YMesh` or set `AdaptiveMesh = n` with some (small) positive integer `n`. This may result in up to 4n times as many triangles as used with `AdaptiveMesh = 0`, potentially more when `f` has non-isolated singularities. See Example 4.

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

The phrase “`XLines`” refers to the curves (x, y0, f(x, y0)) with the parameter x running from `xmin` to `xmax`, while y0 is some fixed value from the interval ```[ymin, ymax]```.

The phrase “`YLines`” refers to the curves (x0, y, f(x0, y)) with the parameter y running from `ymin` to `ymax`, while x0 is some fixed value from the interval ```[xmin, xmax]```.

By default, the parameter lines are visible. They may be “switched off” by specifying `XLinesVisible = FALSE` and ```YLinesVisible = FALSE```, respectively.

The coordinate lines controlled by ```XLinesVisible = TRUE/FALSE``` and `YLinesVisible = TRUE/FALSE` indicate the equidistant regular mesh set via the `Mesh` attributes. If the mesh is refined by the `Submesh` attributes or by the adaptive mechanism controlled by `AdaptiveMesh = n`, no additional parameter lines are drawn.

As far as the numerical approximation of the function graph is concerned, the settings

`Mesh = [nx, ny]`, ```Submesh = [mx, my]```

and

```Mesh = [(nx - 1) (mx + 1) + 1, (ny - 1) (my + 1) + 1]```, `Submesh = [0, 0]`

are equivalent. However, in the first setting, `nx` parameter lines are visible in the x direction, while in the latter setting ```(nx - 1) (mx + 1) + 1``` parameter lines are visible. See Example 5.

## 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`
`Function`function expression or procedure
`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`
`LinesVisible`visibility of lines`TRUE`
`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
`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`
`XLinesVisible`visibility of parameter lines (x lines)`TRUE`
`XMax`final value of parameter “x”`5`
`XMesh`number of sample points for parameter “x”`25`
`XMin`initial value of parameter “x”`-5`
`XName`name of parameter “x”
`XRange`range of parameter “x”`-5` .. `5`
`XSubmesh`density of additional sample points for parameter “x”`0`
`YLinesVisible`visibility of parameter lines (y lines)`TRUE`
`YMax`final value of parameter “y”`5`
`YMesh`number of sample points for parameter “y”`25`
`YMin`initial value of parameter “y”`-5`
`YName`name of parameter “y”
`YRange`range of parameter “y”`-5` .. `5`
`YSubmesh`density of additional sample points for parameter “y”`0`
`ZContours`contour lines at constant z values[]

## Examples

### Example 1

The following call returns an object representing the graph of the function sin(x2 + y2) over the region - 2 ≤ x ≤ 2, - 2 ≤ y ≤ 2:

`g := plot::Function3d(sin(x^2 + y^2), x = -2..2, y = -2..2)`
` `

Call `plot` to plot the graph:

`plot(g)` Functions can also be specified by `piecewise` objects or procedures:

```f := piecewise([x < y, 0], [x >= y, (x - y)^2]): plot(plot::Function3d(f, x = -2 .. 4, y = -1 .. 3))``` ```f := proc(x, y) begin if x + y^2 + 2*y < 0 then 0 else x + y^2 + 2*y end_if: end_proc: plot(plot::Function3d(f, x = -3 .. 2, y = -2 .. 2))``` `delete g, f`

### Example 2

We plot a function with singularities:

```f := plot::Function3d(x/y + y/x, x = -1 .. 1, y = - 1 .. 1): plot(f)``` We specify an explicit viewing range for the z direction:

`plot(f, ViewingBoxZRange = -20 .. 20)` `delete f`

### Example 3

We generate an animation of a parametrized function:

```plot(plot::Function3d(sin((x - a)^2 + y^2), x = -2 .. 2, y = -2 .. 2, a = 0 .. 5))``` ### Example 4

The standard mesh for the numerical evaluation of a function graph does not suffice to generate a satisfying graphics in the following case:

```plot(plot::Function3d(besselJ(0, sqrt(x^2 + y^2)), x = -20 .. 20, y = -20 .. 20))``` We increase the number of mesh points. Here, we use `XSubmesh` and `YSubmesh` to place 2 additional points in each direction between each pair of neighboring points of the default mesh. This increases the runtime by a factor of 9:

```plot(plot::Function3d(besselJ(0, sqrt(x^2 + y^2)), x = -20 .. 20, y = -20 .. 20, Submesh = [2, 2]))``` Alternatively, we enable adaptive sampling by setting the value of `AdaptiveMesh` to some positive value:

```plot(plot::Function3d(besselJ(0, sqrt(x^2 + y^2)), x = -20 .. 20, y = -20 .. 20, AdaptiveMesh = 2))``` ### Example 5

By default, the parameter lines of a function graph are “switched on”:

`plot(plot::Function3d(x^2 + y^2, x = 0 .. 1, y = 0 .. 1))` The parameter lines are “switched off” by setting `XLinesVisible`, `YLinesVisible`:

```plot(plot::Function3d(x^2 + y^2, x = 0 .. 1, y = 0 .. 1, XLinesVisible = FALSE, YLinesVisible = FALSE))``` The number of parameter lines are determined by the `Mesh` attributes:

```plot(plot::Function3d(x^2 + y^2, x = 0 .. 1, y = 0 .. 1, Mesh = [5, 12]))``` When the mesh is refined via the `Submesh` attributes, the numerical approximation of the surface becomes smoother. However, the number of parameter lines is not increased:

```plot(plot::Function3d(x^2 + y^2, x = 0 .. 1, y = 0 .. 1, Mesh = [5, 12], XSubmesh = 1, YSubmesh = 2))``` ### Example 6

Functions need not be defined over the whole parameter range:

`plot(plot::Function3d(sqrt(1-x^2-y^2), x=-1..1, y=-1..1))` `plot(plot::Function3d(sqrt(sin(x)+cos(y))))` This makes for an easy way of plotting a function over a non-rectangular area:

`chi := piecewise([x^2 < abs(y), 1])`
` `
```plot(plot::Function3d(chi*sin(x+cos(y))), CameraDirection=[-1,0,0.5])``` ## Parameters

 `f` The function: an arithmetical expression or a `piecewise` object in the independent variables x, y and the animation parameter `a`. Alternatively, a procedure that accepts 2 input parameter x, y or 3 input parameters x, y, a and returns a numerical value when the input parameters are numerical. `f` is equivalent to the attribute `Function`. `x` The first independent variable: an identifier or an indexed identifier. `x` is equivalent to the attribute `XName`. `xmin .. xmax` The plot range in x direction: `xmin`, `xmax` must be numerical real values or expressions of the animation parameter a. If not specified, the default range `x = -5 .. 5` is used. `xmin` .. `xmax` is equivalent to the attributes `XRange`, `XMin`, `XMax`. `y` The second independent variable: an identifier or an indexed identifier. `y` is equivalent to the attribute `YName`. `ymin .. ymax` The plot range in y direction: `ymin`, `ymax` must be numerical real values or expressions of the animation parameter a. If not specified, the default range `y = -5 .. 5` is used. `ymin` .. `ymax` is equivalent to the attributes `YRange`, `YMin`, `YMax`. `a` Animation parameter, specified as `a```` = amin..amax```, where `amin` is the initial parameter value, and `amax` is the final parameter value.