Section 7.5.3.4
Polygon

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

polygon { TOTAL_NUMBER_OF_POINTS, <A_1>, <A_2>, ..., <A_na>, <A_1>, <B_1>, <B_2>, ..., <B_nb>, <B_1>, <C_1>, <C_2>, ..., <C_nc>, <C_1>, ... }

The points <A_1> through <A_na> describe the first sub-polygon, the points <B_1> through <B_nb> describe the second sub-polygon, and so on. 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. You only have to be sure that each of these polygons is closed. This is insured by repeating the first point of a sub-polygon at the end of the sub-polygon's point sequence. This implies 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 one plane. If this is not the case an error occurs. You can also 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 imagemap 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 }

Section 7.5.3.5
Triangle and Smooth Triangle

The triangle primitive is available in order to make more complex objects than the built-in shapes will permit. Triangles are usually not created by hand but are converted from other files or generated by utilities. A triangle is defined by

triangle { <CORNER1>, <CORNER2>, <CORNER3> }

where <CORNERn> is a vector defining the x, y, z coordinates of each corner of the triangle.

Because triangles are perfectly flat surfaces it would require extremely large numbers of very small triangles to approximate a smooth, curved surface. However much of our perception of smooth surfaces is dependent upon the way light and shading is done. By artificially modifying the surface normals we can simulate as smooth surface and hide the sharp-edged seams between individual triangles.

The smooth triangle primitive is used for just such purposes. The smooth triangles use a formula called Phong normal interpolation to calculate the surface normal for any point on the triangle based on normal vectors which you define for the three corners. This makes the triangle appear to be a smooth curved surface. A smooth triangle is defined by

smooth_triangle { <CORNER1>, <NORMAL1>, <CORNER2>, <NORMAL2>, <CORNER3>, <NORMAL3> }

where the corners are defined as in regular triangles and < NORMALn> is a vector describing the direction of the surface normal at each corner.

These normal vectors are prohibitively difficult to compute by hand. Therefore smooth triangles are almost always generated by utility programs. To achieve smooth results, any triangles which share a common vertex should have the same normal vector at that vertex. Generally the smoothed normal should be the average of all the actual normals of the triangles which share that point.


Section 7.5.4
Infinite Solid Primitives

There are five polynomial primitive shapes that are possibly infinite and do not respond to automatic bounding. They are plane, cubic, poly, quadric and quartic. They do have a well defined inside and may be used in CSG and inside a clipped_by statement. As with all shapes they can be translated, rotated and scaled..

Section 7.5.4.1
Plane

The plane primitive is a simple way to define an infinite flat surface. The plane is specified as follows:

plane { <NORMAL>, DISTANCE }

The <NORMAL> vector defines the surface normal of the plane. A surface normal is a vector which points up from the surface at a 90 degree angle. This is followed by a float value that gives the distance along the normal that the plane is from the origin (that is only true if the normal vector has unit length; see below). For example:

plane { <0, 1, 0>, 4 }

This is a plane where straight up is defined in the positive y-direction. The plane is 4 units in that direction away from the origin. Because most planes are defined with surface normals in the direction of an axis you will often see planes defined using the x, y or z built-in vector identifiers. The example above could be specified as:

plane { y, 4 }

The plane extends infinitely in the x- and z-directions. It effectively divides the world into two pieces. By definition the normal vector points to the outside of the plane while any points away from the vector are defined as inside. This inside/outside distinction is only important when using planes in CSG and clipped_by.

A plane is called a polynomial shape because it is defined by a first order polynomial equation. Given a plane:

plane { <A, B, C>, D }

it can be represented by the equation

A*x + B*y + C*z - D*sqrt(A^2 + B^2 + C^2) = 0.

Therefore our example plane { y,4 } is actually the polynomial equation y=4. You can think of this as a set of all x, y, z points where all have y values equal to 4, regardless of the x or z values.

