.POV File Format – Patterns and maps

Where a pattern can be used

Grammar of a pattern inside a statement: the pattern type comes first, then any number of modifiers in any order. In a normal an optional number (the bump size) may follow the pattern type: bumps 0.4, gradient x, 0.5 (the comma matters when the number is negative). Statements that take a block list (checker, brick …) accept colours, or wrapped items, directly after the keyword.

Continuous patterns

These return a number. The result goes through the wave type (ramp unless noted) after value * frequency + phase. “Default map” is the blend map used when a pigment uses the pattern without any map of its own; all other patterns use a black-to-white ramp ([0 rgb 0] [1 rgb 1]).

spotted and bozo share their noise, but only bozo has its own colourful default map. The default maps matter when such a pattern is used without a map, for instance in a function or in media. The patterns facets (normals only), slope and aoi depend on the surface normal and are listed below.

Block patterns

A block pattern has no number between 0 and 1: it selects item n of a list. The list is written right after the keyword. In a pigment each item is a colour (a comma between colours is optional) or pigment { … }. In a normal each item is normal { … }, in a texture texture { … }, in a density density { … }. Items you leave out take the defaults of the table. Block patterns cannot use color_map, slope_map or wave types, and frequency and phase only give a warning (“has no effect on discrete patterns”).

With normal, the optional bump size after the keyword is parsed when no item is written (checker 0.5).

Fractal patterns

mandel iterations [exponent n] [exterior type, factor] [interior type, factor]
julia <re, im>, iterations [exponent n] [exterior …] [interior …]
magnet 1|2 mandel iterations [exterior …] [interior …]
magnet 1|2 julia <re, im>, iterations [exterior …] [interior …]

For types 0 and 2 to 6 the result is multiplied by the factor. For magnet a type other than 1 or 2 is the error “Invalid magnet-mandel pattern type found. Valid types are 1 and 2.”

Patterns that depend on the surface

These patterns need a surface; they have no value for a sky sphere or media.

Special patterns

average

average does not return a number. It blends all entries of its map. With a pigment map, texture map or density map the entries are weighted and divided by the sum of the weights. With a normal map the perturbed normals are weighted, added and normalised. The number in each entry is the weight and is optional (default 1). The parser stops with “Average must have map.” when there is no map, and color_map and slope_map are refused with it.

image_pattern

image_pattern {
  [bitmap_type] "file" [gamma g] [premultiplied bool]
  [map_type n] [once] [interpolate n]
  [use_colour | use_index | use_alpha]
  [repeat <u, v>] [offset <u, v>]
}

The grey value of the pixel (or the palette index with use_index, or the alpha with use_alpha) is the pattern value. The image fills the square <0,0> to <1,1> of the x-y plane. The keywords are the same as for image_map, see Textures and pigments. Instead of a file, function w, h { … } builds an image from a function, a pattern function or a pigment (the example below). An image pattern has frequency 0, so the wave type applies without a frequency.

user_defined

pigment {
  user_defined {
    function { red }, function { green }, function { blue },
    function { filter }, function { transmit }
  }
}

A pigment (or density) pattern that sets the colour directly. Each of the five functions is optional; a missing one is 0 (the commas stay, ,,). It cannot have a map. It is an error in a normal or texture (“Only in pigment or density”) and it is not accepted in a pattern function.

Plain colour and uv_mapping

A colour written where a pattern type is expected is the “plain” pattern: one colour, no pattern. Modifiers on it have no effect. uv_mapping inside a pigment, normal or texture turns the statement into a surface-coordinate pattern (see Textures and pigments).

Keywords that belong to one pattern

Using one of these keywords with another pattern is an error such as “Only in crackle” or “Not with non-agate”.

Pattern modifiers

These can follow the pattern in a pigment, normal, texture and density.

frequency, phase and the wave types have no effect on image_map, bump_map and material_map. The manual also states that the pattern-specific normals bumps, dents, quilted, ripples, waves, wrinkles ignore maps and wave types in a normal.

Blend maps

A map is a list of entries [ value item ]. The square brackets are part of the syntax. The pattern value (after the wave) is searched in the list: below the first entry the first item is used, at or above the last entry the last item is used, and between two entries the items are blended in proportion to the distance. Two entries with the same value make a hard edge: a value equal to that number gets the second one. Entries must be written in ascending order of value; the parser does not sort them. A comma after value is optional. At least one entry is needed (“Must have at least one entry in map.”); version 3.8 has no upper limit.

An entry body is what could stand inside the braces of the statement, without the keyword and braces: [0.3 wood scale 0.2], [0.6 Jade] (an identifier), [0.9 pigment { rgb 1 } finish { phong 1 }] for a texture. A map can be declared and used by its identifier: color_map { Rainbow }. An identifier map must be of the same kind, otherwise “Wrong identifier type”.

Colour map entries

Two entries that are exactly equal in value and colour next to each other are merged.

Blend modes

A color_map or pigment_map (also in a density) may start with these two items before the first entry:

Both are errors in other maps (“Only in colour_map or pigment_map”).

Pattern functions

A pattern can be used as a function of x, y, z inside function { … }:

