Document how to use and customize Obj in detail

[dbrgn]

I'm trying to load an OBJ file that has been exported from FreeCAD. When doing so, I get the following error message:

LoadError { kind: InsufficientData, desc: "Tried to extract normal data which are not contained in the model" }

What does that mean? FreeCAD can open those files fine, are these normals required to load the file?

(Note: I'm only getting started with the OBJ format and don't have a lot of knowledge about it yet.)

[dbrgn]

The same thing happens when loading the file tests/fixtures/pot.obj in the repository from the glium example.

[sisso]

Same happens with own cube.obj in the fixutres tests:
https://github.com/simnalamburt/obj-rs/blob/master/tests/fixtures/cube.obj

[sisso]

Looks like some fork has a patch to have optional normals.

ojhunt@fe7b3c7

[simnalamburt]

I think making a new type like VertexWithoutNormal would be better, since Option type in Vertex struct is hard to handle with GPU.

[simnalamburt]

Wait, a type called Position already exists. If your Obj file does not contains normal data, this will work:

obj-rs/examples/no-normal.rs

Lines 15 to 20 in a9213b0

	let input = BufReader::new(File::open("tests/fixtures/dome.obj")?);
	// NOTE: This will fail since dome.obj does not have normal data
	// let obj: Obj = load_obj(input)?;
	let obj: Obj<Position> = load_obj(input)?;

I do understand that this is not documented very well. Let's change the title of this issue to state the problem clearer!