xenial (1) oconv.1.gz

Provided by: radiance_4R1+20120125-1.1_amd64 bug

NAME

       oconv - create an octree from a RADIANCE scene description

SYNOPSIS

       oconv [ -i octree | -b xmin ymin zmin size ][ -n objlim ][ -r maxres ][ -f ][ -w ][ - ] [ input ..  ]

DESCRIPTION

       Oconv  adds  each  scene  description  input to octree and sends the result to the standard output.  Each
       input can be either a file name, or a command (enclosed in quotes and preceded by a `!').  Similarly, the
       octree input may be given as a command preceded by a `!'.  If any of the surfaces will not fit in octree,
       an error message is printed and the program aborts.  If no octree is given, a new one  is  created  large
       enough for all of the surfaces.

       The  -b  option  allows  the  user  to give a bounding cube for the scene, starting at xmin ymin zmin and
       having a side length size.  If the cube does not contain all of the surfaces, an error results.   The  -b
       and -i options are mutually exclusive.

       The  -n  option  specifies the maximum surface set size for each voxel.  Larger numbers result in quicker
       octree generation, but potentially slower rendering.  Smaller  values  may  or  may  not  produce  faster
       renderings, since the default number (6) is close to optimal for most scenes.

       The -r option specifies the maximum octree resolution.  This should be greater than or equal to the ratio
       of the largest and smallest dimensions in the scene (ie. surface size or distance between surfaces).  The
       default is 16384.

       The  -f option produces a frozen octree containing all the scene information.  Normally, only a reference
       to the scene files is stored in the octree, and changes to those files may invalidate  the  result.   The
       freeze  option  is  useful  when the octree file's integrity and loading speed is more important than its
       size, or when the octree is to be relocated to another directory, and is especially useful  for  creating
       library  objects  for  the  "instance" primitive type.  If the input octree is frozen, the output will be
       also.

       The -w option suppresses warnings.

       A hyphen by itself ('-') tells oconv to read scene data from its standard input.  This also  implies  the
       -f option.

       The  only  scene  file  changes  that do not require octree regeneration are modifications to non-surface
       parameters.  If the coordinates of a surface are changed, or any primitives are added or  deleted,  oconv
       must  be  run  again.   Programs  will  abort  with a "stale octree" message if they detect any dangerous
       inconsistencies between the octree and the input files.

       Although the octree file format is binary, it is  meant  to  be  portable  between  machines.   The  only
       limitation  is that machines with radically different integer sizes will not work together.  For the best
       results, the -f option should be used if an octree is to be used in different environments.

DIAGNOSTICS

       There are four basic error types reported by oconv:

              warning - a non-fatal input-related error

              fatal - an unrecoverable input-related error

              system - a system-related error

              internal - a fatal error related to program limitations

              consistency - a program-caused error

       Most errors are self-explanatory.  However, the following internal errors should be mentioned:

       Too many scene files
              Reduce the number of scene files by combining them or using calls  to  xform(1)  within  files  to
              create a hierarchy.

       Set overflow in addobject (id)
              This  error occurs when too many surfaces are close together in a scene.  Either too many surfaces
              are lying right on top of each other, or the bounding cube is inflated from an oversized object or
              an  improper  -b specification.  If hundreds of triangles come together at a common vertex, it may
              not be possible to create an octree from the object.  This  happens  most  often  when  inane  CAD
              systems  create  spheres using a polar tessellation.  Chances are, the surface "id" is near one of
              those causing the problem.

       Hash table overflow in fullnode
              This error is caused by too many surfaces.  If it is possible to create an octree for the scene at
              all, it will have to be done in stages using the -i option.

EXAMPLE

       To add book1, book2 and a transformed book3 to the octree ``scene.oct'':

         oconv -i scene.oct book1 book2 '\!xform -rz 30 book3' > newscene.oct

AUTHOR

       Greg Ward

NOTES

       In  the  octree,  the  names of the scene files are stored rather than the scene information.  This means
       that a new octree must be generated whenever the scene files are changed or moved.  Also, an octree  that
       has  been  moved  to  a  new directory will not be able to find scene files with relative pathnames.  The
       freeze option avoids these problems.  make(1) or rad(1) can be  used  to  automate  octree  creation  and
       maintenance.

SEE ALSO

       getbbox(1), getinfo(1), make(1), obj2mesh(1), rad(1), rpict(1), rvu(1), rtrace(1), xform(1)