RHOLO(1)                                                              RHOLO(1)



NNAAMMEE
       rholo - generate/view a RADIANCE holodeck

SSYYNNOOPPSSIISS
       rrhhoolloo [ --nn nnpprr ][ --oo ddeevv ][ --ww ][ --ii ][ --ff | --rr ] hhddkkffiillee [ vvaarrffiillee || ++
       || -- [ VVAARR==vvaalluuee ....  ] ]

DDEESSCCRRIIPPTTIIOONN
       _R_h_o_l_o is a program for generating and viewing holodeck files.   Similar
       to  _r_v_u_(_1_)_,  _r_h_o_l_o  can compute views interactively, but unlike _r_v_u_, it
       reuses any and all information that was previously computed in this  or
       earlier runs using the given holodeck file, _h_d_k_f_i_l_e_.

       The  _-_n  option sets the number of _r_t_r_a_c_e_(_1_) processes to start for the
       calculation.  It defaults to zero, which means that no new rays will be
       calculated.   In  general,  it  is  unwise to start more processes than
       there are processors on the system.  On a multiprocessing system with 4
       or  more processors, a value one less than the total should yield opti-
       mal interactive rates on a lightly loaded system.

       The -o option sets the output device to use  for  display.   Currently,
       there  are  at least two display drivers available, _x_1_1 and _g_l_x_.  If no
       output device is specified, then _r_h_o_l_o will start a global  calculation
       of  the  holodeck,  filling  it in as time goes by.  The quality of the
       final holodeck will depend on how long _r_h_o_l_o runs before it  is  inter-
       rupted  or  runs  out  of file space or time, according to the variable
       settings described in the control variable section, below.  If no  out-
       put  device  and  no  processes  are  specified, _r_h_o_l_o creates an empty
       holodeck using the given _v_a_r_f_i_l_e_, if present.

       The _-_i option provides for reading from the standard input.  Without  a
       display  driver,  the input should consist only of views, which will be
       used to limit which parts of the holodeck are rendered in a batch  cal-
       culation.   With  a  display driver, most of the commands understood by
       the driver can be issued either from the operating window or the  stan-
       dard  input.   These  commands are described together with their window
       equivalents in the display driver section following the  control  vari-
       able section.

       The _-_f option permits the given holodeck to be clobbered.  Without this
       option, giving both the holodeck file and a variable file (or "-") will
       result  in  an  error message if the holodeck exists, since giving both
       implies that a new holodeck is being created.  (When reusing an  exist-
       ing  holodeck,  the variable values are taken from the holodeck header,
       though some may be overriden by giving a "+" in place of  the  variable
       file.)   Also,  attempts  to  clear  the holodeck using the interactive
       "clobber" command will be permitted only if the _-_f option is  given  on
       the initial command line.

       The _-_r option tells _r_h_o_l_o to open the holodeck file read-only, which is
       the default if there are no ray calculation processes.  If one or  more
       _r_t_r_a_c_e  processes  are  started with the _-_n option and the _-_r option is
       given or the specified holodeck is not writable by the user,  then  any
       additional  rays  computed  during the session will be discarded rather
       than saved to the holodeck file.

       One or more holodeck section boundaries are defined  along  with  other
       parameters  in  the holodeck file or, if the holodeck is being created,
       the _r_h_o_l_o control variable file,  _v_a_r_f_i_l_e_.   These  section  boundaries
       define  where you may move, or at least, where you will be able to see,
       since they determine where computed rays are stored.  Additional  vari-
       able  settings may be added or overridden on the command line following
       _v_a_r_f_i_l_e_.  If no _v_a_r_f_i_l_e is needed, a holodeck may still be  created  by
       giving a "-" on the command line in place of the variable file.  If you
       wish to override some of the variable settings in an existing holodeck,
       use  a  "+",  followed  by the new settings on the command line.  Upper
       case variables specified more than once will result in a  warning  mes-
       sage  (unless  the _-_w option is present), and the last value given will
       be the one used, unless it would conflict with something in an existing
       holodeck  that  cannot  be  changed,  such  as  the section boundaries.
       Changing section boundaries requires  creating  a  new  holodeck  using
       _r_h_o_l_o without a _-_n or _-_o option, then running _r_h_c_o_p_y_(_1_) to fill the new
       holodeck with the old holodeck's contents.

       The _-_w option turns off warnings about multiply and  misassigned  vari-
       ables.

       Rendering  variable  assignments  appear  one per line in _v_a_r_f_i_l_e_.  The
       name of the variable is followed  by  an  equals  sign  ('=')  and  its
       value(s).   The  end  of  line  may  be escaped with a backslash ('\'),
       though it is not usually necessary.  Variables that  should  have  only
       one  value  are  given in upper case.  Variables that may have multiple
       values are given in lower case.  Variables may be abbreviated by  their
       first three letters.  Comments in _v_a_r_f_i_l_e start with a pound sign ('#')
       and proceed to the end of line.

CCOONNTTRROOLL VVAARRIIAABBLLEESS
       The control variables, their interpretations  and  default  values  are
       given below.

       OOCCTTRREEEE    The name of the octree file.  The default name is the same as
                 _h_d_k_f_i_l_e but with any suffix replaced by ".oct".   This  vari-
                 able  may  also  be read from _r_a_d_(_1_) if the "RIF" variable is
                 set.  (See below.)

       RRIIFF       This variable specifies a _r_a_d input file to use as  a  source
                 of  rendering options and other variable settings.  If given,
                 _r_h_o_l_o will execute _r_a_d and get the rendering options to later
                 pass  to  _r_t_r_a_c_e_.   Besides  prepending  the _r_e_n_d_e_r variable,
                 _r_h_o_l_o will also  extract  default  settings  for  the  common
                 "OCTREE"  variable, and the "EYESEP" variable.  Following the
                 file name, overriding variable settings may be  given,  which
                 will  be  passed  to  _r_a_d on the command line.  Settings with
                 spaces in them should be enclosed in quotes.   The  execution
                 of _r_a_d will also update the contents of the octree, if neces-
                 sary.  There is no default value for this variable.

       EEYYEESSEEPP    The interocular spacing for stereo viewing.  I.e., the  world
                 distance  between  the  pupils  of  the  left and right eyes.
                 There is no default value for this variable.

       sseeccttiioonn   A section is a 6-sided parallel prism given by an origin  and
                 three  axis  vectors (i.e., 12 floating point values in world
                 coordinates).   The  axis  vectors  define  the  three  edges
                 attached  to  the origin vertex, and the other edges and ver-
                 tices are determined by  the  parallel  wall  constraint.   A
                 holodeck  section  is  a  region in which the user may freely
                 move about to obtain a view of what is outside  that  region.
                 In  object  rendering  mode,  a section may instead contain a
                 detailed object to be viewed  from  the  outside.   The  grid
                 dimensions  for  each  axis  may also be given by three addi-
                 tional integer arguments following the  prism  axes.   Other-
                 wise, if the grid dimensions are left out or any are unspeci-
                 fied or zero, the "GRID" variable will be used  to  determine
                 them  from  the section axis lengths.  (See below.)  There is
                 no default value for this variable, and it is  required.   If
                 multiple  values  are  given,  they will be used for multiple
                 rendering sections, which may or may not  be  connected,  but
                 should generally not overlap.  The starting view for interac-
                 tive display will be the center of the first  section  facing
                 the  positive  X  direction  unless  "OBSTRUCTIONS" is set to
                 True, when the view will be placed outside the first section.
                 (See  below  for this variable's definition.)  The third axis
                 of the first section is also used as the  default  "view  up"
                 vector.

       ggeeoommeettrryy  This  variable  is  used to associate geometry from an octree
                 file with one or more sections.  The specified octree will be
                 used  by  certain drivers (e.g., the "ogl" driver) to display
                 simplified geometry using hardware  lighting  during  motion.
                 If  this  variable is not set, such drivers will use the main
                 octree file, which contains all the scene geometry.  This can
                 be  slow  if the scene is complex, so use simplified geometry
                 with portals (described below) or specify a non-existent file
                 to turn geometry rendering off.  If there is just one setting
                 of this variable, it will be used for all sections.  If there
                 are  multiple settings, they will correspond to multiple sec-
                 tions.

       ppoorrttaallss   This variable is used to associate portal geometry  with  one
                 or more sections, as required for simplified geometry in some
                 drivers (e.g., "ogl").  The portal geometry itself  is  given
                 in one or more RADIANCE scene files or quoted commands begin-
                 ning with an exclamation mark ('!'), and the input may or may
                 not  include material definitons.  (I.e., the surfaces may be
                 modified by "void" if there are no materials.)  A  portal  is
                 an  imaginary surface that intervenes between a view and some
                 detailed geometry not included in the current section.   (See
                 the  "geometry"  variable  definition,  above.)   Portals are
                 often placed in doorways, windows and in  front  of  mirrors.
                 Portal geometry may also be placed around local geometry that
                 has been culled due to its complexity.  This specification is
                 necessary  in  order  that  the detail geometry be drawn cor-
                 rectly, and that mirrors will work  with  virtual  distances.
                 (See  the definition of "VDISTANCE," below.)  The orientation
                 of the portal surface  geometry  is  ignored,  so  they  have
                 effect no matter which way they are facing.  If there is just
                 one setting of this variable, it will be used  for  all  sec-
                 tions.   If there are multiple settings, they will correspond
                 to multiple sections.

       GGRRIIDD      The default section grid size in world  distance  units.   If
                 any  section axis grid is unspecified, the length of the axis
                 will be divided by this number and rounded  up  to  the  next
                 larger integer.  The grid size is a very important determiner
                 of holodeck performance, since the  holodeck  beam  index  is
                 proportional  to  average  axis  grid dimension to the fourth
                 power!  If the beam index is too large, poor file and  memory
                 performance will result.  If the beam index is too small, the
                 holodeck resolution will suffer  and  objects  will  tend  to
                 break  up.  In general, the grid size should divide each sec-
                 tion wall into 64 or fewer  cells  for  optimal  performance.
                 The  default  value  for this variable is the maximum section
                 axis length divided by 8.

       OOBBSSTTRRUUCCTTIIOONNSS
                 This boolean variable tells _r_h_o_l_o whether or not  to  compute
                 intersections  with  objects inside holodeck sections.  If it
                 is set to "False", then only  objects  outside  the  holodeck
                 sections  will be visible.  This is appropriate when you know
                 all sections to be devoid of geometry, or when some secondary
                 method  is  available for rendering geometry inside each sec-
                 tion.  If it is set to "True," all inside  geometry  will  be
                 visible.   There is no default for this variable, which means
                 that rays will  be  started  at  random  points  within  each
                 holodeck  section, allowing interior geometry to be partially
                 sampled.

       VVDDIISSTTAANNCCEE This boolean variable determines whether the actual  distance
                 to  objects  is  computed, or the virtual distance.  If it is
                 set to "True," the virtual distance will be used, which  will
                 make reflections and refractions through smooth, flat objects
                 clear, but will blur the boundaries of those  objects.   Note
                 that  some  drivers cannot render virtual samples without the
                 proper placement of "portals" in the scene.  (See  above  for
                 the  definition  of the "portals" variable.)  If it is set to
                 "False," the reflections and refractions will be blurred, but
                 object  boundaries  will remain sharp.  The default value for
                 this variable is "False."

       CCAACCHHEE     The memory cache size to use for ray samples during  interac-
                 tive  rendering,  in Megabytes.  This tuning parameter deter-
                 mines the tradeoff between memory use and  disk  access  time
                 for  interactive  display.  This value will not affect memory
                 use or performance for global holodeck rendering if there  is
                 no  display process.  The default cache is effectively set to
                 16 Megabytes.  If this variable is set to zero, no limit will
                 be placed on memory use and the process will grow to accommo-
                 date all the beams that have been accessed.

       DDIISSKKSSPPAACCEE Specifies the maximum holodeck file size, in Megabytes.  Once
                 the  holodeck  file  reaches this size, _r_t_r_a_c_e will exit.  If
                 there is no display  process,  _r_h_o_l_o  will  also  exit.   The
                 default value for this variable is 0, which is interpreted as
                 no size limit.

       TTIIMMEE      Sets the maximum time to run rtrace, in decimal hours.  After
                 this  length  of time, _r_t_r_a_c_e will exit.  If there is no dis-
                 play process, _r_h_o_l_o will also exit.  If there  is  a  display
                 process,  and _r_t_r_a_c_e is restarted with the "restart" command,
                 then the time clock will be restarted as well.   The  default
                 value for this variable is 0, which is interpreted as no time
                 limit.

       RREEPPOORRTT    This variable may be used to specify a interval for  progress
                 reports  in  minutes.   If  this value is zero, then progress
                 reports will not be given in intervals, but a final report of
                 the  file size and fragmentation will be issued when the pro-
                 gram terminates, along with the number of  rays  and  packets
                 computed.  If a filename is given after the interval, it will
                 be used as the error file  for  reports  and  error  messages
                 instead of the standard error.  There is no default value for
                 this variable.

       rreennddeerr    This variable may be used to specify  additional  options  to
                 _r_t_r_a_c_e_.   These  options  will  appear  after the options set
                 automatically by _r_a_d_, and thus will override the default val-
                 ues.

DDIISSPPLLAAYY DDRRIIVVEERR
       _R_h_o_l_o may be started in interactive mode using the _-_o option to specify
       an output display driver.  Currently, three drivers  are  supported  on
       most machines, _g_l_x_, _o_g_l and _x_1_1_.  (In addition, there are variations on
       the first two drivers for stereo displays, local objects and human tone
       mapping.   These are accessed with some combination of the 's', 'o' and
       'h' suffixes, always in that order.  E.g.,  the  OpenGL  stereo  driver
       with  human tone mapping would be "oglsh".)  Each driver accepts simple
       one-character commands and mouse view control in its operating  window.
       If  the  _-_i  option is also given, then the driver will also listen for
       commands entered on the standard input.  (It is unwise to  use  the  _-_i
       option  when rholo is run in the background, because it will occassion-
       ally stop the process when input is available on the controlling termi-
       nal.)   The  commands and their single-key window equivalents are given
       below.

       VVIIEEWW==    ((mmoouussee))
                 Modify the current view with the specified parameters.   (See
                 the  _-_v_* view options in the _r_p_i_c_t_(_1_) manual page for parame-
                 ter details.)  There is no one-character equivalent for  this
                 command in the display window.  Instead, the mouse is used to
                 control the current view in the following ways:

                 CONTROL   MOUSE     ACTION
                 (none)    left Move forward towards cursor position
                 (none)    middle    Rotate in place (usually safe)
                 (none)    right     Move backward away from cursor position
                 shift     left Orbit left around cursor position
                 shift     middle    Orbit skyward
                 cntl middle    Orbit earthward
                 shift     right     Orbit right around cursor position
                 cntl+shift     any       Frame focus by dragging rectangle

                 For all movements but rotating in place, the cursor  must  be
                 placed  over  some  bit  of  visible  geometry, otherwise the
                 driver has no reference point from which to work.  It is best
                 to just experiment with these controls until you learn to fly
                 safely in your model.  And  if  you  run  into  trouble,  the
                 "last" command is very useful.  (See below.)

       llaasstt    ''ll''
                 Return  to the previous view.  Some drivers will save up mul-
                 tiple views in a history, but you  are  guaranteed  at  least
                 one.

       wwhheerree    ''vv''
                 Print  the  current  view  parameters to the standard output.
                 This is useful for finding out where you are, or  for  saving
                 specific views in a keyframe file for animations or returning
                 to later.

       ffrraammee     ''ff''
                 Change the calculation focus.   If  the  "frame"  command  is
                 given  with no arguments on the standard input, it is equiva-
                 lent to the interactive 'F' command, which releases the  cur-
                 rent  calculation  focus.  If the "frame" command is followed
                 by a relative horizontal and vertical position (specified  as
                 floating point values between 0 and 1), then the new focus is
                 about this position on the screen (where 0 0 is at the  lower
                 left  of the display).  This is equivalent to the interactive
                 'f' command, which sets the focus about  the  current  window
                 cursor  position.   If  four  relative coordinates are given,
                 they are assumed to mean the minimum horizontal and  vertical
                 positon, and the maximum horizontal and vertical position, in
                 that order.  This is equivalent to dragging the mouse over  a
                 rectangular area with the 'cntl+shift' keys held down.

       ppaauussee    ''pp''
                 Pause the ray calculation temporarily.

       rreessuummee    <<ccrr>>
                 Resume the ray calculation.

       rreeddrraaww    ^^LL
                 Redraw  the current view from values calculated and stored in
                 the holodeck.  When executed  from  the  display  window  via
                 '^L',  the effect may be slightly different, since all stored
                 information will be flushed.

       kkiillll    ''KK''
                 Terminate the  ray  calculation  process.   This  is  usually
                 unnecessary,  but  is  provided  for special purpose applica-
                 tions.

       rreessttaarrtt    ''RR''
                 Restart the ray calculation process.  If the  "RIF"  variable
                 has been set, _r_a_d will be run first to assure that the octree
                 is up to date.

       cclloobbbbeerr    ''CC''
                 Clobber the holodeck contents, deleting  all  that  has  been
                 calculated before.  To get an interactive dissolve of changes
                 to the scene description, use the sequence "kill," "clobber,"
                 "restart."   This command will be honored by _r_h_o_l_o only if it
                 was started with the _-_f option.

       qquuiitt    ''qq''
                 Quit _r_h_o_l_o_.  The ray tracing calculation  is  terminated  and
                 all  values  are  flushed  to the holodeck file.  This is the
                 normal way to exit the program.

       In addition to these standard commands, all drivers offer the following
       supplimentary controls.

       ''hh''       Fix  the head height.  All mouse-controlled view motions will
                 be adjusted so that the head height does  not  change  (where
                 vertical is determined by the current view up vector).

       ''HH''       Release  the  head height, allowing it to change again during
                 mouse-controlled movements.

       ^^RR        Redraw the current view, recomputing the tone mapping in  the
                 process.   This is useful if the current view is too light or
                 too dark.  (On an 8-bit  display,  it  may  be  necessary  to
                 redraw  the screen a couple of times to get the best image.)
                 The "^L" command is a stronger type of redraw, since it  will
                 use  only rays in the current view to determine the tone map-
                 ping, rather than a history of  rays  drawn  from  the  _r_h_o_l_o
                 server.

EEXXAAMMPPLLEESS
       The following shows a minimal holodeck control variable file:


          RIF= sample.rif                       # rad input file
          section= 2 2 4  5 0 0  0 7 0  0 0 3   # section prism boundaries

       Technically,  the  "RIF"  setting is not necessary, but the results are
       much better when _r_h_o_l_o is used in association with _r_a_d to  control  the
       rendering parameters.

       Here is a slightly more sophisticated example:


          RIF=electric.rif
          section= 7 4 3.5  15 0 0  0 10 0  0 0 5
          GRID= .75
          CACHE= 20 # cache size in megabytes
          TIME= 120 # maximum time in hours
          DISK= 200 # maximum file size in megabytes
          REPORT= 60 elect.her
          OBST= False
          VDIST= False

       We  can  invoke _r_h_o_l_o on the above file to compute a hologram overnight
       in batch mode:

         rholo -n 1 elect.hdk elect.hif TIME=12 &

       This will report progress every hour to "elect.her".

       The next morning, we can look at the holodeck interactively:

         rholo-n 1 -o x11 elect.hdk &

       If the previous command were still running,  the  above  command  would
       fail  because  the  permissions on the holodeck would not grant access.
       To terminate _r_h_o_l_o without losing any  computed  information,  use  the
       _k_i_l_l_(_1_)  command  to send an interrupt or terminate signal to the _r_h_o_l_o
       process listed by _p_s_(_1_)_.  If the system goes  down  or  something  dire
       happens  to _r_h_o_l_o_, it may be necessary to restore read/write permission
       on the holodeck using _c_h_m_o_d_(_1_)_.  Do not do this,  however,  unless  you
       are  absolutely  sure  that _r_h_o_l_o is no longer running on the holodeck.
       (See the _p_s man page on how to check for running processes.   The  file
       modification date as reported by _l_s_(_1_) is another clue.)

       To  view the holodeck without invoking a new ray calculation, leave off
       the _-_n option.  To compute the holodeck with multiple  processes  on  a
       multiprocessing  system, use a higher number for the _-_n option.  (Don't
       use more processes than you have  processors,  though,  because  you'll
       only slow things down.)

       To allow interactive control of _r_h_o_l_o from another process, the follow-
       ing invocation will  override  the  file  size  limit  and  permit  the
       holodeck to be clobbered by a command entered on the standard input:

         rholo -n 1 -o x11 -i -f elect.hdk + DISK=0

       To create an empty holodeck from settings on the command line:

         rholo new.hdk - RIF=sample.rif "section=2 2 4  8 0 0  0 10 0  0 0 3"

NNOOTTEESS
       Each  time  rays  are  added  to  a  beam,  that beam's position in the
       holodeck file is released and a new position is found.  After  substan-
       tial  computation  on  a  holodeck,  especially  over several runs, the
       holodeck file may become fragmented, leaving holes that take  up  space
       without  contributing useful information.  The percentage fragmentation
       is reported when the REPORT variable is set and  some  calculation  has
       taken place.  When this percentage gets high on a large holodeck (above
       15% or so), it is a good idea to run  the  _r_h_o_p_t_i_m_i_z_e_(_1_)  program  once
       batch  rendering  is  complete to close the gaps and collect beams into
       groups for quicker rendering access.  Rholo will print  periodic  warn-
       ings when the fragmentation exceeds 20%.

AAUUTTHHOORR
       Greg Ward Larson

AACCKKNNOOWWLLEEDDGGMMEENNTT
       This work was supported by Silicon Graphics, Inc.

BBUUGGSS
       Global participating media are not handled correctly, though local par-
       ticipating media will usually work.

SSEEEE AALLSSOO
       chmod(1), ls(1),  ps(1),  rad(1),  ranimate(1),  rhcopy(1),  rhinfo(1),
       rhoptimize(1), rhpict(1), rpict(1), rtrace(1), rvu(1)



RADIANCE                            1/14/99                           RHOLO(1)
