# The Online POV-Ray Tutorial

## CSG Reference

CSG (Constructive Solid Geometry) is used to combine simple objects to form potentially very complex ones. CSG allows you to merge objects into one and carve away parts of objects with other objects. Any object (just about) can appear in a CSG object, including other CSG objects. There's no limit on the number of objects that can appear in a CSG object, but POV-Ray will complain a little if you don't have at least two objects in a CSG object.

The following topics are covered in this section.

This small collect of objects will do nicely in assisting if our exaplanation of the wonders of CSG.

## Difference

A difference is used to take an object and carve shapes out of it. Specifying a difference is no different from specifying any other CSG object (see union) The first object specified is the object you're carving from, and all subsequent objects are used to carve away sections from the first object. Somewhat more specifically, any parts of the first object that are "inside" any of the other objects are trimmed away. Difference is the only CSG object in which the order of the objects is important. The concept of the "inside" and "outside" of an object can be altered with the inverse keyword. Here's what it looks line when group the cylinder and the box together in a difference statement.

First off, note that this is a different viewing angle from the initial sample scene. This is to make it more obvious what the difference did. Note that the scene is a cube with some interesting sections taken out of it. This is because the box object was the first one listed in the difference (see the source). Also notice how the different parts of the now scarred cube are different colors. When you do a difference operation, the surface is colored based on which object acutally "created" that surface. So the hole through the center of the box is green because it was made with the green cylinder. If you wanted the entire surface to be all one color, you could either change each individual texture to the same, or you could remove all the textures on the individual objects, and just put one inside the difference.

See union for more detailed information on declaring CSG objects.

## Intersection

The intersection of two or more objects is composed of all the points that are inside all the objects. The order of the objects listed in the declaration is not important. You can think of intersection as (sort of) the opposite of a difference. Instead of carving away points that are inside the objects (like difference), intersection throws out regions that are outside of subsequent objects. POV-Ray's concept of "inside" and "outside" can be changed by adding the keyword inverse to an object. But anyway, here's what results if we group our unsuspecting test objects together in an intersection.

The result is a cylinder with sort of "squared off" ends. That volume corresponds to the space which is contained inside both of those objects. You can see which object was defining each boundary by the color of the result. Anywhere that is green is on the boundary of the cylinder and anything that is red is on the boundary of the box. Admittedly, this particular thing isn't too useful, but intersection, along with its close relative, difference, is probably the most powerful CSG directive for creating new and interesting objects.

See union for more detailed information on declaring CSG objects.

## Inverse

The inverse keyword can be added to any finite, infinite, or CSG object. It basically reverses the regions that POV-Ray considers to be the inside and outside of the object. This only really matters in CSG differences and intersections. It can also be used in clipping objects. For an example of the use of inverse, check out these two images.

See the difference (no pun intended)? If you did, then there's something wrong. The only difference between between these two scenes is in the source. They render to the same image. One (the first) uses a difference, while the other (the second) uses an intersection. The reason they look the same is the second and third object in the second scene were inverted (don't just trust me, see for yourself). Remember how difference and intersection work. Difference carves away insides, and intersection carves away outsides. But by flipping the insides and outsides in the intersection, it, too, is effectively carving away outsides. In fact, difference is implemented in POV-Ray as an intersection with the second through nth objects inverted.

Here's an image which should make inverse more understandable. In this intersection, the box is inverted, so only regions outside the box and inside the cylinder remain.

## Merge

Merge is very similar to union. It basically serves the same purpose; it joins a group of objects together into one for whatever purpose. Merge, however, differs from union in that any surfaces which are inside the object are removed. This doesn't matter in opaque objects, as internal surfaces aren't visible anyway. However, it is very important in objects that have transparency. In unions, internal surfaces of transparent objects will be visible, and this can cause unwanted artifacts. Using merge to join these objects will solve these problems, though. Here's our sample scene again, substantially modified, but hopefully still recognizable. Actually, the objects are the same, except for their pigments. A finish was added to make the objects look like glass. The first image shows the objects unioned, the second shows them merged.

Note how in the first image, the outline of the cylinder is clearly visible inside the box. In the second, this object is gone. The combined objects are now acutally a single, continuous unit.

One very important thing to keep in mind when creating merge objects is that coincident surfaces (surfaces which touch exactly at more than just a point or a line) will cause very strange errors in your object. Sections of the object will be randomly invisible, and things will be generally very twisted. For example, doing the following is bad.

```merge {
cylinder {
<0, 0, 0>, <0, 3, 0>, 3
}
cone {
<0, 3, 0>, 3,
<0, 6, 0>, 0
}
texture { SomeTexture }
}
```

Note how the top of the cylinder and the bottom of the cone are the same. This is bad. Note that this will not always render incorrectly. Sometimes it'll come out ok, and sometimes it won't. C programmers will understand when we say that "the results will be undefined."

```merge {
cylinder {
<0, 0, 0>, <0, 3, 0>, 3
}
cone {
<0, 2.99, 0>, 3,
<0, 6, 0>, 0
}
texture { SomeTexture }
}
```

Now the two objects overlap a bit. This is just enough to fix the problem, and won't impact the appearance of the object appreciably.

See union for more detailed information on declaring CSG objects.

## Union

Union is used to combine groups of objects together into one logical object. This object can then be textured and transformed as a whole, so you don't have to deal with a bunch of little objects. The basic form for a union (or any CSG) is as follows

```union {
object { obj 1 }
object { obj 2 }
/* you can have as many objects as you wish */
object { obj n }
/* here go any textures, rotations, translations, and scales. */
}
```

Of course, if you want a difference, intersection, or merge, you should change the "union" above to the appropriate identifier.

Any object, whether finite, infinite, or CSG, can be used in a union. There are restrictions on objects in the other types of CSG, though. Any object used in an intersection, merge, or difference must have a clearly defined inside. Objects like triangles don't have insides, and so can only be used in unions, not the others. You can use clipping to simulate these operations on flat objects, though.

Unions are wonderful for creating coherent objects. For example, you can create an object with a great many components and group them all together into a union. After that, you can transform them by transforming the union instead of having to transform all the individual objects. You can also easily texture the objects as one. One thing to remember when texturing CSG objects, though, is that a texture for a specific object in a CSG will override any texture specified for the CSG object itself.

Here is the sample scene with the objects joined together in a union.

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