Skip to main content
Version: v5.3

IafViewer Performance Tips

Guidance for application developers who embed {{IafViewerDBM}} / {{IafViewer}}. These are configuration levers that affect load time, browser cost, and how many Graphics Service streams your application opens. This page does not cover Graphics Service internals (streaming, keep-alive, server memory) or cluster sizing for those streams — both are install concerns.

For mode object props, see IafViewer. For DBM data props, see IafViewerDBM.

Start with what you load​

Most cost comes from how much geometry and how many modes you activate at once.

LeverWhat to doWhere to read more
Disciplines / compositionLoad only the disciplines your screen needs via modelComposition.initial (or the Model Composition UI). Prefer Architectural-only (or a small set) on first paint.Model composition
Federation typeUse SingleModel when the user is focused on one building. Use Project (all workspace models) only when the experience needs multi-building context.Federation Type vs Federated Mode
Federated / outline GISFor campus-scale views, prefer outline / marker federated modes so you are not streaming full detail for every building at once.Federated View3D Buildings on Gis(Mapbox), IafViewer GIS (Mapbox)
modelComposition.qualityControls dynamic-loading aggressiveness: low (default), medium, high. Start with low unless you need more eager loading.Federated View3D Buildings on Gis(Mapbox) (quality)

Example (lean first load):

<IafViewerDBM
model={model}
serverUri={endPointConfig.graphicsServiceOrigin}
modelComposition={{
defaultFederationType: 'SingleModel',
quality: 'low',
initial: {
Architectural: { load: true, visible: true },
Structural: { load: false, visible: false },
Mechanical: { load: false, visible: false },
Electrical: { load: false, visible: false },
Plumbing: { load: false, visible: false },
FireProtection: { load: false, visible: false },
Infrastructural: { load: false, visible: false },
default: { load: false, visible: false },
},
}}
/>

Limit concurrent viewing modes​

Each enabled mode (View3D, View2D, Mapbox GIS, ArcGIS, Unreal Engine, Photosphere) has its own cost. Enable only what the layout needs; hide unused panes with enable: false (or omit the mode) rather than keeping many full-screen modes active.

Running multiple IafViewer instances (side-by-side comparison, multi-window EVM) multiplies that cost. Use multi-instance layouts when the product requires them; for a single focused navigator, one instance is enough.

See Integration Patterns and IafViewer Overview.

Know what your layout costs per user​

Each enabled View3D or View2D opens its own Graphics Service stream, and streams are not shared between users viewing the same model. Whatever layout you ship is multiplied across every concurrent user.

LayoutStreams per user
View3D only, SingleModel1
View3D + View2D2
Side-by-side comparison (two IafViewer instances)2 or more
Project / MultiModel federation1 per building FileSet in the session

ArcGIS, Unreal Engine, and Photosphere drive their own external runtimes and do not consume Graphics Service streams.

What follows from that when you design the app:

  • A second pane doubles the server cost of every user. Enable View2D because a workflow needs it, not as a default.
  • Federated Project sessions scale with building count. For campus views, prefer outline or marker federated modes over loading full detail per building.
  • Rendering is client-side. A low-spec machine can struggle on a single large model, so test on the weakest device you intend to support rather than only on a developer laptop.

How many streams the platform can host concurrently — replicas, pod memory, licence seats — is an install and infrastructure question. Take a concurrency target to whoever owns the deployment rather than inferring it from viewer props.

Keep the viewer mounted​

Mounting {{IafViewerDBM}} is expensive: it opens a Graphics Service stream and rebuilds viewer state. Switching models by updating props costs far less than recreating the component, so treat the viewer as long-lived and let it re-render.

DoAvoid
Update the model prop when the user selects a different modelUnmounting and remounting the viewer on every model change
Keep one instance for a focused navigatorRendering one viewer per model in a list
Give the element a stable key, or omit key entirelykey={Math.random()}, or any value that changes on each render
Memoise prop objects and callbacks with useMemo / useCallbackRebuilding modelComposition or handler props inline on every render
const ModelViewer = ({ models }) => {
const [currentModel, setCurrentModel] = useState(models[0]);

// Selecting another model updates state; the viewer stays mounted.
return (
<IafViewerDBM
model={currentModel}
serverUri={endPointConfig.graphicsServiceOrigin}
/>
);
};

Note: If your application restarts or re-initialises itself when the selected model changes, the viewer remounts every time and pays the full cost again. Update the model prop instead of restarting the app.

Prefer outlines for many buildings​

Federated View3D Buildings on Gis(Mapbox) is designed so you can inspect several buildings in geographic context without loading full detail for every model in the browser. Zoom or select into a building when the user needs detail.

Persistence and defaults​

Admin-configured composition defaults (per user group) can keep first login lean by only enabling the disciplines that matter. See IafViewer Database Persistence.