Finite Solid Primitives

6.5.1.1 Blob

Blobs are an interesting and flexible object type. Mathematically they are iso-surfaces of scalar fields, i.e. their surface is defined by the strength of the field in each point. If this strength is equal to a threshold value you're on the surface otherwise you're not.

Picture each blob component as an object floating in space. This object is filled with a field that has its maximum at the center of the object and drops off to zero at the object's surface. The field strength of all those components are added together to form the field of the blob. Now POV-Ray looks for points where this field has a given value, the threshold value. All these points form the surface of the blob object. Points with a greater field value than the threshold value are considered to be inside while points with a smaller field value are outside.

There's another, simpler way of looking at blobs. They can be seen as a union of flexible components that attract or repel each other to form a blobby organic looking shape. The components' surfaces actually stretch out smoothly and connect as if they were made of honey or something similar.

The syntax for blob is defined as follows:

BLOB:
    blob { BLOB_ITEM... [BLOB_MODIFIERS...]}
BLOB_ITEM:
    sphere{<Center>, Radius,
           [ strength ] Strength[COMPONENT_MODIFIER...] } |
    cylinder{<End1>, <End2>, Radius,
             [ strength ] Strength [COMPONENT_MODIFIER...] } |
    component Strength, Radius, <Center> |
    threshold Amount
COMPONENT_MODIFIER:
    TEXTURE | PIGMENT | NORMAL | FINISH | TRANSFORMATION
BLOB_MODIFIER:
    hierarchy [Boolean] | sturm [Boolean] | OBJECT_MODIFIER

Blob default values:

hierarchy : on
sturm     : off
threshold : 1.0

The threshold keyword is followed by a float value which determines the total field strength value that POV-Ray is looking for. The default value if none is specified is threshold 1.0. By following the ray out into space and looking at how each blob component affects the ray, POV-Ray will find the points in space where the field strength is equal to the threshold value. The following list shows some things you should know about the threshold value.

The threshold value must be positive.
A component disappears if the threshold value is greater than its strength.
As the threshold value gets larger, the surface you see gets closer to the centers of the components.
As the threshold value gets smaller, the surface you see gets closer to the surface of the components.

Cylindrical components are specified by a cylinder statement. The center of the end-caps of the cylinder is defined by the vectors <End1> and <End2>. Next is the float value of the Radius followed by the float Strength. These vectors and floats are required and should be separated by commas. The keyword strength may optionally precede the strength value. The cylinder has hemispherical caps at each end.

Spherical components are specified by a sphere statement. The location is defined by the vector <Center>. Next is the float value of the Radius followed by the float Strength. These vector and float values are required and should be separated by commas. The keyword strength may optionally precede the strength value.

You usually will apply a single texture to the entire blob object, and you typically use transformations to change its size, location, and orientation. However both the cylinder and sphere statements may have individual texture, pigment, normal, finish, and transformations applied to them. You may not apply separate interior statements to the components but you may specify one for the entire blob.

Note: by unevenly scaling a spherical component you can create ellipsoidal components. The tutorial section on "Blob Object" illustrates individually textured blob components and many other blob examples.

The component keyword is an obsolete method for specifying a spherical component and is only used for compatibility with earlier POV-Ray versions. It may not have textures or transformations individually applied to it.

The strength parameter of either type of blob component is a float value specifying the field strength at the center of the object. The strength may be positive or negative. A positive value will make that component attract other components while a negative value will make it repel other components. Components in different, separate blob shapes do not affect each other.

You should keep the following things in mind.

The strength value may be positive or negative. Zero is a bad value, as the net result is that no field was added -- you might just as well have not used this component.
If strength is positive, then POV-Ray will add the component's field to the space around the center of the component. If this adds enough field strength to be greater than the threshold value you will see a surface.
If the strength value is negative, then POV-Ray will subtract the component's field from the space around the center of the component. This will only do something if there happen to be positive components nearby. The surface around any nearby positive components will be dented away from the center of the negative component.

After all components and the optional threshold value have been specified you may specify zero or more blob modifiers. A blob modifier is any regular object modifier or the hierarchy or sturm keywords.

The components of each blob object are internally bounded by a spherical bounding hierarchy to speed up blob intersection tests and other operations. Using the optional keyword hierarchy followed by an optional boolean float value will turn it off or on. By default it is on.

The calculations for blobs must be very accurate. If this shape renders improperly you may add the keyword sturm followed by an optional boolean float value to turn off or on POV-Ray's slower-yet-more-accurate Sturmian root solver. By default it is off.

An example of a three component blob is:

BLOB:
 blob {
  threshold 0.6
  sphere { <.75, 0, 0>, 1, 1 }
  sphere { <-.375, .64952, 0>, 1, 1 }
  sphere { <-.375, -.64952, 0>, 1, 1 }
  scale 2
 }

If you have a single blob component then the surface you see will just look like the object used, i.e. a sphere or a cylinder, with the surface being somewhere inside the surface specified for the component. The exact surface location can be determined from the blob equation listed below (you will probably never need to know this, blobs are more for visual appeal than for exact modeling).

