thesortedchaos / wavefront-reader

a library for reading .obj/.mtl (wavefront) files

Version Matrix

codecov Quality Gate Status


The wavefront-reader can read .obj files and transform then into usable data for OpenGL (Array[Float], Array[Int]) Wavefront (.obj) files are used to store geometric data, like geometric objects build with e.g. Blender. These files are read, validated and then get transformed into an internal model. In the next step this internal model is transformed to a Mesh object. There are several kinds of Meshes, like:

Mesh Type Provided Data
SimpleMesh vertices: Array[Float], color: Array[Float]
SimpleIndexMesh vertices: Array[Float], color: Array[Float], indexes: Array[Int]
Mesh vertices: Array[Float], textures: Array[Float], normals: Array[Float] and optional tangents: Array[Float], biTangents: Array[Float] for NormalMapping
IndexedMesh vertices: Array[Float], textures: Array[Float], indexes: Array[Int]

These Mesh objects can than be used for filling a VertexBufferObject from OpenGL (e.g. with LWJGL)


  • Scala 2.13.3
  • SBT 1.3.3
  • Java JDK 1.8

How to use

Add the dependency to your build.sbt like:

libraryDependencies += "com.github.thesortedchaos" %% "wavefront-reader" % "0.1.0"


libraryDependencies += "com.github.thesortedchaos" % "wavefront-reader_2.13" % "0.1.0"

After this you have the option to read an .obj file or .mtl file from your resource folder of your project. Reading a file from somewhere else is not supported at the moment. You have the following options:

Read a geometry (.obj) file

import de.sorted.chaos.wavefront.WavefrontReader
import de.sorted.chaos.wavefront.mesh.Mesh


val mesh: Mesh = WavefrontReader.from("my-example.obj")

This will create a mesh model where the following data will be included. Only if the data is present in the .obj file, otherwise the Array will be empty.

  • vertices: Array[Float]
  • textures: Array[Float]
  • normals: Array[Float]

The following Arrays will be empty (used for normal mapping)

  • tangents: Array[Float]
  • biTangents: Array[Float]

There are also some experimental methods, you can play around with:

  • WavefrontReader.withNormalMappingFrom(filename: String): Mesh - This will create a Mesh with tangents and biTangents data for normal mapping
  • WavefrontReader.withIndexFrom(filename: String): IndexMesh - This will create a IndexMesh (without data for normal mapping) which can be used for OpenGL IndexDrawing
  • WavefrontReader.simpleFrom(filename: String, color: Vector3f): SimpleMesh - This will create a SimpleMesh containing only vertices and the color.
  • WavefrontReader.simpleWithIndexFrom(filename: String, color: Vector3f): SimpleIndexMesh - This will create a SimpleIndexMesh the indexed version of a SimpleMesh for OpenGL IndexDrawing

Read a material (.mtl) file

import de.sorted.chaos.wavefront.WavefrontReader
import e.sorted.chaos.wavefront.reader.Material


val material: Material = WavefrontReader.materialFrom("my-example.mtl")

This will create a material model where the following data will be included:

  • ambientColor: Vector3f
  • diffuseColor: Vector3f
  • specularColor: Vector3f
  • specularExponent: Float

Vector3f is coming from JOML - Java OpenGL Math Library


Social Media

Twitter       Instagram       YouTube