Red-i Productions Presents:
Kamakazi Kube Project
Wavefront .Obj Import Compliancy/Robustness Test File

by Keith Young
(a.k.a. Spanki)
http://www.skinprops.com

** Updated 07.17.06 **

- 3DS Max 6 sp1 w/ HABware OBJ importer results added.

 

** Updated 07.14.06 **

- There was an error in Kube6.obj (Non-Standard-Slashing (in facet records) test), where the Blue material was not being set on one of the faces. The links to the download file below have been updated to the new zip file. If you grabbed any of the earlier files, you should get the updated one. If you reported results to me yesterday, please re-check this test on those apps (I think Blender might be the only one in question). Thanks.

 

** Updated 07.13.06 **

- I decided to change the single .obj file (with all the test-cases in it) to a set of .obj files, each with one test. This should make it easier to determine which tests are failing, without having to edit the .obj file... see the updated testing proceedures section below for details.

- Noelr sent me a link to what looks like the official .mtl file spec (yay). I'll admit to not having looked for it for the past year or so, but I had never been able to find this file in the past, so this is the first time I'm seeing it.

- According to the .mtl file spec mentioned above, spaces are not allowed in the names of materials (underscores are suggested in place of them). Note that this complicate things a bit... there are currently several apps to do create material names with spaces in them, so those files are non-compliant (not the importer, failing to read them correctly). I've decided to leave the test in for now, just to see which apps can read them, but it's not a failure if they can't. Note that 'Kube4.obj' is the only one that tests spaces in material names... all other test files use underscores instead of spaces, so the materials should load fine in those.

- Since so many apps were failing (often crashing) on the "Line-Continuation" test, I decided to make that test a little bit more real-world/practical. As far as I can tell, line-continuation could be anywhere in the file and I was testing it on a vertex record, but in the real-world, you'd likely never find it there, so I've moved the test to the facet section.

 

July 09, 2006

Introduction

Kamakazi Kube is a test-case Wavefront .obj file I created to ferret out Import issues in 3D applications while working on my Riptide .obj import/export plugin for Cinema4D by Maxon. It includes tests for several anticipated problem areas, including things that will trip up "sloppy/lazy programming" as well as "things that weren't really spelled out precisely in the specs". It also includes various formatting that I've run across over time... some apps write out some really odd stuff.

The goal is to be able to read/import the various test files, intact and without errors. You should end up with a unit-cube, with each of the 6 faces assigned a separate (and uniquely colored) material.

Note to developers

All of the test cases in this file could be considered 'spec compliant', (depending on your interpretation), but regardless of whether they follow the spec or not, I HAVE run into each condition before, so the idea here is to bullet-proof your code to handle each case when importing .obj files of unknown origin. The file itself just has a simple cube mesh in it (no surfaces or splines or anything not normally needed to specify a polygonal mesh).

Disclaimer

As mentioned above, all of the test cases 'should' be compliant with the Wavefront .obj file format specification, however, depending on the robustness of whatever app you are using, it's possible that one or more of these tests will cause a lock-up, crash or even catch on fire (well, probably not catch on fire, at least...).

So...

PLEASE BACK UP ANY WORK IN PROGRESS BEFORE TRYING TO LOAD THIS MESH.
THIS FILE IS PROVIDED FOR EDUCATIONAL PURPOSES ONLY AND COMES WITH A
**** USE AT YOUR OWN RISK ****
CLAUSE. I WILL NOT BE HELD RESPONSIBLE FOR ANY LOSS AS A RESULT OF
ANY USE OF THIS FILE, WHATSOEVER. THANK YOU - DRIVE THROUGH.

The File

You can grab the zip file from here: Kamakazi Kube ...it includes the .obj files along with 3 .mtl files for testing.

The Tests

Currently, the following test-cases are in the file...

Spaces In Material Filename: (Kube1.obj)
As far as I can tell, the official Wavefront .obj file specification does not specify whether or not a .mtl file can have spaces in the filename. However, several app do allow/produce .mtl files with spaces in the filename (it's usually the same name as the .obj file, but with .mtl as a suffix)...

mtllib My Mesh File.mtl

...there is a record in the .obj file that specifies the name of the material file to load "mtllib [filename]", but the specification doesn't give any further elaboration about whether the name can contain spaces. If the mesh loads, but you get no colors, then the app either doesn't read .mtl files at all, or it doesn't support spaces in the name of the .mtl file.

End-of-Line Comments:
[NOTE: After further investigation, it appears that end-of-line comments are not supported by the file format specification, so I have removed this test - if you already downloaded the test file earlier, you should grab the new one]

Line-Continuation: (Kube2.obj)
The spec also allows for lines to be split and continued on the follow line. This is denoted by a '\' character. When the code sees one of these characters in the file (that's not part of a comment), it should continue reading on the following line. I don't know of any applications that create files with these in them, but I suspect that the place where they might be used when specifying many-sided n-gons (but they could be anywhere in the file)...

