## `plot::Polygon` -- graphical primitive for a polygon

#### Introduction

`plot::Polygon``(p1, p2...)` represents a plot of a polygon build of the points p1, p2, ..., where the points must either be of dimension two or three.

#### Creating Elements

`plot::Polygon(p1, p2... <, option1, option2...>)`

#### Parameters

`p1, p2` | - | plot points, i.e., objects that can be converted into the domain `plot::Point`; the points must have the same dimension
`option1, option2, ...` | - | plot option(s) of the form `OptionName = value`

#### Related Domains

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

#### Related Functions

`plot`, `plot2d`, `plot3d`, `plot::copy`, `plot::line`, `polygon`

#### Details

- Objects generated by `plot::Polygon` represent graphical primitives for two- or three-dimensional polygons that can be displayed via the call `plot(...)`, or used with other graphical primitives of the `plot` library.
- An object of `plot::Polygon` has type `"graphprim"`, i.e., if `o` is such an object, then the result of `type(o)` is the string `"graphprim"`.
- Note that `plot::Polygon`, in difference to the standard graphical object `polygon`, allows to build a polygon of points of arbitrary arithmetical expressions. These expressions must evaluate to numbers at the time where you plot the polygon.
- Options `option1`, `option2`... are specified by equations `OptionName = value`. The following table gives an overview of the available options:

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

  See `plot2d` and `polygon` for further details on each option.

- 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.

