ray/doc/ray.html

<html>
<!-- RCSid $Id: ray.html,v 1.36 2023/12/12 20:12:47 greg Exp $ -->
<head>
<title>
The RADIANCE 6.0 Synthetic Imaging System
</title>
</head>
<body>

<p>

<h1>
The RADIANCE 6.0 Synthetic Imaging System
</h1>

<p>

Building Technologies Program<br>
Lawrence Berkeley National Laboratory<br>
1 Cyclotron Rd., 90-3111<br>
Berkeley, CA  94720<br>
<a HREF="http://radsite.lbl.gov/radiance"</a>
http://radsite.lbl.gov/radiance<br>

<p> 
<hr>

<h2>
<a NAME="Overview">Overview</a>
</h2>
        <ol>
        <li><a HREF="#Intro">Introduction</a><!P>
        <li><a HREF="#Scene">Scene Description</a><!P>
                <ol>
                <li><a HREF="#Primitive"> Primitive Types</a>
                        <ol>
                        <li><a HREF="#Surfaces">Surfaces</a>
                        <li><a HREF="#Materials">Materials</a>
                        <li><a HREF="#Textures">Textures</a>
                        <li><a HREF="#Patterns">Patterns</a>
                        <li><a HREF="#Mixtures">Mixtures</a>
                        </ol><!P>
                <li><a HREF="#Auxiliary">Auxiliary Files</a>
                        <ol>
                        <li><a HREF="#Function">Function Files</a>
                        <li><a HREF="#Data">Data Files</a>
                        <li><a HREF="#Font">Font Files</a>
                        </ol><!P>
                <li><a HREF="#Generators">Generators</a>
                </ol><!P>
        <li><a HREF="#Image">Image Generation</a><!P>
        <li><a HREF="#License">License</a><!P>
        <li><a HREF="#Ack">Acknowledgements</a><!P>
        <li><a HREF="#Ref">References</a><!P>
        <li><a HREF="#Index">Types Index</a><!P>
        </ol>

<p>
<hr>

<h2>
<a NAME="Intro">1.  Introduction</a>
</h2>

RADIANCE was developed as a research tool for  predicting 
the  distribution  of  visible radiation in illuminated spaces.  
It takes as  input  a  three-dimensional  geometric model 
of  the  physical  environment, and produces a map of
spectral radiance values in a color image.  
The technique of ray-tracing  follows light backwards
from the image plane to the source(s).  
Because it can produce realistic images from a
simple description, RADIANCE has a wide range of applications 
in  graphic  arts,  lighting  design, 
computer-aided engineering and architecture.

<p>
<img SRC="diagram1.gif">
<p>
Figure 1
<p>
The diagram in Figure 1 shows the flow between programs (boxes)  and  data  
(ovals).   
The central program is <i>rpict</i>, which produces a picture from a scene
description.
<i>Rvu</i> is a  variation  of  rpict  that  computes  and displays images 
interactively, and rtrace computes single ray values.
Other programs (not shown) connect many of these elements together, 
such as the executive programs
<i>rad</i>
and
<i>ranimate</i>,
the interactive rendering program
<i>rholo</i>,
and the animation program
<i>ranimove</i>.
The program
<i>obj2mesh</i>
acts as both a converter and scene compiler, converting a Wavefront .OBJ
file into a compiled mesh octree for efficient rendering.

<p>
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.
There is also a composite surface type, called mesh, and a pseudosurface
type, called instance, which facilitates very complex geometries.
Surfaces can be made from materials such as plastic, metal, and glass.  
Light sources can be distant disks as well as  local spheres, disks
and polygons.

<p>
From a three-dimensional scene description and a specified  view, 
<i>rpict</i> 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.

<p>
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 <i>getinfo</i>.

<p>
<hr>

<h2>
<a name="Scene">2.  Scene Description</a>
</h2>

A scene description file represents a three-dimensional physical  environment in Cartesian (rectilinear) world coordinates.  
It is stored as ASCII  text,  with  the  following basic format:

<pre>
        # comment

        modifier type identifier
        n S1 S2 &quot;S 3&quot; .. Sn
        0
        m R1 R2 R3 .. Rm

        modifier alias identifier reference

        ! command

         ...
</pre>

