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