The Online POV-Ray Tutorial

Finite Object Reference

The following topics are covered in this section

Bicubic Patch

This primitive creates Bezier style bicubic patch (sorry about the flurry of large words). A bicubic patch is a smooth surface defined by sixteen points, four of which specify the corners and are necessarily on the surface, and twelve others which are probably not on the surface, but are rather used to stretch it into the proper shape. Bicubic patches are really meant to be created by people. They're more the kind of thing that would be generated by a modeller of some sort. If you like pain you can create them yourself, though. POV-Ray renders bicubic patches as meshes of triangles. Here's the syntax for a bicubic patch: 

bicubic_patch {
   type type
   flatness flatness
   u_steps u_steps
   v_steps v_steps
   <c1>,  <c2>,  <c3>,  <c4>,
   <c5>,  <c6>,  <c7>,  <c8>,
   <c9>,  <c10>, <c11>, <c12>,
   <c13>, <c14>, <c15>, <c16>
}

The four parameters (type, flatness, u_steps, and v_steps) may appear in any order, but must appear before the control points are specified. type specfies how POV-Ray should store the patch in memory. If type is 0 then POV-Ray just stores the control points in memory. This is quite memory efficient, but also very slow. If type is 1, then POV-Ray will preprocess the patch and store the resulting object(s) in memory. This will cause the object to render much faster, but at the expense of memory.

The u_steps and v_steps keywords specify the maximum number of subpatches to divide the patch into. u_steps and v_steps are floats and shouldn't have any fractional part. The maximum number of subpatches can be calculated with the expression

max = 2 ^ u_steps * 2 ^ v_steps

As a result, it's a bad idea to make u_steps or v_steps very large. The POV-Ray authors recommend that "u_steps 3" and "v_steps 3" will cause most patches to render well. They also suggest 5 as a maximum value for either parameter.

The flatness keyword is used to determine if a subpatch needs to be divided into smaller ones. flatness is a float which should be between 0 and 1 inclusive. The lower this value is, the more subdivisions POV-Ray will make (up to the u_steps or v_steps). If this value is 0, POV-Ray will always divide the patch into the maximum number of subpatches. Note that the lower this value is, the slower the patch will render.

As bicubic patches are made of triangles, they don't have a clearly defined inside, and so can't be used in CSG (except for union) or inside a clipped_by statement.

Although it's not particularly useful, here's an example of a bicubic patch.

If you want to learn more about bicubic patches (how they are generated, how they work, how to create them, and all the mathematics behind them) a book that we recommend is

Fundamentals of Interactive Computer Graphics
J. D. Foley and A. Van Dam
Addison-Wesley
1983
ISBN 0-201-14468-9
It covers a great deal of material with a good amount of depth, despite the "fundamentals" in the title. Note that when dealing with bicubic patches this book assumes a familiarity with matrices.

Blob

Blobs are quite peculiar. The basically consist of a bunch of spheres which attract or repel each other to form a surface. They aren't really meant to be precise objects, but rather objects that give a sort of "organic" feel to a scene. Their syntax is as follows: 

blob {
   threshold threshold
   component strength1, radius1, <center1>
   component strength2, radius2, <center2>
   component strength3, radius3, <center3>
   component strength4, radius4, <center4>
/* you can have as many components as you have memory and time */
}

Blobs basically work by creating fields around each of the components by adding the strength values from each components according to a specified function. Wherever this value is equal to the threshold, the surface is drawn.

As described above, threshold tells where in space to draw the surface. It is a float which should be greater than zero.

The strength of each component tells how strong the field around this component is. This can be positive or negative. A positive strength will cause the surface to stretch towards this component; a negative strength will repel the surface away from this component. The larger the value, the greater the effect this particular component will have.

The radius of each component describes its field of effect. The blob equations are set up so that the field strength of each component is equal to strength at the center of the component and falls off to zero at a distance of radius from the center of that component.

Each <center> vector gives the <x, y, z> of the center point of that component. As blobs are difficult to visualize, here are a few examples. 

blob {
   threshold 0.25
   component 1.5, 0.5, <0, 0, 0>
   component 1, 0.5, <-0.5, 0.5, 0>
   component 1, 0.5, <0.5, 0.5, 0>
   pigment { color Red }
}

[example blob image] 

blob {
   threshold 0.25
   component 1.5, 0.5, <0, 0, 0>
   component 1, 0.5, <-0.5, 0.5, 0>
   component -1, 0.5, <0.5, 0.5, 0>
   pigment { color Red }
}

[example blob image]

Blobs can be used in CSG, the inside of a blob is anywhere the field strength is greater than the threshold. Conversely, the outside is anywhere that field strength is less than the threshold. Note that components in different blob objects will not affect each other.

If a blob renders improperly, the keyword sturm may be added into the declaration. This will cause POV-Ray to use a more accurate (but slower) root solver.

Box

The box primitive creates a rectangular prism (fancy term for a box) with faces parallel to the coordinate planes. Its syntax is a follows: 

