The Modelzilla Geometry Layer - API Reference

The Geometry package defines geometrical data structures and some math to aid their construction. (It used to or may still be called the MeshGeom package.) The package root name is harmonic.meshGeom. The package harmonic.meshGeom.geom contains data structures render able to graphics. The package harmonic.meshGeom.math contains math operators.

It is possible to define your own geometry class as long as it is a subclass of Geom. If you subclass a geometry that is concrete and render-able, then you will not have to define your own drawing routine. If your geometry requires special rendering, you can look into how to plug in a special rendering method in the ViewerCore layer.

The geometry class names resemble the class names offered in the Java3D library. This is because in the early days of development Modelzilla used Java3D. The render-able geometry classes are improved versions of the Java3D classes, having more convenient ways of specifying the geometry definition arrays, and some nice data extraction systems. They are designed to support the running input and output of computational geometry functions, instead of being ridged structures purely for rendering input. In Modelzilla, the same geometry objects that are passed among computational geometry operations are rendered in the view-port.

Note is possible to use the Geometry package apart from the rest of Modelzilla, because it has no dependencies on Modelzilla, or any other packages other than the Jama matrix math package from NIST.

class Geom (abstract):

This is the abstract base class for all of the geometries.

Picking functions:

intersect(PickRay ray), intersect(PolygonGeom geom)

Defines how the geometries are considered for picking.

Drawing functions:

getGeometryDrawer(): This returns an object that knows how to draw the geometry. The geometries do not contain drawing code themselves. This makes it possible to plug in a new kind of rendering system that uses an all new graphics API. Also, this enables the Geometry package to have no dependencies on external graphics API's. isRenderable(): This returns whether not the geometry should be drawn in the view-port. Possibly the geometry may be in an invalid state and should be skipped.

Transform functions:

transform(TMat mat):

Transform the geometry according to a transformation matrix in some way. This should actually change the material data in the geometry, rather than change an internal transformation matrix.

transformToAux(TMat mat):

Make the transformation to temporary memory such that the transformation can be undone by calling localize(). The geometry should behave just like transform() was used, except that the untransformed memory is stowed away in an internal reference(s).

transformXYToAux(TMat mat):

Like above, but skip calculating Z coordinate. localize(): Undoes a temporary transformation, without inverting a matrix and retransforming.

The debuging functions:

makeGeomInfoString():

This is an abstract function the should return the text printed describes the geometry.

The data transfer functions:

fromInputStream(), toInputStream():

These functions are for serialization support.

The memory tracking functions:

countObject_Created(), countObject_Finalized():

These are concrete functions that communicate with the larger framework if it is resident in the current process, via the AppInterface class. They tell the larger application about the creation and destruction of geometries for memory tracking purposes.

class ArrayGeom (abstract):

This is the abstract base class for geometries that are defined by arrays of vertices and connectivity between the vertices. Today?s computer graphics mostly involves the rendering of object boundaries, practically polygons and lines. ArrayGeom is a container class for keeping data needed for surface geometries, line geometries, and point geometries. The meeting of the data in this class is not known at this level. It becomes known through in subclasses, which define connectivity between vertices. For example the TriangleArrayGeom class says that every three vertices is a triangle. An ArrayGeom object holds six arrays.

The vertex array:

The vertex arrays defines where the various pieces of the geometry are in space. It is an array of float primitives. The format is: x,y,z, x,y,z, x,y,z.. To access the y value of the third point, use y2 = vert[2*3 + 1] . This interleaved format is used because most geometrical methods need the x, y and z together. The computer can access memory faster if it pulls from one area of an array, because of the CPU memory cache.

Other possible formats we rejected are:

An separate array for x?s, y?s and z?s: x,x,x,x,x.... y,y,y,y,y.... z,z,z,z,z.... This format has the advantage of being convenient for functions that can deal with each dimension separately. Our y value: y2 = yArray[2]

An array of coordinate arrays: y2 = array[2][1]. This format has the advantage of being intuitive however it is a huge memory hog. Remember JAVA does not support multi dimensional sub scripting, (it will not compile [2][1] to 2*3 + 1), so this notation requires allocating a separate 3 element arrays for each vertex.

A tuple object array: y2 = array[2].y. This format has the advantage the intuitive however it is a huge memory hog.

The normal array:

