home *** CD-ROM | disk | FTP | other *** search
/ Encyclopedia of Graphics File Formats Companion / GFF_CD.ISO / formats / nff / spec / nff.txt
Text File  |  1994-06-01  |  9KB  |  260 lines
  1. Neutral File Format
  2.  
  3. by Eric Haines
  4.  
  5.  
  6. Draft #1, 10/3/88
  7. Version 2.7, as of 5/22/90 - added information on hither, light color
  8. Version 3.0, 12/17/90 - minor information changes
  9. Version 3.1, 11/2/92 - more minor information changes
  10.  
  11. The NFF (Neutral File Format) is designed as a minimal scene description
  12. language.  The language was designed in order to test various rendering
  13. algorithms and efficiency schemes.  It is meant to describe the geometry and
  14. basic surface characteristics of objects, the placement of lights, and the
  15. viewing frustum for the eye.  Some additional information is provided for
  16. aesthetic reasons (such as the color of the objects, which is not strictly
  17. necessary for testing the efficiency of rendering algorithms).
  18.  
  19. Future enhancements could include:  circle and torus objects, spline surfaces
  20. with trimming curves, directional lights, characteristics for positional
  21. lights, CSG descriptions, and probably more by the time you read this.
  22. Comments, suggestions, and criticisms are all welcome.
  23.  
  24. At present the NFF file format is used in conjunction with the SPD (Standard
  25. Procedural Database) software, a package designed to create a variety of
  26. databases for testing rendering schemes.  For more information about SPD see
  27. "A Proposal for Standard Graphics Environments," IEEE Computer Graphics and
  28. Applications, vol. 7, no. 11, November 1987, pp. 3-5.  See IEEE CG&A, vol. 8,
  29. no. 1, January 1988, p. 18 for the correct image of the tree database (the
  30. only difference is that the sky is blue, not orange).
  31.  
  32. The SPD package is available via anonymous FTP from:
  33.  
  34. wuarchive.wustl.edu [128.252.135.4]:  /graphics/graphics/objects
  35. princeton.edu [128.112.128.1]:  /pub/Graphics [note the capital "G"!]
  36.  
  37. among others.  For those without FTP access, write to the netlib automatic
  38. mailer:  research!netlib and netlib@ornl.gov are the sites.  Send a one line
  39. message "send index" for more information, or "send haines from graphics" for
  40. the latest version of the SPD package.
  41.  
  42. If you would like to see images of the databases, FTP from:
  43.  
  44. ftp.ipl.rpi.edu [128.113.14.50]:  sigma/erich
  45. nic.funet.fi [128.214.6.100]:  somewhere...
  46. gondwana.ecr.mu.oz.au [128.250.70.62]:  pub/images/haines
  47.  
  48. If you're looking for a good scene description language, see Craig Kolb's
  49. Rayshade software (found on weedeater).  Rayshade also has an awk program to
  50. convert NFF to Rayshade's format.  NFF is meant for testing efficiency schemes
  51. and so has minimal support for lighting and shading.
  52.  
  53. By providing a minimal interface, NFF is meant to act as a simple format to
  54. allow the programmer to quickly write filters to move from NFF to the
  55. local file format.  Presently the following entities are supported:
  56.      A simple perspective frustum
  57.      A background color description
  58.      A positional (vs. directional) light source description
  59.      A surface properties description
  60.      Polygon, polygonal patch, cylinder/cone, and sphere descriptions
  61.  
  62. Files are output as lines of text.  For each entity, the first field defines
  63. its type.  The rest of the line and possibly other lines contain further
  64. information about the entity.  Entities include:
  65.  
  66. "v"  - viewing vectors and angles
  67. "b"  - background color
  68. "l"  - positional light location
  69. "f"  - object material properties
  70. "c"  - cone or cylinder primitive
  71. "s"  - sphere primitive
  72. "p"  - polygon primitive
  73. "pp" - polygonal patch primitive
  74.  
  75.  
  76. These are explained in depth below.
  77.  
  78. --------
  79.  
  80. Viewpoint location.  Description:
  81.     "v"
  82.     "from" Fx Fy Fz
  83.     "at" Ax Ay Az
  84.     "up" Ux Uy Uz
  85.     "angle" angle
  86.     "hither" hither
  87.     "resolution" xres yres
  88.  
  89. Format:
  90.  
  91.     v
  92.     from %g %g %g
  93.     at %g %g %g
  94.     up %g %g %g
  95.     angle %g
  96.     hither %g
  97.     resolution %d %d
  98.  
  99. The parameters are:
  100.  
  101.     From:  the eye location in XYZ.
  102.     At:    a position to be at the center of the image, in XYZ world
  103.    coordinates.  A.k.a. "lookat".
  104.     Up:    a vector defining which direction is up, as an XYZ vector.
  105.     Angle: in degrees, defined as from the center of top pixel row to
  106.    bottom pixel row and left column to right column.
  107.     Hither: distance of the hither plane (if any) from the eye.  Mostly
  108.    needed for hidden surface algorithms.
  109.     Resolution: in pixels, in x and in y.
  110.  
  111.   Note that no assumptions are made about normalizing the data (e.g. the
  112.   from-at distance does not have to be 1).  Also, vectors are not
  113.   required to be perpendicular to each other.
  114.  
  115.   For all databases some viewing parameters are always the same:
  116.     Yon is "at infinity."
  117.     Aspect ratio is 1.0.
  118.  
  119.   A view entity must be defined before any objects are defined (this
  120.   requirement is so that NFF files can be displayed on the fly by hidden
  121.   surface machines).
  122.  
  123. --------
  124.  
  125. Background color.  A color is simply RGB with values between 0 and 1:
  126.     "b" R G B
  127.  
  128. Format:
  129.     b %g %g %g
  130.  
  131.     If no background color is set, assume RGB = {0,0,0}.
  132.  
  133. --------
  134.  
  135. Positional light.  A light is defined by XYZ position.  Description:
  136.     "l" X Y Z [R G B]
  137.  
  138. Format:
  139.     l %g %g %g [%g %g %g]
  140.  
  141.     All light entities must be defined before any objects are defined (this
  142.     requirement is so that NFF files can be used by hidden surface machines).
  143.     Lights have a non-zero intensity of no particular value, if not specified
  144.     (i.e. the program can determine a useful intensity as desired); the
  145.     red/green/blue color of the light can optionally be specified.
  146.  
  147. --------
  148.  
  149. Fill color and shading parameters.  Description:
  150.     "f" red green blue Kd Ks Shine T index_of_refraction
  151.  
  152. Format:
  153.     f %g %g %g %g %g %g %g %g
  154.  
  155.     RGB is in terms of 0.0 to 1.0.
  156.  
  157.     Kd is the diffuse component, Ks the specular, Shine is the Phong cosine
  158.     power for highlights, T is transmittance (fraction of contribution of the
  159.     transmitting ray).  Usually, 0 <= Kd <= 1 and 0 <= Ks <= 1, though it is
  160.     not required that Kd + Ks == 1.  Note that transmitting objects ( T > 0 )
  161.     are considered to have two sides for algorithms that need these (normally
  162.     objects have one side).
  163.  
  164.     The fill color is used to color the objects following it until a new color
  165.     is assigned.
  166.  
  167. --------
  168.  
  169. Objects:  all objects are considered one-sided, unless the second side is
  170. needed for transmittance calculations (e.g. you cannot throw out the second
  171. intersection of a transparent sphere in ray tracing).
  172.  
  173. Cylinder or cone.  A cylinder is defined as having a radius and an axis
  174.     defined by two points, which also define the top and bottom edge of the
  175.     cylinder.  A cone is defined similarly, the difference being that the apex
  176.     and base radii are different.  The apex radius is defined as being smaller
  177.     than the base radius.  Note that the surface exists without endcaps.  The
  178.     cone or cylinder description:
  179.  
  180.     "c"
  181.     base.x base.y base.z base_radius
  182.     apex.x apex.y apex.z apex_radius
  183.  
  184. Format:
  185.     c
  186.     %g %g %g %g
  187.     %g %g %g %g
  188.  
  189.     A negative value for both radii means that only the inside of the object is
  190.     visible (objects are normally considered one sided, with the outside
  191.     visible).  Note that the base and apex cannot be coincident for a cylinder
  192.     or cone.  Making them coincident could be used to define endcaps, but none
  193.     of the SPD scenes currently make use of this definition.
  194.  
  195. --------
  196.  
  197. Sphere.  A sphere is defined by a radius and center position:
  198.     "s" center.x center.y center.z radius
  199.  
  200. Format:
  201.     s %g %g %g %g
  202.  
  203.     If the radius is negative, then only the sphere's inside is visible
  204.     (objects are normally considered one sided, with the outside visible).
  205.     Currently none of the SPD scenes make use of negative radii.
  206.  
  207. --------
  208.  
  209. Polygon.  A polygon is defined by a set of vertices.  With these databases,
  210.     a polygon is defined to have all points coplanar.  A polygon has only
  211.     one side, with the order of the vertices being counterclockwise as you
  212.     face the polygon (right-handed coordinate system).  The first two edges
  213.     must form a non-zero convex angle, so that the normal and side visibility
  214.     can be determined by using just the first three vertices.  Description:
  215.  
  216.     "p" total_vertices
  217.     vert1.x vert1.y vert1.z
  218.     [etc. for total_vertices vertices]
  219.  
  220. Format:
  221.     p %d
  222.     [ %g %g %g ] <-- for total_vertices vertices
  223.  
  224. --------
  225.  
  226. Polygonal patch.  A patch is defined by a set of vertices and their normals.
  227.     With these databases, a patch is defined to have all points coplanar.
  228.     A patch has only one side, with the order of the vertices being
  229.     counterclockwise as you face the patch (right-handed coordinate system).
  230.     The first two edges must form a non-zero convex angle, so that the normal
  231.     and side visibility can be determined.  Description:
  232.  
  233.     "pp" total_vertices
  234.     vert1.x vert1.y vert1.z norm1.x norm1.y norm1.z
  235.     [etc. for total_vertices vertices]
  236.  
  237. Format:
  238.     pp %d
  239.     [ %g %g %g %g %g %g ] <-- for total_vertices vertices
  240.  
  241. --------
  242.  
  243. Comment.  Description:
  244.     "#" [ string ]
  245.  
  246. Format:
  247.     # [ string ]
  248.  
  249.     As soon as a "#" character is detected, the rest of the line is considered
  250.     a comment.
  251.  
  252.  
  253.     
  254.  
  255.  
  256.  
  257. Eric Haines
  258. 3D/Eye Inc
  259. email: erich@eye.com, wrath.cs.cornell.edu!eye!erich
  260.