Pigment

### 6.7.1 Pigment

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:
        pigment {
            [PIGMENT_IDENTIFIER]
            [PIGMENT_TYPE]
            [PIGMENT_MODIFIER...]
        }
    PIGMENT_TYPE:
        PATTERN_TYPE | COLOR |
        image_map {
            BITMAP_TYPE "bitmap.ext" [IMAGE_MAP_MODS...]
        }
    PIGMENT_MODIFIER:
        PATTERN_MODIFIER | COLOR_LIST | PIGMENT_LIST |
        color_map { COLOR_MAP_BODY } | colour_map { COLOR_MAP_BODY } |
        pigment_map { PIGMENT_MAP_BODY } | quick_color 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 } }

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.

    PIGMENT_DECLARATION:
        #declare IDENTIFIER = PIGMENT |
        #local IDENTIFIER = 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.

#### 6.7.1.1 Solid Color Pigments

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 optional 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.

#### 6.7.1.2 Color List Pigments

There are four color list patterns: `checker`, `hexagon`, `brick` and `object`. 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:

    COLOR_LIST_PIGMENT:
      pigment {brick [COLOR_1, [COLOR_2]] [PIGMENT_MODIFIERS...] }|
      pigment {checker [COLOR_1, [COLOR_2]] [PIGMENT_MODIFIERS...]}|
      pigment {
         hexagon [COLOR_1, [COLOR_2, [COLOR_3]]] [PIGMENT_MODIFIERS...]
      }|
      pigment {object OBJECT_IDENTIFIER | OBJECT {} [COLOR_1, COLOR_2]}

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.

#### 6.7.1.3 Color Maps

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:
        color_map { COLOR_MAP_BODY } | colour_map { COLOR_MAP_BODY }
    COLOR_MAP_BODY:
        COLOR_MAP_IDENTIFIER | COLOR_MAP_ENTRY...
    COLOR_MAP_ENTRY:
        [ Value COLOR ] |
        [ 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: 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.

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`, `object` 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 }
        }
      }

#### 6.7.1.4 Pigment Maps and Pigment Lists

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:
        pigment_map { PIGMENT_MAP_BODY }
    PIGMENT_MAP_BODY:
        PIGMENT_MAP_IDENTIFIER | PIGMENT_MAP_ENTRY...
    PIGMENT_MAP_ENTRY:
        [ Value PIGMENT_BODY ]

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.

#### 6.7.1.5 Image Maps

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.

##### 6.7.1.5.1 Specifying an Image Map

The syntax for an `image_map` is:

    IMAGE_MAP:
        pigment
        {
            image_map
            {
                [BITMAP_TYPE] "bitmap[.ext]"
                [IMAGE_MAP_MODS...]
            }
            [PIGMENT_MODFIERS...]
        }
    BITMAP_TYPE:
        gif | tga | iff | ppm | pgm | png | jpeg | tiff | sys
    IMAGE_MAP_MOD:
        map_type Type | once | interpolate Type |
        filter Palette, Amount | filter all Amount |
        transmit Palette, Amount | transmit all Amount

After the optional BITMAP_TYPE keyword is a string expression containing the name of a bitmapped image file of the specified type. If the BITMAP_TYPE is not given, the same type is expected as the type set for output.
Example:

      plane {
        -z,0
        pigment {
          image_map {png "Eggs.png"}
        }
      }

      plane {
        -z,0
        pigment {
          image_map {"Eggs"}
        }
      }

The second method will look for, and use "Eggs.png" if the output file type is set to be `png` (Output_File_Type=N in INI-file or +FN on command line). It is particulary usefull when the image used in the `image_map` is also rendered with POV-Ray.

Several optional modifiers may follow the file specification. The modifiers are described below.

Note: 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"

##### 6.7.1.5.2 The Filter and Transmit 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: 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.

##### 6.7.1.5.3 Using the Alpha Channel

Another way to specify non-filtered transmit transparency in an image map is by using the alpha channel. POV-Ray will automatically use the alpha channel for transmittance when one is stored in the image. 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`.

#### 6.7.1.6 Quick Color

When developing POV-Ray scenes it's 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. 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.