The color or pattern of colors for an object is defined by a pigment statement. All plain textures must have a pigment. If you do not specify one the default pigment is used. The color you define is the way you want the object to look if fully illuminated. You pick the basic color inherent in the object and POV-Ray brightens or darkens it depending on the lighting in the scene. The parameter is called pigment because we are defining the basic color the object actually is rather than how it looks.
The syntax for pigment is:
pigment{ }
image_map{ }
color_map{ } | colour_map{ COLOR_MAP_BODY } |
pigment_map{ } |
quick_color quick_colour COLOR
Each of the items in a pigment are optional but if they are present, they must be in the order shown. Any items after the PIGMENT_IDENTIFIER modify or override settings given in the identifier. If no identifier is specified then the items modify the pigment values in the current default texture. The PIGMENT_TYPE fall into roughly four categories. Each category is discussed the sub-sections which follow. The four categories are solid color and image map patterns which are specific to pigment statements or color list patterns, color mapped patterns which use POV-Ray's wide selection of general patterns. See "Patterns" for details about specific patterns.
The pattern type is optionally followed by one or more pigment modifiers. In addition to general pattern modifiers such as transformations, turbulence, and warp modifiers, pigments may also have a COLOR_LIST, PIGMENT_LIST, color_map, pigment_map, and quick_color which are specific to pigments. See "Pattern Modifiers" for information on general modifiers. The pigment-specific modifiers are described in sub-sections which follow. Pigment modifiers of any kind apply only to the pigment and not to other parts of the texture. Modifiers must be specified last.
A pigment statement is part of a texture specification. However it can be tedious to use a texture statement just to add a color to an object. Therefore you may attach a pigment directly to an object without explicitly specifying that it as part of a texture. For example instead of this:
object {My_Object texture{pigment{color Red}}}
you may shorten it to:
object {My_Object pigment{color Red}}
Note however that doing so creates an entire texture structure with default normal and finish statements just as if you had explicitly typed the full texture{...} around it.
Pigment identifiers may be declared to make scene files more readable and to parameterize scenes so that changing a single declaration changes many values. An identifier is declared as follows.
#declare = PIGMENT |
#local = PIGMENT
Where IDENTIFIER is the name of the identifier up to 40 characters long and PIGMENT is any valid pigment statement. See "#declare vs. #local" for information on identifier scope.
The simplest type of pigment is a solid color. To specify a solid color you simply put a color specification inside a pigment statement. For example:
pigment {color Orange}
A color specification consists of the option keyword color followed by a color identifier or by a specification of the amount of red, green, blue, filtered and unfiltered transparency in the surface. See section "Specifying Colors" for more details about colors. Any pattern modifiers used with a solid color are ignored because there is no pattern to modify.
There are three color list patterns: checker, hexagon and brick. The result is a pattern of solid colors with distinct edges rather than a blending of colors as with color mapped patterns. Each of these patterns is covered in more detail in a later section. The syntax is:
pigment{brick , [COLOR_2]] [PIGMENT_MODIFIERS...] } |
pigment{checker , [COLOR_2]] [PIGMENT_MODIFIERS...] } |
pigment{hexagon , [COLOR_2, [COLOR_3]]] [PIGMENT_MODIFIERS...] }
Each COLOR_n is any valid color specification. There should be a comma between each color or the color keyword should be used as a separator so that POV-Ray can determine where each color specification starts and ends. The brick and checker pattern expects two colors and hexagon expects three. If an insufficient number of colors is specified then default colors are used.
Most of the color patterns do not use abrupt color changes of just two or three colors like those in the brick, checker or hexagon patterns. They instead use smooth transitions of many colors that gradually change from one point to the next. The colors are defined in a pigment modifier called a color_map that describes how the pattern blends from one color to the next.
Each of the various pattern types available is in fact a mathematical function that takes any x, y, z location and turns it into a number between 0.0 and 1.0 inclusive. That number is used to specify what mix of colors to use from the color map.
The syntax for color_map is as follows:
color_map{ } | colour_map{ COLOR_MAP_BODY }
[ ] | [ Value_1, Value_2 color COLOR_1 color COLOR_2 ]
Where each Value_n is a float values between 0.0 and 1.0 inclusive and each COLOR_n, is color specifications. Note that the [] brackets are part of the actual COLOR_MAP_ENTRY. They are not notational symbols denoting optional parts. The brackets surround each entry in the color map. There may be from 2 to 256 entries in the map. The alternate spelling colour_map may be used.
Here is an example:
sphere {
<0,1,2>, 2
pigment {
gradient x //this is the PATTERN_TYPE
color_map {
[0.1 color Red]
[0.3 color Yellow]
[0.6 color Blue]
[0.6 color Green]
[0.8 color Cyan]
}
}
}
The pattern function gradient x is evaluated and the result is a value from 0.0 to 1.0. If the value is less than the first entry (in this case 0.1) then the first color (red) is used. Values from 0.1 to 0.3 use a blend of red and yellow using linear interpolation of the two colors. Similarly values from 0.3 to 0.6 blend from yellow to blue. Note that the 3rd and 4th entries both have values of 0.6. This causes an immediate abrupt shift of color from blue to green. Specifically a value that is less than 0.6 will be blue but exactly equal to 0.6 will be green. Moving along, values from 0.6 to 0.8 will be a blend of green and cyan. Finally any value greater than or equal to 0.8 will be cyan.
If you want areas of unchanging color you simply specify the same color for two adjacent entries. For example:
color_map {
[0.1 color Red]
[0.3 color Yellow]
[0.6 color Yellow]
[0.8 color Green]
}
In this case any value from 0.3 to 0.6 will be pure yellow.
The first syntax version of COLOR_MAP_ENTRY with one float and one color is the current standard. The other double entry version is obsolete and should be avoided. The previous example would look as follows using the old syntax.
color_map {
[0.0 0.1 color Red color Red]
[0.1 0.3 color Red color Yellow]
[0.3 0.6 color Yellow color Yellow]
[0.6.0.8 color Yellow color Green]
[0.8 1.0 color Green color Green]
}
You may use color_map with any patterns except brick, checker, hexagon and image_map. You may declare and use color_map identifiers. For example:
#declare Rainbow_Colors=
color_map {
[0.0 color Magenta]
[0.33 color Yellow]
[0.67 color Cyan]
[1.0 color Magenta]
}
object{My_Object
pigment{
gradient x
color_map{Rainbow_Colors}
}
}
In addition to specifying blended colors with a color map you may create a blend of pigments using a pigment_map. The syntax for a pigment map is identical to a color map except you specify a pigment in each map entry (and not a color).
The syntax for pigment_map is as follows:
pigment_map{ }
[ ]
Where Value is a float value between 0.0 and 1.0 inclusive and each PIGMENT_BODY is anything which can be inside a pigment{...} statement. The pigment keyword and {} braces need not be specified.
Note that the [] brackets are part of the actual PIGMENT_MAP_ENTRY. They are not notational symbols denoting optional parts. The brackets surround each entry in the pigment map. There may be from 2 to 256 entries in the map.
For example
sphere {
<0,1,2>, 2
pigment {
gradient x //this is the PATTERN_TYPE
pigment_map {
[0.3 wood scale 0.2]
[0.3 Jade] //this is a pigment identifier
[0.6 Jade]
[0.9 marble turbulence 1]
}
}
}
When the gradient x function returns values from 0.0 to 0.3 the scaled wood pigment is used. From 0.3 to 0.6 the pigment identifier Jade is used. From 0.6 up to 0.9 a blend of Jade and a turbulent marble is used. From 0.9 on up only the turbulent marble is used.
Pigment maps may be nested to any level of complexity you desire. The pigments in a map may have color maps or pigment maps or any type of pigment you want. Any entry of a pigment map may be a solid color however if all entries are solid colors you should use a color_map which will render slightly faster.
Entire pigments may also be used with the block patterns such as checker, hexagon and brick. For example...
pigment {
checker
pigment { Jade scale .8 }
pigment { White_Marble scale .5 }
}
Note that in the case of block patterns the pigment wrapping is required around the pigment information.
A pigment map is also used with the average pigment type. See "Average" for details.
You may not use pigment_map or individual pigments with an image_map. See section "Texture Maps" for an alternative way to do this.
You may declare and use pigment map identifiers but the only way to declare a pigment block pattern list is to declare a pigment identifier for the entire pigment.
When all else fails and none of the above pigment pattern types meets your needs you can use an image_map to wrap a 2-D bit-mapped image around your 3-D objects.
The syntax for an image_map is:
pigment{
image_map{ }
}
gif tga | iff | ppm | pgm | png | sys
map_type once | interpolate Type |
filter , Amount | filter all Amount |
transmit , Amount | transmit all Amount
After the required BITMAP_TYPE keyword is a string expression containing the name of a bitmapped image file of the specified type. Several optional modifiers may follow the file specification. The modifiers are described below. Note that earlier versions of POV-Ray allowed some modifiers before the BITMAP_TYPE but that syntax is being phased out in favor of the syntax described here. Note sys format is a system-specific format such as BMP for Windows or Pict for Macintosh.
Filenames specified in the image_map statements will be searched for in the home (current) directory first and, if not found, will then be searched for in directories specified by any +L or Library_Path options active. This would facilitate keeping all your image maps files in a separate subdirectory and giving a Library_Path option to specify where your library of image maps are. See "Library Paths" for details.
By default, the image is mapped onto the x-y-plane. The image is projected onto the object as though there were a slide projector somewhere in the -z-direction. The image exactly fills the square area from (x,y) coordinates (0,0) to (1,1) regardless of the image's original size in pixels. If you would like to change this default you may translate, rotate or scale the pigment or texture to map it onto the object's surface as desired.
In the section "Checker", the checker pigment pattern is explained. The checks are described as solid cubes of colored clay from which objects are carved. With image maps you should imagine that each pixel is a long, thin, square, colored rod that extends parallel to the z-axis. The image is made from rows and columns of these rods bundled together and the object is then carved from the bundle.
If you would like to change this default orientation you may translate, rotate or scale the pigment or texture to map it onto the object's surface as desired.
The file name is optionally followed by one or more BITMAP_MODIFIERS. The filter, filter all, transmit, and transmit all modifiers are specific to image maps and are discussed in the following sections. An image_map may also use generic bitmap modifiers map_type, once and interpolate described in "Bitmap Modifiers"
To make all or part of an image map transparent you can specify filter and/or transmit values for the color palette/registers of PNG, GIF or IFF pictures (at least for the modes that use palettes). You can do this by adding the keyword filter or transmit following the filename. The keyword is followed by two numbers. The first number is the palette number value and the second is the amount of transparency. The values should be separated by a comma. For example:
image_map {
gif "mypic.gif"
filter 0, 0.5 // Make color 0 50% filtered transparent
filter 5, 1.0 // Make color 5 100% filtered transparent
transmit 8, 0.3 // Make color 8 30% non-filtered transparent
}
You can give the entire image a filter or transmit value using filter all Amount or transmit all Amount. For example:
image_map {
gif "stnglass.gif"
filter all 0.9
}
Note that early versions of POV-Ray used the keyword alpha to specify filtered transparency however that word is often used to describe non-filtered transparency. For this reason alpha is no longer used.
See section "Specifying Colors" for details on the differences between filtered and non-filtered transparency.
Another way to specify non-filtered transmit transparency in an image map is by using the alpha channel. PNG file format allows you to store a different transparency for each color index in the PNG file, if desired. If your paint programs support this feature of PNG you can do the transparency editing within your paint program rather than specifying transmit values for each color in the POV file. Since PNG and TGA image formats can also store full alpha channel (transparency) information you can generate image maps that have transparency which isn't dependent on the color of a pixel but rather its location in the image.
Although POV uses transmit 0.0 to specify no transparency and 1.0 to specify full transparency, the alpha data ranges from 0 to 255 in the opposite direction. Alpha data 0 means the same as transmit 1.0 and alpha data 255 produces transmit 0.0.
When developing POV-Ray scenes its often useful to do low quality test runs that render faster. The +Q command line switch or Quality INI option can be used to turn off some time consuming color pattern and lighting calculations to speed things up. See "Quality Settings" for details. However all settings of +Q5 or Quality=5 or lower turns off pigment calculations and creates gray objects.
By adding a quick_color to a pigment you tell POV-Ray what solid color to use for quick renders instead of a patterned pigment. For example:
pigment {
gradient x
color_map{
[0.0 color Yellow]
[0.3 color Cyan]
[0.6 color Magenta]
[1.0 color Cyan]
}
turbulence 0.5
lambda 1.5
omega 0.75
octaves 8
quick_color Neon_Pink
}
This tells POV-Ray to use solid Neon_Pink for test runs at quality +Q5 or lower but to use the turbulent gradient pattern for rendering at +Q6 and higher.
Note that solid color pigments such as
pigment {color Magenta}
automatically set the quick_color to that value. You may override this if you want. Suppose you have 10 spheres on the screen and all are yellow. If you want to identify them individually you could give each a different quick_color like this:
sphere {
<1,2,3>,4
pigment { color Yellow quick_color Red }
}
sphere {
<-1,-2,-3>,4
pigment { color Yellow quick_color Blue }
}
and so on. At +Q6 or higher they will all be yellow but at +Q5 or lower each would be different colors so you could identify them.
The alternate spelling quick_colour is also supported.