box {
   <corner-1>, <corner-2>
}

where <corner-1> and <corner-2> are vectors specifying the <x, y, z> of opposite corners of the box. The POV-Ray documentation states that all the elements of <corner-1> should be less than the corresponding elements of <corner-2>, but I have never had problems with this. Here's an example of a box: 

box {
   <-1, -1, -1>, <1, 1, 1>
   pigment { color Green }
}

This creates a green cube two units on a side centered at the origin. Here are some sample boxes, both of which just happen to be cubes (not all boxes have to be cubes, though).

Boxes are highly optimized objects and thus make wonderful bounding volumes.

Cone

The cone primitive creates a creates a cone with the given characteristics. It is similar to the cylinder, but two radii are specified instead of just one. Its syntax: 

cone {
   <center-1>, radius-1,
   <center-2>, radius-2
   [open]
}

<center-1> and <center-1> are <x, y, z> vectors for the centers of the two ends of the cone. radius-1 and radius-2 specify the radius of the cone at <center-1> and <center-1> respectively. Both radius-1 and radius-2 can be positive, negative, or zero. If one radius is zero, the objects looks like a standard cone shape. If both radii are the same sign, the object looks like a cone with the tip cut off. If the radii are opposite signs, the object looks like two cones with their tips touching. An example cone: 

cone {
   <0, 0, 0>, 3,
   <0, 3, 0>, 0
   pigment { color Blue }
}

This will create a cone that is three units tall and six units in diameter at the base.

The following scene contains some other examples of cones.

The keyword open may be included in the object definition to make POV-Ray render the cone without endcaps.

Cylinder

The cylinder primitive creates a circular cylinder with the given characteristics. The syntax of the primitive is the following: 

cylinder {
   <center-1>, <center-2>, radius
   [open]
}

<center-1> and <center-2> are vectors specifying the <x, y, z> of the centers of the ends of the cylinder. radius specifies the radius of the cylinder. Note that the sides of the cylinder will always be perpendicular to the ends. An example cylinder declaration: 

cylinder {
   <0, 0, 0>, <0, 1, 0>, 0.5
   pigment { color Yellow }
}

This will create a circular cylinder that has the same height as diameter.

The following example scene contains three cylinders.

Including the keyword open will cause POV-Ray to render the cylinder without endcaps (as a tube).

Disc

The disc primitive creates an infinitely thin circular disc with an optional hole in the center. The syntax for a disc: 

disc {
   <center>, <normal>, radius [, hole radius]
}

<center> is an <x, y, z> vector specifying the center of the disc. <normal> is a vector perpendicular to the plane of the disc. radius is a float which gives the radius of the disc. Optionally, the float hole radius may be specified which will create a circular hole of that radius in the center of the disc. If present, hole radius should be smaller than radius (otherwise, what's the point?). Here's an example use of a disc: 

disc {
   <0, 0, 0>, <0, 1, -1>, 2, 1.5
   pigment { color Green }
}
sphere {
   <0, 0, 0>, 1
   pigment { color Green }
}

This will create a sort of monochromatic version of Saturn. Here's how that would look.

Note that discs are two dimensional objects and so have no inside or outside. Consequently, they can't be used in CSG (except in union) or inside a clipped_by.

Height Field

Height fields are an easy way to create mountains in your scenes. They basically work by reading an image file and then turning that image into a mesh of triangles. The height of each point in the mesh is determined by the value of the corresponding pixel in the image. The general form for specifying a height field is 

height_field {
   type "filename"
   [smooth]
   [water_level height]
   /* transformations */
}

type specifies the type of the file being read, and is one of gif, pot, or tga. This is then followed by the name of the source image (in quotes). With just these declarations, you'll get a height field which fits into the unit box with vertices at <0, 0, 0> an <1, 1, 1>. The image is mapped onto the x-z plane with the value of the pixel determining the y value of the field. The lower-left corner of the image ends up at <0, 0, 0> and the upper-right ends up at <1, 0, 1>. The lowest possible value of the height field ends up at y=0, while the highest gets y=1. The image is always rescaled to fit into that unit box. Thus, larger images do not produce larger height fields, but rather ones with better resolution.

Here's an example of a height field. The first image is the source for the height field (black=0, white=255). The second is the rendered height field.

For gifs, the height of a given pixel is based on its palette index. The color with palette entry 0 gets the lowest height in the height field, while the color with palette entry 255 gets the hightest height in the field. Thus with gifs, you can get 256 distinct height levels in the height field. Pot files work the same, except they support upto 32,000 (or so) colors. As with resolution, this does not produce taller height fields, but rather ones with better vertical resolution. According to the POV-Ray authors, the PC program Fractint can produce pot files.

Height mapping is done slightly differently with tga files. With tgas a sixteen bit number (so you get 65,536 height levels) is stored for each pixel using that pixel's red and green bytes. The most significant byte is stored in the red, the least significant in the green. Generating these kinds of height fields is pretty much beyond the scope of most paint programs, but it's pretty rare that you'll actually need 65,536 distinct height levels anyway. Fractal mountains tend to look fine with 256 divisions, unless you want to get a super-close-up view.

Normally, POV-Ray generates height fields out of normal, flat triangles. This gives the height field a rough, jagged look. While this may be exactly the effect you're looking for with mountains, sometimes it is undesirable. You can include the optional keyword "smooth" in the height field. This will cause POV-Ray to use smooth triangles instead of flat ones for mesh. POV-Ray will automatically calculate surface normals to make the height field into a smooth, rolling surface, however, smooth height fields require much more memory to deal with than do normal height fields.

Another keyword that you can include is "water_level". This keyword is used to cut off the bottom part of a height field. This is useful for mountains which you plan to partially submerge in water. Parts of the height field which are below the "water_level" will not be turned into triangles, making for a speedier render. The water_level keyword takes a float parameter between 0.0 and 1.0 which specifies where to slice. 0.0 corresponds to the lowest level in the field, 1.0 to the heighest. 0.5 would cut off the bottom half of the field. This slicing is applied before any transformations are applied, so you should never need a value greater than 1. Here, for example, is the same height field as above with "water_level 0.5" added in.

Object

The object primitive is not typically used to create single objects. It is primarily used only to create objects that have been declared with a declare directive. In fact, an object primitive is implied around any primitive that creates an object. For example, 

sphere {
   <1, 1, 1>, 1.732
   pigment { color Red }
}

Is the same as 

object {
   sphere {
      <1, 1, 1>, 1.732
      pigment { color Red }
   }
}

The object primitive is more commonly used in this sort of fashion 

#declare BlueSphere = sphere {
   <0, 0, 0>, 1
   pigment { color Blue }
}

