Community hub
0 subscribers7 pages, 0 posts
Recent from talks
All channels
Be the first to start a discussion here.
Be the first to start a discussion here.
Be the first to start a discussion here.
Be the first to start a discussion here.
Contribute something
Welcome to the community hub built to collect knowledge and have discussions related to Wavefront .obj file.
Nothing was collected or created yet.
Wavefront .obj file
View on Wikipediafrom Wikipedia
| OBJ geometry format | |
|---|---|
| Filename extension |
.obj |
| Internet media type |
model/obj [1] |
| Developed by | Wavefront Technologies |
| Type of format | 3D model format |
OBJ (or .OBJ) is a geometry definition file format first developed by Wavefront Technologies for The Advanced Visualizer animation package. It is an open file format and has been adopted by other 3D computer graphics application vendors.
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.
File format
[edit]Anything following a hash character (#) is a comment.
# 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, 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
[edit]A vertex is specified via a line starting with the letter v. That is followed by (x,y,z[,w]) coordinates. W is optional and defaults to 1.0. W scales the point. The point (x,y,z,w) corresponds to the point (x/w,y/w,z/w). A right-hand coordinate system is used to specify the coordinate locations. Some applications support vertex colors, by putting red, green and blue values after x y and z (this precludes specifying w). The color values range from 0 to 1.[2]
Parameter space vertices
[edit]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
[edit]Faces are defined using lists of vertex, texture and normal indices in the format vertex_index/texture_index/normal_index for which each index starts at 1 and increases corresponding to the order in which the referenced element was defined. Polygons such as quadrilaterals can be defined by using more than three indices.
OBJ files also support free-form geometry which use curves and surfaces to define objects, such as NURBS surfaces.
Vertex indices
[edit]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
[edit]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
[edit]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
[edit]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
[edit]Records starting with the letter "l" (lowercase L) specify the order of the vertices which build a polyline.
l v1 v2 v3 v4 v5 v6 ...
Other geometry formats
[edit]Obj files support higher-order surfaces using several different kinds of interpolation, such as Taylor and B-splines,[3] 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.
Reference materials
[edit]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
[edit]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.[citation needed]
Material template library
[edit]| MTL material format | |
|---|---|
| Filename extension |
.mtl |
| Internet media type |
model/mtl [4] |
| Magic number |
|
| Developed by | Wavefront Technologies |
| Type of format | 3D 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.
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.[6][7]
Basic materials
[edit]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.
# white Ka 1.000 1.000 1.000
Similarly, the diffuse color is declared using Kd.
# white Kd 1.000 1.000 1.000
The specular color is declared using Ks, and weighted using the specular exponent Ns.
# black (off) Ks 0.000 0.000 0.000 # ranges between 0 and 1000 Ns 10.000
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" (dissolve) is the default and means fully opaque, as does a value of 0.0 for "Tr". Dissolve works on all illumination models.
# some implementations use 'd' d 0.9 # others use 'Tr' (inverted: Tr = 1 - d) Tr 0.1
Transparent materials can additionally have a Transmission Filter Color, specified with "Tf".
# Transmission Filter Color (using R G B) Tf 1.0 0.5 0.5 # Transmission Filter Color (using CIEXYZ) - y and z values are optional and assumed to be equal to x if omitted Tf xyz 1.0 0.5 0.5 # Transmission Filter Color from spectral curve file (not commonly used) Tf spectral <filename>.rfl <optional factor>
A material can also have an optical density for its surface. This is also known as index of refraction.
# optical density Ni 1.45000
Values can range from 0.001 to 10. A value of 1.0 means that light does not bend as it passes through an object. Increasing the optical density increases the amount of bending. Glass has an index of refraction of about 1.5. Values of less than 1.0 produce bizarre results and are not recommended.[8]
Multiple illumination models are available, per material. Note that it is not required to set a transparent illumination model in order to achieve transparency with "d" or "Tr", and in modern usage illum models are often not specified, even with transparent materials. The illum models 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
[edit]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 # the ambient texture map map_Ka lemur.tga # the diffuse texture map (most of the time, it will be the same as the # ambient texture map) map_Kd lemur.tga # specular color texture map map_Ks lemur.tga # specular highlight component map_Ns lemur_spec.tga # the alpha texture map map_d lemur_alpha.tga # some implementations use 'map_bump' instead of 'bump' below map_bump lemur_bump.tga # bump map (which by default uses luminance channel of the image) bump lemur_bump.tga # displacement map disp lemur_disp.tga # stencil decal texture (defaults to 'matte' channel of the image) decal lemur_stencil.tga
Texture map statements may also have option parameters (see full spec).
# texture origin (1,1,1) map_Ka -o 1 1 1 ambient.tga # spherical reflection map refl -type sphere clouds.tga
Texture options
[edit]-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')
For example,
# says to use the red channel of bumpmap.tga as the bumpmap bump -imfchan r bumpmap.tga
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
[edit]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 multiplier of 0.2 bump texbump.tga -bm 0.2
Physically-based rendering
[edit]The creators of the online 3D editing and modeling tool, Clara.io, proposed extending the MTL format to enable specifying physically-based rendering (PBR) maps and parameters. This extension has been subsequently adopted by Blender and TinyObjLoader. The extension PBR maps and parameters are:[9]
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 (RGB components represent XYZ components of the surface normal)
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.[10]
map_RMA # RMA material (roughness, metalness, ambient occlusion) map_ORM # alternate definition of map_RMA
See also
[edit]- glTF
- Object file
- OFF (file format)
- Relocatable Object Module Format
- STL (file format)
- PLY (file format) is an alternative file format offering more flexibility than most stereolithography applications.
References
[edit]- ^ Media subtype name: obj
- ^ "How can I include vertex color information in .OBJ files?". Game Development Stack Exchange. Archived from the original on 2014-10-14. Retrieved 2014-10-08.
- ^ "Wavefront OBJ: Summary from the Encyclopedia of Graphics File Formats". www.fileformat.info. Archived from the original on 2025-01-14. Retrieved 2025-02-13.
- ^ "Media subtype name: mtl". Archived from the original on 2021-04-12. Retrieved 2021-04-28.
- ^ "Wavefront Material Template Library (MTL) File Format". Library of Congress. 4 October 2019. Archived from the original on 12 April 2021. Retrieved 29 April 2021.
- ^ "MTL Files - Material Definitions for OBJ Files". People.sc.fsu.edu. 2004-06-14. Archived from the original on 2010-06-13. Retrieved 2010-11-26.
- ^ "Wavefront .mtl file format info - GRIPES and GRUMBLES - Wings - Wings3D - Official Development Forum - Message Board". Nendowingsmirai.yuku.com. July 2002. Archived from the original on 2011-07-18. Retrieved 2010-11-26.
- ^ Ramey, Diane (1995). "MTL material format (Lightwave, OBJ)". Alias-Wavefront, Inc. Archived from the original on November 12, 2016. Retrieved May 17, 2020.
- ^ "Ben Houston | Extending Wavefront MTL for Physically-Based Rendering". benhouston3d.com.
- ^ "Ability to define RMA texture in OBJ's MTL. by MattFiler · Pull Request #39 · microsoft/DirectXMesh". GitHub.
External links
[edit]- Appendix B1. Object Files (.obj), Advanced Visualizer Manual
- Mtl Specification
- Tools, libraries and example files
- FileFormat.Info: Wavefront OBJ File Format Summary
Wavefront .obj file
View on Grokipediafrom Grokipedia
The Wavefront .obj file, commonly known as the OBJ format, is an open, text-based standard for storing 3D geometry data, including vertices, normals, texture coordinates, and polygonal faces, enabling the representation of static 3D models without support for animations or skeletal structures.[1] Developed in the late 1980s by Wavefront Technologies—a pioneering computer graphics firm founded in 1984—for its Advanced Visualizer animation software, the format emerged as a key tool for 3D modeling in film, visual effects, and early computer graphics applications, such as those used in productions like The Abyss.[2][3]
Originally designed to facilitate geometry exchange within Wavefront's ecosystem, the OBJ format gained widespread adoption due to its simplicity and human-readable ASCII structure, which uses keyword-prefixed lines (e.g.,
This illustrates logical sequencing for readability, though parsers must tolerate variations such as missing optional elements or invalid lines by skipping them to ensure robustness.[1] The
This connects the first three vertices, their first three texture coordinates, and the first three normals to form a front-facing triangular face.[13]
The .obj format imposes no fixed limit on the number of vertices per face, permitting n-gons for efficiency in describing surfaces, though convex polygons are recommended to ensure reliable tessellation and avoid self-intersection artifacts during rendering.[4] Degenerate faces, such as those with repeated or collinear vertices resulting in zero area, are typically ignored by compliant parsers to maintain model integrity.[1]
Here, the "Cube" object contains two groups with distinct materials and the first group smoothed.[20]
This example illustrates the comment header and sequential material blocks, with parsing proceeding from top to bottom to accumulate all defined materials.[24]
Support for multiple MTL files is provided by allowing several
This format promotes interoperability across 3D modeling tools that support the Wavefront specification.[25]
v for vertices, f for faces) to define elements like points, lines, polygons, free-form curves, and surfaces up to degree 20.[4] It often pairs with a companion Material Template Library (MTL) file for specifying surface properties like colors, textures, and reflectivity, though the core OBJ focuses solely on geometry.[5] This combination supports both basic polygonal meshes and more complex NURBS (non-uniform rational B-splines) for precise surface modeling, making it a versatile interchange format across diverse 3D software, including Autodesk 3ds Max, Blender, and Maya.[6][7]
Despite its age, the format remains prevalent in industries like 3D printing, game development, and CAD due to its uncompressed, platform-independent nature and broad compatibility, though it lacks built-in compression, hierarchy support, or advanced features like quaternions, leading to large file sizes for complex models.[2] Following Wavefront's acquisition by Silicon Graphics in 1995 and subsequent merger with Alias to form Alias|Wavefront (later Autodesk), the format evolved minimally but solidified as a de facto standard for geometry export and import.[8]
Overview and History
Development History
Wavefront Technologies was founded on June 4, 1984, in Santa Barbara, California, by Bill Kovacs, Mark Sylvester, and Larry Barels, with a focus on developing software for computer graphics and animation in the emerging field of 3D modeling and rendering.[9] The company quickly established itself as a pioneer in high-end visual effects tools, targeting industries such as film and advertising. The .obj file format originated in the late 1980s as part of Wavefront's Advanced Visualizer software package, which was designed to handle 3D geometry data for animation and rendering workflows.[2] This text-based format allowed for the efficient storage and exchange of polygonal models, vertices, and related geometric elements within the proprietary ecosystem of Wavefront's tools. In February 1995, Silicon Graphics Inc. (SGI) acquired Wavefront Technologies for approximately $490 million in stock and merged it with Alias Research to create Alias|Wavefront, significantly expanding the format's reach through integration with SGI's hardware and broader software distribution.[10][11] The .obj format is an open, non-proprietary standard focused solely on geometry, free from licensing restrictions, which has facilitated its adoption across diverse applications including film production, computer-aided design (CAD), and 3D printing.[1] The format saw its initial introduction in the late 1980s, followed by expansion in the 1990s through the SGI and Alias|Wavefront ecosystem, and has maintained stability without major revisions into 2025, remaining a foundational interchange format due to its simplicity and interoperability.[1]Purpose and Characteristics
The Wavefront .obj file format serves primarily as a standard for storing 3D geometry data, including vertices, faces, and normal vectors, to facilitate the exchange of polygonal models between different software applications.[1][12] It focuses exclusively on static surface geometry and does not support advanced features such as animation, skeletal rigging, or complex scene hierarchies with lights and cameras.[5] This design emphasis on simplicity makes it ideal for transferring basic 3D models without proprietary dependencies, originally developed for use in Wavefront Technologies' software tools.[13] Key characteristics of the .obj format include its use of plain text in ASCII encoding, which enhances human readability and ease of editing with standard text editors.[1] It supports a range of geometric elements, such as polygonal meshes, freeform curves, and surfaces, while remaining lightweight due to its minimalistic structure and non-proprietary nature, allowing open implementation across platforms.[12] Although binary variants exist, the ASCII form predominates for its accessibility, though it lacks built-in compression, potentially leading to larger file sizes for complex models.[13] Common applications of .obj files span several industries, including 3D printing for model preparation, game development for asset import and export, computer-aided design (CAD) for interoperability between tools, and film visual effects for geometry exchange in production pipelines.[14][15] The format's strengths lie in its simplicity and broad compatibility with popular software like Blender, Autodesk Maya, and Unity, enabling seamless workflow integration without specialized converters.[16][17][18] However, its limitations to static geometry and absence of native compression can pose challenges for high-fidelity or dynamic content.[5] Files typically use the .obj extension and are often paired with a separate .mtl file for material definitions, with the standard MIME type being model/obj.[1][19]Core File Format
Basic Syntax and Structure
The Wavefront .obj file format is a plain text, line-based structure designed for defining 3D geometry, where each non-comment line begins with a keyword identifier followed by space-separated numeric or string values specific to that keyword.[4] This line-oriented parsing allows for straightforward sequential reading, with whitespace (spaces or tabs) serving as delimiters between tokens, though strict matching of the leading keyword is required for interpretation.[1] Blank lines are typically ignored by parsers, and long lines can be continued onto the next line using a backslash () at the end of the line to be split.[1] Comments in .obj files are denoted by lines starting with the # symbol, extending to the end of the line, and are commonly used for headers, metadata, or explanatory notes at the beginning of the file, though no formal header is mandated.[13] The overall file organization is flexible and sequential, without a rigid required order for elements, but conventionally begins with optional comments followed by definitions of geometric primitives (such as vertices) and then referencing elements (such as faces or lines) that index into those definitions; this supports the creation of multiple objects or groups within a single file.[4] Data types are primarily floating-point numbers (in decimal format) for spatial coordinates and parameters, with integer values (1-based indexing) used for references to previously defined elements like vertices.[20] Key keywords in the format includev for geometric vertices, vt for texture vertices, vn for normal vectors, f for polygonal faces, l for polyline elements, o for object names, g for grouping, usemtl for applying materials, and mtllib for linking to an external Material Template Library (MTL) file.[4] These directives enable modular organization, where geometry data is defined globally and then referenced by index in subsequent elements, allowing efficient reuse across faces or lines.[13]
A representative example of basic structure might appear as follows, starting with comments, followed by vertex definitions, and then face references:
# Simple [cube](/page/Cube) model
# Created on November 08, 2025
v 1.0 1.0 1.0
v -1.0 1.0 1.0
v -1.0 -1.0 1.0
v 1.0 -1.0 1.0
v 1.0 1.0 -1.0
v -1.0 1.0 -1.0
v -1.0 -1.0 -1.0
v 1.0 -1.0 -1.0
f 1 2 3 4
f 5 6 7 8
f 1 5 8 4
f 2 6 7 3
f 1 2 6 5
f 4 3 7 8
# Simple [cube](/page/Cube) model
# Created on November 08, 2025
v 1.0 1.0 1.0
v -1.0 1.0 1.0
v -1.0 -1.0 1.0
v 1.0 -1.0 1.0
v 1.0 1.0 -1.0
v -1.0 1.0 -1.0
v -1.0 -1.0 -1.0
v 1.0 -1.0 -1.0
f 1 2 3 4
f 5 6 7 8
f 1 5 8 4
f 2 6 7 3
f 1 2 6 5
f 4 3 7 8
mtllib keyword can reference an external MTL file for materials, but detailed material handling is separate from core geometry syntax.[4]
Geometric Vertices
Geometric vertices in the Wavefront .obj file format represent the foundational 3D positions of points that define the geometry of objects, such as polygons or curves. They are specified using the keywordv followed by three floating-point coordinates , , and , which denote the location in a right-handed coordinate system in world space.[4] An optional fourth coordinate , also a floating-point value, may follow for homogeneous coordinates or rational curve/surface representations, defaulting to 1.0 if omitted.[4]
The format for a geometric vertex line is v x y z [w], where the coordinates are typically stored as single- or double-precision floating-point numbers, though the specification does not enforce a particular precision level. No units are specified for the coordinates, so they are assumed to be consistent within the model, often in arbitrary units like meters or centimeters depending on the originating application. While primarily designed for 3D geometry, the format supports 2D representations by setting , and theoretically 1D by setting , though 3D is the standard use case.[4][1]
These vertices are numbered sequentially starting from 1 in the order they appear in the file, providing indices for referencing in subsequent elements like faces or lines. For example, the line v 0.0 1.0 0.0 defines a vertex at position , which could represent a point along the positive y-axis in a unit cube model. Another example with the optional is v -5.000000 5.000000 0.000000 1.0, specifying a vertex at with explicit homogeneous weight. Positive values for are recommended, as zero or negative values may lead to undefined behavior in certain rendering contexts.[4]
Texture and Parameter Vertices
Texture vertices in the Wavefront .obj file format are specified using thevt keyword, followed by floating-point coordinates that define points in a parameter space for mapping textures or other parameters onto geometric elements.[4] The basic syntax is vt u v [w], where u and v represent the primary texture coordinates, typically ranging from 0 to 1 to correspond with the normalized space of a 2D texture image, and the optional w parameter provides a third dimension for more advanced mappings.[4] Typically, u corresponds to the horizontal axis and v to the vertical axis of the texture, with the origin at the bottom-left corner. If w is omitted, it defaults to 0.[4]
The primary purpose of texture vertices is to establish how 2D (or higher-dimensional) textures, such as images or procedural patterns, are projected onto the surfaces defined by geometric vertices, enabling accurate UV mapping without altering the 3D positions.[1] These coordinates form a separate list from geometric vertices, allowing faces to reference them independently via distinct indices in face definitions, such as f 1/1 2/2 3/3 where the second index per vertex points to the texture vertex.[4] Beyond standard UV texturing, texture vertices can parameterize other spaces, including environment mappings or procedural attribute distributions, providing flexibility for shading and material applications.[4]
For example, a simple midpoint on a texture might be declared as vt 0.5 0.5, indicating the center of a 2D texture space for application to a corresponding geometric point.[4] In 1D textures, only the u coordinate is required; for 2D, both u and v are used; and for 3D volumetric textures, all three (u, v, w) are specified.[4] Compatibility varies across software, with some parsers assuming 2D coordinates and skipping w unless explicitly handling rational curves or free-form surfaces, ensuring broad support for basic texturing workflows.[4]
Normal Vectors
Normal vectors in the Wavefront .obj file format are defined using the "vn" keyword followed by three floating-point numbers representing the x, y, and z components of a directional vector associated with a vertex.[4][1] These components specify the orientation of the surface at that vertex, typically as a unit vector with a length of 1.0 to ensure consistent shading calculations, though the format does not enforce normalization.[5] The syntax isvn i j k, where i, j, and k are the coordinate values in a right-handed coordinate system, and normals are listed sequentially with 1-based indexing.[4]
The primary purpose of vertex normals is to facilitate smooth shading and accurate lighting in 3D rendering by providing per-vertex direction information that is interpolated across polygon faces.[1][5] Unlike geometric vertices, which define position, normals influence how light interacts with the surface without altering its geometry, enabling effects like Gouraud or Phong shading.[4] For example, a normal pointing upward along the y-axis would be written as vn 0.0 1.0 0.0.[5] When referenced in face elements, such as f 1//1, the normal index follows the vertex index with slashes, allowing separate specification from positional data.[4]
Vertex normals can be explicitly provided in the file or automatically generated by 3D modeling software if omitted, often computed from face geometry for per-face or per-vertex application.[5][1] Software like Blender supports both approaches, prioritizing explicit normals when present to override any smoothing groups.[1] While not required to be unit length, normalization is recommended during import to avoid distortions in lighting; the format treats them as optional components that enhance rendering fidelity without affecting the core mesh structure.[4]
Face and Polygon Elements
Face elements in the Wavefront .obj file format define the polygonal surfaces of 3D models by connecting vertices to form closed shapes. These elements use the keyword "f" followed by a space-separated list of indices referencing geometric vertices, and optionally texture vertices and normal vectors.[4] The format supports polygons with arbitrary numbers of sides, including common types like triangles (three vertices) and quadrilaterals (four vertices), enabling the representation of complex meshes through multiple such definitions.[5] The syntax for a face isf v1[/vt1[/vn1]] v2[/vt2[/vn2]] ... vn[/vtn[/vnn]], where each vi is the index of a geometric vertex, vti (if present) is the corresponding texture vertex index, and vni (if present) is the normal vector index; the slashes separate these components, and omitted parts are indicated by consecutive slashes or absence.[4] Multiple combinations of indices are supported to accommodate varying levels of detail: the complete form v/vt/vn includes position, texture, and normal data; v//vn omits texture coordinates; v/vt excludes normals; and simply v uses only vertex positions.[5] Indices are one-based positive integers referencing earlier declarations in the file, with negative values indicating relative positioning from the end of the current list in some implementations.[13]
The order of vertices in a face definition follows a counter-clockwise winding convention when viewed from the front-facing side, consistent with the right-hand rule for determining surface orientation in rendering pipelines.[4]
A representative example for a triangle incorporating all index types is:
f 1/1/1 2/2/2 3/3/3
f 1/1/1 2/2/2 3/3/3
Line and Curve Elements
Line elements in the Wavefront .obj file format are defined using thel keyword, which specifies line segments or polylines by referencing indices of geometric vertices, and optionally texture coordinates.[4] This allows for the representation of edges or paths in 3D models, connecting two or more points in sequence. For a simple polyline connecting four vertices, the syntax is l v1 v2 v3 v4, where v1 through v4 are positive integer indices starting from 1.[21] To include texture mapping along the line, texture vertex indices can be appended after slashes, as in l 1/1 2/2 3/3 4/4, where the numbers after each slash refer to indices from the texture vertex list defined earlier in the file.[4] These elements are particularly useful for wireframe representations or outlining features in models, though they are less commonly used compared to polygonal faces in typical 3D graphics applications.[5]
Curve and surface elements extend the format to support more complex, parametric geometries, primarily through free-form definitions that approximate NURBS-like structures using control points.[21] These are introduced with keywords like curv for 3D curves, curv2 for 2D curves (often used in parameter space), and surf for surfaces, each preceded by supporting statements that define their properties.[4] The cstype keyword specifies the curve or surface type, with syntax cstype [rat | non-rat] [s | u | v] [basis | factor | step] type, where "rat" or "non-rat" indicates rational (weighted) or non-rational control points, the second parameter selects the domain (s for both u and v, or u/v separately), and "type" can be "bezier", "bspline", "cardinal", or "taylor".[21] For instance, cstype rat s bezier declares a rational Bézier surface. The degree is set with deg u du v dv, such as deg 3 3 for cubic curves in both u and v directions.[4]
Parameter ranges are defined using parm, with syntax parm [u | v] [r | map] [min max], for example, parm u 0 1 to set the u-parameter from 0 to 1.[4] Control points for these elements reference parameter vertices (defined with p keyword) rather than just geometric vertices, allowing precise control over the curve's shape; a curv 4 statement followed by four lines of parameter indices like p 1 2 3 4 defines a curve with four control points.[21] For surfaces, surf nu nv specifies the number of control points in u and v directions, followed by a grid of parameter indices. Trimming is handled with trimloop to start a loop (trimloop closed), trim to define trim curves via parameter pairs (e.g., trim u 0 1 0.5 0.5), and end to close it; holes within loops use hole.[4] Resolution for rendering trimmed surfaces can be controlled with step u su v sv, such as step 0.1 0.1 to set step sizes in parameter space.[21]
These curve and surface elements, while part of the core format since its development for CAD and animation workflows, are rarely encountered in modern .obj files, which predominantly feature polygonal meshes for efficiency in rendering pipelines.[5] They find niche applications in importing legacy CAD data or representing smooth contours in specialized modeling tools that support Bézier or B-spline approximations.[4]
Grouping and Object Definitions
In the Wavefront .obj file format, grouping and object definitions provide mechanisms to organize geometric elements into logical units, facilitating the management of complex models and scenes by dividing them into named objects and subgroups.[22] These features allow for modular construction, where multiple objects or groups can represent distinct parts of a 3D model, such as components of a vehicle or architectural elements, enabling selective rendering, editing, or export in software applications.[13] The definitions remain active until overridden by a subsequent declaration or the end of the file, ensuring that subsequent vertices, faces, or other elements are associated with the current object or group.[20] Theo keyword initiates a new object block by specifying a name, as in o object_name, which delimits a section of the file dedicated to that object and resets any prior group or material assignments within the broader file context.[22] This is particularly useful for multi-part models, where each o declaration encapsulates geometry for an independent entity, such as o [Cube](/page/Cube) followed by vertices and faces specific to that cube. Objects can contain multiple groups and material assignments, promoting hierarchical organization without nesting syntax.[13]
Groups are defined using the g keyword, followed by one or more names, such as g group_name1 [group_name2 ...], which assigns subsequent geometric elements—like faces or lines—to those named groups, supporting both flat and hierarchical structures through sequential naming conventions.[20] For instance, g FrontFace would tag following faces as part of the "FrontFace" group, allowing software to isolate or manipulate that subset; hierarchical groups can be implied by naming patterns like g Body/Panel/Door, though the format does not enforce strict tree structures.[22] This enables complex scenes to be broken into reusable or layered components, with groups applying until a new g, o, or file end.[13]
Material assignment within objects or groups is handled by the usemtl keyword, as in usemtl material_name, which applies a predefined material from an associated .mtl file to all subsequent geometric elements until changed.[20] This allows seamless integration of surface properties, such as usemtl red to color following faces red, without altering the core geometry definitions.[22]
Smoothing groups control the interpolation of normals across faces for shading purposes, specified via the s keyword followed by a group number, such as s 1 to enable smoothing within that group or s off (equivalent to 0) to disable it and treat faces as flat-shaded.[13] Group numbers are positive integers, where shared numbers indicate faces that share normals for smooth transitions, effectively defining crease angles by isolating groups with distinct numbers; this applies to subsequent elements until redefined.[22]
A representative example illustrates these features:
o Cube
g FrontFace
usemtl red
s 1
f 1 2 3
g SideFace
usemtl blue
f 4 5 6
o Cube
g FrontFace
usemtl red
s 1
f 1 2 3
g SideFace
usemtl blue
f 4 5 6
Material Template Library (MTL)
File Structure and Linking
The Wavefront .obj file format supports external material definitions through a companion file known as the Material Template Library (MTL), which is referenced using themtllib keyword within the .obj file. This keyword appears on a dedicated line, followed by the path to one or more .mtl files, such as mtllib materials.mtl, allowing the parser to load the specified material libraries before processing geometric elements that may reference them.[23][13]
The MTL file itself is a text-based format stored in ASCII, with UTF-8 encoding recommended for modern implementations to support international characters in comments or names, though the original specification assumes plain ASCII.[24] Similar to the .obj file, it consists of newline-delimited lines, beginning with optional comment lines prefixed by # for documentation or metadata, followed by sequential blocks defining individual materials. Each material block starts with the newmtl keyword followed by a unique alphanumeric name, such as newmtl red, enclosing the properties for that material until the next newmtl or the end of the file.[24][23] This structure enables straightforward parsing, where software reads the file line by line, ignoring comments and recognizing keywords to build a material dictionary.[24]
MTL files are typically organized as one per .obj file for self-contained models, but they can be shared across multiple .obj files to promote reuse of material definitions in larger scenes or asset libraries.[23] For instance, a simple .obj file might include the line mtllib scene.mtl near the top, while the corresponding scene.mtl could begin as follows:
# Material library for sample scene
newmtl default
# Material properties here
newmtl red
# Material library for sample scene
newmtl default
# Material properties here
newmtl red
mtllib declarations in a single .obj file, either on separate lines or comma-separated on one line; parsers load all referenced files, merging their contents into a single material set, with later definitions overriding any duplicates by name.[4] The materials from these libraries are then applied to geometric elements in the .obj file via the usemtl keyword within object or group definitions.[13]
Material Declaration and Naming
In the Material Template Library (MTL) format, which accompanies Wavefront .obj files to define surface properties, individual materials are declared using thenewmtl keyword followed by a material name. This statement initiates a new material block, where the name serves as a unique identifier for the material within the file.[24]
The material name specified after newmtl must be a string without spaces, typically composed of alphanumeric characters and underscores, and it is case-sensitive. Names can be of any reasonable length but must remain unique across the entire MTL file to avoid conflicts during parsing. For instance, a declaration might appear as newmtl diffuse_red, marking the start of properties for a material named "diffuse_red". This naming convention ensures straightforward referencing and prevents ambiguity in material assignments.[24][25]
Following the newmtl declaration, the material block consists of subsequent lines defining various attributes until another newmtl statement begins a new block or the file ends. This sequential structure allows multiple materials to be defined in a single MTL file, each encapsulated in its own block for modular organization.[24]
To apply a declared material to geometry in the corresponding .obj file, the usemtl keyword is used, specifying the exact material name from the MTL file. This command precedes faces or groups in the .obj, switching the active material for rendering or processing those elements. The MTL file is linked to the .obj via a mtllib statement at the top of the .obj file.[24]
If no usemtl statement is encountered in the .obj file, no specific material from the MTL is applied to the geometry, resulting in undefined behavior that depends on the implementing software—often defaulting to a basic or no-material state.[24]
The following example illustrates a simple material declaration in an MTL file:
newmtl example_material
# Material properties would follow here
newmtl example_material
# Material properties would follow here
Basic Material Attributes
The Material Template Library (MTL) format specifies basic material attributes through scalar values and RGB color triples, enabling simple shading models for 3D objects in the Wavefront .obj ecosystem. These attributes primarily support the Phong illumination model and its variants, defining how surfaces interact with light via ambient, diffuse, specular, and emissive components. Colors are represented as floating-point values in the range 0.0 to 1.0 for red (r), green (g), and blue (b) channels, allowing for a wide gamut of surface appearances without requiring texture maps.[24][23] The ambient reflectivity attribute, denoted asKa r g b, sets the color coefficient for ambient lighting, which simulates uniform environmental illumination unaffected by surface orientation. Values for r, g, and b range from 0.0 (no reflection) to 1.0 (full reflection), with a default of 0.2 0.2 0.2 if unspecified. This property contributes to the overall base tone of the material under low-light conditions.[24]
Diffuse reflectivity, specified by Kd r g b, defines the base color of the material for Lambertian (diffuse) lighting, representing the proportion of light scattered equally in all directions. Like Ka, the r, g, b components are in 0.0 to 1.0, and this attribute often serves as the primary color descriptor for non-shiny surfaces, with a default of 0.6 0.6 0.6. For example, Kd 1.0 0.0 0.0 establishes a red diffuse color, evoking a matte crimson appearance.[24]
Specular reflectivity is controlled by Ks r g b, which determines the color of specular highlights from direct light sources, simulating glossy or metallic sheen. The r, g, b values follow the same 0.0-1.0 range, defaulting to 0.0 0.0 0.0 (no specular). The sharpness of these highlights is adjusted via the shininess exponent Ns value, a scalar from 0 (broad, matte highlights) to 1000 (sharp, mirror-like), with a default of 0 indicating no specular contribution.[24]
The illumination model is selected with illum n, an integer from 0 to 10 that dictates which lighting components are active. Value 0 disables all lighting (constant color); 1 enables only ambient and diffuse; 2 activates ambient, diffuse, and specular (standard Phong); higher values (3-10) introduce variants like shadows, ray tracing, or glass refraction, though support varies by renderer. The default is 0 in the original specification, though many implementations use 2 for full shading.[24]
Opacity is handled by the dissolve factor d factor, a scalar from 0.0 (fully transparent) to 1.0 (fully opaque), which modulates alpha blending during rendering. An alternative, the transmission filter Tr factor (0.0 to 1.0), specifies the amount of light transmitted through the material, often used for refractive effects, with values above 0.0 implying partial transparency. Both default to 1.0 (opaque), and d is more commonly used in modern implementations.[24]
These basic attributes provide a foundational shading system, which can be augmented by texture maps for more complex surface details.[24]
Texture Mapping and Options
Texture mapping in Material Template Library (MTL) files allows for the application of image-based textures to modify material properties such as diffuse, specular, and bump effects on 3D models defined in accompanying OBJ files. These mappings reference external image files and can include various options to control how the texture is applied, including scaling, offsetting, and tiling behavior. The textures are typically modulated with the corresponding procedural material attributes (e.g., the diffuse texture multiplies with the Kd color value during rendering).[24] Key keywords for texture mapping includemap_Kd for diffuse textures, map_Ks for specular textures, map_bump (or bump) for normal or bump mapping, map_d for opacity or transparency maps, and disp for displacement maps. Each keyword is followed by an optional filename specifying the texture image, which can be a relative path (relative to the MTL file's directory) or an absolute path; common supported formats include JPEG, PNG, TIFF, and SGI RGB, though compatibility varies by rendering software. For example, map_Kd texture.jpg applies a diffuse texture named texture.jpg.[24][26]
Options modify the texture application and are appended to the mapping keyword with a hyphen prefix, such as -s u v w to scale the texture coordinates (where u, v, w are multipliers, defaulting to 1.0 if omitted), -o u v w to offset the texture origin, and -t du dv dw to introduce turbulence for procedural distortion. Bump-specific options include -bm [bias](/page/Bias) to set the bump height multiplier (default 1.0), controlling the strength of surface perturbations. Tiling behavior can be adjusted with -clamp to clamp texture values at edges instead of repeating (tiling). An illustrative example is map_Kd texture.jpg -s 2.0 2.0 1.0, which scales the diffuse texture by a factor of 2 in the u and v directions while keeping w at 1.0.[24]
Advanced texture types include reflection maps via the refl keyword, which supports -type followed by options like sphere for spherical environment mapping or cube face types (e.g., cube_top, cube_bottom, cube_left, cube_right, cube_front, cube_back) for cubic mapping, each referencing a separate filename for the respective face (e.g., refl -type sphere refl.jpg or refl -type cube_top top.jpg). Displacement mapping with disp filename allows for vertex offset based on texture values, often used for heightfield effects in rendering pipelines. These mappings rely on UV coordinates defined in the OBJ file's texture vertices to project the 2D image onto the 3D surface. Decal textures can be specified separately using the decal keyword for overlay effects without blending.[24]
Indexing and References
Absolute versus Relative Indexing
In the Wavefront .obj file format, indices for referencing geometric vertices (v), texture vertices (vt), and vertex normals (vn) support two modes: absolute and relative. These modes apply independently to each component within elements such as faces, allowing precise control over how model data is linked.[13][12]
Absolute indexing uses positive integers beginning at 1, corresponding to the sequential order of definitions in the file. The value 1 refers to the first defined item in the respective list (e.g., the first vertex for geometric indices), 2 to the second, and so on. For example, the face declaration f 1/1/1 specifies the first vertex, first texture vertex, and first normal. This mode ensures explicit, fixed references regardless of the order or timing of data addition.[13][12]
Relative indexing, in contrast, utilizes negative integers that offset from the end of the current list of defined items. The value -1 denotes the last (most recently defined) item, -2 the second-to-last, and -n the nth from the end. Thus, f -1/-1/-1 references the last vertex, last texture vertex, and last normal defined up to that point in the file. This approach supports incremental construction of models, where elements can reference preceding data without anticipating the final count of items.[13][12]
The format defaults to absolute indexing for positive values and relative for negative ones, with mixed usage permitted across different indices in the same declaration—for instance, combining an absolute vertex reference with relative normals. Absolute indexing suits scenarios requiring unambiguous, global positioning, while relative indexing aids in modular or sequential model building by tying references to local context.[13][12]
Indices must generally fall within the range of defined items; values exceeding the current count (e.g., a vertex index greater than the number of v lines parsed so far) or otherwise invalid are often ignored by parsers or trigger import errors, depending on the implementation. For example, after defining five vertices, the face f 1 5 -1 validly references the first vertex, the fifth vertex, and the last (fifth) vertex, but an index like 6 would be out of range at that stage.[27][13]