makeNSF3 Documentation
v0.0.6.4.i

Nicholas Hampshire
Innovations Project 2008
BACVA3 Level H

1.0 Introduction

The makeNSF tool is a command line driven programme to create collision shape files from geometry files. Currently supported geometry files are:

.obj

All files created with the makeNSF command line tool should be given the filename extension .nsf3 (3D Shape File).

2.0 Shape Types

There are currently two types of shape available for creation by the tool:

Sphere Shape
Proxy Shape

Each type represents a different method of defining a physical space which can be used for collision detection. Sphere shapes are the most simple, whilst Proxy shapes are the most complex.
The following tags should be observed within a .nsf3 file, no matter what the shape type is:

type ~Will be followed by one of two arguaments, specifying the shape type.
origin ~Will be followed by the filename of the input file parsed to the programme from the command line.
*start ~Indicates the start of the data block for whatever shape type may be entered.
*end ~Indicates the end of the data block holding the shape information
status ~Will be followed by an integer which defines whether the object is of dynamic or static status
sidedness ~Will be followed by an integer which defines which side of the object is taken to be the collidable side.

The following are a set of all of the possible entries after each of the above tags, which have a limited number of entries:

type SP / PX (Spherical shape / Proxy shape)

2.1 Sphere Shape Type

The Sphere shape is the simplest type available. By parsing a geometrical input file to the programme on the command line and specifying the SP (Sphere) shape type indicator, the spacial centre of this geometry would be found, and an overall average radius for the verticies produced. The data is then written to the outfile.
The following tags should be observed within a shape file between the *start and *end tags produced for a sphere:

centre (float) (float) (float) ~The geometrical x, y and z centre of the sphere
radius (float) ~The radius of the sphere

2.2 Proxy Shape Type

The Proxy shape is a more complex by comparison. The Proxy shape takes the original geometry of the model which was parsed in in the input file from the command line, and outputs the same geometrical shape but with highly optimised capabilities for use in proxy model collision detection.
The main objective of this type is to take a set of verticies and faces, found in the geometrical input file, and evaluate a set of verticies, edges, faces and patches which will be useful. Operations are performed on each vertex to establish whether it is of neutral type, inside type, outside type, or hybrid type. If defined as neutral, the vertex is surrounded by flat faces and so wouldn't need to be tested for collisions. If defines as inside, this means that a this vertes would only need to be tested for a potential collision with another object if the other object was being tested for collision with the inside of the proxy shape. If defined as outside, the vertex would only need to be tested for collision with another object if the other object was being tested for collisions with the outside of the proxy shape. A hybrid vertex means that it will need to be tested whatever the case, because it has complex connections, such as being a vertex on an open edge of the proxy shape.
Edges undergo a very similar evaluative sequence, which establishes whether they are neutral, inside, outside or hybrid. These identifiers are the same as verticies. So for a neutral edge, both faces attached to the edge are parallel, therefore the edge does not need to be tested. If an edge is hybrid, this means that it is only connected to one face, and that it is on an outside edge of an open proxy model.
Faces again have a very similar setup based on the status of the three edges they are connected to. However, there are no neutral faces. Any faces which entirely neutral connected edges are defaulted to an outside face. The reasons behind this will be later revealed. Faces can be defines as inside, outside, or mixed. An inside face is one with any number of open edges, where all remaining edge attachments are inside. An outside face is one which has any number of open edge attachments, but where all remaining attachments are outside. A mixed face is one where the edges attachments can vary from inside to outside, and also may have open edges.
Patches are the highest hierarchical set of data. A patch can have status inside, outside or mixed, lika a face. A patch is a set of faces collected together depending on their status. A collection of faces which are all set to inside will be a patch with status inside. The same goes for outside, and mixed. However, there may be multiple patches of the same status, as the faces have to be connected in order to join the patch. Therefore, a geometrical definition of a sphere, but with a ridge of insde edges around it's equator would produce three patches: two outside, for the top and bottom outside regions of connected faces and one mixed around the centre where there are faces with inside and outside edge connections.
The followinig tags should be observed within a shape file between *start and *end tags produced for a proxy model:

centre (float) (float) (float) ~The geometrical x y and z centre of the proxy model

v(char) (float) (float) (float) ~Vertex data. The first the vertex type: 'n' means neutral, 'i' means inside, 'o' means outside, 'h' means hybrid. The floating point values are the position of the vertex local to the centre values.

e(char) (int) (int) ((float)(float)(float)) ~Edge data. The character refers to the type in exactly the same way as a vertex. The first integer identies the start vertex of the edge, the next integer is the end vertex index for the edge. The next three floats define the edge unit length vector.

f(char) (int) (int) (int) (int) ((float)(float)(float)) (int) ((float)(float)(float)) (int) ((float)(float)(float)) ((float)(float)(float)) (int) ~Face data. The character refers to the patch type of the face: 'c' means concave patch, 'v' means convex patch, 'm' means mixed patch. The first three integers indicate the verticies that make the face. The next integer is the reference to the first connected edge, and the following vector is the edge/face/safe normal for that edge. The next two integer-vector values are for the second and third edges of the face. The next three floating point values define the faces unit length normal. The final integer is the index to the patch the face belongs to.

centre (float) (float) (float) ~The geometrical centre of the shape, from which all the verticies are locally positioned from

3.0 Command Line Arguaments

The use of the programme from the command line provides the ability to generate a filled shape file of any of the previously explained types, or an empty file shell to enable manual entries, or to see a quick reference of the meaning behind the entries and their place.
There are one or four arguaments.
The first arguament will always be the makeNSF3 programme name.
The second arguament will be the shape type you wish to create: SP or PX are the options, for Spherical or Proxy shapes, respectively.
The third arguament is the input file you wish to have the sphape created from, and should only one of the types of currently supported input file types.
The fourth arguament is the name of the output file you wish to store the shape data in. If the file already exists, it will be entirely overwritten.
With just the first one arguaments, the user will be guided through inputs in order to create the shape. With all four arguaments, the data will be read, created as the specified type and stored in the outfile specified.

4.0 Limitations

Only triangulated models are supported within the proxy shape type. This is both advantageous and limiting at the same time. Faces which are not triangulated can have undefined results within collision detection, and so any faces which do not have three sides will be truncated.

5.0 Closing

The file is appended with the version number of the executable, and the time and date which is was created.