C Sc 405/505 Assignment 4 
NFF Specification
for Ray Tracing
     NFF - Neutral File Format scene description language.

     The NFF (Neutral File Format) is designed as a minimal scene
     description  language.   The  language  was designed to test
     various rendering algorithms and efficiency schemes, and  is
     used to describe the geometry and basic surface characteris-
     tics of objects, the placement of lights,  and  the  viewing
     frustum for the eye.

     The NFF file format was initially designed  by  Eric  Haines
     for   use   with  the  SPD  (Standard  Procedural  Database)
     software, a package designed to create a  variety  of  data-
     bases  for  testing rendering schemes.  For more information
     about SPD see "A Proposal  for  Standard  Graphics  Environ-
     ments," IEEE Computer Graphics and Applications, vol. 7, no.
     11, November 1987, pp. 3-5.

     To enable NFF to describe volumetric  primitives,  a  simple
     extension has been added to the original design. An NFF file
     may contain the following:

          - A simple perspective frustum
          - A background color description
          - A positional light source description
          - A surface properties description
          - Geometric descriptions (polygons, spheres, cylinders)
          - Volumetric descriptions

     NFF files contain lines of text, separated  into  fields  by
     spaces  or  tab characters. For each entity, the first field
     defines its type.  The rest of the line and  possibly  other
     lines  contain  further  information  about  the entity. All
     colors are specified by RGB triples,  represented  by  three
     numbers  between  0  and  1.  Comment can be included in NFF
     files by enclosing the comments between matching pairs of /*
     */ or by preceding a comment by a # character and ending the
     comment with a newline character. The formats for the  vari-
     ous entities are explained below.

     1.1 Viewing frustrum

     Describes the viewing vectors and angles that  are  required
     to define the viewing frustrum. The format is:

          v from Fx Fy Fz at Ax Ay Az up Ux Uy Uz angle A  hither
          H resolution Rx Ry

     where Fx Fy Fz is the eye location, Ax Ay Az is the position
     that  is  to  be  the center of the image (i.e. what you are
     looking at), Ux Uy Uz is a vector defining  which  direction
     is up, A is the angle (in degrees) from the left edge of the
     image to the right edge, H is the  distance  to  the  hither
     plane  (this is not used in the cap_vol renderer), and Rx Ry
     is the resolution in pixels of the  image  to  be  produced.
     The  data are not assumed to be normalized (e.g. the from-at
     distance does not have to be  1).   Also,  vectors  are  not
     required  to  be perpendicular to each other.  A view entity
     must be defined before any objects are defined.

     1.2 Background

     Defines the background color to be used when  no  primitives
     are rendered for a given pixel. Its format is:

          b R G B,

     where R G B is a color specification. If no background color
     is given, a default of black (0,0,0) is used.

     1.3 Light source

     Defines a positional light source for the scene. Its  format

          l Px Py Pz [ R G B ],

     where Px Py Pz is the position of the light source and R G B
     is  an  optional  color  for  the light emitted by the light
     source.  All lights must be defined before any  objects  are
     defined.   Lights  emit  white  light (1,1,1) if no color is

     1.4 Surface definition

     Defines how each geometric primitive that follows this  sur-
     face definition will be shaded by the renderer. This surface
     definition is in effect until another surface definition  is
     encountered  or  the  end  of the input file is reached. Its
     format is:

          f R G B Kd Ks S T IR

     where R G B is the color of the surface, Kd is  the  diffuse
     reflectance  of  the surface, Ks is the specular reflectance
     of the surface, S is the shininess of the surface, T is  the
     transparency  of the surface, and IR is the index of refrac-
     tion of the surface. Usually, 0 <= Kd <= 1 and 0 <= Ks <= 1,
     though  it  is  not  required  that Kd + Ks = 1. The surface
     becomes more shiny as S increases, and it should  always  be
     greater  than  or equal to one. The transparency of the sur-
     face T should fall between 0 and 1, with  a  T  value  of  0
     being  an  opaque  object  and  a value of 1 being a totally
     transparent object. The index of refraction is  the  density
     of  the  surface  material and determines how much the light
     will bend at the interface  between  this  surface  and  the
     other  surfaces  in the scene.  In the cap_vol renderer, the
     adjacent surface is always considered to have  an  index  of
     refraction  of 1. In general, an index of refraction between
     0.5 and 2.0 provides a reasonable amount of refraction.

     1.5 Cone

     A cone is defined as having an axis defined  by  two  points
     (the base and apex of the cone), as well as a radius that is
     orthogonal to the axis at both the base and apex points. The
     apex  radius  is  defined  as  being  smaller  than the base
     radius.  Note that the surface exists without end caps.  The
     cone description is:

          c Bx By Bz Br Ax Ay Az Ar,

     where Bx By Bz is the base point of the cones  axis,  Br  is
     the  radius of the cones axis at the base point, Ax Ay Az is
     the apex point of the cones axis, and Ar is  the  radius  of
     the  cones  axis  at  the apex point. Note that the base and
     apex cannot be coincident for a cone.

     1.6 Sphere

     A sphere is defined by a center point and a radius. Its for-
     mat is:

          s Cx Cy Cz R,

     where Cx Cy Cz is the center point for the sphere, and R  is
     its radius.

     1.7 Polygon

     A polygon is defined by a set of three or more vertices. All
     points in the polygon, are assumed to be coplanar. The first
     two edges must form a non-zero convex  angle,  so  that  the
     normal  can be determined by using just the first three ver-
     tices. A polygon descriptions format is:

          p N P1x P1y P1z ... PNx PNy PNz,

     where N is the number of vertices in the  polygon,  and  the
     P1x  P1y  P1z  ...  PNx  PNy PNz are the N vertices for that

     1.8 Polygonal patch

     A patch is defined by a set of vertices and  their  normals.
     A  patch  is assumed to have all its vertices coplanar.  The
     first two edges must form a non-zero convex angle,  so  that
     the normal can be determined. A polygonal patch is used much
     like a polygon, except rather than using the polygon normal,
     the  normals  given for the vertices are interpolated across
     the polygon. This enables you to produce objects with smooth
     shading even though they are made out of polygonal geometry.
     The format for their description is:

          p N P1x P1y P1z N1x N1y N1z ...  PNx PNy  PNz  NNx  NNy

     where N is the number of vertices in the  polygon,  and  the
     P1x P1y P1z N1x N1y N1z ...  PNx PNy PNz NNx NNy NNz are the
     N vertices and normals for  that  polygon.  For  the  vol(1)
     renderer, N must be 3.

     1.9 Volume

     A volume is defined by  a  file  name,  an  optional  format
     string,  a  volume of space that the volume data occupies, a
     color and opacity map, as well as other optional parameters.
     The format for a volume is:

          voxel filename
          [ format formatstring ]
          origin Px Py Pz extent Ex Ey Ez

     where filename is the name of the  file  or  directory  that
     contains  the volume data, formatstring specifies the format
     of the volume data, Px Py Pz is the location of  the  origin
     of the volume in 3D space, and Ex Ey Ez is the extent in the
     x, y, and z dimensions that the volume occupies.  The volume
     attributes are zero or more of the following:

          color_map colorname
          opacity_map opacityname
          min_threshold min_value
          max_threshold max_value
          brightness bright
          remove_box origin Px Py Pz extent Ex Ey Ez,

     where colorname is the name of a color map file, opacityname
     is  the  name  of an opacity map file, min_value is a volume
     data value cut off below which all sample values  are  tran-
     sparent,  max_value  is  a  volume  data value cut off above
     which all sample values are transparent, bright is a bright-
     ness  scale  applied to the color of each volume sample, and
     Px Py Pz and Ex Ey Ez are the origin and  extent  of  a  box
     within   the   volume   in   which  all  sample  values  are

     The format of the volume data is specified  by  the  format-
     string  argument. The format string can specify either a raw
     floating point data format (raw(5)), a raw byte data  format
     (rawbyte(5)), the HDF format (hdf(5)), or the VoxelView for-
     mat (VoxelView(5)). Both the HDF and the  VovelView  formats
     contain  information  about  the  dimensions within the data
     files themselves, so the  format  strings  used  to  specify
     those  formats  are  ``hdf'' and ``voxelview'' respectively.
     The raw floating point and byte data sets require the dimen-
     sions  and possibly the range of the data values in the data
     set. Their format strings take the form ``rawXxYxZ N:M'' and
     ``rawbyteXxYxZ   N:M''  respectively,  where  X,  Y,  and  Z
     represent the dimensions of  the  data  set,  and  N  and  M
     represent  the  minimum  and maximum data values that are of
     interest within the data set.  For an example of the use  of
     this  type  of  format string, see the NFF data file for the
     CO2 data set provided with this distribution. The  NFF  file
     can be found in $PARVIS/data/co2.nff.

     1.10 Clipping planes

     All geometric and  volumetric  primitives  (cones,  spheres,
     polygons,  polygonal  patches,  and volumes) can have one or
     more clipping planes attached to them. Clipping  planes  are
     attached to primitives by using the binary operators and and
     or, and the unary operator not. A clipping plane  is  speci-
     fied as follows:

          plane Px Py Pz Nx Ny Nz,

     where Px Py Pz is a point on the plane and Nx Ny Nz  is  the
     normal  to  the plane. Each plane defines a half space (half
     of the entire 3D space) which is visible and  a  half  space
     that  is  not  visible.  The  half  space that is visible is
     defined to be the side of the clipping plane that the normal
     points  to.  These clipping planes are applied to primitives
     by using the operations described  above.  This  application
     must follow the format:

          and prim csgtree,

     where prim is either a single primitive as  described  above
     or  a  list of such primitives, and csgtree is an expression
     composed of planes combined by CSG operators.  The  list  of
     primitives  associated with the given CSG tree is defined as

          list primlist endlist

     where primlist is a list of one or more NFF primitives.  The
     CSG  expression  csgtree can be an arbitrary number of clip-
     ping planes combined by following the recursive rules:

          csgtree == plane
          csgtree == and csgtree csgtree
          csgtree == or csgtree csgtree
          csgtree == not plane