A comment line begins with a pound sign, `#'.

<p>
The <a NAME="scene_desc">scene description primitives</a>
all have the same general  format,  and  can  be either surfaces or modifiers.  
A primitive has a modifier, a  type,  and  an  identifier.   
<p>
A <a NAME="modifier"><b>modifier</b></a>  is  either  the
identifier of a previously defined primitive, or &quot;void&quot;.  
<br>
[ 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. ]
<p>
An <a NAME="identifier"><b>identifier</b></a> can be any string
(i.e., any sequence of non-white characters).
<p>
The arguments associated with  a primitive can be strings or real numbers.  
<ul>
<li>    The first integer following the identifier is  the  number  of  <b>string arguments</b>,  
        and  it  is followed by the arguments themselves (separated by white space or enclosed in quotes).  
<li>    The next integer is the  number of  integer  arguments, and is followed by the <b>integer arguments</b>.  
        (There are currently no primitives  that  use  them, however.)  
<li>    The  next integer is the real argument count, and it is followed by the <b>real arguments</b>.
</ul>

<p>
An <a NAME="alias"><b>alias</b></a> 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.  
The reserved modifier name &quot;inherit&quot; may be used to specificy that
an alias will inherit its modifier from the original.
Surfaces cannot be aliased.

<p>
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.

<p>
White 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.

<p>
<hr>

<h3>
<a NAME="Primitive">2.1.  Primitive Types</a>
</h3>

Primitives can be <a HREF="#Surfaces">surfaces</a>,
<a HREF="#Materials">materials</a>,
<a HREF="#Textures">textures</a> or
<a HREF="#Patterns">patterns</a>.   
Modifiers can be <a HREF="#Materials">materials</a>,
<a HREF="#Mixtures">mixtures</a>,
<a HREF="#Textures">textures</a> or <a HREF="#Patterns">patterns</a>.
Simple surfaces must have one material in their modifier list.

<p>
<hr>

<h4>
<a NAME="Surfaces">2.1.1.  Surfaces</a>
</h4>
<dl>

A scene description will consist  mostly  of  surfaces.
The basic types are given below.

<p>

<dt>
        <a NAME="Source">
        <b>Source </b>    
        </a>
<dd>
        A source is not really a surface, but  a  solid  angle.
        It  is  used for specifying light sources that are very distant.  
        The direction to the center of  the  source  and  the number  of  degrees  subtended by its disk are given as follows:

<pre>
        mod source id
        0
        0
        4 xdir ydir zdir angle
</pre>

<p>

<dt>
        <a NAME="Sphere">
        <b>Sphere</b>
        </a>
<dd>
        A sphere is given by its center and radius:

<pre>
        mod sphere id
        0
        0
        4 xcent ycent zcent radius
</pre>

<p>

<dt>
        <a NAME="Bubble">
        <b>Bubble</b>
        </a>

<dd>
        A bubble is simply a sphere whose surface normal points inward.

<p>

<dt>
        <a NAME="Polygon">
        <b>Polygon</b>
        </a>
<dd>
        A polygon is given by a list of three-dimensional  vertices, 
        which  are  ordered counter-clockwise as viewed from the
        front side (into the surface normal). 
        The  last  vertex is   automatically   connected  to  the  first.   
        Holes  are represented in polygons as interior  vertices 
        connected  to the outer perimeter by coincident edges (seams).

<pre>
        mod polygon id
        0
        0
        3n
                x1      y1      z1
                x2      y2      z2
                ...
                xn      yn      zn
</pre>

<p>

<dt>
        <a NAME="Cone">
        <b>Cone</b>
        </a>
<dd>
        A cone is a megaphone-shaped object.  
        It  is  truncated by two planes perpendicular to its axis,
        and one of its ends may come to a point.  
        It is given as two axis endpoints, and the starting and ending radii:

<pre>
        mod cone id
        0
        0
        8
                x0      y0      z0
                x1      y1      z1
                r0      r1
</pre>

<p>

<dt>
        <a NAME="Cup">
        <b>Cup</b>
        </a>
<dd>
        A cup is an inverted <a HREF="#Cone">cone</a> (i.e., has  an 
        inward  surface normal).

<p>

<dt>
        <a NAME="Cylinder">
        <b>Cylinder</b>
        </a>
<dd>
        A cylinder is like a <a HREF="#Cone">cone</a>, but its
        starting and  ending radii are equal.

<pre>
        mod cylinder id
        0
        0
        7
                x0      y0      z0
                x1      y1      z1
                rad
</pre>

<p>

<dt>
        <a NAME="Tube">
        <b>Tube</b>
        </a>
<dd>
        A tube is an inverted <a HREF="#Cylinder">cylinder</a>.

<p>

<dt>
        <a NAME="Ring">
        <b>Ring</b>
        </a>
<dd>
        A ring is a circular disk given by its center,
        surface normal, and inner and outer radii:

<pre>
        mod ring id
        0
        0
        8
                xcent   ycent   zcent
                xdir    ydir    zdir
                r0      r1
</pre>

<p>

<dt>
        <a NAME="Instance">
        <b>Instance</b>
        </a>
<dd>
        An instance is a compound surface, given
        by the contents of an octree file (created by oconv).

<pre>
        mod instance id
        1+ octree transform
        0
        0
</pre>

        If the modifier is &quot;void&quot;, 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.

<p>
        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  <a HREF="../man_html/xform.1.html">xform</a> command
        on the subordinate description is prefered in such cases.
</dl>

<p>

<dt>
        <a NAME="Mesh">
        <b>Mesh</b>
        </a>
<dd>
        A mesh is a compound surface, made up of many triangles and
        an octree data structure to accelerate ray intersection.
        It is typically converted from a Wavefront .OBJ file using the
        <i>obj2mesh</i> program.

<pre>
        mod mesh id
        1+ meshfile transform
        0
        0
</pre>

        If the modifier is &quot;void&quot;, then surfaces will
        use the modifiers  given  in  the  original  mesh description.  
        Otherwise, the modifier specified is used in their  place.   
        The  transform moves the mesh to the desired location in the scene.  
        Multiple instances using the same meshfile take little extra memory,
        and the compiled mesh itself takes much less space than individual
        polygons would.
        In the case of an unsmoothed mesh, using the mesh primitive reduces
        memory requirements by a factor of 30 relative to individual triangles.
        If a mesh has smoothed surfaces, we save a factor of 50 or more,
        permitting very detailed geometries that would otherwise exhaust the
        available memory.
        In addition, the mesh primitive can have associated (u,v) coordinates
        for pattern and texture mapping.
        These are made available to function files via the Lu and Lv variables.

</dl>

<p>
<hr>

<h4>
<a NAME="Materials">2.1.2.  Materials</a>
</h4>

A material defines the way light interacts with a  surface.  The basic types are given below.

<p>

<dl>

<dt>
        <a NAME="Light">
        <b>Light</b>
        </a>
<dd>
        Light is the basic material for self-luminous  surfaces (i.e.,
        light  sources).   
        In  addition  to the <a HREF="#Source">source</a> surface type,  
        <a HREF="#Sphere">spheres</a>,  
        discs  (<a HREF="#Ring">rings</a>  with  zero  inner   radius),
        <a HREF="#Cylinder">cylinders</a>  (provided they are long enough), and <a HREF="#Polygon">polygons</a> can act as light sources.  
        Polygons work best when they are rectangular.  
        Cones cannot be used at this time.  
        A pattern may be used to specify a light output  distribution.   
        Light  is defined simply as a RGB radiance value (watts/steradian/m2):

<pre>
        mod light id
        0
        0
        3 red green blue
</pre>

<p>

<dt>
        <a NAME="Illum">
        <b>Illum</b>
        </a>

<dd>
        Illum is used for secondary light  sources  with  broad distributions.  
        A secondary light source is treated like any other light source, except when viewed  directly.   
        It then acts like it is made of a different material (indicated by
        the string argument), or becomes invisible (if no string argument is given,
        or the argument is &quot;void&quot;).
        Secondary sources are useful when modeling  windows or brightly illuminated surfaces.

<pre>
        mod illum id
        1 material
        0
        3 red green blue
</pre>

<p>

<dt>
        <a NAME="Glow">
        <b>Glow</b>
        </a>

<dd>
        Glow is used for surfaces that are  self-luminous,  but limited in their effect.  
        In addition to the radiance value, a maximum radius for shadow testing is given:

<pre>
        mod glow id
        0
        0
        4 red green blue maxrad
</pre>

        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.

<p>

<dt>
        <a NAME="Spotlight">
        <b>Spotlight</b>
        </a>

<dd>
        Spotlight is used  for  self-luminous  surfaces  having directed  output.   
        As well as radiance, the full cone angle (in degrees) and orientation (output direction)  vector  are given.  
        The length of the orientation vector is the distance of the effective
        focus behind the  source  center  (i.e., the focal length).

<pre>
        mod spotlight id
        0
        0
        7 red green blue angle xdir ydir zdir
</pre>

<p>

<dt>
        <a NAME="Mirror">
        <b>Mirror</b>
        </a>

<dd>
        Mirror is used for planar surfaces that produce  virtual source reflections.  
        This material should be used sparingly, as it may cause the light source calculation to  blow up  if  it is applied to many small surfaces.  
        This material is only supported for flat surfaces  such  as  <a HREF="#Polygon">polygons</a>  and <a HREF="#Ring">rings</a>.  
        The arguments are simply the RGB reflectance values, which should be between 0 and 1.  
        An optional  string  argument  may be used like the illum type to specify a different material to be used for shading non-source rays.
        If this alternate material is given as &quot;void&quot;, then the mirror surface will be invisible.
This is only appropriate if the surface hides other (more detailed) geometry with the same overall reflectance.

<pre>
        mod mirror id
        1 material
        0
        3 red green blue
</pre>

<p>

<dt>
        <a NAME="Prism1">
        <b>Prism1</b>
        </a>

<dd>
        The prism1 material is for  general  light  redirection from prismatic glazings, generating virtual light sources.
        It can only be used  to  modify  a  planar  surface  
        (i.e.,  a <a HREF="#Polygon">polygon</a>  or <a HREF="#Ring">disk</a>) 
        and should not result in either light concentration or scattering.  
        The new direction of the ray  can be  on either side of the material, 
        and the definitions must have the correct bidirectional properties to  work  properly with virtual light sources.  
        The arguments give the coefficient for the redirected light and its direction.

<pre>
        mod prism1 id
        5+ coef dx dy dz funcfile transform
        0
        n A1 A2 .. An
</pre>

        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 <a HREF="#Function">section 2.2.1</a> on function files for further information.

<p>

<dt>
        <a NAME="Prism2">
        <b>Prism2</b>
        </a>

<dd>
        The material prism2 is identical to <a HREF="#Prism1">prism1</a> except  that it provides for two ray redirections rather than one.

<pre>
        mod prism2 id
        9+ coef1 dx1 dy1 dz1 coef2 dx2 dy2 dz2 funcfile transform
        0
        n A1 A2 .. An
</pre>

<p>

<dt>
        <a NAME="Mist">
        <b>Mist</b>
        </a>

<dd>
        Mist is a virtual material used to delineate a volume
        of participating atmosphere.
        A list of important light sources may be given, along with an
        extinction coefficient, scattering albedo and scattering eccentricity
        parameter.
        The light sources named by the string argument list
        will be tested for scattering within the volume.
        Sources are identified by name, and virtual light sources may be indicated
        by giving the relaying object followed by '&gt;' followed by the source, i.e:

<pre>
        3  source1  mirror1&gt;source10  mirror2&gt;mirror1&gt;source3
</pre>

Normally, 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 Henyey-Greenstein function:

<pre>
        P(theta) = (1 - g*g) / (1 + g*g - 2*g*cos(theta))^1.5
</pre>

A 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.)

<pre>
        mod mist id
        N src1 src2 .. srcN
        0
        0|3|6|7 [ rext gext bext [ ralb galb balb [ g ] ] ]
</pre>

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 <a HREF="#Cone">cone</a>
(or <a HREF="#Cylinder">cylinder</a>) 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.

<dt>
        <a NAME="Plastic">
        <b>Plastic</b>
        </a>

<dd>
        Plastic is a material with uncolored highlights.  
        It is given  by  its RGB reflectance, its fraction of specularity, and its roughness value.  
        Roughness is specified as the  rms slope of surface facets.  
        A value of 0 corresponds to a perfectly smooth surface, and a value of  1  would  be  a  very rough  surface.   
        Specularity fractions greater than 0.1 and roughness values greater than 0.2 are  not  very  realistic.
        (A  pattern  modifying  plastic  will  affect  the  material color.)

<pre>
        mod plastic id
        0
        0
        5 red green blue spec rough
</pre>

<p>

<dt>
        <a NAME="Metal">
        <b>Metal</b>
        </a>

<dd>
        Metal is similar to <a HREF="#Plastic">plastic</a>,  but  specular  highlights are  modified  by the material color.  
        Specularity of metals is usually .9 or greater.  
        As for plastic, roughness  values above .2 are uncommon.

<p>

<dt>
        <a NAME="Trans">
        <b>Trans</b>
        </a>

<dd>
        Trans is a translucent material,  similar  to  <a HREF="#Plastic">plastic</a>.
        The transmissivity is the fraction of penetrating light that travels all the way through the material.   
        The  transmitted specular component is the fraction of transmitted light that is  not  diffusely  scattered.   
        Transmitted  and  diffusely reflected light is modified by the material color.  
        Translucent objects are infinitely thin.

<pre>
        mod trans id
        0
        0
        7 red green blue spec rough trans tspec
</pre>

<p>

<dt>
        <a NAME="Plastic2">
        <b>Plastic2</b>
        </a>

<dd>
        Plastic2 is similar to <a HREF="#Plastic">plastic</a>,  but  with  anisotropic roughness.   
        This  means that highlights in the surface will appear elliptical rather than round.  
        The orientation of the anisotropy  is determined by the unnormalized direction vector ux uy uz.  
        These three expressions (separated  by  white space)  are  evaluated  in  the context of the function file funcfile.  
        If no function file is required (i.e.,  no  special variables  or functions are required), a period (`.') may be given in its place.  
        (See the discussion of  <a HREF="#Function">Function  Files</a> in  the  Auxiliary Files section).  
        The urough value defines the roughness along the u vector given  projected  onto  the surface.  
        The vrough value defines the roughness perpendicular to this vector.  
        Note that the highlight  will  be  narrower  in  the  direction  of  the  smaller roughness value.
        Roughness values of zero are not allowed for efficiency reasons since the behavior would be the same as regular plastic in that case.

