xenial (1) rad.1.gz

Provided by: radiance_4R1+20120125-1.1_amd64 bug

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.

SEE ALSO

       glrad(1),  make(1),  mkillum(1),  objview(1),  oconv(1),  pfilt(1),  raddepend(1), ranimate(1), rholo(1),
       rpict(1), rpiece(1), rtrace(1), rvu(1), touch(1), vgaimage(1), ximage(1)