OBJLoader2 & WorkerTaskManager for three.js
OBJLoader2 is a loader for the
OBJ file format included in three.js. It is an alternative to
OBJLoader offering more options. The parser
OBJLoader2Parser is independent and can either be used on Main via
OBJLoader2 or in parallel inside a web worker via
New versions of
OBJLoader2Parallel are now released via three.js. I currently no longer plan to release them independently via npm.
Interested in recent changes? Check the CHANGELOG.
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.
The easiest way to get started is simple by using gitpod! It offers all the possibilities the local environments do.
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
Bash into the running container for any manual task or script you want to run.
docker exec -it obj2dev bash
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:
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):
The parser used by
OBJLoader2Parallel has all OBJ parsing capabilities of
OBJLoader. Please see the following list of features:
- Parser can be executed in worker
Stringas input. Text processing is approx. 15-20 pecent slower
- It features indexed rendering including vertex reduction.
- Indexed rendering is available if switched on via
useIndicesin 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)
- Console logging is deactivated by default, but can be switched on if desired (including debug logging)
OBJLoader2Parallelmust 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 now replaces
WorkerExecutionSupport. It offers a generalized approach for executing parser code in a web worker.
- Standard workers
- Standard workers are implemented including Main-Execution fallback
- Dependency loading for standard workers is available
- Module Workers
- Module workers are implemented, dependencies are declared regularly and therefore no extra functionality is required
initfunctions can be declared in modules and then be packaged in standard worker if needed. This feature is used this to define the worker code once to support both code paths in
- A new example is supplied
- It uses a dat.gui to configure the example. Let it run, stop and reset.
- It allows to select all outlined worker types (standard workers with dependencies, module workers that declare dependencies if required and standard workers that are executed on main) and OBJLoader2Parser (standard and module version).
- It also allows to set the maximum amount of workers, the overall executions count, and the number of meshes to keep.
- It is a potentially indefinitely running example executing over and over the same workers, This has already proven to be very helpful in identifying memory holes and in verifying that CPU is utilized as expected.
- Class notation eases creation of worker code in case of standard workers.
- Execution queue has been added to
- Caching of worker code is available