Important This document is currently under construction.

This document outlines how to use the "Alias/Wavefront OBJ" file format to import attributed geometry into DIRSIG.

Background and History

In 1995, Silicon Graphics Inc. bought and merged two pioneering companies in computer graphics: Alias Research and Wavefront Technologies. Outliving the technical achievements, one of the lasting contibutions of these pioneers was a 3D geometry file format that has remained ubiquitous in modern 3D content creation. The so-called "Alias/Wavefront OBJ" file format has the following features:

  • It is a simple, portable, ASCII/Text based format.

  • It is widely supported by 3D geometry authoring tools (3ds MAX, Maya, Rhino, SketchUp, Blender, etc.).

  • It supports per-facet material attribution.

  • It supports a single level of facet grouping (comparable to the GDB "parts" concept).

  • It uses "shared vertex lists" which cut down on file size, memory usage, and precision issues that lead to gaps at vertexes and along edges.

  • It supports "texture vertexes" which is a texture coordinate system tied to the object coordinate system (rather than scene level (global) coordinate system) and allows for "wrapping" material, texture, etc. maps onto/around objects.

  • It supports "vertex normals" which allows an otherwise flat facet to appear to have curvature by spatially interpolating normals defined at the vertexes.

When using the OBJ format instead of the GDB format you gain nearly seamless inter-operability with most CAD tools. In some cases those tools might preserve the material assignments, which means an OBJ can be moved back and forth without the need to re-attribute. Plus, you get support for numerous features (texture vertexes, vertex normals, smaller files, etc.) that the GDB format doesn’t have. What you give up when using OBJ is the options for per-facet thickness and per-facet override temperatures. If you have not been using either of these features of the GDB format, then the OBJ format might be right for you.

Format Summary

A complete description of the OBJ format is beyond the scope of this document, however some basics are included here so that the user can see how the files are used with DIRSIG.

Basic Polygon Example

The example OBJ file below contains a minimal description of a 4-sided polygon that is 1 x 1 units, in the XY plane and centered about the origin (0,0):

v -0.5 -0.5 0.0
v +0.5 -0.5 0.0
v +0.5 +0.5 0.0
v -0.5 +0.5 0.0
f 1 2 3 4

The four v lines each describe a vertex. The v tag is followed by the XYZ coordinate for that vertex. The single f line defines a facet that is constructed from the 4 vertexes described earlier. The f tag is followed by a list of vertex indexes that define the facet. These vertex indexes start at 1 with the first vertex in the file. In this case, the facet uses the first, second, third and forth vertex. Using a right-handed convention, this results in a normal vector that points in the +Z (0, 0, +1) direction.

A more complex file will have many more vertexes (v entries) and many more facets (f entries). The point of the vertex list is that adjacent facets can share vertexes in the list (by using the same vertex index). This helps to insure that the edges of facets are "tight".

Defining Groups

When large and complex geometric objects are created, it is helpful to have structure to the object. For example, it might be helpful for a vehicle to have "components" called "hood", "driver_door", "passenger_door", "tire1", "tire2", "exhaust", etc. In the OBJ file, this option to create logical collections of geometry within the model is facilitated by "groups". A group is defined by a line beginning with the g tag and followed by an alpha-numeric string. All geometry following the group declaration will belong to that group until a new group is defined.

v -0.5 -0.5 0.0
v +0.5 -0.5 0.0
v +0.5 +0.5 0.0
v -0.5 +0.5 0.0
...
g hood
f 1 2 3 4
...
f 96 97 98 99
g exhaust
f 100 102 103 104

Assigning Materials

The OBJ file format includes a sibling MTL file that describes material properties, which has a .mtl file extension. Materials in the OBJ/MTL file pair are identified by a unique alpha-numeric string. The name of the MTL file to be used by an OBJ file is specified via the mtllib tag. The current alpha-numeric material identifier to be assigned to geometry is speciied via the usemtl tag.

mtllib example.mtl
v -0.5 -0.5 0.0
v +0.5 -0.5 0.0
v +0.5 +0.5 0.0
v -0.5 +0.5 0.0
...
usemtl mat1
f 1 2 3 4
...
f 96 97 98 99
usemtl mat2
f 100 102 103 104

