## `plot2d` -- 2D plots

#### Introduction

`plot2d(`object1, object2, ...`)` generates a 2D plot of graphical objects such as parametrized curves, points, and polygons.

#### Call(s)

`plot2d( <SceneOptions,> object1, object2, ...)`

#### Parameters

`object1, object2, ...` | - | graphical objects as described below

#### Options

`SceneOptions` | - | a sequence of scene options. These determine the general appearance of the graphical scene. See `?plotOptions2d` for details.

#### Returns

MuPAD's graphics tool is called to render the graphical scene, and the `null``()` object is returned to the MuPAD session.

#### Related Functions

`plot`, `plotfunc2d`, `plot3d`, `plotfunc3d`

#### Details

- `plot2d` is a low level interface to create 2D plots from graphical primitives. For graphs of functions, the specialized routines `plotfunc2d` and `plot::Function2d` are more convenient. For graphical scenes built from primitives, we recommend to use the `plot` library, which provides various primitives and tools. In most cases, the user will find it more convenient to use the `plot` library rather than `plot2d`.
- There are two types of graphical objects that are accepted by `plot2d`: i) lists of graphical primitives (points and polygons) and ii) parametrized curves.
- i) Lists of graphical primitives are objects of the following form:

  `[Mode = List, [primitive1, primitive2, ...] <, Options>]`

  The available primitives are points, polygons and filled polygons generated by the MuPAD functions `point` and `polygon`, respectively. You can use such primitives to build more complicated graphical objects.

  Options are specified by equations `OptionName = value`. The following table gives an overview of the available options:

  `OptionName` | admissible values | default value
  Color | `[Flat]`, `[Flat, [r,g,b]]`, `[Height]`, `[Height, [r,g,b], [R,G,B]]`, `[Function, f]` | `[Height]`
  LineStyle | SolidLines, DashedLines | SolidLines
  LineWidth | positive integers | `1`
  PointStyle | Circles, FilledCircles, FilledSquares, Squares | FilledSquares
  PointWidth | positive integers | `30`
  Title | strings |
  TitlePosition | `[x, y]` |

  See the description below for further details on each option.
- ii) Parametric curves are given by a parametrization u -> (x(u), y(u)) with expressions x(u), y(u) defining the x,y-coordinates as functions of a curve parameter u. In `plot2d`, a curve is defined by an object of the following form:

  `[Mode = Curve, [x(u), y(u)], u = [umin, umax] <, Options>]`

  The parametrization `x(u)`, `y(u)` consists of arithmetical expressions in one indeterminate `u` (an identifier). They must not contain any other symbolic parameters that cannot be converted to real floating point numbers. The range of the curve parameter `u` is given by the real numbers or numerical expressions `umin` and `umax`.

  If the parametrization is given by user-defined functions that accept only numerical values, premature evaluation can be avoided using `hold``(x)(u)`, `hold``(y)(u)` with the symbolic curve parameter `u`.

  Options are specified by equations `OptionName = value`. All options for a list of primitives can be used. For curves, the following additional options are available:

  `OptionName` | admissible values | default value
  Grid | `[n]` | `[100]`
  Smoothness | `[n]` | `[0]`
  Style | `[Points]`, `[Lines]`, `[LinesPoints]`, `[Impulses]` | `[Lines]`

  See the description below for further details on each option.

- The graph of a function f(x) can be plotted as a parametrized curve

  `[Mode = Curve, [x, f(x)], x = [xmin, xmax] <, Options>]`

  However, it is more convenient to use `plotfunc2d` or `plot::Function2d` to plot or generate function graphs. Furthermore, in contrast to `plot2d`, the latter handle functions with singularities.

- MuPAD graphics can be saved in a variety of graphical formats. In a `plot2d` command, the PlotDevice scene option allows to specify the conversion into the two MuPAD specific formats 'Ascii' and 'Binary'. See the help page `plotOptions2d` for details.

  For graphical standard formats such as Postscript, JPEG, TIFF etc., no direct conversion is available by a plot command inside a MuPAD session. Instead, conversion has to be requested interactively via the graphical interface of the rendering tool VCam. In a MuPAD Pro notebook, double click on the graphics to activate this interface. Using the menu item ``Edit/Save Graphics ..'', you can choose the desired format in the ``Export Graphics'' dialog box.

