# plot::Spherical

Surfaces in 3D parameterized in spherical coordinates

### Use only in the MuPAD Notebook Interface.

This functionality does not run in MATLAB.

## Syntax

```plot::Spherical(`[r, ϕ, θ]`, `u = umin .. umax`, `v = vmin .. vmax`, <`a = amin .. amax`>, `options`)
```

## Description

`plot::Spherical` creates surfaces parametrized in spherical coordinates.

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

$\left\{\text{\hspace{0.17em}}\left(\begin{array}{c}r\left(u,v\right)\\ \varphi \left(u,v\right)\\ \theta \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{\hspace{0.17em}}\right\}$

in spherical coordinates, which translate to the usual "Cartesian" coordinates as

$\begin{array}{l}x=r\mathrm{cos}\left(\varphi \right)\mathrm{sin}\left(\theta \right)\\ y=r\mathrm{sin}\left(\varphi \right)\mathrm{sin}\left(\theta \right)\\ x=r\mathrm{cos}\left(\theta \right)\end{array}$

r is referred to as "radius", ϕ as "azimuthal angle", and θ is known as "polar angle."

The functions r, ϕ, θ 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. Cf.  Example 3.

"Coordinate lines" ("parameter lines") are curves on the surface.

The phrase "`ULines`" refers to the curves (r(u, v0), ϕ(u, v0), θ(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 (r(u0, v), ϕ(u0, v), θ(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. Cf. Example 3.

Use `Filled` = `FALSE` to obtain a wireframe representation of the surface.

If the expression/function r contains singularities, it is recommended (but not strictly necessary) to use the attribute `ViewingBox` to set a suitable viewing box. No such precautions are necessary for ϕ and θ, although singularities in these functions may result in poorly rendered surfaces – in many cases setting the attributes `Mesh` and/or `AdaptiveMesh` to higher values will help. Cf. Example 6.

## 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`
`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

Spherical coordinates get their name from the fact that, with a constant radius, the parameterize a sphere:

`plot(plot::Spherical([1, u, v], u = 0..2*PI, v = 0..PI))`

`plot(plot::Spherical([1, u, v], u = 0..PI, v = 0..2*PI))`

### Example 2

The following plot demonstrates that spherical plots can exhibit singular surface features even with differentiable parameterizations; in this case, the rim in the middle is actually a border of both the left- and the right-hand part:

```plot(plot::Spherical( [(phi^2*thet), phi, thet^2], phi = -PI..PI, thet=0..0.25*PI, Mesh = [40,40], Submesh=[3,0], Color = [0.9\$3], FillColorType=Flat, LineColor=[0.8\$3]), Axes = None, CameraDirection = [1, 0, 0])```

### Example 3

For oscillating parameterizations or other surfaces with fine details, the default mesh may be too coarse. As stated above, the three attributes `Mesh`, `Submesh`, and `AdaptiveMesh` can be used for improving plots of these objects.

First, note that the following plot is not rendered with a sufficient resolution:

```surf := plot::Spherical([4+sin(5*(u+v)), u, v], u = 0..PI, v = 0..2*PI): plot(surf, Axes = None)```

Setting `Mesh` to twice its default, we get a smoother surface with additional parameter lines:

```surf::Mesh := [50, 50]: plot(surf, Axes = None)```

Almost the same effect, but without the additional parameter lines, can be achieved by setting `Submesh = [1, 1]`:

```delete surf::Mesh: surf::Submesh := [1, 1]: plot(surf, Axes = None)```

It is also possible to use adaptive mesh refinement in areas where neighboring patches have an angle of more than 10 degrees. While this option is mostly useful for surfaces which require refinement only in some parts, it is certainly feasible with a plot like this, too (but increasing `Submesh` is faster):

```delete surf::Submesh: surf::AdaptiveMesh := 2: plot(surf, Axes = None)```

### Example 4

The radius function r may also take on negative values. With radius functions of changing sign, spherical surfaces often do self-intersect:

```plot(plot::Spherical( [sin(phi^2*thet), phi, thet], phi = -PI..PI, thet = 0..0.5*PI, Mesh = [40, 20], Submesh=[0, 3]))```

### Example 5

The angular functions (ϕ and θ) are not limited in value:

```plot(plot::Spherical([r, r, thet], r = 0..9, thet = -PI..PI, Mesh = [60, 60], Filled = FALSE), Axes = None, plot::Camera([100, 100, 50], [0,0,0], 0.1))```

Note that we used an explicit `plot::Camera` object here because the automatic camera is always placed such that all of an object is visible, even when using `CameraDirection`. To get a "closer" look, use the interactive manipulation possibilities or an explicit camera.

### Example 6

Singularities in the radius function are heuristically handled:

`plot(plot::Spherical([1/(u + v), u, v], u = 0..PI, v = 0..PI))`

However, the heuristics fails for some examples:

`plot(plot::Spherical([1/(u + v)^2, u, v], u = 0..PI, v = 0..PI))`

In cases like this, we recommend setting a viewing box explicitly with the attribute `ViewingBox`:

```plot(plot::Spherical([1/(u + v)^2, u, v], u = 0..PI, v = 0..PI), ViewingBox = [-1/10..0.7, 0..1/4, -0.2..0.3])```

### Example 7

By setting one of the parameter ranges to a degenerate interval, it is possible to draw curves on a spherical surface:

```f := (u, v) -> [1 + u/10, u, v]: surface := plot::Spherical(f(u,v), u = 0..2, v = 0..2, FillColor = RGB::Grey, FillColorType = Flat): curve := plot::Spherical(f((1 + sin(u)), (1 + sin(2*u))), u = 0..2*PI, v = 0..0, Mesh = [200, 1], LineColor = RGB::Red, LineWidth = 1): plot(surface, curve)```

### Example 8

While the transformation from spherical to Cartesian coordinates is not invertible, there are at least two ways of expressing each Cartesian point in spherical coordinates and any surface parameterizable in Cartesian coordinates can also be plotted using `plot::Spherical`:

```trans := linalg::ogCoordTab[Spherical, InverseTransformation]: spher := trans(x, y, sin(x^2+y^2))```

`plot(plot::Spherical(spher, x = -2..2, y = -2..2))`

### Example 9

Last but not least we can also produce animations with the help of `plot::Spherical`. The following shows a deformation from a general spherical object to a sphere. We have used the animation parameter `a` inside of the argument for the sine function to obtain a slight rotation during the deformation process:

```plot( plot::Spherical( [1+a*sin(3*Phi+a)*sin(2*Theta),Phi,Theta], Theta=0..PI, Phi=0..2*PI, a=5..0 ) )```

## Parameters

 `r`, `ϕ`, `θ` 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 real numerical value when the input parameters are numerical. `r`, `ϕ`, `θ` are equivalent to the attributes `XFunction`, `YFunction`, `ZFunction`. `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.