<pre>
        mod plastic2 id
        4+ ux uy uz funcfile transform
        0
        6 red green blue spec urough vrough
</pre>

<p>

<dt>
        <a NAME="Metal2">
        <b>Metal2</b>
        </a>

<dd>
        Metal2  is  the  same  as  <a HREF="#Plastic2">plastic2</a>,  except  that  the highlights are modified by the material color.

<p>

<dt>
        <a NAME="Trans2">
        <b>Trans2</b>
        </a>

<dd>
        Trans2 is the anisotropic version of <a HREF="#Trans">trans</a>.  
        The string arguments  are  the same as for <a HREF="#Plastic2">plastic2</a>,
        and the real arguments are the same as  for  trans  but  with  an  additional roughness value.

<pre>
        mod trans2 id
        4+ ux uy uz funcfile transform
        0
        8 red green blue spec urough vrough trans tspec
</pre>

<p>

<dt>
        <a NAME="Ashik2">
        <b>Ashik2</b>
        </a>

<dd>
        Ashik2 is the anisotropic reflectance model by Ashikhmin & Shirley.
        The string arguments are the same as for <a HREF="#Plastic2">plastic2</a>, but the real
        arguments have additional flexibility to specify the specular color.
        Also, rather than roughness, specular power is used, which has no
        physical meaning other than larger numbers are equivalent to a smoother
        surface.
        Unlike other material types, total reflectance is the sum of
        diffuse and specular colors, and should be adjusted accordingly.
<pre>
        mod ashik2 id
        4+ ux uy uz funcfile transform
        0
        8 dred dgrn dblu sred sgrn sblu u-power v-power
</pre>

<p>

<dt>
        <a NAME="Dielectric">
        <b>Dielectric</b>
        </a>

<dd>
        A dielectric material is transparent, and  it  refracts light  as well as reflecting it.  
        Its behavior is determined by the  index  of  refraction  and  transmission coefficient  in  each wavelength  band  per unit length.  
        Common glass has a index of refraction  (n)  around  1.5,  and  a  transmission coefficient  of roughly  0.92 over an inch.  
        An additional number, the Hartmann constant, describes how the index of refraction changes as  a  function of wavelength.  
        It is usually zero.  (A <a HREF="#Patterns">pattern</a> modifies only the refracted value.)

<pre>
        mod dielectric id
        0
        0
        5 rtn gtn btn n hc
</pre>

<p>

<dt>
        <a NAME="Interface">
        <b>Interface</b>
        </a>

<dd>
        An interface is a  boundary  between  two  dielectrics.
        The  first transmission coefficient and refractive index are for the inside; the second  ones  are  for  the  outside.   
        Ordinary dielectrics are surrounded by a vacuum (1 1 1 1).

<pre>
        mod interface id
        0
        0
        8 rtn1 gtn1 btn1 n1 rtn2 gtn2 btn2 n2
</pre>

<p>

<dt>
        <a NAME="Glass">
        <b>Glass</b>
        </a>

<dd>
        Glass is similar to <a HREF="#Dielectric">dielectric</a>, but it is optimized for thin glass surfaces (n = 1.52).  
        One transmitted ray and one reflected ray is produced.  
        By using a single surface is  in place of two, internal reflections are avoided.  
        The surface orientation is irrelevant, as it is for <a HREF="#Plastic">plastic</a>, <a HREF="#Metal">metal</a>,  and <a HREF="#Trans">trans</a>.   
        The only specification  required is the transmissivity at normal incidence.  
        (Transmissivity is the amount of light not absorbed in one traversal
        of the material.
        Transmittance -- the value usually measured -- is the total light
        transmitted through the pane including multiple reflections.)
        To compute transmissivity  (tn) from transmittance (Tn) use:

<pre>
        tn = (sqrt(.8402528435+.0072522239*Tn*Tn)-.9166530661)/.0036261119/Tn