- 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 a polygon primitive:

  attribute | meaning | properties
  `objects` | A list of the points of the polygon primitive. The initial value is the list `[p1, p2...]` of the parameters `p1`, `p2`..., where each parameter was converted into an object of the domain `plot::Point`. Note that if you extract an object of this list and do some changes on this object, then you must set the value of the attribute `refreshPlotdata` to `TRUE` in order to force a rebuild of the plot data of the polygon. | read/write
  `options` | A table of plot options of the polygon 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 polygon 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 polygon primitive in a `plot2d` and `plot3d` conforming syntax, respectively (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
  `refreshPlotdata` | A boolean value which signals whether the plot data of the polygon primitive must be (re-)build with the method `"getPlotdata"` (see below). If its value is `FALSE`, then the plot data of the polygon primitive is stored in the attribute `plotdata`. The initial value is `TRUE`. | read/write

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

#### Operands

The operands of an object of `plot::Polygon` are the points `p1`, `p2`... (in this order).

#### Important Operations

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

Via `polygon[1] := new_point` or `polygon::objects[1] := new_point`, the first point of `polygon` is replaced by `new_point`.

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 `polygon` is such an object, then `polygon::Color := RGB::Red` changes the color of each point of `polygon` to red.

#### Result of Evaluation

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

#### Function Call

Calling an object of `plot::Polygon` 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 polygon primitives and their default values. Each entry has the form `OptionName = default_value`.

  When an object of the domain `plot::Polygon` 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` and `plot3d`, respectively, which are used to plot the object. See the table of plot options above, which gives a summary of the available plot options for polygon 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 polygons.

#### Method _index: indexed access to the operands of a polygon primitive

- `_index(dom polygon, positive integer i)`
- - Returns the `i`th point of `polygon`. If `i` is greater than the number of points of `polygon`, then `FAIL` is returned.
  - This method overloads the system function `_index`, i.e., one may use it in the form `polygon[i]`, or in functional notation `_index(polygon, i)`.

#### Method dimension: dimension of a polygon primitive

- `dimension(dom polygon)`
- - Returns the integer 2 or 3.

#### Method getPlotdata: create the plot data of a polygon primitive

- `getPlotdata(dom polygon)`
- - Returns a list of an inner list, where the inner list is a plot description of `polygon` in a `plot2d` and `plot3d` conforming syntax, respectively, i.e., it has the form `[Mode = List, [polygon(...)], ...]`.

    For example, with `s := plot::Polygon::getPlotdata(polygon)` the call `plot2d(s[1])` and `plot3d(s[1])`, respectively, gives a plot of `polygon`.

  - Only those plot options will be included in the plot data of the point, 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` and `plot3d`, respectively, for lists of primitives is used when plotting the object.
  - The result is stored as the value of the attribute `plotdata` of `polygon`.
  - A call of this method sets the value of the attribute `refreshPlotdata` of `polygon` to `FALSE`.
  - This method is called from `plot::Scene` to build the plot data of the graphical scene.

#### Method nops: number of operands of a polygon primitive

- `nops(dom polygon)`
- - Returns the number of points of `polygon`.
  - This method overloads the system function `nops`, i.e., one may use it in the form `nops(polygon)`.

#### Method op: extract operands of a polygon primitive

- `op(dom polygon, positive integer i)`
- - Returns the `i`th point of `polygon`. If `i` is greater than the number of points of `polygon`, then `FAIL` is returned.
  - This method overloads the system function `op`, i.e., one may use it in the form `op(polygon, i)`.

#### Method set_index: set operands of a polygon primitive

- `set_index(dom polygon, positive integer i, plot::Point p)`
- - Replaces the `i`th point of `polygon` by the point `p`.
  - If `i` is greater than the number of points of `polygon`, or if `p` is not an object of the domain `plot::Point`, then a warning message is issued. In this case the call of this method has no effect on the object `polygon`.
  - A call of this method sets the value of the attribute `refreshPlotdata` of `point` to `TRUE`.

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

- `slot(dom polygon, string slotname)`
- - Reads the value of the slot `slotname` of `polygon`. `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 `polygon::slotname_id` (here, `slotname_id` must be the identifier corresponding to the string `slotname`), or in functional notation `slot(polygon, slotname)`.
- `slot(dom polygon, string slotname, any val)`
- - Changes the value of the attribute or option with the name `slotname` to the value `val`.
  - 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 `polygon::slotname_id := val` (here, `slotname_id` must be the identifier corresponding to the string `slotname`), or in functional notation `slot(polygon, slotname, val)`.
  - The value of the attribute `refreshPlotdata` of `polygon` is set to `TRUE`.

#### Method convert: conversion of objects into a polygon primitive

- `convert(any p)`
- - This method tries to convert `p` into an object of the domain `plot::Polygon`. If this is not possible, then `FAIL` is returned.
  - Currently this method only handles objects of the domain type `DOM_POLYGON`. If `p` does not have a color specification, then the default color for objects of `plot::Polygon` is used (see ``Details'' above).

#### Method convert_to: conversion of a polygon primitive

- `convert_to(dom polygon, domain T)`
- - This method tries to convert `polygon` into an object of the domain `T`. If this is not possible, then `FAIL` is returned.
  - Currently this method only implements the case where `T` is the domain `DOM_POLYGON`. The result is a system polygon primitive, i.e., an object of the domain `DOM_POLYGON`.

    Note that plot options can not be stored in such an object, except of the options Color, Filled and Closed. However, the color specifiaction is used only if it is contained in the attribute `options` of the polygon primitive `polygon` (see the table of attributes above). Otherwise the default color specification for system polygon primitives is used (see the help page of `DOM_POLYGON`).

#### Method expr: conversion into a system polygon primitive

- `expr(dom polygon)`
- - This method converts `polygon` into an object of the domain type `DOM_POLYGON`. See the method `"convert_to"` for details.

#### Method checkOption: check a plot option

- `checkOption(equation OptionName = value)`
- - This method checks whether `OptionName` is a known plot option for polygon 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 a polygon primitive

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

#### Method expose: expose the definition of a polygon

- `expose(dom polygon)`
- - This method returns a sequence of the points of `polygon`.
  - This method overloads the system function `expose`, i.e., you may use it in the form `expose(polygon)`.

#### Method modify: modify a copy of a polygon primitive

- `modify(dom polygon, equation(s) Name1 = value1...)`
- - Creates a copy of the object `polygon` 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::Polygon`. 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 `polygon` to `TRUE`.
  - This method is called from the function `plot::modify`.

#### Method print: print a polygon primitive

- `print(dom polygon)`
- - This method returns an unevaluated expression of the form `plot::Polygon()`. It is used to print objects of `plot::Polygon` to the screen.
  - Call `expose(polygon)` to expose the points of `polygon`.
  - See the system function `print` for details.

#### Example 1

We create a polygon build of the points (1;2), (10;2) and (10;10):

    >> p := plot::Polygon(
         plot::Point(1, 2), plot::Point(10, 2), plot::Point(10, 10)
       )

                                  plot::Polygon()

and plot the polygon in a graphical scene:

    >> plot(p)

Plot options may be specified as additional arguments. For example, to close the polygon created above, set the option Closed to the value `TRUE`:

    >> p := plot::Polygon(
         plot::Point(1, 2), plot::Point(10, 2), plot::Point(10, 10),
         Closed = TRUE
       ):
       plot(p)

You can also set plot options of an object of the domain `plot::Polygon` via the slot operator `::`. For example, to change the color of the polygon `p` into green and increase the width of the lines of the polygon, e.g., to the value 50, we enter:

    >> p::Color := RGB::Red: p::LineWidth:= 50:
       plot(p)

Scene options may be given to the call of `plot`, such as removing axes from the plot:

    >> plot(p, Axes = None)

#### Example 2

Objects of the domain `plot::Polygon`, and objects of the basic domain `DOM_POLYGON` are graphical primitives for two- or three dimensional polygons. The main difference between objects of these two domains is, that objects of `plot::Polygon` can be used together with other graphical primitives of the library `plot` such as function graphs, surface plots, point-list plots, and more.

To ease the use of such different objects, you can easily convert objects of one domain into the other. For example, an object of the domain `plot::Polygon` such as:

    >> p := plot::Polygon([1, 2], [2, 3], [0, 3], [-1,2])

                                  plot::Polygon()

can be converted into the domain `DOM_POLYGON` as follows:

    >> plot::Polygon::convert_to(p, DOM_POLYGON)

          polygon(point(1.0, 2.0), point(2.0, 3.0), point(0.0, 3.0), poi\
          nt(-1.0, 2.0))

Note that because objects of the domain `DOM_POLYGON` only know the plot options Color, Filled and Closed, any other plot option set for the object `p` is lost by this conversion.

With the method `"convert"`, objects can be converted into the domain `plot::Polygon`. For example, we convert the polygon `polygon(point(1, 2, 3), point(2, 4, 6))` into an object of the domain `plot::Polygon`:

    >> p := polygon(point(1, 2, 3), point(2, 4, 6)):
       q := plot::Polygon::convert(p)

                                  plot::Polygon()

One may now override default values of some plot options for the object `q` as follows:

    >> q::Color := RGB::Blue: q::LineWidth := 50:
       plot(q, Axes = None)

#### Changes

- new function

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