The Online POV-Ray Tutorial

Pigment Reference

Topics covered in this section

Note: all the sample images in this scene were rendered with the following color map (unless otherwise specified). 

color_map {
   [0.00 color rgb <0.75, 0, 0>]
   [0.33 color rgb <0.75, 0.75, 0>]
   [0.50 color rgb <0, 0.75, 0>]
   [0.66 color rgb <0, 0, 0.75>]
   [1.00 color rgb <0.75, 0, 0>]
}

This color map has very high contrast so the details of each pigment can be easily seen. Also, all the pigments were rendered without any turbulence (except for agate, which always is turbulent).

Agate

The agate pigment is a very swirly, very turbulent pattern. It's similar to the marble pigment, except for its color look-up function and the fact that it is always very turbulent. The look-up function for the color map uses the colors from 0.0 to 1.0 and back down to 0.0 like marble, but instead of indexing the colors linearly it uses a sine wave. This results in the ends of the color map having more weight than the center. In general, the pigment looks something like this

Another thing to note about agate is the fact that the turbulence keyword has no effect on this pigment. Agate is always turbulent. The amount of turbulence can be controlled, to some extent, with the "agate_turb" keyword. This parameter takes a positive float value.

For more information on declaring pigments, see the pigment section.

Bozo

The bozo pigment is a very cool and very useful pattern. It basically creates a series of "splotches" on the object. Its color map indexing function uses the colors from 0 to 1 without reversing. The pigment basically works by assigning random colors to integer points in space and interpolating the colors between those points. As a result, two points that are "close" tend to have colors that are fairly similar while points that are "distant" tend to have colors that are random with respect to each other. The notion of "close" and "distant" depends on the scaling of the pigment. The bozo pigment uses the same coloring function as spotted, but spotted is unaffected by turbulence. Here's what a bozo texture might look like . . .

For more information on declaring pigments, see the pigment section.

Checker

The checker pigment creates cubes of color in space. The checker pigment doesn't support color maps; you specify the two colors that are checkered. This differs from the standard pigment declaration, so here's the general template for using checker. 

pigment {
   checker
   color color-a
   color color-b
}

color-a and color-b are any two colors. The pigment creates a space filling pattern of colored unit cubes with the given colors. For example, the pigment 

pigment {
   checker
   color Red
   color Blue
}

would come out looking something like this

One thing to notice about the checker pigment is that it is automatically offset a little bit in each direction to prevent problems with coincident surfaces. This may produce undesirable color patterns as seen on the front face of the cube in the image.

Like most other pigments, checker responds to the turbulence modifier. The pigment can be scaled nonuniformly to produce rectangular blocks of color as well.

Color

The color pigment is used to assign monochromatic, flat colors to objects. It is also used in both the hexagon and checker pigments. The general form for this pigment is as follows: 

pigment {
   color color def
}

where color def is a color defined in one of the following ways 

   color color name
   color rgb <color vec>
   color rgbf <color vec>
   color red rval green gval blue bval filter fval

In the first style, color name is the name of a declared color. A great number of (very cool) prefined color names can be found in colors.inc. They can be accessed through the include directive.

In the second style, an rgb color vector is specified for the color. The vector has three components, all floats between 0.0 and 1.0, where 0.0 represents no saturation of that color and 1.0 represents full saturation of that color. Here are a few examples 

   color rgb <1, 1, 1>         // white
   color rgb <0, 0, 0>         // black
   color rgb <1, 0.7, 0.7>     // pink
   color rgb <0, 0.6, 0.9>     // greenish blue

The third color style is similar to the second style, except a filter value is specified to make the color partially transparent. color vec in this example is a four component vector, the first three components are the same as above, and fourth float, also between 0.0 and 1.0, specifying the amount of transparency. 1.0 is a surface that is fully transparent, less than 1.0 makes colors translucent, and 0.0 makes them opaque. Note that a color that filters passes through colors in proportion to each color component. For example 

   color rgbf <1, 1, 1, 1>          // perfectly transparent
   color rgbf <1, 0, 0, 1>          // like red cellophane
   color rgbf <0.8, 0.8, 0.8, 0.4>  // like frosted glass

Note that a declaration like "color rgbf <0, 0, 0, 1>" will produce a filter that is perfectly black (and hence perfectly opaque).

