Radiance rpict program



RPICT(1)                                                              RPICT(1)




NAME

       rpict - generate a RADIANCE picture


SYNOPSIS

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


DESCRIPTION

       Rpict  generates  a picture from the RADIANCE scene given in octree and
       sends it to the standard output.  If no octree is given,  the  standard
       input  is  read.   (The octree may also be specified as the output of a
       command enclosed in quotes and preceded by a `!'.)  Options specify the
       viewing parameters as well as giving some control over the calculation.
       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.

       In the second form shown above, the  default  values  for  the  options
       (modified  by  those options present) are printed with a brief explana-
       tion.

       Most options are followed by one or more arguments, which must be sepa-
       rated from the option and each other by white space.  The exceptions to
       this rule are the -vt option and 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.   Syn-
       onyms  for  '+' are any of the characters "yYtT1", and synonyms for '-'
       are any of the characters "nNfF0".  All other characters will  generate
       an error.

       -vtt      Set  view  type  to  t.   If  t is 'v', a perspective view is
                 selected.  If t is 'l', a parallel view is used.  A cylindri-
                 cal  panorma  may be selected by setting t to the letter 'c'.
                 This view is like a standard perspective vertically, but pro-
                 jected  on  a  cylinder  horizontally  (like  a soupcan's-eye
                 view).  Two fisheye views are provided as well; 'h' yields  a
                 hemispherical fisheye view and 'a' results in angular fisheye
                 distortion.  A hemispherical fisheye is a projection  of  the
                 hemisphere  onto  a  circle.  The maximum view angle for this
                 type is 180 degrees.  An angular fisheye view is defined such
                 that distance from the center of the image is proportional to
                 the angle from the central view direction.  An angular  fish-
                 eye  can  display  a full 360 degrees.  Note that there is no
                 space between the view type  option  and  its  single  letter
                 argument.

       -vp x y z Set  the  view point to x y z .  This is the focal point of a
                 perspective view or the center of a parallel projection.

       -vd xd yd zd
                 Set the view direction vector to xd yd zd .   The  length  of
                 this vector indicates the focal distance as needed by the -pd
                 option, described below.

       -vu xd yd zd
                 Set the view up vector (vertical direction) to xd yd zd .

       -vh val   Set the view horizontal size to val.  For a perspective  pro-
                 jection  (including  fisheye  views),  val  is the horizontal
                 field of view (in degrees).  For a parallel  projection,  val
                 is the view width in world coordinates.

       -vv val   Set the view vertical size to val.

       -vo val   Set  the  view  fore clipping plane at a distance of val from
                 the view point.  The plane will be perpendicular to the  view
                 direction for perspective and parallel view types.  For fish-
                 eye view types, the clipping plane  is  actually  a  clipping
                 sphere,  centered on the view point with radius val.  Objects
                 in front of this imaginary surface will not be visible.  This
                 may  be useful for seeing through walls (to get a longer per-
                 spective from an exterior view point) or for incremental ren-
                 dering.   A  value of zero implies no foreground clipping.  A
                 negative value produces some interesting  effects,  since  it
                 creates  an  inverted image for objects behind the viewpoint.
                 This possibility is provided mostly for the purpose  of  ren-
                 dering stereographic holograms.

       -va val   Set the view aft clipping plane at a distance of val from the
                 view point.  Like the view fore plane, it will be perpendicu-
                 lar  to  the view direction for perspective and parallel view
                 types.  For fisheye view types, the clipping plane  is  actu-
                 ally  a  clipping  sphere,  centered  on  the view point with
                 radius val.  Objects behind this imaginary surface  will  not
                 be  visible.   A  value of zero means no aft clipping, and is
                 the only way to see infinitely distant objects  such  as  the
                 sky.

       -vs val   Set  the  view  shift  to val.  This is the amount the actual
                 image will be shifted to the right  of  the  specified  view.
                 This  is  option is useful for generating skewed perspectives
                 or rendering an image a piece at a time.  A value of 1  means
                 that  the rendered image starts just to the right of the nor-
                 mal view.  A value of -1 would be to  the  left.   Larger  or
                 fractional values are permitted as well.

       -vl val   Set  the  view  lift  to  val.  This is the amount the actual
                 image will be lifted up from the specified view,  similar  to
                 the -vs option.

       -vf file  Get  view  parameters  from file, which may be a picture or a
                 file created by rvu (with the "view" command).

       -x res    Set the maximum x resolution to res.

       -y res    Set the maximum y resolution to res.

       -pa rat   Set the pixel  aspect  ratio  (height  over  width)  to  rat.
                 Either  the x or the y resolution will be reduced so that the
                 pixels have this ratio for the specified  view.   If  rat  is
                 zero,  then  the x and y resolutions will adhere to the given
                 maxima.

       -ps size  Set the pixel sample spacing to the integer size.  This spec-
                 ifies the sample spacing (in pixels) for adaptive subdivision
                 on the image plane.

       -pt frac  Set the pixel sample tolerance to frac.  If two samples  dif-
                 fer by more than this amount, a third sample is taken between
                 them.

       -pj frac  Set the pixel sample jitter to frac.  Distributed ray-tracing
                 performs  anti-aliasing  by randomly sampling over pixels.  A
                 value of one will randomly distribute samples over full  pix-
                 els.   A  value  of zero samples pixel centers only.  A value
                 between zero and  one  is  usually  best  for  low-resolution
                 images.

       -pm frac  Set  the pixel motion blur to frac.  In an animated sequence,
                 the exact view will be blurred between the previous view  and
                 the  next view as though a shutter were open this fraction of
                 a  frame  time.   (See  the  -S  option  regarding   animated
                 sequences.)   The first view will be blurred according to the
                 difference between the initial view set on the  command  line
                 and  the first view taken from the standard input.  It is not
                 advisable  to  use  this  option  in  combination  with   the
                 pmblur(1)  program,  since  one takes the place of the other.
                 However, it may improve results with pmblur  to  use  a  very
                 small  fraction  with  the  -pm option, to avoid the ghosting
                 effect of too few time samples.

       -pd dia   Set the pixel depth-of-field aperture to a  diameter  of  dia
                 (in  world  coordinates).   This  will be used in conjunction
                 with the view focal distance, indicated by the length of  the
                 view  direction  vector  given  in the -vd option.  It is not
                 advisable to use this option in  combination  with  the  pdf-
                 blur(1)  program,  since  one  takes  the place of the other.
                 However, it may improve results with pdfblur to  use  a  very
                 small  fraction  with  the  -pd option, to avoid the ghosting
                 effect of too few samples.

       -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  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 frac is too large.  It is usually wise to turn  off  image
                 sampling when using direct jitter by setting -ps to 1.

       -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  source samples is less than this
                 fraction of the  accumulated  value.   (See  the  -dc  option
                 below.)  The remaining light source contributions are approx-
                 imated statistically.  A value of zero means that  all  light
                 source samples 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 may be desirable in conjunction with the -i option  so
                 that light sources do not appear in the output.

       -sj frac  Set the specular sampling jitter to frac.  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.  This may
                 be  desirable  when  used  in combination with image sampling
                 (see -ps option above) to obtain faster renderings.

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

       -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  calcula-
                 tion.  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  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.

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

       -ar res   Set  the  ambient resolution to res.  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 -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.   A  value
                 of zero is interpreted as unlimited resolution.

       -aa acc   Set  the  ambient  accuracy to acc.  This value will approxi-
                 mately equal the error from indirect  illuminance  interpola-
                 tion.  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 sig-
                 nificant change.

       -af fname Set the ambient file to fname.  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.  Also, by creating an ambient file during a low reso-
                 lution rendering, better results can be obtained in a  second
                 high resolution pass.  The ambient file is in a machine-inde-
                 pendent binary format which may 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 cer-
                 tain 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 con-
                 sidered 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  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.

       -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 per-
                 fectly 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 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.

       -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 val-
                 ues, though the -dv option (above) may be  used  to  override
                 this.

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

       -lr N     Limit reflections to a maximum of N.  If N is zero, then Rus-
                 sian roulette is used for ray termination, and the  -lw  set-
                 ting  (below)  must be positive.  If N is a negative integer,
                 then this sets the upper limit of reflections past which Rus-
                 sian  roulette  will not 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.

       -S seqstart
                 Instead of generating a single picture based only on the view
                 parameters given on the  command  line,  this  option  causes
                 rpict  to  read  view options from the standard input and for
                 each line containing a valid view specification,  generate  a
                 corresponding picture.  This option is most useful for gener-
                 ating animated sequences, though it may also be used to  con-
                 trol rpict from a remote process for network-distributed ren-
                 dering.  Seqstart is a positive integer that will be  associ-
                 ated with the first output frame, and incremented for succes-
                 sive output frames.  By default, each frame  is  concatenated
                 to  the  output  stream,  but  it  is possible to change this
                 action using  the  -o  option  (described  below).   Multiple
                 frames   may   be  later  extracted  from  the  output  using
                 ra_rgbe(1).

                 Note that the octree may not be read from the standard  input
                 when using this option.

       -o fspec  Send  the picture(s) to the file(s) given by fspec instead of
                 the standard output.  If this option is used  in  combination
                 with  -S  and  fspec  contains an integer field for printf(3)
                 (eg. "%03d") then the actual output file  name  will  include
                 the  current  frame  number.   Rpict will not allow a picture
                 file to be clobbered (overwritten) with this option.   If  an
                 image  in  a  sequence already exists (-S option), rpict will
                 skip until it reaches an image that doesn't, or  the  end  of
                 the  sequence.   This is useful for running rpict on multiple
                 machines or processors to render the same sequence,  as  each
                 process will skip to the next frame that needs rendering.

       -r fn     Recover  pixel  information from the file fn.  If the program
                 gets killed during picture generation, the information may be
                 recovered using this option.  The view parameters and picture
                 dimensions are also recovered from fn if possible.  The other
                 options  should be identical to those which created fn, or an
                 inconsistent picture may result.  If fn is identical  to  the
                 file  specification  given  with  the  -o  option, rpict will
                 rename the file prior to copying its contents.  This  insures
                 that the old file is not overwritten accidentally.  (See also
                 the -ro option, below.)

                 If fn is an integer and the recover option is used in  combi-
                 nation  with the -S option, then rpict skips a number of view
                 specifications on its input equal to the  difference  between
                 fn and seqstart.  Rpict then performs a recovery operation on
                 the file constructed from the frame number fn and the  output
                 file specification given with the -o option.  This provides a
                 convenient mechanism for  recovering  in  the  middle  of  an
                 aborted picture sequence.

                 The  recovered  file will be removed if the operation is suc-
                 cessful.  If the recover operation fails (due to lack of disk
                 space)  and  the  output file and recover file specifications
                 are the same, then the original information may be left in  a
                 renamed temporary file.  (See FILES section, below.)

       -ro fspec This option causes pixel information to be recovered from and
                 subsequently returned to the picture file fspec.  The  effect
                 is  the  same as specifying identical recover and output file
                 names with the -r and -o options.

       -z fspec  Write pixel distances out to the file fspec.  The values  are
                 written  as short floats, one per pixel in scanline order, as
                 required by pinterp(1).  Similar to the -o option, the actual
                 file name will be constructed using printf and the frame num-
                 ber from the -S option.  If used with the -r option, -z  also
                 recovers information from an aborted rendering.

       -P pfile  Execute  in  a  persistent  mode,  using pfile as the control
                 file.  This option must be used  together  with  -S,  and  is
                 incompatible with the recover option (-r).  Persistent execu-
                 tion means that after  reaching  end-of-file  on  its  input,
                 rpict  will  fork  a child process that will wait for another
                 rpict 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 rpict process.)  This option may be less useful  than
                 the -PP variation, explained below.

       -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 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 fork(2) system call
                 will  share memory on a copy-on-write basis.  This option may
                 be used with rpiece(1) to efficiently render a  single  image
                 using multiple processors on the same host.

       -t sec    Set  the  time  between  progress reports to sec.  A progress
                 report writes the number of rays traced, the percentage  com-
                 pleted, and the CPU usage to the standard error.  Reports are
                 given either automatically after the specified  interval,  or
                 when  the  process  receives  a  continue (-CONT) signal (see
                 kill(1)).  A value of zero turns automatic reporting off.

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

       -w        Boolean switch for warning messages.  The default is to print
                 warnings, so the first appearance of this option  turns  them
                 off.


EXAMPLE

       rpict -vp 10 5 3 -vd 1 -.5 0 scene.oct > scene.pic

       rpict -S 1 -o frame%02d.pic scene.oct < keyframes.vf


ENVIRONMENT

       RAYPATH        the directories to check for auxiliary files.


FILES

       /tmp/rtXXXXXX       common header information for picture sequence
       rfXXXXXX       temporary name for recover file


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


AUTHOR

       Greg Ward


SEE ALSO

       getinfo(1),  lookamb(1),  oconv(1),  pdfblur(1),  pfilt(1), pinterp(1),
       pmblur(1), printf(3), ra_rgbe(1), rad(1), rtrace(1), rvu(1)



RADIANCE                            2/26/99                           RPICT(1)

Man(1) output converted with man2html