### 2.2.3 CSG Objects

You know you have been raytracing too long when ...
... Your friends are used to the fact that you will suddenly stop walking in order to look at objects and figure out how to do them as CSGs.
  -- Jeff Lee

Constructive Solid Geometry, or CSG, is a powerful tool to combine primitive objects to create more complex objects as shown in the following sections.

#### 2.2.3.1 What is CSG?

CSG stands for Constructive Solid Geometry. POV-Ray allows us to construct complex solids by combining primitive shapes in four different ways. In the `union` statement, two or more shapes are added together. With the `intersection` statement, two or more shapes are combined to make a new shape that consists of the area common to both shapes. The `difference` statement, an initial shape has all subsequent shapes subtracted from it.

And last but not least `merge`, which is like a union where the surfaces inside the union are removed (useful in transparent CSG objects). We will deal with each of these in detail in the next few sections.

CSG objects can be extremely complex. They can be deeply nested. In other words there can be unions of differences or intersections of merges or differences of intersections or even unions of intersections of differences of merges... ad infinitum. CSG objects are (almost always) finite objects and thus respond to auto-bounding and can be transformed like any other POV primitive shape.

#### 2.2.3.2 CSG Union

Let's try making a simple union. Create a file called `csgdemo.pov` and edit it as follows:

      #include "colors.inc"
      camera {
        location <0, 1, -10>
        look_at 0
        angle 36
      }
      light_source { <500, 500, -1000> White }
      plane { y, -1.5
        pigment { checker Green White }
      }

Let's add two spheres each translated 0.5 units along the x-axis in each direction. We color one blue and the other red.

      sphere { <0, 0, 0>, 1
        pigment { Blue }
        translate -0.5*x
      }
      sphere { <0, 0, 0>, 1
        pigment { Red }
        translate 0.5*x
      }

We trace this file and note the results. Now we place a union block around the two spheres. This will create a single CSG union out of the two objects.

      union{
        sphere { <0, 0, 0>, 1
          pigment { Blue }
          translate -0.5*x
        }
        sphere { <0, 0, 0>, 1
          pigment { Red }
          translate 0.5*x
        }
      }

We trace the file again. The union will appear no different from what each sphere looked like on its own, but now we can give the entire union a single texture and transform it as a whole. Let's do that now.

      union{
        sphere { <0, 0, 0>, 1
          translate -0.5*x
        }
        sphere { <0, 0, 0>, 1
          translate 0.5*x
        }
        pigment { Red }
        scale <1, .25, 1>
        rotate <30, 0, 45>
      }

We trace the file again. As we can see, the object has changed dramatically. We experiment with different values of scale and rotate and try some different textures.

There are many advantages of assigning only one texture to a CSG object instead of assigning the texture to each individual component. First, it is much easier to use one texture if our CSG object has a lot of components because changing the objects appearance involves changing only one single texture. Second, the file parses faster because the texture has to be parsed only once. This may be a great factor when doing large scenes or animations. Third, using only one texture saves memory because the texture is only stored once and referenced by all components of the CSG object. Assigning the texture to all n components means that it is stored n times.

#### 2.2.3.3 CSG Intersection

Now let's use these same spheres to illustrate the`intersection` CSG object. We change the word `union` to `intersection` and delete the `scale` and `rotate` statements:

      intersection {
        sphere { <0, 0, 0>, 1
          translate -0.5*x
        }
        sphere { <0, 0, 0>, 1
          translate 0.5*x
        }
        pigment { Red }
      }

We trace the file and will see a lens-shaped object instead of the two spheres. This is because an intersection consists of the area shared by both shapes, in this case the lens-shaped area where the two spheres overlap. We like this lens-shaped object so we will use it to demonstrate differences.

#### 2.2.3.4 CSG Difference

We rotate the lens-shaped intersection about the y-axis so that the broad side is facing the camera.

      intersection{
        sphere { <0, 0, 0>, 1
          translate -0.5*x
        }
        sphere { <0, 0, 0>, 1
          translate 0.5*x
        }
        pigment { Red }
        rotate 90*y
      }

Let's create a cylinder and stick it right in the middle of the lens.

      cylinder { <0, 0, -1> <0, 0, 1>, .35
        pigment { Blue }
      }