Finally, the fourth method of specifying colors is a more verbose variation of color specification three. Each keyword (red, green, blue, and filter) is followed by a float (between 0 and 1) that specifies the corresponding component of that color. Note that these keywords may appear in any order and are all optional (except for the first one. One must be specified or POV-Ray will whine at you). Any components that are not specified will be assumed to be 0. These keywords can also be used to modify existing colors. Any components which have not been specified can be specified with these keywords. For example, these two declarations are the same 

   color Red filter 0.5
   color rgbf <1, 0, 0, 0.5>

For more examples of these kinds of color declarations see the standard POV-Ray file colors.inc.

Here's a sample image that was rendered with the pigment 

pigment {
   color rgb <0.75, 0, 0>
}

Note how the surface have no detail except for the sphere, which has a bit of shading. This is partially because of the flat pigment and partially because of the location of the light source.

Color Map

Color maps are what give pigments life. The default color map is a blend of grays from black to white, and frankly, this is dull. Color maps give you the power to specify blends of color over the range of a pigment. The general format for declaring color maps is like this 

color_map {
   [cp0 color color spec 0]
   [cp1 color color spec 1]
   [cp2 color color spec 2]
/* there can be up to 20 colors in the map */
}

cp0 through cpn are floats in the range 0 to 1 that specify the location of a control point in the color map. For each control point, a color is specified. To get the color of a point in between control points, POV-Ray uses linear interpolation. Color maps must contain between 2 and 20 control points, but the value of each control point should be greater than or equal to the previous one. Here are some example color maps 

color_map {             
   [0.0 color Red]      // starts at red, then blends through
   [0.33 color Green]   // green,
   [0.67 color Blue]    // blue,
   [1.0 color Red]      // and back to red
}

color_map {             // all colors from 0.0 to 0.5 are Yellow
   [0.0 color Yellow]
   [0.5 color Yellow]
   [0.5 color Blue]     // then, at 0.5, there is a sharp change to blue
   [1.0 color Blue]     // which is the color of the remainder of the map
}

color_map {             // same as above, but harder to understand
   [0.5 color Yellow]
   [0.5 color Blue]
}

color_map {             // filters blend too
   [0.0 color Red]
   [0.5 color White filter 1]
   [1.0 color Blue]
}

Some things to keep in mind about color maps

There are a number of examples of color maps in the POV-Ray include file textures.inc.

Frequency

The frequency modifier controls how many times the color map is used over the 0.0 to 1.0 range. The modifier takes a float which defines how the color map is stretched. Values greater than 1 compress the map, values less than 1 stretch it. Negative values will reverse it and (potentially) stretch it. 0 is a bad number. For example, the statement "frequency 2" will cause the color map to repeat twice over the range that would've repeated once. Here are two sample images. The first was rendered with the default "frequency 1", the second was rendered with "frequency 5", and the third was rendered with "frequency -1". All three images use the radial pigment pattern.

See pigment for information about the use of frequency.

Gradient

The gradient pigment creats parallel planes of color. The orientation of those planes is controlled with gradient's parameter. The said parameter is an 3 component vector which descibes the normal of the planes of color (they all have the same normal as they are parallel). Note that the magnitude of the vector is unimportant, as long as it is nonzero. To control the width of the bands of color, use the frequency keyword. The gradient pigment is very similar to the marble pigment. The main difference is the color map look up functions. Gradient uses indexes the color map from 0 to 1 without reversing, while marble bounces back and forth from 0 to 1 and back to 0 again. This effect can be simulated with gradient with the proper color map and scaling. Another thing to note about the gradient pattern is that the color map reverses at 0. To get rid of this potentially undesirable boundary, you can translate the pigment along its normal vector until the boundary is off the object. Here are two sample gradient patterns, the first is rendered with "gradient x" and the second is rendered with "gradient <1, 1, 1>"

The first image shows the color map reversal at the origin, while the second was translated to remove this "feature."

For more information about declaring pigments, see the pigment section.

Granite

The granite pigment creates a sort of bozo-like pattern. Typically, you'll end up with pockets of color from one end of the color map surrounded by rivers of colors from the other end. With the proper color map it can look very convincingly like real granite. The sample color map used here doesn't really do it justice. For much, much, much better examples of the use of this pigment (with layered textures), see the include file stones.inc.

Granite uses the color map from 0 to 1, 0 to 1, etc, without reversing. Granite responds to turbulence, although it doesn't have any by default.

For more information on declaring pigments, see the pigment section.

Hexagon

