jshaper

Use OBJ files from Java.

Description

The library implements a basic implementation for both reading and writing basic features of ASCII Object files based on this specification.

The basic features include:

• Vertex data:
  • Geometric vertices
  • Texture vertices
  • Vertex normals
  • Parameter space vertices
• Elements:
  • Faces
• Grouping data:
  • Groups

Comments are also handled correctly.

The library defines everything under the obj namespace, because it wasn't planned initially as "only OBJ" library.

Notice

I am not interested in developing or maintaining this library at the moment, so it is archived. Should be fully usable, though.

I recommend using this project if you need the basic feature of importing/exporting simple 3D models in OBJ format in Java specifically. That's essentially what I needed for myself.

Also this repository can be a good starting point for making a parser. There are no AST's or something like that, because the format is pretty simple, but works for learning the concept.

Prerequisites

• JDK 21+

Installation

Gradle

The recommended approach is the import as a runtime dependency.

// build.gradle.kts

repositories {
    mavenLocal() // should be here
}

dependencies {
    implementation("io.github.shimeoki:jshaper:0.15.0")
}

Usage

Every symbol in this section has a group prefix of io.github.shimeoki.jshaper. For example, if obj.Reader is mentioned, it should be imported as

import io.github.shimeoki.jshaper.obj.Reader;

The library provides two main interfaces: obj.Reader and obj.Writer. The two default implementations are obj.ModelReader and obj.ModelWriter respectively.

These interfaces work with default Java's File and this library's ObjFile. Latter contains the needed data of the model.

Then, the basic workflow looks as follows:

// get these to read/write from/to
final File in;
final File out;

// or use Reader/Writer interfaces instead of var
final var reader = new ModelReader();
final var writer = new ModelWriter();

// to get access outside of the try-catch block
final ObjFile obj;

// read
try {
    obj = reader.read(in);
} catch (final ShaperError e) {
    // wrap or do something
    throw new RuntimeException(e);
}

// use obj
// ...

// write
try {
    writer.write(obj, out);
} catch (final ShaperError e) {
    // wrap or do something
    throw new RuntimeException(e);
}

For available data, check the methods in ObjFile.

Notes

• The import is not streamed, so models are imported into the memory in full size. Because the imported file is a fully interactive object, it consumes even more memory than in the ASCII format.
• There is no Javadoc.