Tiny but powerful single file wavefront obj loader
Clone or download
syoyo Merge pull request #187 from Neptilo/master
Fix parsing double with negative exponent
Latest commit 59b4d7c Nov 5, 2018
Permalink
Failed to load latest commit information.
deps Add initial unit test codes using Catch. Apr 18, 2016
examples Separate error message into warning and error. Breaks API, so bump to… Oct 9, 2018
experimental Fix parsing double with negative exponent Nov 5, 2018
fuzzer Remove afl files since it fails to create file on Windows file system. Jun 1, 2018
images Add screenshot of glviewer. May 11, 2016
jni Update Android build. Apr 18, 2016
models Add colorspace extension to texture options. Fixes #184 Sep 14, 2018
python Fix mapping for #131 and compilation error #139 #132 (related) Oct 8, 2017
tests Separate error message into warning and error. Breaks API, so bump to… Oct 9, 2018
tools Fix index buffer was not filled when !triangulate case. May 1, 2016
.bintray.in Create dist directory to specify uploading files. Mar 12, 2016
.clang-format Use google C++ code style. Apr 16, 2016
.drone.yml Use syoyo/ubu-dev image. Feb 27, 2015
.gitignore Added a Cmake build system configuration Jan 26, 2014
.travis.yml Disable coveralls due to Travis + python bug? Apr 19, 2016
CMakeLists.txt Added double variant of lib to CMakeLists.txt Apr 24, 2017
LICENSE Add MIT license file Dec 28, 2016
README.md Fix build of viewer example. Feb 4, 2018
appveyor.yml Update AppVeyor script. Aug 20, 2016
build.ninja Add new build.ninja. Apr 23, 2016
loader_example.cc Show line number for some warning and error message. Oct 10, 2018
premake4.lua Add initial unit test codes using Catch. Apr 18, 2016
tiny_obj_loader.cc Add Cocos2d-x. Nov 26, 2015
tiny_obj_loader.h Make ParseTextureNameAndOption function public. Oct 19, 2018
tinyobjloader-config.cmake.in Fixed package config and cmake config templates for double variant of… Apr 24, 2017
tinyobjloader.pc.in Fixed package config and cmake config templates for double variant of… Apr 24, 2017
vcsetup.bat Add Appveyor settings. Jun 3, 2015
wercker.yml Fix CI scripts. Apr 18, 2016

README.md

tinyobjloader

Join the chat at https://gitter.im/syoyo/tinyobjloader

Build Status

wercker status

Build status

Coverage Status

https://github.com/syoyo/tinyobjloader

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 https://github.com/syoyo/tinyobjloader-c .

Notice!

We have released new version v1.0.0 on 20 Aug, 2016. Old version is available v0.9.x branch https://github.com/syoyo/tinyobjloader/tree/v0.9.x

What's new

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

Old version

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

Example

Rungholt

tinyobjloader can successfully load 6M triangles Rungholt scene. http://casual-effects.com/data/index.html

Use case

TinyObjLoader is successfully used in ...

New version(v1.0.x)

Old version(v0.9.x)

Features

TODO

  • Fix obj_sticker example.
  • More unit test codes.
  • Texture options

License

Licensed under MIT license.

Usage

Data format

attrib_t contains single and linear array of vertex data(position, normal and texcoord).

attrib_t::vertices => 3 floats per vertex

       v[0]        v[1]        v[2]        v[3]               v[n-1]
  +-----------+-----------+-----------+-----------+      +-----------+
  | x | y | z | x | y | z | x | y | z | x | y | z | .... | x | y | z |
  +-----------+-----------+-----------+-----------+      +-----------+

attrib_t::normals => 3 floats per vertex

       n[0]        n[1]        n[2]        n[3]               n[n-1]
  +-----------+-----------+-----------+-----------+      +-----------+
  | x | y | z | x | y | z | x | y | z | x | y | z | .... | x | y | z |
  +-----------+-----------+-----------+-----------+      +-----------+

attrib_t::texcoords => 2 floats per vertex

       t[0]        t[1]        t[2]        t[3]               t[n-1]
  +-----------+-----------+-----------+-----------+      +-----------+
  |  u  |  v  |  u  |  v  |  u  |  v  |  u  |  v  | .... |  u  |  v  |
  +-----------+-----------+-----------+-----------+      +-----------+

attrib_t::colors => 3 floats per vertex(vertex color. optional)

       c[0]        c[1]        c[2]        c[3]               c[n-1]
  +-----------+-----------+-----------+-----------+      +-----------+
  | x | y | z | x | y | z | x | y | z | x | y | z | .... | x | y | z |
  +-----------+-----------+-----------+-----------+      +-----------+

Each shape_t::mesh_t does not contain vertex data but contains array index to attrib_t. See loader_example.cc for more details.


mesh_t::indices => array of vertex indices.

  +----+----+----+----+----+----+----+----+----+----+     +--------+
  | i0 | i1 | i2 | i3 | i4 | i5 | i6 | i7 | i8 | i9 | ... | i(n-1) |
  +----+----+----+----+----+----+----+----+----+----+     +--------+

Each index has an array index to attrib_t::vertices, attrib_t::normals and attrib_t::texcoords.

mesh_t::num_face_vertices => array of the number of vertices per face(e.g. 3 = triangle, 4 = quad , 5 or more = N-gons).


  +---+---+---+        +---+
  | 3 | 4 | 3 | ...... | 3 |
  +---+---+---+        +---+
    |   |   |            |
    |   |   |            +-----------------------------------------+
    |   |   |                                                      |
    |   |   +------------------------------+                       |
    |   |                                  |                       |
    |   +------------------+               |                       |
    |                      |               |                       |
    |/                     |/              |/                      |/

 mesh_t::indices

  |    face[0]   |       face[1]     |    face[2]   |     |      face[n-1]           |
  +----+----+----+----+----+----+----+----+----+----+     +--------+--------+--------+
  | i0 | i1 | i2 | i3 | i4 | i5 | i6 | i7 | i8 | i9 | ... | i(n-3) | i(n-2) | i(n-1) | 
  +----+----+----+----+----+----+----+----+----+----+     +--------+--------+--------+

Note that when triangulate flas is true in tinyobj::LoadObj() argument, num_face_vertices are all filled with 3(triangle).

float data type

TinyObjLoader now use real_t for floating point data type. Default is float(32bit). You can enable double(64bit) precision by using TINYOBJLOADER_USE_DOUBLE define.

Example code

#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) {
  exit(1);
}

// 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];
      tinyobj::real_t vx = attrib.vertices[3*idx.vertex_index+0];
      tinyobj::real_t vy = attrib.vertices[3*idx.vertex_index+1];
      tinyobj::real_t vz = attrib.vertices[3*idx.vertex_index+2];
      tinyobj::real_t nx = attrib.normals[3*idx.normal_index+0];
      tinyobj::real_t ny = attrib.normals[3*idx.normal_index+1];
      tinyobj::real_t nz = attrib.normals[3*idx.normal_index+2];
      tinyobj::real_t tx = attrib.texcoords[2*idx.texcoord_index+0];
      tinyobj::real_t ty = attrib.texcoords[2*idx.texcoord_index+1];
      // Optional: vertex colors
      // tinyobj::real_t red = attrib.colors[3*idx.vertex_index+0];
      // tinyobj::real_t green = attrib.colors[3*idx.vertex_index+1];
      // tinyobj::real_t blue = attrib.colors[3*idx.vertex_index+2];
    }
    index_offset += fv;

    // per-face material
    shapes[s].mesh.material_ids[f];
  }
}

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)

Tests

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