saito.objloader
Class OBJModel

java.lang.Object
  extended by saito.objloader.OBJModel

public class OBJModel
extends java.lang.Object

Author:
matt

Field Summary
static java.lang.String ABSOLUTE
           
 Debug debug
           
static java.lang.String RELATIVE
           
 
Constructor Summary
OBJModel(PApplet _parent)
          Class Constructor to setup an empty obj model
OBJModel(PApplet _parent, java.lang.String _filename)
          Class Constructor, loads the file from the data directory
OBJModel(PApplet _parent, java.lang.String _fileName, int _shapeMode)
          Class Constructor, loads the string as an obj from the data directory.
OBJModel(PApplet _parent, java.lang.String _fileName, java.lang.String _texturePathMode)
          Class Constructor, loads the file from the data directory.

use String "relative" to search the data folder for the mtl and textures
use "absolute" to load the files from the specific path
OBJModel(PApplet _parent, java.lang.String _fileName, java.lang.String _texturePathMode, int _shapeMode)
          Class Constructor, loads the string as an obj from the data directory.
 
Method Summary
 void clampUV()
          Helper function to clamp the UV's so they sit within 0-1.
 void disableDebug()
           
 void disableMaterial()
          Disables the material completely.

With this on you can set the appearance of the model in processing before calling model.draw();



background(32);

stroke(255);

noFill();

model.draw();

 void disableTexture()
          Turns off the use of the textures in mtl file.
 void draw()
          The draw method of the OBJModel.

This method used the standard Processing system of beginShape, endShape to draw the model.

 void drawGL()
          Draws the obj model using the Vertex Buffers that were made in the setupOPENGL method

NOTE: this method is on the way out.
 void enableDebug()
          Enables the debug mode.

Prints version and contact information to the console.

 void enableMaterial()
          Turns on the use of the material that came from the mtl file

 void enableTexture()
          Turns on the use of textures that are listed in the mtl file

 int getDrawMode()
          Gets the drawmode
 int getFaceCount()
          Gets the total number of faces in the model.

This is the total of the index count across all segments

This is mostly used when you need raw verts for physics simulation

 Face getFaceInSegment(int _segmentIndex, int _faceIndex)
           
 PVector[] getFaceVertices(int faceNumber)
          Gets an array of PVectors that make up the position co-ordinates of the face.

This method needs one int that must be between 0 and the getTotalFaceCount()

This is mostly used when you need raw verts for physics simulation

Personally I wouldn't do this during draw.
 Group getGroup(java.lang.String groupName)
          Returns the group via name

Until I find a practical use for Groups this feature isn't going anywhere.
 int getGroupCount()
          Gets the size of the Groups from the obj Model.
 int getIndexCountInSegment(int i)
          Gets the number of Indexes in the Segment.
 PVector getNormal(int i)
          Returns a reference to a numbered Normal.
 int getNormalCount()
          Get's the total number of Normals in the model.
 int[] getNormalIndicesInSegment(int i, int num)
          Returns an array of ints.
 Segment getSegment(int _index)
           
 int getSegmentCount()
          Gets the number of segments in the model.

A segment is a unique material and an array of indexes into the vert, norm and uv Vectors

 int[] getTextureIndicesInSegment(int i, int num)
          Returns an array of ints.
 java.lang.String getTexturePathMode()
          Should return "relative" or "absolute"
 PVector getUV(int i)
          Returns a reference to a numbered Textured Coordinate.
 int getUVCount()
          Get's the total number of UVs in the model.
 PVector getVertex(int i)
          Returns a reference to a numbered Vertex.
 int getVertexCount()
          Get's the total number of Verts in the model.
 int[] getVertexIndicesInSegment(int i, int num)
          Returns an array of ints.
 void load(java.lang.String filename)
          The manual load method for obj files.
 void mapUVToZeroOne()
          Helper function to scale the UV's so they sit within 0-1.
 void originalTexture()
          Sets the override texture back to null.
 void printModelInfo()
          A Debug method that prints information about the loaded model

This method only prints information if the debugMode is true.

V Size = The number of vertex positions

Vt Size = The number of UV positions

Vn Size = The number of normals

G Size = the number of Groups in the model

S Size = the number of segments in the model, this should directly equate to the number of unique materials in the mtl file

 void reset()
          Clears all Vectors ready for loading in a new model.

Doing something like this