For the more mathematically minded, here's the formula used internally by POV-Ray to create blobs. You don't need to understand this to use blobs. The density of the blob field of a single component is:

Density of a blob field

where distance is the distance of a given point from the spherical blob's center or cylinder blob's axis. This formula has the nice property that it is exactly equal to the strength parameter at the center of the component and drops off to exactly 0 at a distance from the center of the component that is equal to the radius value. The density formula for more than one blob component is just the sum of the individual component densities.

6.5.1.2 Box

A simple box can be defined by listing two corners of the box using the following syntax for a box statement:

BOX:
    box
    {
        <Corner_1>, <Corner_2>
        [OBJECT_MODIFIERS...]
    }

The geometry of a box

Where <Corner_1> and <Corner_2> are vectors defining the x, y, z coordinates of the opposite corners of the box.

Note: that all boxes are defined with their faces parallel to the coordinate axes. They may later be rotated to any orientation using the rotate keyword.

Boxes are calculated efficiently and make good bounding shapes (if manually bounding seems to be necessary).

6.5.1.3 Cone

The cone statement creates a finite length cone or a frustum (a cone with the point cut off). The syntax is:

CONE:
    cone
    {
        <Base_Point>, Base_Radius, <Cap_Point>, Cap_Radius
        [ open ][OBJECT_MODIFIERS...]
    }

The geometry of a cone

Where <Base_Point> and < Cap_Point> are vectors defining the x, y, z coordinates of the center of the cone's base and cap and Base_Radius and Cap_Radius are float values for the corresponding radii.

Normally the ends of a cone are closed by flat discs that are parallel to each other and perpendicular to the length of the cone. Adding the optional keyword open after Cap_Radius will remove the end caps and results in a tapered hollow tube like a megaphone or funnel.

6.5.1.4 Cylinder

The cylinder statement creates a finite length cylinder with parallel end caps The syntax is:

CYLINDER:
    cylinder
    {
        <Base_Point>, <Cap_Point>, Radius
        [ open ][OBJECT_MODIFIERS...]
    }

The geometry of a cylinder

Where <Base_Point> and <Cap_Point> are vectors defining the x, y, z coordinates of the cylinder's base and cap and Radius is a float value for the radius.

Normally the ends of a cylinder are closed by flat discs that are parallel to each other and perpendicular to the length of the cylinder. Adding the optional keyword open after the radius will remove the end caps and results in a hollow tube.

6.5.1.5 Height Field

Height fields are fast, efficient objects that are generally used to create mountains or other raised surfaces out of hundreds of triangles in a mesh. The height_field statement syntax is:

HEIGHT_FIELD:
    height_field{
      [HF_TYPE]
      "filename"
      [HF_MODIFIER...]
      [OBJECT_MODIFIER...]
    }
HF_TYPE:
    gif | tga | pot | png | pgm | ppm | jpeg | tiff | sys
HF_MODIFIER:
    hierarchy [Boolean]  |
    smooth               |
    water_level Level

Height_field default values:

hierarchy   : on
smooth      : off
water_level : 0.0

A height field is essentially a one unit wide by one unit long square with a mountainous surface on top. The height of the mountain at each point is taken from the color number or palette index of the pixels in a graphic image file. The maximum height is one, which corresponds to the maximum possible color or palette index value in the image file.

The size and orientation of an un-scaled height field

The mesh of triangles corresponds directly to the pixels in the image file. Each square formed by four neighboring pixels is divided into two triangles. An image with a resolution of N*M pixels has (N-1)*(M-1) squares that are divided into 2*(N-1)*(M-1) triangles.

Relationship of pixels and triangles in a height field

The resolution of the height field is influenced by two factors: the resolution of the image and the resolution of the color/index values. The size of the image determines the resolution in the x- and z-direction. A larger image uses more triangles and looks smoother. The resolution of the color/index value determines the resolution along the y-axis. A height field made from an 8-bit image can have 256 different height levels while one made from a 16-bit image can have up to 65536 different height levels. Thus the second height field will look much smoother in the y-direction if the height field is created appropriately.

The size/resolution of the image does not affect the size of the height field. The un-scaled height field size will always be 1 by 1 by 1. Higher resolution image files will create smaller triangles, not larger height fields.

There are eight or possibly nine types of files which can define a height field. The image file type used to create a height field is specified by one of the keywords gif, tga, pot, png, pgm, ppm, tiff, jpeg and possibly sys which is a system specific (e. g. Windows BMP or Macintosh Pict) format file. Specifying the file type is optional. If it is not defined the same file type will be assumed as the one that is set as the output file type. This is usefull when the source for the height_field is also generated with POV-Ray.

The GIF, PNG, PGM, TIFF and possibly SYS format files are the only ones that can be created using a standard paint program. Though there are paint programs for creating TGA image files they won't be of much use for creating the special 16 bit TGA files used by POV-Ray (see below and "HF_Gray_16" for more details).