This equation is a first order polynomial because each term contains only single powers of x, y or z. A second order equation has terms like x^2, y^2, z^2, xy, xz and yz. Another name for a 2nd order equation is a quadric equation. Third order polys are called cubics. A 4th order equation is a quartic. Such shapes are described in the sections below.


Section 7.5.4.2
Poly, Cubic and Quartic

Higher order polynomial surfaces may be defined by the use of a poly shape. The syntax is

poly { ORDER, <T1, T2, T3, .... Tm> }

where ORDER is an integer number from 2 to 7 inclusively that specifies the order of the equation. T1, T2, ... Tm are float values for the coefficients of the equation. There are m such terms where

m = ((ORDER+1)*(ORDER+2)*(ORDER+3))/6.

An alternate way to specify 3rd order polys is:

cubic { <T1, T2,... T20> }

Also 4th order equations may be specified with:

quartic { <T1, T2,... T35> }

Here's a more mathematical description of quartics for those who are interested. Quartic surfaces are 4th order surfaces and can be used to describe a large class of shapes including the torus, the lemniscate, etc. The general equation for a quartic equation in three variables is (hold onto your hat):

  a00 x^4 + a01 x^3 y + a02 x^3 z+ a03 x^3 + a04 x^2 y^2+
  a05 x^2 y z+ a06 x^2 y + a07 x^2 z^2+a08 x^2 z+a09 x^2+
  a10 x y^3+a11 x y^2 z+ a12 x y^2+a13 x y z^2+a14 x y z+
  a15 x y + a16 x z^3 + a17 x z^2 + a18 x z + a19 x+
  a20 y^4 + a21 y^3 z + a22 y^3+ a23 y^2 z^2 +a24 y^2 z+
  a25 y^2 + a26 y z^3 + a27 y z^2 + a28 y z + a29 y+
  a30 z^4 + a31 z^3 + a32 z^2 + a33 z + a34 = 0

To declare a quartic surface requires that each of the coefficients (a0 ... a34) be placed in order into a single long vector of 35 terms.

As an example let's define a torus the hard way. A Torus can be represented by the equation:

 x^4 + y^4 + z^4 + 2 x^2 y^2 + 2 x^2 z^2 + 2 y^2 z^2 -
 2 (r_0^2 + r_1^2) x^2 + 2 (r_0^2 - r_1^2) y^2 -
 2 (r_0^2 + r_1^2) z^2 + (r_0^2 - r_1^2)^2 = 0

Where r_0 is the major radius of the torus, the distance from the hole of the donut to the middle of the ring of the donut, and r_1 is the minor radius of the torus, the distance from the middle of the ring of the donut to the outer surface. The following object declaration is for a torus having major radius 6.3 minor radius 3.5 (Making the maximum width just under 20).

// Torus having major radius sqrt(40), minor radius sqrt(12) quartic { < 1, 0, 0, 0, 2, 0, 0, 2, 0, -104, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 1, 0, 0, 2, 0, 56, 0, 0, 0, 0, 1, 0, -104, 0, 784 > sturm bounded_by { // bounded_by speeds up the render, // see bounded_by // explanation later // in docs for more info. sphere { <0, 0, 0>, 10 } } }

Poly, cubic and quartics are just like quadrics in that you don't have to understand what one is to use one. The file shapesq.inc has plenty of pre-defined quartics for you to play with. The syntax for using a pre-defined quartic is:

object { Quartic_Name }

Polys use highly complex computations and will not always render perfectly. If the surface is not smooth, has dropouts, or extra random pixels, try using the optional keyword sturm in the definition. This will cause a slower but more accurate calculation method to be used. Usually, but not always, this will solve the problem. If sturm doesn't work, try rotating or translating the shape by some small amount. See the sub-directory math in the scene files directory for examples of polys in scenes.