</pre>

        Standard 88% transmittance glass  has  a  transmissivity  of 0.96.   
        (A <a HREF="#Patterns">pattern</a> 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.

<pre>
        mod glass id
        0
        0
        3 rtn gtn btn
</pre>

<p>

<dt>
        <a NAME="Plasfunc">
        <b>Plasfunc</b>
        </a>

<dd>
        Plasfunc in  used  for  the  procedural  definition  of plastic-like  materials 
        with arbitrary bidirectional reflectance distribution functions  (BRDF's).   
        The  arguments  to this  material include the color and specularity, 
        as well as the function defining the specular distribution and the auxiliary file where it may be found.

<pre>
        mod plasfunc id
        2+ refl funcfile transform
        0
        4+ red green blue spec A5 ..
</pre>

        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.

<p>

<dt>
        <a NAME="Metfunc">
        <b>Metfunc</b>
        </a>

<dd>
        Metfunc is identical to <a HREF="#Plasfunc">plasfunc</a>  and  takes  the  same arguments,  
        but the specular component is multiplied also by the material color.

<p>

<dt>
        <a NAME="Transfunc">
        <b>Transfunc</b>
        </a>

<dd>
        Transfunc is similar to <a HREF="#Plasfunc">plasfunc</a> but with an  arbitrary bidirectional   transmittance  distribution  
        as  well  as  a reflectance    distribution. 
        Both    reflectance and transmittance are specified with the same function.

<pre>
        mod transfunc id
        2+ brtd funcfile transform
        0
        6+ red green blue rspec trans tspec A7 ..
</pre>

        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.

<p>

<dt>
        <a NAME="BRTDfunc">
        <b>BRTDfunc</b>
        </a>

<dd>
        The material BRTDfunc  gives  the  maximum  flexibility over  surface  reflectance  and transmittance, 
        providing for spectrally-dependent  specular  rays  and  reflectance   and transmittance distribution functions.

<pre>
        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 ..
</pre>

        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.

<p>
        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.

<p>
        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.

<p>
        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.

<p>

<dt>
        <a NAME="Plasdata">
        <b>Plasdata</b>
        </a>

<dd>
        Plasdata is used for arbitrary  BRDF's  that  are  most conveniently  given  as interpolated data.  
        The arguments to this material are the <a HREF="#Data">data file</a> and coordinate  index  functions,  
        as  well as a function to optionally modify the data values.

<pre>
        mod plasdata id
        3+n+
                func datafile
                funcfile x1 x2 .. xn transform
        0
        4+ red green blue spec A5 ..
</pre>

        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.

<p>

<dt>
        <a NAME="Metdata">
        <b>Metdata</b>
        </a>

<dd>
        As metfunc is to  plasfunc,  metdata  is  to  <a HREF="#Plasdata">plasdata</a>.  
        Metdata takes the same arguments as plasdata, but the specular component is modified by the given material color.

<p>

<dt>    
        <a NAME="Transdata">
        <b>Transdata</b>
        </a>

<dd>
        Transdata  is  like  <a HREF="#Plasdata">plasdata</a>  but  the   specification includes  transmittance as well as reflectance.  
        The parameters are as follows.

<pre>
        mod transdata id
        3+n+
                func datafile
                funcfile x1 x2 .. xn transform
        0
        6+ red green blue rspec trans tspec A7 ..
</pre>

<p>

<dt>
        <a NAME="BSDF">
        <b>BSDF</b>
        </a>

<dd>
        The BSDF material type loads an XML (eXtensible Markup Language)
        file describing a bidirectional scattering distribution function.
        Real arguments to this material may define additional
        diffuse components that augment the BSDF data.
        String arguments are used to define thickness for proxied
        surfaces and the &quot;up&quot; orientation for the material.

<pre>
        mod BSDF id
        6+ thick BSDFfile ux uy uz funcfile transform
        0
        0|3|6|9
                rfdif gfdif bfdif
                rbdif gbdif bbdif
                rtdif gtdif btdif
</pre>

<p>
        The first string argument is a &quot;thickness&quot; parameter that may be used
        to hide detail geometry being proxied by an aggregate BSDF material.
        If a view or shadow ray hits a BSDF proxy with non-zero thickness,
        it will pass directly through as if the surface were not there.
        Similar to the illum type, this permits direct viewing and
        shadow testing of complex geometry.
        The BSDF is used when a scattered (indirect) ray hits the surface,
        and any transmitted sample rays will be offset by the thickness amount
        to avoid the hidden geometry and gather samples from the other side.
        In this manner, BSDF surfaces can improve the results for indirect
        scattering from complex systems without sacrificing appearance or
        shadow accuracy.
        If the BSDF has transmission and back-side reflection data,
        a parallel BSDF surface may be
        placed slightly less than the given thickness away from the front surface
        to enclose the complex geometry on both sides.
        The sign of the thickness is important, as it indicates
        whether the proxied geometry is behind the BSDF
        surface (when thickness is positive) or in front (when
        thickness is negative).
<p>
        The second string argument is the name of the BSDF file,
        which is found in the usual auxiliary locations.  The
        following three string parameters name variables for an
        &quot;up&quot; vector, which together with the surface
        normal, define the local coordinate system that orients the
        BSDF.  These variables, along with the thickness, are defined
        in a function file given as the next string argument.  An
        optional transform is used to scale the thickness and
        reorient the up vector.
<p>
        If no real arguments are given, the BSDF is used by itself
        to determine reflection and transmission.  If there are at
        least 3 real arguments, the first triplet is an additional
        diffuse reflectance for the front side.  At least 6 real
        arguments adds diffuse reflectance to the rear side of the
        surface.  If there are 9 real arguments, the final triplet
        will be taken as an additional diffuse transmittance.  All
        diffuse components as well as the non-diffuse transmission
        are modified by patterns applied to this material.  The
        non-diffuse reflection from either side are unaffected.
        Textures perturb the effective surface normal in the usual
        way.
<p>
        The surface normal of this type is not altered to face the
        incoming ray, so the front and back BSDF reflections may
        differ.  (Transmission is identical front-to-back by physical
        law.) If back visibility is turned off during rendering and
        there is no transmission or back-side reflection, only then
        the surface will be invisible from behind.  Unlike other
        data-driven material types, the BSDF type is fully supported
        and all parts of the distribution are properly sampled.
<p>

<dt>
        <a NAME="aBSDF">
        <b>aBSDF</b>
        </a>

<dd>
        The aBSDF material is identical to the BSDF type with two
        important differences.  First, proxy geometry is not
        supported, so there is no thickness parameter.  Second, an
        aBSDF is assumed to have some specular through component
        (the &rsquo;a&rsquo; stands for &quot;aperture&quot;),
        which is treated specially during the direct calculation
        and when viewing the material.  Based on the BSDF data, the
        coefficient of specular transmission is determined and used
        for modifying unscattered shadow and view rays.

<pre>
        mod aBSDF id
        5+ BSDFfile ux uy uz funcfile transform
        0
        0|3|6|9
             rfdif gfdif bfdif
             rbdif gbdif bbdif
             rtdif gtdif btdif
</pre>

<p>
        If a material has no specular transmitted component, it is
        much better to use the BSDF type with a zero thickness
        than to use aBSDF.
<p>

<dt>
        <a NAME="Antimatter">
        <b>Antimatter</b>
        </a>

<dd>
        Antimatter is a material that  can  &quot;subtract&quot;  volumes from other volumes.  
        A ray passing into an antimatter object becomes blind to all the specified modifiers:

<pre>
        mod antimatter id
        N mod1 mod2 .. modN
        0
        0
</pre>

        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 <a HREF="#Trans">&quot;trans&quot;</a>, 
        and multiple antimatter  surfaces  should  be  disjoint.   
        The viewpoint must be outside all volumes concerned for a correct rendering.

</dl>

<p>
<hr>

<h4>
<a NAME="Textures">2.1.3.  Textures</a>
</h4>

A texture is a perturbation of the surface normal,  and is given by either a function or data.

<p>

<dl>

<dt>
        <a NAME="Texfunc">
        <b>Texfunc</b>
        </a>

<dd>
        A texfunc uses an auxiliary function file to specify  a procedural texture:

<pre>
        mod texfunc id
        4+ xpert ypert zpert funcfile transform
        0
        n A1 A2 .. An
</pre>

<p>

<dt>
        <a NAME="Texdata">
        <b>Texdata</b>
        </a>

<dd>
        A texdata texture uses three data files to get the surface  normal  perturbations.  
        The variables xfunc, yfunc and zfunc take three arguments each from the interpolated values in xdfname, ydfname and zdfname.

<pre>
        mod texdata id
        8+ xfunc yfunc zfunc xdfname ydfname zdfname vfname x0 x1 .. xf
        0
        n A1 A2 .. An
</pre>

</dl>

<p>
<hr>

<h4>
<a NAME="Patterns">2.1.4.  Patterns</a>
</h4>

Patterns are used to modify the reflectance of  materials.  The basic types are given below.

<p>

<dl>

<dt>
        <a NAME="Colorfunc">
        <b>Colorfunc</b>
        </a>

<dd>
A colorfunc is a procedurally  defined  color  pattern.  It is specified as follows:

<pre>
        mod colorfunc id
        4+ red green blue funcfile transform
        0
        n A1 A2 .. An
</pre>

<p>

<dt>
        <a NAME="Brightfunc">
        <b>Brightfunc</b>
        </a>

<dd>
        A brightfunc is the same as a colorfunc, except  it  is monochromatic.

<pre>
        mod brightfunc id
        2+ refl funcfile transform
        0
        n A1 A2 .. An
</pre>

<p>

<dt>
        <a NAME="Colordata">
        <b>Colordata</b>
        </a>

<dd>
        Colordata uses an interpolated data  map  to  modify  a material's  color.   
        The map is n-dimensional, and is stored in three auxiliary files, one for each color.   
        The  coordinates  used  to look up and interpolate the data are defined in another auxiliary file.  
        The interpolated data values are modified  by  functions  of  one or three variables.  
        If the functions are of one variable,  then  they  are  passed  the corresponding  color  component  (red or green or blue).  
        If the functions are of three variables, then they  are  passed the original red, green, and blue values as parameters.

<pre>
        mod colordata id
        7+n+
                rfunc gfunc bfunc rdatafile gdatafile bdatafile
                funcfile x1 x2 .. xn transform
        0
        m A1 A2 .. Am
</pre>

<p>

<dt>
        <a NAME="Brightdata">
        <b>Brightdata</b>
        </a>

<dd>
        Brightdata is like colordata, except monochromatic.

<pre>
        mod brightdata id
        3+n+
                func datafile
                funcfile x1 x2 .. xn transform
        0
        m A1 A2 .. Am
</pre>

<p>

<dt>
        <a NAME="Colorpict">
        <b>Colorpict</b>
        </a>

<dd>
        Colorpict is a special case  of  colordata,  where  the pattern  is  a  two-dimensional image stored in the RADIANCE picture format.  
        The dimensions of the image data are determined  by  the  picture  such  that the smaller dimension is always 1, 
        and the other is the ratio between the larger  and the  smaller.   
        For  example,  a  500x338 picture would have coordinates  (u,v)  in  the  rectangle  between  (0,0)   and (1.48,1).

<pre>
        mod colorpict id
        7+
                rfunc gfunc bfunc pictfile
                funcfile u v transform
        0
        m A1 A2 .. Am
</pre>

<p>

<dt>
        <a NAME="Colortext">
        <b>Colortext</b>
        </a>

<dd>
        Colortext is dichromatic writing in a  polygonal  font.
        The   font   is  defined  in  an  auxiliary  file,  such  as helvet.fnt.  
        The text itself is also specified in a separate file, or can be part of the material arguments.  
        The character size, orientation, aspect ratio and slant is  determined by right and down motion vectors.  
        The upper left origin for the text block as well  as  the  foreground  and  background colors must also be given.

<pre>
        mod colortext id
        2 fontfile textfile
        0
        15+
                Ox Oy Oz
                Rx Ry Rz
                Dx Dy Dz
                rfore gfore bfore
                rback gback bback
                [spacing]
</pre>

or:

<pre>
        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]
</pre>

<p>

<dt>
        <a NAME="Brighttext">
        <b>Brighttext</b>
        </a>

<dd>
        Brighttext is like colortext, but the writing is  monochromatic.

<pre>
        mod brighttext id
        2 fontfile textfile
        0
        11+
                Ox Oy Oz
                Rx Ry Rz
                Dx Dy Dz
                foreground background
                [spacing]
</pre>

or:

<pre>
        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]