#### Option: Color =

`value`

- This option determines the color of the object. Admissible values are `[Flat]`, `[Flat, [r,g,b]]`, `[Height]`, `[Height, [r,g,b], [R,G,B]]` and `[Function, f]`. The default is Color = `[Height]`.
  - With Color = `[Flat]`, the object is displayed with a flat color. The actual color is chosen automatically.
  - With Color = `[Flat, [r, g, b]]`, the object is displayed with a flat color. The values `r`, `g`, `b` represent the red, green and blue contributions according to the RGB color model. They must be real numbers between `0` and `1`. Pre-defined colors are provided by MuPAD's `RGB` data structure.
  - With Color = `[Height]`, the color varies with the y-coordinate. The actual colors are chosen automatically.
  - With Color = `[Height, [r, g, b], [R, G, B]]`, the color varies with the y-coordinate. The parts of the object with small values of y are displayed with the color `[r, g, b]`, parts with large values of y are displayed with the color `[R, G, B]`. Interpolated color values are used in between.
  - With Color = `[Function, f]`, users may implement their own coloring scheme. The parameter `f` must be a MuPAD procedure returning a color as a list `[r, g, b]`.
    - Inside a curve object, the function `f` must accept three parameters:

      `f := proc(x, y, u) begin ...; return([r, g, b]) end:`

      During the numerical evaluation of the plot, this function is called with the arguments `(x(u), y(u), u)`, where `u` is the curve parameter and `x(u)`, `y(u)` are the corresponding coordinates.

    - Inside a list of primitives, the function `f` must accept two parameters:

      `f := proc(x, y) begin ...; return([r, g, b]) end:`

      During the numerical evaluation of the plot this function is called with arguments `(x, y)` from the viewing range of the object.

      Note that polygons are always displayed with a flat color.

    If the color function `f` is created inside a procedure, using local variables of this procedure, then this procedure must use `option escape`.

#### Option: Grid = `[n]`

- This option determines the number of sample points of the curve. The graphics uses linear interpolation between adjacent sample points. The integer `n` must be larger than 1. The default is Grid = `[100]`. Large values of `n` generate a smooth curve. Alternatively, the Smoothness parameter can be increased.

#### Option: LineStyle =

`value`

- This option determines the style in which lines are displayed. Admissible values are SolidLines and DashedLines; the default is LineStyle = SolidLines.

#### Option: LineWidth = `n`

- This option sets the width of the lines belonging to the object. Admissible values for `n` are nonnegative integers; the default is LineWidth = 1.

#### Option: PointStyle =

`value`

- This option sets the style in which point objects are displayed. Admissible values are Circles, Squares, FilledCircles, and FilledSquares. The default is PointStyle = FilledSquares.

#### Option: PointWidth = `n`

- This option sets the size of point objects. Admissible values for `n` are positive integers; the default is PointWidth = 30.

#### Option: Smoothness = `[n]`

- This option determines the number of interpolation points between the sample points determined by the Grid option. Admissible values for `n` are integers between 0 and 20; the default is Smoothness = `[0]`. Lines are depicted as linear segments connecting these interpolation points. Consequently, large values of `n` produce smooth lines.

#### Option: Style =

`value`

- This option sets the style in which curves are displayed. Admissible values are `[Points]`, `[Lines]`, `[LinesPoints]` and `[Impulses]`. The default is Style = `[Lines]`.
  - With Style = `[Points]`, only the sample points determined by the Grid option are displayed.
  - With Style = `[Lines]`, the curve is displayed as a collection of line segments connecting the sample points.
  - With Style = `[LinesPoints]`, both the sample points as well as the connecting line segments are displayed.
  - With Style = `[Impulses]`, the curve is displayed like a ``histogram'': vertical lines from the bottom of the scene to the sample points are drawn.

#### Option: Title =

`TitleString`

- This option adds the text given by the string `TitleString` to the object. The default is the empty string Title = , i.e., no title.

#### Option: TitlePosition = `[x, y]`

