Section 7.5.3
Finite Patch Primitives

There are six totally thin, finite objects which have no well-defined inside. They are bicubic patch, disc, smooth triangle, triangle, polygon and mesh. They may be combined in CSG union but cannot be use in other types of CSG (or inside a clipped_by statement). Because these types are finite POV-Ray can use automatic bounding on them to speed up rendering time. As with all shapes they can be translated, rotated and scaled.

Bicubic Patch

A bicubic patch is a 3D curved surface created from a mesh of triangles. POV-Ray supports a type of bicubic patch called a Bezier patch. A bicubic patch is defined as follows:

bicubic_patch { type PATCH_TYPE flatness FLATNESS_VALUE u_steps NUM_U_STEPS v_steps NUM_V_STEPS <CP1>, <CP2>, <CP3>, <CP4>, <CP5>, <CP6>, <CP7>, <CP8>, <CP9>, <CP10>, <CP11>, <CP12>, <CP13>, <CP14>, <CP15>, <CP16> }

The keyword type is followed by a float PATCH_TYPE which currently must be either 0 or 1. For type 0 only the control points are retained within POV-Ray. This means that a minimal amount of memory is needed but POV-Ray will need to perform many extra calculations when trying to render the patch. Type 1 preprocesses the patch into many subpatches. This results in a significant speedup in rendering at the cost of memory.

The four parameters type, flatness, u_steps and v_steps may appear in any order. They are followed by 16 vectors that define the x, y, z coordinates of the 16 control points which define the patch. The patch touches the four corner points <CP1>, <CP4>, < CP13> and <CP16> while the other 12 points pull and stretch the patch into shape. The Bezier surface is enclosed by the convex hull formed by the 16 control points, this is known as the convex hull property.

The keywords u_steps and v_steps are each followed by float values which tell how many rows and columns of triangles are the minimum to use to create the surface. The maximum number of individual pieces of the patch that are tested by POV-Ray can be calculated from the following:

sub-pieces = 2^u_steps * 2^v_steps

This means that you really should keep u_steps and v_steps under 4. Most patches look just fine with u_steps 3 and v_steps 3, which translates to 64 subpatches (128 smooth triangles).

As POV-Ray processes the Bezier patch it makes a test of the current piece of the patch to see if it is flat enough to just pretend it is a rectangle. The statement that controls this test is flatness. Typical flatness values range from 0 to 1 (the lower the slower).

If the value for flatness is 0 POV-Ray will always subdivide the patch to the extend specified by u_steps and v_steps. If flatness is greater than 0 then every time the patch is split, POV-Ray will check to see if there is any need to split further.

There are both advantages and disadvantages to using a non-zero flatness. The advantages include:

-If the patch isn't very curved, then this will be detected and POV-Ray won't waste a lot of time looking at the wrong pieces.
-If the patch is only highly curved in a couple of places, POV-Ray will keep subdividing there and concentrate it's efforts on the hard part.

The biggest disadvantage is that if POV-Ray stops subdividing at a particular level on one part of the patch and at a different level on an adjacent part of the patch there is the potential for cracking. This is typically visible as spots within the patch where you can see through. How bad this appears depends very highly on the angle at which you are viewing the patch.

Like triangles, the bicubic patch is not meant to be generated by hand. These shapes should be created by a special utility. You may be able to acquire utilities to generate these shapes from the same source from which you obtained POV-Ray.

bicubic_patch { type 1 flatness 0.01 u_steps 4 v_steps 4 <0, 0, 2>, <1, 0, 0>, <2, 0, 0>, <3, 0,-2>, <0, 1 0>, <1, 1, 0>, <2, 1, 0>, <3, 1, 0>, <0, 2, 0>, <1, 2, 0>, <2, 2, 0>, <3, 2, 0>, <0, 3, 2>, <1, 3, 0>, <2, 3, 0>, <3, 3, -2> }

The triangles in a POV-Ray bicubic_patch are automatically smoothed using normal interpolation but it is up to the user (or the user's utility program) to create control points which smoothly stitch together groups of patches.


One other flat, finite object available with POV-Ray is the disc. The disc is infinitely thin, it has no thickness. If you want a disc with true thickness you should use a very short cylinder. A disc shape may be defined by:


The vector <CENTER> defines the x, y, z coordinates of the center of the disc. The < NORMAL> vector describes its orientation by describing its surface normal vector. This is followed by a float specifying the RADIUS. This may be optionally followed by another float specifying the radius of a hole to be cut from the center of the disc.


The mesh object can be used to efficiently store large numbers of triangles. Its syntax is:

mesh { triangle { <CORNER1>, <CORNER2>, <CORNER3> [ texture { STRING } ] } smooth_triangle { <CORNER1>, <NORMAL1>, <CORNER2>, <NORMAL2>, <CORNER3>, <NORMAL3> [ texture { STRING } ] } [ hierarchy FLAG ] }

Any number of triangles and/or smooth triangles can be used and each of those triangles can be individually textured by assigning a texture name to it. The texture has to be declared before the mesh is parsed. It is not possible to use texture definitions inside the triangle or smooth triangle statements. This is a restriction that is necessary for an efficient storage of the assigned textures.

The mesh's components are internally bounded by a bounding box hierarchy to speed up intersection testing. The bounding hierarchy can be turned off with the hierarchy keyword. This should only be done if memory is short or the mesh consists of only a few triangles.

Copies of a mesh object refer to the same triangle data and thus consume very little memory. You can easily trace hundred copies of an 10000 triangle mesh without running out of memory (assuming the first mesh fits into memory).

The mesh object has two advantages over a union of triangles: it needs less memory and it is transformed faster. The memory requirements are reduced by efficiently storing the triangles vertices and normals. The parsing time for transformed meshes is reduced because only the mesh object has to be transformed and not every single triangle as it is necessary for unions.

The mesh object can currently only include triangle and smooth triangle components. That restriction is liable to change, allowing polygonal components, at some point in the future.


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 }
Next Section
Table Of Contents