.POV File Format – Textures and pigments

The texture statement

texture {
  [texture identifier]
  [pigment identifier | normal identifier | finish identifier ...]
  [pigment { ... }] [normal { ... }] [finish { ... }]
  [transformations] [no_bump_scale]
}

Every item is optional. A texture starts as a copy of the identifier if one is given, otherwise as a copy of the default texture (see below). Pigment, normal and finish identifiers (written without their keyword, for old scenes such as texture { MyPigment }) replace that part. A later pigment { … }, normal { … } or finish { … } modifies that part: it is parsed starting from the copy, so pigment { rgb 1 } after an identifier keeps the pattern modifiers of the identifier unless the new statement replaces the pattern.

The pigment, normal and finish statements also work directly inside an object: sphere { 0, 1 pigment { rgb 1 } finish { phong 1 } } builds a texture from the default texture and the given parts. If the object already has a patterned texture, a new layer is started. The object keywords texture, interior_texture, material, interior and cutaway_textures are described on Object modifiers.

Layered textures

In a layered texture all layers except the bottom one should have some transparency (a filter or transmit value in the pigment). The colour of a lower layer shows through where the layers above are transparent. A layer filters the colour of the layers below it, but not the illumination on the way in, so the result is not the same as a stack of transparent surfaces. A layered texture can be declared: #declare Layers = texture { T1 } texture { T2 } texture { T3 }. A pigment, normal or finish written after such an identifier modifies the bottom layer only. A patterned texture cannot be a layer, but a layered texture can be an item of a patterned texture (declare it first). Macros are not allowed inside a layered texture declaration.

Texture maps and block lists

texture {
  pattern [pattern modifiers]
  texture_map { [ value texture body ] ... }
}
texture { checker | brick | hexagon | square | triangular | cubic | object  texture { ... } texture { ... } ... }

With a continuous pattern the map is a texture_map; each entry is what could stand inside texture { … } without the keyword. Where two entries meet, both textures are evaluated completely and their colours mixed, so reflection, refraction and lighting are computed twice. With a block pattern (checker and so on) the textures are listed after the keyword, each in texture { … }; missing items are copies of the default texture. The grammar of maps, their value rules and the list of patterns are on Patterns and maps. In a layered texture, the texture-map form (a patterned texture) cannot be one of the layers.

material_map

texture {
  material_map {
    [bitmap_type] "file"
    [once] [interpolate n] [map_type n]
    [repeat <u, v>] [offset <u, v>]
    texture { … } texture { … } …
  }
  [transformations]
}

The image is placed like an image map (see below) on the square <0,0> to <1,1> of the x-y plane. For an image with a palette, the palette index of the pixel selects the texture from the list; for an image without a palette, the 8-bit value of the red component (0 to 255) is the index. If the index is larger than the number of textures it is taken modulo the number. With once, points outside the unit square get the first texture. At least one texture is needed. No pigment, normal or finish may be written outside the textures. No alpha handling is done: the data of the file is used as it is. interpolate interpolates the index before the texture is chosen, which is rarely useful. A material_map cannot be part of a layered texture; declare it and use the identifier. (Not to be confused with the material statement.)

The #default directive

#default { texture { … } }
#default { pigment { … } }
#default { normal { … } }
#default { finish { … } }

#default changes the default texture, the texture that every new texture starts from. Several of the four items may be written in one block. The default texture must be plain: it cannot be layered (“Default texture cannot be layered.”) or a patterned texture, tiles or material_map (“Default texture cannot be material map or tiles.”). The factory defaults are:

If a scene changes the language version after a #default, the version-dependent factory values are not applied (a warning is given). The default camera right vector depends on the version in the same way, see Cameras.

uv_mapping

All textures are three-dimensional. With uv_mapping a texture is instead taken from the surface coordinates u and v of the object: a slice of the 3D texture from the x-y plane (z = 0) is wrapped around the surface. Some textures should be rotated to fit the slice into the x-y plane.

Objects with surface coordinates: bicubic_patch (the patch parameters; the default corners are <0,0>, <1,0>, <1,1>, <0,1>, changed with uv_vectors), box, cone, cylinder, lathe, sor, lemon, mesh and mesh2 (a UV pair for each vertex), ovus, parametric, sphere, torus. A pattern does not work with uv_mapping in a pattern function.

The pigment statement

pigment {
  [pigment identifier]
  [colour | pattern type | image_map { … } | user_defined { … }]
  [pattern modifiers]
  [color_map { … } | pigment_map { … }] [quick_color colour]
}

