| |
rad (1)
NAME
|
rad - render a RADIANCE scene |
SYNOPSIS
|
rad [ -s ][ -n ][ -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 rview(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 -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 rview
(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. |
|
The name of the octree file. The default name is the same as
rfile but with any suffix replaced by
".oct". |
|
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. |
|
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 rview and noting
the exposure given by the "exposure =" command. As
in rview 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. |
|
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. |
|
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. |
|
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. |
|
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"). |
|
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.) |
|
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]?[vlcah]?". (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
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. |
|
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. |
|
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". |
|
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". |
|
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. |
|
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 ".pic" 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. |
|
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. |
|
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. |
|
This is the name of the file where "ambient" or
diffuse interreflection values will be stored by
rpict or rview. 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. |
|
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". |
|
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". |
|
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 rview 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. |
|
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. |
|
This variable may be used to specify special options to
oconv. See the oconv(1) manual page for a list
of valid options. |
|
This variable may be used to specify additional options to
mkillum. See the rtrace(1) manual page for a
list of valid options. |
|
This variable may be used to specify additional options to
rpict or rview. These options will appear
after the options set automatically by rad, and thus
will override the default values. |
|
This variable may be used to specify additional options to
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: |
|
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 |
|
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.pic"
|
|
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 rview: |
|
Rad will run oconv first to create the octree
(assuming it doesn't already exist), then rview with
a long list of options. Let's say that from within
rview, 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 rview 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
BUGS
|
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. |
SEE ALSO
|
glrad(1), make(1), mkillum(1), objview(1), oconv(1),
pfilt(1), raddepend(1), ranimate(1), rpict(1), rtrace(1),
rview(1), touch(1), vgaimage(1), ximage(1) |
|
