====== Object Files (.obj) ======
[[http://local.wasp.uwa.edu.au/~pbourke/dataformats/obj/| Full specification (c) Paul Bourke]]\\
[[http://local.wasp.uwa.edu.au/~pbourke/dataformats/mtl/| MTL material format (c) Diane Ramey, Linda Rose, and Lisa Tyerman]]
Object files define the geometry and other properties for objects in
Wavefront's Advanced Visualizer. Object files can also be used to
transfer geometric data back and forth between the Advanced Visualizer
and other applications.
Object files can be in ASCII format (.obj) or binary format (.mod).
This document describes the ASCII format for object files. These files
must have the extension .obj.
===== 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 normals (vn)
==== Elements ====
* point (p)
* line (l)
* face (f)
==== Grouping ====
* group name (g)
* smoothing group (s)
* merging group (mg)
* object name (o)
==== Display/render attributes ====
* bevel interpolation (bevel)
* color interpolation (c_interp)
* dissolve interpolation (d_interp)
* level of detail (lod)
* material name (usemtl)
* material library (mtllib)
* shadow casting (shadow_obj)
* ray tracing (trace_obj)
* curve approximation technique (ctech)
* surface approximation technique (stech)
===== Vertex data =====
Vertex data provides coordinates for:
* geometric vertices
* texture vertices
* vertex normals
The vertex data is represented by four vertex lists; one for each type
of vertex coordinate. A right-hand coordinate system is used to specify
the coordinate locations.
The following sample is a portion of an .obj file that contains the
four types of vertex information.
v -5.000000 5.000000 0.000000
v -5.000000 -5.000000 0.000000
v 5.000000 -5.000000 0.000000
v 5.000000 5.000000 0.000000
vt -5.000000 5.000000 0.000000
vt -5.000000 -5.000000 0.000000
vt 5.000000 -5.000000 0.000000
vt 5.000000 5.000000 0.000000
vn 0.000000 0.000000 1.000000
vn 0.000000 0.000000 1.000000
vn 0.000000 0.000000 1.000000
vn 0.000000 0.000000 1.000000
When vertices are loaded into the Advanced Visualizer, they are
sequentially numbered, starting with 1. These reference numbers are
used in element statements.
==== Syntax ====
The following syntax statements are listed in order of complexity.
v x y z w
Specifies a geometric vertex and its x y z coordinates. Rational
curves and surfaces require a fourth homogeneous coordinate, also
called the weight.
x y z are the x, y, and z coordinates for the vertex. These are
floating point numbers that define the position of the vertex in
three dimensions.
w is the weight required for rational curves and surfaces. It is
not required for non-rational curves and surfaces. If you do not
specify a value for w, the default is 1.0.
NOTE: A positive weight value is recommended. Using zero or
negative values may result in an undefined point in a curve or
surface.
vn i j k
Specifies a normal vector with components i, j, and k.
Vertex normals affect the smooth-shading and rendering of geometry.
For polygons, vertex normals are used in place of the actual facet
normals. For surfaces, vertex normals are interpolated over the
entire surface and replace the actual analytic surface normal.
When vertex normals are present, they supersede smoothing groups.
i j k are the i, j, and k coordinates for the vertex normal. They
are floating point numbers.
vt u v w
Specifies a texture vertex and its coordinates. A 1D texture
requires only u texture coordinates, a 2D texture requires both u
and v texture coordinates, and a 3D texture requires all three
coordinates.
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.
===== Elements =====
For polygonal geometry, the element types available in the .obj file
are:
* points
* lines
* faces
All elements can be freely intermixed in the file.
==== 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 with
1. 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
separated 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. Although points cannot be shaded or
rendered, they are used by other Advanced Visualizer programs.
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. Although
lines cannot be shaded or rendered, they are used by other Advanced
Visualizer programs.
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 are 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 are 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 counterclockwise 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.
If a face has a texture map assigned to it and no texture vertices
are assigned in the f statement, the texture map is ignored when
the element is rendered.
NOTE: Any references to fo (face outline) are no longer valid as of
version 2.11. You can use f (face) to get the same results.
References to fo in existing .obj files will still be read,
however, they will be written out as f when the file is saved.
==== Examples ====
These are examples for polygonal geometry.
For examples using free-form geometry, see the examples at the end of
the next section, "Free-form curve/surface body statements."
=== 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 counterclockwise. 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
=== 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
=== Cube with negative reference numbers ===
This is a cube with negative vertex reference numbers. Each element
references the vertices stored immediately above it in the file. Note
that vertices are not shared.
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
f -4 -3 -2 -1
v 2.000000 2.000000 0.000000
v 2.000000 0.000000 0.000000
v 0.000000 0.000000 0.000000
v 0.000000 2.000000 0.000000
f -4 -3 -2 -1
v 2.000000 2.000000 2.000000
v 2.000000 0.000000 2.000000
v 2.000000 0.000000 0.000000
v 2.000000 2.000000 0.000000
f -4 -3 -2 -1
v 0.000000 2.000000 0.000000
v 0.000000 2.000000 2.000000
v 2.000000 2.000000 2.000000
v 2.000000 2.000000 0.000000
f -4 -3 -2 -1
v 0.000000 2.000000 0.000000
v 0.000000 0.000000 0.000000
v 0.000000 0.000000 2.000000
v 0.000000 2.000000 2.000000
f -4 -3 -2 -1
v 0.000000 0.000000 2.000000
v 0.000000 0.000000 0.000000
v 2.000000 0.000000 0.000000
v 2.000000 0.000000 2.000000
f -4 -3 -2 -1
===== Grouping =====
There are four statements in the .obj file to help you manipulate groups
of elements:
* Group name statements are used to organize collections of elements and simplify data manipulation for operations in Model.
* Smoothing group statements let you identify elements over which normals are to be interpolated to give those elements a smooth, non-faceted appearance. This is a quick way to specify vertex normals.
* Merging group statements are used to ideneify free-form elements that should be inspected for adjacency detection. You can also use merging groups to exclude surfaces which are close enough to be considered adjacent but should not be merged.
* Object name statements let you assign a name to an entire object in a single file.
All grouping statements are state-setting. This means that once a
group statement is set, it alpplies to all elements that follow
until the next group statement.
This portion of a sample file shows a single element which belongs to
three groups. The smoothing group is turned off.
g square thing all
s off
f 1 2 3 4
This example shows two surfaces in merging group 1 with a merge
resolution of 0.5.
mg 1 .5
surf 0.0 1.0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16
surf 0.0 1.0 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32
==== Syntax ====
g group_name1 group_name2 . . .
Specifies the group name for the elements that follow it. You can
have multiple group names. If there are multiple groups on one
line, the data that follows belong to all groups. Group information
is optional.
group_name is the name for the group. Letters, numbers, and
combinations of letters and numbers are accepted for group names.
The default group name is default.
s group_number
Sets the smoothing group for the elements that follow it. If you do
not want to use a smoothing group, specify off or a value of 0.
To display with smooth shading in Model and PreView, you must
create vertex normals after you have assigned the smoothing groups.
You can create vertex normals with the vn statement or with the
Model program.
To smooth polygonal geometry for rendering with Image, it is
sufficient to put elements in some smoothing group. However, vertex
normals override smoothing information for Image.
group_number is the smoothing group number. To turn off smoothing
groups, use a value of 0 or off. Polygonal elements use group
numbers to put elements in different smoothing groups. For
free-form surfaces, smoothing groups are either turned on or off;
there is no difference between values greater than 0.
o object_name
Optional statement; it is not processed by any Wavefront programs.
It specifies a user-defined object name for the elements defined
after this statement.
object_name is the user-defined object name. There is no default.
==== Examples ====
=== Cube with group names ===
The following example is a cube with each of its faces placed in a
separate group. In addition, all elements belong to the group cube.
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
# 8 vertices
g front cube
f 1 2 3 4
g back cube
f 8 7 6 5
g right cube
f 4 3 7 8
g top cube
f 5 1 4 8
g left cube
f 5 6 2 1
g bottom cube
f 2 6 7 3
# 6 elements
=== Two adjoining squares with a smoothing group ===
This example shows two adjoining squares that share a common edge. The
squares are placed in a smoothing group to ensure that their common
edge will be smoothed when rendered with Image.
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
v 4.000000 0.000000 -1.255298
v 4.000000 2.000000 -1.255298
# 6 vertices
g all
s 1
f 1 2 3 4
f 4 3 5 6
# 2 elements
=== Two adjoining squares with vertex normals ===
This example also shows two squares that share a common edge. Vertex
normals have been added to the corners of each square to ensure that
their common edge will be smoothed during display in Model and PreView
and when rendered with Image.
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
v 4.000000 0.000000 -1.255298
v 4.000000 2.000000 -1.255298
vn 0.000000 0.000000 1.000000
vn 0.000000 0.000000 1.000000
vn 0.276597 0.000000 0.960986
vn 0.276597 0.000000 0.960986
vn 0.531611 0.000000 0.846988
vn 0.531611 0.000000 0.846988
# 6 vertices
# 6 normals
g all
s 1
f 1//1 2//2 3//3 4//4
f 4//4 3//3 5//5 6//6
# 2 elements
===== Display/render attributes =====
Display and render attributes describe how an object looks when
displayed in Model and PreView or when rendered with Image.
All display and render attribute statements are state-setting. This
means that once an attribute statement is set, it applies to all
elements that follow until it is reset to a different value.
The following sample shows rendering and display statements for a face
element.:
s 1
usemtl blue
usemap marble
f 1 2 3 4
==== Syntax ====
The following syntax statements are listed by the type of geometry.
First are statements for polygonal geometry. Second are statements for
both free-form and polygonal geometry. Third are statements for
free-form geometry only.
bevel on/off
Sets bevel interpolation on or off. It works only with beveled
objects, that is, objects with sides separated by beveled faces.
Bevel interpolation uses normal vector interpolation to give an
illusion of roundness to a flat bevel. It does not affect the
smoothing of non-bevelled faces.
Bevel interpolation does not alter the geometry of the original
object.
on turns on bevel interpolation.
off turns off bevel interpolation. The default is off.
NOTE: Image cannot render bevel-interpolated elements that have
vertex normals.
c_interp on/off
Sets color interpolation on or off.
Color interpolation creates a blend across the surface of a polygon
between the materials assigned to its vertices. This creates a
blending of colors across a face element.
To support color interpolation, materials must be assigned per
vertex, not per element. The illumination models for all materials
of vertices attached to the polygon must be the same. Color
interpolation applies to the values for ambient (Ka), diffuse (Kd),
specular (Ks), and specular highlight (Ns) material properties.
on turns on color interpolation.
off turns off color interpolation. The default is off.
d_interp on/off
Sets dissolve interpolation on or off.
Dissolve interpolation creates an interpolation or blend across a
polygon between the dissolve (d) values of the materials assigned
to its vertices. This feature is used to create effects exhibiting
varying degrees of apparent transparency, as in glass or clouds.
To support dissolve interpolation, materials must be assigned per
vertex, not per element. All the materials assigned to the vertices
involved in the dissolve interpolation must contain a dissolve
factor command to specify a dissolve.
on turns on dissolve interpolation.
off turns off dissolve interpolation. The default is off.
lod level
Sets the level of detail to be displayed in a PreView animation.
The level of detail feature lets you control which elements of an
object are displayed while working in PreView.
level is the level of detail to be displayed. When you set the
level of detail to 0 or omit the lod statement, all elements are
displayed. Specifying an integer between 1 and 100 sets the level
of detail to be displayed when reading the .obj file.
maplib filename1 filename2 . . .
This is a rendering identifier that specifies the map library file
for the texture map definitions set with the usemap identifier. You
can specify multiple filenames with maplib. If multiple filenames
are specified, the first file listed is searched first for the map
definition, the second file is searched next, and so on.
When you assign a map library using the Model program, Model allows
only one map library per .obj file. You can assign multiple
libraries using a text editor.
filename is the name of the library file where the texture maps are
defined. There is no default.
usemap map_name/off
This is a rendering identifier that specifies the texture map name
for the element following it. To turn off texture mapping, specify
off instead of the map name.
If you specify texture mapping for a face without texture vertices,
the texture map will be ignored.
map_name is the name of the texture map.
off turns off texture mapping. The default is off.
usemtl material_name
Specifies the material name for the element following it. Once a
material is assigned, it cannot be turned off; it can only be
changed.
material_name is the name of the material. If a material name is
not specified, a white material is used.
mtllib filename1 filename2 . . .
Specifies the material library file for the material definitions
set with the usemtl statement. You can specify multiple filenames
with mtllib. If multiple filenames are specified, the first file
listed is searched first for the material definition, the second
file is searched next, and so on.
When you assign a material library using the Model program, only
one map library per .obj file is allowed. You can assign multiple
libraries using a text editor.
filename is the name of the library file that defines the
materials. There is no default.
shadow_obj filename
Specifies the shadow object filename. This object is used to cast
shadows for the current object. Shadows are only visible in a
rendered image; they cannot be seen using hardware shading. The
shadow object is invisible except for its shadow.
An object will cast shadows only if it has a shadow object. You can
use an object as its own shadow object. However, a simplified
version of the original object is usually preferable for shadow
objects, since shadow casting can greatly increase rendering time.
filename is the filename for the shadow object. You can enter any
valid object filename for the shadow object. The object file can be
an .obj or .mod file. If a filename is given without an extension,
an extension of .obj is assumed.
Only one shadow object can be stored in a file. If more than one
shadow object is specified, the last one specified will be used.
trace_obj filename
Specifies the ray tracing object filename. This object will be used
in generating reflections of the current object on reflective
surfaces. Reflections are only visible in a rendered image; they
cannot be seen using hardware shading.
An object will appear in reflections only if it has a trace object.
You can use an object as its own trace object. However, a
simplified version of the original object is usually preferable for
trace objects, since ray tracing can greatly increase rendering
time.
filename is the filename for the ray tracing object. You can enter
any valid object filename for the trace object. You can enter any
valid object filename for the shadow object. The object file can be
an .obj or .mod file. If a filename is given without an extension,
an extension of .obj is assumed.
Only one trace object can be stored in a file. If more than one is
specified, the last one is used.
==== Examples ====
=== Cube with materials ===
This cube has a different material applied to each of its faces.
mtllib master.mtl
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
# 8 vertices
g front
usemtl red
f 1 2 3 4
g back
usemtl blue
f 8 7 6 5
g right
usemtl green
f 4 3 7 8
g top
usemtl gold
f 5 1 4 8
g left
usemtl orange
f 5 6 2 1
g bottom
usemtl purple
f 2 6 7 3
# 6 elements
=== Cube casting a shadow ===
In this example, the cube casts a shadow on the other objects when it
is rendered with Image. The cube, which is stored in the file cube.obj,
references itself as the shadow object.
mtllib master.mtl
shadow_obj cube.obj
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
# 8 vertices
g front
usemtl red
f 1 2 3 4
g back
usemtl blue
f 8 7 6 5
g right
usemtl green
f 4 3 7 8
g top
usemtl gold
f 5 1 4 8
g left
usemtl orange
f 5 6 2 1
g bottom
usemtl purple
f 2 6 7 3
# 6 elements
=== Cube casting a reflection ===
This cube casts its reflection on any reflective objects when it is
rendered with Image. The cube, which is stored in the file cube.obj,
references itself as the trace object.
mtllib master.mtl
trace_obj cube.obj
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
# 8 vertices
g front
usemtl red
f 1 2 3 4
g back
usemtl blue
f 8 7 6 5
g right
usemtl green
f 4 3 7 8
g top
usemtl gold
f 5 1 4 8
g left
usemtl orange
f 5 6 2 1
g bottom
usemtl purple
f 2 6 7 3
# 6 elements
=== Texture-mapped square ===
This example describes a 2 x 2 square. It is mapped with a 1 x 1 square
texture. The texture is stretched to fit the square exactly.
mtllib master.mtl
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
vt 0.000000 1.000000 0.000000
vt 0.000000 0.000000 0.000000
vt 1.000000 0.000000 0.000000
vt 1.000000 1.000000 0.000000
# 4 vertices
usemtl wood
f 1/1 2/2 3/3 4/4
# 1 element
===== Comments =====
Comments can appear anywhere in an .obj file. They are used to annotate
the file; they are not processed.
Here is an example:
# this is a comment
The Model program automatically inserts comments when it creates .obj
files. For example, it reports the number of geometric vertices,
texture vertices, and vertex normals in a file.
# 4 vertices
# 4 texture vertices
# 4 normals