### Section 7.5.1
Empty and Solid Objects

It is very important that you know the basic concept behind empty and solid objects in POV-Ray to fully understand how features like halos and translucency are used.

Objects in POV-Ray can either be solid, empty or filled with (small) particles.

A solid object is made from the material specified by its pigment and finish statements (and to some degree its normal statement). By default all objects are assumed to be solid. If you assign a stone texture to a sphere you'll get a ball made completely of stone. It's like you had cut this ball from a block of stone. A glass ball is a massive sphere made of glass.

You should be aware that solid objects are conceptual things. If you e. g. clip away parts of the sphere you'll see that the sphere is empty, i. e. you'll clearly see that the interior is empty and it just has a very thin surface.

This is not contrary to the concept of a solid object used in POV-Ray. It is assumed that all space inside the sphere is covered by the sphere's material. Thus there is no room for any other particles like those used by fog or halos.

Empty objects are created by adding the hollow keyword (see "Hollow") to the object statement. An empty (or hollow) object is assumed to be made of a very thin surface which is of the material specified by the pigment, finish and normal statements. The object's interior is empty, i. e. it normally contains air molecules.

An empty object can be filled with particles by adding fog or atmosphere to the scene or by adding a halo to the object. It is very important to understand that in order to fill an object with any kind of particles it first has to be made hollow.

### Section 7.5.1.1
Halo Pitfall

There is a pitfall in the current empty/solid object implementation that you have to be aware of.

In order to be able to put solid objects inside a halo (this also holds for fog and atmosphere) a test has to be made for every ray that passes through the halo. If this ray travels through a solid object the halo will not be calculated. This is what anyone will expect.

The problem arises when the camera ray is inside any non-hollow object. In this case the ray is already traveling through a solid object and even if the halo's container object is hit and it is hollow, the halo will not be calculated. There is no way of telling between these two cases.

POV-Ray has to determine whether the camera is inside any object prior to tracing a camera ray in order to be able to correctly render halos when the camera is inside the container object. There's no way around doing this.

The solution to this problem (that will often happen with infinite objects like planes) is to make those objects hollow too. Thus the ray will travel through a hollow object, will hit the container object and the halo will be calculated.

Note that the above is also true for atmosphere and fog.

### Section 7.5.1.2
Refraction Pitfall

There is a pitfall in the way refractive (and non-refractive translucent) objects are handled.

Imagine you want to create an object that's partially made of glass and stone. You'd use something like the following merge because you don't want to see any inside surfaces.

      merge {
        sphere { <-1,0,0>, 2 texture { Stone } }
        sphere { <+1,0,0>, 2 texture { Glass } }
      }

What's wrong with this, you may ask? The problem is that there is no way of telling what the interior of the actual object will look like. This is not a problem of POV-Ray, it's a general problem. You can't define the interior of any object in a surface based model. You would have to create some (complex) rules to decide what the interior will look like. Is it made of stone? Is it made of glass? Is it made of some bizarre mixture between glass and stone? Is it half stone and half glass? Where is the boundary between the two materials and what does it look like?

You will not be able to answer any of the above questions by just looking at the above object. You need more information.

If you wanted to create an object made half of stone and half of glass you would have used the following statements.

      union {
        intersection {
          sphere { <-1,0,0>, 2 }
          plane { x, 0 }
          texture { Stone }
        }
        intersection {
          sphere { <+1,0,0>, 2 }
          plane { x, 0 inverse }
          texture { Glass }
        }
      }

This example is correct because there is one object made only of stone and one made only of glass.

You should never use objects whose interior is not well defined, i. e. there must not be different textures for the object having different refractive (and translucent) properties. You should be aware that this holds only for the lowest layer if you use layered textures.

See also "Halo Pitfall" for a similar problem with halos.

### Section 7.5.2
Finite Solid Primitives

There are twelve different solid finite primitive shapes: blob, box, cone, cylinder, fractal, height field, lathe, sphere, superellipsoid, surface of revolution, text object and torus. These have a well-defined inside and can be used in CSG (see section "Constructive Solid Geometry"). They are finite and respond to automatic bounding. As with all shapes they can be translated, rotated and scaled.

### Section 7.5.2.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 like that.

