libobj

A modern C++ library for parsing the Wavefront OBJ file format.

Introduction

The Wavefront OBJ format is a de factor standard for storing and exchanging 3D data. The Wavefront OBJ format was developed by Wavefront Technologies, and is currently supported by almost all major 3D applications.

Libobj is a modern C++ library for parsing the Wavefront OBJ file format. Libobj consists of an event-based error-reporting parser for the Wavefront OBJ file format. A similar parser for the Wavefront MTL file format is planned. Libobj is available under the GNU General Public License.

Features

Libobj's Wavefront OBJ parser currently supports vertex data (geometric vertices (v), texture vertices (vt), vertex normals (vn)), elements (faces (f)), grouping (group name (g), smoothing group (s), merging group (mg), object name (o)) and display/render attributes (material name (usemtl), material library (mtllib)). The parser supports triangular, quadrilateral and polygonal faces, and optionally triangulates (convex and planar) non-triangular faces. The parser optionally translates negative indices. For more information, refer to the OBJ specification.

Libobj's Wavefront OBJ parser is event-based, which makes it easy to integrate and well suited for parsing very large files (such as the 350 million triangles Boeing 777 Model). Libobj's Wavefront OBJ parser reports errors, which is especially useful for handling the large variety of OBJ files out there. Libobj is a modern C++ library written in standard C++, and uses TR1's function objects as an efficient and flexible callback mechanism.

Libobj comes with the obj2obj command line tool, which supports transformations on OBJ files, such as triangulation and index translation.

Author

Libobj was written by Ares Lagae. Ares Lagae is a researcher in the Computer Graphics Research Group at the Katholieke Universiteit Leuven, and a C++ enthusiast. In his spare time, he writes C++ libraries that he uses in his research. Libobj is one of these libraries. Other libraries include libnff, a modern C++ library for parsing the Wavefront OBJ file format, and libply, a modern C++ library for parsing the PLY file format.

Download

Libobj does not depend on any external libraries, but requires <tr1/functional> and <tr1/tuple>. Libobj was developed with gcc version 4.2.0.

Please send bug reports, feature requests, questions and comments to Ares Lagae.

Documentation

To install libobj, download the source distribution, unpack the archive (tar xzf obj-0.1.tar.gz), move into the directory (cd obj-0.1/), configure the package (./configure --prefix=/home/ares), compile the programs and libraries (make), install the programs and libraries (make install), and clean the package (make clean).

To use libobj, create an OBJ file (cube.obj),

v 0.000000 2.000000 2.000000
v 0.000000 0.000000 2.000000
v 2.000000 0.000000 2.000000
v 2.000000 2.000000 2.000000
v 0.000000 2.000000 0.000000
v 0.000000 0.000000 0.000000
v 2.000000 0.000000 0.000000
v 2.000000 2.000000 0.000000
f 1 2 3 4
f 8 7 6 5
f 4 3 7 8
f 5 1 4 8
f 5 6 2 1
f 2 6 7 3
create an example program (obj.cpp),
#include <iostream>
#include <obj.hpp>

void geometric_vertex_callback(obj::float_type x, obj::float_type y, obj::float_type z)
{
  std::cout << "v " << x << " " << y << " " << z << "\n";
}

int main(int argc, char* argv[])
{
  obj::obj_parser obj_parser;
  obj_parser.geometric_vertex_callback(geometric_vertex_callback);
  obj_parser.parse("cube.obj");
}
compile the program (g++ -Wall -I ~/include obj.cpp -L ~/lib/ -l obj -o obj), and execute the program (./obj). In order to locate the locate the dynamic libraries, update the dynamic library search path of the linker (export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:~/lib). If libobj was installed system-wide (./configure withouth --prefix=/home/ares), then reconfigure the dynamic linker run time bindings (ldconfig). Alternatively, the example program can be linked statically (g++ -Wall -I ~/include obj.cpp -L ~/lib/ -l obj -static -o obj).

To uninstall libobj, move into the directory (cd obj-0.1/), uninstall the programs and libraries (make uninstall), move out of the directory (cd ..), remove the directory (rm -r obj-0.1/), and remove the source distribution (rm obj-0.1.tar.gz).

Libobj does not have detailed documentation. Please refer to the Doxygen documentation, to the source code of the obj2obj program that comes with libobj, and to TR1 documentation.

Ares Lagae - Personal site (disclaimer) -