OBJModel model = new OBJModel(this, "myobj.obj");

// do something with model

model.clear();

model.load("myobj.obj");



is vastly better for memory use than doing something like this



OBJModel model = new OBJModel(this, "myobj.obj");

// do something with model

model = new OBJModel(this, "myOtherObj.obj");



The second example is really bad because the original model is still in memory but nothing is pointing to it.

We would have to wait for the Garbage Collector to do the clean up before freeing the memory.
 void scale(float scale)
          Scales the vertex positions of the model.
 void scale(float scaleX, float scaleY, float scaleZ)
          Scales the vertex positions of the model.
 void setDrawMode(int _drawMode)
          Sets the draw mode of the shape drawing
 void setNormal(int i, PVector normal)
          Sets the Normal at index i to the PVector supplied
 void setTexture(PImage textureName)
          Sets an override texture for the drawing of the model.

Any PImage supplied will be used over all model segments

NOTE: This method is identical to texture(), It has the better syntax.
 void setTexturePathMode(java.lang.String _texturePathMode)
          Use "relative" or "absolute" to set the texture load method
 void setupGL()
          Called after loading the obj model.
 void setUV(int i, PVector uv)
          Sets the UV at index i to the PVector supplied
 void setVertex(int i, float x, float y, float z)
          Sets the vert at index i to the x,y,z values supplied
 void setVertex(int i, PVector vertex)
          Sets the vert at index i to the PVector supplied
 void shapeMode(int mode)
          Set's the beginShape mode for drawing the model.
 void texture(PImage tex)
          Sets an override texture for the drawing of the model.

Any PImage supplied will be used over all model segments

 void translate(PVector p)
          Translates all the verts by the PVector amount
 void translateToCenter()
          Helper function to move the origin point of the model to the center of the objects BoundingBox
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

RELATIVE

public static java.lang.String RELATIVE

ABSOLUTE

public static java.lang.String ABSOLUTE

debug

public Debug debug
Constructor Detail

OBJModel

public OBJModel(PApplet _parent)
Class Constructor to setup an empty obj model


OBJModel

public OBJModel(PApplet _parent,
                java.lang.String _filename)
Class Constructor, loads the file from the data directory


OBJModel

public OBJModel(PApplet _parent,
                java.lang.String _fileName,
                int _shapeMode)
Class Constructor, loads the string as an obj from the data directory.

The int sets the draw mode, to the processing draw mode, eg. TRIANGLES, POINTS, POLYGON, LINES, TRIANGLE_STRIP, QUAD_STRIP, QUADS.


OBJModel

public OBJModel(PApplet _parent,
                java.lang.String _fileName,
                java.lang.String _texturePathMode)
Class Constructor, loads the file from the data directory.

use String "relative" to search the data folder for the mtl and textures
use "absolute" to load the files from the specific path


OBJModel

public OBJModel(PApplet _parent,
                java.lang.String _fileName,
                java.lang.String _texturePathMode,
                int _shapeMode)
Class Constructor, loads the string as an obj from the data directory.

use String "relative" to search the data folder for the mtl and textures
use "absolute" to load the files from the specific path

The int sets the draw mode, to the processing draw mode, eg. TRIANGLES, POINTS, POLYGON, LINES, TRIANGLE_STRIP, QUAD_STRIP, QUADS.

Method Detail

setupGL

public void setupGL()
Called after loading the obj model.

This will setup the Vertex buffer objects ready for the drawOPENGL method.

The obj file must be loaded for this method to work.
NOTE: this method is on the way out. It'll be removed in the near future.


drawGL

public void drawGL()
Draws the obj model using the Vertex Buffers that were made in the setupOPENGL method

NOTE: this method is on the way out. It'll be removed in the near future.


printModelInfo

public void printModelInfo()
A Debug method that prints information about the loaded model

This method only prints information if the debugMode is true.

V Size = The number of vertex positions

Vt Size = The number of UV positions

Vn Size = The number of normals

G Size = the number of Groups in the model

S Size = the number of segments in the model, this should directly equate to the number of unique materials in the mtl file


enableDebug

public void enableDebug()
Enables the debug mode.

Prints version and contact information to the console.


disableDebug

public void disableDebug()

reset

public void reset()
Clears all Vectors ready for loading in a new model.

Doing something like this



OBJModel model = new OBJModel(this, "myobj.obj");

