Wavefront .obj file

Last updated
OBJ geometry format
Filename extension .obj
Internet media type text/plain
Developed by Wavefront Technologies
Type of format3D model format

OBJ (or .OBJ) is a geometry definition file format first developed by Wavefront Technologies for its Advanced Visualizer animation package. The file format is open and has been adopted by other 3D graphics application vendors.

Wavefront Technologies was a computer graphics company that developed and sold animation software used in Hollywood motion pictures and other industries. It was founded in 1984, in Santa Barbara, California, by Bill Kovacs, Larry Barels, Mark Sylvester. They started the company to produce computer graphics for movies and television commercials, and to market their own software, as there were no off-the-shelf computer animation tools available at the time. In 1995, Wavefront Technologies was purchased by Kroyer Films, Silicon Graphics, Rhythm & Hues and merged with Alias Research to form Alias|Wavefront.

The Advanced Visualizer (TAV), a 3D graphics software package, was the flagship product of Wavefront Technologies from the 1980s until the 1990s.


The OBJ file format is a simple data-format that represents 3D geometry alone namely, the position of each vertex, the UV position of each texture coordinate vertex, vertex normals, and the faces that make each polygon defined as a list of vertices, and texture vertices. Vertices are stored in a counter-clockwise order by default, making explicit declaration of face normals unnecessary. OBJ coordinates have no units, but OBJ files can contain scale information in a human readable comment line.

In geometry, a vertex is a point where two or more curves, lines, or edges meet. As a consequence of this definition, the point where two lines meet to form an angle and the corners of polygons and polyhedra are vertices.

UV mapping The process of projecting a 2D image to a 3D models surface for texture mapping.

UV mapping is the 3D modelling process of projecting a 2D image to a 3D model's surface for texture mapping. The letters "U" and "V" denote the axes of the 2D texture because "X", "Y" and "Z" are already used to denote the axes of the 3D object in model space.

Vertex normal

In the geometry of computer graphics, a vertex normal at a vertex of a polyhedron is a directional vector associated with a vertex, intended as a replacement to the true geometric normal of the surface. Commonly, it is computed as the normalized average of the surface normals of the faces that contain that vertex. The average can be weighted for example by the area of the face or it can be unweighted. Vertex normals can also be computed for polygonal approximations to surfaces such as NURBS, or specified explicitly for artistic purposes. Vertex normals are used in Gouraud shading, Phong shading and other lighting models. Using vertex normals, much smoother shading than flat shading can be achieved; however, without some modifications, it cannot produce a sharp edge.

File format