The normal array is parallel to the vertex array (if the geometry is not indexed). It has the format: x,y,z, x,y,z, x,y,z.. This means that an element in the normal array corresponds to the element of the same index in the vertex array. The normal array describes the direction perpendicular to the surface at a given vertex. The most important use for this is lighting calculations, which look at the normal at a vertex to learn how the surface at the vertex is oriented to the viewer. If the array is left unspecified when is comes time to draw the geometry, Modelzilla will compute a normal array automatically. The automatic computer assumes the surface is flat. The Normalizer class helps to compute normals, flat, smooth, mixed flat and smooth, and with edge kinks. However, the specification of the normal array is not just routine computation. Is part of the art of computer graphics. By carefully controlling the directions of the normal, a surface can be made to have flat faces in some places, smooth faces in another, and hard or soft edges. Some surfaces should appear to be smooth along one direction, but have sharp changes in the perpendicular direction, for example the extrusion of a rectangle.

The color array:

The color array is parallel to the vertex array (if the geometry is not indexed). It has the format: r,g,b, r,g,b, r,g,b. It defines how of the surface in the area of the corresponding vertex is rendered. If no color array is given the service will be drawn in a uniform color. Future plans include making this array optionally 4-D to accommodate a per vertex transparency.

The texture array:

The texture array defines the two dimensional texture mapping that maps from the corresponding vertex on the geometry to the point on an image buffer. This allows an image to be applied to a surface. The texture array is indexed in groups of two. It has the format: x,y,x,y,x,y. The each x and y refers to a point on the image kept in the image buffer with normalized width and height. (The image is specified in the graphics layer)

The part integer array:

This is an array of integers that parallels the atomic parts of the geometry. That is, there should be one element in the part array for every polygon or line of the geometry. It can be used to identify pieces of the geometry, usually for mouse feedback.

The part object array:

This is just like the part integer array, except it is an array of references. Either one may be used.

In the current implementations of ArrayGeom, the arrays are kept in the geometry object directly as primitive array objects. Each array has a corresponding good count. Future plans include changing these fields to smart container classes that each independently manage vertices, normals, colors and textures on a per tuple basis. Right now the geometry class itself is handling the array growing, etc. You should use the access functions to get a direct array references or sizes, because these primitive array objects will be removed in the future. (get[Vert,Normal,Color,Texture]ArrayRef)

In classes that are not a subclasses of IndexedGeom (which is a subclass of ArrayGeom), the vertex array, the normal array, the color array, and the texture array must have the same number of tuples. This requirement does not exist for the IndexedGeom subclasses.

The array changing functions:

_allocVertArray(int n):

Allocate vertex array memory, keeping good count unchanged

addVert(Pnt3f pnt):

Append vertex

addVert(float[] pnt):

Append vertex

addVert(float[] pntArray, int which):

Append vertex

addVert(float x, float y, float z):

Append vertex

addVertArray(float[] array, int tupleCount):

Append vertex array

insertVert(int where, Pnt3f pnt):

Insert vertex at tuple index

insertVertexArray(float[] array, int count, int where):

Insert vertex array at tuple inex

setVert(int where, float x, float y, float z):

Set vertex value

setVert(int where, Pnt3f pnt):

Set vertex value

setVertArray(float[] array, int count):

Set to given vertex value array of count tuples

setVertArray(ArrayGeom geom):

Set vertex array to a copy of the vertex array of given geometry

shareVertArray(float[] array):

Set vertex array reference

shareVertArray(ArrayGeom geom):

Set vertex array reference to vertex array of given geometry

sizeVertArray(int nVert):

Allocate and set good size Similar functions are used for normals, colors, texture indices, and part mappings.

The array retrieval functions:

_getVert(int tupleIndex):

Get vertex at index

getVert(int tupleIndex):

Get vertex at index, or vertex at index directed through index array

_nVert():

Get good vertex count

nVert():

Get good vertex count, or good index count for index geometry

getVertArrayRef():

Get internal float array reference Similar functions are used for normals, colors, texture indices, and part mappings.

class PointArrayGeom: (points)

Every element describes a point. The geometry is drawn as a cloud of individual points.

class LineArrayGeom: (lines)

Every two elements in the value array specifies the end point of a line.

class LineStripGeom: (lines)

