This page concerns the Vuforia Engine API version 9.8 and earlier. It has been deprecated and will no longer be actively updated.
Area Targets are created from a 3D scanned digital model of a physical space. Such a model can be obtained by using a 3D depth scanning camera. This guide lists the supported devices and the guides on using the technology to capture a rich and detailed model of your environment. Get started creating engaging AR applications for large environments, rooms, and spaces! The surrounding environment is your target playground!
Supported Devices
- Matterport™ Pro2 Camera
- Leica BLK360
Currently, the Matterport™ Pro2 Camera and the Leica BLK360 is supported for this feature. Follow this guide to set up your Matterport™ account and start scanning your chosen space to get an accurate digital replica of your environment.
Matterport scanning workflow
- Prerequisites:
- If you don't have one, set up a Matterport™ account and purchase scanning equipment.
- Please note that a Professional subscription plan or above is required.
- A purchased Matterpak™ of your scanned space. See Purchasing the MatterPak™ below for details.
- Purchasing the Developer Tools Production Access API. See Retrieving Models with the Matterport™ API Token below for details.
- Preparing the camera and the environment.
- Scanning the environment.
- Uploading the scan to your Matterport cloud for processing.
- Purchasing the MatterPak™ of the model.
- One-time action; request the API token IDs to import the model into the Area Target Generator.
- Create the Area Target.
Setting up an account with Matterport
Go to MyMatterport.com and either enter your credentials, or click the Sign up for free button to create an account. Follow the instructions provided there to complete your Matterport™ profile, filling in all required input fields.
Matterport™ API Tokens
With a Matterport™ account you will gain access to their API and SDK developer tools which are supported with the Vuforia Area Target Generator desktop tool. A Matterport™ API token ID and token secret allows you to retrieve scans that are hosted on your Matterport™ account directly in the Area Target Generator. Admin privileges of the account are necessary to request the token pair. See the below section Retrieving the Matterport™ API Token for instructions on how to request and use the token IDs.
Equipment
In addition to the Matterport™ Pro2 camera, available via https://matterport.com/pro2-3d-camera/, some additional equipment is required for obtaining a successful scan. These include:
- Professional grade tripod
The Pro2 3D Camera weighs 7,5 lbs. (3,4 kg) and rotates 360 degrees while scanning. Therefore, it is necessary to use a high-quality tripod that will not move or shake during the scanning process. It should be height adjustable. We recommend using some heavy-duty stand available from professional vendors.
- Quick-release clamp
We also recommend purchasing an Arca-Swiss compatible quick-release clamp that allows for easy fixation and release of the scanner from the tripod. This speeds-up handling of the Pro2 3D Camera during scanning.
- iPad tablet or iPhone 6s or newer
The Matterport™ Capture App is required to control the Matterport™ camera and is only supported on iOS devices. The app connects to the Matterport™ camera to control and manages the scanning process. It is free to download from the Apple App Store.
NOTE: In some situations, the abovementioned equipment might be acquired through rental or data generated by a full-service provider or an agency.
Preparing the Camera and the Environment
Before heading to the scanning site, it is always good to ensure that the camera and iOS device is fully charged. We also recommend transporting the equipment safely in sturdy cases.
Matterport™ offers the Matterport™ Capture iOS application that allows you to review the model in a dollhouse view as it is being generated. It also offers tools to remove any parts that you do not wish to have in the final mesh. For information on the Matterport™ Capture App, please refer to Area Targets Scanning Guide or Best Practices from Matterport™.
Preparing the Environment
In extension of the general Best Practices for Choosing and Scanning Environments, there are some device-specific recommendations applicable to the Matterport™ scanner.
- Minimize incoming sunlight from windows by closing the curtains or blinds. At the same time ensure enough ambient lighting is provided, by e.g. switching on lamps and lighting, providing a typical lighting scenario.
- Scanning outdoors with the Matterport camera is currently not advised or supported for creating Area Targets because bright sunlight can negatively impact the 3D data from a scan and lead to alignment issues and poor 3D geometry. Sunlight makes it very difficult to create a compact mesh of the scanned area.
- Additionally, Matterport’s ‘360-degree views’ (panorama images) are not supported as they do not contribute to the dollhouse or floorplan view.
Scanning the Environment
Mount the camera with the clamp and turn on the iOS device and the camera. Connect the Matterport™ scanner with the Matterport™ Capture App through the camera’s Wi-Fi that should be visible on the iOS device. Use the create new button to create a new model and the blue circle to start scanning.
The camera will perform a 360-degree rotation to scan its surroundings (make sure you are not in the field-of-view). A preview will gradually appear in the capture app. Use the capture app’s tools (Mirrors, Trim, and Windows) in-between scans, to mark highly reflective facades and outdoor facing windows as it will help reduce alignment errors. For more detailed information on the scanning process, please consult Matterport’s Scan a Space and introduction video.
NOTE: The Mirror tool should be used to mark reflective surfaces such as mirrors, screens and glossy metals. Make sure the arrow in the marking is facing the correct direction as illustrated in the image below
.jpeg)
Uploading the Scan
When the scanned environment is complete, press the upload button in the Matterport™ Capture App menu to upload it to your account for processing. Do not forget to disconnect from the Camera’s WIFI and connect to a different one for the upload process. Due to large file sizes, a stable network is recommended.
NOTE: Once a scan is uploaded to your Matterport™ account, processing can take several hours, depending on the size of the scan. Due to this processing delay, in most cases, you will not be able to generate the Area Target directly at scanning-time. Therefore, we advise you to plan an additional on-site-trip for testing the Area Target.
Purchasing the MatterPak™
Using the uploaded 3D scan, the Matterport™ cloud service generates several derived products automatically. A couple of hours after the upload is finished you will receive a notification from Matterport™. Visit your Matterport™ account and open the specific space.
- Go to the “MatterPak™” section of the space associated with the scan.
- Confirm the purchase using the Buy button. This button will change into a Download button after the purchase process has been finished. Although it is not a requirement, you can download your completed model directly.
Using the token authentication, the Area Target Generator will be connected to your Matterport™ account and retrieves automatically the necessary data for target generation. For additional for MatterPak™, visit the Matterport™ support site on Downloading the MatterPak™ bundle.
NOTE: Mattertags (annotations and snapshots added to the 3D model for presentation) are not included in the Area Targets creation process. Such markup components should be authored in the Unity Editor or coded in your native application.
Retrieving Models with the Matterport™ API Token
You can create an Area Target from a space on your Matterport™ account by connecting it to the Area Target Generator (ATG) through unique Matterport™ API tokens. For more information, please see Matterport™ Integration with PTC Vuforia.
NOTE: The Matterport™ API tokens are part of the API & SDK developer tool licenses and must be purchased in addition to your subscription plan to gain access to the Production Access API. The Sandbox Access API will not work.
- The token ID and the token secret can be requested in my.matterport.com under your Account Settings (Admin only).
- In the Developer Tools section, click the Apply to Purchase.
- Fill out the form with the use case as Integration with PTC/Vuforia.
- After submission you should receive an email from Matterport™ with additional instructions.
- When all prerequisites are confirmed and established the token ID and token secret can be generated under section API Token Management in the Developer Tools section. See also Matterport’s™ guide to Generate API Keys. Depending on your plan different number of API tokens might be available.
.png)
- Copy Paste the generated token-pair to a safe location. They are later used to provide access for the ATG to retrieve your models. You may revoke the access again in your Matterport™ account. After revoking and relaunching the ATG, you will again be requested to enter a valid token pair upon the next target generation attempt.
NOTE: The token secret is only visible right after you pressed confirm. It will not be available after you close the window! You should, therefore, have the ATG opened in order to securely copy the secret into the ATG. If you miss this step, you will need to revoke the token ID and secret and repeat the above steps. Revoking a token ID can be done in the public tokens list embedded into the API Token Management section. For additional support please see Matterport™ API documentation.
Placing token pairs
- Open the ATG and login with your Vuforia Developer credentials.
- Press the New Area Target from Matterport™ Scan. Insert your Token ID and Token Secret and click Apply. You can check the Remember Credentials to skip this step on future Area Target generations.
Complete your Area Target Generation by following the How to Create Area Targets – Creating an Area Target from a Matterport™ scan.