object {
   BlueSphere
}

object {
   BlueSphere
   scale 2
   translate <0, 5, 5>
}

Of course, this is a very simple example. Any type of object, whether finite, infinite, or CSG, can appear in an object statement.

Smooth Triangle

Smooth triangles are triangular patches with normal vectors specified for each of the vertices. These vectors are used to bend the triangle into a curved shape. Smooth triangles aren't really designed to be used extensively by people. They're more the type of thing a modeller would produce to approximate a smooth surface. Here's the syntax anyway: 

smooth_triangle {
   <vertex-1>, <normal-1>
   <vertex-2>, <normal-2>
   <vertex-3>, <normal-3>
}

The three vertices specify the corners of the triangle. The corresponding normal vector is then used in shading the surface. Note that the normal vectors don't acutally cause the triangle to be deformed, they just alter the way POV-Ray shades it. This can be used to great effect when approximating smooth surfaces, as it would require a much larger number of flat triangles to acheive the same results. To create a smooth smooth_triangle mesh, the normals for shared vertices in any triangles should be the same.

Smooth triangles are perfectly two-dimensional so they have no inside or outside. They therefore cannot be used in CSG (other than in union) or inside a clipped_by statement.

Sphere

The sphere primitive creates a sphere of a given radius and center. The syntax is the following: 

sphere {
   <center>, radius
}

where <center> is a vector specifying <x, y, z> of the center of the sphere and radius is a float specifying the sphere's radius. For example, 

sphere {
   <10, 10, 10>, 5
   pigment { color Blue }
}

will create a blue sphere of radius 5 that is centered at <10, 10, 10>. This primitive can only create spheres, but you can use nonuniform scaling to create ellipsoidal objects.

Anyway, here are some sample spheres.

Also, spheres are highly optimized objects in POV-Ray, and thus make spectacular bounding volumes.

Torus

The torus primitive will create a torus (doughnut shape) at the origin. A torus is a quartic shape; this primitive is basically an easier way of creating this cool and useful shape. The torus syntax is as follows: 

torus {
   major radius, minor radius
}

The major radius and minor radius are defined as shown below

This primitive always creates a torus with a major axis in the x-z plane. If you want one with a different orientation, you'll need to rotate it. The advantage to using this form over the quartic definition is that this form is known by POV-Ray to be finite, thus POV-Ray can optimize its rendering.

Triangle

Triangles are the familiar three cornered polygons we all learned about in school. They are similar to smooth triangles, only they don't have normal information for the vertices. Here's the syntax for the triangle: 

triangle {
   <corner-1>, <corner-2>, <corner-3>
}

where each <corner> is an <x, y, z> vector specifying the locations of the three corners. Triangles are moderately useful to human beings, but they're much more useful to modelling programs.

The object in the following scene is composed entirely of triangles. If you're interested, the object is known as an icosahedron.

As with the other two dimensional objects, triangles have no inside or outside and so can't be used in CSG, with the exception of union, and nor can they be used inside a clipped_by.

Reference Index Top of Document Beginning of the Tutorial

The Online POV-Ray Tutorial © 1996 The Online POV-Ray Tutorial ThinkQuest Team