Ubuntu Manpage: rad - render a RADIANCE scene

name
synopsis
description
examples
files
author
bugs
see also

Provided by: radiance_4R1+20120125-1.1_amd64

NAME

       rad - render a RADIANCE scene

SYNOPSIS

       rad [ -s ][ -n | -N npr ][ -t ][ -e ][ -V ][ -w ][ -v view ][ -o device ] rfile [ VAR=value ..  ]

DESCRIPTION

Rad is an executive program that reads the given rfile and makes appropriate calls to oconv(1),
mkillum(1), rpict(1), pfilt(1), and/or rvu(1) to render a specific scene. Variables in rfile give input
files and qualitative information about the rendering(s) desired that together enable rad to
intelligently set parameter values and control the simulation.

Normally, commands are echoed to the standard output as they are executed. The -s option tells rad to do
its work silently. The -n option tells rad not to take any action (ie. not to actually execute any
commands). The -N option instructs rad to run as many as npr rendering processes in parallel. The -t
option tells rad to bring rendering files up to date relative to the input (scene description) files,
without performing any actual calculations. If no octree exists, it is still necessary to run oconv(1)
to create one, since the -t option will not create invalid (i.e. empty) files, and a valid octree is
necessary for the correct operation of rad. The -e option tells rad to explicate all variables used for
the simulation, including default values not specified in the input file, and print them on the standard
output.

Normally, rad will produce one picture for each view given in rfile. The -v option may be used to
specify a single desired view. The view argument may either be a complete view specification (enclosed
in quotes and beginning with an optional identifier) or a number or single-word identifier to match a
view defined in rfile. If the argument is one of the standard view identifiers, it may or may not be
further elaborated in rfile. (See "view" variable description, below.) If the argument does not match
any views in rfile and is not one of the standard views, no rendering will take place. This may be
convenient when the only action desired of rad is the rebuilding of the octree. In particular, the
argument "0" will never match a view.

If the -V option is given, each view will be printed on the standard output before being applied, in a
form suitable for use in a view file or rpict rendering sequence. This is helpful as feedback or for
accessing the rad view assignments without necessarily starting a rendering.

By default, rad will run rpict and pfilt to produce a picture for each view. The -o option specifies an
output device for rvu (usually "x11") and runs this interactive program instead, using the first view in
rfile or the view given with the -v option as the starting point.

Additional variable settings may be added or overridden on the command line following rfile. Upper case
variables specified more than once will result in a warning message (unless the -w option is present),
and the last value given will be the one used.

The -w option turns off warnings about multiply and misassigned variables.

