IafViewer APS
Overview
APS mode displays Autodesk Platform Services (APS) designs in the IafViewer. It runs the Autodesk Viewer (LMV), which the IafViewer loads from the Autodesk CDN. The default SDK version is 7.100; to use another version, set aps.config.sdkVersion.
APS is an Enhanced Viewing Mode (EVM) widget, like View3D or GIS. Your application drives it through aps.* props and receives events through aps.callbacks.*. Your application supplies the APS viewer token. GraphicsService provides an optional proxy to the APS REST APIs (OSS, Model Derivative, and Extra Derivatives) for effective visualization. GraphicsService doesn't send commands to the LMV canvas.
Your application owns OSS model management: uploads, buckets, and object keys. To sync APS with other modes, such as Mapbox, add the logic in your application.
For the full prop reference, see IafViewer — APS. IafViewerDBM forwards the same aps prop.
Prerequisites
- Network access to
developer.api.autodesk.com, which serves the LMV SDK. - An APS viewer token that your application supplies in
aps.config.accessToken. - Optional: An APS-enabled GraphicsService, for the APS REST proxy.
- One or more translated design URNs.
Setting up APS mode
To display an APS design in the IafViewer, complete the following steps:
- Set
aps.enabletotrue. - Pass one or more design URNs in
aps.config.urn. - Set
aps.config.accessTokento your APS viewer token. - Optional: To list or upload models, set
aps.config.bucketKey. You don't need it when you pass a URN. - Add an
aps.callbacks.onApsReadycallback to receive the viewer state and helper APIs after the design loads.
import { IafViewerDBM, IafEvmUtils } from '@dtplatform/iaf-viewer';
<IafViewerDBM
aps={{
enable: true,
layout: { displayMode: IafEvmUtils.EVMDisplayMode.FULLSCREEN, showToolbar: true },
config: {
urn: ['dXJuOmFkc2sub2JqZWN0czpvcy5vYmplY3Q6...'], // element 0 = primary
accessToken: hostApsToken, // APS viewer token supplied by your application
// bucketKey: 'my-oss-bucket', // optional if urn is provided
},
camera: { enable: true, view: 'fit' },
rendering: { mode: 'shaded' },
callbacks: {
onApsReady: (payload) => console.log(payload.viewerState, payload.apis),
onSelectedElementChange: (dbIds) => setSelected(dbIds),
},
}}
/>
The IafViewer forwards accessToken to GraphicsService as the X-Aps-Access-Token header, and bucketKey as X-Aps-Bucket-Key.
Access token scopes
The scopes of the APS token in aps.config.accessToken decide which APIs work. Request only the scopes your application needs.
| Scope | What it enables |
|---|---|
viewables:read | Loading and viewing designs (aps.config.urn), and the viewer-side helpers in payload.apis.client |
data:read | Server read calls in payload.apis.server: fetchModelsList, fetchModelStatus, fetchModelMetadata, fetchModelProperties / fetchModelPropertiesQuery, fetchExtraDerivativesStatus, and the download helpers. Also needed to download existing outlines for Mapbox. |
bucket:read | fetchBucketsList |
data:write and data:create | uploadModelFile, startTranslationForUrn, startExtraDerivatives / buildOutline, and deleteModel |
A call outside the token's scopes fails with an authorization error from APS, while the rest of the viewer keeps working. For example:
// Viewer only: designs load and display, but server calls such as
// payload.apis.server.fetchModelProperties fail with an authorization error.
const viewerToken = await getApsToken(['viewables:read']);
// Design review: also read status, metadata, and element properties.
const reviewToken = await getApsToken(['viewables:read', 'data:read']);
// Model management: also list buckets, upload, translate, and delete.
const adminToken = await getApsToken([
'viewables:read', 'data:read', 'bucket:read', 'data:write', 'data:create',
]);
<IafViewerDBM
aps={{ enable: true, config: { urn: designUrns, accessToken: reviewToken } }}
/>
Here, getApsToken stands for your application's own APS token service.
Loading multiple models
To load several designs into one APS viewer, pass an array of URNs in aps.config.urn. The array is an ordered model set. Element 0 is the primary model, and single-design APIs act on it.
When you change aps.config.urn after the initial load, the onApsModelsChange callback reports the added, removed, and failed URNs.
Core components
| Prop | Type | Purpose | Default |
|---|---|---|---|
aps.enable | boolean | Enable/disable the APS widget | false |
aps.visible | boolean | Show or hide the enabled widget without turning the mode off. When false, the launcher can still open the widget if layout.showLauncher is true. | true |
aps.layout | object | Widget chrome: displayMode, showToolbar, showLauncher, alignment, order, margin | FULLSCREEN, toolbar and launcher shown, LEFT_TOP, order 6 |
aps.config.urn | string | string[] | Design URN, or an ordered set of URNs with element 0 as primary | undefined |
aps.config.accessToken | string | APS token that your application supplies. Its scopes decide which APIs work; see Access token scopes. | undefined |
aps.config.viewableGuid, aps.config.viewableName | string | Viewable to load. viewableGuid takes precedence. If no viewable matches, the viewer loads {3D}. | undefined |
aps.config.bucketKey | string | OSS bucket for model list and upload. Optional if urn is provided. | undefined |
aps.config.sdkVersion | string | Autodesk Viewer SDK version to load from the Autodesk CDN | Loader default |
aps.config.modelOutlineQuality | object | Mesh quality for GIS outline placement | { mode: 'source' } |
aps.config.initial | object | LMV constructor options: extensions, enableDefaultUi | { extensions: [], enableDefaultUi: true } |
aps.camera | object | Camera placement: mode, view, projection, fov, showNavCube | enable: false |
aps.navigation.mode | enum | pan, orbit, zoom, walk, firstPerson | undefined |
aps.rendering.mode | enum | shaded, wireframeOnShaded, hiddenLine, wireframe, glass | shaded |
aps.rendering.glass | object | Used when mode is glass: mode (materials or ghosting) and opacity | { mode: 'materials', opacity: 0.05 } |
aps.rendering.slice | object | Look of sliced elements: mode, opacity | { mode: 'ghosting', opacity: 1 } |
aps.rendering.appearance | object | antialiasing, ambientShadows, groundShadow, groundReflection | All false |
aps.rendering.display | object | lines, points, sectionHatches, units, precision | Lines, points, and hatches shown |
aps.rendering.performance | object | disableShadowEffect, progressiveDisplay, largeModelExperience | Progressive display on |
aps.cuttingPlanes | object | LMV cutting planes: mode named, absolute, or box | enable: false |
aps.selection | object | selectedElementIds, slicedElementIds, hiddenElementIds (LMV dbId integers) | mode: 'lastObject' |
aps.callbacks | object | Ready, models, error, camera, cutting-plane, and selection callbacks. See Callbacks. | — |
aps.debug | object | Diagnostic overlays, such as axisGrid (a grid in model units) and showApsModelOriginLabel. Not intended for production layouts. | axisGrid off |
Note: APS selection IDs are LMV
dbIdintegers. The IafViewer doesn't map Platform element IDs to LMV IDs, so don't reuse View3D ID arrays.
For every nested prop and default, see IafViewer — APS.
Callbacks
| Callback | Signature | When it fires |
|---|---|---|
onApsReady | (payload) => void | After the viewer starts and loads the initial document |
onApsError | ({ phase, operation?, urn?, error }) => void | On token, SDK, document-load, model-sync, or server API failures. phase is accessToken, sdk, documentLoad, modelSync, or api. |
onApsModelsChange | ({ urns, primaryUrn, models, added, removed, failed }) => void | After a later change to aps.config.urn |
onApsCameraChange | { delayInMs: 300, callback({ position, target, up, fov, projection, view? }) } | Once on ready, then debounced on every camera change |
onCuttingPlanesUpdate | (status) => void | After each cutting-plane apply |
onSelectedElementChange | (dbIds: number[]) => void | On canvas selection or prop-driven highlight |
onSlicedElementChange / onHiddenElementChange | (dbIds: number[]) => void | After each selection apply |
onApsCameraChange uses the same payload shape as view3d.onCameraUpdate. Use aps.callbacks.* instead of the legacy top-level aps.onApsReady and aps.onApsCameraChange props.
APS models on Mapbox
You can place APS designs on a Mapbox map alongside models. For more information, see APS models on Mapbox.
Related examples
The IafViewer Examples view includes these APS examples:
| Example | Shows |
|---|---|
IafViewerExApsStandalone | APS viewer with a full aps.* config panel and server API (CRUD) actions |
IafViewerExApsMultiModel | Federated, multi-trade, and URN array model sets, and onApsModelsChange |
IafViewerExGeoBimAps | APS clusters placed on Mapbox with side panes |