Skip to main content
Version: v5.3

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:

  1. Set aps.enable to true.
  2. Pass one or more design URNs in aps.config.urn.
  3. Set aps.config.accessToken to your APS viewer token.
  4. Optional: To list or upload models, set aps.config.bucketKey. You don't need it when you pass a URN.
  5. Add an aps.callbacks.onApsReady callback 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.

ScopeWhat it enables
viewables:readLoading and viewing designs (aps.config.urn), and the viewer-side helpers in payload.apis.client
data:readServer 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:readfetchBucketsList
data:write and data:createuploadModelFile, 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​

PropTypePurposeDefault
aps.enablebooleanEnable/disable the APS widgetfalse
aps.visiblebooleanShow 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.layoutobjectWidget chrome: displayMode, showToolbar, showLauncher, alignment, order, marginFULLSCREEN, toolbar and launcher shown, LEFT_TOP, order 6
aps.config.urnstring | string[]Design URN, or an ordered set of URNs with element 0 as primaryundefined
aps.config.accessTokenstringAPS token that your application supplies. Its scopes decide which APIs work; see Access token scopes.undefined
aps.config.viewableGuid, aps.config.viewableNamestringViewable to load. viewableGuid takes precedence. If no viewable matches, the viewer loads {3D}.undefined
aps.config.bucketKeystringOSS bucket for model list and upload. Optional if urn is provided.undefined
aps.config.sdkVersionstringAutodesk Viewer SDK version to load from the Autodesk CDNLoader default
aps.config.modelOutlineQualityobjectMesh quality for GIS outline placement{ mode: 'source' }
aps.config.initialobjectLMV constructor options: extensions, enableDefaultUi{ extensions: [], enableDefaultUi: true }
aps.cameraobjectCamera placement: mode, view, projection, fov, showNavCubeenable: false
aps.navigation.modeenumpan, orbit, zoom, walk, firstPersonundefined
aps.rendering.modeenumshaded, wireframeOnShaded, hiddenLine, wireframe, glassshaded
aps.rendering.glassobjectUsed when mode is glass: mode (materials or ghosting) and opacity{ mode: 'materials', opacity: 0.05 }
aps.rendering.sliceobjectLook of sliced elements: mode, opacity{ mode: 'ghosting', opacity: 1 }
aps.rendering.appearanceobjectantialiasing, ambientShadows, groundShadow, groundReflectionAll false
aps.rendering.displayobjectlines, points, sectionHatches, units, precisionLines, points, and hatches shown
aps.rendering.performanceobjectdisableShadowEffect, progressiveDisplay, largeModelExperienceProgressive display on
aps.cuttingPlanesobjectLMV cutting planes: mode named, absolute, or boxenable: false
aps.selectionobjectselectedElementIds, slicedElementIds, hiddenElementIds (LMV dbId integers)mode: 'lastObject'
aps.callbacksobjectReady, models, error, camera, cutting-plane, and selection callbacks. See Callbacks.—
aps.debugobjectDiagnostic overlays, such as axisGrid (a grid in model units) and showApsModelOriginLabel. Not intended for production layouts.axisGrid off

Note: APS selection IDs are LMV dbId integers. 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​

CallbackSignatureWhen it fires
onApsReady(payload) => voidAfter the viewer starts and loads the initial document
onApsError({ phase, operation?, urn?, error }) => voidOn 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 }) => voidAfter 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) => voidAfter each cutting-plane apply
onSelectedElementChange(dbIds: number[]) => voidOn canvas selection or prop-driven highlight
onSlicedElementChange / onHiddenElementChange(dbIds: number[]) => voidAfter 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.

The IafViewer Examples view includes these APS examples:

ExampleShows
IafViewerExApsStandaloneAPS viewer with a full aps.* config panel and server API (CRUD) actions
IafViewerExApsMultiModelFederated, multi-trade, and URN array model sets, and onApsModelsChange
IafViewerExGeoBimApsAPS clusters placed on Mapbox with side panes