OBJ file reader

For loading polygonal geometry stored in the Wavefront OBJ format, a widespread text-based exchange format for 3D surface models written by CAD programs, 3D modeling tools such as Blender, and mesh processing libraries. The reader produces a triangle mesh data object, which OVITO can display alongside particle-based simulation data, for example to show a container geometry, a tool, a substrate, or some other static object in the scene. Meshes loaded from OBJ files can also serve as user-defined particle shapes. Triangle meshes stored in the STL format are handled by a separate file reader.

Imported data

The file reader creates the following data in the pipeline’s file source:

Triangle mesh

A single triangle mesh object with the identifier mesh, consisting of the list of vertices and the list of triangular faces read from the file. Polygons with more than three vertices are triangulated during import. The mesh is rendered by a Triangle mesh visual element, which controls its color, transparency, and the optional highlighting of polygon edges. In Python, the imported TriangleMesh can be found in the DataCollection.objects list.

Since the format describes a single static geometry, the reader does not load trajectories from a single file. A numbered sequence of files (e.g. mesh.0.obj, mesh.1.obj, …) can however be imported as an animation sequence using a wildcard file pattern, as described in Simulation trajectories.

The format stores no simulation cell, per-vertex or per-face properties, or global attributes; no such data is created by the reader. The loaded mesh can be moved, rotated, and scaled with the Affine transformation modifier.

OBJ is a text-based format in which each line begins with a keyword identifying the type of record. OVITO can directly load gzipped OBJ files (“.gz” suffix). The file reader interprets the following records:

v x y z

A vertex with Cartesian coordinates. Any additional values on the line (e.g. a fourth w coordinate or a vertex color) are ignored.

f v1 v2 v3 ...

A polygonal face referencing three or more previously defined vertices. Both positive (1-based) and negative (relative to the end of the current vertex list) vertex indices are supported. The texture coordinate and vertex normal indices of the v/vt/vn and v//vn index syntax are parsed but not used. Polygons with more than three vertices are triangulated as a triangle fan, and only the outer polygon edges are marked as visible in the triangle mesh, i.e. the interior diagonals inserted by the triangulation are not drawn when the Highlight edges option of the visual element is turned on.

s n / s off

Smoothing group records are honored. Faces belonging to the same smoothing group are rendered with smooth (interpolated) shading across shared vertices, whereas faces outside of any smoothing group are rendered with flat shading. OVITO supports smoothing group numbers up to 32; higher numbers are ignored.

vn, vt, vp, o, g, l, p, mtllib, usemtl

These records are accepted but skipped. In particular, vertex normals (vn) are not imported; the shading of the mesh is determined solely by the face geometry and the smoothing groups. Object (o) and group (g) records do not split the file into separate meshes: the entire content of an OBJ file is merged into one triangle mesh. Material libraries and material assignments are ignored, and the mesh is rendered with the uniform color set in the visual element.

Limitations

  • Line elements (l) and point elements (p) are not imported, because the triangle mesh can only represent faces.

  • Any other record type not listed above (e.g. free-form curve and surface records) results in a parsing error.

  • Vertex normals, texture coordinates, vertex colors, and materials are ignored.

  • The automatic format detection requires that at least three v records appear within the first 18 lines of the file (including comment and blank lines). If a file is not recognized automatically, the format can be selected explicitly by passing input_format='obj' to import_file().

Options

This file reader has no user-adjustable options.

Python parameters

The file reader accepts no format-specific keyword parameters in a call to the import_file() or load() Python functions.