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)

                 w    weight

                 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

                 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.  Spawned rays are indented one tab for each level.

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

       --ttee _m_a_t   Append _m_a_t 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_a_t 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 the 't' option has been given  as
                 part of the output specifier.  Any number of excluded materi-
                 als may be given, but each must appear in a separate  option.

       --ttii _m_a_t   Add _m_a_t to the trace include list, so that it will be consid-
                 ered during the indirect calculation.  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 materials to be excluded from _f_i_l_e_.
                 The RAYPATH environment variable determines which directories
                 are searched for this file.  The material names are separated
                 by white space in the file.

       --ttII _f_i_l_e  Same as _-_t_i_, except read materials 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.

       --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
                 useful 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.)

       --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
                 computation.  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_a_t   Append  _m_a_t  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_a_t as its modifier will get
                 the  default  ambient  level  rather than a calculated value.
                 Any number of excluded materials may be given, but each  must
                 appear in a separate option.

       --aaii _m_a_t   Add  _m_a_t 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 materials to be excluded from _f_i_l_e_.
                 The RAYPATH environment variable determines which directories
                 are searched for this file.  The material names are separated
                 by white space in the file.

       --aaII _f_i_l_e  Same as _-_a_i_, except read materials 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_.

       --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 final contribution a ray
                 would  have  to  the image.  If it is less then the specified
                 minimum, the ray is not traced.

       --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.pic  |  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.pic  |  rtrace  -fda  `vwrays  -d  scene.pic`  -os
         scene.oct

       To compute an image with an unusual view mapping:

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

EENNVVIIRROONNMMEENNTT
       RAYPATH        the directories to check for auxiliary files.

FFIILLEESS
       /usr/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), rvu(1), vwrays(1), ximage(1)



RADIANCE                           10/17/97                          RTRACE(1)
