sermonis / three-web-worker-obj-loader

OBJLoader2 & OBJLoader2Parallel for three.js

OBJLoader2 & OBJLoader2Parallel for three.js

OBJLoader2 is a loader for the OBJ file format. It is an alternative to OBJLoader included in three.js. The loader and its parser can be used on Main via OBJLoader2 or in parallel inside a web worker via OBJLoader2Parallel.

New versions of OBJLoader2 and OBJLoader2Parallel are from now on again released as npm modules independent of three.js. The next stable version will be 4.0.0. 4.0.0-beta.0 is already available for testing

This README is outdated and will be updated soon...

Changelog

Interested in recent changes? Check the CHANGELOG.

Development

Main Branches

Main development now takes place on branch dev.
Last stable release available with three.js is available on branch stable.

Repository structure

The directory structure now mimics the three.js directory structure to easy porting of changes:

• examples: Contains Tests/HTML examples
• examples/jsm: Contains the sources for the loaders
• examples/models: Contains OBJs, MTLs and textures

Use the index.html to easily access the different examples.

Development Environments

Gitpod

The easiest way to get started is simple by using gitpod! It offers all the possibilities the local environments do.

Local Container

If you have docker & docker-compose available there is no need to install any software stacks (git, node, npm, gulp, etc.). From the root of the repo just invoke the following command:

docker-compose up -d --build

When the container starts it always performs the initialisation task which puts all required files in place and then launches a local nginx http server on port 8085. All local build environment configuration is stored in the dev folder.

Bash into the running container for any manual task or script you want to run.

docker exec -it obj2dev bash

Local System

If you don't want to use the docker environment, then you need to set-up and npm and gulp locally on your local platform. After you have cloned this repository locally and have npm and gulp set-up, please run:

npm install

Docs

From the project's root run gulp to create The documentation in directory build/docs.

Additional models and resources

Use the following script to download missing resources (OBJ, MTL files and textures):

bash dev/models/retrieveExtras.sh

Implementation Overview

OBJLoader2Parser

The parser used by OBJLoader2 and OBJLoader2Parallel has all OBJ parsing capabilities of OBJLoader. Please see the following list of features:

• Parser can be executed in worker
• OBJLoader2.parse and OBJLoader2Parallel.parse methods accept ArrayBuffer or String as input. Text processing is approx. 15-20 pecent slower
• It features indexed rendering including vertex reduction.
• Indexed rendering is available if switched on via setUseIndices (see useIndices in example OBJLoader2 usage options).
• Face N-Gons are supported
• Multi-Materials are created when needed
• Flat smoothing defined by "s 0" or "s off" is supported and Multi-Material is created when one object/group defines both smoothing groups equal and not equal to zero.
• Support for points and lines was added (since V2.3.0)
• New mesh detection relies 'g' occurrence or 'f', 'l' or 'p' type change (since V2.3.0). This allows mutiple mesh definitions within one group.
• Negative face indices are supported (issue #28)
• The parser is now a single function that can be easily embedded in module or standard Workers (since V4.0.0-dev)

General features

• Console logging is deactivated by default, but can be switched on if desired (including debug logging)
• OBJLoader2 and OBJLoader2Parallel must be re-instantiated every time they are used.
• Progress callbacks provide numerical values to indicate overall progress of download or parsing (issue #16)
• TypeScript definitions (d.ts) are generated from JSDoc definitions for free from it, see declaration

WorkerTaskManager

See https://github.com/kaisalmen/three-wtm

Happy coding!

Kai