The Neutral File Format (NFF) scene description

The Neutral File Format (NFF) 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 characteristics 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 databases for testing rendering schemes. For more information about SPD see "A Proposal for Standard Graphics Environments," 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:

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 various entities are explained below.

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.

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.

Light source

Defines a positional light source for the scene. Its format is:

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 specified.

Surface definition

Defines how the geometric primitives that follow this 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. A surface definition can either be a typical NFF surface description or a surface shader description. The NFF surface description 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 refraction 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 surface 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.

The surface shader description format is:

surface shader "shadername" instance_list end

where shadername is the name of the shader to be used, and instance_list is a list of 0 or more instance variable definitions. An instance definition can be one of:

where variable_name is the name of the instance variable, string_value is a string of characters enclosed in quotes, value is a floating point value, and map_name is a file name (enclosed in quotes) giving a file containing a map.

 

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.

Sphere

A sphere is defined by a center point and a radius. Its format is:

s Cx Cy Cz R,

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

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 vertices. 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 polygon.

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 NNz,

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 ParVis volume renderer, N must be 3.

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 volume_attributes

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 ignored if a data shader has been specified. If no shader has been specified, the volume attributes should be zero or more of the following:

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 transparent, max_value is a volume data value cut off above which all sample values are transparent, bright is a brightness 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 transparent.

The format of the volume data is specified by the formatstring argument. The format string can specify either a raw floating point data format, a raw byte data format, the HDF format, or the VoxelView format. 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 dimensions 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.

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 specified 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 follows:

list primlist endlist

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

csgtree == plane

or

csgtree == and csgtree csgtree

or

csgtree == or csgtree csgtree

or

csgtree == not plane