.POV File Format – Light sources

Syntax

light_source {
  <location> [,] [colour]
  [spotlight | cylinder | parallel | shadowless]
  [point_at <v>] [radius r] [falloff f] [tightness t]
  [area_light <axis1>, <axis2>, size1, size2]
  [adaptive n] [jitter] [circular] [orient] [area_illumination [bool]]
  [fade_distance d] [fade_power p]
  [media_interaction [bool]] [media_attenuation [bool]]
  [looks_like { object }] [projected_through { object }]
  [photons { … }]
  [translate | rotate | scale | transform | matrix …]
}

The location and the colour come first. A light source can also be an identifier: #declare L = light_source { … } and then light_source { L } (or object { L }). Only the red, green and blue parts of the colour are used; a filter or transmit value is ignored. The colour is also the intensity: rgb 0.5 is a white light at half strength, and values above 1 are allowed. If no colour is written the light is white (rgb 1). No object modifiers other than transformations may be used (the parser stops at the first other word). The items can be in any order, but spotlight or cylinder must come before radius, falloff and tightness, and parallel before point_at for a plain light.

A light has one type: a point light (the default), a spotlight, a cylinder light, a parallel light or a shadowless (fill) light. area_light can be combined with any of them.

Keywords and defaults

The manual says that the cylinder defaults radius 0.75 and falloff 1 are in degrees. In the source (Attenuate_Light in source/core/lighting/lightsource.cpp) they are distances from the axis, and the page lists them so. The manual’s overview also lists radius 70, falloff 70 and tightness 10 as light defaults, which are not what the parser sets for either type.

Intensity of spotlights and cylinder lights

For a spotlight the parser stores the cosines of the two angles. For a ray at the angle θ from the axis the intensity factor is zero if θ is 90 degrees or more (the light is behind the spot), otherwise cos(θ) ^ tightness, and further multiplied by a cubic spline between 1 (at the radius angle) and 0 (at the falloff angle) when θ is beyond the radius. For a cylinder, the point must be in front of the light (positive along the axis), the factor is zero at the falloff distance from the axis or beyond and (1 − d / falloff) ^ tightness inside, with a cubic spline between the radius and the falloff distance. After that, if fade_power is positive, the fading factor below is applied.

Light fading

By default light does not weaken with distance. With fade_power greater than 0, the intensity is multiplied by

2 / (1 + (d / fade_distance) ^ fade_power)

where d is the distance from the light. At d = fade_distance the factor is 1, so the colour is the intensity there; closer than that the light is brighter. Only light coming straight from the source is attenuated, not reflected or refracted light. From language version 3.8, fade_distance 0 with a positive fade_power gives the inverse power law d ^ −fade_power at all distances, with the nominal intensity at distance 1. In older language versions that combination gives a warning, and the fading is ignored. For realism use fade_power 2 and a fade_distance of about the radius of the glowing body, and brighten the colour if the light is then too dim.

looks_like

looks_like { object } puts an object at the position of the light, so that the light has a visible shape (a lamp, a sun). The object should be modelled at the origin; the parser moves it to the light location. It may have object modifiers after it inside the braces. Only one looks_like is allowed (“Only one looks_like allowed per light_source.”). The object and the light get no_shadow, so the light can leave an opaque object. It works with point lights and spotlights, not with parallel lights. If the object should block light, use a union of the light and the object instead, with some part transparent.

projected_through

projected_through { object } works with every type of light, including area lights. Only the light rays that go through the object contribute to the scene; it is the opposite of a shadow. Objects between the light and that object, and surfaces inside it, cast no shadows. Textures and interiors of the object are removed and it is not seen. Only one is allowed (“Only one projected through allowed per light_source.”).

Photons

The global photon settings are on Global settings. The photon keywords of objects (target, pass_through, collect) are on Object modifiers; a light group takes them too.

light_group

