This function takes a description of a flat polygon in x, y and z coordinates,
and draws it in three dimensions.

```
polygon3d(x, y = NULL, z = NULL, fill = TRUE, plot = TRUE,
coords, random = TRUE, ...)
```

## Arguments

- x, y, z
Vertices of the polygon in a form accepted by `xyz.coords`

.

- fill
logical; should the polygon be filled?

- plot
logical; should the polygon be displayed?

- coords
Which two coordinates (`x = 1`

, `y = 2`

, `z = 3`

) describe the
polygon. If missing, `triangulate`

makes
an automatic choice.

- random
Should a random triangulation be used?

- ...
Other parameters to pass to `lines3d`

or `shade3d`

if `plot = TRUE`

.

## Details

The function triangulates the two dimensional polygon described by `coords`

, then
applies the triangulation to all three coordinates. No check is made that the polygon
is actually all in one plane, but the results may be somewhat unpredictable
(especially if `random = TRUE`

) if it is not.

Polygons need not be simple; use `NA`

to indicate separate closed pieces. For
`fill = FALSE`

there are no other restrictions on the pieces, but for
`fill = TRUE`

the resulting two-dimensional polygon needs to be one that
`triangulate`

can handle.

## Value

If `plot = TRUE`

, the id number of the lines (for `fill = FALSE`

) or triangles
(for `fill = TRUE`

) that have been plotted.

If `plot = FALSE`

, then for `fill = FALSE`

, a vector of indices into
the XYZ matrix that could be used to draw the polygon. For `fill = TRUE`

,
a triangular mesh object representing the triangulation.

## Examples

```
theta <- seq(0, 4*pi, length.out = 50)
r <- theta + 1
r <- c(r[-50], rev(theta*0.8) + 1)
theta <- c(theta[-50], rev(theta))
x <- r*cos(theta)
y <- r*sin(theta)
open3d()
plot(x, y, type = "n")
polygon(x, y)
polygon3d(x, y, x + y, col = "blue")
```