| title | description | author | manager | services | ms.author | ms.date | ms.topic | ms.service |
|---|---|---|---|---|---|---|---|---|
Create & locate anchors in C++/NDK |
In-depth explanation of how to create and locate anchors using Azure Spatial Anchors in C++/NDK. |
pamistel |
MehranAzimi-msft |
azure-spatial-anchors |
pamistel |
11/20/2020 |
tutorial |
azure-spatial-anchors |
[!div class="op_single_selector"]
Azure Spatial Anchors allow you to share anchors in the world between different devices. It supports several different development environments. In this article, we'll dive into how to use the Azure Spatial Anchors SDK, in C++/NDK, to:
- Correctly set up and manage an Azure Spatial Anchors session.
- Create and set properties on local anchors.
- Upload them to the cloud.
- Locate and delete cloud spatial anchors.
To complete this guide, make sure you have:
- Read through the Azure Spatial Anchors overview.
- Completed one of the 5-minute Quickstarts.
- Basic knowledge on C++ and the Android Native Development Kit.
- Basic knowledge on ARCore.
[!INCLUDE Start]
Learn more about the CloudSpatialAnchorSession struct.
std::shared_ptr<CloudSpatialAnchorSession> cloudSession_;
// In your view handler
cloudSession_ = std::make_shared<CloudSpatialAnchorSession>();[!INCLUDE Account Keys]
Learn more about the SessionConfiguration struct.
auto configuration = cloudSession_->Configuration();
configuration->AccountKey(R"(MyAccountKey)");[!INCLUDE Access Tokens]
auto configuration = cloudSession_->Configuration();
configuration->AccessToken(R"(MyAccessToken)");[!INCLUDE Access Tokens Event]
Learn more about the TokenRequiredDelegate delegate.
auto accessTokenRequiredToken = cloudSession_->TokenRequired([](auto&&, auto&& args) {
args->AccessToken(R"(MyAccessToken)");
});[!INCLUDE Asynchronous Tokens]
auto accessTokenRequiredToken = cloudSession_->TokenRequired([this](auto&&, auto&& args) {
std::shared_ptr<CloudSpatialAnchorSessionDeferral> deferral = args->GetDeferral();
MyGetTokenAsync([&deferral, &args](std::string const& myToken) {
if (myToken != nullptr) args->AccessToken(myToken);
deferral->Complete();
});
});[!INCLUDE Azure AD Tokens]
auto configuration = cloudSession_->Configuration();
configuration->AuthenticationToken(R"(MyAuthenticationToken)");[!INCLUDE Azure AD Tokens Event]
auto accessTokenRequiredToken = cloudSession_->AccessTokenRequired([](auto&&, auto&& args) {
args->AuthenticationToken(R"(MyAuthenticationToken)");
});[!INCLUDE Asynchronous Tokens]
auto accessTokenRequiredToken = cloudSession_->TokenRequired([this](auto&&, auto&& args) {
std::shared_ptr<CloudSpatialAnchorSessionDeferral> deferral = args->GetDeferral();
MyGetTokenAsync([&deferral, &args](std::string const& myToken) {
if (myToken != nullptr) args->AuthenticationToken(myToken);
deferral->Complete();
});
});[!INCLUDE Setup]
Learn more about the Start method.
cloudSession_->Session(ar_session_);
cloudSession_->Start();[!INCLUDE Frames]
Learn more about the ProcessFrame method.
cloudSession_->ProcessFrame(ar_frame_);[!INCLUDE Feedback]
Learn more about the SessionUpdatedDelegate delegate.
auto sessionUpdatedToken = cloudSession_->SessionUpdated([this](auto&&, auto&& args) {
auto status = args->Status();
if (status->UserFeedback() == SessionUserFeedback::None) return;
std::ostringstream str;
str << std::fixed << std::setw(2) << std::setprecision(0)
<< R"(Feedback: )" << FeedbackToString(status.UserFeedback()) << R"( -)"
<< R"( Recommend Create=)" << (status->RecommendedForCreateProgress() * 100) << R"(%)";
feedback_ = str.str();
});[!INCLUDE Creating]
Learn more about the CloudSpatialAnchor struct.
// Create a local anchor, perhaps by hit-testing and creating an ARAnchor
ArAnchor* localAnchor;
ArHitResultList* hit_result_list = nullptr;
ArHitResultList_create(ar_session_, &hit_result_list);
CHECK(hit_result_list);
ArFrame_hitTest(ar_session_, ar_frame_, 0.5, 0.5, hit_result_list);
int32_t hit_result_list_size = 0;
ArHitResultList_getSize(ar_session_, hit_result_list, &hit_result_list_size);
if (hit_result_list_size == 0) {
ArHitResultList_destroy(hit_result_list);
return;
}
ArHitResult* ar_hit = nullptr;
ArHitResult_create(ar_session_, &ar_hit);
// The hitTest method sorts the resulting list by increasing distance from the camera
// The first hit result will usually be the most relevant when responding to user input
ArHitResultList_getItem(ar_session_, hit_result_list, 0, ar_hit);
if (ArHitResult_acquireNewAnchor(ar_session_, ar_hit, &localAnchor) != AR_SUCCESS) return;
ArTrackingState tracking_state = AR_TRACKING_STATE_STOPPED;
ArAnchor_getTrackingState(ar_session_, localAnchor, &tracking_state);
if (tracking_state != AR_TRACKING_STATE_TRACKING) {
ArAnchor_release(localAnchor);
ArHitResult_destroy(ar_hit);
return;
}
ArHitResult_destroy(ar_hit);
ar_hit = nullptr;
ArHitResultList_destroy(hit_result_list);
hit_result_list = nullptr;
// If the user is placing some application content in their environment,
// you might show content at this anchor for a while, then save when
// the user confirms placement.
std::shared_ptr<CloudSpatialAnchor> cloudAnchor = std::make_shared<CloudSpatialAnchor>();
cloudAnchor->LocalAnchor(localAnchor);
cloudSession_->CreateAnchorAsync(cloudAnchor, [this, cloudAnchor](Status status) {
std::ostringstream str;
if (status != Status::OK) {
str << "Save Failed: " << std::to_string(static_cast<uint32_t>(status));
feedback_ = str.str();
return;
}
str << R"(Created a cloud anchor with ID=)" << cloudAnchor->Identifier();
feedback_ = str.str();
});[!INCLUDE Session Status]
Learn more about the GetSessionStatusAsync method.
cloudSession_->GetSessionStatusAsync([this](Status status, const std::shared_ptr<SessionStatus>& value) {
if (status != Status::OK) {
std::ostringstream str;
str << "Session status error: " << std::to_string(static_cast<uint32_t>(status));
feedback_ = str.str();
return;
}
if (value->RecommendedForCreateProgress() < 1.0f) return;
// Issue the creation request ...
});[!INCLUDE Setting Properties]
Learn more about the AppProperties method.
std::shared_ptr<CloudSpatialAnchor> cloudAnchor = std::make_shared<CloudSpatialAnchor>();
cloudAnchor->LocalAnchor(localAnchor);
auto properties = cloudAnchor->AppProperties();
properties->Insert(R"(model-type)", R"(frame)");
properties->Insert(R"(label)", R"(my latest picture)");
cloudSession_->CreateAnchorAsync(cloudAnchor, [this, cloudAnchor](Status status) {
// ...
});[!INCLUDE Update Anchor Properties]
Learn more about the UpdateAnchorPropertiesAsync method.
std::shared_ptr<CloudSpatialAnchor> anchor = /* locate your anchor */;
auto properties = anchor->AppProperties();
properties->Insert(R"(last-user-access)", R"(just now)");
cloudSession_->UpdateAnchorPropertiesAsync(anchor, [this](Status status) {
if (status != Status::OK) {
std::ostringstream str;
str << "Updating Properties Failed: " << std::to_string(static_cast<uint32_t>(status));
feedback_ = str.str();
}
});[!INCLUDE Getting Properties]
Learn more about the GetAnchorPropertiesAsync method.
cloudSession_->GetAnchorPropertiesAsync(R"(anchorId)", [this](Status status, const std::shared_ptr<CloudSpatialAnchor>& anchor) {
if (status != Status::OK) {
std::ostringstream str;
str << "Getting Properties Failed: " << std::to_string(static_cast<uint32_t>(status));
feedback_ = str.str();
return;
}
if (anchor != nullptr) {
auto properties = anchor->AppProperties();
properties->Lookup(R"(last-user-access)") = R"(just now)";
cloudSession_->UpdateAnchorPropertiesAsync(anchor, [this](Status status) {
// ...
});
}
});[!INCLUDE Expiration]
Learn more about the Expiration method.
std::chrono::system_clock::time_point now = std::chrono::system_clock::now();
std::chrono::system_clock::time_point oneWeekFromNow = now + std::chrono::hours(7 * 24);
const int64_t oneWeekFromNowUnixEpochTimeMs = std::chrono::duration_cast<std::chrono::milliseconds>(oneWeekFromNow.time_since_epoch()).count();
cloudAnchor->Expiration(oneWeekFromNowUnixEpochTimeMs);[!INCLUDE Locate]
Learn more about the CreateWatcher method.
auto criteria = std::make_shared<AnchorLocateCriteria>();
criteria->Identifiers({ R"(id1)", R"(id2)", R"(id3)" });
auto cloudSpatialAnchorWatcher = cloudSession_->CreateWatcher(criteria);[!INCLUDE Locate Events]
Learn more about the AnchorLocated delegate.
auto anchorLocatedToken = cloudSession_->AnchorLocated([this](auto&&, auto&& args) {
switch (args->Status()) {
case LocateAnchorStatus::Located: {
std::shared_ptr<CloudSpatialAnchor> foundAnchor = args->Anchor();
// Go add your anchor to the scene...
}
break;
case LocateAnchorStatus::AlreadyTracked:
// This anchor has already been reported and is being tracked
break;
case LocateAnchorStatus::NotLocatedAnchorDoesNotExist:
// The anchor was deleted or never existed in the first place
// Drop it, or show UI to ask user to anchor the content anew
break;
case LocateAnchorStatus::NotLocated:
// The anchor hasn't been found given the location data
// The user might in the wrong location, or maybe more data will help
// Show UI to tell user to keep looking around
break;
}
});[!INCLUDE Deleting]
Learn more about the DeleteAnchorAsync method.
cloudSession_->DeleteAnchorAsync(cloudAnchor, [this](Status status) {
// Perform any processing you may want when delete finishes
});[!INCLUDE Stopping]
Learn more about the Stop method.
cloudSession_->Stop();[!INCLUDE Resetting]
Learn more about the Reset method.
cloudSession_->Reset();[!INCLUDE Cleanup]
cloudSession_ = nullptr;[!INCLUDE Next Steps]