Unity'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 Unity'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 Unity hakkında temel bilgiler.
- Android kullanmak istiyorsanız ARCore veya iOS kullanmak istiyorsanız ARKit hakkında temel bilgi.
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 cloudSession;
// In your view handler
this.cloudSession = new 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.
this.cloudSession.Configuration.AccountKey = @"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.
this.cloudSession.Configuration.AccessToken = @"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.
this.cloudSession.TokenRequired += (object sender, TokenRequiredEventArgs args) =>
{
args.AccessToken = @"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.
this.cloudSession.TokenRequired += async (object sender, TokenRequiredEventArgs args) =>
{
var deferral = args.GetDeferral();
string myToken = await MyGetTokenAsync();
if (myToken != null) 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.
this.cloudSession.Configuration.AuthenticationToken = @"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.
this.cloudSession.TokenRequired += (object sender, TokenRequiredEventArgs args) =>
{
args.AuthenticationToken = @"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.
this.cloudSession.TokenRequired += async (object sender, TokenRequiredEventArgs args) =>
{
var deferral = args.GetDeferral();
string myToken = await MyGetTokenAsync();
if (myToken != null) 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.
#if UNITY_ANDROID || UNITY_IOS
this.cloudSession.Session = aRSession.subsystem.nativePtr.GetPlatformPointer();
#elif UNITY_WSA || WINDOWS_UWP
// No need to set a native session pointer for HoloLens.
#else
throw new NotSupportedException("The platform is not supported.");
#endif
this.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.
#if UNITY_ANDROID || UNITY_IOS
XRCameraFrame xRCameraFrame;
if (aRCameraManager.subsystem.TryGetLatestFrame(cameraParams, out xRCameraFrame))
{
long latestFrameTimeStamp = xRCameraFrame.timestampNs;
bool newFrameToProcess = latestFrameTimeStamp > lastFrameProcessedTimeStamp;
if (newFrameToProcess)
{
session.ProcessFrame(xRCameraFrame.nativePtr.GetPlatformPointer());
lastFrameProcessedTimeStamp = latestFrameTimeStamp;
}
}
#endif
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.
this.cloudSession.SessionUpdated += (object sender, SessionUpdatedEventArgs args) =>
{
var status = args.Status;
if (status.UserFeedback == SessionUserFeedback.None) return;
this.feedback = $"Feedback: {Enum.GetName(typeof(SessionUserFeedback), status.UserFeedback)} -" +
$" Recommend Create={status.RecommendedForCreateProgress: 0.#%}";
};
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.
// Create a local anchor, perhaps by hit-testing and spawning an object within the scene
Vector3 hitPosition = new Vector3();
#if UNITY_ANDROID || UNITY_IOS
Vector2 screenCenter = new Vector2(0.5f, 0.5f);
List<ARRaycastHit> aRRaycastHits = new List<ARRaycastHit>();
if(arRaycastManager.Raycast(screenCenter, aRRaycastHits) && aRRaycastHits.Count > 0)
{
ARRaycastHit hit = aRRaycastHits[0];
hitPosition = hit.pose.position;
}
#elif WINDOWS_UWP || UNITY_WSA
RaycastHit hit;
if (this.TryGazeHitTest(out hit))
{
hitPosition = hit.point;
}
#endif
Quaternion rotation = Quaternion.AngleAxis(0, Vector3.up);
this.localAnchor = GameObject.Instantiate(/* some prefab */, hitPosition, rotation);
this.localAnchor.AddComponent<CloudNativeAnchor>();
// 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.
CloudNativeAnchor cloudNativeAnchor = this.localAnchor.GetComponent<CloudNativeAnchor>();
if (cloudNativeAnchor.CloudAnchor == null) { await cloudNativeAnchor.NativeToCloud(); }
CloudSpatialAnchor cloudAnchor = cloudNativeAnchor.CloudAnchor;
await this.cloudSession.CreateAnchorAsync(cloudAnchor);
this.feedback = $"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 value = await this.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 özelliği hakkında daha fazla bilgi edinin.
CloudSpatialAnchor cloudAnchor = new CloudSpatialAnchor() { LocalAnchor = localAnchor };
cloudAnchor.AppProperties[@"model-type"] = @"frame";
cloudAnchor.AppProperties[@"label"] = @"my latest picture";
await this.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[@"last-user-access"] = @"just now";
await this.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.
var anchor = await cloudSession.GetAnchorPropertiesAsync(@"anchorId");
if (anchor != null)
{
anchor.AppProperties[@"last-user-access"] = @"just now";
await this.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 özelliği hakkında daha fazla bilgi edinin.
cloudAnchor.Expiration = DateTimeOffset.Now.AddDays(7);
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 = new AnchorLocateCriteria();
criteria.Identifiers = new string[] { @"id1", @"id2", @"id3" };
this.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.
this.cloudSession.AnchorLocated += (object sender, AnchorLocatedEventArgs args) =>
{
switch (args.Status)
{
case LocateAnchorStatus.Located:
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;
}
}
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.
Yer değiştirdikten sonra yer işareti silme (önerilir)
await this.cloudSession.DeleteAnchorAsync(cloudAnchor);
// Perform any processing you may want when delete finishes
Yer bulmadan yer işareti silme
Bir tutturucuyu bulamıyor ancak yine de silmek istiyorsanız nesneyi almak için giriş olarak anchorId alan API'yi CloudSpatialAnchor kullanabilirsinizGetAnchorPropertiesAsync. Daha sonra silmek için bu nesneyi içine DeleteAnchorAsync geçirebilirsiniz.
var anchor = await cloudSession.GetAnchorPropertiesAsync(@"anchorId");
await this.cloudSession.DeleteAnchorAsync(anchor);
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.
this.cloudSession.Stop();
Oturumunuzda yakalanan ortam verilerini sıfırlamak için öğesini çağırabilirsiniz Reset().
Reset yöntemi hakkında daha fazla bilgi edinin.
this.cloudSession.Reset();
Oturumdan sonra düzgün bir şekilde temizlemek için çağrısı yapın Dispose().
Dispose yöntemi hakkında daha fazla bilgi edinin.
this.cloudSession.Dispose();
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.