.POV File Format – Global settings, radiosity and photons

Syntax

global_settings {
  adc_bailout Float
  ambient_light Colour
  assumed_gamma Float | srgb | bt709 | bt2020
  charset ascii | utf8 | sys
  hf_gray_16 [Bool]
  irid_wavelength Colour
  max_intersections Integer
  max_trace_level Integer
  mm_per_unit Float
  noise_generator 1 | 2 | 3
  number_of_waves Integer
  radiosity { radiosity items }
  photons { photon items }
  subsurface { subsurface items }
}

The parser reads the items until it meets a word that is not one of these; that word must then be the closing brace, or the scene stops with an error. The word for photons is photons (the manual's syntax line writes photon; the parser has only photons).

Items

#version 3.8;
global_settings {
  assumed_gamma 1.0
  adc_bailout 0.01
  ambient_light rgb <0.8, 0.8, 1>
  irid_wavelength rgb <0.7, 0.52, 0.48>
  max_trace_level 12
  mm_per_unit 10
  noise_generator 3
  number_of_waves 5
}
camera { location <0, 1, -4> look_at 0 }
light_source { <5, 8, -6> rgb 1 }
plane { y, -1
  pigment { wrinkles scale 0.3 }
  normal { waves 0.3 }
  finish { ambient 0.1 }
}
sphere { 0, 1 pigment { rgb <1, 0.4, 0.2> } finish { ambient 0.1 } }

Radiosity

Radiosity replaces the constant ambient term by a light level computed from the surfaces around a point. The program shoots rays into the hemisphere above a point, averages what they see (using the diffuse colour of what they hit), stores the result as a sample and reuses it for nearby points. A first pass (the pretrace) works over the image in a mosaic of blocks that grow finer, so that the final pass finds most of the samples it needs. The settings trade quality against speed.

• Radiosity runs only when the quality level is 9 or more (+Q9, the default).
• In a scene of version 3.7 or later, a surface that gets radiosity has its finish ambient ignored. To make a surface glow, use emission in its finish. A scene of an older version keeps both.
• A radiosity block in a scene below 3.5 only warns that the block now turns radiosity on. The radiosity of 3.7 and later cannot be switched back to the old method with #version.
• The cache file is not named in the scene any more: load_file and save_file inside radiosity are read and ignored, with a warning. Use Radiosity_From_File, Radiosity_To_File and Radiosity_File_Name.

Two object-level words belong with radiosity: radiosity { importance Float } in an object (the fraction of its sample rays that are fully computed, above 0 up to 1) and no_radiosity (hides the object from radiosity rays). Both are covered under Object modifiers.

#version 3.8;
global_settings {
  assumed_gamma 1.0
  radiosity {
    pretrace_start 0.08
    pretrace_end   0.02
    count 120
    nearest_count 6
    error_bound 0.5
    recursion_limit 2
    low_error_factor 0.8
    minimum_reuse 0.015
    brightness 1.0
    always_sample off
  }
}
camera { location <0, 1, -4> look_at 0 }
light_source { <5, 8, -6> rgb 1 }
plane { y, -1 pigment { rgb 0.8 } finish { ambient 0 } }
sphere { 0, 1 pigment { rgb <1, 0.4, 0.2> } finish { ambient 0 } }

The presets of rad_def.inc

The include file rad_def.inc declares eleven constants and a macro that expands to the keywords of a preset. Put #include "rad_def.inc" before global_settings and call the macro inside the radiosity block:

Rad_Settings(preset, normal, media)

The second and third parameters (on or off) become the normal and media keywords. Every preset sets gray_threshold 0, brightness 1.0 and adc_bailout 0.005, and the macro prints the name of the preset to the debug stream. The keywords you add after the macro override it.

All presets except the first set pretrace_start 0.08. The file sets #version 3.5 while it is read and restores the version of the scene afterwards.

#version 3.8;
#include "rad_def.inc"
global_settings {
  assumed_gamma 1.0
  radiosity {
    Rad_Settings(Radiosity_Normal, off, off)
    always_sample off
    recursion_limit 2
  }
}
camera { location <0, 1, -4> look_at 0 }
light_source { <5, 8, -6> rgb 1 }
plane { y, -1 pigment { rgb 0.8 } finish { ambient 0 diffuse 0.8 } }
sphere { 0, 1 pigment { rgb <1, 0.4, 0.2> } finish { ambient 0 diffuse 0.8 } }

Photons

Photon mapping computes caustics. Before the image is traced the program shoots photons from the light sources at the objects that are marked as targets. Where a photon has passed through or bounced off such an object and then lands on a surface, it is stored. During the trace, the stored photons near a point are gathered to estimate the extra light. Photons run only at quality 9 or more. (The manual gives 6 or more for photons; the program's quality flags in coretypes.h turn them on at 9, and the parser's own warning says "quality is set to 8 or less".)

#version 3.8;
global_settings {
  assumed_gamma 1.0
  photons {
    count 20000
    gather 20, 100
    autostop 0
    jitter 0.4
  }
}
camera { location <0, 1, -4> look_at 0 }
light_source { <5, 8, -6> rgb 1 }
plane { y, -1 pigment { rgb 0.8 } }
sphere { 0, 1
  pigment { rgbf <1, 1, 1, 0.9> }
  finish { reflection 0.05 }
  interior { ior 1.3 }
  photons { target reflection on refraction on collect off }
}

Photon words outside global_settings

The same blocks are described with their objects on Object modifiers, Lights and Media and interior.

Subsurface

Subsurface light transport (translucent materials such as skin or wax) runs only when a subsurface block exists in global_settings, even an empty one, and only at quality 9 or more. A material then opts in with subsurface { translucency Colour } in its finish. This is an experimental feature; the render reports it as such.

The scale of the effect depends on mm_per_unit; any effect of a change of it can also be had by changing the translucency of the materials.

Light groups and global lights

A light_group is a union of light sources and objects whose lights illuminate only the objects of the group (and the scattering media in it). Inside the group, global_lights on makes the objects also receive the global lights; off (the default) keeps them to the group's own lights. Light groups nest and combine with CSG. They are covered on Lights. They are mentioned here because the global lights, radiosity and photons all work on the objects of a group like any others.

Not described

Known, not yet covered

• Reference: the exact interplay of count and spacing when both are given was not traced through the photon code; autostop and expand_thresholds are described as the manual describes them. The effect of a count above 1600 for radiosity is taken from the manual and was not checked in the radiosity source.