An identifier first, if present, supplies the starting pigment; the other items modify it. Without an identifier the items modify a copy of the pigment of the default texture. The pattern type is one of the patterns of Patterns and maps, a plain colour, or an image_map. Pigment modifiers apply only to the pigment, not to the other parts of the texture. A pigment can be declared with #declare Name = pigment { … }; the identifier is then used as pigment { Name } or, with a texture, as texture { Name }.

Pigment-specific items, in addition to the pattern modifiers:

Filter and transmit

A colour has five components: red, green, blue, filter and transmit. rgbf and rgbt set the fourth component, rgbft all five; the keyword form is rgb 1 filter 0.5 transmit 0.2 (also red, green, blue). srgb, srgbf, srgbt, srgbft do the same for sRGB values. The full colour syntax is on Expressions.

• filter is filtered transparency: light passing through the surface is tinted by the colour of the surface (stained glass). The colour is subtracted from the light.
• transmit is non-filtered transparency: light passes unchanged but is reduced in amount (fine mesh, dust). The colour of the object and the transmitted colour together make 100 per cent: with transmit 0.9, 90 per cent of the colour comes from behind and 10 per cent from the object. Values outside 0 to 1 are allowed and act like contrast (transmit 2 doubles the contrast around the object colour, a negative value inverts it).
• Both apply only to the diffuse, ambient and emission components, unless the finish has use_alpha on; then they also hide the highlights and the specular reflection.
• In layered textures filter and transmit decide how much of the layers below shows through. A finish with conserve_energy reduces both by the amount that is reflected.

Colour maps

color_map | colour_map {
  [blend_mode 0..3] [blend_gamma g]
  [ value colour ] ...
}

A colour map turns the value of a pattern (0 to 1 after the wave type) into a colour. Entries are written [ value colour ] in ascending order of value; the brackets belong to the syntax. A value below the first entry gets the first colour, at or above the last entry the last colour, and between two entries the colours are blended linearly. Two entries with the same value ([0.6 Blue] [0.6 Green]) make a sharp edge; a value equal to that number takes the second colour. Entries with the same colour next to each other make a flat band. The colours may use filter and transmit: the map then blends those too. A colour map can be declared (#declare Rainbow = color_map { … }) and used by its identifier (color_map { Rainbow }). It cannot be used with checker, brick, hexagon, object, square, triangular, cubic, average, or image_map: the parser gives “Cannot use color_map with this pattern type.” The map has at least one entry; version 3.8 has no upper limit. Details of the blend modes and the old double entry [0.0 0.1 color Red color Red] are on Patterns and maps.

sphere { 0, 1
  pigment {
    gradient x
    color_map {
      blend_mode 1
      [0.0 rgb <1, 0, 0>]
      [0.3 rgbt <1, 1, 0, 0.5>]
      [0.3 rgb <0, 0, 1>]
      [1.0 rgbf <0, 1, 0, 0.8>]
    }
    quick_color rgb 0.5
  }
}

Image maps

pigment {
  image_map {
    [bitmap_type] "file" | function w, h { body }
    [gamma g] [premultiplied bool]
    [map_type n] [once] [interpolate n]
    [filter all f | filter index, f]
    [transmit all t | transmit index, t]
    [use_colour | use_index]
    [repeat <u, v>] [offset <u, v>]
  }
}

An image map wraps a picture around the object. By default the image is projected on the x-y plane as if from a slide projector in the −z direction. It exactly fills the square from <0, 0> to <1, 1> of the x-y plane, whatever its size in pixels. Imagine each pixel as a long thin rod along the z axis; the object is carved out of the bundle. Move, scale and rotate the pigment to place the image. The same keywords (without filter and transmit) are accepted by bump_map, image_pattern and material_map. The file is searched in the current directory first, then in the library paths (+L, Library_Path).

The image source

Keywords

The old keyword alpha still means filter (a warning for language versions of 1.55 and later). An image with an alpha channel uses it as transmit automatically; alpha 255 is transmit 0 and alpha 0 is transmit 1. The old syntax with a vector or map type before the file type is ignored with a warning.

sphere { 0, 1
  pigment {
    image_map {
      function 64, 64 { pigment { checker rgb <1, 0, 0>, rgb <0, 0, 1> scale 0.1 } }
      map_type 1
      interpolate 2
      filter all 0.2
    }
  }
}

plane { -z, -3
  pigment {
    image_map {
      function 8, 8 { pattern { checker } }
      once
      transmit all 0.5
    }
    scale 4
    translate <-2, -2, 0>
  }
}

The material statement

material {
  [material identifier]
  [texture { … }] [interior_texture { … }] [interior { … }]
  [transformations]
}

A material bundles the surface texture with the interior (the volume properties, see Media, interior and atmosphere). It is declared with #declare Name = material { … } and used inside an object: sphere { 0, 1 material { Name } }. Several texture items are layers. interior_texture is the texture of the inside surface of the object. The transformations are applied to the textures and to the interior (its media density). If the object has a texture already, the material adds its layers on top.

#declare Glass = material {
  texture {
    pigment { rgbf <1, 1, 1, 0.9> }
    finish { reflection 0.05 specular 0.8 roughness 0.01 }
  }
  interior { ior 1.5 }
}

