The OBJ file format allows the definition of polygon-based objects, as well as of free-form curves and Surfaces. I discuss only the parts of the OBJ file format that describe polygon-based objects.
 

The OBJ file format has a fairly free form organisation, comments may appear any where in an OBJ file and are ignored by OBJ file readers. A comment is any line that begins with the # character; in a multiline comment, each line must begin with a # character.

File structure

The following types of data may be included in an .obj file. In this list, the keyword (in parentheses) follows the data type.
 

Vertex data
 

Geometric vertices (v)

Texture vertices (vt)

Vertex normal (vn)

Elements
 

Point (p)

Line (l)

Face (f)

Grouping
 

Group name (g)

Object name (o)

Display/render attributes
 

Colour interpolation (c_interp)

Dissolve interpolation (d_interp)

Material name (usemtl)

Material library (mtllib)

The v x y z Construct

The v x y z construct is called a vertex statement. This statement defines the (x, y, z) co-ordinates for a face vertex. Polygons are constructed out of three of more vertices. Each vertex is referenced by its index, where the index of the first vertex definition is 1, of the second is 2, and so on.

 The vn i j k Construct

The vn i j k construct defines the vertex normal statement. Vertex normals are used to smooth a polygon surface (by lighting calculations). Vertex normals affect the smooth shading and rendering of geometry. A vertex normal statement begins with the characters "vn" and is followed by three floating-point values that define the normal vector.

The vt u v w Construct

Specifies a texture vertex and its co-ordinates. A 1D texture requires only u texture co-ordinates, a 2D texture requires both u and v texture co-ordinates, and a 3D texture requires all three co-ordinates.

u is the value for the horizontal direction of the texture.

v is an optional argument.

v is the value for the vertical direction of the texture. The default is 0.

w is an optional argument.

w is a value for the depth of the texture. The default is 0.

Referencing vertex data

For all elements, reference numbers are used to identify geometric vertices, texture vertices, vertex normals, and parameter space vertices.

Each of these types of vertices is numbered separately, starting with1. This means that the first geometric vertex in the file is 1, the second is 2, and so on. The first texture vertex in the file is 1, the second is 2, and so on. The numbering continues sequentially throughout the entire file. Frequently, files have multiple lists of vertex data. This numbering sequence continues even when vertex data is separated by other data.

In addition to counting vertices down from the top of the first list in the file, you can also count vertices back up the list from an element's position in the file. When you count up the list from an element, the reference numbers are negative. A reference number of -1 indicates the vertex immediately above the element. A reference number of -2 indicates two references above and so on.

Referencing groups of vertices

Some elements, such as faces and surfaces, may have a triplet of numbers that reference vertex data. These numbers are the reference numbers for a geometric vertex, a texture vertex, and a vertex normal.

Each triplet of numbers specifies a geometric vertex, texture vertex, and vertex normal. The reference numbers must be in order and must separate by slashes (/).

The first reference number is the geometric vertex.

The second reference number is the texture vertex. It follows the first slash.

The third reference number is the vertex normal. It follows the second slash.

There is no space between numbers and the slashes. There may be more than one series of geometric vertex/texture vertex/vertex normal numbers on a line.

The following is a portion of a sample file for a four-sided face element:

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

Using v, vt, and vn to represent geometric vertices, texture vertices, and vertex normals, the statement would read:

f v/vt/vn v/vt/vn v/vt/vn v/vt/vn

If there are only vertices and vertex normals for a face element (no texture vertices), you would enter two slashes (//). For example, to specify only the vertex and vertex normal reference numbers, you would enter:

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

When you are using a series of triplets, you must be consistent in the way you reference the vertex data. For example, it is illegal to give vertex normals for some vertices, but not all.

The following is an example of an illegal statement.

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

Syntax

The following syntax statements are listed in order of complexity of geometry.

p v1 v2 v3 . . .

Specifies a point element and its vertex. You can specify multiple-points with this statement.

v is the vertex reference number for a point element. Each point element requires one vertex. Positive values indicate absolute vertex numbers. Negative values indicate relative vertex numbers.

l v1/vt1 v2/vt2 v3/vt3 . . .

Specifies a line and its vertex reference numbers. You can optionally include the texture vertex reference numbers.

The reference numbers for the vertices and texture vertices must be separated by a slash (/). There is no space between the number and the slash.

v is a reference number for a vertex on the line. A minimum of two vertex numbers is required. There is no limit on the maximum. Positive values indicate absolute vertex numbers. Negative values indicate relative vertex numbers.

vt is an optional argument.

vt is the reference number for a texture vertex in the line element. It must always follow the first slash.

f v1/vt1/vn1 v2/vt2/vn2 v3/vt3/vn3 . . .
 

Specifies a face element and its vertex reference number. You can optionally include the texture vertex and vertex normal reference numbers.

The reference numbers for the vertices, texture vertices, and vertex normals must be separated by slashes (/). There is no space between the number and the slash.

v is the reference number for a vertex in the face element. A minimum of three vertices is required.

vt is an optional argument.

vt is the reference number for a texture vertex in the face element. It always follows the first slash.

vn is an optional argument.

vn is the reference number for a vertex normal in the face element. It must always follow the second slash.

Face elements use surface normals to indicate their orientation. If vertices are ordered counter-clockwise around the face, both the face and the normal will point toward the viewer. If the vertex ordering is clockwise, both will point away from the viewer. If vertex normals are assigned, they should point in the general direction of the surface normal, otherwise unpredictable results may occur.

Examples:

1. Square

This example shows a square that measures two units on each side and faces in the positive direction (toward the camera). Note that the ordering of the vertices is counter-clockwise. This ordering determines that the square is facing forward.
 

v 0.000000 2.000000 0.000000 v 0.000000 0.000000 0.000000 v 2.000000 0.000000 0.000000 v 2.000000 2.000000 0.000000 f 1 2 3 4

 

2. Cube

This is a cube that measures two units on each side. Each vertex is shared by three different faces.
 

v 0.000000 2.000000 2.000000 v 0.000000 0.000000 2.000000 v 2.000000 0.000000 2.000000 v 2.000000 2.000000 2.000000 v 0.000000 2.000000 0.000000 v 0.000000 0.000000 0.000000 v 2.000000 0.000000 0.000000 v 2.000000 2.000000 0.000000 f 1 2 3 4 f 8 7 6 5 f 4 3 7 8 f 5 1 4 8 f 5 6 2 1 f 2 6 7 3