This page concerns the Vuforia Engine API version 9.8 and earlier. It has been deprecated and will no longer be actively updated.
The Ground Plane is tracking the environment by using HitTest to detect surfaces that are then tracked by the SmartTerrain tracker. The Vuforia SmartTerrain API is used in conjunction with Device Tracking and the PositionalDeviceTracker.
Class Definitions
Main classes
- SmartTerrain – is responsible for finding and tracking Surfaces and executing hit tests in the World Coordinate Space.
- PositionalDeviceTracker - maintains position and orientation in world space for the device and Anchors.
- Anchor - a 6 DoF trackable point in space that is tracked by the PositionalDeviceTracker. Anchor points are persistent locations in the world space that are continually tracked as the world space grows and changes in a Ground Plane session.
TIP: Use an Anchor when you want your content to be positioned as accurately as possible at a specific location in the world. Use the tracking status to create continuous AR experiences. See Interpreting Tracking State API Results for more information.
SmartTerrain
SmartTerrain is used to collect information about the environment. The information can be used to identify surfaces with the hitTest functions. SmartTerrain can only run successfully in conjunction with Vuforia Fusion and after the initialization of the PositionalDeviceTracker.
HitTest
HitTest is performed to identify suitable surfaces. It sends a ray to a plane and calculates the relative deviceHeight to a plane. The HitTest behavior depends on the active Fusion Provider given by Vuforia::getActiveFusionProvider(). See also the Ground Plane page for more information on the different hit test UX modes.
hitTest (Vec2F point, HITTEST_HINT hint, State state, float deviceHeight)
The HitTest cannot be performed before or during initialization of the PositionalDeviceTracker.
NOTE: Hit testing should use the same State as the frame rendering for the hitTestResults to be accurate.
PositionalDeviceTracker
Please refer to Using the Device Tracker in Native for an introduction to the PositionalDeviceTracker
The PositionalDeviceTracker delivers the Anchors used to position content in the environment.
Its initialization steps depend on the Vuforia Fusion Provide you are using.
Anchors
An Anchor is a trackable representing a point in space with fixed position and orientation. An Anchor is used to position virtual content in the physical space. The Anchor is controlled and managed by the PositionalDeviceTracker.
Create an anchor using
createAnchor (const char *name, const HitTestResult &hitTestResult)
Destroy anchors
destroyAnchor (Anchor * anchor)
NOTE: Calling reset() invalidates all created Anchors.
App Workflow
The high-level control flow of a Ground Plane App consists of the following steps:
- Initialize Vuforia Engine AR
- Start the AR Session
- Initialize and configure the Trackers required for Ground Plane (PositionalDeviceTracker and SmartTerrain)
- Create an Anchor in real-world space (either based on hit test or relative to camera)
- Place your content in the anchor
- For Every Frame:
- Adjust the rendering camera position based on the DeviceTrackable Pose
- Adjust the transform of the content based on an updated Anchor position
- Use the DeviceTracker states to recover from interrupted sessions. See Best Practices for Continued AR Experiences for more information.
- Deinitialize the Trackers (PositionalDeviceTracker and SmartTerrain)
- Deinitialize Vuforia Engine AR
- For more details on the control flow of a Ground Plane app, please refer to the Ground Plane Native User Guide.