In an image file that uses a color palette, like GIF, the color number is the palette index at a given pixel. Use a paint program to look at the palette of a GIF image. The first color is palette index zero, the second is index one, the third is index two and so on. The last palette entry is index 255. Portions of the image that use low palette entries will result in lower parts of the height field. Portions of the image that use higher palette entries will result in higher parts of the height field.

Height fields created from GIF files can only have 256 different height levels because the maximum number of colors in a GIF file is 256.

The color of the palette entry does not affect the height of the pixel. Color entry 0 could be red, blue, black or orange but the height of any pixel that uses color entry 0 will always be 0. Color entry 255 could be indigo, hot pink, white or sky blue but the height of any pixel that uses color entry 255 will always be 1.

You can create height field GIF images with a paint program or a fractal program like Fractint. You can usually get Fractint from most of the same sources as POV-Ray.

A POT file is essentially a GIF file with a 16 bit palette. The maximum number of colors in a POT file is 65536. This means a POT height field can have up to 65536 possible height values. This makes it possible to have much smoother height fields.

Note: the maximum height of the field is still 1 even though more intermediate values are possible.

At the time of this writing the only program that created POT files was a freeware MS-Dos/Windows program called Fractint. POT files generated with this fractal program create fantastic landscapes.

The TGA and PPM file formats may be used as a storage device for 16 bit numbers rather than an image file. These formats use the red and green bytes of each pixel to store the high and low bytes of a height value. These files are as smooth as POT files but they must be generated with special custom-made programs. Several programs can create TGA heightfields in the format POV uses, such as Gforge and Terrain Maker.

PNG format heightfields are usually stored in the form of a grayscale image with black corresponding to lower and white to higher parts of the height field. Because PNG files can store up to 16 bits in grayscale images they will be as smooth as TGA and PPM images. Since they are grayscale images you will be able to view them with a regular image viewer. gforge can create 16-bit heightfields in PNG format. Color PNG images will be used in the same way as TGA and PPM images.

SYS format is a platform specific file format. See your platform specific documentation for details.

In addition to all the usual object modifiers, there are three additional height field modifiers available.

The optional water_level parameter may be added after the file name. It consists of the keyword water_level followed by a float value telling the program to ignore parts of the height field below that value. The default value is zero and legal values are between zero and one. For example water_level 0.5 tells POV-Ray to only render the top half of the height field. The other half is below the water and couldn't be seen anyway. Using water_level renders faster than cutting off the lower part using CSG or clipping. This term comes from the popular use of height fields to render landscapes. A height field would be used to create islands and another shape would be used to simulate water around the islands. A large portion of the height field would be obscured by the water so the water_level parameter was introduced to allow the ray-tracer to ignore the unseen parts of the height field. water_level is also used to cut away unwanted lower values in a height field. For example if you have an image of a fractal on a solid colored background, where the background color is palette entry 0, you can remove the background in the height field by specifying, water_level 0.001.

Normally height fields have a rough, jagged look because they are made of lots of flat triangles. Adding the keyword smooth causes POV-Ray to modify the surface normal vectors of the triangles in such a way that the lighting and shading of the triangles will give a smooth look. This may allow you to use a lower resolution file for your height field than would otherwise be needed. However, smooth triangles will take longer to render. The default value is off.

In order to speed up the intersection tests a one-level bounding hierarchy is available. By default it is always used but it can be switched off using hierarchy off to improve the rendering speed for small height fields (i.e. low resolution images). You may optionally use a boolean value such as hierarchy on or hierarchy off.

6.5.1.6 Julia Fractal

A julia fractal object is a 3-D slice of a 4-D object created by generalizing the process used to create the classic Julia sets. You can make a wide variety of strange objects using the julia_fractal statement including some that look like bizarre blobs of twisted taffy. The julia_fractal syntax is:

JULIA_FRACTAL:
    julia_fractal
    {
        <4D_Julia_Parameter>
        [JF_ITEM...] [OBJECT_MODIFIER...]
    }
JF_ITEM:
    ALGEBRA_TYPE | FUNCTION_TYPE | max_iteration Count |
    precision Amt | slice <4D_Normal>, Distance
ALGEBRA_TYPE:
    quaternion | hypercomplex
FUNCTION_TYPE:
    QUATERNATION: 
         sqr | cube
    HYPERCOMPLEX:
         sqr | cube | exp | reciprocal | sin | asin | sinh |
         asinh | cos | acos | cosh | acosh | tan | atan |tanh |
         atanh | ln | pwr( X_Val, Y_Val )

Julia Fractal default values:

ALGEBRA_TYPE    : quaternion
FUNCTION_TYPE   : sqr
max_iteration   : 20
precision       : 20
slice, DISTANCE : <0,0,0,1>, 0.0

