239 lines
No EOL
9 KiB
Markdown
239 lines
No EOL
9 KiB
Markdown
# Viewer Function Reference
|
||
|
||
This file documents the main exported viewer functions and helpers used by the viewer runtime.
|
||
It is intended as a quick reference for the current `viewer/` module exports and their roles.
|
||
|
||
## `viewer/main.js`
|
||
|
||
`viewer/main.js` exposes the exported `Viewer` object and core runtime entry points.
|
||
|
||
- `Viewer.MainInit()`
|
||
- Initialize the viewer runtime.
|
||
- Loads `viewer-settings.json`, configures the DOM container, sets up core state, starts the animation loop, and prepares the viewer for model loading.
|
||
|
||
- `Viewer.mainLoadModel()`
|
||
- Load the current model from `core.fileObject`.
|
||
- Handles all supported file formats, archive transformations, GLTF/GLB loading, and post-load scene preparation.
|
||
|
||
- `Viewer.mainLoadModelWrapper()`
|
||
- Wrapper for `mainLoadModel()`.
|
||
- Normalizes auto-paths and archive paths before delegating to the loader.
|
||
|
||
- `Viewer.prepareSandboxScene()`
|
||
- Reset the viewer for sandbox mode.
|
||
- Clears loaded objects, resets camera and controls, and shows sandbox UI hints.
|
||
|
||
- `Viewer.setModelPaths()`
|
||
- Parse and populate `core.fileObject` from `core.fileObject.originalPath`.
|
||
- Sets `filename`, `basename`, `extension`, `path`, `uri`, and `relativePath`.
|
||
|
||
- `Viewer.normalizeFileUrl(rawUrl)`
|
||
- Normalize source URLs and Drupal `public://` paths.
|
||
- Converts relative model attributes into canonical browser URLs.
|
||
|
||
- `Viewer.normalizeDrupalFilesPath(path)`
|
||
- Normalize Drupal file paths by stripping `sites/default/files` prefixes and trimming slashes.
|
||
|
||
- `Viewer.normalizeArchiveModelPath(path)`
|
||
- Fix archive-derived model paths by injecting a `/gltf/` segment when needed.
|
||
|
||
- `Viewer.applyCameraOverridesFromUrl()`
|
||
- Apply camera position, camera target, and FOV overrides from URL query parameters.
|
||
|
||
- `Viewer.toggleFullscreen()`
|
||
- Enter or exit fullscreen mode for the viewer container.
|
||
|
||
- `Viewer.updateSize()`
|
||
- Resize the renderer, camera, GUI, metadata, and action menu when the viewport changes.
|
||
|
||
- `Viewer.setCameraProjection(projection)`
|
||
- Switch the viewer camera between perspective and orthographic projection.
|
||
|
||
- `Viewer.toHexColor(input)` / `Viewer.toThreeColor(input)`
|
||
- Normalize different color input formats into numeric or `THREE.Color` values.
|
||
|
||
- `Viewer.disposeObjectResources(object)`
|
||
- Dispose of mesh geometry and material resources for an object tree.
|
||
|
||
- `Viewer.removeAndDisposeFromScene(object)`
|
||
- Remove an object or object array from the scene and dispose its resources.
|
||
|
||
- `Viewer.resetLoadedModelState()`
|
||
- Clear viewer state related to loaded models, annotations, selection, and helper objects.
|
||
|
||
- `Viewer.reportError(error, options)`
|
||
- Report viewer errors consistently to console, toast notifications, and E2E state.
|
||
|
||
- URL and parameter parsing utilities:
|
||
- `Viewer.parseBooleanParam(value)`
|
||
- `Viewer.parseFloatParam(value)`
|
||
- `Viewer.parseVector2Param(value)`
|
||
- `Viewer.parseVector3Param(value)`
|
||
- `Viewer.formatVector3Param(vector)`
|
||
|
||
- Viewer support utilities:
|
||
- `Viewer.getSupportedFormatsText()`
|
||
- `Viewer.getSupportedArchiveFormatsText()`
|
||
- `Viewer.getDistanceMeasurementScaleMeters()`
|
||
- `Viewer.formatMeasuredDistance(rawDistanceInModelUnits)`
|
||
- `Viewer.toggleAutoRotateByKeyboard()`
|
||
- `Viewer.onViewerKeyDown(event)`
|
||
|
||
|
||
## `viewer/loaders.js`
|
||
|
||
`viewer/loaders.js` contains model loaders, environment sync logic, and loading progress/error handlers.
|
||
|
||
- `loadDDSLoader()` / `loadMTLLoader()` / `loadOBJLoader()` / `loadFBXLoader()`
|
||
- `loadPLYLoader()` / `loadColladaLoader()` / `loadSTLLoader()` / `loadXYZLoader()`
|
||
- `loadTDSLoader()` / `loadPCDLoader()` / `loadGLTFLoader()` / `loadDRACOLoader()`
|
||
- `loadIFCLoader()` / `loadRoomEnvironment()` / `loadHDRLoader()`
|
||
- Dynamically import the corresponding Three.js loader or environment helper.
|
||
|
||
- `syncSceneEnvironment(enabled = true, preset = null)`
|
||
- Load the environment texture for the scene and apply it to `core.scene`.
|
||
- Supports built-in studio and HDR presets.
|
||
|
||
- `loadModel()`
|
||
- Main engine for model loading.
|
||
- Detects file type, chooses the correct loader, applies geometry/material setup, adds the object to the scene, and triggers metadata loading.
|
||
|
||
- `getModuleAssetBasePath()`
|
||
- Resolve the runtime asset base path based on build target, Drupal environment, and local preview mode.
|
||
|
||
- `onError(_event)`
|
||
- Generic loader error handler.
|
||
|
||
- `onErrorMTL(_event)`
|
||
- Fallback loader error handler for OBJ/MTL bundles.
|
||
|
||
- `onErrorGLB(_event, params, loadedTimes)`
|
||
- Retry logic for GLB loading errors.
|
||
|
||
- `onProgress(xhr)`
|
||
- Update progress UI while a model is downloading.
|
||
|
||
|
||
## `viewer/metadata.js`
|
||
|
||
`viewer/metadata.js` handles metadata fetching, metadata panel rendering, and IIIF support.
|
||
|
||
- `addWissKIMetadata(label, value)`
|
||
- Map WissKI field names to localized metadata display labels.
|
||
|
||
- `lilGUIhasFolder(folder, name)` / `lilGUIgetFolder(gui, name)`
|
||
- Find lil-gui folders by title.
|
||
|
||
- `expandMetadata()`
|
||
- Toggle the metadata panel open/closed.
|
||
|
||
- `appendMetadata(metadataContent)`
|
||
- Render metadata HTML into the viewer metadata container.
|
||
|
||
- `fetchMetadata(_object, _type)`
|
||
- Count vertices or faces for a mesh object.
|
||
|
||
- `handleMetadataResponse(data, metadata, object, hierarchyMain)`
|
||
- Build the metadata panel and edit/hierarchy UI after loading a model.
|
||
|
||
- `settingsHandler(object, hierarchyMain, data)`
|
||
- Apply object and camera settings after metadata has been loaded.
|
||
|
||
- `traverseObject(object)`
|
||
- Run object traversal logic for metadata and camera setup.
|
||
|
||
- `presentationMode(object)`
|
||
- Apply presentation-mode-specific scene setup.
|
||
|
||
- `fetchSettings(object)`
|
||
- Fetch remote metadata payloads and dispatch metadata handling.
|
||
|
||
- `createIIIFDropdown(iiifConfigURL)`
|
||
- Render a dropdown for selectable IIIF manifests.
|
||
|
||
- `createAIM3IFDropdown()`
|
||
- Render a dropdown for selectable AIM³IF manifests.
|
||
|
||
- `createManifestUI()`
|
||
- Create the IIIF/AIM³IF manifest loader UI panel.
|
||
|
||
|
||
## `viewer/viewer-utils.js`
|
||
|
||
`viewer/viewer-utils.js` contains viewer helpers for clipping planes, UI notifications, camera setup, and background rendering.
|
||
|
||
- `initClippingPlanes()`
|
||
- Initialize the three clipping planes used by the viewer.
|
||
|
||
- `toastHelper(key, toneOrOptions, maybeOptions)`
|
||
- Show a translated status toast by key.
|
||
|
||
- `showToast(message, toneOrOptions, maybeOptions)`
|
||
- Show a message or translated toast directly.
|
||
|
||
- `getErrorMessage(error)`
|
||
- Normalize error objects or strings into a message.
|
||
|
||
- `reportViewerError(error, options)`
|
||
- Report errors through console, toast, and E2E state.
|
||
|
||
- `setupObject(_object, _metadata)`
|
||
- Adjust object position, rotation, scale, and camera based on metadata or configuration.
|
||
|
||
- `setupCamera(_object, _data)`
|
||
- Set up camera, controls, lights, and background for the loaded object.
|
||
|
||
- `applyGradientCss(gradient)`
|
||
- Set a CSS gradient background from parsed gradient values.
|
||
|
||
- `changeBackground(_type, _color1, _color2 = _color1, _alpha = 100)`
|
||
- Set viewer canvas background color or gradient.
|
||
|
||
- `invertHexColor(hexTripletColor)`
|
||
- Return the inverted value for a hex color string.
|
||
|
||
- `getOrAddGuiController(object, prop)`
|
||
- Find or create a lil-gui controller by property name.
|
||
|
||
|
||
## `viewer/utils.js`
|
||
|
||
`viewer/utils.js` exposes generic utility functions used throughout the viewer.
|
||
|
||
- `distanceBetweenPoints(pointA, pointB)`
|
||
- `distanceBetweenPointsVector(vector)`
|
||
- `vectorBetweenPoints(pointA, pointB)`
|
||
- `halfwayBetweenPoints(pointA, pointB)`
|
||
- `interpolateDistanceBetweenPoints(pointA, vector, length, scalar)`
|
||
- Geometry helpers for basic vector math.
|
||
|
||
- `detectColorFormat(color)`
|
||
- `hexToRgb(hex)`
|
||
- `parseCssColor(str)`
|
||
- `normalizeColor(value)`
|
||
- Color parsing and normalization helpers.
|
||
|
||
- `isValidUrl(urlString)`
|
||
- `truncateString(str, n)`
|
||
- String and URL utilities.
|
||
|
||
- `getProxyPath(url, config)`
|
||
- Build proxied asset URLs for server-side proxy support.
|
||
|
||
|
||
## `viewer/viewer-settings.js`
|
||
|
||
- `loadSettings()`
|
||
- Load `viewer-settings.json` relative to the current module path.
|
||
- Used by source-mode development and runtime config loading.
|
||
|
||
## scripts/convert.sh
|
||
- ```handle_file``` - uses python script (downloaded and modified version of https://github.com/ux3d/2gltf2/tree/master) triggered by blender
|
||
```${BLENDER_PATH}blender -b -P ${SPATH}/scripts/2gltf2/2gltf2.py -- "$INPATH/$FILENAME" "$GLTF" "$COMPRESSION" "$COMPRESSION_LEVEL" "$OUTPUT$OUTPUTPATH"```
|
||
- ```handle_ifc_file``` - uses IfcConvert script (available at https://ifcopenshell.sourceforge.net/ifcconvert.html)
|
||
```${SPATH}/scripts/IfcConvert "$INPATH/$FILENAME" "$INPATH/gltf/$NAME.glb"```
|
||
- ```handle_blend_file``` - uses python script triggered by blender
|
||
```${BLENDER_PATH}blender -b -P ${SPATH}/scripts/convert-blender-to-gltf.py "$INPATH/$FILENAME" "$INPATH/gltf/$NAME.glb"```
|
||
|
||
- automatic rendering of 3D model for thumbnails - function ```render_preview```, which uses wrapper for triggering virtual environment (xvfb-run) for blender and it’s python script
|
||
```xvfb-run --auto-servernum --server-args="-screen 0 512x512x16" sudo ${BLENDER_PATH}blender -b -P ${SPATH}/scripts/render.py -- "$INPATH/$NAME.glb" "glb" $1 "$INPATH/views/" $IS_ARCHIVE -E BLENDER_EEVEE -f 1``` |