2.4.2.5 Polygon

The polygon object is useful for creating rectangles, squares and other planar shapes with more than three edges. Their syntax is:

POLYGON:
    polygon
    {
        Number_Of_Points, <Point_1> <Point_2>... <Point_n>
        [OBJECT_MODIFIER...]
    }

The float Number_Of_Points tells how many points are used to define the polygon. The points <Point_1> through <Point_n> describe the polygon or polygons. A polygon can contain any number of sub-polygons, either overlapping or not. In places where an even number of polygons overlaps a hole appears. When you repeat the first point of a sub-polygon, it closes it and starts a new sub-polygon's point sequence. This means that all points of a sub-polygon are different.

If the last sub-polygon is not closed a warning is issued and the program automatically closes the polygon. This is useful because polygons imported from other programs may not be closed, i.e. their first and last point are not the same.

All points of a polygon are three-dimensional vectors that have to lay on the same plane. If this is not the case an error occurs. It is common to use two-dimensional vectors to describe the polygon. POV-Ray assumes that the z value is zero in this case.

A square polygon that matches the default planar image map is simply:

  polygon {
    4,
    <0, 0>, <0, 1>, <1, 1>, <1, 0>
    texture {
      finish { ambient 1 diffuse 0 }
      pigment { image_map { gif "test.gif"  } }
    }
    //scale and rotate as needed here
  }

The sub-polygon feature can be used to generate complex shapes like the letter "P", where a hole is cut into another polygon:

  #declare P = polygon {
    12,
    <0, 0>, <0, 6>, <4, 6>, <4, 3>, <1, 3>, <1,0>, <0, 0>, 
    <1, 4>, <1, 5>, <3, 5>, <3, 4>, <1, 4>
  }

The first sub-polygon (on the first line) describes the outer shape of the letter "P". The second sub-polygon (on the second line) describes the rectangular hole that is cut in the top of the letter "P". Both rectangles are closed, i.e. their first and last points are the same.

The feature of cutting holes into a polygon is based on the polygon inside/outside test used. A point is considered to be inside a polygon if a straight line drawn from this point in an arbitrary direction crosses an odd number of edges (this is known as Jordan's curve theorem).

Another very complex example showing one large triangle with three small holes and three separate, small triangles is given below:

  polygon {
    28,
    <0, 0> <1, 0> <0, 1> <0, 0>          // large outer triangle
    <.3, .7> <.4, .7> <.3, .8> <.3, .7>  // small outer triangle #1
    <.5, .5> <.6, .5> <.5, .6> <.5, .5>  // small outer triangle #2
    <.7, .3> <.8, .3> <.7, .4> <.7, .3>  // small outer triangle #3
    <.5, .2> <.6, .2> <.5, .3> <.5, .2>  // inner triangle #1
    <.2, .5> <.3, .5> <.2, .6> <.2, .5>  // inner triangle #2
    <.1, .1> <.2, .1> <.1, .2> <.1, .1>  // inner triangle #3
  }