The required 4-D vector <4D_Julia_Parameter> is the classic Julia parameter p in the iterated formula f(h) + p. The julia fractal object is calculated by using an algorithm that determines whether an arbitrary point h(0) in 4-D space is inside or outside the object. The algorithm requires generating the sequence of vectors h(0), h(1), ... by iterating the formula h(n+1) = f(h(n)) + p (n = 0, 1, ..., max_iteration-1) where p is the fixed 4-D vector parameter of the julia fractal and f() is one of the functions sqr, cube, ... specified by the presence of the corresponding keyword. The point h(0) that begins the sequence is considered inside the julia fractal object if none of the vectors in the sequence escapes a hypersphere of radius 4 about the origin before the iteration number reaches the integer max_iteration value. As you increase max_iteration, some points escape that did not previously escape, forming the julia fractal. Depending on the <4D_Julia_Parameter>, the julia fractal object is not necessarily connected; it may be scattered fractal dust. Using a low max_iteration can fuse together the dust to make a solid object. A high max_iteration is more accurate but slows rendering. Even though it is not accurate, the solid shapes you get with a low max_iteration value can be quite interesting. If none is specified, the default is max_iteration 20.

Since the mathematical object described by this algorithm is four-dimensional and POV-Ray renders three dimensional objects, there must be a way to reduce the number of dimensions of the object from four dimensions to three. This is accomplished by intersecting the 4-D fractal with a 3-D "plane" defined by the slice modifier and then projecting the intersection to 3-D space. The keyword is followed by 4-D vector and a float separated by a comma. The slice plane is the 3-D space that is perpendicular to <4D_Normal> and is Distance units from the origin. Zero length <4D_Normal> vectors or a <4D_Normal> vector with a zero fourth component are illegal. If none is specified, the default is slice <0,0,0,1>,0.

You can get a good feel for the four dimensional nature of a julia fractal by using POV-Ray's animation feature to vary a slice's Distance parameter. You can make the julia fractal appear from nothing, grow, then shrink to nothing as Distance changes, much as the cross section of a 3-D object changes as it passes through a plane.

The precision parameter is a tolerance used in the determination of whether points are inside or outside the fractal object. Larger values give more accurate results but slower rendering. Use as low a value as you can without visibly degrading the fractal object's appearance but note values less than 1.0 are clipped at 1.0. The default if none is specified is precision 20.

The presence of the keywords quaternion or hypercomplex determine which 4-D algebra is used to calculate the fractal. The default is quaternion. Both are 4-D generalizations of the complex numbers but neither satisfies all the field properties (all the properties of real and complex numbers that many of us slept through in high school). Quaternions have non-commutative multiplication and hypercomplex numbers can fail to have a multiplicative inverse for some non-zero elements (it has been proved that you cannot successfully generalize complex numbers to four dimensions with all the field properties intact, so something has to break). Both of these algebras were discovered in the 19th century. Of the two, the quaternions are much better known, but one can argue that hypercomplex numbers are more useful for our purposes, since complex valued functions such as sin, cos, etc. can be generalized to work for hypercomplex numbers in a uniform way.

For the mathematically curious, the algebraic properties of these two algebras can be derived from the multiplication properties of the unit basis vectors 1 = <1,0,0,0>, i=< 0,1,0,0>, j=<0,0,1,0> and k=< 0,0,0,1>. In both algebras 1 x = x 1 = x for any x (1 is the multiplicative identity). The basis vectors 1 and i behave exactly like the familiar complex numbers 1 and i in both algebras.

Quaternion basis vector multiplication rules
`ij = k`	`jk = i`	`ki = j`
`ji = -k`	`kj = -i`	`ik = -j`
`ii = jj = kk = -1`	`ijk = -1`

Hypercomplex basis vector multiplication rules
`ij = k`	`jk = -i`	`ki = -j`
`ji = k`	`kj = -i`	`ik = -j`
`ii = jj = kk = -1`	`ijk = 1`

A distance estimation calculation is used with the quaternion calculations to speed them up. The proof that this distance estimation formula works does not generalize from two to four dimensions but the formula seems to work well anyway, the absence of proof notwithstanding!

The presence of one of the function keywords sqr, cube, etc. determines which function is used for f(h) in the iteration formula h(n+1) = f(h(n)) + p. The default is sqr. Most of the function keywords work only if the hypercomplex keyword is present. Only sqr and cube work with quaternion. The functions are all familiar complex functions generalized to four dimensions. Function Keyword Maps 4-D value h to:

Function Keyword Maps 4-D value h to
`sqr`	h*h
`cube`	hhh
`exp`	e raised to the power h
`reciprocal`	1/h
`sin`	sine of h
`asin`	arcsine of h
`sinh`	hyperbolic sine of h
`asinh`	inverse hyperbolic sine of h
`cos`	cosine of h
`acos`	arccosine of h
`cosh`	hyperbolic cos of h
`acosh`	inverse hyperbolic cosine of h
`tan`	tangent of h
`atan`	arctangent of h
`tanh`	hyperbolic tangent of h
`atanh`	inverse hyperbolic tangent of h
`ln`	natural logarithm of h
`pwr(x,y)`	h raised to the complex power x+iy

A simple example of a julia fractal object is:

 julia_fractal {
  <-0.083,0.0,-0.83,-0.025>
  quaternion
  sqr
  max_iteration 8
  precision 15
 }

