{"id":25368253,"url":"https://github.com/discoverygarden/dgi_3d_viewer","last_synced_at":"2026-04-29T17:06:35.296Z","repository":{"id":194919850,"uuid":"624440893","full_name":"discoverygarden/dgi_3d_viewer","owner":"discoverygarden","description":"This module provides display plugins for 3D model files in Drupal.","archived":false,"fork":false,"pushed_at":"2023-11-02T13:36:00.000Z","size":1642,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":8,"default_branch":"main","last_synced_at":"2025-02-15T00:36:35.818Z","etag":null,"topics":["3d-models","drupal","drupal-module","islandora","viewer"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/discoverygarden.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null}},"created_at":"2023-04-06T13:26:49.000Z","updated_at":"2024-11-12T17:49:50.000Z","dependencies_parsed_at":"2024-05-12T20:32:39.272Z","dependency_job_id":null,"html_url":"https://github.com/discoverygarden/dgi_3d_viewer","commit_stats":null,"previous_names":["discoverygarden/dgi_3d_viewer"],"tags_count":10,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/discoverygarden%2Fdgi_3d_viewer","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/discoverygarden%2Fdgi_3d_viewer/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/discoverygarden%2Fdgi_3d_viewer/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/discoverygarden%2Fdgi_3d_viewer/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/discoverygarden","download_url":"https://codeload.github.com/discoverygarden/dgi_3d_viewer/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247987235,"owners_count":21028895,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["3d-models","drupal","drupal-module","islandora","viewer"],"created_at":"2025-02-15T00:36:44.979Z","updated_at":"2026-04-29T17:06:35.205Z","avatar_url":"https://github.com/discoverygarden.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# DGI 3D Viewer\n\n## Introduction\nThis module provides display plugins for 3D model files in Drupal.\nCurrently, the following formats are supported:\n* GLTF/GLB - GLB is preferred, since some browsers fail to handle large GLTFs.\n* OBJ\n\n## Three.js Library Usage Notes\nGiven that Drupal does not yet fully support ES6 modules, specifically\nimportmaps, and we want to use the latest version of three.js, we have\na slightly unusual setup for using the three.js library that results in\ncompiling our usage of three.js into a single file that can be loaded.\nSuch a setup results in the actual three.js library only needing to be\npresent to compile when developing, and not needing to be present in\nproduction. However, if this process becomes unnecessary in the future,\nthen we can simply use the three.js library directly, without compiling.\n\n## Requirements (for development)\nThis module requires the following modules/libraries:\n* [Three.js 0.151.0](https://github.com/mrdoob/three.js/releases/tag/r151 )\n  * And the following 'Add-ons':\n    * [GLTFLoader](https://github.com/mrdoob/three.js/blob/r151/examples/jsm/loaders/GLTFLoader.js)\n    * [OBJLoader](https://github.com/mrdoob/three.js/blob/r151/examples/jsm/loaders/OBJLoader.js)\n    * [MTLLoader](https://github.com/mrdoob/three.js/blob/r151/examples/jsm/loaders/MTLLoader.js)\n    * [OrbitControls](https://github.com/mrdoob/three.js/blob/r151/examples/jsm/controls/OrbitControls.js)\n    * [RoomEnvironment](https://github.com/mrdoob/three.js/blob/r151/examples/jsm/environments/RoomEnvironment.js)\n    * [strFromU8, unzipSync](https://github.com/mrdoob/three.js/blob/r151/examples/jsm/libs/fflate.module.js)\n* [Node.js](https://nodejs.org/en/)\n* [NPM](https://www.npmjs.com/)\n* [Webpack](https://webpack.js.org/)\n* [Babel](https://babeljs.io/)\n\n## Installation\nInstall the module as usual,\nsee [this](https://www.drupal.org/docs/8/extending-drupal-8/installing-drupal-8-modules) for further information.\n\n## Configuration\nTo use the 3D viewer, you need to configure the display plugin(s) for the file field you want to use.\nThe `3D Model File` widget provided by this module adds the ability to preview the uploaded file\nprovided the file is a supported format. The `3D Model File` formatter provided by this module can be\nused independently of the widget if you do not want file preview added to the ingest form.\nThe preview provided by the widget could be useful for users to verify that they have uploaded the correct file,\nand to verify that the file is supported by the 3D viewer. However, the preview loading time can be slow, depending\non the model being previewed, and so it may be best to use the regular file widget in some cases.\n\n### Bonus configuration: Camera, Lights, Textures\nThe following is a work in progress to be replaced by a MediaSource Plugin\n\nSometimes we want to accommodate viewing a 3D model that does not include anything aside from the object itself in\nthe uploaded file, so we need a way to configure a camera and some light; without light and something to perceive\nthe light bouncing off the model, only darkness is rendered. Additionally, sometimes we would rather not generate\na GLB, and just upload the OBJ and related MTL and texture files. These capabilities are available, but rely on\nthe existence of certain configuration entities.\n\nConfiguration expectations:\n* media.type.3d_object\n  * field_media_file: the field that uses the 3D File Formatter\n  * field_customcamera: programmatically flattened values from field_camera\n  * field_camera: Entity reference link to paragraphs.paragraphs_type.perspective_camera_settings\n  * field_materials_zip\n  * field_room_environment\n  * field_background_color\n  * field_add_default_lights\n\n## Usage\nOnce the module is installed and configured, file fields using the `3D Model File` formatter to display a file field\nwill render the 3D model in the browser, provided the file is a supported format.\n\n## Resources\nFor more information on the three.js library, and 3D model formats, see the following resources:\n* [Three.js](https://threejs.org/)\n* [GLTF](https://www.khronos.org/gltf/)\n\n## Development\nThis module uses Webpack to compile the three.js library and our usage of it into a single file.\n### Three.js Library Installation\nDesired outcome: The appropriate version of three.js exists in\n`/opt/www/drupal/libraries/three`; if the location needs to change, then\nadjust the webpack.config.js file accordingly.\n\n#### A Composer way to install three.js:\n1. Add npm-asset handling to your drupal-project composer.json.\n* See [this](https://www.drupal.org/docs/develop/using-composer/manage-dependencies#third-party-libraries) for more information.\n* Make sure to add the following to the `extra` section of your composer.json:\n  ```\n  \"installer-paths\": {\n    \"libraries/{$name}\": [\"type:npm-asset\"]\n  }\n  ```\n2. Run `composer require npm-asset/three:^0.151.0` in the drupal-project root directory.\n\n#### A manual way to install three.js:\n1. In `/opt/www/drupal/libraries`, run `git clone --branch=\u003cversion tag\u003e --depth=1 https://github.com/mrdoob/three.js.git`\n   It's a rather large repo, so the `--depth=1` option is recommended to avoid downloading the entire history.\n\n### Three.js Library Compilation\n1. In the module root directory, run `npm install` to install the required packages.\n2. Make sure the three.js library is installed in the correct location expected by webpack.config.js.\n3. Make desired changes to the `js/*.es6.js` file(s), and run `webpack` to compile it to `js/*.js`.\n\nFor an example of compilation, and a way to check if issues are with your code\nchanges or the rest of the setup, see `js/test_threejs.es6.js`,\n`webpack_test_threejs.config.js`, and the `build-test` script in `package.json`.\nTry deleting `js/test_threejs.js` and recompiling it with `npm run build-test`.\n\n## Sponsors\n* [UNR](https://library.unr.edu/)\n\n## Maintainers\nCurrent maintainers:\n* [discoverygarden](https://discoverygarden.ca/)\n\n## License\n[GPLv3](http://www.gnu.org/licenses/gpl-3.0.txt)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdiscoverygarden%2Fdgi_3d_viewer","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdiscoverygarden%2Fdgi_3d_viewer","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdiscoverygarden%2Fdgi_3d_viewer/lists"}