makeNSF2 Documentation
v0.0.6.4.i
Nicholas Hampshire
Innovations Project 2008
BACVA3 Level H
1.0 Introduction
The makeNSF2 tool is a command line driven programme to create 2 dimensional collision shape files from geometry files. Currently supported geometry files are:
.obj
Files created with the makeNSF2 command line tool should be given the file extension .nsf2 (2D shape file).
2.0 Shape Types
There are currently two types of shape available for creation by the tool:
Circle 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 .nsf2 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 CR / PX (Circle shape / Proxy shape)
2.1 Circle Shape Type
The Circle shape is the simplest type available. By parsing a geometrical input file to the programme on the command line and specifying the CR (Circle) shape type indicator, the spacial centre of this geometry would be found, and an overall average radius for the vertices 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 circle:
centre (float) (float) ~The geometrical x and y centre of the circle
radius (float) ~The radius of the circle
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 in 2 dimensions. It should be noted at this stage that all coordinates of the 'z' dimension will be ignored, and the outputted data will only include 'x' and 'y' values. The type of data that the programme will work on from a geometry file is that of single polygons. If a 3 dimensional object with an entirely closed mesh was sent as the input file, then the expected output should be no valid edges or verticies for use. If a triagular face was entered, then the expected output would be three faces, three vertices and one convex patch. This is the nature of the programme, as it is the open egdes on a face which are used as the collidable edges in 2 dimensions.
The main objective of this type is to take a set of verticies and faces, found in the geometrical input file, and evaluate to create a set of verticies, edges 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 edges and so wouldn't need to be tested for collisions. If defines as inside, this means that a this vertex 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. If defined as hybrid, then the vertex only has one connected edge and is open, i.e, does not form the body of a solid polygonal object.
Edges undergo a very similar evaluative sequence, which establishes whether they are concave, convex or mixed. These identifiers are promoted from the original vertex types. So for a convex edge, both vertices attached to the edge are alos convex (or neutral). The same circumstance but inverted apply for concave edges. If an edge is mixed, this means that it is only connected to one vertex, and that it is on an outside end line segment of a line.
Patches are the highest hierarchical set of data. A patch can have status concave, convex or mixed. A patch is a set of edges collected together depending on their status. A collection of edges which are all set to concave will be a patch with status concave. The same goes for convex and mixed. However, there may be multiple patches of the same status, as the edges have to be connected to be able to join the patch. Therefore, a geometrical definition of a circle, but with a dent on either side of the centre would produce four patches: two convex, for the top and bottom convex regions of connected faces and two mixed for the region including and around the dents where there are edges with both concave and convex connections.
The following tags should be observed within a shape file between *start and *end tags produced for a proxy model:
v(char) (float) (float) (float) (float) ~Vertex data. The first character indicates a neutral 'n', inside 'i', outside 'o' or hybrid 'h' vertex type. The next two float values are position local to the centre value. The final two floating point values are the safe point of this vertex.
e(char) (int) (int) (float) (float) (float) (float) (int) ~Edge data. The character indicates a concave 'c', convex 'v' or mixed 'm' edge patch type. The first two integers identify the connected verticies, the first two floats define the edge unit length vector, the second two indicate the edges outward normal. The final int is the number of the patch which the edge belongs to.
centre (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, a file which can be filled with manual entries, or an empty file shell to see a reference of the meaning behind the entries and their place.
There are one or four arguaments.
The first arguament will always be the makeNSF2 programme name.
The second arguament will be the shape type you wish to create: CR or PX are the options, for Circular or Proxy, respectively.
The third arguament is the input file you wish to have the shape created from, and should only be one of the 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 only one arguament, the user will be guided via input to creating the type of output file they wish. With four arguaments, the data will be read, created of the correct type and stored in the outfile specified.
4.0 Closing
The file is appended with the version number of the executable, and the time and date which is was run.