Rendering variable assignments appear one per line in rfile. The name of the variable is followed by an
equals sign ('=') and its value(s). The end of line may be escaped with a backslash ('\'), though it is
not usually necessary since additional variable values may be given in multiple assignments. Variables
that should have only one value are given in upper case. Variables that may have multiple values are
given in lower case. Variables may be abbreviated by their first three letters. Comments in rfile start
with a pound sign ('#') and proceed to the end of line.

The rendering variables, their interpretations and default values are given below.

OCTREE The name of the octree file. The default name is the same as rfile but with any suffix
replaced by ".oct". (The octree must be a file -- rad cannot work with commands that produce
octrees.)

ZONE This variable specifies the volume of interest for this simulation. The first word is either
"Interior" or "Exterior", depending on whether the zone is to be observed from the inside or
the outside, respectively. (A single letter may be given, and case does not matter.) The
following six numbers are the minimum and maximum X coordinates, minimum and maximum Y, and
minimum and maximum Z for the zone perimeter. It is important to give the zone as it is used
to determine many of the rendering parameters. The default exterior zone is the bounding cube
for the scene as computed by oconv.

EXPOSURE This variable tells rad how to adjust the exposure for display. It is important to set this
variable properly as it is used to determine the ambient value. An appropriate setting may be
discovered by running rvu and noting the exposure given by the "exposure =" command. As in rvu
and pfilt, the exposure setting may be given either as a multiplier or as a number of f-stop
adjustments (eg. +2 or -1.5). There is no default value for this variable. If it is not
given, an average level will be computed by pfilt and the ambient value will be set to 10 for
exterior zones and 0.01 for interior zones.

EYESEP The interocular spacing for stereo viewing. I.e., the world distance between the pupils of the
left and right eyes. The default value is the sum of the three "ZONE" dimensions divided by
100.

scene This variable is used to specify one or more scene input files. These files will be given
together with the materials file(s) and any options specified by the "oconv" variable to oconv
to produce the octree given by the "OCTREE" variable. In-line commands may be specified in
quotes instead of a file, beginning with an exclamation mark ('!'). If the "scene" variable is
not present, then the octree must already exist in order for rad to work. Even if this
variable is given, oconv will not be run unless the octree is out of date with respect to the
input files. Note that the order of files in this variable is important for oconv to work
properly, and files given in later variable assignments will appear after previous ones on the
oconv command line.

materials This variable is used to specify files that, although they must appear on the oconv command
line, do not affect the actual octree itself. Keeping the materials in separate files allows
them to be modified without requiring the octree to be rebuilt (a sometimes costly procedure).
These files should not contain any geometry, and the -f option must not be given in the "oconv"
variable for this to work.

illum This variable is used to specify files with surfaces to be converted into illum sources by
mkillum(1). When this variable is given, additional octree files will be created to contain
the scene before and after illum source conversion. These files will be named according to the
(default) value of the OCTREEE variable, with either a '0' or a '1' appearing just before the
file type suffix (usually ".oct").

objects This variable is used for files that, although they do not appear on the oconv command line,
contain geometric information that is referenced indirectly by the scene files. If any of
these files is changed, the octree will be rebuilt. (The raddepend(1) command may be used to
find these dependencies automatically.)

view This variable is used to specify a desired view for this zone. Any number of "view" lines may
be given, and each will result in a rendered picture (unless the -v or -o option is specified).
The value for this variable is an optional identifier followed by any number of view options
(see rpict(1) for a complete listing). The identifier is used in file naming and associating a
desired view with the -v command line option. Also, there are several standard view
identifiers defined by rad. These standard views are specified by strings of the form
"[Xx]?[Yy]?[Zz]?[vlcahs]?". (That is, an optional upper or lower case X followed by an
optional upper or lower case Y followed by an optional upper or lower case Z followed by an
optional lower case V, L, C, A or H.) The letters indicate the desired view position, where
upper case X means maximum X, lower case means minimum and so on. The final letter is the view
type, where 'v' is perspective (the default), 'l' is parallel, 'c' is a cylindrical panorama,
´a' is angular fisheye, 'h' is hemispherical fisheye, and 's' is a planisphere (stereographic)
fisheye. A perspective view from maximum X, minimum Y would be "Xy" or "Xyv". A parallel view
from maximum Z would be "Zl". If "ZONE" is an interior zone, the standard views will be inside
the perimeter. If it is an exterior zone, the standard views will be outside. Note that the
standard views are best used as starting points, and additional arguments may be given after
the identifier to modify a standard view to suit a particular model. The default view is "X"
if no views are specified. A single specified view of "0" means no views will be automatically
generated.

UP The vertical axis for this scene. A negative axis may be specified with a minus sign (eg.
"-Y"). There is no default value for this variable, although the standard views assume Z is up
if no other axis is specified.

RESOLUTION
This variable specifies the desired final picture resolution. If only a single number is
given, this value will be used for both the horizontal and vertical picture dimensions. If two
numbers are given, the first is the horizontal resolution and the second is the vertical
resolution. If three numbers are given, the third is taken as the pixel aspect ratio for the
final picture (a real value). If the pixel aspect ratio is zero, the exact dimensions given
will be those produced. Otherwise, they will be used as a frame in which the final image must
fit. The default value for this variable is 512.

QUALITY This variable sets the overall rendering quality desired. It can have one of three values,
"LOW", "MEDIUM" or "HIGH". These may be abbreviated by their first letter, and may be in upper
or lower case. Most of the rendering options will be affected by this setting. The default
value is "L".

PENUMBRAS This is a boolean variable indicating whether or not penumbras are desired. A value of "TRUE"
will result in penumbras (soft shadows), and a value of "FALSE" will result in no penumbras
(sharp shadows). True and false may be written in upper or lower case, and may be abbreviated
by a single letter. Renderings generally proceed much faster without penumbras. The default
value is "F".

INDIRECT This variable indicates how many diffuse reflections are important in the general lighting of
this zone. A direct lighting system (eg. fluorescent troffers recessed in the ceiling)
corresponds to an indirect level of 0. An indirect lighting system (eg. hanging fluorescents
directed at a reflective ceiling) corresponds to an indirect level of 1. A diffuse light shelf
reflecting sunlight onto the ceiling would correspond to an indirect level of 2. The setting
of this variable partially determines how many interreflections will be calculated. The
default value is 0.

PICTURE This is the root name of the output picture file(s). This name will have appended the view
identifier (or a number if no id was used) and a ".hdr" suffix. If a picture corresponding to
a specific view exists and is not out of date with respect to the given octree, it will not be
re-rendered. The default value for this variable is the root portion of rfile.

RAWFILE This is the root name of the finished, raw rpict output file. If specified, rad will rename
the original rpict output file once it is finished and filtered rather than removing it, which
is the default action. The given root name will be expanded in the same way as the "PICTURE"
variable, and if the "RAWFILE" and "PICTURE" variables are identical, then no filtering will
take place.

ZFILE This is the root name of the raw distance file produced by the -z option of rpict. To this
root name, an underscore plus the view name plus a ".zbf" suffix will be added. If no "ZFILE"
is specified, none will be produced.

AMBFILE This is the name of the file where "ambient" or diffuse interreflection values will be stored
by rpict or rvu. Although it is not required, an ambient file should be given whenever an
interreflection calculation is expected. This will optimize successive runs and minimize
artifacts. An interreflection calculation will take place when the "QUALITY" variable is set
to HIGH, or when the "QUALITY" variable is set to MEDIUM and "INDIRECT" is positive. There is
no default value for this variable.

DETAIL This variable specifies the level of visual detail in this zone, and is used to determine image
sampling rate, among other things. If there are few surfaces and simple shading, then this
should be set to LOW. For a zone with some furniture it might be set to MEDIUM. If the space
is very cluttered or contains a lot of geometric detail and textures, then it should be set to
HIGH. The default value is "M".

VARIABILITY
This variable tells rad how much light varies over the surfaces of this zone, and is used to
determine what level of sampling is necessary in the indirect calculation. For an electric
lighting system with uniform coverage, the value should be set to LOW. For a space with spot
lighting or a window with sky illumination only, it might be set to MEDIUM. For a space with
penetrating sunlight casting bright patches in a few places, it should be set to HIGH. The
default value is "L".

OPTFILE This is the name of a file in which rad will place the appropriate rendering options. This
file can later be accessed by rpict or rvu in subsequent manual runs using the at-sign ('@')
file insert option. (Using an "OPTFILE" also reduces the length of the rendering command,
which improves appearance and may even be necessary on some systems.) There is no default
value for this variable.

REPORT This variable may be used to specify a reporting interval for batch rendering. Given in
minutes, this value is multiplied by 60 and passed to rpict with the -t option. If a filename
is given after the interval, it will be used as the error file for reports and error messages
instead of the standard error. (See the -e option of rpict(1). There is no default value for
this variable.

oconv This variable may be used to specify special options to oconv. If the first word of the first
instance of this variable is not an option, it will be used in place of the default command
path, "oconv". See the oconv(1) manual page for a list of valid options.

mkillum This variable may be used to specify additional options to mkillum. If the first word of the
first instance of this variable is not an option, it will be used in place of the default
command path, "mkillum". See the rtrace(1) manual page for a list of valid options.

render This variable may be used to specify additional options to rpict or rvu. These options will
appear after the options set automatically by rad, and thus will override the default values.

rpict This variable may be used to specify overriding options specific to rpict. If the first word
of the first instance of this variable is not an option, it will be used in place of the
default command path, "rpict". See the rpict(1) man page for a list of valid options.

rvu This variable may be used to specify overriding options specific to rvu. If the first word of
the first instance of this variable is not an option, it will be used in place of the default
command path, "rvu". See the rvu(1) man page for a list of valid options.

pfilt This variable may be used to specify additional options to pfilt. If the first word of the
first instance of this variable is not an option, it will be used in place of the default
command path, "pfilt". See the pfilt(1) manual page for details.

EXAMPLES

       A minimal input file for rad might look like this:

          ::::::::::
          sample.rif
          ::::::::::
          # The octree we want to use:
          OCTREE= tutor.oct        # w/o this line, name would be "sample.oct"
          # Our scene input files:
          scene= sky.rad outside.rad room.rad srcwindow.rad
          # The interior zone cavity:
          ZONE= I  0 3  0 2  0 1.75          # default would be scene bounding cube
          # The z-axis is up:
          UP= Z                    # no default - would use view spec.
          # Our exposure needs one f-stop boost:
          EXPOSURE= +1             # default is computed ex post facto

       Note that we have not specified any views in the file above.  The standard default view "X" would be used
       if  we  were  to  run rad on this file.  If we only want to see what default values rad would use without
       actually executing anything, we can invoke it thus:

         rad -n -e sample.rif

       This will print the variables we have given as well as default values rad has assigned for us.  Also,  we
       will  see the list of commands that rad would have executed had the -n option not been present.  (Note if
       the octree, "tutor.oct", is not present, an error will result as it is needed to determine  some  of  the
       opiton settings.)

       Different option combinations have specific uses, ie:

         rad -v 0 sample.rif OPT=samp.opt   # build octree, put options in "sample.opt"
         rad -n -e -s sample.rif > full.rif # make a complete rad file
         rad -n sample.rif > script.sh # make a script of commands
         rad -V -v Zl -n -s sample.rif > plan.vf # make a plan view file
         rad -t sample.rif        # update files after minor change to input
         rad -s sample.rif &      # execute silently in the background
         rad -N 2 sample.rif # render views using two parallel rpict calls
         rad -N 4 -v 1 sample.rif # render first view with four rpiece calls

       If we decide that the default values rad has chosen for our variables are not all appropriate, we can add
       some more assignments to the file:

          QUAL= MED      # default was low
          DET= low       # default was medium - our space is almost empty
          PEN= True      # we want to see soft shadows from our window
          VAR= hi        # daylight can result in fairly harsh lighting
          view= XYa -vv 120   # let's try a fisheye view
          PICT= tutor         # our picture name will be "tutor_XYa.hdr"

       Note the use of abbreviations, and the modification of a standard view.  Now we can invoke rad to take  a
       look at our scene interactively with rvu:

         rad -o x11 sample.rif

       Rad  will  run oconv first to create the octree (assuming it doesn't already exist), then rvu with a long
       list of options.  Let's say that from within rvu, we wrote out the view files "view1.vp" and  "view2.vp".
       We could add these to "sample.rif" like so:

         view= vw1 -vf view1.vp        # Our first view
         view= vw2 -vf view2.vp        # Our second view
         RESOLUTION= 1024         # Let's go for a higher resolution result

       To start rvu again using vw2 instead of the default, we use:

         rad -o x11 -v vw2 sample.rif

       Once we are happy with the variable settings in our file, we can run rad in the background to produce one
       image for each view:

         rad sample.rif REP=5 >& errfile &

       This will report progress every five minutes to "errfile".

FILES

       $(PICTURE)_$(view).unf   Unfinished output of rpict

AUTHOR

       Greg Ward

BUGS

       You cannot run more than one rad process at a time on the same input file, as  the  second  process  will
       attempt  to  recover the output files of the first process, damaging the results.  The exceptions to this
       are running interactively via the -o option, or rendering different views using the -v option.

       Incremental building of octrees is not  supported  as  it  would  add  considerable  complexity  to  rad.
       Complicated  scene  builds  should  still  be  left to make(1), which has a robust mechanism for handling
       hierarchical dependencies.  If make is used in this fashion, then only the "OCTREE" variable  of  rad  is
       needed.

       The  use  of  some  pfilt  options  is  awkward,  since  the "EXPOSURE" variable results in a single pass
       invocation (the -1 option of pfilt and two passes  are  necessary  for  certain  effects,  such  as  star
       patterns.   The  way  around  this  problem  is  to specify a "RAWFILE" that is the same as the "PICTURE"
       variable so that no filtering takes place, then call pfilt manually.  This is preferable to  leaving  out
       the "EXPOSURE" variable, since the exposure level is needed to accurately determine the ambient value for
       rpict.

       The use of upper and lower case naming for the standard views may be problematic on  systems  that  don't
       distinguish case in filenames.