## `plot::Ellipse2d` -- graphical primitive for a two-dimensional ellipse

#### Introduction

`plot::Ellipse2d``(p, l1, l2)` represents a plot of a two-dimensional ellipse with center point p = (px; py) and semi-axes of lengths l1 and l2.

#### Creating Elements

`plot::Ellipse2d(m, l1, l2 <, option1, option2...>)`
`plot::Ellipse2d(p, l1, l2 <, option1, option2...>)`

#### Parameters

`m` | - | a list of two arithmetical expressions
`p` | - | a two-dimensional point, i.e., an object of the domain `plot::Point` or `DOM_POINT`
`l1, l2` | - | arithmetical expressions
`option1, option2, ...` | - | plot option(s) of the form `OptionName = value`

#### Related Domains

`plot::Point`, `plot::Rectangle2d`, `plot::Scene`, `RGB`

#### Related Functions

`plot`, `plot2d`, `plot::copy`

#### Details

- Objects generated by `plot::Ellipse2d` represent graphical primitives for two-dimensional ellipses that can be displayed via the call `plot`, or used with other graphical primitives of the `plot` library. See example 1.
- If the first parameter of the call of `plot::Ellipse2d` is a point `p`, then it is converted into a list containing the two coordinates of `p`. Specified plot options for `p` are ignored! (Cf. example 2.)
- An object of `plot::Ellipse2d` has the type `"graphprim"`, i.e., if `o` is such an object, then the result of `type(o)` is the string `"graphprim"`.
- Options `option1`, `option2`... 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]` | `[Flat, RGB::Red]`
  Filled | `TRUE`, `FALSE` | `FALSE`
  Grid | `[n]` | `[100]`
  LineStyle | SolidLines, DashedLines | SolidLines
  LineWidth | positive integers | `1`
  PointStyle | Circles, FilledCircles, FilledSquares, Squares | FilledSquares
  PointWidth | positive integers | `30`
  Smoothness | `[n]` | `[0]`
  Style | `[Points]`, `[Lines]`, `[LinesPoints]`, `[Impulses]` | `[Lines]`
  Title | strings |
  TitlePosition | `[x, y]` |

  See `plot2d` for further details on each option, except of the option Filled, which is described in detail below.

- Scene options for the parameters `option1`, `option2`... are not allowed! One may pass scene options to the call of `plot`, or use `plot::Scene` to create an object representing a graphical scene. Cf. example 1.

- A so-called attribute of a graphical primitive is a named entry of the object which can be accessed via the slot operator `::`.

  Each attribute has the property ``read'', i.e., the value of an attribute `attr` of a graphical primitive `o` can be read with `o::attr`. If the attribute also has the ``write'' property, then the value of the attribute can be changed with `o::attr := new_value`.

  The following attributes are available for an ellipse primitive:

  attribute | meaning | properties
  `center` | A list of two arithmetical expressions describing the center point of the ellipse. The initial value is the parameter `m`, or the list of the coordinates of `p`, respectively. | read/write
  `options` | A table of plot options of the ellipse primitive. Note that if you change the value of this attribute, the entries of the assigned table are not checked to be valid plot options for ellipse primitives. Invalid entries lead to runtime errors. The initial value of this attribute is the table stored under the domain entry `"defaultOptions"`, where such options are replaced and added, respectively, which are given with the parameters `option1`, `option2`... of the creating call. | read/write
  `plotdata` | List of the plot data of the ellipse primitive in a `plot2d` conforming syntax (see the method `"getPlotdata"` below). Note that the value of this attribute should only be used if the attribute `refreshPlotdata` has the value `FALSE` (see below). | read
  `radius1` | The length of the first semi-axis (an arithmetical expression). The initial value is the parameter `l1`. | read/write
  `radius2` | The length of the second semi-axis (an arithmetical expression). The initial value is the parameter `l2`. | read/write
  `range` | A range of the form `a..b` specifying the range of the parameter of the ellipse in parametrized form. `a` and `b` must be arithmetical expressions. The initial value is `0..2*PI`. Cf. example 3. | read/write
  `refreshPlotdata` | A boolean value which signals whether the plot data of the ellipse primitive must be (re-)build with the method `"getPlotdata"` (see below). If its value is `FALSE`, then the plot data of the ellipse is stored in the attribute `plotdata`. The initial value is `TRUE`. | read/write

  See the examples 2 and 3.

#### Option: Filled =

`value`

- With Filled = `TRUE` the ellipse is filled with the color specified with the option Color.

  In this case, the ellipse is approximated by a (filled) polygon. The number of the vertices of the polygon is the value `n` of the option Grid(see the table of options above).

  Note that drawing a filled polygon with more than three vertices is quite time consuming in MuPAD!

  The default is Filled = `FALSE`.

#### Operands

An object of `plot::Ellipse2d` consists of the three operands `m`, `l1` and `l2`.

#### Important Operations

Operands of an ellipse primitive can be accessed either using the system function `op`, the index operator `[ ]`, or using some attributes described above. For example, if `ellipse` is such an object, then the calls `op(ellipse,1)`, `ellipse[1]` and `ellipse::center` return the center point of the ellipse.

Via `ellipse[1] := new_point` or `ellipse::center := new_point`, the center point of an ellipse can be changed.

See the methods `"op"`, `"_index"`, `"set_index"` and `"slot"` below.

Use the slot operator `::` to get or set plot options of such objects afterwards, i.e., when they have been created. For example, if `ellipse` is such an object, then `ellipse::Color := RGB::Red` changes the color of `ellipse` to red.

#### Result of Evaluation

Evaluating an object of type `plot::Ellipse2d` returns itself.

#### Function Call

Calling an object of `plot::Ellipse2d` as a function yields the object itself, regardless of the arguments. The arguments are not evaluated.

#### Entries

defaultOptions

  is a table of plot options for ellipse primitives and their default values. Each entry has the form `OptionName = default_value`.

  When an object of the domain `plot::Ellipse2d` is created, then a copy of this table is stored under the attribute `options` (see the table of attributes above), where those options are added and replaced, respectively, which are given by the (optional) parameters `option1`, `option2`... of the creating call (see ``Creating Elements'' above).

  Plot options, which are not contained in the table stored under the attribute `options` will not be included in the plot data of the object created by the method `"getPlotdata"` (see below).

  For those options, the corresponding default value either is set by a graphical scene, if the option also exists as a scene option (such as the option PointWidth), or it is internally set by the function `plot2d` which is used to plot the object. See the table of plot options above, which gives a summary of the available plot options for curve primitives and their default values.

  To change the default value of some plot options, the option name and its default value may be added to the table `"defaultOptions"`, or replaced by a new value, respectively.

optionNames

  is a set of the available option names for plots of two-dimensional ellipses.

#### Method _index: indexed access to the operands of an ellipse primitive

- `_index(dom ellipse, positive integer i)`
- - Returns the `i`th operand of `ellipse`. See ``Operands'' above for a description of the operands of `ellipse`. If `i` is greater than 3, then `FAIL` is returned.
  - This method overloads the system function `_index`, i.e., one may use it in the form `ellipse[i]`, or in functional notation `_index(ellipse, i)`.

#### Method dimension: dimension of an ellipse primitive

- `dimension(dom ellipse)`
- - Returns the integer 2.

#### Method getPlotdata: create the plot data of an ellipse primitive

- `getPlotdata(dom ellipse)`
- - Returns a list of an inner list, where the inner list is a plot description of `ellipse` in a `plot2d` conforming syntax. If the option Filled of `ellipse` is set to `FALSE`, then the plot description has the form `[Mode = Curve, [...], ...]`. Otherwise, it has the form `[Mode = List, [polygon(...)], ...]`.

    For example, with `s := plot::Ellipse2d::getPlotdata(ellipse)` the call `plot2d(s[1])` gives a plot of `ellipse`.

  - Only those plot options will be included in the plot data of the ellipse, that are contained in the table stored under the attribute `options` (see the table of attributes above). For any other plot option not contained in this table, the corresponding default value set by the function `plot2d` for curves is used when plotting the object.
  - The result is stored as the value of the attribute `plotdata` of `ellipse`.
  - A call of this method sets the value of the attribute `refreshPlotdata` of `ellipse` to `FALSE`.
  - This method is called from `plot::Scene` to build the plot data of the graphical scene.

#### Method nops: number of operands of an ellipse primitive

- `nops(dom ellipse)`
- - Returns the integer 3.
  - This method overloads the system function `nops`, i.e., one may use it in the form `nops(ellipse)`.

#### Method op: extract operands of an ellipse primitive

- `op(dom ellipse, positive integer i)`
- - Returns the `i`th operand of `ellipse`. See ``Operands'' above for a description of the operands of `ellipse`. If `i` is greater than 3, then `FAIL` is returned.
  - This method overloads the system function `op`, i.e., one may use it in the form `op(ellipse, i)`.

#### Method set_index: set operands of an ellipse primitive

- `set_index(dom ellipse, positive integer i, any val)`
- - Reset the `i`th operand of `ellipse` to the value `val`. See ``Operands'' above for a description of the operands of `ellipse`.
  - If `i` is greater than 3, or if `val` is not an admissible value for the `i`th operand, then a warning message is issued. In this case the call of this method has no effect on the object `ellipse`.
  - A call of this method sets the value of the attribute `refreshPlotdata` of `ellipse` to `TRUE`.

#### Method slot: read and write attributes and plot options

- `slot(dom ellipse, string slotname)`
- - Reads the value of the slot `slotname` of `ellipse`. `slotname` may either be the name of an attribute or the name of a plot option. See the tables of available plot options and attributes above.
  - If `slotname` is the name of a plot option, but the option is not contained in the table stored under the attribute `options`, then `FAIL` is returned.

    If `slotname` is an invalid attribute or option, then an error message is issued.

  - This method overloads the system function `slot`, i.e., one may use it in the form `ellipse::slotname_id` (here, `slotname_id` must be the identifier corresponding to the string `slotname`), or in functional notation `slot(ellipse, slotname)`.
- `slot(dom ellipse, string slotname, any val)`
- - Changes the value of the attribute or option with the name `slotname` to the value `val`. See the Details above for existing attributes and options of an ellipse primitive.
  - If there is no attribute or option with the name `slotname`, or if `val` is not an admissible value for `slotname`, then a warning message is issued. In this case, the value of `slotname` remains unchanged.
  - This method overloads the system function `slot`, i.e., one may use it in the form `ellipse::slotname_id := val` (here, `slotname_id` must be the identifier corresponding to the string `slotname`), or in functional notation `slot(ellipse, slotname, val)`.
  - The value of the attribute `refreshPlotdata` of `ellipse` is set to `TRUE`.

#### Method checkOption: check a plot option

- `checkOption(equation OptionName = value)`
- - This method checks whether `OptionName` is an available plot option for ellipse primitives (see the table of available plot options above), and `value` is an admissible value for this option.
  - If both is correct, then the list `[TRUE, OptionName, newValue]` is returned. Note that the value of the option could have been converted into an admissible format. Thus, `newValue` must be used as the value of the option `OptionName` instead of `value`.
  - Otherwise, the list `[FALSE, error_msg]` is returned. The string `error_msg` is a description of the located problem, which can be passed, for example, to the system function `error` to raise a user-specified exception.

#### Method copy: create a copy of an ellipse primitive

- `copy(dom ellipse)`
- - Returns a copy of the object `ellipse`.
  - This method is called from the function `plot::copy`. See its help page for details.

#### Method modify: modify a copy of an ellipse primitive

- `modify(dom ellipse, equation(s) Name1 = value1...)`
- - Creates a copy of the object `ellipse` and changes the slots `Name1`... of this copy to the new values `value1`...
  - The identifiers `Name1`... must be names of attributes or plot options of the domain `plot::Ellipse2d`. Otherwise a warning message is issued, and the slot remains unchanged. Also, if one of the values `value1`... is not an admissible value for the corresponding attribute or plot option, respectively, the change of the slot is ignored.

    See the tables of available options and attributes above.

  - A call of this method sets the value of the attribute `refreshPlotdata` of the copy of `ellipse` to `TRUE`.
  - This method is called from the function `plot::modify`.

#### Method print: print an ellipse primitive

- `print(dom ellipse)`
- - This method returns an unevaluated expression of the form `plot::Ellipse2d(p, l1, l2`. It is used to print objects of `plot::Ellipse2d` to the screen.
  - See the system function `print` for details.

#### Example 1

We create a plot of an ellipse with center point (1;2) and semi-axes of length 3 and 4:

    >> ellipse := plot::Ellipse2d([1, 2], 3, 4)

                           plot::Ellipse2d([1, 2], 3, 4)

The center point can also be an object of the domain `plot::Point`. The following example creates the unit circle around the point (-1; -1), filled with green color:

    >> circle := plot::Ellipse2d(
         plot::Point(-1, -1), 1, 1, Filled = TRUE, Color = RGB::Green
       )

                          plot::Ellipse2d([-1, -1], 1, 1)

We plot these two objects in a graphical scene, where the scaling of the plot is changed to be constrained:

    >> plot(ellipse, circle, Scaling = Constrained)

#### Example 2

The attribute `center`, which specifies the center point of the ellipse, is a list of two arithmetical expressions. This is also the case if the center point of the created object was given as an object of the domain `plot::Point` or `DOM_POINT`:

    >> c := plot::Point([-1, 1]):
       ellipse := plot::Ellipse2d(c, 2, -2):
       ellipse::center

                                      [-1, 1]

If you replace the value of the attribute `center`, then the point must be given as a list of two arithmetical expressions, otherwise a warning message is issued:

    >> ellipse::center:= point(0, 0)

          Warning: attribute 'center': expecting a list of two arithmeti\
          cal expressions; assignment ignored [plot::Ellipse2d::slot]

                                    point(0, 0)

    >> ellipse::center

                                      [-1, 1]

Note that if you specify an object of the domain `plot::Point` or `DOM_POINT` as the center point of the ellipse, then plot options of the point are ignored. For example, if we change the color of the point `c` created above to blue and create a new ellipse:

    >> c::Color := RGB::Blue: ellipse := plot::Ellipse2d(c, 1, 1):
       plot(ellipse)

then the ellipse is still drawn in red color (the default color of objects of the domain `plot::Ellipse2d`). You must use the color option of the object `ellipse` to change the color of the object:

    >> ellipse::Color := RGB::Blue: plot(ellipse)

#### Example 3

The value of the attribute `range` specifies the range of the parameter of the ellipse in parametrized form. For example, if we create a plot of the unit circle arount the point (0; 0):

    >> circle := plot::Ellipse2d([0, 0], 1, 1)

                           plot::Ellipse2d([0, 0], 1, 1)

and restrict the parameter of the circle to the interval [0, PI], we get the following plot:

    >> circle::range := 0..PI: plot(circle)

See the help page of `plot::Curve2d` for more examples for working with attributes of graphical primitives.

#### Changes

- new function

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