Fetching contributors…
Cannot retrieve contributors at this time
180 lines (127 sloc) 6.62 KB


Join the chat at

Build Status

wercker status

Build status

Coverage Status

Tiny but powerful single file wavefront obj loader written in C++. No dependency except for C++ STL. It can parse over 10M polygons with moderate memory and time.

tinyobjloader is good for embedding .obj loader to your (global illumination) renderer ;-)

If you are looking for C89 version, please see .


We have released new version v1.0.0 on 20 Aug, 2016. Old version is available v0.9.x branch

What's new

  • 20 Aug, 2016 : Bump version v1.0.0. New data strcutre and API!

Old version

Previous old version is avaiable in v0.9.x branch.



tinyobjloader can successfully load 6M triangles Rungholt scene.

Use case

TinyObjLoader is successfully used in ...

New version(v1.0.x)

Old version(v0.9.x)


  • Group(parse multiple group name)
  • Vertex
  • Texcoord
  • Normal
  • Material
    • Unknown material attributes are returned as key-value(value is string) map.
  • Crease tag('t'). This is OpenSubdiv specific(not in wavefront .obj specification)
  • PBR material extension for .MTL. Its proposed here:
  • Callback API for custom loading.


  • Fix obj_sticker example.
  • More unit test codes.
  • Texture options
  • Normal vector generation
    • Support smoothing groups


Licensed under MIT license.


attrib_t contains single and linear array of vertex data(position, normal and texcoord). Each shape_t does not contain vertex data but contains array index to attrib_t. See for more details.

#define TINYOBJLOADER_IMPLEMENTATION // define this in only *one* .cc
#include "tiny_obj_loader.h"

std::string inputfile = "cornell_box.obj";
tinyobj::attrib_t attrib;
std::vector<tinyobj::shape_t> shapes;
std::vector<tinyobj::material_t> materials;

std::string err;
bool ret = tinyobj::LoadObj(&attrib, &shapes, &materials, &err, inputfile.c_str());

if (!err.empty()) { // `err` may contain warning message.
  std::cerr << err << std::endl;

if (!ret) {

// Loop over shapes
for (size_t s = 0; s < shapes.size(); s++) {
  // Loop over faces(polygon)
  size_t index_offset = 0;
  for (size_t f = 0; f < shapes[s].mesh.num_face_vertices.size(); f++) {
    int fv = shapes[s].mesh.num_face_vertices[f];

    // Loop over vertices in the face.
    for (size_t v = 0; v < fv; v++) {
      // access to vertex
      tinyobj::index_t idx = shapes[s].mesh.indices[index_offset + v];
      float vx = attrib.vertices[3*idx.vertex_index+0];
      float vy = attrib.vertices[3*idx.vertex_index+1];
      float vz = attrib.vertices[3*idx.vertex_index+2];
      float nx = attrib.normals[3*idx.normal_index+0];
      float ny = attrib.normals[3*idx.normal_index+1];
      float nz = attrib.normals[3*idx.normal_index+2];
      float tx = attrib.texcoords[2*idx.texcoord_index+0];
      float ty = attrib.texcoords[2*idx.texcoord_index+1];
    index_offset += fv;

    // per-face material

Optimized loader

Optimized multi-threaded .obj loader is available at experimental/ directory. If you want absolute performance to load .obj data, this optimized loader will fit your purpose. Note that the optimized loader uses C++11 thread and it does less error checks but may work most .obj data.

Here is some benchmark result. Time are measured on MacBook 12(Early 2016, Core m5 1.2GHz).

  • Rungholt scene(6M triangles)
    • old version(v0.9.x): 15500 msecs.
    • baseline(v1.0.x): 6800 msecs(2.3x faster than old version)
    • optimised: 1500 msecs(10x faster than old version, 4.5x faster than baseline)


Unit tests are provided in tests directory. See tests/ for details.