tinyobjloader

The experimental/ directory contains two specialized versions of the .obj loader:

1. Multi-threaded optimized parser: Located in tinyobj_loader_opt.h. Designed for high-performance parsing using multiple threads.
2. Streaming experimental parser: Located in stream/stream_obj_loader.h. Designed for streaming data processing.

tinyobjloader provides two independent implementations for loading Wavefront .obj and .mtl files:

1. C++11 Implementation: A single-header loader (tiny_obj_loader.h) that requires only the C++ STL. It is designed for ease of integration into C++ projects.
2. C11 Implementation: A pure C11 loader (tiny_obj_c.{c,h}) bundled with the tobj_tess tessellation library. This version is secure, portable, freestanding-capable (no libc dependency in the core), and supports optional multithreading, SIMD, and mmap. It also supports points (p) and free-form geometry (curv, curv2, surf).

To build the simple .obj viewer on Linux, you must ensure glfw3 and glew are accessible. You can either set the PKG_CONFIG_PATH environment variable or manually edit the include/library paths in premake4.lua. Use premake5 to generate the makefiles and then run make.

$ premake5 gmake
$ make

You can install the tinyobjloader Python bindings using pip.

$ python -m pip install tinyobjloader

To build the simple .obj viewer on macOS, ensure you have glfw3 and glew installed via Homebrew. Use premake5 to generate the makefiles and then run make.

$ premake5 gmake
$ make

To build the experimental components, use premake5 with the gmake target. Ensure you have a C++11 compliant compiler installed.

$ premak5 gmake

The fuzz target is compiled alongside the main project when the LIB_FUZZING_ENGINE environment variable is defined during the CMake configuration step. For clang, use -fsanitize=fuzzer.

export LIB_FUZZING_ENGINE=-fsanitize=fuzzer
mkdir build && cd build
cmake .. -DBUILD_SHARED_LIBS=OFF
make -j $(nproc)

To perform a developer build from the cloned repository, use pip to install the current directory.

$ git clone https://github.com/tinyobjloader/tinyobjloader
$ cd tinyobjloader
$ python -m pip install .

The experimental stream parser is designed to parse Wavefront .obj files from a std::istream without loading the entire file into memory. This reduces peak input buffering and allows applications to consume mesh data (like faces) incrementally.

The parser is implemented in two layers:

1. StreamHandler: A callback-style incremental parser interface for low-level event handling.
2. LoadObjStreamExperimental(...): A convenience wrapper that automatically builds tinyobj::attrib_t, tinyobj::shape_t, and tinyobj::material_t structures.

It also supports an ordered multithreaded chunk mode that reads bounded batches of lines and parses them in parallel while replaying events in the original order.

To install, copy the tiny_obj_loader.h header file into your project. You must define TINYOBJLOADER_IMPLEMENTATION exactly once in one of your .cc files to generate the implementation.

#define TINYOBJLOADER_IMPLEMENTATION
#include "tiny_obj_loader.h"

To perform fuzzing tests on the ParseFromString API, you need clang with fuzzer support (at least version 8.0).

On Ubuntu 18.04, install the necessary packages using:

sudo apt install clang++-8
sudo apt install libfuzzer-8-dev

If clang++ is not already pointing to version 8, you can configure update-alternatives:

sudo update-alternatives --install /usr/bin/clang clang /usr/bin/clang-8 10
sudo update-alternatives --install /usr/bin/clang++ clang++ /usr/bin/clang++-8 10

To run the fuzzer regression tests, you must be on a Linux system using the clang compiler. The process involves building the runner with make and then executing the resulting binary against a specific regression file located in the ../regressions/ directory.

$ make
$ ./a.out ../regressions/<regression_file>