.POV File Format – Constructive solid geometry

Syntax

union        { object ... [modifiers] }
merge        { object ... [modifiers] }
intersection { object ... [modifiers] }
difference   { object ... [modifiers] }

The members are any objects, in any number, in any order: shapes, other CSG objects, object { ... } wrappers, light sources. They are read until the first word that is not an object; then the modifiers follow. As with every shape, the first thing in the block may be the name of a declared object, which is copied. A CSG with fewer than two members is accepted without a message (the warning only exists for versions before 1.5).

These words start an object, and so can be a member of a CSG object (or the body of clipped_by, bounded_by and looks_like): box, sphere, cylinder, cone, torus, disc, lemon, ovus, superellipsoid, lathe, prism, sor, text, polygon, triangle, smooth_triangle, bicubic_patch, blob, sphere_sweep, julia_fractal, plane, poly, cubic, quartic, polynomial, quadric, isosurface, parametric, height_field, mesh, mesh2, union, merge, intersection, difference, composite, light_group, light_source, object, and the name of a declared object.

How the surface is found

To trace a ray, a CSG object asks each member for all the points where the ray crosses its surface and keeps some of them.

• A union keeps every crossing of every member.
• A merge keeps a crossing of one member only if the point is not inside any other member. This costs one inside test per other member.
• An intersection keeps a crossing of one member only if the point is inside all the other members.
• A difference is an intersection. The parser inverts every member but the first, then builds the intersection. The inverted members are "everything outside the object", so their surfaces are kept where they lie inside the first member, and the first member's surface is kept where it lies outside the others.

The inside test of a member is the question the shape itself answers (see the table below). A ray that goes on inside an object, for example in refraction or in media, relies on the crossings coming in pairs, one entering and one leaving. A shape that is not closed breaks that, and so gives wrong pictures in CSG.

A point counts as inside a CSG object by the same rules, applied to the members. A member that has no inside never passes the test of an intersection or a difference. The parser warns Patch objects not allowed in intersection. when a patch is a member of an intersection or a difference.

inverse

The modifier inverse turns the inside and the outside of an object round. On a CSG object the parser rewrites the object with the rules of De Morgan: an inverted union (or merge) becomes an intersection of the inverted members; an inverted intersection or difference becomes a merge of the inverted members. That is how difference works internally. inverse on an object that has no inside (a patch) gives the warning Cannot invert a patch object.

The inside of each object

A CSG object that has any patch among its members is a patch itself: it takes over the patch property of its members, so it has no inside either. The same holds one level up. A union of patches is fine (it is a way to group triangles). An intersection or a difference with a patch member has an inside test that is always false for that member, so the result is unreliable.

In a difference, the patch behaves as expected only as the first member: solids can be subtracted from a patch with the expected result. Subtracting a patch from a solid, or inverting a patch, can give surprising results.

Textures and flags of the members

After the whole scene is read, the parser walks each CSG object and gives its members what they do not already have. The order is: first the object's own texture, then the parent's.

A transformation of a CSG object is applied to every member and to every texture the CSG and its members have at that moment. So a texture that is written after a translate or a rotate in the same block is not moved by it. The same holds for the object modifiers: write the transformations last if the texture should move with the object.

These flags and settings of a CSG object are also copied to the members that do not set them: no_shadow, no_image, no_reflection, no_radiosity, cutaway_textures, the photons flags (target with its density, pass_through, reflection, refraction, collect) and the radiosity { importance } value. hollow and double_illuminate are different: when they are read in a union, merge, intersection or difference, the parser at once sets or clears the flag on every member (hollow) or on the whole tree below (double_illuminate). A union in which every member has no_shadow gets no_shadow itself.

cutaway_textures

Normally the face made by a cut takes the texture of the object that cut: in a difference, the face of the subtracted object. If that object has no texture, it gets the default texture. With cutaway_textures in an intersection or difference, members that have no texture are not given the default texture. For a cut face, POV-Ray runs the inside tests of the members: where the point lies inside an object, that object's texture is used, evaluated at that point. Where the objects overlap and are CSG objects with different textures, the textures are averaged. The keyword is an error in anything but an intersection or a difference (cutaway_textures can only be used with intersection and difference.).

Bounding, clipping and splitting

Splitting. After the parse a union that is not inside another CSG object, has no clipped_by and is not a merge is split: its members are linked to the scene one by one and the union disappears. The point is speed: the members are then bounded individually. The union is kept whole if split_union off (or 0) was written, and if it has a bounded_by and either one of its members is infinite or the INI option Split_Unions is off (its default). A bounded union that is split gives the warning Bounded CSG union split.; one that is kept although it could have been split gives CSG union unnecessarily bounded. The textures and flags of the union are passed on to its members before the split, so splitting does not change the picture.

Intersections, differences and merges are never split. A CSG object that is itself a member of another CSG object is not split either.

The object wrapper

object { object [modifiers] }

An object block holds one object and then modifiers. The inner object can be a shape written in place or the name of a declared object. The result is a copy that is changed by the modifiers; the declared original is not touched. This is the way to place the same declared object many times.

