Greg Ward
Lawrence Berkeley National Laboratory
1 Cyclotron Rd., 90-3111
Berkeley, CA 94720
GJWard@lbl.gov
Figure 1
The diagram in Figure 1 shows the flow between programs (boxes) and data (ovals). The central program is rpict, which produces a picture from a scene description. Rview is a variation of rpict that computes and displays images interactively.
A scene description file lists the surfaces and materials that make up a specific environment. The current surface types are spheres, polygons, cones, and cylinders. They can be made from materials such as plastic, metal, and glass. Light sources can be distant disks as well as local spheres, discs and polygons.
From a three-dimensional scene description and a specified view, rpict produces a two-dimensional image. A picture file is a compressed binary representation of the pixels in the image. This picture can be scaled in size and brightness, anti-aliased, and sent to a graphics output device.
A header in each picture file lists the program(s) and parameters that produced it. This is useful for identifying a picture without having to display it. The information can be read by the program getinfo.
# comment
modifier type identifier
n S1 S2 S3 .. Sn
0
m R1 R2 R3 .. Rm
modifier alias identifier reference
! command
...
A comment line begins with a pound sign, `#'.
The scene description primitives all have the same general format, and can be either surfaces or modifiers. A primitive has a modifier, a type, and an identifier.
A modifier is either the identifier of a previously defined primitive, or "void".
[ The most recent definition of a modifier is the one used, and later definitions do not cause relinking of loaded primitives. Thus, the same identifier may be used repeatedly, and each new definition will apply to the primitives following it. ]
An identifier can be any string (i.e. sequence of non-blank characters).
The arguments associated with a primitive can be strings or real numbers.
An alias gets its type and arguments from a previously defined primitive. This is useful when the same material is used with a different modifier, or as a convenient naming mechanism. Surfaces cannot be aliased.
A line beginning with an exclamation point, `!', is interpreted as a command. It is executed by the shell, and its output is read as input to the program. The command must not try to read from its standard input, or confusion will result. A command may be continued over multiple lines using a backslash, `\', to escape the newline.
Blank space is generally ignored, except as a separator. The exception is the newline character after a command or comment. Commands, comments and primitives may appear in any combination, so long as they are not intermingled.
mod source id 0 0 4 xdir ydir zdir angle
mod sphere id
0
0
4 xcent ycent zcent radius
mod polygon id
0
0
3n
x1 y1 z1
x2 y2 z2
...
xn yn zn
mod cone id
0
0
8
x0 y0 z0
x1 y1 z1
r0 r1
mod cylinder id
0
0
7
x0 y0 z0
x1 y1 z1
rad
mod ring id
0
0
8
xcent ycent zcent
xdir ydir zdir
r0 r1
mod instance id
1+ octree transform
0
0
If the modifier is "void", then surfaces will use the modifiers given in the original description.
Otherwise, the modifier specified is used in their place.
The transform moves the octree to the desired location in the scene.
Multiple instances using the same octree take little extra memory, hence very complex descriptions can be rendered using this primitive.
There are a number of important limitations to be aware of when using instances. First, the scene description used to generate the octree must stand on its own, without referring to modifiers in the parent description. This is necessary for oconv to create the octree. Second, light sources in the octree will not be incorporated correctly in the calculation, and they are not recommended. Finally, there is no advantage (other than convenience) to using a single instance of an octree, or an octree containing only a few surfaces. An xform command on the subordinate description is prefered in such cases.
mod light id
0
0
3 red green blue
mod illum id
1 material
0
3 red green blue
mod glow id
0
0
4 red green blue maxrad
If maxrad is zero, then the surface will never be tested for shadow, although it may participate in an interreflection calculation.
If maxrad is negative, then the surface will never contribute to scene illumination.
Glow sources will never illuminate objects on the other side of an illum surface.
This provides a convenient way to illuminate local light fixture geometry without overlighting nearby objects.
mod spotlight id
0
0
7 red green blue angle xdir ydir zdir
mod mirror id
1 material
0
3 red green blue
mod prism1 id
5+ coef dx dy dz funcfile transform
0
n A1 A2 .. An
The new direction variables dx, dy and dz need not produce a normalized vector.
For convenience, the variables DxA, DyA and DzA are defined as the normalized direction to the target light source.
See section 2.2.1 on function files for further information.
mod prism2 id
9+ coef1 dx1 dy1 dz1 coef2 dx2 dy2 dz2 funcfile transform
0
n A1 A2 .. An
3 source1 mirror1>source10 mirror2>mirror1>source3Normally, only one source is given per mist material, and there is an upper limit of 32 to the total number of active scattering sources. The extinction coefficient, if given, is added the the global coefficient set on the command line. Extinction is in units of 1/distance (distance based on the world coordinates), and indicates the proportional loss of radiance over one unit distance. The scattering albedo, if present, will override the global setting within the volume. An albedo of 0 0 0 means a perfectly absorbing medium, and an albedo of 1 1 1 means a perfectly scattering medium (no absorption). The scattering eccentricity parameter will likewise override the global setting if it is present. Scattering eccentricity indicates how much scattered light favors the forward direction, as fit by the Heyney-Greenstein function:
P(theta) = (1 - g*g) / (1 + g*g - 2*g*cos(theta))^1.5A perfectly isotropic scattering medium has a g parameter of 0, and a highly directional material has a g parameter close to 1. Fits to the g parameter may be found along with typical extinction coefficients and scattering albedos for various atmospheres and cloud types in USGS meteorological tables. (A pattern will be applied to the extinction values.)
mod mist id N src1 src2 .. srcN 0 0|3|6|7 [ rext gext bext [ ralb galb balb [ g ] ] ]There are two usual uses of the mist type. One is to surround a beam from a spotlight or laser so that it is visible during rendering. For this application, it is important to use a cone (or cylinder) that is long enough and wide enough to contain the important visible portion. Light source photometry and intervening objects will have the desired effect, and crossing beams will result in additive scattering. For this application, it is best to leave off the real arguments, and use the global rendering parameters to control the atmosphere. The second application is to model clouds or other localized media. Complex boundary geometry may be used to give shape to a uniform medium, so long as the boundary encloses a proper volume. Alternatively, a pattern may be used to set the line integral value through the cloud for a ray entering or exiting a point in a given direction. For this application, it is best if cloud volumes do not overlap each other, and opaque objects contained within them may not be illuminated correctly unless the line integrals consider enclosed geometry.
mod plastic id
0
0
5 red green blue spec rough
mod trans id
0
0
7 red green blue spec rough trans tspec
mod plastic2 id
4+ ux uy uz funcfile transform
0
6 red green blue spec urough vrough
mod trans2 id
4+ ux uy uz funcfile transform
0
8 red green blue spec urough vrough trans tspec
mod dielectric id
0
0
5 rtn gtn btn n hc
mod interface id
0
0
8 rtn1 gtn1 btn1 n1 rtn2 gtn2 btn2 n2
tn = (sqrt(.8402528435+.0072522239*Tn*Tn)-.9166530661)/.0036261119/Tn
Standard 88% transmittance glass has a transmissivity of 0.96.
(A pattern modifying glass will affect the transmissivity.)
If a fourth real argument is given, it is interpreted as the index of refraction to use instead of 1.52.
mod glass id
0
0
3 rtn gtn btn
mod plasfunc id
2+ refl funcfile transform
0
4+ red green blue spec A5 ..
The function refl takes four arguments, the x, y and z
direction towards the incident light, and the solid angle
subtended by the source.
The solid angle is provided to facilitate averaging, and is usually
ignored.
The refl function should integrate to 1 over
the projected hemisphere to maintain energy balance.
At least four real arguments must be given, and these are made available along with any additional values to the reflectance function.
Currently, only the contribution from direct light sources is considered in the specular calculation.
As in most material types, the surface normal is always altered to face the incoming ray.
mod transfunc id
2+ brtd funcfile transform
0
6+ red green blue rspec trans tspec A7 ..
Where trans is the total light transmitted and tspec is the non-Lambertian fraction of transmitted light.
The function brtd should integrate to 1 over each projected hemisphere.
mod BRTDfunc id
10+ rrefl grefl brefl
rtrns gtrns btrns
rbrtd gbrtd bbrtd
funcfile transform
0
9+ rfdif gfdif bfdif
rbdif gbdif bbdif
rtdif gtdif btdif
A10 ..
The variables rrefl, grefl and brefl specify the color coefficients for the ideal specular (mirror) reflection of the surface.
The variables rtrns, gtrns and btrns specify the color coefficients for the ideal specular transmission.
The functions rbrtd, gbrtd and bbrtd take the direction to the incident light (and its solid angle) and
compute the color coefficients for the directional diffuse part of reflection and transmission.
As a special case, three identical values of '0' may be given in place of these function names to indicate no directional diffuse component.
Unlike most other material types, the surface normal is not altered to face the incoming ray. Thus, functions and variables must pay attention to the orientation of the surface and make adjustments appropriately. However, the special variables for the perturbed dot product and surface normal, RdotP, NxP, NyP and NzP are reoriented as if the ray hit the front surface for convenience.
A diffuse reflection component may be given for the front side with rfdif, gfdif and bfdif for the front side of the surface or rbdif, gbdif and bbdif for the back side. The diffuse transmittance (must be the same for both sides by physical law) is given by rtdif, gtdif and btdif. A pattern will modify these diffuse scattering values, and will be available through the special variables CrP, CgP and CbP.
Care must be taken when using this material type to produce a physically valid reflection model. The reflectance functions should be bidirectional, and under no circumstances should the sum of reflected diffuse, transmitted diffuse, reflected specular, transmitted specular and the integrated directional diffuse component be greater than one.
mod plasdata id
3+n+
func datafile
funcfile x1 x2 .. xn transform
0
4+ red green blue spec A5 ..
The coordinate indices (x1, x2, etc.) are themselves functions of the x, y and z direction to the incident light, plus the solid angle
subtended by the light source (usually ignored).
The data function (func) takes five variables, the
interpolated value from the n-dimensional data file, followed by the
x, y and z direction to the incident light and the solid angle of the source.
The light source direction and size may of course be ignored by the function.
mod transdata id
3+n+
func datafile
funcfile x1 x2 .. xn transform
0
6+ red green blue rspec trans tspec A7 ..
mod antimatter id
N mod1 mod2 .. modN
0
0
The first modifier will also be used to shade the area leaving the antimatter volume and entering the regular volume.
If mod1 is void, the antimatter volume is completely invisible.
Antimatter does not work properly with the material type "trans",
and multiple antimatter surfaces should be disjoint.
The viewpoint must be outside all volumes concerned for a correct rendering.
mod texfunc id
4+ xpert ypert zpert funcfile transform
0
n A1 A2 .. An
mod texdata id
8+ xfunc yfunc zfunc xdfname ydfname zdfname vfname x0 x1 .. xf
0
n A1 A2 .. An
mod colorfunc id
4+ red green blue funcfile transform
0
n A1 A2 .. An
mod brightfunc id
2+ refl funcfile transform
0
n A1 A2 .. An
mod colordata id
7+n+
rfunc gfunc bfunc rdatafile gdatafile bdatafile
funcfile x1 x2 .. xn transform
0
m A1 A2 .. Am
mod brightdata id
3+n+
func datafile
funcfile x1 x2 .. xn transform
0
m A1 A2 .. Am
mod colorpict id
7+
rfunc gfunc bfunc pictfile
funcfile u v transform
0
m A1 A2 .. Am
mod colortext id
2 fontfile textfile
0
15+
Ox Oy Oz
Rx Ry Rz
Dx Dy Dz
rfore gfore bfore
rback gback bback
[spacing]
or:
mod colortext id
2+N fontfile . This is a line with N words ...
0
15+
Ox Oy Oz
Rx Ry Rz
Dx Dy Dz
rfore gfore bfore
rback gback bback
[spacing]
mod brighttext id
2 fontfile textfile
0
11+
Ox Oy Oz
Rx Ry Rz
Dx Dy Dz
foreground background
[spacing]
or:
mod brighttext id
2+N fontfile . This is a line with N words ...
0
11+
Ox Oy Oz
Rx Ry Rz
Dx Dy Dz
foreground background
[spacing]
By default, a uniform spacing algorithm is used that guarantees every character will appear in a precisely determined position. Unfortunately, such a scheme results in rather unattractive and difficult to read text with most fonts. The optional spacing value defines the distance between characters for proportional spacing. A positive value selects a spacing algorithm that preserves right margins and indentation, but does not provide the ultimate in proportionally spaced text. A negative value insures that characters are properly spaced, but the placement of words then varies unpredictably. The choice depends on the relative importance of spacing versus formatting. When presenting a section of formatted text, a positive spacing value is usually preferred. A single line of text will often be accompanied by a negative spacing value. A section of text meant to depict a picture, perhaps using a special purpose font such as hexbit4x1.fnt, calls for uniform spacing. Reasonable magnitudes for proportional spacing are between 0.1 (for tightly spaced characters) and 0.3 (for wide spacing).
mod mixfunc id
4+ foreground background vname funcfile transform
0
n A1 A2 .. An
Foreground and background are modifier names that must be uniquely defined in the scene description.
If one of these is a material, then
the modifier of the mixfunc must be "void".
(Either the foreground or background modifier may be "void",
which serves as a form of opacity control when used with a material.)
Vname is the coefficient defined in funcfile that determines the influence of foreground.
The background coefficient is always (1-vname).
Since the references are not resolved until run-time, the last definitions of the modifier id's will be used.
This can result in modifier loops, which are detected by the renderer.
mod mixdata id
5+n+
foreground background func datafile
funcfile x1 x2 .. xn transform
0
m A1 A2 .. Am
mod mixtext id
4 foreground background fontfile textfile
0
9+
Ox Oy Oz
Rx Ry Rz
Dx Dy Dz
[spacing]
or:
mod mixtext id
4+N
foreground background fontfile .
This is a line with N words ...
0
9+
Ox Oy Oz
Rx Ry Rz
Dx Dy Dz
[spacing]
{
This is a comment, enclosed in curly braces.
{Comments can be nested.}
}
{ standard expressions use +,-,*,/,^,(,) }
vname = Ny * func(A1) ;
{ constants are defined with a colon }
const : sqrt(PI/2) ;
{ user-defined functions add to library }
func(x) = 5 + A1*sin(x/3) ;
{ functions may be passed and recursive }
rfunc(f,x) = if(x,f(x),f(-x)*rfunc(f,x+1)) ;
{ constant functions may also be defined }
cfunc(x) : 10*x / sqrt(x) ;
Many variables and functions are already defined by the program, and they are listed in the file rayinit.cal.
The following variables are particularly important:
Dx, Dy, Dz - incident ray direction
Px, Py, Pz - intersection point
Nx, Ny, Nz - surface normal at intersection point
Rdot - cosine between ray and normal
arg(0) - number of real arguments
arg(i) - i'th real argument
For BRDF types, the following variables are defined as well:
NxP, NyP, NzP - perturbed surface normal
RdotP - perturbed dot product
CrP, CgP, CbP - perturbed material color
A unique context is set up for each file so that the same variable may appear in different function files without conflict.
The variables listed above and any others defined in rayinit.cal are available globally.
If no file is needed by a given primitive because all the required variables are global,
a period (`.') can be given in place of the file name.
It is also possible to give an expression instead of a straight variable name in a scene file,
although such expressions should be kept simple as they cannot contain any white space.
Also, functions (requiring parameters) must be given as names and not as expressions.
Constant expressions are used as an optimization in function files. They are replaced wherever they occur in an expression by their value. Constant expressions are evaluated only once, so they must not contain any variables or values that can change, such as the ray variables Px and Ny or the primitive argument function arg(). All the math library functions such as sqrt() and cos() have the constant attribute, so they will be replaced by immediate values whenever they are given constant arguments. Thus, the subexpression cos(PI*sqrt(2)) is immediately replaced by its value, -.266255342, and does not cause any additional overhead in the calculation.
It is generally a good idea to define constants and variables before they are referred to in a function file. Although evaluation does not take place until later, the interpreter does variable scoping and constant subexpression evaluation based on what it has compiled already. For example, a variable that is defined globally in rayinit.cal then referenced in the local context of a function file cannot subsequently be redefined in the same file because the compiler has already determined the scope of the referenced variable as global. To avoid such conflicts, one can state the scope of a variable explicitly by preceding the variable name with a context mark (a back-quote) for a local variable, or following the name with a context mark for a global variable.
N
beg1 end1 m1
0 0 m2 x2.1 x2.2 x2.3 x2.4 .. x2.m2
...
begN endN mN
DATA, later dimensions changing faster.
N is the number of dimensions.
For each dimension, the beginning and ending coordinate values and the dimension size is given.
Alternatively, individual coordinate values can be given when the points are not evenly spaced.
These values must either be increasing or decreasing monotonically.
The data is m1*m2*...*mN real numbers in ascii form.
Comments may appear anywhere in the file, beginning with a pound
sign ('#') and continuing to the end of line.
code n
x0 y0
x1 y1
...
xn yn
...
The ascii codes can appear in any order. N is the number of vertices, and the last is automatically connected to the first.
Separate polygonal sections are joined by coincident sides.
The character coordinate system is a square with lower left corner at (0,0), lower right at (255,0) and upper right at (255,255).
The image generating programs use an octree to efficiently trace rays through the scene. An octree subdivides space into nested octants which contain sets of surfaces. In RADIANCE, an octree is created from a scene description by oconv. The details of this process are not important, but the octree will serve as input to the ray-tracing programs and directs the use of a scene description.
A number of filters are available for manipulating picture files:
Pictures may be displayed directly under X11 using the program ximage, or converted a standard image format using one of the following translators:
NEITHER THE UNITED STATES NOR THE UNITED STATES DEPARTMENT OF ENERGY, NOR ANY OF THEIR EMPLOYEES, MAKES ANY WARRANTY, EXPRESS OR IMPLIED, OR ASSUMES ANY LEGAL LIABILITY OR RESPONSIBILITY FOR THE ACCURACY, COMPLETENESS, OR USEFULNESS OF ANY INFORMATION, APPARATUS, PRODUCT, OR PROCESS DISCLOSED, OR REPRESENTS THAT ITS USE WOULD NOT INFRINGE PRIVATELY OWNED RIGHTS. By downloading, using or copying this software, you agree to abide by the intellectual property laws and all other applicable laws of the United States, and by the terms of this License Agreement. Ownership of the software shall remain solely in The Regents. The Regents shall have the right to terminate this License immediately by written notice upon your breach of, or noncompliance with, any of its terms. You shall be liable for any infringement or damages resulting from your failure to abide by the terms of this License Agreement.
NOTICE: The Government is granted for itself and others acting on its behalf a paid-up, nonexclusive irrevocable worldwide license in this data to reproduce, prepare derivative works, and perform publicly and display publicly. Beginning five (5) years after permission to assert copyright is granted, subject to two possible five year renewals, the Government is granted for itself and others acting on its behalf a paid-up, non-exclusive, irrevocable worldwide license in this data to reproduce, prepare derivative works, distribute copies to the public, perform publicly and display publicly, and to permit others to do so.
Additional work was sponsored by the Swiss federal government under the Swiss LUMEN Project and was carried out in the Laboratoire d'Energie Solaire (LESO Group) at the Ecole Polytechnique Federale de Lausanne (EPFL University) in Lausanne, Switzerland.
Rushmeier, H., G. Ward, ``Energy-Preserving Non-Linear Filters,'' Computer Graphics, Orlando, July 1994.
Ward, G., ``A Contrast-Based Scalefactor for Luminance Display,'' Graphics Gems IV, Edited by Paul Heckbert, Academic Press 1994.
Ward, G., ``Measuring and Modeling Anisotropic Reflection,'' Computer Graphics, Chicago, July 1992.
Ward, G., P. Heckbert, ``Irradiance Gradients,'' Third Annual Eurographics Workshop on Rendering, to be published by Springer-Verlag, held in Bristol, UK, May 1992.
Ward, G., ``Adaptive Shadow Testing for Ray Tracing,'' Second Annual Eurographics Workshop on Rendering, to be pub- lished by Springer-Verlag, held in Barcelona, SPAIN, May 1991.
Ward, G., ``Visualization,'' Lighting Design and Applica- tion, Vol. 20, No. 6, June 1990.
Ward, G., F. Rubinstein, R. Clear, ``A Ray Tracing Solution for Diffuse Interreflection,'' Computer Graphics, Vol. 22, No. 4, August 1988.
Ward, G., F. Rubinstein, ``A New Technique for Computer Simulation of Illuminated Spaces,'' Journal of the Illuminating Engineering Society, Vol. 17, No. 1, Winter 1988.
SURFACES MATERIALS TEXTURES PATTERNS MIXTURES
Source Light Texfunc Colorfunc Mixfunc Sphere Illum Texdata Brightfunc Mixdata Bubble Glow Colordata Mixtext Polygon Spotlight Brightdata Cone Mirror Colorpict Cup Prism1 Colortext Cylinder Prism2 Brighttext Tube Plastic Ring Metal Instance Trans Plastic2 Metal2 Trans2 Mist Dielectric Interface Glass Plasfunc Metfunc Transfunc BRTDfunc Plasdata Metdata Transdata Antimatter