## `polygon` -- generate a graphical polygon primitive

#### Introduction

`polygon(`p1, p2, ...`)` defines a polygon with vertices `p1`, `p2` etc.

#### Call(s)

`polygon(p1, p2, ... <, Closed = b1> <, Filled = b2> <, Color = [r, g, b]>)`

#### Parameters

`p1, p2, ...` | - | graphical points created by the function `point`. A 2D polygon is created if all points are 2D points. 3D points create a 3D polygon.

#### Options

`Closed` = b1 | - | `b1` may be either `TRUE` or `FALSE`. If `TRUE`, the first point `p1` is internally appended to the points, thus creating a closed polygon. The default is `Closed = FALSE`.
`Filled` = b2 | - | `b2` may be either `TRUE` or `FALSE`. If `FALSE`, the polygon is a curve consisting of line segments. If `TRUE`, the polygon is rendered as a filled area. The default is `Filled = FALSE`.
`Color =` [r, g, b] | - | sets an RGB color given by the amount of red, green and blue. The parameters `r`, `g`, `b` must be real numbers between 0 and 1.

#### Returns

an object of domain type `DOM_POLYGON`.

#### Related Functions

`plot`, `plot::Polygon`, `plot2d`, `plot3d`, `plotfunc2d`, `plotfunc3d`, `point`, `RGB`

#### Details

- Polygons generated by `polygon` represent graphical primitives that can be displayed via `plot2d` or `plot3d` using the list format `[Mode = List, [..primitives..]]`.
- The `plot` library provides the alternative primitive `plot::Polygon`. This object is more flexible than the kernel object generated by `polygon`. The first can be used with all functions of the `plot` library, whereas the latter can only be used in a call to `plot2d` or `plot3d`.
- `polygon` is a function of the system kernel.

#### Option: Filled = `b2`

- With `Filled = TRUE` a closed polygon is created, i.e., the first point `p1` is appended to the points. The plot functions render the polygon as a filled area.
- If `Closed = FALSE`, the edges of the polygon are rendered with the same color as the interior. If `Closed = TRUE`, the edges are rendered in the foreground color of the scene.

- Filled 3D polygons may not consist of more than three points (triangles). Use `plot::Polygon` to generate more complex filled 3D polygons.

#### Option: Color = `[r, g, b]`

- The color values `r`, `g`, `b` must be numerical expressions that can be converted to real floating point numbers from the interval [0.0, 1.0]. An error occurs if any of these values is not in this range. Symbolic expressions such as `PI - 2`, `exp(-sqrt(2))` etc. are accepted. Note, however, that expressions involving symbolic identifiers are not accepted!
- Point colors may be specified in the definition of the vertices via the function `point`. These colors are ignored.
- The domain `RGB` contains many pre-defined colors.

#### Operands

The first operands of a polygon are the vertices as specified in the generating call to `polygon`. The third but last operand is the list `[r, g, b]` defining the polygon color. This operand is `NIL`, if no color was specified. The second but last operand is the Boolean `b1` corresponding to `Closed = b1`. The last operand is the Boolean `b2` corresponding to `Filled = b2`.

#### Example 1

We define the vertices of a 2D triangle:

    >> p1 := point(0, 0): p2 := point(0, 1): p3 := point(1, 0):

We use `plot2d` to render the edges of the triangle:

    >> plot2d(Axes = None, [Mode = List,
              [polygon(p1, p2, p3, Closed = TRUE, Color = RGB::Black)]
              ])

The following command renders the triangle area:

    >> plot2d(Axes = None, [Mode = List,
              [polygon(p1, p2, p3, Filled = TRUE, Color = RGB::Red)]])

The following command renders the triangle area and the edges:

    >> plot2d(Axes = None, [Mode = List,
              [polygon(p1, p2, p3, Closed = TRUE, Filled = TRUE,
               Color = RGB::Red)]])

    >> delete p1, p2, p3:

#### Example 2

We define 2D points on the graph of the cosine function:

    >> for i from 0 to 12 do
         p[i] := point(i, cos(i*PI/6)):
       end_for:

These points are used to build a polygon:

    >> plot2d(Scaling = UnConstrained,
              [Mode = List, [polygon(p[i] $ i = 0..12)]])

The following command plots the area between the graph of the cosine function and the x-axis:

    >> plot2d(Scaling = UnConstrained, [Mode = List,
               [polygon(point(0, 0), p[i] $ i = 0..12, point(12, 0),
                        Closed = TRUE, Filled = TRUE)]])

The following command plots splits the area between the graph of the cosine function and the x-axis into trapezoids. The trapezoids are plotted as a list of filled polygons:

    >> plot2d(Scaling = UnConstrained, [Mode = List,
               [polygon(point(i, 0), p[i], p[i+1], point(i + 1, 0),
                        Closed = TRUE, Filled = TRUE) $ i = 0..11]])

    >> delete p:

#### Example 3

We define the vertices of a 3D triangle:

    >> a := point(0, 0, 1): b := point(1, 1, 1): c := point(1, 0, 1):

We render the triangle in various modes:

    >> plot3d(Axes = None, [Mode = List, [polygon(a, b, c)] ])

    >> plot3d(Axes = None,
              [Mode = List, [polygon(a, b, c, Closed = TRUE)]])

    >> plot3d(Axes = None,
              [Mode = List, [polygon(a, b, c, Filled = TRUE)]])

    >> plot3d(Axes = None, [Mode = List,
              [polygon(a, b, c, Closed = TRUE, Filled = TRUE)]])

    >> plot3d(Axes = None, LineWidth = 30, [Mode = List,
              [polygon(a, b, c, Closed = TRUE, Filled = TRUE)]])

    >> delete a, b, c:

#### Changes

- no changes

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