- This option determines the position of the object title. The parameters `x`, `y` must be numerical values between 0 and 10. The position `[0, 0]` denotes the upper left corner of the scene, the position `[10, 10]` denotes the lower right corner.

  Note that the specified positions are relative to the entire scene. Consequently, if titles are specified for several objects, their positions should differ to avoid overlap.

- Object titles can be moved interactively with the mouse to any appropriate position inside the scene.

#### Example 1

We plot a semi-circle of radius 1, parametrized by the polar angle u. The scene option Scaling = Constrained ensures that the circle is not deformed to an ellipse:

    >> plot2d(Scaling = Constrained, Labeling = TRUE,
              [Mode = Curve, [cos(u), sin(u)], u = [0, PI]])

#### Example 2

We define two point primitives, a line primitive and a filled polygon:

    >> point1 := point(1, 1, Color = RGB::Red):
       point2 := point(-1, 1, Color = RGB::Green):
       line := polygon(point(1, 0), point(0, 1), point(0, 0),
                       Color = RGB::Blue):
       triangle := polygon(point(0, 0), point(0, 1), point(-1, 0),
                           Closed = TRUE, Filled = TRUE,
                           Color = RGB::Antique):

These are combined to a graphical object:

    >> object := [Mode = List, [point1, point2, line, triangle]]:

Finally, this object is plotted:

    >> plot2d(BackGround = RGB::White, PointWidth = 50,
              PointStyle = FilledCircles, object)

    >> delete point1, point2, line, triangle, object:

#### Example 3

The graph of the sine function is diplayed using different styles:

    >> plot2d(BackGround = RGB::White, ForeGround = RGB::Black,
              Labeling = TRUE, PointWidth = 50,
              [Mode = Curve, [x, sin(10*x)], x = [0, 1],
               Color = [Flat, RGB::Red], Grid = [50], Smoothness = [0],
               PointStyle = FilledSquares, Style = [Points]
              ],
              [Mode = Curve, [x, 0.1 + sin(10*x)], x = [0, 1],
               Color = [Flat, RGB::Green],
               Grid = [20], Smoothness = [1],
               PointStyle = FilledCircles, Style = [LinesPoints]
              ],
              [Mode = Curve, [x, 0.2 + sin(10*x)], x = [0, 1],
               Color = [Flat, RGB::Blue], Grid = [100], Style = [Lines]
              ])

#### Example 4

We demonstrate the ViewingBox option.

    >> spiral := [Mode = Curve, [u*cos(u), u*sin(u)], u = [0, 2*PI],
                  Grid = [50]]:

First, this object is plotted without clipping:

    >> plot2d(Axes = Box, Labeling = TRUE, spiral)

In the next plot, the object is clipped to the horizontal range x = -4..1 and the vertical range y = -2..2:

    >> plot2d(Axes = Box, Labeling = TRUE,
              ViewingBox = [-4..1, -2..2], spiral)

    >> delete spiral:

#### Example 5

We demonstrate user-defined color functions. The following function produces admissible RGB-values between 0 and 1 for objects with coordinates from the range x=0..1 and y=0..1:

    >> myColor := (x, y) -> [x, 0.5 + abs(x - y)/(1 + x + y), y]:

The unit square is to be colored by the function above. We cover the square by 2*n^2 triangles, each of which is displayed with a flat color determined by `myColor`:

    >> n :=  30:
       plot2d([Mode = List,
               [polygon(point((i-1)/n, (j-1)/n),
                        point((i-1)/n,   j  /n),
                        point(  i  /n,   j  /n),
                        Filled = TRUE
                        ) $ i = 1..n $ j = 1..n,
                polygon(point((i-1)/n, (j-1)/n),
                        point(  i  /n, (j-1)/n),
                        point(  i  /n,   j  /n),
                        Filled = TRUE
                        ) $ i = 1..n $ j = 1..n
               ],
               Color = [Function, myColor]
              ]):

    >> delete myColor, n:

#### Changes

- The new scene options Discont, GridLines, GridLinesColor, GridLinesStyle, GridLinesWidth, RealValuesOnly and ViewingBox were introduced. The functionality of the scene option Ticks was extended.
- The default values of various options were changed.
- Scene titles as well as object titles can now be moved interactively by the mouse.

Do you have questions or comments?
Copyright © SciFace Software GmbH & Co. KG 2000