Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/discoverygarden/dgi_3d_viewer

This module provides display plugins for 3D model files in Drupal.
https://github.com/discoverygarden/dgi_3d_viewer

3d-models drupal drupal-module islandora viewer

Last synced: about 11 hours ago
JSON representation

This module provides display plugins for 3D model files in Drupal.

Awesome Lists containing this project

README 

        
# DGI 3D Viewer



## Introduction

This module provides display plugins for 3D model files in Drupal.

Currently, the following formats are supported:

* GLTF/GLB - GLB is preferred, since some browsers fail to handle large GLTFs.

* OBJ



## Three.js Library Usage Notes

Given that Drupal does not yet fully support ES6 modules, specifically

importmaps, and we want to use the latest version of three.js, we have

a slightly unusual setup for using the three.js library that results in

compiling our usage of three.js into a single file that can be loaded.

Such a setup results in the actual three.js library only needing to be

present to compile when developing, and not needing to be present in

production. However, if this process becomes unnecessary in the future,

then we can simply use the three.js library directly, without compiling.



## Requirements (for development)

This module requires the following modules/libraries:

* [Three.js 0.151.0](https://github.com/mrdoob/three.js/releases/tag/r151 )

  * And the following 'Add-ons':

    * [GLTFLoader](https://github.com/mrdoob/three.js/blob/r151/examples/jsm/loaders/GLTFLoader.js)

    * [OBJLoader](https://github.com/mrdoob/three.js/blob/r151/examples/jsm/loaders/OBJLoader.js)

    * [MTLLoader](https://github.com/mrdoob/three.js/blob/r151/examples/jsm/loaders/MTLLoader.js)

    * [OrbitControls](https://github.com/mrdoob/three.js/blob/r151/examples/jsm/controls/OrbitControls.js)

    * [RoomEnvironment](https://github.com/mrdoob/three.js/blob/r151/examples/jsm/environments/RoomEnvironment.js)

    * [strFromU8, unzipSync](https://github.com/mrdoob/three.js/blob/r151/examples/jsm/libs/fflate.module.js)

* [Node.js](https://nodejs.org/en/)

* [NPM](https://www.npmjs.com/)

* [Webpack](https://webpack.js.org/)

* [Babel](https://babeljs.io/)



## Installation

Install the module as usual,

see [this](https://www.drupal.org/docs/8/extending-drupal-8/installing-drupal-8-modules) for further information.



## Configuration

To use the 3D viewer, you need to configure the display plugin(s) for the file field you want to use.

The `3D Model File` widget provided by this module adds the ability to preview the uploaded file

provided the file is a supported format. The `3D Model File` formatter provided by this module can be

used independently of the widget if you do not want file preview added to the ingest form.

The preview provided by the widget could be useful for users to verify that they have uploaded the correct file,

and to verify that the file is supported by the 3D viewer. However, the preview loading time can be slow, depending

on the model being previewed, and so it may be best to use the regular file widget in some cases.



### Bonus configuration: Camera, Lights, Textures

The following is a work in progress to be replaced by a MediaSource Plugin



Sometimes we want to accommodate viewing a 3D model that does not include anything aside from the object itself in

the uploaded file, so we need a way to configure a camera and some light; without light and something to perceive

the light bouncing off the model, only darkness is rendered. Additionally, sometimes we would rather not generate

a GLB, and just upload the OBJ and related MTL and texture files. These capabilities are available, but rely on

the existence of certain configuration entities.



Configuration expectations:

* media.type.3d_object

  * field_media_file: the field that uses the 3D File Formatter

  * field_customcamera: programmatically flattened values from field_camera

  * field_camera: Entity reference link to paragraphs.paragraphs_type.perspective_camera_settings

  * field_materials_zip

  * field_room_environment

  * field_background_color

  * field_add_default_lights



## Usage

Once the module is installed and configured, file fields using the `3D Model File` formatter to display a file field

will render the 3D model in the browser, provided the file is a supported format.



## Resources

For more information on the three.js library, and 3D model formats, see the following resources:

* [Three.js](https://threejs.org/)

* [GLTF](https://www.khronos.org/gltf/)



## Development

This module uses Webpack to compile the three.js library and our usage of it into a single file.

### Three.js Library Installation

Desired outcome: The appropriate version of three.js exists in

`/opt/www/drupal/libraries/three`; if the location needs to change, then

adjust the webpack.config.js file accordingly.



#### A Composer way to install three.js:

1. Add npm-asset handling to your drupal-project composer.json.

* See [this](https://www.drupal.org/docs/develop/using-composer/manage-dependencies#third-party-libraries) for more information.

* Make sure to add the following to the `extra` section of your composer.json:

  ```

  "installer-paths": {

    "libraries/{$name}": ["type:npm-asset"]

  }

  ```

2. Run `composer require npm-asset/three:^0.151.0` in the drupal-project root directory.



#### A manual way to install three.js:

1. In `/opt/www/drupal/libraries`, run `git clone --branch= --depth=1 https://github.com/mrdoob/three.js.git`

   It's a rather large repo, so the `--depth=1` option is recommended to avoid downloading the entire history.



### Three.js Library Compilation

1. In the module root directory, run `npm install` to install the required packages.

2. Make sure the three.js library is installed in the correct location expected by webpack.config.js.

3. Make desired changes to the `js/*.es6.js` file(s), and run `webpack` to compile it to `js/*.js`.



For an example of compilation, and a way to check if issues are with your code

changes or the rest of the setup, see `js/test_threejs.es6.js`,

`webpack_test_threejs.config.js`, and the `build-test` script in `package.json`.

Try deleting `js/test_threejs.js` and recompiling it with `npm run build-test`.



## Sponsors

* [UNR](https://library.unr.edu/)



## Maintainers

Current maintainers:

* [discoverygarden](https://discoverygarden.ca/)



## License

[GPLv3](http://www.gnu.org/licenses/gpl-3.0.txt)