ATLAS for Unreal: User Guide

Open source. The source code, build instructions and release notes are in the Bitbucket repository:
bitbucket.org/enablemyteam/atlas_for_unreal

ATLAS for Unreal (the EMT ATLAS Viewer) is a desktop app for exploring your ATLAS 3D models in their real-world setting. It places your models on a map, lets you fly around them, and shows an element's ATLAS details when you click it.

What it does

Opens ATLAS models directly. Pick a project, tick a model, and it streams in. Several models can be open at once and line up with each other.
Shows them on a real map. Models sit on OpenStreetMap with terrain, or on Google's photorealistic 3D view of the area.
Loads nearby models for you. As you fly along a site, models close to your view open automatically, and close again when you move away.
Shows element details. Click any element to highlight all of its pieces and see its ATLAS properties.
Lights the scene realistically. A sun and sky at the right position for the site's location and the time of day.

Before you start

You need	Details
A computer	A Mac with Apple Silicon (M1 or later). A Windows version is planned but not available yet.
An internet connection	The app streams models and map imagery as you move.
An ATLAS account	Your ATLAS domain (for example `your-company.enablemyteam.com`), your username and your password.
Optional: a Google Maps key	Only if you want Google's photorealistic 3D view. Google bills the key's owner.
Optional: a Cesium ion token	Only if you want Cesium World Terrain for more accurate ground heights.

You do not need Unreal Engine installed to use the app.

Install and open the app

Download and unzip EMT-ATLAS-Viewer-mac-arm64.zip.
Drag EMT ATLAS Viewer into your Applications folder, or run it from where you unzipped it.
The first time you open it on a Mac, macOS may say the app can't be checked for malicious software. Right-click the app, choose Open, then click Open. You only need to do this once.

If you'd rather use Terminal: xattr -dr com.apple.quarantine "EMT ATLAS Viewer.app"

The app opens in a normal window sized to fit your screen.

Sign in and choose a project

On the sign-in page, enter your ATLAS domain, username and password, then select Sign in.
The app lists the projects your account can use. Select one.
The model list opens on the left.

Good to know:

You stay signed in for 24 hours, even if you close and reopen the app. After that, or if ATLAS says your session has ended, the sign-in page comes back with a short message.
To change project, select Switch project at the top of the model list. To sign out, select Sign out.
If you see "You do not have access to that project", pick another project or ask your ATLAS administrator.

Open models

The panel on the left lists every model in the project, newest first. Use the search box to filter by file name or revision number.

Tick a model to open it. It shows loading... and then loaded.
Untick it to close it.
A model marked processing is still being prepared by ATLAS. Try again later.
Tab hides and shows the panel.

The first model you open decides where the scene sits, and the camera flies to it. Every model you open after that lines up with it. If you close all models, the next one you open can be somewhere else in the world.

Automatic loading

Once your first model is open, the app opens other models for you as you fly around:

A model opens when it is within 500 m of what the camera can see (the view reaches about 2 km ahead).
A model closes only once it is more than 750 m away, so models at the edge don't flicker open and shut.
Models you tick yourself are never closed automatically. If you untick an automatically opened model, it stays closed until you have moved well away from it.
The app opens up to 30 models this way, a couple at a time, nearest first.
Automatic loading needs a location for each model. A few models have none; open those yourself.

Turn this on or off with the Auto: on / Auto: off button at the top of the model list.

Move around

Control	What it does
W A S D	Move forward, left, back, right
Q / E	Move down / up
Hold the right mouse button and move the mouse	Look around
Mouse wheel	Change your speed (hold Shift for a boost)
Left click	Select an element
Esc	Clear the selection
Tab	Show or hide the model list
M	Show or hide the map
Page Up / Page Down	Move the map up or down (hold Shift for 10 m steps)
T	Make the ground more or less see-through (Google view)
L	Turn lighting on or off
, and .	Move the time of day earlier or later (hold Shift for 3-hour steps)

Tip: if the camera is too fast or slow, scroll the mouse wheel.

Click an element to see its details

Left-click any part of a model.
Every piece of that element lights up yellow, even pieces in other tiles. The panel at the top right says how many pieces and tiles are highlighted.
The panel shows the element's data from the model, plus its ATLAS attributes. These can take a few seconds to arrive the first time.
Press Esc to clear the selection.

If an element has no tag in the model, only the piece you clicked is highlighted.