The hexagon pigment is similar to the checker pigment. For this pigment, three colors are specified, and they are used to create a hexagonal pattern on the objects. The hexagon pattern is projected onto the x-z plane, and produces haxagonal "pillars" of color parallel to the y-axis. Rendered with the following pigment 

pigment {
   hexagon
   color rgb <0.75, 0, 0>
   color rgb <0, 0, 0.75>
   color rgb <0, 0.75, 0>
   scale 0.5
}

The pigment was scaled to give more detail about how the pigment works.

For more information about declaring pigments, see the pigment section.

Image Map

Image mapping a very powerful technique for producing specific color patterns on the surface of an object. It basically works by reading an image file and then projecting that image onto the object. The default mapping method is to project the image onto the x-y plane in such a way that it fits into the square (0, 0), (1, 1). The pixels of the original image are turned into infinitely long boxes that are parallel to the z-axis. Note that larger images do not produce larger image maps, but rather image maps with better resolution. By default, the image map is repeated infinitely in the x and y directions. This can be changed with the once keyword. If you don't like the normal position of the image map, you can scale, rotate, and translate it to your heart's content. If you don't like the default projection style mapping, you can change it (to some extent) with the map_type modifier. But onward now, to the syntax for image maps 

image_map {
   type "filename"
   modifiers . . .
}

type is one of gif, tga, iff, or dump. This is followed by the filename (in quotes) which specifies the image file to be mapped.

Here we have an example of an image being mapped onto a box. The first image is the image that was mapped, and the second is the resulting scene.

The modifiers following the file type are optional. They include the aforementioned once and map_type as well as a few others.

One of these others is the interpolate keyword. Interpolation performs smoothing on the image as it is mapped. By default, POV-Ray takes the location of the ray intersection and assigns a pixel value to it. When the image map is scaled up a great deal or is of poor resolution initally, this can result in image maps that appear blocky or otherwise generally ugly. When interpolation is turned on, POV-Ray averages the values of surrounding pixels to determine intermediate values. This eliminates (for the most part) blockiness, but at the expense of tracing time. The interpolate keyword is followed by a number specifying the type of interpolation to be used. This number can be either 4 (for the Normalized Distance algorithm) or 2 (for the Bilinear algorithm). Normalized Distance is the faster algorithm, while Bilinear does a better job of picking intermediate colors. Here's an example of using the interpolate keyword 

pigment {
   image_map {
      gif "foobar.gif"
      interpolate 4
   }
}

The last modifier accepted by image maps is filter values. By default, image maps are all opaque. The filter keyword can be used to change this. Filter can be used to modify specific colors, or to assign a filter value to the entire image map. Probably the best way to explain filter is through examples so here are a few 

image_map {
   gif "zordo.gif"
   filter 0, 0.5
   filter 2, 1.0
   filter 7, 0.4
}

image_map {
   gif "gurple.gif"
   filter all 0.8
}

The first image map maps the image with the color specified by palette entry 0 (in the .GIF file) being 50% transparent. The color specified by palette entry 2 becomes 100% transparent. The color with palette entry 7 becomes 40% transparent (which should not be surprising at this point). See the section on color for an explanation of color filtering.

Image maps also respond to turbulence, which can make for some very interesting effects.

Image maps and color maps do not mix.

For more information about declaring pigments, see the pigment section.

Lambda

Lambda (besides being a greek letter) is a modifier for turbulence. The lambda parameter basically controls how random each step of turbulence is (see turbulence for a description). It takes a float parameter that must be greater than or equal to 1.0. Values of 1.0 produce very straight steps, while greater values produce steps with a greater randomness. The default lambda is 2. Note that specifying a lambda value only makes sense if you have turbulence.

Leopard

The leopard pigment is similar to the bozo pigment, except for its regularness. The pigment is generated by basically setting the center of each unit cube in the space to the color at one end of the color map, and points on the edge of the cube to the color at the other end. The colors inside the cube are then blended between the two. Leopard uses the color map values from 0 to 1, 0 to 1 without reversing. Here's an example of a leopard pigment

The leopard pigment responds to turbulence, and it is said that very turbulent leopard pigments look like bozo pigments to some extent.

For more information about declaring pigments, see the pigment section.

Mandel

The mandel pigment creates a pattern that looks like the famous Mandelbrot set. Mandel one of the few pigments which take a parameter; that parameter is the number of iterations to compute when generating the pigment. The number of interations for each point to escape is used to color it according to the given color map. By default, the set is mapped onto the x-y plane in the standard range. As usual, the pigment can be scaled, rotated, and translated to fulfill your fondest Mandelbrot set dreams. Now we have an example of a mandel texture rendered with "mandel 50"

