bimface-helper-v4-3d

BIMFACE v4 Web Application Development Skills - 3D

Usage Notes

• Only supports BIMFACE platform Web applications, using JSSDK v4
• Strictly refer to references/ the code style of the corresponding documentation in the directory, and do not change the interface calling method on your own
• Only implement the functions explicitly requested by the user

Core changes in v4

The core changes in v4 compared with v3 must be paid special attention to when coding:

1. ESM module import: The SDK is loaded via ESM import (await import('...BimfaceSDKLoader-v4.esm.js')), and the script tag fallback can also be used
2. Async first: Many interfaces have changed from synchronous/callback to returning Promise (such as getComponentProperty、getFloors、getBoundingBoxByIds、getMatchIds、setStatus、setStandardView、zoomToBoundingBox、getStatus etc.), and you must use .then() or async/await to handle the result
3. Removal of Config classes: All *Config classes have been removed, and constructors directly receive object parameters
4. Namespace change：Plugins → Plugin(singular);Color class path changed to Glodon.Bimface.Common.Graphics.Color
5. Widget mode: Built-in tools are obtained through app.initializeWidget("WidgetName") + app.getWidget("WidgetName") Get

Interface Calling Guide

1. Page initialization

• SDK loading and application initialization: refer toInitialization

1.1 Requirement analysis (mandatory before coding)

After receiving the user requirement, complete the following steps before starting coding:

1. Capability mapping: Match the keywords of the user requirement against §2 功能模块 to find the matching reference document
2. Scope confirmation: If the requirement involves more than 3 modules, list the modules planned to be called and let the user confirm the priority
3. Unsupported notification: If the requirement cannot match any existing reference, immediately inform the user that "the current SDK capability scope does not support it" to avoid silently generating incorrect code
4. Multi-model determination: If the requirement involves multiple models/integrated models, confirm whether viewer.getModel(modelId) is needed to specify the target model

2. Functional modules

2.1 Scene interaction related

• Common listening events: refer toListening events
• Camera state and viewpoint: refer toCamera, including viewpoint switching, interaction behavior, zooming to bounding box/selected component
• Navigation mode: refer toNavigation mode
• Path roaming: refer toPath roaming

2.2 Component operation related

• Component visibility: refer toComponent visibility
• Component coloring: refer toComponent coloring
• Component highlighting: refer toComponent highlighting
• Component isolation: refer toIsolate components
• Model properties: refer toModel properties
• Component selection: refer toComponent selection
• Bounding box: refer toBounding box
• Grid: refer toGrid
• Model transformation: refer toModel transformation
• Drawing association: ReferenceDrawing association
• Viewpoint positioning: ReferenceViewpoint positioning

2.3 Effect presentation related

• Model explosion: ReferenceModel explosion
• Section box: ReferenceSection box
• Section plane: ReferenceSection plane
• Flame effect: ReferenceFlame effect
• Electronic fence effect: ReferenceElectronic fence effect

2.4 Annotation related

• 3D label: Reference3D label
• Custom label: ReferenceCustom label
• Leader line label: ReferenceLeader line label
• Drawable container: ReferenceDrawable container
• Aggregation label: ReferenceAggregation label
• 3D anchor effect: Reference3D anchor effect

2.5 Tool related

• Model annotation: ReferenceModel annotation
• Model measurement: ReferenceModel measurement
• Model merging tool: ReferenceModel merging tool
• Model editor: ReferenceModel editor
• Navigation map: ReferenceNavigation map

2.6 Spatial analysis

• Room: ReferenceRoom
• Room management: ReferenceRoom management

2.7 External resources

• External component: ReferenceExternal component

2.8 Others

• Component filtering: ReferenceComponent filtering, when the interface description involves filtering based on the component's objectData information, parameters need to be passed according to the filtering condition format

3. Global variable naming conventions

All reference documents uniformly use the following variable names and no longer declare them individually:

Variable name	Type/Description	How to obtain
viewer3D	3D viewer object	app.createViewer({...})
app	WebApplication application object	new Glodon.Bimface.Application.WebApplication3D({domElement, tool:{...}})
model	3D model object	viewer3D.getModel()(single model) or viewer3D.getModel(modelId)(multiple models)
camera	3D camera object	viewer3D.getCamera()

Key constraints：model It can only be obtained after the model has finished loading; in multi-model scenarios, viewer3D.getModel(modelId) must be used to specify the target model.

4. Code self-check

After development is complete, check item by item:

• Function traceability: Compare the generated code with the original requirements one by one, confirm that every function point in the requirements has a corresponding implementation, and that there is no "A was needed but B was generated" or extra generation of unrequested functions
• Whether the variable names are consistent with the naming conventions (viewer3D / model / app / camera）
• Whether each API call can find an identical method signature in the corresponding reference (do not fabricate method names or parameter names on your own); if a function cannot find a clear API in the corresponding reference document, please inform the user that "the current SDK capability scope does not support it"
• Asynchronous Promise：getComponentProperty、getFloors、getBoundingBoxByIds、getMatchIds、getDrawingList、setStatus、setStandardView、zoomToBoundingBox、getStatus（SectionBox/SectionPlane/Annotation/ModelEditor）、getProperty（Room）、getComponents（Room）、getAreas(Model) and other methods that return a Promise, whether they process the result through .then() or async/await .
• Is the color constructed using new Glodon.Bimface.Common.Graphics.Color() instead of Glodon.Web.Graphics.Color
• Does the plugin namespace use Plugin(singular) instead of Plugins
• Does the room class use Glodon.Bimface.Plugin.Room.RoomItem instead of Room
• Does the room manager obtain it via viewer3D.getRoomManager() instead of new RoomManager()
• Does event listening use the addEventListener / removeEventListener pattern
• Are the parameters of component operations (visibility/color/opacity/selection) in object form (e.g. {ids: [...], all: true}) instead of bare arrays
• Is the model loading method viewer3D.loadModel({viewMetaData}) instead of viewer3D.addView(viewToken)

4.1 Common Errors Quick Reference

❌ Incorrect	✅ Correct
model.setColor(...)	Use overrideComponentColorfor component coloring, and setColor
viewer3D.addView(viewToken)	for rooms should use viewer3D.loadModel({viewMetaData/modelId})
model.hideComponentsById(ids)	should use model.hideComponents({ids: componentIds})
model.getComponentProperty(id, callback)	should use model.getComponentProperty(id).then(property => {...})
new Glodon.Web.Graphics.Color(255,0,0,1)	should use new Glodon.Bimface.Common.Graphics.Color(255,0,0,1)
Glodon.Bimface.Plugins.Marker3D.Marker3D	should use Glodon.Bimface.Plugin.Marker3D.Marker3DItem
new Glodon.Bimface.Plugin.Room.Room(...)	should use new Glodon.Bimface.Plugin.Room.RoomItem({...})
new RoomManager({viewer})	should use viewer3D.getRoomManager()
sectionBox.exit()	should use sectionBoxTool.switchOff()
measure.setUnits({...})	should use measureTool.setResultFormat({...})
camera.setView(...)	should use camera.setStandardView(...)
camera.setState(state)	should use camera.setStatus(state).then(...)