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.
| Lever | What to do | Where to read more |
|---|---|---|
| Disciplines / composition | Load 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 type | Use 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 GIS | For 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.quality | Controls 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.
| Layout | Streams per user |
|---|---|
View3D only, SingleModel | 1 |
| View3D + View2D | 2 |
| Side-by-side comparison (two IafViewer instances) | 2 or more |
Project / MultiModel federation | 1 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
Projectsessions 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.
| Do | Avoid |
|---|---|
Update the model prop when the user selects a different model | Unmounting and remounting the viewer on every model change |
| Keep one instance for a focused navigator | Rendering one viewer per model in a list |
Give the element a stable key, or omit key entirely | key={Math.random()}, or any value that changes on each render |
Memoise prop objects and callbacks with useMemo / useCallback | Rebuilding 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
modelprop 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.
Related
- Model composition
- Federated View3D Buildings on Gis(Mapbox) — federation type, GIS mode, clusters, setup
- Integration Patterns
- IafViewer — mode object prop tables
- IafViewerDBM — DBM data props and animations