3.5 Textures

POV-Ray 3.6 for UNIX documentation 3.5.1 Pigment

3.5.2 Normal

3.5.1 Pigment

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.

3.5.1.1 Solid Color Pigments

  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.

3.5.1.2 Color List Pigments

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]}

3.5.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 }
    }
  }

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

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

3.5.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 particularly useful 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"

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

3.5.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 is not 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.

3.5.1.6 Quick Color

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

More about "Pattern Modifiers"

• 3.5.12 Pattern Modifiers in 3.5 Textures
• 3.8.10.8 Pattern Modifiers in 3.8.10 Texture

3.5 Textures

3.5.1 Pigment

3.5.2 Normal