rnsrk/dfg_3dviewer_js_library
1
0
Fork 0
Code Issues Pull requests Projects Releases 1 Packages Wiki Activity Actions
dfg_3dviewer_js_library/viewer/FUNCTIONS.md
rsnrk 05c65aad4d Initial commit
2026-06-25 09:11:23 +02:00

9 KiB
Raw Blame History

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