Radiance rtcontrib program



RTCONTRIB(1)                                                      RTCONTRIB(1)




NAME

       rtcontrib - compute contribution coefficients in a RADIANCE scene


SYNOPSIS

       rtcontrib  [  -n nprocs ][ -V ][ -fo | -r ][ -e expr ][ -f source ][ -o
       ospec ][ -b binv ][ -bn nbins ] { -m mod | -M file } [ $EVAR ] [  @file
       ] [ rtrace options ] octree
       rtcontrib [ options ] -defaults


DESCRIPTION

       Rtcontrib  computes  ray  coefficients  for objects whose modifiers are
       named in one or more -m settings.  These modifiers are usually  materi-
       als  associated with light sources or sky domes, and must directly mod-
       ify some geometric primitives to be considered in the output.  A  modi-
       fier  list  may also be read from a file using the -M option.  The RAY-
       PATH environment variable determines directories  to  search  for  this
       file.   (No search takes place if a file name begins with a '.', '/' or
       '~' character.)

       By setting the boolean -V option, you may instruct rtcontrib to  report
       the  contribution  from  each material rather than the ray coefficient.
       This is particularly useful for light sources with  directional  output
       distributions,  whose  value  would  otherwise  be lost in the shuffle.
       With the default -V- setting, the output of rtcontrib is a  coefficient
       that must be multiplied by the radiance of each material to arrive at a
       final contribution.  This is more  convenient  for  computing  daylight
       coefficeints,  or  cases where the actual radiance is not desired.  Use
       the -V+ setting when you wish  to  simply  sum  together  contributions
       (with  possible  adjustment  factors) to obtain a final radiance value.
       Combined with  the  -i  or  -I  option,  irradiance  contributions  are
       reported  by  -V+ rather than radiance, and -V- coefficients contain an
       additonal factor of PI.

       The output of rtcontrib has many potential uses.  Source  contributions
       can  be  used  as  components  in  linear  combination to reproduce any
       desired variation, e.g., simulating lighting controls or  changing  sky
       conditions via daylight coefficients.  More generally, rtcontrib can be
       used to compute arbitrary input-output relationships  in  optical  sys-
       tems, such as luminaires, light pipes, and shading devices.

       Rtcontrib  calls  rtrace(1) with the -oTW (or -oTV) option to calculate
       the daughter ray contributions for each input ray, and the output  tal-
       lies  are  sent  to  one or more destinations according to the given -o
       specification.  If a destination begins with an exclamation mark ('!'),
       then  a  pipe  is  opened to a command and data is sent to its standard
       input.  Otherwise, the destination is treated as a file.   An  existing
       file  of  the same name will not be clobbered, unless the -fo option is
       given.  If instead  the  -r  option  is  specified,  data  recovery  is
       attempted  on  existing  files.   If an output specification contains a
       "%s" format, this will be replaced by the modifier name.  The -b option
       may  be  used  to  further  define a "bin number" within each object if
       finer resolution is needed, and this will be applied to a  "%d"  format
       in  the output file specification if present.  The actual bin number is
       computed at run time based on ray direction and  surface  intersection,
       as  described  below.   If  the  number of bins is known in advance, it
       should be specified with the -bn option, and this is critical for  out-
       put  files  containing  multiple  values per record.  Since bin numbers
       start from 0, the bin count is always equal to the  last  bin  plus  1.
       Set the this value to 0 if the bin count is unknown (the default).  The
       most recent -b, -bn and -o options to  the  left  of  each  -m  setting
       affect  only that modifier.  (The ordering of other options is unimpor-
       tant.)

       If a -b expression is defined for a particular modifier, the bin number
       will  be  evaluated  at run time for each ray contribution from rtrace.
       Specifically, each ray's world intersection point will be  assigned  to
       the  variables Px, Py, and Pz, and the normalized ray direction will be
       assigned to Dx, Dy, and Dz.  These parameters may be combined with def-
       initions given in -e arguments and files read using the -f option.  The
       computed bin value will be rounded to the nearest whole  number.   This
       mechanism  allows the user to define precise regions or directions they
       wish to accumulate, such as  the  Tregenza  sky  discretization,  which
       would  be  otherwise  impossible to specify as a set of RADIANCE primi-
       tives.  The rules and predefined functions available for these  expres-
       sions  are described in the rcalc(1) man page.  Unlike rcalc, rtcontrib
       will search the RADIANCE library directories for each file given  in  a
       -f option.

       If  no  -o  specification is given, results are written on the standard
       output in order of modifier (as given on the  command  line)  then  bin
       number.   Concatenated data is also sent to a single destination (i.e.,
       an initial -o specification without formatting  strings).   If  a  "%s"
       format  appears but no "%d" in the -o specification, then each modifier
       will have its own output file, with multiple values per record  in  the
       case  of  a  non-zero  -b  definition.  If a "%d" format appears but no
       "%s", then each bin will get its own output file, with modifiers output
       in  order in each record.  For text output, each RGB coefficient triple
       is separated by a tab, with a newline at the end of  each  ray  record.
       For  binary  output formats, there is no such delimiter to mark the end
       of each record.

       Input and output format defaults to plain text, where each ray's origin
       and  direction (6 real values) are given on input, and one line is pro-
       duced per output file per ray.  Alternative data representations may be
       specified  by  the  -f[io] option, which is described in the rtrace man
       page along with the associated -x and -y resolution settings.  In  par-
       ticular, the color ('c') output data representation together with posi-
       tive dimensions for -x and -y will  produce  an  uncompressed  RADIANCE
       picture, suitable for manipulation with pcomb(1) and related tools.

       If  the  -n  option  is specified with a value greater than 1, multiple
       rtrace processes will be used to accelerate  computation  on  a  shared
       memory  machine.  Note that there is no benefit to using more processes
       than there are local CPUs available to do the work, and  the  rtcontrib
       process itself may use a considerable amount of CPU time.

       Options  may be given on the command line and/or read from the environ-
       ment and/or read from a file.  A command argument beginning with a dol-
       lar  sign  ('$')  is  immediately replaced by the contents of the given
       environment variable.  A command argument beginning  with  an  at  sign
       ('@') is immediately replaced by the contents of the given file.


EXAMPLES

       To  compute  the  proportional  contributions  from sources modified by
       "light1" vs. "light2" on a set of illuminance values:

         rtcontrib -I+ @render.opt -o c_%s.dat -m light1 -m light2 scene.oct <
         test.dat

       To generate a pair of images corresponding to these two lights' contri-
       butions:

         vwrays -ff -x 1024 -y 1024 -vf best.vf | rtcontrib -ffc `vwrays -d -x
         1024 -y 1024 -vf best.vf` @render.opt -o c_%s.pic -m light1 -m light2
         scene.oct

       These images may then be recombined using the desired outputs of light1
       and light2:

         pcomb  -c  100  90  75  c_light1.pic  -c 50 55 57 c_light2.pic > com-
         bined.pic

       To compute an array of illuminance contributions according  to  a  Tre-
       genza sky:

         rtcontrib  -I+  -b  tbin  -o sky.dat -m skyglow -b 0 -o ground.dat -m
         groundglow @render.opt -f tregenza.cal scene.oct < test.dat


ENVIRONMENT

       RAYPATH        path to search for -f and -M files


AUTHOR

       Greg Ward


SEE ALSO

       cnt(1), getinfo(1), pcomb(1), pfilt(1), ra_rgbe(1), rcalc(1), rpict(1),
       rtrace(1), vwrays(1), ximage(1)



RADIANCE                            5/25/05                       RTCONTRIB(1)

Man(1) output converted with man2html