</pre>

<p>

        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).

<p>

<dt>
        <a NAME="Spectrum">
        <b>Spectrum</b>
        </a>

<dd>
        The spectrum primitive is the most basic type for introducing spectral
        color to a material.
        Since materials only provide RGB parameters, spectral patterns
        are the only way to superimpose wavelength-dependent behavior.

<pre>
        mod spectrum id
        0
        0
        5+ nmA nmB s1 s2 .. sN
</pre>

<p>
        The first two real arguments indicate the extrema of the
        spectral range in nanometers.
        Subsequent real values correspond to multipliers at each wavelength.
        The nmA wavelength may be greater or less than nmB,
        but they may not be equal, and their ordering matches
        the order of the spectral values.
        A minimum of 3 values must be given, which would act
        more or less the same as a constant RGB multiplier.
        As with RGB values, spectral quantities normally range between 0
        and 1 at each wavelength, or average to 1.0 against a standard
        sensitivity functions such as V(lambda).
        The best results obtain when the spectral range and number
        of samples match rendering options, though resampling will handle
        any differences, zero-filling wavelenths outside the nmA to nmB
        range.
        A warning will be issued if the given wavelength range does not
        adequately cover the visible spectrum.

<p>

<dt>
        <a NAME="Specfile">
        <b>Specfile</b>
        </a>

<dd>
        The specfile primitive is equivalent to the spectrum type, but
        the wavelength range and values are contained in a 1-dimensional
        data file.
        This may be a more convenient way to specify a spectral color,
        especially one corresponding to a standard illuminant such as D65
        or a library of measured spectra.

<pre>
        mod specfile id
        1 datafile
        0
        0
</pre>

<p>
        As with the spectrum type, rendering wavelengths outside the defined
        range will be zero-filled.
        Unlike the spectrum type, the file may contain non-uniform samples.

<p>

<dt>
        <a NAME="Specfunc">
        <b>Specfunc</b>
        </a>

<dd>
        The specfunc primitive offers dynamic control over a spectral
        pattern, similar to the colorfunc type.

<pre>
        mod specfunc id
        2+ sfunc funcfile transform
        0
        2+ nmA nmB A3 ..
</pre>

<p>
        Like the spectrum primitive, the wavelength range is specified
        in the first two real arguments, and additional real values are
        set in the evaluation context.
        This function is fed a wavelenth sample
        between nmA and nmB as its only argument,
        and it returns the corresponding spectral intensity.

</dl>

<p>
<hr>

<h4>
<a NAME="Mixtures">2.1.5.  Mixtures</a>
</h4>

A mixture is a blend of one or more materials or textures and patterns.
Blended materials should not be light source types or virtual source types.
The basic types are given below.

<p>

<dl>

<dt>
        <a NAME="Mixfunc">
        <b>Mixfunc</b>
        </a>

<dd>
A mixfunc mixes  two  modifiers  procedurally.   It  is specified as follows:

<pre>
        mod mixfunc id
        4+ foreground background vname funcfile transform
        0
        n A1 A2 .. An
</pre>

        Foreground and background are modifier names that must be
        defined earlier in the scene description.
        If one of these is a material, then
        the modifier of the mixfunc must be &quot;void&quot;.
        (Either the foreground or background modifier may be &quot;void&quot;,
        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).  

<p>