// do something with model

model.clear();

model.load("myobj.obj");



is vastly better for memory use than doing something like this



OBJModel model = new OBJModel(this, "myobj.obj");

// do something with model

model = new OBJModel(this, "myOtherObj.obj");



The second example is really bad because the original model is still in memory but nothing is pointing to it.

We would have to wait for the Garbage Collector to do the clean up before freeing the memory.

If loading in lots of stuff is important then using the model.clear() could help a lot.


disableTexture

public void disableTexture()
Turns off the use of the textures in mtl file.

Only the ambient, diffuse and specular values will be used.


enableTexture

public void enableTexture()
Turns on the use of textures that are listed in the mtl file


disableMaterial

public void disableMaterial()
Disables the material completely.

With this on you can set the appearance of the model in processing before calling model.draw();



background(32);

stroke(255);

noFill();

model.draw();


enableMaterial

public void enableMaterial()
Turns on the use of the material that came from the mtl file


shapeMode

public void shapeMode(int mode)
Set's the beginShape mode for drawing the model.

This will vary depending on the model and the export settings.

A safe bet is to triangulate the model before exporting and set the drawmode to TRANGLES.

Also due to inconsistencies in OPENGL points, the POINTS mode may draw nothing in OPENGL.

A common misconception is that LINES will result in a wireframe. For this effect you should leave the drawmode as the correct mode and disable the material and use stroke() to get a wireframe

All the standard processing modes are supported
TRIANGLES, POINTS, POLYGON, LINES, TRIANGLE_STRIP, QUAD_STRIP, QUADS

Parameters:
int -

draw

public void draw()
The draw method of the OBJModel.

This method used the standard Processing system of beginShape, endShape to draw the model.


load

public void load(java.lang.String filename)
The manual load method for obj files. This method is automatically called when using Constructors that include the file name

The method uses the Processing createReader() function to get a BufferedReader object in order to read the file one line at a time.

This is slightly better method than loadStrings() as it's less memory intensive for large obj files.


scale

public void scale(float scale)
Scales the vertex positions of the model. As processing runs in pixel units and the rest of the world works in cm,mm,meters, there's a damn good chance you'll need to scale the model in order to draw it.

Parameters:
scale -

scale

public void scale(float scaleX,
                  float scaleY,
                  float scaleZ)
Scales the vertex positions of the model. As processing runs in pixel units and the rest of the world works in cm,mm,meters, there's a damn good chance you'll need to scale the model in order to draw it.

Parameters:
scaleX -
scaleY -
scaleZ -

translate

public void translate(PVector p)
Translates all the verts by the PVector amount

Parameters:
p -

translateToCenter

public void translateToCenter()
Helper function to move the origin point of the model to the center of the objects BoundingBox


mapUVToZeroOne

public void mapUVToZeroOne()
Helper function to scale the UV's so they sit within 0-1. One day I'll be able to kill this function.


clampUV

public void clampUV()
Helper function to clamp the UV's so they sit within 0-1. One day I'll be able to kill this function.


setDrawMode

public void setDrawMode(int _drawMode)
Sets the draw mode of the shape drawing

Parameters:
_drawMode -

getDrawMode

public int getDrawMode()
Gets the drawmode

Returns:
int

setTexturePathMode

public void setTexturePathMode(java.lang.String _texturePathMode)
Use "relative" or "absolute" to set the texture load method

Parameters:
_texturePathMode -

getTexturePathMode

public java.lang.String getTexturePathMode()
Should return "relative" or "absolute"


getGroupCount

public int getGroupCount()
Gets the size of the Groups from the obj Model.

At the moment groups are an unexplored feature.

So you can get the size, but it's not going to do much for you.

Returns:
int

getGroup

public Group getGroup(java.lang.String groupName)
Returns the group via name

Until I find a practical use for Groups this feature isn't going anywhere.

Parameters:
String -
Returns:
Group

getSegment

public Segment getSegment(int _index)

getFaceInSegment

public Face getFaceInSegment(int _segmentIndex,
                             int _faceIndex)

getSegmentCount

public int getSegmentCount()
Gets the number of segments in the model.

A segment is a unique material and an array of indexes into the vert, norm and uv Vectors

Returns:
int

getFaceCount

public int getFaceCount()
Gets the total number of faces in the model.

This is the total of the index count across all segments

