An OBJ file is plain text. The specification also describes a binary version with the
extension .mod; it is a different file and is not covered here. Each
statement starts with a keyword and has its values after it, separated by spaces.
Statements and lines
A file is a list of statements, one to a line. The keyword comes first and the rest of the line holds its arguments. Blank lines are allowed and mean nothing.
A statement can run over several lines: a backslash as the last character of a line joins the next line on. The specification’s examples use this for long statements, though its text does not state the rule.
# a comment on a line of its own
v 0.0 0.0 0.0 # three coordinates
v 1.0 0.0 0.0
v 0.0 1.0 0.0
f 1 \
2 \
3Numbers and references
Coordinates and other real values are decimal numbers, with an optional sign,
fraction and exponent, such as -0.5 or 1.2e-3.
Vertices, texture vertices, normals and parameter vertices are numbered separately, each
starting at 1, in the order they appear in the file. The numbering carries on across the
whole file, however the kinds are mixed. An element refers to a vertex by its number; a
negative number counts back from the current position, so -1 is the
vertex defined just above the element. See Vertices.
Character encoding
The specification does not name a character set. Files are usually ASCII or UTF-8. Comments, group names, material names and file names are where other characters appear, and some files use a byte order mark.
General statements
| Statement | Meaning |
|---|---|
call filename.ext [arg1 arg2 …] | Reads another .obj or .mod file here. The extension is required. Whole-number arguments replace $1, $2 and so on in the file read, as in UNIX scripts. There is no stated limit on how deeply files can call each other. |
csh command | Runs a UNIX shell command. If it fails the parser reports an error, unless the command starts with a dash (csh -command). |
A viewer should not run a command from a file it has been given. This site’s explorer shows these statements and does not act on them.
Order of a file
A few rules govern the order of statements:
- A negative reference is relative to where it appears, so it depends on the vertices above it. A reference to a positive number that is defined only later in the file is unusual; this site’s explorer reports it.
- Attribute statements such as
usemtlandgapply to the elements after them, until a new one replaces them. - A
curv,curv2orsurfand itsendenclose its body statements (Free-form curves and surfaces).
Comments
A line that starts with
#is a comment, which is not read. Comments can appear anywhere in the file. The specification only shows them on whole lines, but many files also put a comment after a statement’s last value. This site’s explorer treats a#that starts a token as a comment and reads the rest of the line as its text.