The first to element in the value arrays starts set of connected lines, and every element after this adds a new line that starts where the previous line ended. Allows for multiple strips.

class PolygonGeom: (lines)

This geometry is much like the LineArrayGeom except it does not allow for multiple chains.

class TriangleArrayGeom: (surface)

Every three elements describe a triangle.

class QuadArrayGeom: (surface)

Every four elements describe a quadrilateral.

class QuadMeshGeom: (surface)

This is a specialized geometry that describes quad elements in a rectangular array that are implicitly connected in a way matching the nearest neighbors in the two dimensional array.

class IndexedGeom (abstract):

An indexed geometry has an array of integers for every value array, each element of which indexes the value array. (The value arrays are what we are calling vertex arrays, color arrays, normal arrays and texture arrays.) The vertex is then described by the index values in the index arrays. This enables the value array elements to be unique. Instead of repeating a value in the value array, the index to the value is repeated in the index array. Usually a geometry described by and vertex arrays will have line segments that touch at their end points, and polygon faces that share common edges. If a TriangleArrayGeom is used to define an array of triangles that from a closed surface, it will include every vertex value at least three times, because most vertices will be shared by a least three faces. The index geometry class introduces an array of connectivity indices. The indexing arrays are parallel. The 3rd element of the vertex index array, color index array, normal index array and texture index array all collectively describe the same connection. Indexed geometries are the preferred method of storage. In fact, there is not much reason to use the non indexed geometries at all, unless to store a geometry made of elements that are truly unjoined. Indexed geometries have the advantage of:

Indexed geometry does not require that the underlying value arrays be parallel. It is possible have 100 vertices in your vertex array, and only two colors in the color array. It is however required that the various index arrays are parallel.

Indexed geometry is capable of representing anything that non index geometry can represent, and more. In our Modelzilla applications, we make use of indexed geometry almost exclusively.

The array changing functions:

_allocVertIndexArray(int n)

addVertIndex(int i)

addVertIndexArray(int[] array, int n)

Similar functions are used for normals, colors, and texture indices.

The array retrieval functions:

There really are none. Just use the public fields.

class IndexedLineArrayGeom

Every two elements in the index arrays describe a line.

class IndexedLineStripArrayGeom

The first element in the index arrays starts set of connected lines, and every element after this adds a new line that starts where the previous line ended. Allows for multiple strips.

class IndexedTriangleArrayGeom

Every three elements in the index arrays describe a triangle

class IndexedQuadArrayGeom

Every four elements in the index arrays describe the quadrilateral

class IndexedTriangleStripArrayGeom

The first three elements in the index arrays describe a triangle, and then every element after this adds a triangle connected to the previous two vertices the previous triangle.

class IndexedPolygonArrayGeom

This is a set of N-sided polygons. In contrast to other geometries such as the IndexedTriangleArray, this geometry allows every polygon have any number of vertices. Polygons may also have any number holes. IndexedPolygonArrayGeom can represent any surface. Because it is the most general of the surface geometry classes, there are many conversion functions that go to and from this class. It is the most important of the concrete geometry class.

IndexedPolygonArrayGeom introduces a partitioning array to describe polygon sizes and hole sizes. The index arrays of IndexedGeom are still used to list the values used for each polygon vertex. The partitioning array describes how to break up the indexing arrays.

The geometry may be assembled by using the IndexedFace class in combination with the IndexedPolygonArrayGeom.addFace() function. It may also be assembled by using the IndexedPolygonArrayGeom.breakLoop() and IndexedPolygonArrayGeom.breakPolygon() function between the addition of vertex indices. The getFace() function can be used iterate over the faces.

class IndexedFace

This is a helper class that helps one iterate over the faces in any surface geometry. The function ArrayGeom.getFace(int iFace, IndexedFace face) fills in information regarding the face (polygon) at the given index. Every surface geometry class in this package represents the surface by a set of polygons. Every surface geometry class can return a complete descriptor of the face through this function. And the IndexedPolygonArrayGeom class uses the IndexedFace class for assembling geometries as well.

class RasterGeom

An image.

The geometry operators

The Geometry package comes with a variety of functions operate on geometries in the package meshGeom.math. As of this writing these classes are not so presentable as an attractive API, but you may be able to figure out how to use some things. The TMat and Geo classes are relatively well documented.