Change the map

Select Map at the top of the model list, choose an option, then select Apply. If you change nothing, you get the free default.

Option	What you need	What it's like
OpenStreetMap + free terrain (default)	Nothing	Street map on terrain of about 30 m detail. Free, but the public OpenStreetMap server is meant for light use.
Cesium World Terrain	A Cesium ion token	The same street map on much more accurate ground (1-2 m in England).
Google Photorealistic 3D Tiles	A Google Maps Platform key with the Map Tiles API enabled	A photographic 3D view of the area, including buildings and trees.

Notes:

Your keys are optional and yours. The app never uses a paid service unless you pick it and enter your own key. Usage is billed to the owner of that key.
Google's 3D ground is solid, so it can hide underground parts of a model. Press T to make the ground see-through.
If a key is missing or wrong, the app tells you and falls back to the free map.
M hides the map entirely, which is useful if it gets in the way of a model that sits below ground.
The map shows the required credit line along the bottom of the window. Please leave it in place if you share screenshots.

Lighting and time of day

The scene has a sun, sky and clouds placed for the real location of your model.

Press L to switch lighting off and see flat, plain colours.
Press , and . to change the time of day. By default the scene shows the current time at the site, or 11:00 if it is dark there.
Common materials (concrete, asphalt, steel, soil, wood, gravel, brick) get a surface texture so large areas don't look flat. Other surfaces keep the colour from the model.

Troubleshooting

Problem	What to try
The sign-in fails	Check the domain is your company's ATLAS address (for example `your-company.enablemyteam.com`), then re-check your username and password.
"Session expired" or the sign-in page comes back	Your 24-hour session ended. Sign in again.
The list is empty or a project can't be opened	You may not have access to that project. Use Switch project, or ask your administrator.
A model says "processing"	ATLAS is still preparing it. Wait, then select Refresh at the top of the list.
Nothing appears after ticking a model	Wait for "loaded". Large models stream in pieces and need a moment. Check your internet connection.
The model is below the ground	In Google view press T. You can also hide the map with M, or move it with Page Up / Page Down.
The map is flat or blank	You need an internet connection. Check you haven't hidden the map with M.
A key was rejected	Open Map, re-enter the key and select Apply. The app reports the problem and falls back to the free map.
Clicks land in the wrong place	The app sizes its window to fit the screen. Don't enlarge it to full screen; keep the normal window.
The app is slow	Close models you don't need (or turn Auto off), and close other heavy apps. Many large models open at once use a lot of memory.
macOS won't open the app	Right-click the app, choose Open, then Open (first time only).

Still stuck? See Getting help.

Frequently asked questions

Do I need Unreal Engine?
No. The app is self-contained.

Does it work on Windows?
Not yet. A Windows version is prepared but hasn't been built or tested.

Does it change my models or data in ATLAS?
No. The app only reads from ATLAS. It never edits or uploads anything.

Can I open more than one model?
Yes. Models open together and line up on one shared map.

Why do some models not open automatically?
Automatic loading needs a location for each model, and a few don't have one. Tick those yourself.

Does using Google or Cesium cost money?
Only if you choose them and enter your own key. The free OpenStreetMap option costs nothing.

Can I change the map credit or remove it?
No. Map and imagery providers require their credit to be shown.

Privacy and security

Your password is never stored. The app uses it once to sign in.
A sign-in token (valid for 24 hours), your domain, username and last project are saved on your computer so you don't have to sign in again straight away. They are stored in plain text in the app's own settings folder, so protect your computer account as you normally would.
Map keys you enter are saved the same way, on your computer only. They are sent only to the service they belong to (Google or Cesium).
Select Sign out to forget the saved sign-in.
The ATLAS token is only sent to ATLAS, never to the storage links that deliver model files.

Getting help

Questions or problems: contact your ATLAS administrator or Enable My Team support, and include your macOS version and what you were doing when it happened.
Source code, build instructions and issues: bitbucket.org/enablemyteam/atlas_for_unreal
Developers: the repository README explains how to build the app and how to add the viewer to an existing Unreal Engine 5.4 project.

ATLAS for Unreal is built on Unreal Engine 5.4 and the open-source cesium-native library. Map data: OpenStreetMap contributors, AWS Terrain Tiles, and, if you choose them, Cesium and Google. See the repository's NOTICE file for the full list of licences.