The first renderings of julia fractals using quaternions were done by Alan Norton and later by John Hart in the '80's. This POV-Ray implementation follows Fractint in pushing beyond what is known in the literature by using hypercomplex numbers and by generalizing the iterating formula to use a variety of transcendental functions instead of just the classic Mandelbrot z2 + c formula. With an extra two dimensions and eighteen functions to work with, intrepid explorers should be able to locate some new fractal beasts in hyperspace, so have at it!

6.5.1.7 Lathe

The lathe is an object generated from rotating a two-dimensional curve about an axis. This curve is defined by a set of points which are connected by linear, quadratic, cubic or bezier spline curves. The syntax is:

LATHE:
    lathe
    {
        [SPLINE_TYPE] Number_Of_Points, <Point_1>
        <Point_2>... <Point_n>
        [LATHE_MODIFIER...]
    }
SPLINE_TYPE:
    linear_spline | quadratic_spline | cubic_spline | bezier_spline
LATHE_MODIFIER:
    sturm | OBJECT_MODIFIER

Lathe default values:

SPLINE_TYPE   : linear_spline
sturm         : off

The first item is a keyword specifying the type of spline. The default if none is specified is linear_spline. The required integer value Number_Of_Points specifies how many two-dimensional points are used to define the curve. The points follow and are specified by 2-D vectors. The curve is not automatically closed, i.e. the first and last points are not automatically connected. You will have to do this yourself if you want a closed curve. The curve thus defined is rotated about the y-axis to form the lathe object, centered at the origin.

The following examples creates a simple lathe object that looks like a thick cylinder, i.e. a cylinder with a thick wall:

 lathe {
  linear_spline
  5,
  <2, 0>, <3, 0>, <3, 5>, <2, 5>, <2, 0>
  pigment {Red}
 }

The cylinder has an inner radius of 2 and an outer radius of 3, giving a wall width of 1. It's height is 5 and it's located at the origin pointing up, i.e. the rotation axis is the y-axis.

Note: the first and last point are equal to get a closed curve.

The splines that are used by the lathe and prism objects are a little bit difficult to understand. The basic concept of splines is to draw a curve through a given set of points in a determined way. The default linear_spline is the simplest spline because it's nothing more than connecting consecutive points with a line. This means the curve that is drawn between two points only depends on those two points. No additional information is taken into account. The other splines are different in that they do take other points into account when connecting two points. This creates a smooth curve and, in the case of the cubic spline, produces smoother transitions at each point.

The quadratic_spline keyword creates splines that are made of quadratic curves. Each of them connects two consecutive points. Since those two points (call them second and third point) are not sufficient to describe a quadratic curve, the predecessor of the second point is taken into account when the curve is drawn. Mathematically, the relationship (their relative locations on the 2-D plane) between the first and second point determines the slope of the curve at the second point. The slope of the curve at the third point is out of control. Thus quadratic splines look much smoother than linear splines but the transitions at each point are generally not smooth because the slopes on both sides of the point are different.

The cubic_spline keyword creates splines which overcome the transition problem of quadratic splines because they also take a fourth point into account when drawing the curve between the second and third point. The slope at the fourth point is under control now and allows a smooth transition at each point. Thus cubic splines produce the most flexible and smooth curves.

The bezier_spline is an alternate kind of cubic spline. Points 1 and 4 specify the end points of a segment and points 2 and 3 are control points which specify the slope at the endpoints. Points 2 and 3 do not actually lie on the spline. They adjust the slope of the spline. If you draw an imaginary line between point 1 and 2, it represents the slope at point 1. It is a line tangent to the curve at point 1. The greater the distance between 1 and 2, the flatter the curve. With a short tangent the spline can bend more. The same holds true for control point 3 and endpoint 4. If you want the spline to be smooth between segments, points 3 and 4 on one segment and points 1 and 2 on the next segment must form a straight line and point 4 of one segment must be the same as point 1 on the next segment.

