File format Wavefront .obj file

1 file format

1.1 geometric vertex
1.2 parameter space vertices
1.3 face elements

1.3.1 vertex indices
1.3.2 vertex texture coordinate indices
1.3.3 vertex normal indices
1.3.4 vertex normal indices without texture coordinate indices


1.4 other geometry formats
1.5 referencing materials
1.6 relative , absolute indices

file format

lines beginning hash character (#) comments.

# comment

an obj file may contain vertex data, free-form curve/surface attributes, elements, free-form curve/surface body statements, connectivity between free-form surfaces, grouping , display/render attribute information. common elements geometric vertices, texture coordinates, vertex normals , polygonal faces:

# list of geometric vertices, (x,y,z[,w]) coordinates, w optional , defaults 1.0.
v 0.123 0.234 0.345 1.0
v ...
...
# list of texture coordinates, in (u, v [,w]) coordinates, these vary between 0 , 1, w optional , defaults 0.
vt 0.500 1 [0]
vt ...
...
# list of vertex normals in (x,y,z) form; normals might not unit vectors.
vn 0.707 0.000 0.707
vn ...
...
# parameter space vertices in ( u [,v] [,w] ) form; free form geometry statement ( see below )
vp 0.310000 3.210000 2.100000
vp ...
...
# polygonal face element (see below)
f 1 2 3
f 3/1 4/2 5/3
f 6/4/1 3/5/3 7/6/5
f 7//1 8//2 9//3
f ...
...

geometric vertex

a vertex can specified in line starting letter v. followed (x,y,z[,w]) coordinates. w optional , defaults 1.0. applications support vertex colors, putting red, green , blue values after x y , z. color values range 0 1.

parameter space vertices

a free-form geometry statement can specified in line starting string vp. define points in parameter space of curve or surface. u required curve points, u , v surface points , control points of non-rational trimming curves, , u, v , w (weight) control points of rational trimming curves.

face elements

faces defined using lists of vertex, texture , normal indices. polygons such quadrilaterals can defined using more 3 vertex/texture/normal indices.

obj files support free-form geometry use curves , surfaces define objects, such nurbs surfaces.

vertex indices

a valid vertex index matches corresponding vertex elements of defined vertex list. if index positive refers offset in vertex list, starting @ 1. if index negative relatively refers end of vertex list, -1 referring last element.

each face can contain 3 or more vertices.

f v1 v2 v3 ....

vertex texture coordinate indices

optionally, texture coordinate indices can used specify texture coordinates when defining face. add texture coordinate index vertex index when defining face, 1 must put slash after vertex index , put texture coordinate index. no spaces permitted before or after slash. valid texture coordinate index starts 1 , matches corresponding element in defined list of texture coordinates. each face can contain 3 or more elements.

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

vertex normal indices

optionally, normal indices can used specify normal vectors vertices when defining face. add normal index vertex index when defining face, 1 must put second slash after texture coordinate index , put normal index. valid normal index starts 1 , matches corresponding element in defined list of normals. each face can contain 3 or more elements.

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

vertex normal indices without texture coordinate indices

as texture coordinates optional, 1 can define geometry without them, 1 must put 2 slashes after vertex index before putting normal index.

f v1//vn1 v2//vn2 v3//vn3 ...

other geometry formats

obj files support higher-order surfaces using several different kinds of interpolation, such taylor , b-splines, although support features in third party file readers far universal. obj files not support mesh hierarchies or kind of animation or deformation, such vertex skinning or mesh morphing.

referencing materials

materials describe visual aspects of polygons stored in external .mtl files. more 1 external mtl material file may referenced within obj file. .mtl file may contain 1 or more named material definitions.

mtllib [external .mtl file name]
...

this tag specifies material name element following it. material name matches named material definition in external .mtl file.

usemtl [material name]
...

named objects , polygon groups specified via following tags.

o [object name]
...
g [group name]
...

smooth shading across polygons enabled smoothing groups.

s 1
...
# smooth shading can disabled well.
s off
...

relative , absolute indices

obj files, due list structure, able reference vertices, normals, etc. either absolute position (1 represents first defined vertex, n representing nth defined vertex), or relative position (-1 represents latest defined vertex).

however, not software supports latter approach, , conversely software inherently writes latter form (due convenience of appending elements without needing recalculate vertex offsets, etc.), leading occasional incompatibilities.