A blob is made up of spherical and cylindrical components and is defined as follows:

      blob {
        threshold THRESHOLD_VALUE
        cylinder { <END1>, <END2>, RADIUS, [ strength ] STRENGTH }
        sphere { <CENTER>, RADIUS, [ strength ] STRENGTH }
        [ component STRENGTH, RADIUS, <CENTER> ]
        [ hierarchy FLAG ]
        [ sturm ]
      }

The threshold keyword determines the total field strength value that POV-Ray is looking for. 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.

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

Cylindrical components are specified by the keyword cylinder giving a cylinder formed by the base <END1>, the apex <END2> and the radius. The cylinder has hemispherical caps at the base and apex. Spherical components are specified by the keyword sphere forming a sphere at <CENTER> with the given radius. Each component can be individually translated, rotated, scaled and textured. The complete syntax for the cylindrical and spherical components is:

      sphere { <CENTER>, RADIUS, [strength] STRENGTH
        [ translate <VECTOR> ]
        [ rotate <VECTOR> ]
        [ scale <VECTOR> ]
        TEXTURE_MODIFIERS
      }

      cylinder { <END1>, <END2>, RADIUS, [strength] STRENGTH
        [ translate <VECTOR> ]
        [ rotate <VECTOR> ]
        [ scale <VECTOR> ]
        TEXTURE_MODIFIERS
      }

By unevenly scaling a spherical component you can create ellipsoidal components. The component keyword gives a spherical component and is only used for compatibility with earlier POV-Ray versions.

The strength parameter 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.

1) | 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.
2) | 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.
3) | 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. What happens is that the surface around any nearby positive components will be dented away from the center of the negative component.

The components of each blob object are internally bounded by a spherical bounding hierarchy to speed up blob intersection tests and other operations. By using the optional keyword hierarchy you can switch this hierarchy off.

An example of a three component blob is:

      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 formula used for a single blob component is:

      density = strength * (1 - radius^2)^2

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:

      density = density1 + density2 + ...

The calculations for blobs must be very accurate. If this shape renders improperly you may add the keyword sturm after the last component to use POV-Ray's slower-yet-more-accurate Sturmian root solver.

### Section 7.5.2.2
Box

A simple box can be defined by listing two corners of the box like this:

      box { <CORNER1>, <CORNER2> }

The geometry of a box.

Where <CORNER1> and <CORNER2> 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.

Each element of <CORNER1> should always be less than the corresponding element in <CORNER2>. If any elements of <CORNER1> are larger than <CORNER2> the box will not appear in the scene.

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

### Section 7.5.2.3
Cone

A finite length cone or a frustum (a cone with the point cut off) may be defined by.

      cone {
        <BASE_POINT>, BASE_RADIUS, <CAP_POINT>, CAP_RADIUS
        [ open ]
      }

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 planes which 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.

### Section 7.5.2.4
Cylinder

A finite length cylinder with parallel end caps may be defined by.

      cylinder {
        <BASE_POINT>, <CAP_POINT>, RADIUS
        [ open ]
      }

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 planes which 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.

### Section 7.5.2.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 syntax is:

      height_field {
        FILE_TYPE "FILENAME"
        [ hierarchy BOOL ]
        [ smooth BOOL ]
        [ water_level FLOAT ]
      }

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.

Four pixels of an image and the resulting heights and triangles in the 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* 1. Higher resolution image files will create smaller triangles, not larger height fields.

There are six or possibly seven types of files which can define a heightfield, as follows:

      height_field { gif "filename.gif" }
      height_field { pgm "filename.pgm" }
      height_field { png "filename.png" }
      height_field { pot "filename.pot" }
      height_field { ppm "filename.ppm" }
      height_field { sys "filename.???" }
      height_field { tga "filename.tga" }

The image file used to create a height field can be a GIF, TGA, POT, PNG, PGM, PPM and possibly a system specific (e. g. Windows BMP or Macintosh Pict) format file. The GIF, PNG, PGM and possibly system 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 like GIF that uses a color palette 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 that 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 IBM-PC 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.

An 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 .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. 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 .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.

In order to speed up the intersection tests an one-level bounding hierarchy is available. By default it is always used but it can be switched off to eventually improve the rendering speed for small height fields (i. e. low resolution images).

Next Section
Table Of Contents