• Transformations are added after the ones the declared object already has.
• pigment, normal and finish replace that part of the plain texture the object already has. A texture block is laid on top of the existing texture as a new layer, so the object needs a transparent texture for the lower layer to show. Layering over a texture that is a pattern (a texture_map or tiles) is the error Cannot layer over a patterned texture.
• The object can be a CSG object; the modifiers are applied to the CSG object as a whole.
• Written without the object word, the name of a declared object can follow the opening brace of any shape: cylinder { Peg translate x }. The declared object is copied whatever its type was and the shape's own arguments are not read.

Light sources in CSG

A light_source can be a member of a CSG object, and the light then moves, rotates and scales with the object. A light has no surface of its own. Its optional looks_like { object } is a visible object at the position of the light; the parser moves it to the light's position, gives it the no-shadow flag, and gives the light the no-shadow flag as well. For the inside tests of an intersection or a merge a light without looks_like is skipped, so it does not change the result. A CSG object that holds only lights is marked as a union of lights, and the light sources in it are processed as global lights. In a light_group they are local to the group. See Lights.

Examples

// a die: a cube rounded by a sphere, with two pits cut out
difference {
  intersection {
    box { -1, 1 }
    sphere { 0, 1.35 }
  }
  sphere { <0, 0, -1.4>, 0.3 }
  sphere { <-1.4, 0, 0>, 0.3 }
  pigment { rgb <1, 1, 0.9> }
  translate -x*3
}
// merge removes the surface inside: a see-through shape shows no inner shell
merge {
  sphere { <-0.4, 0, 0>, 0.8 }
  sphere { <0.4, 0, 0>, 0.8 }
  pigment { rgbf <0.6, 0.8, 1, 0.7> }
  interior { ior 1.3 }
}
// a union texture applies to the members that have none
union {
  cylinder { <0, -1, 0>, <0, 1, 0>, 0.3 pigment { rgb <1, 0, 0> } }
  cylinder { <-1, 0, 0>, <1, 0, 0>, 0.3 }
  pigment { rgb <0, 0, 1> }
  translate x*3
}

#declare Peg = cylinder { <0, 0, 0>, <0, 1, 0>, 0.2 pigment { rgb <1, 0.5, 0> } }
// the object wrapper: reuse a declared object with extra modifiers
object { Peg translate -x*2 }
object { Peg scale 2 pigment { rgb <0, 1, 0> } }
// clipped_by with a CSG object as the clip
sphere {
  <2, 0.5, 0>, 1
  pigment { rgb 1 }
  clipped_by {
    difference {
      box { <1, -1, -2>, <3, 2, 2> }
      sphere { <2, 0.5, -1>, 0.6 }
    }
  }
}
// a light with looks_like, inside a union
union {
  light_source {
    <0, 3, 0>, rgb 1
    looks_like { sphere { 0, 0.2 pigment { rgb 1 } finish { emission 1 } } }
  }
  box { <-0.5, 2, -0.5>, <0.5, 2.2, 0.5> pigment { rgb 0.4 } }
}
// inverse on a union gives an intersection of the inverted members
intersection {
  box { <-3, -3, -0.5>, <-1, -1, 0.5> }
  union {
    sphere { <-2, -2, 0>, 0.8 }
    sphere { <-1.2, -2, 0>, 0.8 }
    inverse
  }
  pigment { rgb <1, 0, 1> }
}

// cutaway_textures: the cut faces take the texture of the object that was cut
difference {
  sphere { 0, 1 pigment { rgb <1, 0.5, 0> } interior_texture { pigment { rgb <0, 0.5, 1> } } }
  box { <-0.5, -0.5, -2>, <0.5, 0.5, 0> pigment { rgb <0, 1, 0> } }
  cutaway_textures
}
// hollow and split_union
union {
  sphere { <3, 0, 0>, 0.5 }
  sphere { <4, 0, 0>, 0.5 }
  split_union off
  hollow
  pigment { rgb 1 }
}
// a solid mesh in a difference needs an inside_vector
difference {
  box { <-4, -1, -1>, <-2, 1, 1> pigment { rgb 1 } }
  mesh {
    triangle { <-3, -1.5, -1.5>, <-2.2, -1.5, -1.5>, <-3, 0.5, -1.5> }
    triangle { <-3, -1.5, -1.5>, <-2.2, -1.5, -1.5>, <-3, -1.5, 0.5> }
    triangle { <-3, -1.5, -1.5>, <-3, 0.5, -1.5>, <-3, -1.5, 0.5> }
    triangle { <-2.2, -1.5, -1.5>, <-3, 0.5, -1.5>, <-3, -1.5, 0.5> }
    inside_vector <0, 0, 1>
  }
}

Not described

Known, not yet covered

• Reference: the exact way cutaway_textures decides between textures at the shading step (the average over overlapping objects is taken from the manual) and the way bounding slabs use the box of a CSG object (the Bounding and Bounding_Threshold INI options) are not described.