light_group {
  light_source | object | light_group …
  [global_lights [bool]]
  [translate | rotate | scale | transform | matrix …]
  [photons { target [density] refraction bool reflection bool pass_through [bool] collect [bool] }]
}

A light group is a union of lights and objects. The lights in the group light only the objects in the group (this includes scattering media, which must be in the group too). The objects in the group are lit by the lights of the group and, only with global_lights on (a number above 0.5; written without a value it is on), also by the global lights. The default is off, so the global lights do not reach the objects of a group. Light groups can be nested: an inner group also gets the lights of the group it is in. A light group can be used in CSG. Only transformations, global_lights and photons may follow the contents; other object modifiers are not accepted. Light groups help when some objects are too dark but the overall light is right, since the lights of the group do not change the global lighting.

Lights in CSG and shadows

A light source can be a member of a union together with objects, and the whole union can be moved with one translate or rotate. A union that holds only light sources is marked as a light source union. A looks_like object belongs to its light and is moved with it. A light source is flagged no_shadow itself, so it does not block other lights; the object of a looks_like also gets no_shadow.

For each light and each surface point the renderer shoots a shadow ray toward the light. An opaque object in the way blocks the light. A transparent one lets light pass, filtered by its colour. An object with no_shadow never blocks. An area light shoots one ray for each of the lights of the array (or fewer with adaptive), so a partly hidden area light gives a soft shadow. A shadowless light shoots no shadow rays. If the light has media_interaction on and media_attenuation on, the shadow ray also takes part in the dimming by fog and media in between.

Examples

// a point light that fades with distance
light_source {
  <10, 20, -10>, rgb 1
  fade_distance 20
  fade_power 2
}

// a spotlight: full intensity inside 10 degrees, zero beyond 20 degrees
light_source {
  <0, 10, 0>, rgb <1, 0.9, 0.7>
  spotlight
  point_at <0, 0, 0>
  radius 10
  falloff 20
  tightness 10
}

// a cylinder light: radius and falloff are distances from the axis
light_source {
  <-5, 5, -5>, rgb <1, 0, 0>
  cylinder
  point_at <0, 0, 0>
  radius 0.5
  falloff 1
}

// a parallel light, like the sun
light_source {
  <0, 100, 0>, rgb 0.5
  parallel
  point_at <0, 0, 0>
}

light_source {
  <0, 8, 0>, rgb 1
  area_light <2, 0, 0>, <0, 0, 2>, 5, 5
  adaptive 1
  jitter
  circular
  orient
  area_illumination on
}

light_source {
  <6, 5, -6>, rgb 0.6
  area_light x*3, y*0.2, 8, 1
  spotlight
  point_at 0
  radius 20
  falloff 40
}

#declare Bulb = sphere { 0, 0.3 pigment { rgbf <1, 1, 0.8, 0.5> } finish { emission 1 diffuse 0 } }

light_source {
  <3, 4, -3>, rgb 1
  looks_like { Bulb }
  media_interaction on
  media_attenuation off
}

light_source {
  <-3, 6, -2>, rgb 1
  shadowless
  projected_through { box { -1, 1 } }
}

#declare Lamp = light_group {
  light_source { <-5, 5, -5>, rgb <1, 0, 0> }
  sphere { <4, 0, 0>, 1 pigment { rgb 1 } }
  global_lights off
  translate y
}

object { Lamp }

union {
  light_source { <0, 3, 0>, rgb <0, 0, 1> }
  sphere { <0, 3, 0>, 0.1 pigment { rgb <0, 0, 1> } finish { emission 1 } }
  rotate y*30
}

Not described

Known, not yet covered

• Reference: the shadow-ray code was summarised from the renderer source (source/core/render/trace.cpp) and the manual, not followed line by line, and the effect of no_shadow on transparent objects in an area light is not described.
• Reference: the photon switches of a light are listed from the parser; how they combine with the global photon settings (photons in global_settings) was not checked in the photon code.