BeamTest 1.2.1 User Manual

A library module from the Persistence of Vision Ray Tracer (POV-Ray) Object Collection.


[Thumbnail which links to a demo image] Sometimes, it is desirable to know the behavior of light refracting through or reflecting off a transparent or specular object before incorporating the object into a scene. Examples could be a gem cut or a lens system. BeamTest provides for optical testing of such objects by shooting beams of light at two-dimensional slices of objects.

Table of Contents


Downloaded Files

The italicized nnnnnn in some of the file names represents the 6-digit number that is in the name of the .zip file.

Key Files
File Description
beamtest.html The user manual (this document) The BeamTest software
beamtest.pov A demonstration scene description file
beamtest.jpg Sample output images
beamtest_spectral.pov A scene description file demonstrating use with Lilysoft’s SpectralRender
beamtest_spectral.jpg A spectrally rendered sample output image
Administrative Files
File Description
READMEnnnnnn.html Important information about using the POV-Ray Object Collection
beamtest_description.txt A brief description of BeamTest
beamtest_keywords.txt A list of keywords
beamtest_prereqs.txt Prerequisites
beamtest.css Other administrative files

Note: The file beamtest_cc-lgpl.png is no longer used.

Table of contents


BeamTest requires POV-Ray version 3.6 or later. POV-Ray 3.7 or later is recommended for the most accurate dispersion.

The demo scene beamtest_spectral.pov requires SpectralRender and Lightsys IV (available under other licenses), and POV-Ray 3.7 or later. (These are not prerequisites for general use of the module.) Only two files from Lightsys are actually required; if you do not wish to download the entire package, these two files can be downloaded at the SpectralRender page, in the prerequisites section.

Namespace Compliance

All file names in this module and all global and local identifiers defined in comply fully with the Object Collection naming standards, as revised August 2008 and proposed August 2012. The reserved prefixes for this module are “BeamTest” and “Beam,” including any uppercase and lowercase variants. To avoid conflicts, do not introduce into your scene description file any identifiers with these names, or any identifiers that start with these names plus an underscore.

The identifier View_POV_Include_Stack from the standard include file is referenced by; itself is not used.


  1. Declare the appropriate parameters, described below.
  2. Include this file once prior to using any of the macros:

    #include ""

    Including the file more than once is harmless, though unnecessary.

  3. Create the light sources using the provided macros, and place the objects to be tested.

A camera is set up automatically, and the assumed_gamma is set to 1.

Light fixtures are arrayed along the left side of the image (with the x direction being toward the right). The user chooses the height, aiming, and color of the lights.

The objects to be tested should be placed to the right (with the x direction being toward the right), with the slice to be tested along the x-y plane. All tested objects must be declared as a photons { target }; in addition, refractive objects must be declared hollow.

In POV-Ray 3.7.0, spurious unrefracted light beams are often traced concurrently with refracted beams. This can be avoided by disregarding the POV-Ray recommendation to set collect off in the photons{} block of the refracting object.

So that objects in the scene may be visible, an environmental light is created automatically. This light does not shoot photons or interact with media. To accommodate spectral rendering with SpectralRender, the color of this light may be set by the user.

Table of contents

Global Parameters

The following parameters may be modified by declaring them prior to including

Parameter Type Description Default
Beam_c_lighting color The color of the environmental lighting. rgb 1
Beam_extinction float Scattering extinction of the environmental media. This value may need to be increased if Beam_image_depth is increased. A practical maximum appears to be 0.1. 0.0
Beam_field_of_view float Camera angle, in degrees. If set to 0, the orthographic camera will be used. 0.0 (changed from previous versions)
Beam_fixture_length float Length of each light fixture, in POV units 0.6
Beam_fixture_radius float Radius of each light fixture, in POV units 0.1
Beam_fixture_shadow float/Boolean Whether or not the light fixtures cast shadows. Set this parameter to no if the fixtures interfere with the light beams. yes
Beam_fixture_x float Horizontal position of the light fixtures -5.0
Beam_image_depth float Depth (in the z-direction) of the environmental media, in POV units. Set a large value if a test object deflects light outside the x-y plane. (Warning: This may slow render times and oversaturate deflected light beams.) Slightly more than twice Beam_radius
Beam_image_height float Height of the image, in POV units. Normally, this parameter is calculated automatically, but the user may set it to force a certain aspect ratio. Derived from Beam_image_width and the image dimensions, in pixels.
Beam_image_width float Width of the image, in POV units 32/3
Beam_max_trace float Maximum trace level 15
Beam_photons float
  • If greater than 1.0, the photon count;
  • Otherwise, if greater than 0.0, the photon spacing;
  • Otherwise photons are not used.
Note: Photons are required for a proper simulation; they should be turned off only for draft renders.
Beam_photons_media float Maximum media photons (media max_steps) 200
Beam_radius float Radius of each light beam, including the falloff, in POV units 0.05
Beam_umbra float The width of the bright core of each light beam, i.e., without the falloff, as a fraction of the total diameter 0.5

Table of contents


Beam_angled (Height, Color, Angle)

A light beam with fixture, aimed by angle.


Formal Parameter Type Description
Height float The height of the fixture, with 0.0 at the middle of the image.
Color color The color of the light.
Angle float The angle of the light beam from the horizontal.

Beam_sloped (Height, Color, Slope)

A light beam with fixture, aimed by mathematical slope.


Formal Parameter Type Description
Height float The height of the fixture, with 0.0 at the middle of the image.
Color color The color of the light.
Slope float The slope of the light beam, Δvertical ÷ Δhorizontal.

Beam_targeted (Height, Color, Target)

A light beam with fixture, aimed at a target point.


Formal Parameter Type Description
Height float The height of the fixture, with 0.0 at the middle of the image.
Color color The color of the light.
Target vector The target point. If the z-coordinate is non-zero, the result is undefined.

Table of contents

Other Identifiers

Reference Identifiers

Identifier Type Description Value
Beam_media media The media used for the test environment
BEAMTEST_VERSION float The BeamTest version, in case the scene file needs that information. 1.21

Internal Identifiers

Any identifiers in that are not documented in this manual are considered “private” or “protected,” and are subject to change or elimination in a future update.

Table of contents

About BeamTest

Copyright © 2008 – 2019 Richard Callwood III. Some rights reserved. Licensed under the Creative Commons-GNU Lesser General Public License.

Object Collection Categories

Change Log

Version Date Notes
N/A 2007 November 21
  • The software is created.
1.0 2008 July 30
  • The software is adapted for the Object Collection.
1.0.1 2008 August 4
  • The user manual is edited; software is unmodified.
1.1 2008 September 1
  • Namespace compliance is extended to local identifiers.
1.1.1 2012 June 30
  • Demo scene is re-rendered using POV-Ray 3.7.
1.2 2014 November 1
  • An orthographic camera is introduced.
  • Parameters are introduced to color the environmental lighting and control the image aspect ratio.
  • A demo scene is added showing BeamTest used with SpectralRender.
1.2.1 2019 March 24
  • A message is optionally sent to the debug stream stating that is included.


Many thanks to Matthew Goulet, Juha Nieminen (who will recognize his parabolic mirror), and William F. Pokorny.

Table of contents