You should note that the number of spline segments, i. e. curves between two points, depends on the spline type used. For linear splines you get n-1 segments connecting the points P[i], i=1,...,n. A quadratic spline gives you n-2 segments because the last point is only used for determining the slope, as explained above (thus you'll need at least three points to define a quadratic spline). The same holds for cubic splines where you get n-3 segments with the first and last point used only for slope calculations (thus needing at least four points). The bezier spline requires 4 points per segment, creating n/4 segments.

If you want to get a closed quadratic and cubic spline with smooth transitions at the end points you have to make sure that in the cubic case P[n-1] = P[2] (to get a closed curve), P[n] = P[3] and P[n-2] = P[1] (to smooth the transition). In the quadratic case P[n-1] = P[1] (to close the curve) and P[n] = P[2].

The sturm keyword can be used to specify that the slower, but more accurate, Sturmian root solver should be used. Use it, if the shape does not render properly. Since a quadratic polynomial has to be solved for the linear spline lathe, the Sturmian root solver is not needed.

6.5.1.8 Prism

The prism is an object generated specifying one or more two-dimensional, closed curves in the x-z plane and sweeping them along y axis. These curves are defined by a set of points which are connected by linear, quadratic, cubic or bezier splines. The syntax for the prism is:

PRISM:
    prism
    {
        [PRISM_ITEMS...] Height_1, Height_2, Number_Of_Points,
        <Point_1>, <Point_2>, ... <Point_n>
        [ open ] [PRISM_MODIFIERS...]
    }
PRISM_ITEM:
    linear_spline | quadratic_spline | cubic_spline |
    bezier_spline | linear_sweep | conic_sweep
PRISM_MODIFIER:
    sturm | OBJECT_MODIFIER

Prism default values:

SPLINE_TYPE   : linear_spline
SWEEP_TYPE    : linear_sweep
sturm         : off

The first items specify the spline type and sweep type. The defaults if none is specified is linear_spline and linear_sweep. This is followed by two float values Height_1 and Height_2 which are the y coordinates of the top and bottom of the prism. This is followed by a float value specifying the number of 2-D points you will use to define the prism. (This includes all control points needed for quadratic, cubic and bezier splines). This is followed by the specified number of 2-D vectors which define the shape in the x-z plane.

The interpretation of the points depends on the spline type. The prism object allows you to use any number of sub-prisms inside one prism statement (they are of the same spline and sweep type). Wherever an even number of sub-prisms overlaps a hole appears.

Note: you need not have multiple sub-prisms and they need not overlap as these examples do.

In the linear_spline the first point specified is the start of the first sub-prism. The following points are connected by straight lines. If you specify a value identical to the first point, this closes the sub-prism and next point starts a new one. When you specify the value of that sub-prism's start, then it is closed. Each of the sub-prisms has to be closed by repeating the first point of a sub-prism at the end of the sub-prism's point sequence. In this example, there are two rectangular sub-prisms nested inside each other to create a frame.

 prism {
  linear_spline
  0, 1, 10,
  <0,0>, <6,0>, <6,8>, <0,8>, <0,0>,  //outer rim
  <1,1>, <5,1>, <5,7>, <1,7>, <1,1>   //inner rim
 }

The last sub-prism of a linear spline prism is automatically closed - just like the last sub-polygon in the polygon statement - if the first and last point of the sub-polygon's point sequence are not the same. This make it very easy to convert between polygons and prisms. Quadratic, cubic and bezier splines are never automatically closed.

In the quadratic_spline, each sub-prism needs an additional control point at the beginning of each sub-prisms' point sequence to determine the slope at the start of the curve. The first point specified is the control point which is not actually part of the spline. The second point is the start of the spline. The sub-prism ends when this second point is duplicated. The next point is the control point of the next sub-prism. The point after that is the first point of the second sub-prism. Here is an example:

 prism {
   quadratic_spline
   0, 1, 12,
   <1,-1>, <0,0>, <6,0>, //outer rim; <1,-1> is control point and 
   <6,8>, <0,8>, <0,0>,  //<0,0> is first & last point

   <2,0>, <1,1>, <5,1>,  //inner rim; <2,0> is control point and 
   <5,7>, <1,7>, <1,1>   //<1,1> is first & last point
 }

In the cubic_spline, each sub-prism needs two additional control points -- one at the beginning of each sub-prisms' point sequence to determine the slope at the start of the curve and one at the end. The first point specified is the control point which is not actually part of the spline. The second point is the start of the spline. The sub-prism ends when this second point is duplicated. The next point is the control point of the end of the first sub-prism. Next is the beginning control point of the next sub-prism. The point after that is the first point of the second sub-prism.

Here is an example:

 prism {
   cubic_spline
   0, 1, 14,
   <1,-1>, <0,0>, <6,0>, //outer rim; First control is <1,-1> and
   <6,8>, <0,8>, <0,0>,  //<0,0> is first & last point.
   <-1,1>,               //Last control of first spline is <-1,1>

   <2,0>, <1,1>, <5,1>,  //inner rim; First control is <2,0> and 
   <5,7>, <1,7>, <1,1>,  //<1,1> is first & last point
   <0,2>                 //Last control of first spline is <0,2>
 }

The bezier_spline is an alternate kind of cubic spline. Points 1 and 4 specify the end points of a segment and points 2 and 3 are control points which specify the slope at the endpoints. Points 2 and 3 do not actually lie on the spline. They adjust the slope of the spline. If you draw an imaginary line between point 1 and 2, it represents the slope at point 1. It is a line tangent to the curve at point 1. The greater the distance between 1 and 2, the flatter the curve. With a short tangent the spline can bend more. The same holds true for control point 3 and endpoint 4. If you want the spline to be smooth between segments, point 3 and 4 on one segment and point 1 and 2 on the next segment must form a straight line and point 4 of one segment must be the same as point one on the next segment.

By default linear sweeping is used to create the prism, i.e. the prism's walls are perpendicular to the x-z-plane (the size of the curve does not change during the sweep). You can also use conic_sweep that leads to a prism with cone-like walls by scaling the curve down during the sweep.

Like cylinders the prism is normally closed. You can remove the caps on the prism by using the open keyword. If you do so you shouldn't use it with CSG because the results may get wrong.

For an explanation of the spline concept read the description of the "Lathe" object. Also see the tutorials on "Lathe Object" and "Prism Object".

The sturm keyword specifies the slower but more accurate Sturmian root solver which may be used with the cubic or bezier spline prisms if the shape does not render properly. The linear and quadratic spline prisms do not need the Sturmian root solver.

6.5.1.9 Sphere

The syntax of the sphere object is:

SPHERE:
    sphere
    {
        <Center>, Radius
        [OBJECT_MODIFIERS...]
    }

The geometry of a sphere

Where <Center> is a vector specifying the x, y, z coordinates of the center of the sphere and Radius is a float value specifying the radius. Spheres may be scaled unevenly giving an ellipsoid shape.

Because spheres are highly optimized they make good bounding shapes (if manual bounding seems to be necessary).

6.5.1.10 Spheresweep

The syntax of the sphere_sweep object is:

SPHERE_SWEEP:
sphere_sweep {
  linear_spline | b_spline | cubic_spline
  NUM_OF_SPHERES,

  CENTER, RADIUS,
  CENTER, RADIUS,
  ...
  CENTER, RADIUS
  [tolerance DEPTH_TOLERANCE]
  [OBJECT_MODIFIERS]
}

Sphere_sweep default values:

tolerance : 1.0e-6 (0.000001)

A Sphere Sweep is the envelope of a moving sphere with varying radius, or, in other words, the space a sphere occupies during its movement along a spline.
Sphere Sweeps are modeled by specifying a list of single spheres which are then interpolated.
Three kinds of interpolation are supported:

linear_spline : Interpolating the input data with a linear function, which means that the single spheres are connected by straight tubes.
b_spline : Approximating the input data using a cubic b-spline function, which results in a curved object.
cubic_spline : Approximating the input data using a cubic spline, which results in a curved object.

The sphere list (center and radius of each sphere) can take as many spheres as you like to describe the object, but you will need at least two spheres for a linear_spline, and four spheres for b_spline or cubic_spline.

Optional: The depth tolerance that should be used for the intersection calculations. This is done by adding the tolerance keyword and the desired value: the default distance is 1.0e-6 (0.000001) and should do for most sphere sweep objects.
You should change this when you see dark spots on the surface of the object. These are probably caused by an effect called "Self-Shading". This means that the object casts shadows onto itself at some points because of calculation errors. A ray tracing program usually defines the minimal distance a ray must travel before it actually hits another (or the same) object to avoid this effect. If this distance is chosen too small, Self-Shading may occur.
If so, specify tolerance 1.0e-4 or higher.

Note: if these dark spots remain after raising the tolerance, you might get rid of these spots by using Adaptive Supersampling (Method 2) for antialiasing. Images look better with antialiasing anyway.

Note: the merge CSG operation is not recommended with Sphere Sweeps: there could be a small gap between the merged objects!

6.5.1.11 Superquadric Ellipsoid

The superellipsoid object creates a shape known as a superquadric ellipsoid object. It is an extension of the quadric ellipsoid. It can be used to create boxes and cylinders with round edges and other interesting shapes. Mathematically it is given by the equation:

The values of e and n, called the east-west and north-south exponent, determine the shape of the superquadric ellipsoid. Both have to be greater than zero. The sphere is given by e = 1 and n = 1.

The syntax of the superquadric ellipsoid is:

SUPERELLIPSOID:
    superellipsoid
    {
        <Value_E, Value_N>
        [OBJECT_MODIFIERS...]
    }

The 2-D vector specifies the e and n values in the equation above. The object sits at the origin and occupies a space about the size of a box{<-1,-1,-1>,<1,1,1>}.

Two useful objects are the rounded box and the rounded cylinder. These are declared in the following way.

 #declare Rounded_Box = superellipsoid { <Round, Round> }
 #declare Rounded_Cylinder = superellipsoid { <1, Round> }

The roundedness value Round determines the roundedness of the edges and has to be greater than zero and smaller than one. The smaller you choose the values, the smaller and sharper the edges will get.

Very small values of e and n might cause problems with the root solver (the Sturmian root solver cannot be used).

6.5.1.12 Surface of Revolution

The sor object is a surface of revolution generated by rotating the graph of a function about the y-axis. This function describes the dependence of the radius from the position on the rotation axis. The syntax is:

SOR:
    sor
    {
        Number_Of_Points, <Point_1>, <Point_2>, ... <Point_n>
        [ open ] [SOR_MODIFIERS...]
    }
SOR_MODIFIER:
    sturm | OBJECT_MODIFIER

SOR default values:

sturm : off

The float value Number_Of_Points specifies the number of 2-D vectors which follow. The points <Point_1> through <Point_n> are two-dimensional vectors consisting of the radius and the corresponding height, i.e. the position on the rotation axis. These points are smoothly connected (the curve is passing through the specified points) and rotated about the y-axis to form the SOR object. The first and last points are only used to determine the slopes of the function at the start and end point. They do not actually lie on the curve. The function used for the SOR object is similar to the splines used for the lathe object. The difference is that the SOR object is less flexible because it underlies the restrictions of any mathematical function, i.e. to any given point y on the rotation axis belongs at most one function value, i.e. one radius value. You can't rotate closed curves with the SOR object. Also, make sure that the curve does not cross zero (y-axis) as this can result in 'less than perfect' bounding cylinders. POV-Ray will very likely fail to render large chunks of the part of the spline contained in such an interval.

The optional keyword open allows you to remove the caps on the SOR object. If you do this you shouldn't use it with CSG because the results may be wrong.

The SOR object is useful for creating bottles, vases, and things like that. A simple vase could look like this:

 #declare Vase = sor {
  7,
  <0.000000, 0.000000>
  <0.118143, 0.000000>
  <0.620253, 0.540084>
  <0.210970, 0.827004>
  <0.194093, 0.962025>
  <0.286920, 1.000000>
  <0.468354, 1.033755>
  open
 }

