IafViewer FAQs
FAQs for application developers who embed {{IafViewerDBM}} / {{IafViewer}}, and for product users configuring the viewer. Topics that previously lived as separate Confluence FAQ trees (UX, Animations, Model Composition, EVM / View3D / GIS / ArcGIS / UE, Federated Model) are merged here into one categorized list.
It does not cover IafViewer package internals, Graphics Service ops, OC deployment runbooks, or hosting/infrastructure.
For mode object props (view3d, gis, modelComposition, …), see IafViewer. For DBM data props and animations, see IafViewerDBM. For load-time levers, see IafViewer Performance Tips.
Contents
- Getting started
- Model composition
- Federated models and GIS (Mapbox)
- Camera sync (GIS + View3D)
- View3D / enhanced viewing modes
- ArcGIS
- Unreal Engine
- APS (Autodesk Platform Services)
- Photosphere and animations
- Internationalization
- UX and UI
- Callbacks and selection
Getting started
What happens when the model prop is set on {{IafViewerDBM}}?
With modelComposition.defaultFederationType SingleModel (default), only that model is selected and displayed. With Project, model can still select which model is primary or focused while workspace models remain loaded per Project behavior.
What happens if the model prop is omitted?
With SingleModel, a model must be supplied for the viewer to load content. With Project, the viewer loads workspace models when model is omitted (or used only to set primary). See how to set up a federated view.
Model composition
What is model composition and defaultFederationType?
modelComposition configures which models load and how. defaultFederationType values:
| Value | Behavior |
|---|---|
SingleModel (default) | One model from model / modelVersionId |
Project | All models in the current workspace / namespace |
MultiModel | Only the models listed in clusteredModels. View3D outlines come only from View3D clusters; APS clusters are placed as GlbDraco outlines. |
Resolution order: props.settings → localStorage (iafviewer_settings) → props.modelComposition → Property Store default. Full table: Model composition.
Details: Federated View3D Buildings on Gis(Mapbox).
What other modelComposition options matter for apps?
initial— per-discipline{ load, visible }(Architectural is typically on by default).clusteredModels— optional clusters of models (filter + shared map outline / site). Each cluster lists its models inids; setevmMode: 'aps'for a cluster of APS design URNs.quality—low|medium|highfor dynamic-loading eligibility.
See IafViewer Performance Tips and Model composition.
Should a cluster list its models in ids or modelIds?
Use ids. modelIds is a legacy alias that works only for View3D clusters. APS clusters must use ids. See View3D and APS clusters and modelComposition.
Why does MultiModel show no View3D outlines?
In MultiModel federation, View3D outlines come only from View3D clusters. If no View3D clusters are defined, the viewer doesn't fall back to loading all project models. Add a cluster with the model ids you want on the map.
Why is modelComposition.quality necessary?
Linked models are not always split cleanly by discipline. quality controls how strictly the viewer decides whether a linked model is eligible to load for the selected disciplines (low = broader eligibility; medium = local then global; high = view presence–based). Prefer low on first paint unless you need more eager loading.
How are discipline settings set — app or plugin?
Initial disciplines come from the app via modelComposition.initial. After the user changes toggles in the viewer, local storage (or remote persistence when enablePersistence is true) can override that.
Can users change composition in the UI?
Yes. Discipline toggles and related options are available under the viewer toolbar Settings → Model Composite.
Is the quality: 'high' threshold (composed layer percent) from a plugin?
No. It is driven by the app-supplied modelComposition.quality value; the viewer applies the eligibility logic.
Federated models and GIS (Mapbox)
GIS is configured with the top-level gis prop group (not nested under view3d). Use gis.enable (not enabled).
What is Federated Mode vs Federation Type?
| Setting | Controls |
|---|---|
modelComposition.defaultFederationType | Which models load (SingleModel / Project / …) |
gis.federatedMode | How multiple models appear on the map (None, Outline, Dynamic, Markers, …) |
See Federation Type vs Federated Mode.
Can both be set via props on {{IafViewerDBM}}?
Yes. Federation type via modelComposition.defaultFederationType (or settings). Federated mode via gis.federatedMode. Prefer the enum from EvmUtils / IafEvmUtils (for example EvmFederatedMode.Outline), not free-form strings such as "Outline" or "soft" — strings are not accepted and the mode may stay at None.
Why do outlines appear when I didn't set gis.federatedMode?
The default for gis.federatedMode is Outline. If you don't want outlines, set it to EvmFederatedMode.None explicitly. See GIS.
How can multiple models be shown on the same map?
Use defaultFederationType: "Project", enable GIS (gis.enable: true), and set an appropriate gis.federatedMode (for example Outline or Dynamic). Optionally set gis.primaryModelId as the reference model. Walkthrough: how to set up a federated view.
What is clusteredModels?
Optional array under modelComposition used with Project / MultiModel to (1) filter which models participate and (2) group models that share one outline / site on the map. A cluster can hold View3D models (the default) or APS designs (evmMode: 'aps'). See View3D and APS clusters and Multi-model GIS.
How do gis.initial and clusteredModels zoom work together?
They control different moments:
gis.initial— default map session (zoom, pitch, bearing, optional center) on first build / Home-style reset.clusteredModels[].zoom— optional fly-to zoom when focusing a model in that cluster (for example marker click). Pitch/bearing still come fromgis.initialunless changed elsewhere.gis.dynamicRenderingZoom/gis.dynamicRenderingDistance— Dynamic federated mode thresholds (markers vs outline vs full model), not the default session zoom.
Can Dynamic Mode zoom thresholds be adjusted?
Yes. Use gis.dynamicRenderingZoom (map zoom threshold, default often 14) and gis.dynamicRenderingDistance (meters, default often 750) for representation switches in Dynamic mode. Default session zoom remains gis.initial.zoom.
Why does gis.onModelSelect fire on both click and double-click?
gis.onModelSelect(modelId, eventType, modelIds) fires for both 'click' and 'dblclick', and also when View3D is disabled. If your handler should react to only one of them, check eventType. modelIds lists every marker under the pointer, including IDs and APS IDs, so filter it in your application. See Responding to marker selection.
How do I open a building in a separate View3D widget from a GIS-only map?
- Set
gis.initial.enableOverlaytofalseso the map doesn't draw the detailed model itself. - Handle
gis.onModelSelectto get the selected model ID. - Load that model in your separate View3D widget.
See Showing the detailed model in a separate widget.
Why are None and Dynamic missing from the federated-mode list, and Reference Model disabled?
The map overlay is off. This happens when gis.initial.enableOverlay is false or when any APS cluster is present. With the overlay off, the federated-mode list offers only modes that don't draw the detailed model on the map, and Reference Model, Rendering Distance, and Rendering Zoom are disabled.
When I move one building, why does “Apply location shift” appear?
Only when the workspace has more than one building. The moved building updates immediately; the dialog asks how to treat the others so the federation stays consistent. Single-building projects do not show the dialog.
What do the “Apply location shift” options mean?
| Option | Effect |
|---|---|
| Auto Adjust Others | Shift every other building by the same delta (relative layout preserved) |
| Reset Others | Move all others to the same new location (stack) |
| Ignore Others | Leave others unchanged |
| Cancel | Undo the move for the building you just moved |
After a choice, horizontal realignment is typically turned off for the moved building.
When is location search (geocoder) available?
When horizontal realignment is on for the selected building. See IafViewer GIS (Mapbox).
Camera sync (GIS + View3D)
Why avoid calling Mapbox setCenter (and similar) directly?
If View3D is enabled, driving the raw Mapbox camera updates the map only and desynchronizes View3D. Prefer viewer-mediated interaction and documented props/callbacks. If View3D is off (GIS-only), direct map camera APIs are generally unrestricted.
Are View3D camera APIs restricted when GIS is on?
They are not fully blocked for legacy reasons, but driving View3D independently of the map while both are enabled is not recommended — it can desync the two views.
Why doesn't my view3d.camera change stick when the map overlay is on?
When the GIS overlay is on, the map's camera sync can overwrite the View3D camera every frame, so your camera change competes with it. If your application needs to set the View3D camera itself, turn the overlay off with gis.initial.enableOverlay: false.
What is the recommended approach when both are enabled?
Treat {{IafViewerDBM}} as the single place that owns camera / map pose. Use GIS UI and federated controls; observe with view3d.onCameraUpdate if your app needs a mirror of camera state. Details: Federated View3D Buildings on Gis(Mapbox) — Step 3.
View3D / enhanced viewing modes
Is @dtplatform/iaf-viewer too large because it supports so many modes?
No. Modes are modular: Communicator (2D/3D), Mapbox GIS, ArcGIS, UE, Photosphere, and others load only when enabled via props. If a mode is disabled, its heavy dependencies are not loaded. With no modes enabled, the viewer stays a blank canvas. Prefer enabling only the modes your layout needs — see IafViewer Performance Tips.
How do I enable only the modes my layout needs?
Pass mode groups such as view3d, view2d, gis, arcgis, unreal, photosphere with enable: true|false. Each enabled mode has cost — see IafViewer Overview.
How do I hide a mode without turning it off?
Set the mode's visible flag to false, for example aps: { enable: true, visible: false }. Every EVM prop group has a visible flag, such as view3d.visible, aps.visible, or gis.visible. It defaults to true and shows or hides an enabled widget without turning it off. To turn the mode off, set enable to false instead.
Must view3d.enable be set explicitly to true?
Yes for current EVM-style usage. If view3d.enable is omitted/undefined, 3D may not load and the console can warn that enable is undefined. Set view3d: { enable: true } when you want Communicator 3D. Explicit enable is the safe app contract.
Can Mapbox GIS run as a standalone mode (no 2D/3D)?
Yes. Disable Communicator views and enable GIS only, for example:
view3d: { enable: false },
view2d: { enable: false },
gis: {
enable: true,
token: '<mapbox-token>',
onIafMapReady: (iafMap) => { /* optional map controls */ },
},
Does GIS still load when gis.enable is true but no 3D model is present?
It should. If GIS fails to appear in that case, check that GIS props and tokens are valid and that no app logic is gating the map on a 3D model being present.
How does Communicator / HOOPS dependency loading work?
IafViewer loads Communicator-related dependencies dynamically when view3d or view2d is enabled. Apps should not manually inject hoops-web-viewer scripts. Wait for readiness via OnViewerReadyCallback ('2d' / '3d') before using Communicator APIs.
Can the app access the underlying HOOPS / Mapbox / ArcGIS / UE engines?
Yes, through documented ready callbacks (not by forking viewer internals):
| Mode / engine | Typical callback |
|---|---|
| Mapbox GIS / ArcGIS map | onIafMapReady (on the relevant prop group) |
| HOOPS Communicator 2D/3D | onViewerReady / OnViewerReadyCallback |
| Unreal Engine | onUeReady |
Prefer props for common workflows; use these callbacks for advanced engine access. To decide between a mode and embedding the toolkit directly, see Why use an IafViewer EVM instead of a native viewer embed.
What’s the best way to compare models side by side?
Use two viewer instances (for example QuickModelView / model comparison patterns). See Model Comparison Using View3D and Integration Patterns.
Does View3D rendering-mode switching require app wiring?
Yes. view3d.renderingMode / onRenderingModeChange require the host app to participate (wire the callback and keep app or persisted state in sync). Without that, UI mode switching can fail or leave inconsistent state.
For View3D/2D feature UI, see 2D and 3D features.
How do I save and restore a camera view?
Store the payload that view3d.onCameraUpdate returns, then assign it back to view3d.camera. Set delayInMs on onCameraUpdate to control how often it fires. See View3D props and View3d.
Is the Communicator Camera.toJson() format still accepted for view3d.camera?
Yes. The viewer converts a Camera.toJson() object into an absolute camera. For new code, use the structured view3d.camera object with mode set to 'spherical' or 'absolute'.
Why do isolated spaces look different in Glass mode?
view3d.rendering.ignoreSpaceTransparencyInGlass is true by default. In Glass mode, the viewer draws isolated spaceElementIds in the XRay Selected overlay, which overrides the space transparency set in the model. To keep the model's space transparency, set it to false.
Should apps copy Graphics Service / IafViewer source for POCs?
No. Use official @dtplatform/iaf-viewer package builds and documented hooks. Do not fork or copy internal Graphics Service viewer code into apps — that diverges from the platform and is unsupported.
ArcGIS
Should the app load ArcGIS via CDN or @arcgis/core (NPM)?
Choose one load path and keep it consistent with your bundler and CSP:
- NPM (
@arcgis/core) — typical for production apps that already use a modern bundler; versions stay aligned with your lockfile. - CDN — useful for prototypes or hosts that inject the ArcGIS JS API globally.
Configure the viewer’s arcgis props as described in IafViewer ArcGIS. Prefer props and documented ready callbacks (for example map-ready style callbacks) over reaching into SceneView internals.
How should the app drive ArcGIS (or UE) behavior — props or legacy command?
Prefer declarative props (opinionated, reactive), for example zoomElements. The command property remains supported for existing apps but is documented as legacy — there are no immediate deprecation plans. Recommended patterns:
- Props such as
zoomElementsfor declarative workflows - Ready-callback
sendCommand(for example fromonIafMapReady/onUeReady) for programmatic commands - Legacy
commandprop when you need full control of command payloads
Use EVM_COMMANDS / EVM_EVENTS (via EvmUtils) for consistency.
See IafViewer ArcGIS for props, ready callbacks, and EVM_COMMANDS / EVM_EVENTS. The Commands API page is the separate View3D IafViewer.commands bag (selection, camera, cutting planes) — not the ArcGIS / UE command queue.
Unreal Engine
How do I embed Unreal Engine with IafViewer?
Use the unreal / ue prop group on {{IafViewerDBM}} and follow IafViewer Unreal Engine. Combine with ArcGIS or Photosphere only when the layout needs those modes; each adds cost (performance tips).
Is the UE command prop deprecated?
No. It is marked legacy in docs to steer new work toward props and onUeReady / sendCommand, but it remains functional for existing apps. Prefer:
ue: {
enable: true,
config: { /* streaming config */ },
// Preferred declarative zoom
zoomElements: [{ elementId: '123', uuid: crypto.randomUUID() }],
onUeReady: ({ sendCommand, viewerReady }) => {
if (viewerReady && sendCommand) {
// programmatic commands when needed
}
},
eventHandler: (event) => { /* EVM_EVENTS */ },
}
When showToolbar is true, does the app receive UE UI commands?
Toolbar / EVM widget interactions update IafViewer state (for example display mode), which is passed down as props to control the UE view. Apps should rely on props/callbacks rather than assuming raw command streams from every UE chrome click. Details: IafViewer Unreal Engine.
Where are UE integration examples?
See IafViewer Unreal Engine and Reference app UE samples. Prefer official package examples over copying Graphics Service internals.
APS (Autodesk Platform Services)
Where does the APS viewer token come from?
Your application supplies it in aps.config.accessToken, which is required. GraphicsService only provides an optional APS REST proxy. The browser also needs network access to developer.api.autodesk.com, which serves the Autodesk viewer SDK. See Prerequisites and Access token scopes.
Can I reuse View3D element IDs in aps.selection?
No. aps.selection takes Autodesk viewer dbId integers, and there is no mapping between IDs and dbId values. Get dbId values from aps.callbacks.onSelectedElementChange. See APS.
How do I load several APS designs in one viewer?
Pass an array of URNs in aps.config.urn. Element 0 is the primary design and drives the single-design APIs. To react when the array changes after the first load, use aps.callbacks.onApsModelsChange. See Loading multiple models.
Do aps.cuttingPlanes affect View3D cutting planes?
No. aps.cuttingPlanes applies only to the APS viewer. View3D cutting planes are configured separately.
Why does an APS design show as a marker on the map instead of an outline?
No outline is available for that design from APS Extra Derivatives, so the map shows a marker instead. When an outline is available, aps.config.modelOutlineQuality controls its mesh quality. See APS models on Mapbox.
Why don't my APS clusters appear with Project federation?
APS clusters load only with MultiModel federation. SingleModel ignores them, and Project doesn't place them on the map. Set modelComposition.defaultFederationType to MultiModel. See View3D and APS clusters.
Photosphere and animations
How do I enable photosphere (360°) viewing?
Configure the photosphere prop group. See IafViewer Photosphere.
Why do photosphere hotspot links fail on localhost?
Usually an application localhost setup/config issue (URLs, auth, CORS), not a viewer defect. Verify the same build in a shared environment and check hotspot target URLs.
How do animations / workflows work?
Pass a workflow prop with animation scripts (markup, transforms, and related frame types). See Animations and IafViewerDBM animations.
My 2D sheet animation does not show — what should I check?
- Element IDs — Confirm
elementIdsmatch the 2D asset (select the element in the viewer and verify IDs from selection/logs). enableOptimizedSelection— TryenableOptimizedSelection={true}on the viewer if overlays never appear.- Timing — Set or update
workflowafter 2D sheets are ready. Wait forOnViewerReadyCallbackwithmodelType === '2d'(or the equivalent ready callback) before applying workflow.
Example shape (illustrative):
workflow: {
active: 3,
list: [{
uuid: 3,
timeInSeconds: 4.5,
loop: true,
script: [{
uuid: 'wf-3.markup.circle',
elementIds: [478],
type: 'Markup',
frames: [{ type: 'Circle', status: 'Error', blink: true, scale: 1.4 }],
}],
}],
}
Internationalization
Why is the viewer still in English when my browser is set to another language?
The viewer doesn't read the browser language. Pass a BCP 47 tag in i18n.locale, for example locale: 'ja-JP'. Unsupported languages and missing strings fall back to English. See Localizing the viewer.
How do I override one label?
Pass a nested object in i18n.messages that contains only the keys you want to change, for example { tooltips: { ResetView: 'Restore the default 3D view' } }. Don't use flat dotted keys such as "tooltips.ResetView". To find keys, see IafI18n.catalog. Keep any {placeholders} in the string unchanged. See Message overrides.
Why do characters show as boxes after I set i18n.fontFamily?
Setting i18n.fontFamily replaces the font stack the viewer derives from the locale, and Noto fonts aren't bundled. Include fonts that cover the script, such as CJK, Devanagari, or Tamil, in your stack. See Fonts.
Are model names, IFC/Revit types, or unit symbols translated?
No. The i18n prop localizes only the viewer interface, such as the toolbar, settings, and notifications. Data from the model stays as stored. See What to localize.
Are right-to-left languages supported?
No. The viewer doesn't support right-to-left layout.
UX and UI
What does showSidePanel do?
Boolean (default false). When false, the side panel stays hidden until the user opens a panel toolbar action (Settings, Markups, Cutting Planes, GIS, and similar). Opening a panel overrides the hidden state for that session.
Can the toolbar be customized to show only some actions?
Yes. Apps can hide the standard toolbar and/or drive a minimal set of actions for a focused experience (for example GIS-focused layouts in viewer examples). Prefer documented props for launcher/toolbar visibility rather than DOM hacks.
Can the GIS panel be prevented from opening by default when gis.enable is true?
Prefer explicit toolbar / launcher props for your layout. Confirm the available props for panel and launcher visibility in IafViewerDBM.
Callbacks and selection
What shapes does OnViewerReadyCallback accept?
The argument can be:
- a string
'2d'|'3d'when structure is ready, or - an object
{ modelType, modelId, modelVersionId }when model selection changes inside the viewer (for example GIS).
Handle both shapes. See IafViewerDBM, IafViewer UI — selection, and the Integration Guide Multiple Selection with IafViewerDBM.
What is OnModelCompositionReadyCallback?
Called when desired linked models / views for composition are ready (modelType '2d' | '3d', plus related readiness flags). Use it to run app logic that must wait until composition is loaded.
It fires each time the viewer fetches a segment, linked model, discipline, or layer, so it can fire several times in one session.
Related
- IafViewer Overview
- IafViewer Performance Tips
- Federated View3D Buildings on Gis(Mapbox) — federation type, GIS mode, clusters, setup
- Why use an IafViewer EVM instead of a native viewer embed — when to use an EVM instead of embedding its toolkit
- IafViewer GIS (Mapbox)
- IafViewer APS — Autodesk Platform Services viewer mode
- IafViewer internationalization —
i18nprop: locales, message overrides, fonts - IafViewer — mode object prop tables
- IafViewerDBM