Embedded 3D Viewer

The model-viewer is installed as the build-in standard viewer and supports ‘glTF/GLB 3D models’ as the model file format. Alternatively you can use one or multiple custom viewer implementations or our reference implementations from the GitHub repository slub/dlf-3d-viewers. On this page, you will find all the information needed to configure and embed any 3D Viewer implementation for Kitodo.Presentation.

Setup

Add folder with name dlf_3d_viewers in your default storage
Add a subfolder with name of your custom 3D viewer (see Custom Viewer) e.g. 3dviewer or use one or more viewer folders of our reference implementation in GitHub Repository slub/dlf-3d-viewers.

Important

When creating folders through the Filelist module in TYPO3, follow the usual process. However, when creating folders in the system, ensure that the name is URL-compliant.

Configuration

By default, the viewers from the folder dlf_3d_viewers are all active and can be accessed and tested via URL.

For this, only the parameter tx_dlf[viewer] with the name of the viewer and the encoded URL to the model via the parameter tx_dlf[model] need to be passed to the URL under which the plugin plugin.tx_dlf_embedded3dViewer is rendered.

Note

For example in the DFG Viewer, this is the page whose ID is set via the constant config.kitodoPageView.

Automatic selection of the viewer

Under the configuration of the dlf extension, you will find a tab to configure embedded 3D viewer implementation for automatic selection of 3D viewer.

With the configuration field "Viewer model format mapping," you can define a list of considered viewers from the dlf_3d_viewers folder along with their associated model formats. If there are multiple viewers that support the same model format, you can decide here which one is responsible for the specific format.

Additionally, a default viewer can be set, which serves as a fallback for all model formats that have not been mapped.

Custom Viewer

Viewers can be added and customized depending on the use case. A viewer is a folder with the name of the viewer that contains a dlf-3d-viewer.yml file and at least one HTML file. A reference implementation of various 3D viewers for integration into Kitodo.Presentation can be found on GitHub in Repository slub/dlf-3d-viewers.

dlf-3d-viewer.yml

To configure the 3D viewer for Kitodo.Presentation, a dlf-3d-viewer.yml file must be present in the viewer directory.

Key	Description
base	Specify the name of the HTML file in which the viewer will be displayed. (Default is `index.html`)
supportedModelFormats (required)	Specify single or multiple supported model formats of the viewer.

Example

defaultStorage/dlf_3d_viewers/3dviewer/dlf-3d-viewer.yml

viewer:
 base: main.html
 supportedModelFormats:
   - glf
   - ply

Placeholders

Placeholders can be used within the file which is define under the base key of dlf-3d-viewer.yml. The notation for placeholders is {{placeholderName}}. The following placeholders are available:

Name	Description
viewerPath	Path to the viewer directory located inside the `dlf_3d_viewers` folder. For example "fileadmin/dlf_3d_viewers/3dviewer/".
modelUrl	The fileserver where your resource is hosted. For example "https://example.com/my-model.glb".
modelPath	Part of the `modelUrl` where your resource is hosted. For example, if your resource is hosted at "https://example.com/my-model.glb", the value would be "https://example.com/static/models/".
modelResource	Resource part of the `modelUrl` with the filename to be loaded from the endpoint. For example, if your resource is hosted at "https://example.com/my-model.glb", the value would be "my-model.glb".