Lines beginning with a hash character (#) are comments.

# this is a 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 and display/render attribute information. The most common elements are geometric vertices, texture coordinates, vertex normals and polygonal faces:

  # List of geometric vertices, with (x, y, z [,w]) coordinates, w is optional and defaults to 1.0.   v 0.123 0.234 0.345 1.0   v ...   ...   # List of texture coordinates, in (u, [v ,w]) coordinates, these will vary between 0 and 1, v and w are optional and default to 0.   vt 0.500 1 [0]   vt ...   ...   # List of vertex normals in (x,y,z) form; normals might not be 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 ...   ...   # Line element (see below)   l 5 8 1 2 4 9

Geometric vertex

A vertex can be specified in a line starting with the letter v. That is followed by (x,y,z[,w]) coordinates. W is optional and defaults to 1.0. Some applications support vertex colors, by putting red, green and blue values after x y and z. The color values range from 0 to 1. [1]

Parameter space vertices

A free-form geometry statement can be specified in a line starting with the string vp. Define points in parameter space of a curve or surface. u only is required for curve points, u and v for surface points and control points of non-rational trimming curves, and u, v and w (weight) for control points of rational trimming curves.

Face elements

Faces are defined using lists of vertex, texture and normal indices which start at 1. Polygons such as quadrilaterals can be defined by using more than three vertex/texture/normal indices.

OBJ files also support free-form geometry which use curves and surfaces to define objects, such as NURBS surfaces.

Vertex indices

A valid vertex index matches the corresponding vertex elements of a previously defined vertex list. If an index is positive then it refers to the offset in that vertex list, starting at 1. If an index is negative then it relatively refers to the end of the vertex list, -1 referring to the last element.

Each face can contain three or more vertices.

f v1 v2 v3 ....

Vertex texture coordinate indices

Optionally, texture coordinate indices can be used to specify texture coordinates when defining a face. To add a texture coordinate index to a vertex index when defining a face, one must put a slash immediately after the vertex index and then put the texture coordinate index. No spaces are permitted before or after the slash. A valid texture coordinate index starts from 1 and matches the corresponding element in the previously defined list of texture coordinates. Each face can contain three or more elements.

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

Vertex normal indices

Optionally, normal indices can be used to specify normal vectors for vertices when defining a face. To add a normal index to a vertex index when defining a face, one must put a second slash after the texture coordinate index and then put the normal index. A valid normal index starts from 1 and matches the corresponding element in the previously defined list of normals. Each face can contain three or more elements.

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

Vertex normal indices without texture coordinate indices

As texture coordinates are optional, one can define geometry without them, but one must put two slashes after the vertex index before putting the normal index.

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

Line elements

Records starting with the letter "l" specify the order of the vertices which build a polyline.

l v1 v2 v3 v4 v5 v6 ...

Other geometry formats

Obj files support higher-order surfaces using several different kinds of interpolation, such as Taylor and B-splines, although support for those features in third party file readers is far from universal. Obj files also do not support mesh hierarchies or any kind of animation or deformation, such as vertex skinning or mesh morphing.

Referencing materials

Materials that describe the visual aspects of the polygons are stored in external .mtl files. More than one external MTL material file may be referenced from within the OBJ file. The .mtl file may contain one or more named material definitions.

mtllib [external .mtl file name]   ...

This tag specifies the material name for the element following it. The material name matches a named material definition in an external .mtl file.

usemtl [material name]   ...

Named objects and polygon groups are specified via the following tags.

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

Smooth shading across polygons is enabled by smoothing groups.

s 1   ...   # Smooth shading can be disabled as well.   s off   ...

Relative and absolute indices

OBJ files, due to their list structure, are able to reference vertices, normals, etc. either by their absolute position (1 represents the first defined vertex, N representing the Nth defined vertex), or by their relative position (-1 represents the latest defined vertex). However, not all software supports the latter approach, and conversely some software inherently writes only the latter form (due to the convenience of appending elements without needing to recalculate vertex offsets, etc.), leading to occasional incompatibilities.

Material template library

MTL material format
Filename extension .mtl
Developed by Wavefront Technologies
Type of format3D texture format

The Material Template Library format (MTL) or .MTL File Format is a companion file format to .OBJ, also defined by Wavefront Technologies, that describes surface shading (material) properties of objects within one or more .OBJ files. A .OBJ file references one or more .MTL files (called "material libraries"), and from there, references one or more material descriptions by name. .MTL files are ASCII text that define the light reflecting properties of a surface for the purposes of computer rendering, and according to the Phong reflection model. The standard has widespread support among different computer software packages, making it a useful format for interchange of materials.

ASCII American computer character encoding

ASCII, abbreviated from American Standard Code for Information Interchange, is a character encoding standard for electronic communication. ASCII codes represent text in computers, telecommunications equipment, and other devices. Most modern character-encoding schemes are based on ASCII, although they support many additional characters.

The Phong reflection model is an empirical model of the local illumination of points on a surface. In 3D computer graphics, it is sometimes referred to as "Phong shading", in particular if the model is used with the interpolation method of the same name and in the context of pixel shaders or other places where a lighting calculation can be referred to as “shading”.

The MTL format, although still widely used, is outdated and does not fully support later technologies such as specular maps and parallax maps. However, due to the open and intuitive nature of the format, these can easily be added with a custom MTL file generator.

The MTL format defines a number of formats. [2] [3]

Basic materials

A single .mtl file may define multiple materials. Materials are defined one after another in the file, each starting with the newmtl command:

# define a material named 'Colored'    newmtl Colored

The ambient color of the material is declared using Ka. Color definitions are in RGB where each channel's value is between 0 and 1.

Ka 1.000 1.000 1.000     # white

Similarly, the diffuse color is declared using Kd.

Kd 1.000 1.000 1.000     # white

The specular color is declared using Ks, and weighted using the specular exponent Ns.

Ks 0.000 0.000 0.000     # black (off) Ns 10.000                # ranges between 0 and 1000

Materials can be transparent. This is referred to as being dissolved. Unlike real transparency, the result does not depend upon the thickness of the object. A value of 1.0 for "d" is the default and means fully opaque, as does a value of 0.0 for "Tr".

d 0.9                    # some implementations use 'd' Tr 0.1                   # others use 'Tr' (inverted: Tr = 1 - d)

Multiple illumination models are available, per material. These are enumerated as follows:

0. Color on and Ambient off 1. Color on and Ambient on 2. Highlight on 3. Reflection on and Ray trace on 4. Transparency: Glass on, Reflection: Ray trace on 5. Reflection: Fresnel on and Ray trace on 6. Transparency: Refraction on, Reflection: Fresnel off and Ray trace on 7. Transparency: Refraction on, Reflection: Fresnel on and Ray trace on 8. Reflection on and Ray trace off 9. Transparency: Glass on, Reflection: Ray trace off 10. Casts shadows onto invisible surfaces
   illum 2

Texture maps

Textured materials use the same properties as above, and additionally define texture maps. Below is an example of a common material file. See the full wavefront file format reference for more details.

   newmtl Textured    Ka 1.000 1.000 1.000    Kd 1.000 1.000 1.000    Ks 0.000 0.000 0.000    d 1.0    illum 2    map_Ka lemur.tga           # the ambient texture map    map_Kd lemur.tga           # the diffuse texture map (most of the time, it will                               # be the same as the ambient texture map)    map_Ks lemur.tga           # specular color texture map    map_Ns lemur_spec.tga      # specular highlight component    map_d lemur_alpha.tga      # the alpha texture map    map_bump lemur_bump.tga    # some implementations use 'map_bump' instead of 'bump' below
   bump lemur_bump.tga        # bump map (which by default uses luminance channel of the image)    disp lemur_disp.tga        # displacement map    decal lemur_stencil.tga    # stencil decal texture (defaults to 'matte' channel of the image)

Texture map statements may also have option parameters (see full spec).

   map_Ka -o 1 1 1 ambient.tga            # texture origin (1,1,1)     refl -type sphere clouds.tga           # spherical reflection map

Texture options

    -blendu on | off                       # set horizontal texture blending (default on)     -blendv on | off                       # set vertical texture blending (default on)     -boost float_value                     # boost mip-map sharpness     -mm base_value gain_value              # modify texture map values (default 0 1)                                            #     base_value = brightness, gain_value = contrast     -o u [v [w]]                           # Origin offset             (default 0 0 0)     -s u [v [w]]                           # Scale                     (default 1 1 1)     -t u [v [w]]                           # Turbulence                (default 0 0 0)     -texres resolution                     # texture resolution to create     -clamp on | off                        # only render texels in the clamped 0-1 range (default off)                                            #   When unclamped, textures are repeated across a surface,                                            #   when clamped, only texels which fall within the 0-1                                            #   range are rendered.     -bm mult_value                         # bump multiplier (for bump maps only)       -imfchan r | g | b | m | l | z         # specifies which channel of the file is used to                                             # create a scalar or bump texture. r:red, g:green,                                            # b:blue, m:matte, l:luminance, z:z-depth..                                             # (the default for bump is 'l' and for decal is 'm')     bump -imfchan r bumpmap.tga            # says to use the red channel of bumpmap.tga as the bumpmap 

For reflection maps...

    -type sphere                           # specifies a sphere for a "refl" reflection map         -type cube_top    | cube_bottom |      # when using a cube map, the texture file for each           cube_front  | cube_back   |      # side of the cube is specified separately           cube_left   | cube_right 

Vendor specific alterations

Because of the ease in parsing the files, and the unofficial spreading of the file format, files may contain vendor specific alterations.

According to the spec, options are supposed to precede the texture filename. However, at least one vendor generates files with options at the end.

bump texbump.tga -bm 0.2               # bump multiplier of 0.2

Physically-based Rendering

The creators of the online 3D editing and modeling tool, Clara.io, proposed extending the MTL format to contain the following parameters to represent the physically-based rendering parameters: [4]

Pr/map_Pr     # roughness Pm/map_Pm     # metallic Ps/map_Ps     # sheen Pc            # clearcoat thickness Pcr           # clearcoat roughness Ke/map_Ke     # emissive aniso         # anisotropy anisor        # anisotropy rotation norm          # normal map, same format as "bump" parameter 

Further proposed extensions come from the DirectXMesh toolkit for Microsoft's DirectX engine, allowing the ability to define a model's pre-compiled RMA material. [5]

map_RMA       # RMA material (roughness, metalness, ambient occlusion) map_ORM       # alternate definition of map_RMA 

See also

Related Research Articles

Texture mapping method for defining high frequency detail, surface texture, or color information on a computer-generated graphic or 3D model

Texture mapping is a method for defining high frequency detail, surface texture, or color information on a computer-generated graphic or 3D model. Its application to 3D graphics was pioneered by Edwin Catmull in 1974.

Truevision TGA, often referred to as TARGA, is a raster graphics file format created by Truevision Inc.. It was the native format of TARGA and VISTA boards, which were the first graphic cards for IBM-compatible PCs to support Highcolor/truecolor display. This family of graphic cards was intended for professional computer image synthesis and video editing with PCs; for this reason, usual resolutions of TGA image files match those of the NTSC and PAL video formats.

Wings 3D software for modeling and texturing low to mid-range polygon models

Wings 3D is a free and open-source subdivision modeler inspired by Nendo and Mirai from Izware. Wings 3D is named after the winged-edge data structure it uses internally to store coordinate and adjacency data, and is commonly referred to by its users simply as Wings.

Polygon mesh

A polygon mesh is a collection of vertices, edges and faces that defines the shape of a polyhedral object in 3D computer graphics and solid modeling. The faces usually consist of triangles, quadrilaterals, or other simple convex polygons, since this simplifies rendering, but may also be composed of more general concave polygons, or polygons with holes.

Shader subroutine that may run on a graphics processing unit and is used to do shading, special effects, post processing, or general purpose computation

In computer graphics, a shader is a type of computer program that was originally used for shading but which now performs a variety of specialized functions in various fields of computer graphics special effects or does video post-processing unrelated to shading, or even functions unrelated to graphics at all.

In 3D computer graphics, Polygonal modeling is an approach for modeling objects by representing or approximating their surfaces using polygons. Polygonal modeling is well suited to scanline rendering and is therefore the method of choice for real-time computer graphics. Alternate methods of representing 3D objects include NURBS surfaces, subdivision surfaces, and equation-based representations used in ray tracers. See polygon mesh for a description of how polygonal models are represented and stored.

STL (file format) file format

STL is a file format native to the stereolithography CAD software created by 3D Systems. STL has several backronyms such as "Standard Triangle Language" and "Standard Tessellation Language". This file format is supported by many other software packages; it is widely used for rapid prototyping, 3D printing and computer-aided manufacturing. STL files describe only the surface geometry of a three-dimensional object without any representation of color, texture or other common CAD model attributes. The STL format specifies both ASCII and binary representations. Binary files are more common, since they are more compact.

A triangle strip is a series of connected triangles, sharing vertices, allowing for more efficient memory usage for computer graphics. They are more efficient than triangle lists without indexing, but usually equally fast or slower than indexed triangle lists. The primary reason to use triangle strips is to reduce the amount of data needed to create a series of triangles. The number of vertices stored in memory is reduced from 3N to N+2, where N is the number of triangles to be drawn. This allows for less use of disk space, as well as making them faster to load into RAM.

Triangle mesh

A triangle mesh is a type of polygon mesh in computer graphics. It comprises a set of triangles that are connected by their common edges or corners.

PLY (file format) file format

PLY is a computer file format known as the Polygon File Format or the Stanford Triangle Format. It was principally designed to store three-dimensional data from 3D scanners. The data storage format supports a relatively simple description of a single object as a list of nominally flat polygons. A variety of properties can be stored, including: color and transparency, surface normals, texture coordinates and data confidence values. The format permits one to have different properties for the front and back of a polygon. There are two versions of the file format, one in ASCII, the other in binary.

Kerkythea rendering software

Kerkythea is a standalone rendering system that supports raytracing and Metropolis light transport, uses physically accurate materials and lighting, and is distributed as freeware. Currently, the program can be integrated with any software that can export files in obj and 3ds formats, including 3ds Max, Blender, LightWave 3D, SketchUp, Silo and Wings3D.

3DS is one of the file formats used by the Autodesk 3ds Max 3D modeling, animation and rendering software.

A vertex in computer graphics is a data structure that describes certain attributes, like the position of a point in 2D or 3D space, or multiple points on a surface.

Additive manufacturing file format (AMF) is an open standard for describing objects for additive manufacturing processes such as 3D printing. The official ISO/ASTM 52915:2016 standard is an XML-based format designed to allow any computer-aided design software to describe the shape and composition of any 3D object to be fabricated on any 3D printer. Unlike its predecessor STL format, AMF has native support for color, materials, lattices, and constellations.

OFF is a geometry definition file format containing the description of the composing polygons of the 3D object.

Open Game Engine Exchange file format

The Open Game Engine Exchange (OpenGEX) format is a text-based file format designed to facilitate the transfer of complex 3D scene data between applications such as modeling tools and game engines. The OpenGEX format is built upon the data structure concepts defined by the Open Data Description Language (OpenDDL), a generic language for the storage of arbitrary data in human-readable format. The OpenGEX file format is registered with the Internet Assigned Numbers Authority (IANA) as the model/vnd.opengex media type.

In Computer graphics, Materials are an enhancement of texture mapping that allows for objects in 3D modelling packages and video games to simulate different types of materials in real life. They are typically used to enhance the realism of polygon meshes and other forms 3D model data.

This is a glossary of terms relating to computer graphics.

Art of Illusion

Art of Illusion is a free, open source software package for creating 3D-graphics.


  1. "How can I include vertex color information in .OBJ files?". Game Development Stack Exchange. Retrieved 2014-10-08.
  2. "MTL Files - Material Definitions for OBJ Files". People.sc.fsu.edu. 2004-06-14. Retrieved 2010-11-26.
  3. Author. "Wavefront .mtl file format info - GRIPES and GRUMBLES - Wings - Wings3D - Official Development Forum - Message Board". Nendowingsmirai.yuku.com. Retrieved 2010-11-26.
  4. "Exocortex | Extending Wavefront MTL for Physically-Based Rendering". exocortex.com.
  5. "Ability to define RMA texture in OBJ's MTL. by MattFiler · Pull Request #39 · microsoft/DirectXMesh". GitHub.