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