C++/WinRT'de Azure Spatial Anchors kullanarak yer işaretleri oluşturma ve bulma
Azure Spatial Anchors, dünyadaki yer işaretleri farklı cihazlar arasında paylaşmanızı sağlar. Çeşitli geliştirme ortamlarını destekler. Bu makalede, C++/WinRT'de Azure Spatial Anchors SDK'sını kullanarak şunları yapacağız:
- Azure Spatial Anchors oturumlarını doğru şekilde ayarlayın ve yönetin.
- Yerel tutturucularda özellikleri oluşturun ve ayarlayın.
- Bunları buluta yükleyin.
- Bulut uzamsal tutturucularını bulun ve silin.
Önkoşullar
Bu kılavuzu tamamlamak için aşağıdakilere sahip olduğunuzdan emin olun:
- Azure Spatial Anchors'a genel bakış adımlarını okuyun.
- 5 dakikalık Hızlı Başlangıçlardan birini tamamladınız.
- C++ ve Windows Çalışma Zamanı API'leri hakkında temel bilgiler.
Oturumu başlatma
SDK'nın ana giriş noktası, oturumunuzu temsil eden sınıftır. Genellikle sınıfında görünümünüzü ve yerel AR oturumunuzu yöneten bir alan bildirirsiniz.
CloudSpatialAnchorSession sınıfı hakkında daha fazla bilgi edinin.
CloudSpatialAnchorSession m_cloudSession{ nullptr };
m_cloudSession = CloudSpatialAnchorSession();
Kimlik doğrulaması kurulumu
Hizmete erişmek için bir hesap anahtarı, erişim belirteci veya Microsoft Entra kimlik doğrulama belirteci sağlamanız gerekir. Bu konu hakkında daha fazla bilgiyi Kimlik doğrulaması kavramı sayfasından da okuyabilirsiniz.
Hesap Anahtarları
Hesap Anahtarları, uygulamanızın Azure Spatial Anchors hizmetiyle kimlik doğrulaması yapmasına olanak tanıyan bir kimlik bilgisidir. Hesap Anahtarları'nın amaçlanan amacı, hızlı bir şekilde başlamanıza yardımcı olmaktır. Özellikle uygulamanızın Azure Spatial Anchors ile tümleştirmesinin geliştirme aşamasında. Bu nedenle, geliştirme sırasında bunları istemci uygulamalarınıza ekleyerek Hesap Anahtarlarını kullanabilirsiniz. Geliştirmenin ötesine geçerken, üretim düzeyinde, Erişim Belirteçleri veya Microsoft Entra kullanıcı kimlik doğrulaması tarafından desteklenen bir kimlik doğrulama mekanizmasına geçmeniz kesinlikle önerilir. Geliştirme için Hesap Anahtarı almak için Azure Spatial Anchors hesabınızı ziyaret edin ve "Anahtarlar" sekmesine gidin.
SessionConfiguration sınıfı hakkında daha fazla bilgi edinin.
auto configuration = m_cloudSession.Configuration();
configuration.AccountKey(LR"(MyAccountKey)");
Erişim Belirteçleri
Erişim Belirteçleri, Azure Spatial Anchors ile kimlik doğrulaması yapmak için daha sağlam bir yöntemdir. Özellikle de uygulamanızı üretim dağıtımına hazırlarken. Bu yaklaşımın özeti, istemci uygulamanızın güvenli bir şekilde kimlik doğrulaması yapabileceğiniz bir arka uç hizmeti ayarlamaktır. Arka uç hizmetiniz, erişim belirteci istemek için çalışma zamanında AAD ve Azure Spatial Anchors Güvenli Belirteç Hizmeti ile arabirim oluşturur. Bu belirteç daha sonra istemci uygulamasına teslim edilir ve AZURE Spatial Anchors ile kimlik doğrulaması yapmak için SDK'da kullanılır.
auto configuration = m_cloudSession.Configuration();
configuration.AccessToken(LR"(MyAccessToken)");
Erişim belirteci ayarlanmadıysa, olayı işlemeniz TokenRequired veya temsilci protokolünde tokenRequired yöntemini uygulamanız gerekir.
Olay bağımsız değişkenlerinde özelliğini ayarlayarak olayı zaman uyumlu olarak işleyebilirsiniz.
TokenRequiredDelegate temsilcisi hakkında daha fazla bilgi edinin.
m_accessTokenRequiredToken = m_cloudSession.TokenRequired(winrt::auto_revoke, [](auto&&, auto&& args) {
args.AccessToken(LR"(MyAccessToken)");
});
İşleyicinizde zaman uyumsuz çalışma yürütmeniz gerekiyorsa, aşağıdaki örnekte olduğu gibi bir deferral nesne isteyerek ve sonra tamamlayarak belirteci ayarlamayı erteleyebilirsiniz.
m_accessTokenRequiredToken = m_cloudSession.TokenRequired(winrt::auto_revoke, [this](auto&&, auto&& args) {
auto deferral = args.GetDeferral();
MyGetTokenAsync([&deferral, &args](winrt::hstring const& myToken) {
if (!myToken.empty()) args.AccessToken(myToken);
deferral.Complete();
});
});
Microsoft Entra doğrulaması
Azure Spatial Anchors, uygulamaların kullanıcı Microsoft Entra ID (Active Directory) belirteçleriyle kimlik doğrulaması yapmasına da olanak tanır. Örneğin, Azure Spatial Anchors ile tümleştirmek için Microsoft Entra belirteçlerini kullanabilirsiniz. Bir Kuruluş Kullanıcıları Microsoft Entra Kimliği'nde barındırıyorsa, Azure Spatial Anchors SDK'sında bir kullanıcıya Microsoft Entra belirteci sağlayabilirsiniz. Bunun yapılması, aynı Microsoft Entra kiracısının parçası olan bir hesap için doğrudan Azure Spatial Anchors hizmetinde kimlik doğrulaması yapmanıza olanak tanır.
auto configuration = m_cloudSession.Configuration();
configuration.AuthenticationToken(LR"(MyAuthenticationToken)");
Erişim belirteçlerinde olduğu gibi, bir Microsoft Entra belirteci ayarlanmamışsa TokenRequired olayını işlemeniz veya temsilci protokolünde tokenRequired yöntemini uygulamanız gerekir.
Olay bağımsız değişkenlerinde özelliğini ayarlayarak olayı zaman uyumlu olarak işleyebilirsiniz.
m_accessTokenRequiredToken = m_cloudSession.TokenRequired(winrt::auto_revoke, [](auto&&, auto&& args) {
args.AuthenticationToken(LR"(MyAuthenticationToken)");
});
İşleyicinizde zaman uyumsuz çalışma yürütmeniz gerekiyorsa, aşağıdaki örnekte olduğu gibi bir deferral nesne isteyerek ve sonra tamamlayarak belirteci ayarlamayı erteleyebilirsiniz.
m_accessTokenRequiredToken = m_cloudSession.TokenRequired(winrt::auto_revoke, [this](auto&&, auto&& args) {
auto deferral = args.GetDeferral();
MyGetTokenAsync([&deferral, &args](winrt::hstring const& myToken) {
if (!myToken.empty()) args.AuthenticationToken(myToken);
deferral.Complete();
});
});
Oturumu ayarlama
Oturumunuzun ortam verilerini işlemesini sağlamak için çağır.Start()
Oturumunuz tarafından tetiklenen olayları işlemek için bir olay işleyicisi ekleyin.
Start yöntemi hakkında daha fazla bilgi edinin.
m_cloudSession.Start();
Oturuma çerçeveler sağlama
Uzamsal yer işareti oturumu, kullanıcının etrafındaki alanı eşleyerek çalışır. Bunun yapılması, tutturucuların nerede bulunduğunu belirlemeye yardımcı olur. Mobil platformlar (iOS ve Android), platformunuzun AR kitaplığından kareler almak için kamera akışına yerel bir çağrı gerektirir. Buna karşılık HoloLens sürekli olarak ortamı taradığından mobil platformlarda olduğu gibi belirli bir aramaya gerek yoktur.
ProcessFrame yöntemi hakkında daha fazla bilgi edinin.
m_cloudSession->ProcessFrame(ar_frame_);
Kullanıcıya geri bildirim sağlayın
Oturum güncelleştirilmiş olayını işlemek için kod yazabilirsiniz. Bu olay, oturum çevrenizin anlaşılmasını her geliştirdiğinde tetikler. Bunu yaptığınızda şunları yapmanıza olanak tanır:
UserFeedbackCihaz hareket ettikçe ve oturum ortam anlayışını güncelleştirdikçe kullanıcıya geri bildirim sağlamak için sınıfını kullanın. Bunu yapmak için- Hangi noktada uzamsal yer işaretleri oluşturmak için yeterli izlenen uzamsal veri olduğunu belirleyin. Bunu veya
RecommendedForCreateProgressileReadyForCreateProgressbelirlersiniz.ReadyForCreateProgress1'in üzerinde olduğunda, bulut uzamsal sabit noktasını kaydetmek için yeterli verimiz vardır, ancak bunu yapmak için 1'in üzerine gelene kadarRecommendedForCreateProgressbeklemenizi öneririz.
SessionUpdatedDelegate temsilcisi hakkında daha fazla bilgi edinin.
m_sessionUpdatedToken = m_cloudSession.SessionUpdated(winrt::auto_revoke, [this](auto&&, auto&& args)
{
auto status = args.Status();
if (status.UserFeedback() == SessionUserFeedback::None) return;
m_feedback = LR"(Feedback: )" + FeedbackToString(status.UserFeedback()) + LR"( -)" +
LR"( Recommend Create=)" + FormatPercent(status.RecommendedForCreateProgress() * 100.f);
});
Bulut uzamsal yer işareti oluşturma
Bulut uzamsal yer işareti oluşturmak için önce platformunuzun AR sisteminde bir yer işareti oluşturursunuz ve ardından bir bulut karşılık gelenini oluşturursunuz. yöntemini kullanırsınız CreateAnchorAsync() .
CloudSpatialAnchor sınıfı hakkında daha fazla bilgi edinin.
// Initialization
SpatialStationaryFrameOfReference m_stationaryReferenceFrame = nullptr;
HolographicDisplay defaultHolographicDisplay = HolographicDisplay::GetDefault();
SpatialLocator spatialLocator = defaultHolographicDisplay.SpatialLocator();
m_stationaryReferenceFrame = spatialLocator.CreateStationaryFrameOfReferenceAtCurrentLocation();
// Create a local anchor, perhaps by positioning a SpatialAnchor a few meters in front of the user
SpatialAnchor localAnchor{ nullptr };
PerceptionTimestamp timestamp = PerceptionTimestampHelper::FromHistoricalTargetTime(DateTime::clock::now());
SpatialCoordinateSystem currentCoordinateSystem = m_attachedReferenceFrame.GetStationaryCoordinateSystemAtTimestamp(timestamp);
SpatialPointerPose pose = SpatialPointerPose::TryGetAtTimestamp(currentCoordinateSystem, timestamp);
// Get the gaze direction relative to the given coordinate system.
const float3 headPosition = pose.Head().Position();
const float3 headDirection = pose.Head().ForwardDirection();
// The anchor is positioned two meter(s) along the user's gaze direction.
constexpr float distanceFromUser = 2.0f; // meters
const float3 gazeAtTwoMeters = headPosition + (distanceFromUser * headDirection);
localAnchor = SpatialAnchor::TryCreateRelativeTo(currentCoordinateSystem, gazeAtTwoMeters);
// 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.
CloudSpatialAnchor cloudAnchor = CloudSpatialAnchor();
cloudAnchor.LocalAnchor(localAnchor);
co_await m_cloudSession.CreateAnchorAsync(cloudAnchor);
m_feedback = LR"(Created a cloud anchor with ID=)" + cloudAnchor.Identifier();
Daha önce açıklandığı gibi, yeni bir bulut uzamsal tutturucu oluşturmaya çalışmadan önce yakalanan yeterli ortam verilerine ihtiyacınız vardır. Bu, ReadyForCreateProgress 1'in üzerinde olması gerekir, ancak bunu yapmak için 1'in üzerine gelene kadar RecommendedForCreateProgress beklemenizi öneririz.
GetSessionStatusAsync yöntemi hakkında daha fazla bilgi edinin.
SessionStatus status = co_await m_cloudSession.GetSessionStatusAsync();
if (value.RecommendedForCreateProgress() < 1.0f) return;
// Issue the creation request ...
Özellikleri ayarlama
Bulut uzamsal bağlantı noktalarınızı kaydederken bazı özellikler eklemeyi seçebilirsiniz. Kaydedilmekte olan nesne türü veya etkileşim için etkinleştirilmesi gerekip gerekmediği gibi temel özellikler gibi. Bunu yapmak bulma sırasında yararlı olabilir: nesneyi kullanıcı için hemen işleyebilirsiniz, örneğin boş içerik içeren bir resim çerçevesi. Ardından, arka planda farklı bir indirme işlemi ek durum ayrıntıları (örneğin, çerçevede görüntülenecek resim) alır.
AppProperties yöntemi hakkında daha fazla bilgi edinin.
CloudSpatialAnchor cloudAnchor = CloudSpatialAnchor();
cloudAnchor.LocalAnchor(localAnchor);
auto properties = m_cloudAnchor.AppProperties();
properties.Insert(LR"(model-type)", LR"(frame)");
properties.Insert(LR"(label)", LR"(my latest picture)");
co_await m_cloudSession.CreateAnchorAsync(cloudAnchor);
Özellikleri güncelleştirme
Bir tutturucudaki özellikleri güncelleştirmek için yöntemini kullanırsınız UpdateAnchorProperties() . İki veya daha fazla cihaz aynı tutturucunun özelliklerini aynı anda güncelleştirmeye çalışırsa iyimser bir eşzamanlılık modeli kullanırız. Bu da ilk yazmanın kazanacağı anlamına gelir. Diğer tüm yazma işlemleri "Eşzamanlılık" hatası alır: Yeniden denemeden önce özelliklerin yenilenmesi gerekir.
UpdateAnchorPropertiesAsync yöntemi hakkında daha fazla bilgi edinin.
CloudSpatialAnchor anchor = /* locate your anchor */;
anchor.AppProperties().Insert(LR"(last-user-access)", LR"(just now)");
co_await m_cloudSession.UpdateAnchorPropertiesAsync(anchor);
Hizmette oluşturulduktan sonra yer işareti konumunu güncelleştiremezsiniz. Yeni bir yer işareti oluşturmanız ve yeni konumu izlemek için eskisini silmeniz gerekir.
Özelliklerini güncelleştirmek için bir tutturucu bulmanız gerekmiyorsa, özellikleri olan bir CloudSpatialAnchor nesne döndüren yöntemini kullanabilirsinizGetAnchorPropertiesAsync().
GetAnchorPropertiesAsync yöntemi hakkında daha fazla bilgi edinin.
CloudSpatialAnchor anchor = co_await m_cloudSession.GetAnchorPropertiesAsync(LR"(anchorId)");
if (anchor != nullptr)
{
anchor.AppProperties().Insert(LR"(last-user-access)", LR"(just now)");
co_await m_cloudSession.UpdateAnchorPropertiesAsync(anchor);
}
Süre sonu ayarla
Bağlantınızın süresinin gelecekte belirli bir tarihte otomatik olarak dolacak şekilde yapılandırılması da mümkündür. Yer işareti sona erdiğinde, bağlantı noktası artık bulunmayacak veya güncelleştirilmeyecektir. Süre sonu yalnızca yer işareti oluşturulduğunda, buluta kaydedilmeden önce ayarlanabilir. Daha sonra süre sonunu güncelleştirmek mümkün değildir. Yer işareti oluşturma sırasında süre sonu ayarlı değilse, tutturucunun süresi yalnızca el ile silindiğinde sona erer.
Expiration yöntemi hakkında daha fazla bilgi edinin.
const int64_t oneWeekFromNowInHours = 7 * 24;
const DateTime oneWeekFromNow = DateTime::clock::now() + std::chrono::hours(oneWeekFromNowInHours);
cloudAnchor.Expiration(oneWeekFromNow);
Bulut uzamsal yer işareti bulma
Azure Spatial Anchors'ı kullanmanın başlıca nedenlerinden biri, önceden kaydedilmiş bir bulut uzamsal tutturucuyu bulabilmektir. Bunun için "İzleyiciler" kullanıyoruz. Aynı anda yalnızca bir İzleyici kullanabilirsiniz; birden çok İzleyici desteklenmez. İzleyicinin bir bulut uzamsal sabit noktasını bulabilmesinin birkaç farklı yolu vardır (Yer İşareti Bulma Stratejileri olarak da bilinir). Bir izleyicide aynı anda tek bir strateji kullanabilirsiniz.
- Tanımlayıcıya göre yer işaretleri bulun.
- Önceden bulunan bir yer işaretine bağlı bağlantıları bulun. Yer işareti ilişkileri hakkında buradan bilgi edinebilirsiniz.
- Kaba yeniden konumlandırmayı kullanarak yer işareti bulun.
Dekont
Her yer işareti kullandığınızda Azure Spatial Anchors, yer işareti üzerindeki görsel bilgileri artırmak için toplanan ortam verilerini kullanmayı dener. Bir tutturucuyu bulma konusunda sorun yaşıyorsanız, bir yer işareti oluşturmak ve ardından farklı açılardan ve aydınlatma koşullarından birkaç kez bulmak yararlı olabilir.
Bulut uzamsal bağlantı noktalarını tanımlayıcıya göre konumlandırıyorsanız, bulut uzamsal yer işareti tanımlayıcısını uygulamanızın arka uç hizmetinde depolayabilir ve doğru kimlik doğrulaması yapabilen tüm cihazlar için erişilebilir hale getirebilirsiniz. Bunun bir örneği için bkz . Öğretici: Uzamsal Yer İşaretlerini cihazlar arasında paylaşma.
Bir AnchorLocateCriteria nesnenin örneğini oluşturun, aradığınız tanımlayıcıları ayarlayın ve oturumda yönteminizi sağlayarak çağırın CreateWatcherAnchorLocateCriteria.
CreateWatcher yöntemi hakkında daha fazla bilgi edinin.
AnchorLocateCriteria criteria = AnchorLocateCriteria();
criteria.Identifiers({ LR"(id1)", LR"(id2)", LR"(id3)" });
auto cloudSpatialAnchorWatcher = m_cloudSession.CreateWatcher(criteria);
İzleyiciniz oluşturulduktan sonra, AnchorLocated olay istenen her yer işareti için tetiklenir. Bu olay, bir yer işareti bulunduğunda veya yer işareti bulunamazsa tetikler. Bu durum ortaya çıkarsa, nedeni durum olarak belirtilir. bir izleyicinin tüm tutturucuları işlendikten, bulunduktan veya bulunamadıktan sonra LocateAnchorsCompleted olay tetiklenir. İzleyici başına 35 tanımlayıcı sınırı vardır.
AnchorLocatedDelegate temsilcisi hakkında daha fazla bilgi edinin.
m_anchorLocatedToken = m_cloudSession.AnchorLocated(winrt::auto_revoke, [this](auto&&, auto&& args)
{
switch (args.Status())
{
case LocateAnchorStatus::Located:
{
CloudSpatialAnchor foundAnchor = args.Anchor();
}
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;
}
});
Tutturucuları silme
Artık kullanılmadığında tutturucuları silmek, Azure kaynaklarınızı temiz tutmak için geliştirme sürecinize ve uygulamalarınıza erken dahil etmek iyi bir uygulamadır.
DeleteAnchorAsync yöntemi hakkında daha fazla bilgi edinin.
co_await m_cloudSession.DeleteAnchorAsync(cloudAnchor);
// Perform any processing you may want when delete finishes
Oturumu duraklatma, sıfırlama veya durdurma
Oturumu geçici olarak durdurmak için öğesini çağırabilirsiniz Stop(). Bunu yaptığınızda, çağırsanız ProcessFrame()bile tüm izleyiciler ve ortam işlemleri durdurulacaktır. Ardından işlemeye devam etmek için çağırabilirsiniz Start() . Devam ederken, oturumda zaten yakalanan ortam verileri korunur.
Stop yöntemi hakkında daha fazla bilgi edinin.
m_cloudSession.Stop();
Oturumunuzda yakalanan ortam verilerini sıfırlamak için öğesini çağırabilirsiniz Reset().
Reset yöntemi hakkında daha fazla bilgi edinin.
m_cloudSession.Reset();
Bir oturumdan sonra tüm başvuruları düzgün bir şekilde temizlemek için.
m_cloudSession = nullptr;
Sonraki adımlar
Bu kılavuzda, Azure Spatial Anchors SDK'sını kullanarak yer işaretleri oluşturmayı ve bulmayı öğrendiniz. Bağlantı ilişkileri hakkında daha fazla bilgi edinmek için sonraki kılavuza geçin.