One might ask why there is any need for a SOR object if there is already a lathe object which is much more flexible. The reason is quite simple. The intersection test with a SOR object involves solving a cubic polynomial while the test with a lathe object requires to solve a 6th order polynomial (you need a cubic spline for the same smoothness). Since most SOR and lathe objects will have several segments this will make a great difference in speed. The roots of the 3rd order polynomial will also be more accurate and easier to find.

The sturm keyword may be added to specify the slower but more accurate Sturmian root solver. It may be used with the surface of revolution object if the shape does not render properly.

The following explanations are for the mathematically interested reader who wants to know how the surface of revolution is calculated. Though it is not necessary to read on it might help in understanding the SOR object.

The function that is rotated about the y-axis to get the final SOR object is given by

with radius r and height h. Since this is a cubic function in h it has enough flexibility to allow smooth curves.

The curve itself is defined by a set of n points P(i), i=0...n-1, which are interpolated using one function for every segment of the curve. A segment j, j=1...n-3, goes from point P(j) to point P(j+1) and uses points P(j-1) and P(j+2) to determine the slopes at the endpoints. If there are n points we will have n-3 segments. This means that we need at least four points to get a proper curve. The coefficients A(j), B(j), C(j) and D(j) are calculated for every segment using the equation

where r(j) is the radius and h(j) is the height of point P(j).