sphere { 0, 1 material { Glass } }

How transformations apply

A pattern is fixed in space: a transformation of an object does not move a texture that was set before it, and a transformation of a texture or pigment moves the pattern, not the surface. A translate, rotate, scale, matrix or transform inside a pigment, normal, texture or density changes the pattern and works like the same word on an object. In a finish transformations are not allowed. Scaling an object after the texture is set scales the texture with it (and its bumps, unless no_bump_scale).

Inside one pattern, the transformations and the warps are applied in the order written (as one list), and the classic turbulence is applied before all of them, regardless of where it is written. To put turbulence at a chosen place, write it in a warp. In a texture map the transformation of the outer texture moves the pattern and, with it, the textures of the map; a transformation inside an entry moves only that entry. pigment_pattern and image_pattern keep their own transformation, independent from the items they choose.

sphere { 0, 1
  texture {
    pigment {
      gradient y
      color_map { [0 rgb <1, 0.8, 0>] [1 rgb <0.8, 0, 0>] }
      scale 2        // pigment only
    }
    normal { bumps 0.4 }
    rotate x*20      // pigment and normal, not the finish
    finish { phong 0.5 }
    translate y      // pigment and normal; the finish has no position
  }
}

Warps

A warp moves the point at which a pattern is evaluated. It is a pattern modifier for pigments, normals, textures and densities. A pattern can have any number of warp { … } statements; they and the transformations are applied in the order written.

warp { one warp }
  repeat <direction> [offset <v>] [flip <v>]
  black_hole <centre>, radius [strength s] [falloff f] [inverse] [type t] [repeat <v>] [turbulence <v>]
  turbulence <amount> [octaves n] [omega o] [lambda l]
  cylindrical | spherical [orientation <v>] [dist_exp e]
  toroidal [orientation <v>] [dist_exp e] [major_radius r]
  planar [<normal>, offset]
  cubic

Any other word after warp { is the error “Expected warp type”, and an empty warp: “Empty warp statement.” The warps are not applied to the normal of a pattern; for the perturbed normals only the transformations are.

box { <-3, -1, -1>, <3, 1, 1>
  pigment {
    wood
    color_map { [0 rgb <0.8, 0.5, 0.2>] [1 rgb <0.3, 0.15, 0.05>] }
    warp { repeat 1*x offset <0, 0, 0.1> flip <1, 0, 0> }
    warp { turbulence 0.2 octaves 3 omega 0.4 lambda 2.5 }
    rotate x*90
  }
}

sphere { <0, 3, 0>, 1
  pigment {
    checker rgb 1, rgb 0
    scale 0.1
    warp { spherical orientation y dist_exp 1 }
  }
}

sphere { <-2.5, 0, 0>, 1
  pigment {
    wood
    color_map { [0 rgb <0.8, 0.5, 0.2>] [1 rgb <0.3, 0.15, 0.05>] }
    warp { black_hole <0, 0, 0>, 0.5 falloff 3 strength 1.5 inverse }
    warp { planar y, 0.25 }
  }
}

Turbulence, octaves, omega and lambda

Turbulence is random noise that moves the point at which a pattern is evaluated. It works as a pattern modifier (turbulence amount directly in the pigment, normal, texture or density) and as a warp (warp { turbulence amount … }). It also works in fog and in the iridescence of a finish (see Media, interior and atmosphere and Normals and finishes).

The point p becomes p + turbulence × d (per axis), where d is the sum over the octaves k = 0 to octaves − 1 of omega^k × DNoise(p × lambda^k). DNoise is a vector noise: smooth, with a direction at each point. The word “classic turbulence” means the form without warp. It is stored first in the list of the pattern, is always applied before everything else, and is treated specially by agate, marble, spiral1, spiral2 and wood (their formulae use the turbulence value themselves). octaves, omega and lambda outside a warp belong to the classic turbulence and create it even when no amount is given.

Not described

Known, not yet covered

• Reference: the exact blend formulae of the colour map blend modes 1 to 3 and the layer maths (how filter and transmit of each layer combine in the lighting calculation) are described only by effect; the code in source/core/lighting was not followed through.
• Reference: the surface coordinates of each object for uv_mapping are listed from the manual, not checked in the object code.