xenial (1) rtrace.1.gz

Provided by: radiance_4R1+20120125-1.1_amd64 bug

NAME

       rtrace - trace rays in RADIANCE scene

SYNOPSIS

       rtrace [ options ] [ $EVAR ] [ @file ] octree
       rtrace [ options ] -defaults

DESCRIPTION

       Rtrace  traces  rays  from  the  standard  input through the RADIANCE scene given by octree 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 rtrace
       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 environment and/or read  from  a  file.   A
       command  argument beginning with a dollar 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 characters "yYtT1", and synonyms for '-' are any of the characters "nNfF0".  All other  characters
       will generate an error.

       -fio      Format  input  according  to  the  character i and output according to the character o.  Rtrace
                 understands the following input and output formats:  'a' for ascii,  'f'  for  single-precision
                 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 (-ov option, below).  If the output character is missing, the
                 input format is used.

                 Note that there is no space between this option and its argument.

       -ospec    Produce output fields according to spec.  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 spec, 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 differentiating 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., -ov~TmW will emit a tilde followed by a tab at the end of each
                 trace, which can be easily distinguished even in binary output.

                 Note that there is no space between this option and its argument.

       -te mod   Append mod to the trace exclude list, so that it will not  be  reported  by  the  trace  option
                 (-o*t*).   Any  ray  striking  an object having mod 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.

       -ti mod   Add mod 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.

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

       -tI file  Same as -ti, except read modifiers to be included from file.

       -i        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 values, though the -dv option (below) may be used  to  override  this.   This
                 option  is  especially  useful in conjunction with ximage(1) for computing illuminance at scene
                 points.

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

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

       -h        Boolean switch for information header on output.

       -x res    Set  the  x  resolution to res.  The output will be flushed after every res input rays if -y is
                 set to zero.  A value of one means that every ray will be flushed, whatever the setting of  -y.
                 A value of zero means that no output flushing will take place.

       -y res    Set  the  y  resolution to res.  The program will exit after res 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 pvalue(1), and for creating
                 valid Radiance picture files using the color output format.  (See the -f option, above.)

       -n nproc  Execute in parallel on nproc local processes.  This option is incompatible with the -P and -PP,
                 options.  Multiple processes also do not work properly with ray tree output using  any  of  the
                 -o*t*  options.   There  is  no  benefit  from  specifying  more processes than there are cores
                 available on the system or the -x setting, which forces a wait at each flush.

       -dj frac  Set the direct jittering to frac.  A value of zero  samples  each  source  at  specific  sample
                 points  (see  the -ds option below), giving a smoother but somewhat less accurate rendering.  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 frac is too large.

       -ds frac  Set  the  direct  sampling ratio to frac.  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.

       -dt frac  Set  the direct threshold to frac.  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 -dc option below.)  The remaining light source contributions are
                 approximated statistically.  A value of zero means that all light sources will  be  tested  for
                 shadow.

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

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

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

       -dv       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 mkillum(1) to avoid inappropriate counting of light sources, but it may
                 also be desirable in conjunction with the -i option.

       -ss samp  Set the specular sampling to samp.  For values less than 1, this is the  degree  to  which  the
                 highlights  are sampled for rough specular materials.  A value greater than one causes multiple
                 ray samples to be sent to reduce noise at a commmesurate cost.  A value of zero means  that  no
                 jittering  will  take  place,  and  all  reflections will appear sharp even when they should be
                 diffuse.

       -st frac  Set the specular sampling threshold to frac.  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  sampling  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 accuracy and
                 rendering time.

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

       -av red grn blu
                 Set  the ambient value to a radiance of red grn blu .  This is the final value used in place of
                 an indirect light calculation.  If the number of ambient bounces is  one  or  greater  and  the
                 ambient  value  weight  is  non-zero (see -aw and -ab below), this value may be modified by the
                 computed indirect values to improve overall accuracy.

       -aw N     Set the relative weight of the ambient value given with the -av option to N.  As  new  indirect
                 irradiances  are computed, they will modify the default ambient value in a moving average, 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 ambient 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.

       -ab N     Set the number of ambient bounces to N.  This is the maximum number of diffuse bounces computed
                 by the indirect calculation.  A value of zero implies no indirect calculation.

       -ar res   Set the ambient resolution to res.  This number will determine the maximum density  of  ambient
                 values  used in interpolation.  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 -aa option below) divided by the ambient resolution.
                 The scene size can be determined using getinfo(1) with the -d option on the input octree.

       -aa acc   Set the ambient accuracy to acc.  This value will approximately equal the error  from  indirect
                 illuminance interpolation.  A value of zero implies no interpolation.

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

       -as N     Set  the  number  of ambient super-samples to N.  Super-samples are applied only to the ambient
                 divisions which show a significant change.

       -af fname Set the ambient file to  fname.   This  is  where  indirect  illuminance  will  be  stored  and
                 retrieved.   Normally, indirect illuminance values are kept in memory and lost when the program
                 finishes or dies.  By using a file, different invocations can share illuminance values,  saving
                 time  in the computation.  The ambient file is in a machine-independent binary format which can
                 be examined with lookamb(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.   nfs(4)).   The
                 network lock manager lockd(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.  Getinfo(1) may be used to
                 print out this information.

       -ae mod   Append mod 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 certain objects.
                 Any object having mod 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.

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

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

       -aI file  Same as -ai, except read modifiers to be included from file.

       -me rext gext bext
                 Set  the  global  medium  extinction coefficient to the indicated color, in units of 1/distance
                 (distance in world coordinates).  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.

       -ma ralb galb balb
                 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.

       -mg gecc  Set the medium Heyney-Greenstein eccentricity parameter to gecc.  This parameter determines how
                 strongly scattering favors the forward direction.  A value of 0 indicates  perfectly  isotropic
                 scattering.  As this parameter approaches 1, scattering tends to prefer the forward direction.

       -ms sampdist
                 Set  the  medium  sampling  distance  to  sampdist,  in  world coordinate 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.

       -lr N     Limit  reflections  to  a  maximum of N, if N is a positive integer.  If N is zero or negative,
                 then Russian roulette is used for  ray  termination,  and  the  -lw  setting  (below)  must  be
                 positive.  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  reflection,  a
                 setting of 0 (no limit) may cause a stack overflow.

       -lw frac  Limit the weight of each ray to a minimum of frac.  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 -lr 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 frac.

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

       -e efile  Send error messages and progress reports to efile instead of the standard error.

       -w        Boolean switch to suppress warning messages.

       -P pfile  Execute in a persistent mode, using pfile as the control file.  Persistent execution means that
                 after reaching end-of-file on its input, rtrace will fork a child process that  will  wait  for
                 another  rtrace  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
                 kill(1) command.  (The process ID in the first line of  pfile  may  be  used  to  identify  the
                 waiting  rtrace  process.)   This option may be used with the -fr option of pinterp(1) to avoid
                 the cost of starting up rtrace many times.

       -PP pfile Execute in continuous-forking persistent mode, using pfile as the control file.  The difference
                 between  this  option  and  the -P option described above is the creation of multiple duplicate
                 processes to handle any number of attaches.  This provides a simple and reliable  mechanism  of
                 memory  sharing  on  most  multiprocessing  platforms, since the fork(2) system call will share
                 memory on a copy-on-write basis.

EXAMPLES

       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' command of ximage(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

ENVIRONMENT

       RAYPATH        the directories to check for auxiliary files.

FILES

       /tmp/rtXXXXXX       common header information for picture sequence

DIAGNOSTICS

       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
       status  of  3.   In  each  case,  an  error message will be printed to the standard error, or to the file
       designated by the -e option.

AUTHOR

       Greg Ward

SEE ALSO

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