function { pattern { pattern [modifiers…] } }

The result is the number of the pattern after its wave type, before any map. These patterns are accepted: agate, bozo, bumps, cells, checker, brick, hexagon, cubic, object, crackle, cylindrical, dents, density_file, function, gradient, granite, image_pattern, julia, leopard, magnet, mandel, marble, onion, pavement, pigment_pattern, planar, potential, quilted, radial, ripples, spherical, spiral1, spiral2, spotted, tiling, boxed, waves, wood, wrinkles. Not accepted: square, triangular, slope, aoi, average, facets, image_map, bump_map, user_defined, uv_mapping, a plain colour, and the maps (the parser stops with a parse error for them). The modifiers are the same as above except that accuracy, bump_size and the maps are not accepted.

A pattern function can also be used as a pattern: pigment { function { MyFn(x, y, z) } color_map { … } }. A pigment can be turned into a function as well; its components are read with .red, .green, .blue, .filter, .transmit (see Functions and constants).

Examples

plane { y, 0
  pigment {
    gradient x
    color_map {
      [0 rgb <1, 0, 0>]
      [1 rgb <0, 0, 1>]
    }
    triangle_wave
    frequency 2
    phase 0.25
  }
}

sphere { 0, 1
  pigment {
    average
    pigment_map {
      [2 checker rgb 1, rgb 0 scale 0.25]
      [1 gradient y color_map { [0 rgb <1, 0.5, 0>] [1 rgb <0, 0.5, 1>] }]
    }
  }
}

sphere { <2, 0, 0>, 1
  pigment {
    checker
    pigment { rgb <1, 0, 0> }
    pigment { wood scale 0.2 }
    scale 0.5
  }
}

#declare Cyl  = function { pattern { cylindrical } }
#declare Grad = function { pattern { gradient x ramp_wave } }
#declare Wd   = function { pattern { wood } }
#debug concat("cylindrical at (0.5, 3, 0): ", str(Cyl(0.5, 3, 0), 0, 3), "\n")
#debug concat("gradient at x = 1.25: ", str(Grad(1.25, 0, 0), 0, 3), "\n")
#debug concat("wood at x = 0.5: ", str(Wd(0.5, 0, 0), 0, 3), "\n")

sphere { 0, 1
  pigment {
    function { Cyl(x, y, z) * 0.5 + Wd(x, y, z) * 0.5 }
    color_map { [0 rgb 0] [1 rgb 1] }
  }
}

box { <-2, -2, 0>, <2, 2, 0.1>
  pigment {
    julia <0.353, 0.288>, 30
    interior 1, 1
    color_map {
      [0 rgb 0]
      [0.2 rgb x]
      [0.4 rgb x + y]
      [1 rgb 1]
    }
  }
}

box { <-2, -2, 0.2>, <2, 2, 0.3>
  pigment {
    mandel 25
    exponent 3
    exterior 7, 8
    color_map { [0 rgb <0, 0, 0.3>] [1 rgb <1, 1, 0>] }
  }
}

box { <-2, -2, 0.4>, <2, 2, 0.5>
  pigment {
    magnet 2 julia <0.5, 0.2>, 30
  }
}

sphere { 0, 1
  texture {
    slope { y, 0.0, 0.5 }
    texture_map {
      [0 pigment { rgb <0.9, 0.9, 1> }]
      [1 pigment { rgb <0.2, 0.5, 0.1> } finish { phong 0.3 }]
    }
  }
}

plane { y, -1
  pigment {
    image_pattern { function 16, 16 { pattern { checker } } interpolate 2 }
    color_map { [0 rgb <1, 1, 0>] [1 rgb <0, 0, 1>] }
  }
}

sphere { <2, 0, 0>, 0.7
  pigment {
    crackle form <1, 0, 0> metric 1 offset 0.1 repeat <3, 3, 3>
    color_map { [0 rgb 0] [1 rgb 1] }
  }
}

Internals and notes

• The parser keeps one list of “warps” for each pattern. Classic turbulence (turbulence, octaves, omega, lambda outside a warp) is always the first item in the list. Each translate, rotate, scale, matrix and transform is merged into the last transform step, or added as a new one after a warp. The sample point passes through the list from first to last, and the result is looked up in the pattern.
• agate, marble, spiral1, spiral2 and wood handle the classic turbulence themselves (the turbulence value is part of their formula); agate always has turbulence settings, so a turbulence step is always present. For other patterns the classic turbulence moves the point before the pattern is evaluated.
• Noise patterns (bozo, spotted, bumps, granite, wrinkles, dents) depend on noise_generator. crackle caches data per unit cube (the manual gives 30 MB per thread) and discards new entries once the cache is full.
• The default blend maps are used only when a pigment (or density) has a pattern but no map. A pattern with a map ignores them.
• The parser accepts repeat and offset in image_pattern (and in the other bitmaps), which the manual does not list. The manual gives other default colours for square (“red, blue, yellow and green”) and triangular (“blue, green, red, magenta, cyan and yellow”) than the default colour list in source/core/material/pattern.cpp, which is the one in the table above.