RAD(1)                                                                  RAD(1)



NNAAMMEE
       rad - render a RADIANCE scene

SSYYNNOOPPSSIISS
       rraadd [ --ss ][ --nn||--NN nnpprr ][ --tt ][ --ee ][ --VV ][ --ww ][ --vv vviieeww ][ --oo ddeevviiccee ]
       rrffiillee [ VVAARR==vvaalluuee ....  ]

DDEESSCCRRIIPPTTIIOONN
       _R_a_d is an executive program that reads the given _r_f_i_l_e and makes appro-
       priate calls to _o_c_o_n_v_(_1_)_, _m_k_i_l_l_u_m_(_1_)_, _r_p_i_c_t_(_1_)_, _p_f_i_l_t_(_1_)_, and/or _r_v_u_(_1_)
       to render a specific scene.  Variables in _r_f_i_l_e give  input  files  and
       qualitative  information  about  the rendering(s) desired that together
       enable _r_a_d to intelligently set parameter values and control the  simu-
       lation.

       Normally,  commands  are echoed to the standard output as they are exe-
       cuted.  The _-_s option tells _r_a_d to do its work silently.  The _-_n option
       tells  _r_a_d not to take any action (ie. not to actually execute any com-
       mands).  The _-_N option instructs _r_a_d to run as many  as  _n_p_r  rendering
       processes  in  parallel.   The  _-_t  option tells _r_a_d to bring rendering
       files up to date relative to the input (scene description) files, with-
       out  performing  any  actual  calculations.  If no octree exists, it is
       still necessary to run _o_c_o_n_v_(_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 _r_a_d_.  The _-_e option tells _r_a_d 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, _r_a_d will produce one picture for each view  given  in  _r_f_i_l_e_.
       The  _-_v  option may be used to specify a single desired view.  The _v_i_e_w
       argument may either be  a  complete  view  specification  (enclosed  in
       quotes  and  beginning with an optional identifier) or a number or sin-
       gle-word identifier to match a view defined in _r_f_i_l_e_.  If the  argument
       is  one  of the standard view identifiers, it may or may not be further
       elaborated in _r_f_i_l_e_.  (See "view" variable description, below.)  If the
       argument  does not match any views in _r_f_i_l_e and is not one of the stan-
       dard views, no rendering will take place.  This may be convenient  when
       the  only  action  desired  of _r_a_d 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 _r_p_i_c_t rendering sequence.   This  is  helpful  as  feedback  or  for
       accessing  the _r_a_d view assignments without necessarily starting a ren-
       dering.

       By default, _r_a_d will run _r_p_i_c_t and _p_f_i_l_t to produce a picture for  each
       view.  The _-_o option specifies an output device for _r_v_u (usually "x11")
       and runs this interactive program instead,  using  the  first  view  in
       _r_f_i_l_e 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 _r_f_i_l_e_.  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  vari-
       ables.

       Rendering  variable assignments appear one per line in _r_f_i_l_e_.  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 mul-
       tiple 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 _r_f_i_l_e start with a pound sign ('#') and proceed to the  end
       of line.

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

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

       ZZOONNEE      This variable specifies the volume of interest for this simu-
                 lation.  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  maxi-
                 mum  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 _o_c_o_n_v_.

       EEXXPPOOSSUURREE  This variable tells _r_a_d how to adjust the exposure  for  dis-
                 play.  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  _r_v_u and noting the exposure
                 given by the "exposure =" command.  As in _r_v_u and _p_f_i_l_t_,  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 _p_f_i_l_t and the ambient value
                 will  be  set  to 10 for exterior zones and 0.01 for interior
                 zones.

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

       sscceennee     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
                 _o_c_o_n_v 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 _r_a_d to work.  Even  if  this  variable  is
                 given, _o_c_o_n_v 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 _o_c_o_n_v to work prop-
                 erly, and files given  in  later  variable  assignments  will
                 appear after previous ones on the _o_c_o_n_v command line.

       mmaatteerriiaallss This  variable  is  used to specify files that, although they
                 must appear on the _o_c_o_n_v 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.

       iilllluumm     This  variable  is  used to specify files with surfaces to be
                 converted into illum sources by _m_k_i_l_l_u_m_(_1_)_.  When this  vari-
                 able  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 _O_C_T_R_E_E_E variable, with either a '0' or  a  '1'  appearing
                 just before the file type suffix (usually ".oct").

       oobbjjeeccttss   This  variable  is  used for files that, although they do not
                 appear on the _o_c_o_n_v command line, contain geometric  informa-
                 tion  that  is  referenced indirectly by the scene files.  If
                 any of these files is changed, the octree  will  be  rebuilt.
                 (The _r_a_d_d_e_p_e_n_d_(_1_) command may be used to find these dependen-
                 cies automatically.)

       vviieeww      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 iden-
                 tifier followed by any number of view options  (see  _r_p_i_c_t_(_1_)
                 for a complete listing).  The identifier is used in file nam-
                 ing and associating a desired view with the _-_v  command  line
                 option.   Also,  there  are several standard view identifiers
                 defined by  _r_a_d_.   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,  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 iden-
                 tifier 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.

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

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

       QQUUAALLIITTYY   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".

       PPEENNUUMMBBRRAASS This is a boolean variable indicating whether or  not  penum-
                 bras 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  let-
                 ter.  Renderings generally proceed much faster without penum-
                 bras.  The default value is "F".

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

       PPIICCTTUURREE   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 corre-
                 sponding 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
                 _r_f_i_l_e_.

       RRAAWWFFIILLEE   This is the root name of the finished, raw _r_p_i_c_t output file.
                 If specified, _r_a_d will rename the original _r_p_i_c_t 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.

       ZZFFIILLEE     This  is  the  root name of the raw distance file produced by
                 the _-_z option of _r_p_i_c_t_.  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.

       AAMMBBFFIILLEE   This is the name of  the  file  where  "ambient"  or  diffuse
                 interreflection  values  will  be  stored  by  _r_p_i_c_t  or _r_v_u_.
                 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 "QUAL-
                 ITY" 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.

       DDEETTAAIILL    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 furni-
                 ture it might be set to MEDIUM.  If the space is  very  clut-
                 tered  or  contains  a  lot of geometric detail and textures,
                 then it should be set to HIGH.  The default value is "M".

       VVAARRIIAABBIILLIITTYY
                 This variable tells _r_a_d how much light varies over  the  sur-
                 faces  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".

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

       RREEPPOORRTT    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 _r_p_i_c_t 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 _r_p_i_c_t_(_1_)_.  There is no default
                 value for this variable.

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

       mmkkiilllluumm   This variable may be used to specify  additional  options  to
                 _m_k_i_l_l_u_m_.   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 _r_t_r_a_c_e_(_1_) manual
                 page for a list of valid options.

       rreennddeerr    This variable may be used to specify  additional  options  to
                 _r_p_i_c_t  or  _r_v_u_.   These options will appear after the options
                 set automatically by _r_a_d_, and thus will override the  default
                 values.

       rrppiicctt     This  variable may be used to specify overriding options spe-
                 cific to _r_p_i_c_t_.  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 _r_p_i_c_t_(_1_) man page
                 for a list of valid options.

       rrvvuu       This  variable may be used to specify overriding options spe-
                 cific to _r_v_u_.  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 _r_v_u_(_1_) man page for
                 a list of valid options.

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

EEXXAAMMPPLLEESS
       A minimal input file for _r_a_d 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 stan-
       dard default view "X" would be used if we were to run _r_a_d on this file.
       If  we only want to see what default values _r_a_d would use without actu-
       ally 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
       _r_a_d  has  assigned for us.  Also, we will see the list of commands that
       _r_a_d 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 _r_a_d 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 _r_a_d to take a look at our scene interactively with
       _r_v_u_:

         rad -o x11 sample.rif

       _R_a_d will run _o_c_o_n_v first to create  the  octree  (assuming  it  doesn't
       already  exist),  then _r_v_u with a long list of options.  Let's say that
       from within _r_v_u_, 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 _r_v_u 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
       _r_a_d 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".

FFIILLEESS
       $(PICTURE)_$(view).unf   Unfinished output of _r_p_i_c_t

AAUUTTHHOORR
       Greg Ward

BBUUGGSS
       Incremental building of octrees is not supported as it would  add  con-
       siderable  complexity to _r_a_d_.  Complicated scene builds should still be
       left to _m_a_k_e_(_1_)_, which has a robust mechanism for handling hierarchical
       dependencies.   If _m_a_k_e is used in this fashion, then only the "OCTREE"
       variable of _r_a_d is needed.

       The use of some _p_f_i_l_t options is awkward, since the "EXPOSURE" variable
       results  in  a  single  pass invocation (the _-_1 option of _p_f_i_l_t 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
       _p_f_i_l_t manually.  This is preferable to leaving out the "EXPOSURE" vari-
       able, since the exposure level is needed to  accurately  determine  the
       ambient value for _r_p_i_c_t_.

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

SSEEEE AALLSSOO
       glrad(1), make(1), mkillum(1), objview(1), oconv(1),  pfilt(1),  radde-
       pend(1),  ranimate(1), rholo(1), rpict(1), rtrace(1), rvu(1), touch(1),
       vgaimage(1), ximage(1)



RADIANCE                            2/1/99                              RAD(1)