<dt>
        <a NAME="Mixdata">
        <b>Mixdata</b>
        </a>

<dd>
        Mixdata combines two modifiers using an auxiliary  data file:

<pre>
        mod mixdata id
        5+n+
                foreground background func datafile
                funcfile x1 x2 .. xn transform
        0
        m A1 A2 .. Am
</pre>

<dt>
        <a NAME="Mixpict">
        <b>Mixpict</b>
        </a>

<dd>
        Mixpict combines two modifiers based on a picture:

<pre>
        mod mixpict id
        7+
                foreground background func pictfile
                funcfile u v transform
        0
        m A1 A2 .. Am
</pre>

<p>

        The mixing coefficient function &quot;func&quot; takes three
        arguments, the red, green and blue values
        corresponding to the pixel at (u,v).

<p>

<dt>
        <a NAME="Mixtext">
        <b>Mixtext</b>
        </a>

<dd>
        Mixtext uses one modifier for the text foreground,  and one for the background:

<pre>
        mod mixtext id
        4 foreground background fontfile textfile
        0
        9+
                Ox Oy Oz
                Rx Ry Rz
                Dx Dy Dz
                [spacing]
</pre>

or:

<pre>
        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]
</pre>

</dl>

<p>
<hr>

<h3>
<a NAME="Auxiliary">2.2.  Auxiliary Files</a>
</h3>

Auxiliary files  used  in  <a HREF="#Textures">textures</a>  and  <a HREF="#Patterns">patterns</a>  
are accessed  by  the  programs  during image generation.  
These files may be located in  the  working  directory,  or  in  a library  directory.  
The environment variable RAYPATH can be assigned an alternate set of search directories.   
Following is a brief description of some common file types.

<p>

<h4>
<a NAME="Function">12.2.1.  Function Files</a>
</h4>

A function file contains the definitions of  variables, functions  and constants used by a primitive.  
The transformation that accompanies the file name contains the necessary rotations,  translations  and  scalings 
to bring the coordinates of the function file into  agreement  with  the  world coordinates.   
The  transformation specification is the same as for the <a HREF="#Generators">xform</a> command.  
An example function file is given below:

<pre>
        {
                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) ;
</pre>

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:

<pre>
                Dx, Dy, Dz              - incident ray direction
                Nx, Ny, Nz              - surface normal at intersection point
                Px, Py, Pz              - intersection point
                T                       - distance from start
                Ts                      - single ray (shadow) distance
                Rdot                    - cosine between ray and normal
                arg(0)                  - number of real arguments
                arg(i)                  - i'th real argument
</pre>

For mesh objects, the local surface coordinates are available:

<pre>
                Lu, Lv                  - local (u,v) coordinates
</pre>

For BRDF types, the following variables are defined as well:

<pre>
                NxP, NyP, NzP           - perturbed surface normal
                RdotP                   - perturbed dot product
                CrP, CgP, CbP           - perturbed material color
</pre>

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.
Functions (requiring parameters) must be given
as names and not as expressions.

<p>
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.

<p>
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.

<p>

<h4>
<a NAME="Data">2.2.2.  Data Files</a>
</h4>

Data files contain n-dimensional arrays of real numbers used  for  interpolation.  
Typically, definitions in a function file determine how to index and use  interpolated  data values.  
The basic data file format is as follows:

<pre>
        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.
</pre>

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.

<p>

<h4>
<a NAME="Font">2.2.3.  Font Files</a>
</h4>

A font file lists the polygons which make up a  character set.
Comments may appear anywhere in the file, beginning with a pound
sign ('#') and continuing to the end of line.
All numbers are decimal integers:

<pre>
        code n
                x0 y0
                x1 y1
                 ...
                xn yn
         ...
</pre>

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).

<p>

<hr>

<h3>
<a NAME="Generators">2.3.  Generators</a>
</h3>

A generator  is  any  program  that  produces  a  scene description  as its output.  
They usually appear as commands in a scene description file.  
An example of a simple generator  is genbox.  

<ul>

<li>
<a NAME="Genbox" HREF="../man_html/genbox.1.html">
<b>Genbox</b>
</a>
takes the arguments of width, height and depth to produce a parallelepiped  description.   
<li>
<a NAME="Genprism" HREF="../man_html/genprism.1.html">
<b>Genprism</b>
</a>
takes a list of 2-dimensional coordinates and extrudes them along a vector to
produce a 3-dimensional prism.
<li>
<a NAME="Genrev" HREF="../man_html/genrev.1.html">
<b>Genrev</b>
</a>
is a more sophisticated generator that produces an object of rotation from parametric functions for radius and axis position.    
<li>
<a NAME="Gensurf" HREF="../man_html/gensurf.1.html">
<b>Gensurf</b> 
</a>
tessellates  a  surface  defined  by  the parametric functions x(s,t), y(s,t),  and  z(s,t).   
<li>
<a NAME="Genworm" HREF="../man_html/genworm.1.html">
<b>Genworm</b>
</a>
links  cylinders and spheres along a curve.  
<li>
<a NAME="Gensky" HREF="../man_html/gensky.1.html">
<b>Gensky</b> 
</a>
produces a sun and sky distribution corresponding to a given time and date.
<li>
<a NAME="Xform" HREF="../man_html/xform.1.html">
<b>Xform</b> 
</a>
is a program that transforms a scene  description from  one coordinate space to another.  
Xform does rotation, translation, scaling, and mirroring.

</ul>

<p>
<hr>

<h2>
<a NAME="Image">3.  Image Generation</a>
</h2>

Once the scene has been described in  three-dimensions, it  is  possible  to generate a two-dimensional image from a given perspective.

<p>
The image generating programs use an  <a NAME="octree"><b>octree</b></a>  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 <a NAME="oconv1" HREF="../man_html/oconv.1.html"><b>oconv</b></a>.  
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.
<ul>
<li>
<a NAME="rvu" HREF="../man_html/rvu.1.html"><b>Rvu</b></a>  is  ray-tracing  program  for  viewing  a  scene interactively.   
When  the user specifies a new perspective, rvu quickly displays a rough image on the  terminal,  
then progressively increases the resolution as the user looks on.
He can select a particular section of the image to  improve, or  move  to  a different view and start over.  
This mode of interaction is useful for debugging scenes as well as determining the best view for a final image.

<li>
<a NAME="rpict" HREF="../man_html/rpict.1.html"><b>Rpict</b></a> produces a high-resolution  picture  of  a  scene from  a particular perspective.  
This program features adaptive sampling, crash recovery and progress reporting, all of which are important for time-consuming images.
</ul>
<p>
A number of <a NAME="filters"><b>filters</b></a> are available for manipulating picture files:
        <ul>
        <li> <a HREF="../man_html/pfilt.1.html"><b>Pfilt</b></a>
              sets  the  exposure and performs antialiasing.  
        <li> <a HREF="../man_html/pcompos.1.html"><b>Pcompos</b></a>
              composites (cuts  and  pastes)  pictures.
        <li> <a HREF="../man_html/pcomb.1.html"><b>Pcomb</b></a>
                performs arbitrary math on one or more pictures.
        <li> <a HREF="../man_html/pcond.1.html"><b>Pcond</b></a>
                conditions a picture for a specific display device.
        <li> <a HREF="../man_html/protate.1.html"><b>Protate</b></a>
                rotates a picture 90 degrees clockwise.
        <li> <a HREF="../man_html/pflip.1.html"><b>Pflip</b></a>
                flips a picture horizontally, vertically, or both
                (180 degree rotation).
        <li> <a HREF="../man_html/pvalue.1.html"><b>Pvalue</b></a>
              converts a picture to and from simpler formats.
        </ul>