The figure below shows the configuration of the points P(i), the location of segment j, and the curve that is defined by this segment.

Points on a surface of revolution

6.5.1.13 Text

A text object creates 3-D text as an extruded block letter. Currently only TrueType fonts (ttf) and TrueType Collections (ttc) are supported but the syntax allows for other font types to be added in the future. If TrueType Collections are used, the first font found in the collection will be used. The syntax is:

TEXT_OBECT:
  text {
    ttf "fontname.ttf/ttc" "String_of_Text"
	Thickness, <Offset>
    [OBJECT_MODIFIERS...]
  }

Where fontname.ttf or fontname.ttc is the name of the TrueType font file. It is a quoted string literal or string expression. The string expression which follows is the actual text of the string object. It too may be a quoted string literal or string expression. See section "Strings" for more on string expressions.

The text will start with the origin at the lower left, front of the first character and will extend in the +x-direction. The baseline of the text follows the x-axis and descender drop into the -y-direction. The front of the character sits in the x-y-plane and the text is extruded in the +z-direction. The front-to-back thickness is specified by the required value Thickness.

Characters are generally sized so that 1 unit of vertical spacing is correct. The characters are about 0.5 to 0.75 units tall.

The horizontal spacing is handled by POV-Ray internally including any kerning information stored in the font. The required vector <Offset> defines any extra translation between each character. Normally you should specify a zero for this value. Specifying 0.1*x would put additional 0.1 units of space between each character. Here is an example:

  text {
    ttf "timrom.ttf" "POV-Ray" 1, 0
    pigment { Red }
  }

Only printable characters are allowed in text objects. Characters such as return, line feed, tabs, backspace etc. are not supported.

For easy access to your fonts, set the Library_Path to the directory that contains your font collection.

6.5.1.14 Torus

A torus is a 4th order quartic polynomial shape that looks like a donut or inner tube. Because this shape is so useful and quartics are difficult to define, POV-Ray lets you take a short-cut and define a torus by:

TORUS:
    torus
    {
        Major, Minor
        [TORUS_MODIFIER...]
    }
TORUS_MODIFIER:
    sturm | OBJECT_MODIFIER

Torus default values:

sturm : off

where Major is a float value giving the major radius and Minor is a float specifying the minor radius. The major radius extends from the center of the hole to the mid-line of the rim while the minor radius is the radius of the cross-section of the rim. The torus is centered at the origin and lies in the x-z-plane with the y-axis sticking through the hole.

Major and minor radius of a torus

The torus is internally bounded by two cylinders and two rings forming a thick cylinder. With this bounding cylinder the performance of the torus intersection test is vastly increased. The test for a valid torus intersection, i.e. solving a 4th order polynomial, is only performed if the bounding cylinder is hit. Thus a lot of slow root solving calculations are avoided.

Calculations for all higher order polynomials must be very accurate. If the torus renders improperly you may add the keyword sturm to use POV-Ray's slower-yet-more-accurate Sturmian root solver.

6.5.1 Finite Solid Primitives