RTRACE(1)                                                            RTRACE(1)



NNAAMMEE
       rtrace - trace rays in RADIANCE scene

SSYYNNOOPPSSIISS
       rrttrraaccee [ ooppttiioonnss ] [ $$EEVVAARR ] [ @@ffiillee ] ooccttrreeee
       rrttrraaccee [[ ooppttiioonnss ]] --ddeeffaauullttss

DDEESSCCRRIIPPTTIIOONN
       _R_t_r_a_c_e  traces  rays from the standard input through the RADIANCE scene
       given by _o_c_t_r_e_e and sends the results to  the  standard  output.   (The
       octree  may  be given as the output of a command enclosed in quotes and
       preceded by a `!'.)  Input for each ray is:

            xorg yorg zorg xdir ydir zdir

       If the direction vector is (0,0,0), a bogus record is printed  and  the
       output  is flushed if the _-_x value is unset or zero.  (See the notes on
       this option below.)  This may be useful for programs that run _r_t_r_a_c_e as
       a  separate  process.   In  the second form, the default values for the
       options (modified by those options present) are printed  with  a  brief
       explanation.

       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.  Most
       options are followed by one or more arguments, which must be  separated
       from  the option and each other by white space.  The exceptions to this
       rule are the boolean options.  Normally, the appearance  of  a  boolean
       option  causes  a feature to be "toggled", that is switched from off to
       on or on to off depending on its previous state.  Boolean  options  may
       also be set explicitly by following them immediately with a '+' or '-',
       meaning on or off, respectively.  Synonyms for '+' are any of the char-
       acters "yYtT1", and synonyms for '-' are any of the characters "nNfF0".
       All other characters will generate an error.

       --ff_i_o      Format input according to the character _i and output  accord-
                 ing  to  the  character  _o_.  _R_t_r_a_c_e understands the following
                 input and output formats:  'a' for ascii, 'f' for single-pre-
                 cision  floating point, and 'd' for double-precision floating
                 point.  In addition to these three choices, the character 'c'
                 may  be used to denote 4-byte floating point (Radiance) color
                 format for the output of values only _(_-_o_v option, below).  If
                 the output character is missing, the input format is used.

                 Note that there is no space between this option and its argu-
                 ment.

       --oo_s_p_e_c    Produce output fields  according  to  _s_p_e_c_.   Characters  are
                 interpreted as follows:

                 o    origin (input)

                 d    direction (normalized)

                 v    value (radiance)

                 V    contribution (radiance)

                 w    weight

                 W    color coefficient

                 l    effective length of ray

                 L    first intersection distance

                 c    local (u,v) coordinates

                 p    point of intersection

                 n    normal at intersection (perturbed)

                 N    normal at intersection (unperturbed)

                 s    surface name

                 m    modifier name

                 M    material name

                 ~    tilde (end of trace marker)

                 If  the letter 't' appears in _s_p_e_c_, then the fields following
                 will be printed for every ray  traced,  not  just  the  final
                 result.   If  the capital letter 'T' is given instead of 't',
                 then all rays will be reported, including shadow testing rays
                 to light sources.  Spawned rays are indented one tab for each
                 level.  The tilde marker ('~') is a handy way of  differenti-
                 ating  the  final  ray value from daughter values in a traced
                 ray tree, and usually appears right before  the  't'  or  'T'
                 output  flags.  E.g., _-_o_v_~_T_m_W will emit a tilde followed by a
                 tab at the end of each trace, which  can  be  easily  distin-
                 guished even in binary output.

                 Note that there is no space between this option and its argu-
                 ment.

       --ttee _m_o_d   Append _m_o_d to the trace exclude list, so that it will not  be
                 reported  by  the  trace option _(_-_o_*_t_*_)_.  Any ray striking an
                 object having _m_o_d as its modifier will not be reported to the
                 standard output with the rest of the rays being traced.  This
                 option has no effect unless either the 't' or 'T' option  has
                 been  given  as  part of the output specifier.  Any number of
                 excluded modifiers may be given, but each must  appear  in  a
                 separate option.

       --ttii _m_o_d   Add  _m_o_d  to  the  trace  include  list,  so  that it will be
                 reported by the trace option.  The program can use either  an
                 include list or an exclude list, but not both.

       --ttEE _f_i_l_e  Same  as _-_t_e_, except read modifiers to be excluded from _f_i_l_e_.
                 The RAYPATH environment variable determines which directories
                 are searched for this file.  The modifier names are separated
                 by white space in the file.

       --ttII _f_i_l_e  Same as _-_t_i_, except read modifiers to be included from  _f_i_l_e_.

       --ii        Boolean  switch  to  compute  irradiance rather than radiance
                 values.  This only affects the final result,  substituting  a
                 Lambertian surface and multiplying the radiance by pi.  Glass
                 and other transparent surfaces are ignored during this stage.
                 Light  sources still appear with their original radiance val-
                 ues, though the _-_d_v option (below) may be  used  to  override
                 this.   This  option is especially useful in conjunction with
                 ximage(1) for computing illuminance at scene points.

       --uu        Boolean switch to control uncorrelated random sampling.  When
                 "off",  a  low-discrepancy  sequence  is  used, which reduces
                 variance but can result in a brushed appearance  in  specular
                 highlights.   When "on", pure Monte Carlo sampling is used in
                 all calculations.

       --II        Boolean switch to compute irradiance  rather  than  radiance,
                 with  the  input  origin and direction interpreted instead as
                 measurement point and orientation.

       --hh        Boolean switch for information header on output.

       --xx _r_e_s    Set the x resolution to _r_e_s_.   The  output  will  be  flushed
                 after  every  _r_e_s  input rays.  A value of zero means that no
                 output flushing will take place.

       --yy _r_e_s    Set the y resolution to _r_e_s_.  The program will exit after _r_e_s
                 scanlines have been processed, where a scanline is the number
                 of rays given by the _-_x option, or 1 if _-_x is zero.  A  value
                 of zero means the program will not halt until the end of file
                 is reached.

                 If both _-_x and _-_y options are given, a resolution  string  is
                 printed  at the beginning of the output.  This is mostly use-
                 ful for recovering image dimensions with _p_v_a_l_u_e_(_1_)_,  and  for
                 creating  valid Radiance picture files using the color output
                 format.  (See the _-_f option, above.)

       --nn _n_p_r_o_c  Execute in parallel on _n_p_r_o_c local processes.  This option is
                 incompatible  with  the  _-_P  and _-_P_P_, options.  Multiple pro-
                 cesses also do not work properly with ray tree  output  using
                 any  of the _-_o_*_t_* options.  There is no benefit from specify-
                 ing more processes than there are cores available on the sys-
                 tem or the _-_x setting, which forces a wait at each flush.

       --ddjj _f_r_a_c  Set  the  direct  jittering to _f_r_a_c_.  A value of zero samples
                 each source at specific sample points  (see  the  _-_d_s  option
                 below),  giving a smoother but somewhat less accurate render-
                 ing.  A positive value causes rays  to  be  distributed  over
                 each  source  sample according to its size, resulting in more
                 accurate penumbras.  This option should never be greater than
                 1,  and  may  even  cause problems (such as speckle) when the
                 value is smaller.  A warning about aiming failure will issued
                 if _f_r_a_c is too large.

       --ddss _f_r_a_c  Set  the  direct sampling ratio to _f_r_a_c_.  A light source will
                 be subdivided until the width of each sample area divided  by
                 the  distance  to  the illuminated point is below this ratio.
                 This assures accuracy in regions close to large area  sources
                 at  a  slight  computational  expense.  A value of zero turns
                 source subdivision off, sending at most  one  shadow  ray  to
                 each light source.

       --ddtt _f_r_a_c  Set  the  direct threshold to _f_r_a_c_.  Shadow testing will stop
                 when the potential contribution of at least the next  and  at
                 most  all  remaining light sources is less than this fraction
                 of the accumulated value.  (See the _-_d_c option  below.)   The
                 remaining light source contributions are approximated statis-
                 tically.  A value of zero means that all light  sources  will
                 be tested for shadow.

       --ddcc _f_r_a_c  Set  the direct certainty to _f_r_a_c_.  A value of one guarantees
                 that the absolute accuracy of the direct calculation will  be
                 equal  to or better than that given in the _-_d_t specification.
                 A value of zero only insures that all shadow lines  resulting
                 in  a contrast change greater than the _-_d_t specification will
                 be calculated.

       --ddrr _N     Set the number of relays for secondary sources to _N_.  A value
                 of  0  means that secondary sources will be ignored.  A value
                 of 1 means that sources will be made  into  first  generation
                 secondary  sources;  a value of 2 means that first generation
                 secondary sources will also be made  into  second  generation
                 secondary sources, and so on.

       --ddpp _D     Set  the  secondary source presampling density to D.  This is
                 the number of samples per steradian  that  will  be  used  to
                 determine  ahead of time whether or not it is worth following
                 shadow rays through all the reflections and/or  transmissions
                 associated  with a secondary source path.  A value of 0 means
                 that the full secondary source path will always be tested for
                 shadows if it is tested at all.

       --ddvv       Boolean switch for light source visibility.  With this switch
                 off, sources will be black when viewed directly although they
                 will  still  participate  in  the  direct  calculation.  This
                 option is mostly for the program _m_k_i_l_l_u_m_(_1_) to avoid inappro-
                 priate  counting  of light sources, but it may also be desir-
                 able in conjunction with the _-_i option.

       --ssjj _f_r_a_c  Set the specular sampling jitter to _f_r_a_c_.  This is the degree
                 to  which the highlights are sampled for rough specular mate-
                 rials.  A value of one means  that  all  highlights  will  be
                 fully sampled using distributed ray tracing.  A value of zero
                 means that no jittering will take place, and all  reflections
                 will appear sharp even when they should be diffuse.

       --sstt _f_r_a_c  Set  the  specular  sampling  threshold to _f_r_a_c_.  This is the
                 minimum fraction of reflection or transmission,  under  which
                 no  specular  sampling  is  performed.  A value of zero means
                 that highlights will always be sampled by  tracing  reflected
                 or transmitted rays.  A value of one means that specular sam-
                 pling is never used.   Highlights  from  light  sources  will
                 always  be  correct, but reflections from other surfaces will
                 be approximated using an ambient value.  A sampling threshold
                 between  zero and one offers a compromise between image accu-
                 racy and rendering time.

       --bbvv       Boolean switch for back face visibility.   With  this  switch
                 off,  back  faces  of opaque objects will be invisible to all
                 rays.  This is dangerous unless  the  model  was  constructed
                 such that all surface normals on opaque objects face outward.
                 Although turning off back face visibility does not save  much
                 computation  time  under most circumstances, it may be useful
                 as a tool for scene debugging, or  for  seeing  through  one-
                 sided  walls  from the outside.  This option has no effect on
                 transparent or translucent materials.

       --aavv _r_e_d _g_r_n _b_l_u
                 Set the ambient value to a radiance of _r_e_d _g_r_n _b_l_u _.  This is
                 the  final  value used in place of an indirect light calcula-
                 tion.  If the number of ambient bounces is one or greater and
                 the ambient value weight is non-zero (see _-_a_w and _-_a_b below),
                 this value may be modified by the computed indirect values to
                 improve overall accuracy.

       --aaww _N     Set  the  relative weight of the ambient value given with the
                 _-_a_v option to _N_.  As new indirect irradiances  are  computed,
                 they  will modify the default ambient value in a moving aver-
                 age, with the specified weight assigned to the initial  value
                 given  on  the  command and all other weights set to 1.  If a
                 value of 0 is given with this option, then the initial  ambi-
                 ent  value  is  never modified.  This is the safest value for
                 scenes with large differences in indirect contributions, such
                 as when both indoor and outdoor (daylight) areas are visible.

       --aabb _N     Set the number of ambient bounces to _N_.  This is the  maximum
                 number  of  diffuse bounces computed by the indirect calcula-
                 tion.  A value of zero implies no indirect calculation.

       --aarr _r_e_s   Set the ambient resolution to _r_e_s_.  This number  will  deter-
                 mine the maximum density of ambient values used in interpola-
                 tion.  Error will start to increase on surfaces spaced closer
                 than  the  scene size divided by the ambient resolution.  The
                 maximum ambient value density is the  scene  size  times  the
                 ambient  accuracy  (see  the _-_a_a option below) divided by the
                 ambient resolution.  The scene size can be  determined  using
                 _g_e_t_i_n_f_o_(_1_) with the _-_d option on the input octree.

       --aaaa _a_c_c   Set  the  ambient  accuracy to _a_c_c_.  This value will approxi-
                 mately equal the error from indirect  illuminance  interpola-
                 tion.  A value of zero implies no interpolation.

       --aadd _N     Set  the  number of ambient divisions to _N_.  The error in the
                 Monte Carlo  calculation  of  indirect  illuminance  will  be
                 inversely  proportional to the square root of this number.  A
                 value of zero implies no indirect calculation.

       --aass _N     Set the number of ambient super-samples to _N_.   Super-samples
                 are  applied  only to the ambient divisions which show a sig-
                 nificant change.

       --aaff _f_n_a_m_e Set the ambient file to _f_n_a_m_e_.  This is where indirect  illu-
                 minance  will  be  stored  and retrieved.  Normally, indirect
                 illuminance values are kept in memory and lost when the  pro-
                 gram  finishes  or  dies.  By using a file, different invoca-
                 tions can share illuminance values, saving time in the compu-
                 tation.   The ambient file is in a machine-independent binary
                 format which can be examined with _l_o_o_k_a_m_b_(_1_)_.

                 The ambient file may also be used as a means of communication
                 and  data sharing between simultaneously executing processes.
                 The same file may be used  by  multiple  processes,  possibly
                 running  on different machines and accessing the file via the
                 network (ie.  _n_f_s_(_4_)_)_.  The network lock manager _l_o_c_k_d_(_8_)  is
                 used to insure that this information is used consistently.

                 If  any  calculation  parameters  are changed or the scene is
                 modified, the old ambient file should be removed so that  the
                 calculation  can  start  over from scratch.  For convenience,
                 the original ambient parameters are listed in the  header  of
                 the  ambient  file.  _G_e_t_i_n_f_o_(_1_) may be used to print out this
                 information.

       --aaee _m_o_d   Append _m_o_d to the ambient exclude list, so that it  will  not
                 be  considered  during  the  indirect calculation.  This is a
                 hack for speeding the indirect computation by  ignoring  cer-
                 tain objects.  Any object having _m_o_d as its modifier will get
                 the default ambient level rather  than  a  calculated  value.
                 Any  number of excluded modifiers may be given, but each must
                 appear in a separate option.

       --aaii _m_o_d   Add _m_o_d to the ambient include list, so that it will be  con-
                 sidered during the indirect calculation.  The program can use
                 either an include list or an exclude list, but not both.

       --aaEE _f_i_l_e  Same as _-_a_e_, except read modifiers to be excluded from  _f_i_l_e_.
                 The RAYPATH environment variable determines which directories
                 are searched for this file.  The modifier names are separated
                 by white space in the file.

       --aaII _f_i_l_e  Same  as _-_a_i_, except read modifiers to be included from _f_i_l_e_.

       --mmee _r_e_x_t _g_e_x_t _b_e_x_t
                 Set the global medium extinction coefficient to the indicated
                 color,  in  units  of  1/distance  (distance in world coordi-
                 nates).  Light will be scattered or  absorbed  over  distance
                 according  to  this  value.  The ratio of scattering to total
                 scattering plus absorption is set by  the  albedo  parameter,
                 described below.

       --mmaa _r_a_l_b _g_a_l_b _b_a_l_b
                 Set the global medium albedo to the given value between 0 0 0
                 and 1 1 1.  A zero value means that all light not transmitted
                 by  the  medium  is absorbed.  A unitary value means that all
                 light not transmitted by the medium is scattered in some  new
                 direction.   The  isotropy of scattering is determined by the
                 Heyney-Greenstein parameter, described below.

       --mmgg _g_e_c_c  Set the medium Heyney-Greenstein  eccentricity  parameter  to
                 _g_e_c_c_.   This  parameter  determines  how  strongly scattering
                 favors the forward direction.  A value of  0  indicates  per-
                 fectly isotropic scattering.  As this parameter approaches 1,
                 scattering tends to prefer the forward direction.

       --mmss _s_a_m_p_d_i_s_t
                 Set the medium sampling distance to _s_a_m_p_d_i_s_t_, in world  coor-
                 dinate  units.   During  source  scattering, this will be the
                 average distance between adjacent  samples.   A  value  of  0
                 means  that  only  one  sample will be taken per light source
                 within a given scattering volume.

       --llrr _N     Limit reflections to a maximum of _N_, if N is a positive inte-
                 ger.  If _N is zero or negative, then Russian roulette is used
                 for ray termination, and the _-_l_w setting (below) must be pos-
                 itive.   If N is a negative integer, then this sets the upper
                 limit of reflections past  which  Russian  roulette  will  be
                 used.   In scenes with dielectrics and total internal reflec-
                 tion, a setting of 0 (no limit) may cause a stack overflow.

       --llww _f_r_a_c  Limit the weight of each ray to a minimum  of  _f_r_a_c_.   During
                 ray-tracing,  a  record is kept of the estimated contribution
                 (weight) a ray would have in the image.  If  this  weight  is
                 less  than  the specified minimum and the _-_l_r setting (above)
                 is positive, the  ray  is  not  traced.   Otherwise,  Russian
                 roulette is used to continue rays with a probability equal to
                 the ray weight divided by the given _f_r_a_c_.

       --lldd       Boolean switch to limit ray distance.  If this option is set,
                 then rays will only be traced as far as the magnitude of each
                 direction vector.  Otherwise, vector magnitude is ignored and
                 rays are traced to infinity.

       --ee _e_f_i_l_e  Send  error messages and progress reports to _e_f_i_l_e instead of
                 the standard error.

       --ww        Boolean switch to suppress warning messages.

       --PP _p_f_i_l_e  Execute in a persistent mode,  using  _p_f_i_l_e  as  the  control
                 file.  Persistent execution means that after reaching end-of-
                 file on its input, _r_t_r_a_c_e will fork a child process that will
                 wait  for  another  _r_t_r_a_c_e command with the same _-_P option to
                 attach to it.  (Note that since the rest of the command  line
                 options  will  be those of the original invocation, it is not
                 necessary to give any arguments  besides  _-_P  for  subsequent
                 calls.)   Killing  the  process  is achieved with the _k_i_l_l_(_1_)
                 command.  (The process ID in the first line of _p_f_i_l_e  may  be
                 used  to  identify  the waiting _r_t_r_a_c_e process.)  This option
                 may be used with the _-_f_r option of _p_i_n_t_e_r_p_(_1_)  to  avoid  the
                 cost of starting up _r_t_r_a_c_e many times.

       --PPPP _p_f_i_l_e Execute in continuous-forking persistent mode, using _p_f_i_l_e as
                 the control file.  The difference between this option and the
                 _-_P  option described above is the creation of multiple dupli-
                 cate processes to handle any number of attaches.   This  pro-
                 vides  a  simple  and reliable mechanism of memory sharing on
                 most multiprocessing platforms, since the _f_o_r_k_(_2_) system call
                 will share memory on a copy-on-write basis.

EEXXAAMMPPLLEESS
       To compute radiance values for the rays listed in samples.inp:

         rtrace -ov scene.oct < samples.inp > radiance.out

       To  compute  illuminance values at locations selected with the 't' com-
       mand of _x_i_m_a_g_e_(_1_)_:

         ximage  scene.hdr  |  rtrace  -h  -x  1  -i  scene.oct  |  rcalc   -e
         '$1=47.4*$1+120*$2+11.6*$3'

       To  record  the  object  identifier  corresponding  to each pixel in an
       image:

         vwrays  -fd  scene.hdr  |  rtrace  -fda  `vwrays  -d  scene.hdr`  -os
         scene.oct

       To compute an image with an unusual view mapping:

         cnt  480  640 | rcalc -e 'xr:640;yr:480' -f unusual_view.cal | rtrace
         -x 640 -y 480 -fac scene.oct > unusual.hdr

EENNVVIIRROONNMMEENNTT
       RAYPATH        the directories to check for auxiliary files.

FFIILLEESS
       /tmp/rtXXXXXX       common header information for picture sequence

DDIIAAGGNNOOSSTTIICCSS
       If the program terminates from an input related error, the exit  status
       will  be 1.  A system related error results in an exit status of 2.  If
       the program receives a signal that is caught, it will exit with a  sta-
       tus  of 3.  In each case, an error message will be printed to the stan-
       dard error, or to the file designated by the _-_e option.

AAUUTTHHOORR
       Greg Ward

SSEEEE AALLSSOO
       getinfo(1),  lookamb(1),  oconv(1),  pfilt(1),  pinterp(1),  pvalue(1),
       rpict(1), rtcontrib(1), rvu(1), vwrays(1), ximage(1)



RADIANCE                           10/17/97                          RTRACE(1)