<p>
Pictures may be displayed directly under X11 using the program
<a HREF="../man_html/ximage.1.html">ximage</a>,
or converted a standard image format using one of the following
<b>translators</b>:
        <ul>
        <li> <a HREF="../man_html/ra_bmp.1.html"><b>Ra_bmp</b></a>
                converts to and from BMP image format.
        <li> <a HREF="../man_html/ra_ppm.1.html"><b>Ra_ppm</b></a>
                converts to and from Poskanzer Portable Pixmap formats.
        <li> <a HREF="../man_html/ra_ps.1.html"><b>Ra_ps</b></a>
                converts to PostScript color and greyscale formats.
        <li> <a HREF="../man_html/ra_rgbe.1.html"><b>Ra_rgbe</b></a>
                converts to and from Radiance uncompressed picture format.
        <li> <a HREF="../man_html/ra_t16.1.html"><b>Ra_t16</b></a>
                converts to and from Targa 16 and 24-bit image formats.
        <li> <a HREF="../man_html/ra_t8.1.html"><b>Ra_t8</b></a>
                converts to and from Targa 8-bit image format.
        <li> <a HREF="../man_html/ra_tiff.1.html"><b>Ra_tiff</b></a>
                converts to and from TIFF.
        <li> <a HREF="../man_html/ra_xyze.1.html"><b>Ra_xyze</b></a>
                converts to and from Radiance CIE picture format.
        </ul>

<p>

<hr>

<h2>
<a NAME="License">4.  License</a>
</h2>

<pre>
The Radiance Software License, Version 1.0

Copyright (c) 1990 - 2021 The Regents of the University of California,
through Lawrence Berkeley National Laboratory.   All rights reserved.

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions
are met:

1. Redistributions of source code must retain the above copyright
        notice, this list of conditions and the following disclaimer.

2. Redistributions in binary form must reproduce the above copyright
      notice, this list of conditions and the following disclaimer in
      the documentation and/or other materials provided with the
      distribution.