f v/vt/vn v/vt/vn v/vt/vn v/vt/vn v/vt/vn v/vt/vn v/vt/vn v/vt/vn v/vt/vn \
v/vt/vn v/vt/vn v/vt/vn

...(the v/vt/vn would be the actual vertex indices). Note that this particular test caused a Crash in Hexagon 2.0... Poser 6 did not crash, but it didn't read that polygon correctly, so this should be one of the first places to look in the test file if you're having troubles importing it.

If this test fails, then the Red (right-side) face will either be missing, or displayed as a triangle, instead of a quad.

Note to developers: for practical purposes, I consider a line-continuation to also be an end-of-line comment... I ignore anything after the slash on that line and pick up filling my buffer with the next line (after adding a space, if needed).

Whitepace: (Kube3.obj)
This is a pretty simple test within the file... basically apps should treat any amount and any combination of tabs and spaces as a (single) delimiter between tokens in the file (note that there are some records within the spec where whitespace is specifically forbiden, like between the indices and slashes of a facet record shown above).

Spaces in Material Names: (Kube4.obj)
**Update**
As mentioned above, I have finally had a look at what appears to be the official .mtl file format spec, which states that material names can not have spaces in them. I've decided to leave this test in the mix for now, just to see which apps support it, but it should be noted that it is not a failure if this test fails... the app that created/exported the file with spaces in material names is creating non-compliant files.

Within the facet record section of a .obj file, you can specify that facets/polygons belong to a "material group". This is done with a "usemtl [materialname]" record...

usemtl My Material

...after importing the test file, you should end up with 6 unique materials. Note that this is a separate issue from spaces within the name of the material file itself.

Obsolete Facet Record: (Kube5.obj)
Currently, a facet record within a .obj file looks something like this: "f 1/1/1 2/2/2 3/3/3" (without the quotes). At some point in the past, there used to be a different facet record, that used 'fo' instead of just 'f'. I'm not sure what software might still be out there still writing 'fo' records, but there are stil some older files out there that have these records in them, so apps should handle reading them.

If this test fails, you'll likely be missing the "Blue" (top) face.

Non-Standard-Slashing (in facet records): (Kube6.obj)
There are 4 different ways to specify a facet/polygon's indices within a .obj file: vertex-only, vertex + texture, vertex + normal, vertex + texture + normal. These indices are separated by a slash '/' and must be in that ordering (vertex, then texture, then normal), but you can leave out either the texture or the normal, or both. If you leave out the texture, you still need the extra slash, so...

f 1 1 1 <-- a triangle
f 1/1 2/2 3/3 <-- a triangle, with texture
f 1//1 2//2 3//3 <-- a traingle, with normals
f 1/1/1 2/2/2 3/3/3 <-- a triangle, with textures and normals

...above are examples of the most often used/recognized forms of the facet record, in it's various formats. However, likely due to a loose interpretation of the spec, there is at least one other form that is often found in files and one other form that's written out by at least one app (MakeHuman.exe)...

f 1/1/ 2/2/ 3/3/ <-- a triangle, with texture but no normal, but note the trailing slash on the end(s)
f 1// 2// 3// <-- a triangle with no textures or normals, but with trailing slashes for both slots

...so apps should handle these extra cases as well, but many apps do not currently support these forms.

If this test fails, you'll likely be missing the "Green_Red" (Yellow, bottom) face.

Negative/Relative Indexing: (Kube7.obj)
In the sample facet records above, the numbers you see represent an 'absolute index' into the various vertex tables (1-based index, not zero-based). The spec also allows for specifying a 'relative index', specified by negative index values. An index of -1 means "the previous/latest vertex up until this point in the file", so a -5 would be 5 down from the top of the vertex table (up to this point in the file.. more vertices might be found later in the file). The apps I've tested so far handle relative indexing fine, but there may be others out there that don't.

If this test fails, you'll likely be missing the "Blue_Green" (Cyan) face.

 

Running the Test(s)

**Updated** 07.13.06
As mentioned above, I've changed the format of the testing from a single .obj file with all the tests in it, to separate .obj files - one for each test. This should make it easier for people to run through the test suite and identify which ones are failing...

The most basic form of the test is to SAVE ANY WORK IN PROGRESS and then just try importing the individual .obj files, one at a time (Kube1.obj, Kube2.obj, Kube3.obj, etc.) and see what happens. Here are the results you're looking for:

