obj

Documentation

Overview

Package obj provides APIs through which one can parse Wavefront OBJ resources. The OBJ file format is quite common and is used to store 3D model data.

The parsers provided by this library do not support the full OBJ spec, which is quite lengthy, but rather only the most essential and common features.

Index

• Constants
• type DecodeLimits
  • func DefaultLimits() DecodeLimits
• type Decoder
  • func NewDecoder(limits DecodeLimits) Decoder
• type Face
• type Mesh
• type Model
  • func (m *Model) FindObject(name string) (*Object, bool)
  • func (m *Model) GetNormalFromReference(ref Reference) Normal
  • func (m *Model) GetTexCoordFromReference(ref Reference) TexCoord
  • func (m *Model) GetVertexFromReference(ref Reference) Vertex
• type Normal
• type Object
  • func (o *Object) FindMesh(materialName string) (*Mesh, bool)
• type Reference
  • func (r Reference) HasNormal() bool
  • func (r Reference) HasTexCoord() bool
• type TexCoord
• type Vertex

Constants

const UndefinedIndex int64 = -1

UndefinedIndex is used to mark an index as undefined.

Types

type DecodeLimits

type DecodeLimits struct {

	// MaxVertexCount specifies the maximum number of vertices
	// that can be parsed before an error is thrown.
	MaxVertexCount int

	// MaxTexCoordCount specifies the maximum number of texture
	// coordinates that can be parsed before an error is thrown.
	MaxTexCoordCount int

	// MaxNormalCount specifies the maximum number of normals
	// that can be parsed before an error is thrown.
	MaxNormalCount int

	// MaxObjectCount specifies the maximum number of objects
	// that can be parsed before an error is thrown.
	MaxObjectCount int

	// MaxFaceCount specifies the maximum number of faces
	// that can be parsed per mesh before an error is thrown.
	MaxFaceCount int

	// MaxReferenceCount specifies the maximum number of vertex
	// references that a given face can have.
	MaxReferenceCount int

	// MaxMaterialLibraryCount specifies the maximum number of
	// material library references that can be parsed before
	// an error is thrown.
	MaxMaterialLibraryCount int

	// MaxMaterialReferenceCount specifies the maximum number of
	// material references that can be parsed per object before
	// an error is thrown.
	MaxMaterialReferenceCount int
}

DecodeLimits specifies restrictions on parsing.

One will generally use this to limit the number of data that is parsed in order to prevent out of memory errors

func DefaultLimits

func DefaultLimits() DecodeLimits

DefaultLimits returns some default DecodeLimits. Users can take the result and modify specific parameters.

type Decoder

type Decoder interface {

	// Decode decodes the OBJ Wavefront resource, specified
	// through the io.Reader, into a Library model.
	//
	// If decoding fails for some reason, an error is returned.
	Decode(io.Reader) (*Model, error)
}

Decoder is an API that allows one to decode OBJ Wavefront resources into an object model.

func NewDecoder

func NewDecoder(limits DecodeLimits) Decoder

NewDecoder creates a new Decoder instance with the specified DecodeLimits.

type Face

type Face struct {

	// References holds an array of Reference objects
	//
	// Each Reference holds information for a single
	// point in space. The list of all references compose
	// a polygon shape.
	References []Reference
}

Face defines a single face that is part of a mesh

type Mesh

type Mesh struct {

	// MaterialName holds the name of the material that
	// should be used for the rendering of this mesh
	MaterialName string

	// Faces holds all the faces that comprise this mesh
	Faces []*Face
}

Mesh is a concept that cannot be directly mapped to OBJ specification. It is here to allow for the separation of mesh data based on material.

Since a single object can have sections that use various materials, the Mesh is a mechanism through which such sections are separated.

type Model

type Model struct {

	// Vertex holds a list of all the vertices
	Vertices []Vertex

	// Normals holds a list of all the normals
	Normals []Normal

	// TexCoords holds a list of the texture coordinates
	TexCoords []TexCoord

	// Objects holds a list of all the objects
	Objects []*Object

	// MaterialLibraries holds a list of filenames to MTL
	// resources that should be used together with the current
	// OBJ resource
	MaterialLibraries []string
}

Model represents the data of a single Wavefront OBJ resource.

func (*Model) FindObject

func (m *Model) FindObject(name string) (*Object, bool)

FindObject is a helper method that allows one to search for an object in this model based on name

func (*Model) GetNormalFromReference

func (m *Model) GetNormalFromReference(ref Reference) Normal

GetNormalFromReference is a helper method that allows one to get the Normal directly from a Reference

func (*Model) GetTexCoordFromReference

func (m *Model) GetTexCoordFromReference(ref Reference) TexCoord

GetTexCoordFromReference is a helper method that allows one to get the TexCoord directly from a Reference

func (*Model) GetVertexFromReference

func (m *Model) GetVertexFromReference(ref Reference) Vertex

GetVertexFromReference is a helper method that allows one to get the Vertex directly from a Reference

type Normal

type Normal struct {

	// X coordinate of this normal.
	X float64

	// Y coordinate of this normal.
	Y float64

	// Z coordinate of this normal.
	Z float64
}

Normal is used to define the directional information for objects.

type Object

type Object struct {

	// Name holds the name of the object
	Name string

	// Meshes holds a list of meshes that make up
	// the object's shape
	Meshes []*Mesh
}

Object represents an object in the model

func (*Object) FindMesh

func (o *Object) FindMesh(materialName string) (*Mesh, bool)

FindMesh is a helper function that allows one to find a Mesh within an Object by searching by its material name

type Reference

type Reference struct {

	// VertexIndex holds the index into the array of vertices
	// for the positional data of this point.
	VertexIndex int64

	// TexCoordIndex holds the index into the array of texture
	// coordinates for the texture data of this point.
	//
	// If this value is equal to UndefinedIndex, then this point
	// does not have texture information.
	TexCoordIndex int64

	// NormalIndex holds the index into the array of normals
	// for the directional data of this point.
	//
	// If this value is equal to UndefinedIndex, then this point
	// does not have directional information.
	NormalIndex int64
}

Reference is used to describe a single point from the set of points that define a shape

Since a single point can have position, direction and texture information, all of that data is held in this structure.

func (Reference) HasNormal

func (r Reference) HasNormal() bool

HasNormal is a helper method that helps determine whether the current Reference has normal information.

func (Reference) HasTexCoord

func (r Reference) HasTexCoord() bool

HasTexCoord is a helper method that helps determine whether the current Reference has texture coordinate information.

type TexCoord

type TexCoord struct {

	// U coordinate of this texture coordinate.
	U float64

	// V coordinate of this texture coordinate.
	V float64

	// W coordinate of this texture coordinate.
	W float64
}

TexCoord is used to define the texture mapping on an object's surface

type Vertex

type Vertex struct {

	// X coordinate of this vertex.
	X float64

	// Y coordinate of this vertex.
	Y float64

	// Z coordinate of this vertex.
	Z float64

	// W coordinate of this vertex. (By default 1.0)
	W float64
}

Vertex is used to define the positional information for objects.