discoverygarden/dgi_3d_viewer

Provide a viewer for 3D objects in Drupal.

Maintainers

Details

github.com/discoverygarden/dgi_3d_viewer

Source

Issues

Installs: 6

Dependents: 0

Suggesters: 0

Security: 0

Stars: 1

Watchers: 7

Forks: 0

Open Issues: 0

Language:JavaScript

Type:drupal-module

v1.4.4 2023-11-02 13:35 UTC

Requires

  • drupal/paragraphs: ^1

Requires (Dev)

  • npm-asset/three: ^0.151.0

GPL-3.0-only 63efec290a7e42cf7cbbe855d28378a74562842c

This package is auto-updated.

Last update: 2024-12-01 00:09:23 UTC

README

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:

Installation

Install the module as usual, see this 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:

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 for more information.
  • Make sure to add the following to the extra section of your composer.json: 
    "installer-paths": {
  "libraries/{$name}": ["type:npm-asset"]
}
  1. 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=<version tag> --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

Maintainers

Current maintainers:

License

GPLv3