- All six sides of the cube are loaded (you'll have to spin the cube around and look to see that all faces loaded).
- Each face of the cube has it's own unique material: "Red", "Green", "Blue", "Red_Blue", "Green_Red", "Blue_Green" (Note: on Kube4.obj, the material names might show up with spaces instead of underscores)
- Each of the 6 materials has it's own unique color: Red, Green, Blue, Magenta/Pink, Yellow, Cyan/Aqua
- If 'groups' are supported in the app, there should be a group named "Cube" - many apps just use that as the mesh name.

...if all of the above is true, then the app passed the test. If any of the above is not true, then it fails the test (see the comments on each test above for potential failure modes).

Kube1.obj - Spaces in .mtl Filename
Kube2.obj - Line-continuation
Kube3.obj - Whitespace
Kube4.obj - Spaces in Material Names
Kube5.obj - Obsolete Facet Record
Kube6.obj - Non-Standard-Slashing (in facet records)
Kube7.obj - Negative/Relative Indexing

Test Results

So far, I've only tested a few apps, but there are a lot that I don't have access to, so If you want to send me results for other apps, I'll be happy to add them as I get them.

Just for the record, my Riptide v1.4 or later .obj import/export plugin (for Cinema4D R9.1 or later) loads the file intact, with no errors and when exporting, does not produce any of these potential problem cases.

On with the tests...

 Riptide v1.4 (or later) .obj Import/Export Plugin for Cinema4D R9.1 or later
Spaces In Material Filename Pass
Line-Continuation Pass
Whitepace Pass
Spaces in Material Names Pass
Obsolete Facet Record Pass
Non-Standard-Slashing (in facet records) Pass
Negative/Relative Indexing Pass

 Cinema4D (R.37-R9.1) Native .obj Import
Spaces In Material Filename Fail - The built-in import code ignores .mtl files altogether, so I guess it fails this test as well :).
Line-Continuation Pass
Whitepace Pass
Spaces in Material Names Ignores anything after the space in the material name, so we end up with 3 materials (Red, Green, Blue), but since it doesn't bother reading the .mtl file, all colors are set to grey.
Obsolete Facet Record Pass
Non-Standard-Slashing (in facet records) Fail - Does not support trailing slashes when there's no Normal index (error dialog - doesn't load the file at all).
Negative/Relative Indexing Pass

 Maya 7.0
Spaces In Material Filename Fail
Line-Continuation Pass
Whitepace Pass
Spaces in Material Names Doesn't support spaces in material names.
Obsolete Facet Record Pass
Non-Standard-Slashing (in facet records) Pass
Negative/Relative Indexing Pass

 Lightwave 9 (release candidate 22) Native .obj Import
Spaces In Material Filename Fail - Apparently, LW doesn't bother reading .mtl files, whether they have spaces in the filename or not.
Line-Continuation Fail - Didn't crash, but didn't read this vertex correctly.
Whitepace Pass
Spaces in Material Names Pass
Obsolete Facet Record Pass
Non-Standard-Slashing (in facet records) Pass
Negative/Relative Indexing Pass

 Accutrans3D v2.9.18 (NOTE: I just got word that the programmer promptly fixed both failures for an upcomming release! Great Service!)
Spaces In Material Filename Pass
Line-Continuation Fail - Didn't crash, but didn't read this vertex correctly.
Whitepace Pass
Spaces in Material Names Pass
Obsolete Facet Record Fail - missing blue facet.
Non-Standard-Slashing (in facet records) Pass
Negative/Relative Indexing Pass

 UVMapper Pro v2.0
Spaces In Material Filename Pass
Line-Continuation Pass
Whitepace Pass
Spaces in Material Names This one was kind of interesting... UVM seems to have understood that there were 6 unique materials (it assigned each face to a separate one, like it was supposed to), but the code that reads the .mtl file didn't quite grok the spaces in material names, so the first 3 materials got over-written by the second 3 materials and the second 3 materials ended up a default grey.
Obsolete Facet Record Pass
Non-Standard-Slashing (in facet records) Pass
Negative/Relative Indexing Pass

 Hexagon 2.0