This is mostly used when you need raw verts for physics simulation

Returns:
int

getFaceVertices

public PVector[] getFaceVertices(int faceNumber)
Gets an array of PVectors that make up the position co-ordinates of the face.

This method needs one int that must be between 0 and the getTotalFaceCount()

This is mostly used when you need raw verts for physics simulation

Personally I wouldn't do this during draw. It's going to be expensive.

Returns:
PVector[]

getIndexCountInSegment

public int getIndexCountInSegment(int i)
Gets the number of Indexes in the Segment.

In effect this is the number of faces in the Segment.

As each Index is an Array of ints to the vert, normal, or uv Array

Make sure the param is between 0 and the number of segments

Parameters:
int -
Returns:
int

getVertexIndicesInSegment

public int[] getVertexIndicesInSegment(int i,
                                       int num)
Returns an array of ints. Use these ints to get the verts of a single face.

Parameters:
int
-
int
-
Returns:
int[]

getNormalIndicesInSegment

public int[] getNormalIndicesInSegment(int i,
                                       int num)
Returns an array of ints. Use these ints to get the normals of a single face.

Parameters:
int
-
int
-
Returns:
int[]

getTextureIndicesInSegment

public int[] getTextureIndicesInSegment(int i,
                                        int num)
Returns an array of ints. Use these ints to get the UV's of a single face.

Parameters:
int
-
int
-
Returns:
int[]

getVertexCount

public int getVertexCount()
Get's the total number of Verts in the model.

Returns:
int

getNormalCount

public int getNormalCount()
Get's the total number of Normals in the model.

It can happen that the Normal count is identical to the Vert count. This will depend on the effecency of the exporter that has been used.

In a situation where the count is identical often there is a relationship between a certain numbered Normal and the same numbered Vert.

However this can also be total luck. The correct method of getting the normal for the correct vert is to go through the ModelSegment to ModelElement to VertIndex and NormalIndex.
Or take the easy route and get the Face

Returns:
int

getUVCount

public int getUVCount()
Get's the total number of UVs in the model.

Returns:
int

getVertex

public PVector getVertex(int i)
Returns a reference to a numbered Vertex. As this is a reference to the original vertex you can directly manipulate the PVector without having to set it back.

PVector tmp = model.getVertex(0);

tmp.x += 10;

Parameters:
int
-
Returns:
PVector

getNormal

public PVector getNormal(int i)
Returns a reference to a numbered Normal. As this is a reference to the original normal you can directly manipulate the PVector without having to set it back.

PVector tmp = model.getNormal(0);

tmp.mult(-1);

Parameters:
int
-
Returns:
PVector

getUV

public PVector getUV(int i)
Returns a reference to a numbered Textured Coordinate. As this is a reference to the original UV you can directly manipulate the PVector without having to set it back.

It is important to note that the UV's of an obj model are in a NORMALIZED space (between 0-1).

Another important issue is that the native processing renderer does not tile textures that are outside 0-1

This can have the effect of streaking pixel lines at the edges of the texture.

PVector tmp = model.getUV(0);

tmp.x += 0.01;

Parameters:
int
-
Returns:
PVector

setVertex

public void setVertex(int i,
                      PVector vertex)
Sets the vert at index i to the PVector supplied

Parameters:
int -
PVector -

setVertex

public void setVertex(int i,
                      float x,
                      float y,
                      float z)
Sets the vert at index i to the x,y,z values supplied

Parameters:
i -
x -
y -
z -

setNormal

public void setNormal(int i,
                      PVector normal)
Sets the Normal at index i to the PVector supplied

Parameters:
int -
PVector -

setUV

public void setUV(int i,
                  PVector uv)
Sets the UV at index i to the PVector supplied

Parameters:
int -
PVector -

setTexture

public void setTexture(PImage textureName)
Sets an override texture for the drawing of the model.

Any PImage supplied will be used over all model segments

NOTE: This method is identical to texture(), It has the better syntax.

Parameters:
PImage -

texture

public void texture(PImage tex)
Sets an override texture for the drawing of the model.

Any PImage supplied will be used over all model segments

Parameters:
PImage -

originalTexture

public void originalTexture()
Sets the override texture back to null. This sends the model back to original method of drawing the segment with the texture contained in the segments material



processing library OBJLoader by Saito, Matt Ditton, Ekene Ijeoma. (c) 2010