Managing multi-model alignment in APS Viewer

Disclosure: parts of this post were produced with the assistance of AI tools, then reviewed and edited by the author.

Loading more than one model into the APS Viewer and getting them to line up is a common ask — architecture, structure and MEP models coming from different disciplines, or a Revit model paired with an IFC export for coordination. But making them actually sit in the same place turns out to require you to know a lot of things you’d rather not have to think about:

• Do the models share the same origin, or does each one carry its own?
• What’s the globalOffset the Viewer picked for each model, and how do you apply it consistently?
• Was the Revit model published using Shared Coordinates, or project-internal ones?
• If it’s an IFC file, which Coordinate Base was it exported from Revit with — Internal, Survey Point, or Project Base Point?

Get any of these wrong and your models don’t just look slightly off — they can be tens of meters apart, in different orientations, at different scales.

aps-model-alignment is a sample built to make this a non-issue. Instead of reasoning about offsets and coordinate systems ahead of time, you load your models into the Viewer and align them interactively — pick points, rotate, scale — right there in the scene, save the result, and move on.

A note on workflow: this sample is not intended to replace existing coordinate management workflows such as Revit Shared Coordinates or IFC georeferencing. When source models are properly coordinated and the required metadata is available, those approaches remain the preferred solution.

However, in real-world APS integration scenarios, customers may not always have the authority or ability to modify the original RVT or IFC source models. This is especially common when combining models from different teams, organizations, or external partners. In these situations, an interactive alignment workflow can provide an alternative way to inspect, validate, and resolve spatial relationships at the integration or visualization layer without changing the source data.

A note on scope: this sample is primarily a showcase for the ModelAlignmentExtension itself — the interactive picking/aligning experience in the Viewer. The Node.js/Express backend that stores alignment records is a prototype to make the sample runnable end to end; if you adopt this in a real app, you’ll likely want to reimplement that persistence layer in your own preferred backend framework or language.

What the extension does

The sample ships a custom Viewer extension, Autodesk.DeveloperAdvocacySupport.ModelAlignmentExtension, that adds a docking panel with three guided, click-to-pick workflows for aligning a selected model against another model already in the scene:

• Move — pick a “from” point on the model and a “to” point elsewhere in the scene, then translate the model by the vector between them.
• Rotate — pick two points that define a current direction on the model (the first point doubles as the pivot), then two more points that define the target direction. The model rotates around that pivot to match.
• Scale — pick two points that define a known distance on the model (A → B, with A staying fixed as the pivot), then two more points anywhere in the scene defining the target distance (C → D). A live preview box tracks the target as you move toward D, so you can see where the model lands at the resulting scale factor (|CD| / |AB|) before committing.