OBJ8 File Format Reference¶
This is based off of Laminar Research’s OBJ8 File Format Specification.
Basic file format¶
OBJ8 files are text files (7-bit ASCII only) 1 that consists of records, one per line. Any number of spaces or tabs are treated as white space. White space at the start (and end) of lines is ignored.
Each record, i.e., each line, starts with a case-sensitve keyword (ignoring and leading white space, of course).
Fully blank lines are legal (after then 3-line header). Lines beginning with # are also treated as comments.
Lines which contain a single word (such as the Header lines) can include an in-line comment if sepearated with a space. For example:
OBJ # This is a comment
The format is meant to be backward compatible: as new features are introduced, “old” software should be able to safely ignore these new features.
Coordinate System¶
Distances are expressed in meters. The object’s (0, 0, 0) point is the reference point for placing the object. That is, if you say the object is at latitude 0.0, longitude 0.0 at ground level, then the object’s (0, 0, 0) point is exactly at that position.
X-Plane uses a Y-up 3D coordinate system, with +X to the east/right, and +Z to the south/back.
+1 X is one meter right
-1 X is one meter left.
+1 Y is one meter up
-1 Y is one meter down.
+1 Z is one meter back
-1 Z is one meter forward.
Note
This is different from Blender’s coordinate system which uses Z-Up. Fortunately, the XPlane2Blender plugin converts the coordinate systems, so “up” in Blender remains “up” in X-Plane. Right (positive X) is the same in both. Blender positive Y maps to X-Plane negative Z, so “pointing” something in Blender in a positive Y direction will result it in “pointing” in X-Plane the negative Z direction, which are both considered “forward”.
The OBJ8 file, of course, uses X-Plane coordinates.
X-Plane
Blender
+ Direction
X
X
Right
Y
Z
Up
Z
-Y
Backwards
File Header¶
Header is required to be the first three lines of the file 2 (without blank lines or leading spaces.):
I
800
OBJ
Following the header are commands to define the objects, lights, and textures.
Commands¶
Geometry Commands: Defining sets of triangles forming a geometric shapes, and lines (forming lines)
Lights: Defining light effects
Animation Commands: Defining positioning changes to geometric shapes and lights, often due to dataref values.
Textures: Defining the texture (png file) used to overlay the object.
Particles and Emitters: Defining particle emitters.
name type x y z psi theta phiAttibutes¶
Other¶
- 1
Laminar documentation says files are 7-bit ascii, but X-Plane ships with files encoded with UTF-8 and LATIN-1. I do not know the full extent of encodings which are acceptable.
- 2
Technically, line endings are either single linefeed (
\nor 0x0a) if the first line of the header isI, or carriage-return + linefeed (\r\nor 0x0d0a) if the first line of the header isA. Do yourself a favor and useIwith simple newline.