For more information on declaring textures, see the pigment section.

Marble

The marble pigment is quite similar to the gradient x pigment, except for its color map look up function. Where gradient uses the colors from 0 to 1, 0 to 1 without reversing, the marble pigment blends from colors 0 to 1 in the range x=0 to x=0.5 and then back down to color 0 again in the range x=0.5 to x=1. Also, the marble pigment doesn't take a "normal" parameter; if you want the pattern to vary from the default y-z plane orientation, you'll need to rotate the pigment. By default, marble has no turbulence and is consequently rather boring. A turbulence value of 0.8 or 0.9, in combination with a good color map, can create very realistic looking stone textures. Here are two sample images of marble pigments, identical except for the turbulence. The first image has no turbulence, while the second has turbulence 0.8.

For more information on declaring pigments, see the pigment section.

Octaves

The octaves keyword is modifier for turbulence. It controls the number of steps taken by the turbulence function when it is generating turbulence. The parameter is the number of steps that should be taken by the turbulence function. It can range from 1 to 10. The default value is 6. As the length of each step decreases exponentially, an octaves value much higher than 6 won't change the scene much. It will change the rendering time, though, as the more steps there are to calculate, the longer POV-Ray will have to spend on each ray. Using a low number of octaves can produce a sort of wavy pattern on the surface. For a description of turbulence, see (naturally enough) turbulence. Note that specifying the number of octaves only makes sense if you have turbulence.

Omega

Omega is yet another turbulence modifier. It controls the size of each step in the turbulence function. When generating turbulence, each step is omega times as long as the previous one. Normally omega values are between 0.0 and 1.0. The default value is 0.5, which means that each step is half as long as the previous. For a more in depth description of turbulence, see the turbulence section (go figure). Note that specifying an omega only makes sense if you have turbulence.

Onion

The onion pigment creates concentric spheres of color centered at the origin. It uses the color map entries from 0 to 1, 0 to 1, without reversing. Here's a sample of the onion texture

Note that the sphere is entirely one color. This is because the pigment is centered at the enter of the sphere and so each point one the sphere lines up with the same color in the color map.

For more information on declaring pigments, see the pigment section.

Phase

The phase keyword is used to offset the color map It takes a float parameter between 0.0 and 1.0. The phase adjustment is always applied before any frequency adjustments, regardless of their order in the pigment declaration. Note that adjusting the phase of a gradient pattern is the same as translating the pigment and adjusting the phase of a radial pigment is the same as rotating the pigment around the y-axis. By modifying the phase of a pigment you can create interesting effects in animations. For more information on the usage of phase, see pigment, which just happens to be the next section.

Pigment

The pigment statement is how pigments (colors or patterns of colors) are assigned to objects. Pigments are what give the life to raytraced images. POV-Ray supports a very wide array of pigment types, with an effectively infinite number of ways to al ter them to your needs. And if there still isn't something you want, you can also image mapping and even material mapping (image mapping with entire textures instead of just colors). Anyway, the general format for specifying a pigment is like this . . . 

pigment {
// One of these is required
   pigment type                        /* OR */
   color color    /* OR */
   image_map {
      /* image map specifications */
   }
// all the following are optional
   color_map {
      /* color map entries */
   }
   frequency frequency
   lambda lambda val
   octaves number of octaves
   omega omega val
   phase phase
   quick_color color
   turbulence turbulence val or vec
/* any transformations go here */
}

Any number of transformations (rotations, translations, and scales) may follow the pigment declaration, but must specified after the last pigment modifier.

A pigment consists of three major parts, first the pigment type, then the color map, and finally the turbulence. The color map and the turbulence are optional. The first part, pigment type is one of the following: agate, bozo, checker, gradient, granite, hexagon, leopard, marble, mandel, onion, , or wood. See their individual sections for more specific information on each (as well as sample images).

The second type of modifier is the color map. The specification of a color map is covered in some detail above. The two color map modifiers are frequency, which stretches or compresses the color map, and phase, which shifts the colors in the map.

The third part of the pigment is the turbulence specification. Turbulence is the "most optional" of the three parts. There are a number of pigments which will look fine without turbulence (such as bozo), and some which look rather lame without turbulence (such as marble) and even some which don't even respond to turbulence (such as spotted). Turbulence is basically used to mix up a pigment a little (or a lot). This can add life to a pigment. It can also make some pigments look weird. The modifiers lambda, octaves, and omega can be used to tweak the turbulence to achieve the exact effect you're looking for.