There are really so many different quartic shapes, we can't even begin to list or describe them all. If you are interested and mathematically inclined, an excellent reference book for curves and surfaces where you'll find more quartic shape formulas is:

  "The CRC Handbook of Mathematical Curves and Surfaces"
  David von Seggern
  CRC Press, 1990

Section 7.5.4.3
Quadric

Quadric surfaces can produce shapes like ellipsoids, spheres, cones, cylinders, paraboloids (dish shapes) and hyperboloids (saddle or hourglass shapes). Note that you do not confuse quaDRic with quaRTic. A quadric is a 2nd order polynomial while a quartic is 4th order. Quadrics render much faster and are less error-prone.

A quadric is defined in POV-Ray by

quadric { <A,B,C>, <D,E,F>, <G,H,I>, J }

where A through J are float expressions that define a surface of x, y, z points which satisfy the equation

  A x^2   + B y^2   + C z^2 +
  D xy    + E xz    + F yz +
  G x     + H y     + I z    + J = 0

Different values of A, B, C, ... J will give different shapes. If you take any three dimensional point and use its x, y and z coordinates in the above equation the answer will be 0 if the point is on the surface of the object. The answer will be negative if the point is inside the object and positive if the point is outside the object. Here are some examples:

  X^2 + Y^2 + Z^2 - 1 = 0  Sphere
  X^2 + Y^2 - 1 = 0        Infinite cylinder along the Z axis
  X^2 + Y^2 - Z^2 = 0      Infinite cone along the Z axis

The easiest way to use these shapes is to include the standard file shapes.inc into your program. It contains several pre-defined quadrics and you can transform these pre-defined shapes (using translate, rotate and scale) into the ones you want. You can invoke them by using the syntax:

object { Quadric_Name }

The pre-defined quadrics are centered about the origin < 0,0,0> and have a radius of 1. Don't confuse radius with width. The radius is half the diameter or width making the standard quadrics 2 units wide.

Some of the pre-defined quadrics are,

  Ellipsoid
  Cylinder_X, Cylinder_Y, Cylinder_Z
  QCone_X, QCone_Y, QCone_Z
  Paraboloid_X, Paraboloid_Y, Paraboloid_Z

For a complete list, see the file shapes.inc.


Section 7.5.5
Constructive Solid Geometry

POV-Ray supports Constructive Solid Geometry (CSG) with five different operations: difference, intersection, merge, union and negation (inversion). While the first four operations represent binary operators, i. e. they need two arguments, the negation is a unary operator, it takes only one argument.

Section 7.5.5.1
About CSG

Constructive Solid Geometry is a technique for combining two or more objects to create a new object using the three boolean set operators union, intersection, and negation. It only works with solid objects, i. e. objects that have a well-defined interior. This is the case for all objects described in the sections "Finite Solid Primitives" and "Infinite Solid Primitives".

CSG shapes may be used anywhere a standard shape can be used, even inside other CSG shapes. They can be translated, rotated or scaled in the same way as any other shape. The shapes making up the CSG shape may be individually translated, rotated and scaled as well.


Section 7.5.5.2
Inside and Outside

Most shape primitives, like spheres, boxes and blobs divide the world into two regions. One region is inside the object and one is outside.

Given any point in space you can say it's either inside or outside any particular primitive object. Well, it could be exactly on the surface but this case is rather hard to determine due to numerical problems.

Even planes have an inside and an outside. By definition, the surface normal of the plane points towards the outside of the plane. You should note that triangles and triangle-based shapes cannot be used as solid objects in CSG since they have no well defined inside and outside.

CSG uses the concepts of inside and outside to combine shapes together as explained in the following sections.

Imagine you have to objects that partially overlap like shown in the figure below. Four different areas of points can be distinguished: points that are neither in object A nor in object B, points that are in object A but not in object B, points that are not in object A but in object B and last not least points that are in object A and object B.


Two overlapping objects.

Keeping this in mind it will be quite easy to understand how the CSG operations work.


Next Section
Table Of Contents