In this example, the file example.mtl contains one or more material descriptions. The usemtl line before the first facet indicates that the material identified with the alpha-numeric string mat1 should be assigned to all geometry following this line, or until a new usemtl line is supplied. In the above example, all the facets will get assigned mat1 until we reach the line usemtl mat2.

Note The material descriptions in the MTL file are not complete enough for use in DIRSIG. However, the method to associate materials with geometry can be utilized by DIRSIG. This will be discussed later in this document.

Defining Texture Coordinates

An OBJ file can also contain a list of "texture vertexes". This is an alternate coordinate system that can be used to wrap 2D image maps around 3D geometry using an approach sometimes referred to as UV mapping. The texture vertex list is another list of 3D vertexes in the OBJ file, but using the vt tag:

v -0.5 -0.5 0.0
v +0.5 -0.5 0.0
v +0.5 +0.5 0.0
v -0.5 +0.5 0.0
vt 0.0 0.0 0.0
vt 1.0 0.0 0.0
vt 1.0 1.0 0.0
vt 0.0 1.0 0.0
f 1/1 2/2 3/3 4/4

The single facet line still has four tokens that represent each of the four corners of the polygon. However, each token now has two parts: a vertex (v) index and a texture vertex (vt) index that are specified using a v/vt format within the token.

Facets do not need to have both vertexes and texture vertexes. Some facets can use texture vertexes and some can not:

...
f 1/1 2/2 3/3 4/4
...
f 100 102 103 104
...

Defining Vertex Normals

The OBJ format also supports "vertex normals", which is the option to have a normal vector defined at a given location. The vertex normal list is another list of 3D vertexes (vectors, actually) in the OBJ file, but using the vn tag:

v -0.5 -0.5 0.0
v +0.5 -0.5 0.0
v +0.5 +0.5 0.0
v -0.5 +0.5 0.0
vt 0.0 0.0 0.0
vt 1.0 0.0 0.0
vt 1.0 1.0 0.0
vt 0.0 1.0 0.0
vn 0.0 0.0 1.0
vn 0.0 0.0 1.0
vn 0.0 0.0 1.0
vn 0.0 0.0 1.0
f 1/1/1 2/2/2 3/3/3 4/4/4

The single facet line still has four tokens that represent each of the four corners of the polygon. However, each token now has three parts: a vertex (v) index, a texture vertex (vt) index and a vertex normal index that are specified using a v/vt/vn format within the token.

In this example all four vertex normals were the same, so the facet could have been defined using only one normal for each node:

f 1/1/1 2/2/1 3/3/1 4/4/1

Flexible Facet Definitions

Not every facet in the object needs to be defined with the same attributes. At a minimum, each facet token must have a vertex index, but including the texture vertex index and/or vertex normal index is optional. The example below shows a set of facets that have different combinations of vertex indexes, texture vertex indexes and normal vertex indexes:

...
f 1/1/1 2/2/2 3/3/3 4/4/4
...
f 100/50 102/51 103/52 104/53
...
f 100//100 102//101 103//103 104//104
...
f 100 102 103 104
...

The first facet has all three define at each node. The second has just the texture vertexes added, the third has just the vertex normals added and the fourth has just the vertexes (no texture vertexes or vertex normals).

It is important to note that vertex indices, texture vertex indices and vertex normal indices do not need to be correlated in any way. We have noted that some facets may not include either the vertex indices and/or the vertex normal indices. Furthermore, it is not uncomomon for facets that share vertexes to not share either texture vertexes or vertex normals.

Feature Support in DIRSIG

DIRSIG’s support for OBJ includes the following:

  • Only "facet" constructs ("f" entries) are currently supported

    • Facets are expected to have either 3 or 4 sides/vertexes.

    • Facets with more than 3 or 4 sides/vertexes will result in an error.

  • The material tag (the "usemtl" entries) is assumed to have a DIRSIG numerical material ID associated with it.

    • Note that alpha-numeric material IDs (which are allowed in the OBJ/MTL format) were not supported in DIRSIG 4.6 and earlier, where only numeric IDs were allowed.

  • Texture vertexes (the "vt" entries) are read and used with any mappings applied to the geometry.

  • Vertex normals (the "vn" entries) are read and automatically used to compute the normal across a facet.

  • The use of "groups" (the "g" entries) is allowed and even encouraged to help users organize the components of the geometry. However, internally DIRSIG doesn’t leverage them in any way.