Quick Color

Quick colors are used only when debugging scenes. The method for specifying quick colors is the same as for specifying normal colors. You can have a pigment and a quick color assigned to the same object. The only time POV-Ray uses quick colors is when you set the rendering quality to +Q5 or below. At +Q6 and above the normal pigment declaration is used. When rendering a +Q5 and below, any objects which are not already solid colors will be grayscaled. For example 

sphere {
   gradient x
   color_map {
      [0.0 color Red]
      [1.0 color Yellow]
   }
   turbulence 0.8
   quick_color Aquamarine
}

will instruct POV-Ray to create a turbulent gradient pigment at +Q6 and above, and otherwise just color the sphere Aquamarine. You can use the quick_color modifier to distinguish two objects in a quick rendering. Note that giving an object a solid color pigment will automatically set the quick color to the same color. You can override this by explicitly specifying a quick color, though.

Radial

The radial pigment takes the color map and wraps it clockwise around the y-axis, starting in the positive x direction. There's not much more to say about it, so here's a sample image which probably explains it better.

There are some more samples over with the frequency section. For more information on declaring pigments, see the pigment section.

Spotted

The spotted pigment is identical to the bozo pigment, except it doesn't respond to turbulence. See the bozo section for more information on it. The following image was rendered with the spotted pigment.

For more information on declaring pigments, see the pigment section.

Turbulence

Turbulence is used to mix up a pigment to some extent. The turbulence key word can take either a float or a three component vector as a parameter. For example 

   turbulence 0.8           // stir up the pigment equally in all directions
   turbulence <0, 0.9, 0.3> // no turbulence in the x direction, a lot in
                            // the y direction and a little in the z
                            // direction
   turbulence x             // major turbulence only in the x direction

All of the numbers, whether individual floats or vector components, should be between 0.0 and 1.0 inclusive. High numbers mean lots of turbulence, low numbers mean only a little turbulence. Here's an example of what turbulence does. Both images use a marble pigment, but only the second was rendered with turbulence (turbulence 0.8, to be exact).

The way POV-Ray implements turbulence is quite interesting. In a normal pigment, POV-Ray simples determines the color of the pixel at each point on the surface of the object and colors the object with that. Turbulence works by taking a number of semi-random steps and using the color at the destination point. In essence, it constructs a pointer which says, "use that color over there." The "random" number generator used to produce these steps is a function of original point. Hence, points that are near each other initially tend to end up with similar colors, while points that are distant tend to end up with random colors (with respect to each other). The "random" number generator is also deterministic, so rendering a scene file with turbulence will always result in the same image (good for creating animations).

Here's a more in depth description of the turbulence function which will make its modifiers (lambda, octaves, and omega) make a little more sense. Turbulence works by first selecting a direction and moving so far that way. Then it picks a new direction and moves not-quite-as-far in that direction. Then it picks yet another direction and moves not-quite-not-quite-as-far in that direction. It uses a function called DNoise to generate these random steps. The overall magnitude of these steps is controlled by the parameter given to turbulence. Hence large amounts of turbulence create very large steps. The total number of steps taken is controlled by the octaves parameter. The default number of octaves is 6. This is a reasonable number and will do fine for most textures. Decreasing the number or octaves (to, say, 2) can create interesting effects. Increasing it will have only a marginal effect. This is because the length of each step falls off exponentially. The rate at which the step length falls off is determined by the omega value. Each subsequent step in the turbulence is omega times as long as the previous one. The default omega value is 0.5. Omegas are typically less than 1.0. High values or omega (0.8, 0.9, whatever) tend to make the turbulence more random, while low values (say, 0.1, 0.2) tend to smooth the pigment out a lot. The third modifier for turbulence is the lambda parameter. This controls the "randomness" of each step. Lambdas that are close to 1.0 cause each of the steps to be in approximately the same direction. Higher lambdas increase the randomness of the direction of each step. The default value is 2.0. Lambda should be greater than or equal to 1.0.

Wood

The wood pigment creates concentric cylinders of color centered around the z-axis. To create pigments that acutally look like wood, stick with earth tones, rotate the pigment around the x-axis a few degrees, and add a small amount of turbulence. Here, looking very un-wood-like is a sample image.

For more information about declaring pigments, see the pigment section.

Reference Index Top of Document Beginning of the Tutorial

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