We render the scene to see the position of the cylinder. We will place a `difference` block around both the lens-shaped intersection and the cylinder like this:

      difference {
        intersection {
          sphere { <0, 0, 0>, 1
            translate -0.5*x
          }
          sphere { <0, 0, 0>, 1
            translate 0.5*x
          }
          pigment { Red }
          rotate 90*y
        }
        cylinder { <0, 0, -1> <0, 0, 1>, .35
          pigment { Blue }
        }
      }

We render the file again and see the lens-shaped intersection with a neat hole in the middle of it where the cylinder was. The cylinder has been `subtracted` from the intersection. Note that the pigment of the cylinder causes the surface of the hole to be colored blue. If we eliminate this pigment the surface of the hole will be black, as this is the default color if no color is specified.

OK, let's get a little wilder now. Let's declare our perforated lens object to give it a name. Let's also eliminate all textures in the declared object because we will want them to be in the final union instead.

      #declare Lens_With_Hole = difference {
        intersection {
          sphere { <0, 0, 0>, 1
            translate -0.5*x
          }
          sphere { <0, 0, 0>, 1
            translate 0.5*x
          }
          rotate 90*y
        }
        cylinder { <0, 0, -1> <0, 0, 1>, .35 }
      }

Let's use a union to build a complex shape composed of copies of this object.

      union {
        object { Lens_With_Hole translate <-.65, .65, 0> }
        object { Lens_With_Hole translate <.65, .65, 0> }
        object { Lens_With_Hole translate <-.65, -.65, 0> }
        object { Lens_With_Hole translate <.65, -.65, 0> }
        pigment { Red }
      }

We render the scene. An interesting object to be sure. But let's try something more. Let's make it a partially-transparent object by adding some filter to the pigment block.

      union {
        object { Lens_With_Hole translate <-.65, .65, 0> }
        object { Lens_With_Hole translate <.65, .65, 0> }
        object { Lens_With_Hole translate <-.65, -.65, 0> }
        object { Lens_With_Hole translate <.65, -.65, 0> }
        pigment { Red filter .5 }
      }

We render the file again. This looks pretty good... only... we can see parts of each of the lens objects inside the union! This is not good.

#### 2.2.3.5 CSG Merge

This brings us to the fourth kind of CSG object, the `merge`. Merges are the same as unions, but the geometry of the objects in the CSG that is inside the merge is not traced. This should eliminate the problem with our object. Let's try it.

      merge {
        object { Lens_With_Hole translate <-.65, .65, 0> }
        object { Lens_With_Hole translate <.65, .65, 0> }
        object { Lens_With_Hole translate <-.65, -.65, 0> }
        object { Lens_With_Hole translate <.65, -.65, 0> }
        pigment { Red filter .5 }
      }

Sure enough, it does!

#### 2.2.3.6 CSG Pitfalls

There is a severe pitfall in the CSG code that we have to be aware of.

##### 2.2.3.6.1 Co-incident Surfaces

POV-Ray uses inside/outside tests to determine the points at which a ray intersects a CSG object. A problem arises when the surfaces of two different shapes coincide because there is no way (due to the computer's floating-point accuracy) to tell whether a point on the coincident surface belongs to one shape or the other.

Look at the following example where a cylinder is used to cut a hole in a larger box.

      difference {
        box { -1, 1 pigment { Red } }
        cylinder { -z, z, 0.5 pigment { Green } }
      }

Note: that the vectors -1 and 1 in the box definition expand to <-1,-1,-1> and <1,1,1> respectively.

If we trace this object we see red speckles where the hole is supposed to be. This is caused by the coincident surfaces of the cylinder and the box. One time the cylinder's surface is hit first by a viewing ray, resulting in the correct rendering of the hole, and another time the box is hit first, leading to a wrong result where the hole vanishes and red speckles appear. This problem can be avoided by increasing the size of the cylinder to get rid of the coincidence surfaces. This is done by:

      difference {
        box { -1, 1 pigment { Red } }
        cylinder { -1.001*z, 1.001*z, 0.5 pigment { Green } }
      }

In general we have to make the subtracted object a little bit larger in a CSG difference. We just have to look for coincident surfaces and increase the subtracted object appropriately to get rid of those surfaces.

The same problem occurs in CSG intersections and is also avoided by scaling some of the involved objects.