3.4 Objects 
POVRay 3.6 for UNIX documentation 3.4.1 Finite Solid Primitives 
3.4.2 Finite Patch Primitives 
There are fourteen different solid finite primitive shapes: blob, box, cone, cylinder, height field, Julia fractal, lathe, prism, sphere, spheresweep, superellipsoid, surface of revolution, text object and torus. These have a welldefined inside and can be used in CSG (see section "Constructive Solid Geometry"). They are finite and respond to automatic bounding. You may specify an interior for these objects.
Blobs are an interesting and flexible object type. Mathematically they are isosurfaces 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 are on the surface otherwise you are 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 POVRay 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
hierarchy : on sturm : off threshold : 1.0
The threshold
keyword is followed by a float value which determines the total field strength value
that POVRay 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, POVRay 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.
Cylindrical components are specified by a cylinder
statement. The center of the endcaps 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 POVRay
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.
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 POVRay's sloweryetmoreaccurate 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 POVRay to create blobs. You do not need to understand this to use blobs. The density of the blob field of a single component is:
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.
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...] }
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).
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...] }
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.
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...] }
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.
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  function HF_MODIFIER: hierarchy [Boolean]  smooth  water_level Level
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 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 (N1)*(M1)
squares that are divided into 2*(N1)*(M1)
triangles.
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 zdirection. A larger image uses more triangles and looks smoother. The resolution of the color/index value determines the resolution along the yaxis. A height field made from an 8bit image can have 256 different height levels while one made from a 16bit image can have up to 65536 different height levels. Thus the second height field will look much smoother in the ydirection if the height field is created appropriately.
The size/resolution of the image does not affect the size of the height field. The unscaled 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 useful when the source for the height_field
is also generated with POVRay.
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 will not be of much use for creating the special 16 bit TGA files used by POVRay (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 POVRay.
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 MSDos/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 custommade 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 16bit 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 POVRay to only render the top half of the height field. The other
half is below the water and could not 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 raytracer 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 POVRay 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.
A julia fractal object is a 3D slice of a 4D 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 )
ALGEBRA_TYPE : quaternion FUNCTION_TYPE : sqr max_iteration : 20 precision : 20 slice, DISTANCE : <0,0,0,1>, 0.0
The required 4D 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 4D 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_iteration1)
where p
is
the fixed 4D 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
fourdimensional and POVRay 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 4D fractal with a 3D
"plane" defined by the slice
modifier and then projecting the intersection to 3D space. The
keyword is followed by 4D vector and a float separated by a comma. The slice plane is the 3D 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 POVRay'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 3D 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 4D algebra is used to
calculate the fractal. The default is quaternion
. Both are 4D 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 noncommutative multiplication and hypercomplex numbers can fail to have a
multiplicative inverse for some nonzero 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.
ij = k

jk = i

ki = j

ji = k

kj = i

ik = j

ii = jj = kk = 1

ijk = 1

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 4D value h to:
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 POVRay 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!
The lathe
is an object generated from rotating a twodimensional 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
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 twodimensional points are used
to define the curve. The points follow and are specified by 2D 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 yaxis 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 yaxis.
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 2D
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 n1 segments connecting the points P[i], i=1,...,n. A quadratic spline gives you n2 segments because the last point is only used for determining the slope, as explained above (thus you will need at least three points to define a quadratic spline). The same holds for cubic splines where you get n3 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[n1] = P[2] (to get a closed curve), P[n] = P[3] and P[n2] = P[1] (to smooth the transition). In the quadratic case P[n1] = P[1] (to close the curve) and P[n] = P[2].
The prism
is an object generated specifying one or more twodimensional, closed curves in the xz
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
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 2D 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 2D vectors which define the shape in the xz plane.
The interpretation of the points depends on the spline type. The prism object allows you to use any number of subprisms inside one prism statement (they are of the same spline and sweep type). Wherever an even number of subprisms overlaps a hole appears.
Note: you need not have multiple subprisms and they need not overlap as these examples do.
In the linear_spline
the first point specified is the start of the first subprism. The following
points are connected by straight lines. If you specify a value identical to the first point, this closes the subprism
and next point starts a new one. When you specify the value of that subprism's start, then it is closed. Each of the
subprisms has to be closed by repeating the first point of a subprism at the end of the subprism's point sequence.
In this example, there are two rectangular subprisms 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 subprism of a linear spline prism is automatically closed  just like the last subpolygon in the polygon statement  if the first and last point of the subpolygon'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 subprism needs an additional control point at the beginning of each
subprisms' 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 subprism ends when
this second point is duplicated. The next point is the control point of the next subprism. The point after that is
the first point of the second subprism. 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 subprism needs two additional control points  one at the beginning of
each subprisms' 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 subprism ends when this second point is duplicated. The next point is the control point of the end of the first
subprism. Next is the beginning control point of the next subprism. The point after that is the first point of the
second subprism.
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 xzplane
(the size of the curve does not change during the sweep). You can also use conic_sweep
that leads to a
prism with conelike 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 should not 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.
The syntax of the sphere
object is:
SPHERE: sphere { <Center>, Radius [OBJECT_MODIFIERS...] }
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).
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] }
tolerance : 1.0e6 (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 bspline 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.0e6 (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
"SelfShading". 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, SelfShading may occur.
If so,
specify tolerance 1.0e4
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!
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 eastwest and northsouth
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 2D 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).
The sor
object is a surface of revolution generated by rotating the graph of a function about
the yaxis. 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
sturm : off
The float value Number_Of_Points
specifies the number of 2D vectors which follow. The points
<Point_1>
through <Point_n>
are twodimensional 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 yaxis 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 cannot rotate
closed curves with the SOR object. Also, make sure that the curve does not cross zero (yaxis) as this can result in
'less than perfect' bounding cylinders. POVRay 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 should
not 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 yaxis 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...n1, which are interpolated using one function for every segment of the curve. A segment j, j=1...n3, goes from point P(j) to point P(j+1) and uses points P(j1) and P(j+2) to determine the slopes at the endpoints. If there are n points we will have n3 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.
A text
object creates 3D 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
+xdirection. The baseline of the text follows the xaxis and descender drop into the ydirection. The front of the
character sits in the xyplane and the text is extruded in the +zdirection. The fronttoback 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 POVRay 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" "POVRay" 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.
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, POVRay lets you take a shortcut and define a torus by:
TORUS: torus { Major, Minor [TORUS_MODIFIER...] } TORUS_MODIFIER: sturm  OBJECT_MODIFIER
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 midline of the rim
while the minor radius is the radius of the crosssection of the rim. The torus is centered at the origin and lies in
the xzplane with the yaxis sticking through the hole.
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 POVRay's sloweryetmoreaccurate Sturmian root
solver.
3.4 Objects  3.4.1 Finite Solid Primitives  3.4.2 Finite Patch Primitives 