Spaces In Material Filename Fail - Does not support spaces in .mtl filenames
Line-Continuation Fail - ** Crashes **
Whitepace Pass
Spaces in Material Names Hexagon fails to load the .mtl file if there are spaces in the filename of the file, but it actually creates all 6 materials correctly, if it can find the file (so, it doesn't fail on this particular test, but I wanted to point out the difference in spaces within filenames vs spaces within material names).
Obsolete Facet Record Fail - Does not support the (obsolete) 'fo' facet record (facet ends up missing).
Non-Standard-Slashing (in facet records) Fail - Does not support trailing slashes when there's no Normal index (this facet ends up missing).
Negative/Relative Indexing Pass

 Poser 6
Spaces In Material Filename Pass
Line-Continuation Fail - Doesn't crash, but doesn't get this vertex read correctly.
Whitepace Pass
Spaces in Material Names Ignores anything after the space in the material name, so we end up with 3 materials (Red, Green, Blue), colored Pink, Yellow and Aqua.
Obsolete Facet Record Pass
Non-Standard-Slashing (in facet records) Pass
Negative/Relative Indexing Pass

 Metasequoia version unknown, general failure, need more details.
Spaces In Material Filename Fail (?) - doesn't appear to set up colors in materials.
Line-Continuation Fail - Doesn't crash, but doesn't get this vertex read correctly.
Whitepace Pass
Spaces in Material Names Doesn't support spaces in material names (only creates 3 materials).
Obsolete Facet Record ?
Non-Standard-Slashing (in facet records) ?
Negative/Relative Indexing ?

 Carrara 5
Spaces In Material Filename Pass
Line-Continuation Pass
Whitepace Pass
Spaces in Material Names Doesn't support spaces in material names (Red, Green, Blue colors overwritten with Pink, Yellow, Cyan)
Obsolete Facet Record Pass
Non-Standard-Slashing (in facet records) Fail - face missing.
Negative/Relative Indexing Pass

 DAZ|Studio v1.2
Spaces In Material Filename Fail - not supported.
Line-Continuation Fail - didn't crash, but failed to get correct values.
Whitepace Pass
Spaces in Material Names Doesn't support spaces in material names (Only 3 materials created - Red, Green, Blue colors overwritten with Pink, Yellow, Cyan)
Obsolete Facet Record Pass
Non-Standard-Slashing (in facet records) Pass
Negative/Relative Indexing Pass

 Ultimate Unwrap3D v2.18
Spaces In Material Filename Pass
Line-Continuation Fail - did not crash, but did not load vertex correctly.
Whitepace Pass
Spaces in Material Names Pass - (one of the few that have passed so far)
Obsolete Facet Record Pass
Non-Standard-Slashing (in facet records) Pass
Negative/Relative Indexing Fail - the only one to fail so far.

 Wings3D v0.98.34b
Spaces In Material Filename Fail
Line-Continuation Fail
Whitepace Fail - Wow. I honestly didn't expect any apps to fail this one (and yet it passed some of the more obscure tests below).
Spaces in Material Names Doesn't support spaces in material names.
Obsolete Facet Record Pass
Non-Standard-Slashing (in facet records) Pass
Negative/Relative Indexing Pass

 Blender v2.41
Spaces In Material Filename Fail
Line-Continuation Fail
Whitepace Pass
Spaces in Material Names Doesn't support spaces in material names.
Obsolete Facet Record Pass
Non-Standard-Slashing (in facet records) Fail
Negative/Relative Indexing Pass

 Blender v2.42RC3 - it looks like they fixed everything in this version.
Spaces In Material Filename Pass
Line-Continuation Pass
Whitepace Pass
Spaces in Material Names Pass - (spaces get replaced by underscores)
Obsolete Facet Record Pass
Non-Standard-Slashing (in facet records) Pass
Negative/Relative Indexing Pass

 Silo v1.4
Spaces In Material Filename Fail - Does not support spaces in .mtl filenames
Line-Continuation Fail - Red face loads as triangle (new test).
Whitepace Pass
Spaces in Material Names Doesn't support spaces in material names.
Obsolete Facet Record Pass
Non-Standard-Slashing (in facet records) Pass
Negative/Relative Indexing Pass

 messiah:Studio 2.2 and 2.4

(NOTE: oddly enough, messiah seems to have some trouble reading 'some' comment lines or some combination of comment lines, so the results below were only after removing comments from the files)

Spaces In Material Filename Pass
Line-Continuation Pass
Whitepace Pass
Spaces in Material Names Pass
Obsolete Facet Record Pass
Non-Standard-Slashing (in facet records) Pass
Negative/Relative Indexing Fail - Face missing.

 3DS Max 6 sp1 w/ HABware OBJ Importer
Spaces In Material Filename Pass
Line-Continuation Pass
Whitepace Pass
Spaces in Material Names Does not support spaces in material names.
Obsolete Facet Record Fail - ** Crash **
Non-Standard-Slashing (in facet records) Fail - Assertion Error (after clicking Retry 4 times, it actually loaded)
Negative/Relative Indexing Pass

[top]

 

  All images, meshes, props, programs and textual content on this site are Copyright © 2003 by Keith Young. All rights reserved.