3. The end-user documentation included with the redistribution,
          if any, must include the following acknowledgment:
            &quot;This product includes Radiance software
                (<a HREF="http://radsite.lbl.gov/">http://radsite.lbl.gov/</a>)
                developed by the Lawrence Berkeley National Laboratory
              (<a HREF="http://www.lbl.gov/">http://www.lbl.gov/</a>).&quot;
      Alternately, this acknowledgment may appear in the software itself,
      if and wherever such third-party acknowledgments normally appear.

4. The names &quot;Radiance,&quot; &quot;Lawrence Berkeley National Laboratory&quot;
      and &quot;The Regents of the University of California&quot; must
      not be used to endorse or promote products derived from this
      software without prior written permission. For written
      permission, please contact [email protected].

5. Products derived from this software may not be called &quot;Radiance&quot;,
      nor may &quot;Radiance&quot; appear in their name, without prior written
      permission of Lawrence Berkeley National Laboratory.

THIS SOFTWARE IS PROVIDED ``AS IS&quot; AND ANY EXPRESSED OR IMPLIED
WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
DISCLAIMED.   IN NO EVENT SHALL Lawrence Berkeley National Laboratory OR
ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
SUCH DAMAGE.
</pre>

<hr>

<h2>
<a NAME="Ack">5.  Acknowledgements</a>
</h2>

This work was supported by the Assistant  Secretary  of Conservation and Renewable Energy, 
Office of Building Energy Research and Development, 
Buildings  Equipment  Division  of the  U.S.  Department  of Energy under Contract No. DE-AC03-76SF00098.

<p>
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.

<p>

<hr>

<h2>
<a NAME="Ref">6.</a> References
</h2>
<p>
<ul>
    <li>Ward, Gregory J., Bruno Bueno, David Geisler-Moroder,
      Lars O. Grobe, Jacob C. Jonsson, Eleanor
      S. Lee, Taoning Wang, Helen Rose Wilson,
      &quot;<a href="https://doi.org/10.1016/j.enbuild.2022.111890">Daylight
      Simulation Workflows Incorporating Measured Bidirectional
      Scattering Distribution Functions</a>&quot;
      <em>Energy &amp; Buildings</em>, Vol. 259, No. 11890, 2022.
    <li>Wang, Taoning, Gregory Ward, Eleanor Lee,
      &quot;<a href="https://authors.elsevier.com/a/1XQ0a1M7zGwT7v">Efficient
      modeling of optically-complex, non-coplanar exterior shading:
      Validation of matrix algebraic methods</a>&quot;
      <em>Energy & Buildings</em>, vol. 174, pp. 464-83, Sept. 2018.
    <li>Lee, Eleanor S., David Geisler-Moroder, Gregory Ward,
      &quot;<a href="https://eta.lbl.gov/sites/default/files/publications/solar_energy.pdf">Modeling
      the direct sun component in buildings using matrix
      algebraic approaches: Methods and
      validation</a>,&quot; <em>Solar Energy</em>,
      vol. 160, 15 January 2018, pp 380-395.
    <li>Narain, Rahul, Rachel A. Albert, Abdullah Bulbul,
       Gregory J. Ward, Marty Banks, James F. O'Brien,
       &quot;<a href="http://graphics.berkeley.edu/papers/Narain-OPI-2015-08/index.html">Optimal
       Presentation of Imagery with Focus
       Cues on Multi-Plane Displays</a>,&quot;
       <em>SIGGRAPH 2015</em>.
    <li>Ward, Greg, Murat Kurt, and Nicolas Bonneel,
        &quot;<a href="papers/WMAM14_Tensor_Tree_Representation.pdf">Reducing
        Anisotropic BSDF Measurement to Common Practice</a>,&quot;
        <em>Workshop on Material Appearance Modeling</em>, 2014.
    <li>Banks, Martin, Abdullah Bulbul, Rachel Albert, Rahul Narain,
        James F. O'Brien, Gregory Ward,
        &quot;<a href="http://graphics.berkeley.edu/papers/Banks-TPO-2014-05/index.html">The
        Perception of Surface Material from Disparity and Focus Cues</a>,&quot;
        <em>VSS 2014</em>.
    <li>McNeil, A., C.J. Jonsson, D. Appelfeld, G. Ward, E.S. Lee,
        &quot;<a href="http://gaia.lbl.gov/btech/papers/4414.pdf">
        A validation of a ray-tracing tool used to generate
        bi-directional scattering distribution functions for
        complex fenestration systems</a>,&quot;
        <em>Solar Energy</em>, 98, 404-14,
        November 2013.
    <li>Ward, G., R. Mistrick, E.S. Lee, A. McNeil, J. Jonsson,
        &quot;<a href="http://gaia.lbl.gov/btech/papers/4414.pdf">Simulating
        the Daylight Performance of Complex Fenestration Systems
        Using Bidirectional Scattering Distribution Functions within
        Radiance</a>,&quot;
        <em>Leukos</em>, 7(4)
        April 2011.
    <li>Cater, Kirsten, Alan Chalmers, Greg Ward,
        &quot;<a href="http://www.anyhere.com/gward/papers/egsr2003.pdf">Detail to Attention:
        Exploiting Visual Tasks for Selective Rendering</a>,&quot;
        <em>Eurographics Symposium
        on Rendering 2003</em>, June 2003.
    <li>Ward, Greg, Elena Eydelberg-Vileshin,
        &quot;<a HREF="http://www.anyhere.com/gward/papers/egwr02/index.html">Picture Perfect RGB
        Rendering Using Spectral Prefiltering and Sharp Color Primaries</a>,&quot;
        Thirteenth Eurographics Workshop on Rendering (2002),
        P. Debevec and S. Gibson (Editors), June 2002.
    <li>Ward, Gregory,
        &quot;<a HREF="http://www.anyhere.com/gward/papers/cic01.pdf">High Dynamic Range Imaging</a>,&quot;
        Proceedings of the Ninth Color Imaging Conference, November 2001.
    <li>Ward, Gregory and Maryann Simmons,
        &quot;<a HREF="http://www.anyhere.com/gward/papers/tog99.pdf">
        The Holodeck Ray Cache: An Interactive Rendering System for Global Illumination in Nondiffuse
        Environments</a>,&quot; ACM Transactions on Graphics, 18(4):361-98, October 1999.
    <li>Larson, G.W., &quot;<a HREF="http://www.anyhere.com/gward/papers/ewp98.pdf">The Holodeck: A Parallel
        Ray-caching Rendering System</a>,&quot; Proceedings of the Second
        Eurographics Workshop on Parallel Graphics and Visualisation,
        September 1998.
    <li>Larson, G.W. and R.A. Shakespeare,
        <a HREF="http://radsite.lbl.gov/radiance/book/index.html"><em>Rendering with Radiance:
        the Art and Science of Lighting Visualization</em></a>,
        Morgan Kaufmann Publishers, 1998.
    <li>Larson, G.W., H. Rushmeier, C. Piatko,
        &quot;<a HREF="http://radsite.lbl.gov/radiance/papers/lbnl39882/tonemap.pdf">A Visibility
        Matching Tone Reproduction Operator for
        High Dynamic Range Scenes</a>,&quot; LBNL Technical Report 39882,
        January 1997.
    <li>Ward, G., &quot;<a HREF="http://radsite.lbl.gov/radiance/papers/erw95.1/paper.html">Making
        Global Illumination User-Friendly</a>,&quot; Sixth
        Eurographics Workshop on Rendering, Springer-Verlag,
        Dublin, Ireland, June 1995.</li>
    <li>Rushmeier, H., G. Ward, C. Piatko, P. Sanders, B. Rust,
        &quot;<a HREF="http://radsite.lbl.gov/mgf/compare.html">
        Comparing Real and Synthetic Images: Some Ideas about
        Metrics</a>,&quot; Sixth Eurographics Workshop on Rendering,
        Springer-Verlag, Dublin, Ireland, June 1995.</li>
    <li>Ward, G., &quot;<a HREF="http://radsite.lbl.gov/radiance/papers/sg94.1/paper.html">The RADIANCE
        Lighting Simulation and Rendering System</a>,&quot; <em>Computer
        Graphics</em>, July 1994.</li>
    <li>Rushmeier, H., G. Ward, &quot;<a HREF="http://radsite.lbl.gov/radiance/papers/sg94.2/energy.html">Energy
        Preserving Non-Linear Filters</a>,&quot; <em>Computer
        Graphics</em>, July 1994.</li>
    <li>Ward, G., &quot;A Contrast-Based Scalefactor for Luminance
        Display,&quot; <em>Graphics Gems IV</em>, Edited by Paul Heckbert,
        Academic Press 1994.</li>
    <li>Ward, G., &quot;<a HREF="http://radsite.lbl.gov/radiance/papers/sg92/paper.html">Measuring and
        Modeling Anisotropic Reflection</a>,&quot; <em>Computer
        Graphics</em>, Vol. 26, No. 2, July 1992. </li>
    <li>Ward, G., P. Heckbert, &quot;<a HREF="http://radsite.lbl.gov/radiance/papers/erw92/paper.html">Irradiance
        Gradients</a>,&quot; Third Annual Eurographics Workshop on
        Rendering, Springer-Verlag, May 1992. </li>
    <li>Ward, G., &quot;<a HREF="http://radsite.lbl.gov/radiance/papers/erw91/erw91.html">Adaptive Shadow
        Testing for Ray Tracing</a>&quot; Photorealistic Rendering in
        Computer Graphics, proceedings of 1991 Eurographics
        Rendering Workshop, edited by P. Brunet and F.W. Jansen,
        Springer-Verlag. </li>
    <li>Ward, G., &quot;Visualization,&quot; <em>Lighting Design and
        Application</em>, Vol. 20, No. 6, June 1990. </li>
    <li>Ward, G., F. Rubinstein, R. Clear, &quot;<a HREF="http://radsite.lbl.gov/radiance/papers/sg88/paper.html">A Ray Tracing Solution for
        Diffuse Interreflection</a>,&quot; <em>Computer Graphics</em>,
        Vol. 22, No. 4, August 1988. </li>
    <li>Ward, G., F. Rubinstein, &quot;A New Technique for Computer
        Simulation of Illuminated Spaces,&quot; <em>Journal of the
        Illuminating Engineering Society</em>, Vol. 17, No. 1,
        Winter 1988. </li>
</ul>
<p>
See the <a HREF="index.html">RADIANCE Reference Materials</a> page
for additional information.
<hr>

<a NAME="Index"><h2>7. Types Index</h2></a>

<pre>
<h4>
SURFACES        MATERIALS       TEXTURES        PATTERNS        MIXTURES</h4>
<a HREF="#Source">Source</a>            <a HREF="#Light">Light</a>              <a HREF="#Texfunc">Texfunc</a>          <a HREF="#Colorfunc">Colorfunc</a>      <a HREF="#Mixfunc">Mixfunc</a>
<a HREF="#Sphere">Sphere</a>            <a HREF="#Illum">Illum</a>              <a HREF="#Texdata">Texdata</a>          <a HREF="#Brightfunc">Brightfunc</a>    <a HREF="#Mixdata">Mixdata</a>
<a HREF="#Bubble">Bubble</a>            <a HREF="#Glow">Glow</a>                                <a HREF="#Colordata">Colordata</a>      <a HREF="#Mixtext">Mixtext</a>
<a HREF="#Polygon">Polygon</a>          <a HREF="#Spotlight">Spotlight</a>                      <a HREF="#Brightdata">Brightdata</a>
<a HREF="#Cone">Cone</a>                <a HREF="#Mirror">Mirror</a>                            <a HREF="#Colorpict">Colorpict</a>
<a HREF="#Cup">Cup</a>          <a HREF="#Prism1">Prism1</a>                            <a HREF="#Colortext">Colortext</a>
<a HREF="#Cylinder">Cylinder</a>        <a HREF="#Prism2">Prism2</a>                            <a HREF="#Brighttext">Brighttext</a>
<a HREF="#Tube">Tube</a>                <a HREF="#Plastic">Plastic</a>
<a HREF="#Ring">Ring</a>                <a HREF="#Metal">Metal</a>
<a HREF="#Instance">Instance</a>        <a HREF="#Trans">Trans</a>
<a HREF="#Mesh">Mesh</a>                <a HREF="#Plastic2">Plastic2</a>
                <a HREF="#Metal2">Metal2</a>
                <a HREF="#Trans2">Trans2</a>
                <a HREF="#Mist">Mist</a>
                <a HREF="#Dielectric">Dielectric</a>
                <a HREF="#Interface">Interface</a>
                <a HREF="#Glass">Glass</a>
                <a HREF="#Plasfunc">Plasfunc</a>
                <a HREF="#Metfunc">Metfunc</a>
                <a HREF="#Transfunc">Transfunc</a>
                <a HREF="#BRTDfunc">BRTDfunc</a>
                <a HREF="#Plasdata">Plasdata</a>
                <a HREF="#Metdata">Metdata</a>
                <a HREF="#Transdata">Transdata</a>
                <a HREF="#BSDF">BSDF</a>
                <a HREF="#Antimatter">Antimatter</a>
                                
</pre>

<p>


<hr>
<center>Last Update: October 22, 1997</center>
</body>
</html>

Revision:	1.37
Committed:	Tue Dec 12 20:25:22 2023 UTC (5 months ago) by greg
Content type:	text/html
Branch:	MAIN
Changes since 1.36:	+2 -2 lines
Log Message:	docs: renamed function