DIRSIG’s support for OBJ does not include the following:

  • Geometry entities other than "facets" (including "points", "lines", "curves", etc.) are not supported.

  • Shading groups (the "s" entries) are not relevant to DIRSIG since all modeling is controlled via material descriptions.

Note In general, any element that DIRSIG doesn’t support is simply ignored, so you don’t need to filter out unsupported features in the OBJ file.

Material Assignments

Direct Look-up Method

The usemtl tag in an OBJ file provides a unique material name or label that is associated with all the geometry following the tag (or until the next usemtl tag appears). As noted earlier in this document, the standard material descriptions described in the MTL (sister) file are not enough for DIRSIG. However, these labels can used by DIRSIG to assign material descriptions out of a standard DIRSIG material database file. For example, here is an excerpt from an OBJ file specifying a few labels using the usemtl tag:

v 0 0.525731112 0.8506508085
v 0 -0.525731112 0.8506508085
v 0 0.525731112 -0.8506508085
v 0 -0.525731112 -0.8506508085
usemtl metal.1a
f 1//2 163//163 165//169
f 163//163 43//47 164//168
f 165//169 164//168 45//40
...
usemtl glass4
f 171//170 170//174 15//9
f 169//160 170//174 171//170
...

And here are a few excepts from a DIRSIG material file using these same labels as the unique identifiers:

MATERIAL_ENTRY {
    ID = metal.1a
    NAME = Metal, polished aluminum
    EDITOR_COLOR = 0.5, 0.5, 0.5
    DOUBLE_SIDED = FALSE
    ...
    [additional material parameters deleted for documenation purposes]
    ...
}

MATERIAL_ENTRY {
    ID = glass4
    NAME = Clear glass, uncoated
    EDITOR_COLOR = 0.0, 0.0, 0.2
    DOUBLE_SIDED = FALSE
    ...
    [additional material parameters deleted for documenation purposes]
    ...
}
Note Prior to DIRSIG 4.7, material labels had to be numeric. However, in DIRSIG 4.7 and later these labels can be alpha-numeric.

GLIST Remapping Method

Another option is to use the GLIST file to remap material labels specified in the OBJ file (via the usemtl tag) to material labels in a DIRSIG material database. Below is th same excerpt used above from an OBJ file specifying a few labels using the usemtl tag:

v 0 0.525731112 0.8506508085
v 0 -0.525731112 0.8506508085
v 0 0.525731112 -0.8506508085
v 0 -0.525731112 -0.8506508085
usemtl metal.1a
f 1//2 163//163 165//169
f 163//163 43//47 164//168
f 165//169 164//168 45//40
...
usemtl glass4
f 171//170 170//174 15//9
f 169//160 170//174 171//170
...

Here are a few excepts from a DIRSIG material file of the materials we would like to map the OBJ labels to (not the difference in the label/ID names):

MATERIAL_ENTRY {
    ID = aluminum
    NAME = Metal, polished aluminum
    EDITOR_COLOR = 0.5, 0.5, 0.5
    DOUBLE_SIDED = FALSE
    ...
    [additional material parameters deleted for documenation purposes]
    ...
}

MATERIAL_ENTRY {
    ID = glass
    NAME = Clear glass, uncoated
    EDITOR_COLOR = 0.0, 0.0, 0.2
    DOUBLE_SIDED = FALSE
    ...
    [additional material parameters deleted for documenation purposes]
    ...
}

Using the GLIST <assign> feature, the metal.1a and glass4 material requests can get remapped to use the aluminum and glass DIRSIG materials, respectively:

<basegeometry>
  <obj>
    <filename>vw_golf.obj</filename>
    <assign id="aluminum">metal.1a</assign>
    <assign id="glass">glass4</assign>
  </obj>
</basegeometry>

This <assign> feature is discussed more in the GLIST file documentation.