Features — LeonardoXR SDK

Version: 1.0.2 Target Device: Youbiquo Leonardo XR
Base SDK: Snapdragon Spaces 1.0.4

Questa pagina documenta le features disponibili nell’SDK LeonardoXR, organizzate in due sezioni:

Snapdragon Spaces Features — funzionalità AR/XR fornite dalla piattaforma Snapdragon Spaces e accessibili tramite AR Foundation.
LeonardoXR Features — funzionalità proprietarie specifiche di Leonardo XR.

Snapdragon Spaces Features

Local Anchors

Come Abilitare

Vai su Project Settings > XR Plug-in Management > OpenXR (scheda Android) > OpenXR Feature Groups > Snapdragon Spaces > Spatial Anchors e abilita la feature.

Spaces Anchor Store (Script)

Attenzione: Guarda intorno all’ambiente per generare una mappa di tracking migliore e ridurre i tempi di salvataggio/caricamento. Salvare più anchor contemporaneamente blocca il main thread — usa il callback per salvare gli anchor successivi in modo sequenziale.

Questo componente richiede un AR Anchor Manager (aggiunto automaticamente se assente). Aggiungi Spaces Anchor Store insieme ad AR Anchor Manager per salvare gli anchor localmente per le sessioni future.

namespace Qualcomm.Snapdragon.Spaces
{
    public class SpacesAnchorStore
    {
        public void ClearStore();

        public void SaveAnchor(ARAnchor anchor, string anchorName, Action<bool> onSavedCallback = null);
        public void SaveAnchor(ARAnchor anchor, Action<bool> onSavedCallback = null);
        public void SaveAnchorWithResult(ARAnchor anchor, string anchorName, Action<SaveAnchorResult> onSavedCallback = null);
        public void SaveAnchorWithResult(ARAnchor anchor, Action<SaveAnchorResult> onSavedCallback = null);

        public void DeleteSavedAnchor(string anchorName);

        public void LoadSavedAnchor(string anchorName, Action<bool> onLoadedCallback = null);
        public void LoadAllSavedAnchors(Action<bool> onLoadedCallback = null);

        public string[] GetSavedAnchorNames();
        public string GetSavedAnchorNameFromARAnchor(ARAnchor anchor);
    }
}

API Reference

Metodo	Descrizione
`ClearStore()`	Pulisce il local anchor storage.
`SaveAnchor(...)`	Salva un `ARAnchor` per nome o hash generato; callback opzionale al completamento.
`SaveAnchorWithResult(...)`	Come `SaveAnchor` ma restituisce un enum `SaveAnchorResult`.
`DeleteSavedAnchor(name)`	Elimina un anchor salvato per nome.
`LoadSavedAnchor(name, ...)`	Carica un anchor dallo storage e prova a localizzarlo; lancia `ARAnchorManager.anchorsChanged.added`.
`LoadAllSavedAnchors(...)`	Carica tutti gli anchor memorizzati.
`GetSavedAnchorNames()`	Restituisce tutti i nomi degli anchor salvati.
`GetSavedAnchorNameFromARAnchor(anchor)`	Restituisce il nome di un anchor salvato da un `ARAnchor` tracciato, o stringa vuota se non salvato.

Valori di `SaveAnchorResult`

Valore	Significato
`PENDING`	L’anchor è in attesa di salvataggio.
`SAVED`	Salvato con successo.
`FAILURE_RUNTIME_ERROR`	Errore di runtime.
`FAILURE_STORE_NOT_LOADED`	L’Anchor Store non è riuscito a caricarsi.
`FAILURE_INSUFFICIENT_QUALITY`	La qualità della mappa ambientale è insufficiente.

Hit Testing

Abilitare tramite Project Settings > XR Plug-in Management > OpenXR (scheda Android) > Snapdragon Spaces > Hit Testing.

Usa l’AR Raycast Manager di AR Foundation (XRRaycastSubsystem). Supporta hit testing continuo contro piani e mesh del mondo reale.

Come funziona: Il sistema proietta un ray dalla camera (o da un punto specificato) e restituisce le intersezioni con le superfici rilevate nell’ambiente. Ogni hit contiene posizione, normale e tipo di superficie (piano o mesh).

Utilizzo tipico:

// Aggiungi ARRaycastManager alla scena tramite XR Origin
// Poi esegui il raycast:
List<ARRaycastHit> hits = new List<ARRaycastHit>();
if (raycastManager.Raycast(screenCenter, hits, TrackableType.PlaneWithinPolygon))
{
    Pose hitPose = hits[0].pose;
    // Posiziona contenuto AR a hitPose.position
}

Known Issue: ARRaycastHit.trackableId restituisce sempre 0-0.

Image Tracking

Abilitare tramite Project Settings > XR Plug-in Management > OpenXR (scheda Android) > Snapdragon Spaces > Image Tracking.

Usa l’AR Tracked Image Manager di AR Foundation (XRImageTrackingSubsystem). Supporta librerie di immagini di riferimento statiche e mutabili (runtime). Le modalità di tracking opzionali controllano la frequenza di calcolo.

Libreria di immagini statica: configurata nell’Inspector tramite un asset XRReferenceImageLibrary. Le immagini vengono compilate nel build.

Libreria mutabile: usa MutableRuntimeReferenceImageLibrary per aggiungere immagini a runtime:

var library = trackedImageManager.CreateRuntimeLibrary() as MutableRuntimeReferenceImageLibrary;
await library.ScheduleAddImageWithValidationJob(texture, "nome-immagine", 0.1f); // 0.1f = larghezza fisica in metri
trackedImageManager.referenceLibrary = library;

Plane Detection

Abilitare tramite Project Settings > XR Plug-in Management > OpenXR (scheda Android) > Snapdragon Spaces > Plane Detection.

Usa l’AR Plane Manager di AR Foundation (XRPlaneSubsystem). L’opzione Use Scene Understanding Backend è abilitata di default. Supporta modalità di rilevamento per controllare il comportamento. I piani con convex hull possono essere abilitati o disabilitati tramite il componente opzionale SpacesARPlaneManagerConfig.

Modalità di rilevamento disponibili:

PlaneDetectionMode.Horizontal — rileva solo superfici orizzontali.
PlaneDetectionMode.Vertical — rileva solo superfici verticali.
PlaneDetectionMode.Horizontal | PlaneDetectionMode.Vertical — rileva entrambe.

Configurazione del PlaneManager:

arPlaneManager.requestedDetectionMode = PlaneDetectionMode.Horizontal | PlaneDetectionMode.Vertical;

Known Issue: Plane Detection entra in un loop infinito di triangolazione mesh in AR Foundation 6.0.
Known Issue (Unity 6 + OpenXR 1.15.1): Plane Detection non funziona nelle app Dual Render Fusion.

Camera Frame Access

Abilitare tramite Project Settings > XR Plug-in Management > OpenXR (scheda Android) > Snapdragon Spaces > Camera Frame Access.

Usa l’AR Camera Manager di AR Foundation (XRCameraSubsystem). Funzionalità principali:

Accesso ai frame camera raw in formato YUV (Y'UV420sp) e YUYV / YUY2.
XRCpuImage.GetPlane(int) per accesso CPU-side all’immagine.
XRCpuImage.ConvertAsync per conversione asincrona.
ARCameraManager.currentConfiguration / GetConfigurations per query sulla risoluzione.
ARCameraFrameEventArgs.displayMatrix per la trasformazione del display.
Accesso al frame RGB accelerato da GPU per dispositivi AiO (tramite OpenGL).
Recupero di estrinseci del sensore / pose tramite InputBindings.

Importante: Abilita Allow ‘unsafe’ Code in Player Settings > Android > Other Settings > Script Compilation quando si usa il sample Camera Frame Access. Disabilita AR Camera Background per evitare problemi di rendering.

Esempio di accesso ai frame YUV:

void OnCameraFrameReceived(ARCameraFrameEventArgs args)
{
    if (cameraManager.TryAcquireLatestCpuImage(out XRCpuImage image))
    {
        using (image)
        {
            // Accedi al piano Y (luminanza)
            XRCpuImage.Plane yPlane = image.GetPlane(0);
            // yPlane.data contiene i dati grezzi
        }
    }
}

Spatial Meshing

Abilitare tramite Project Settings > XR Plug-in Management > OpenXR (scheda Android) > Snapdragon Spaces > Spatial Meshing.

Usa l’AR Mesh Manager di AR Foundation (XRMeshSubsystem). Il componente opzionale SpacesARMeshManagerConfig controlla le caratteristiche della mesh e gestisce gli offset di altezza camera per TrackingOriginMode.Floor.

Parametri configurabili tramite SpacesARMeshManagerConfig:

Densità e granularità della mesh.
Gestione dell’offset verticale della camera in modalità Floor.

Nota: Alcune proprietà di AR Mesh Manager non sono supportate e generano avvisi a runtime.

QR Code Tracking

Abilitare tramite Project Settings > XR Plug-in Management > OpenXR (scheda Android) > Snapdragon Spaces > QR Code Tracking.

Usa il componente custom SpacesQrCodeManager. Supporta più modalità di tracking per controllare la frequenza di calcolo dell’algoritmo.

Nota: Non esiste un subsystem di simulazione editor per QR Code Tracking. Aggira i controlli del subsystem nelle build editor:
bool CheckSubsystem()
{
#if UNITY_EDITOR
    return arQrCodeManager.subsystem?.running ?? false;
#else
    return true;
#endif
}

Hand Tracking

Abilitare tramite Project Settings > XR Plug-in Management > OpenXR (scheda Android) > Snapdragon Spaces > Hand Tracking.

L’Hand Tracking è fornito dai pacchetti del plugin QCHT (Qualcomm Hand Tracking). Per LeonardoXR si usa il pacchetto XR Hands (v1.7.2) di Unity come layer di accesso ai dati delle giunture, integrato con le estensioni QCHT.

Il toggle Auto Start nelle impostazioni della feature OpenXR controlla se Hand Tracking viene riavviato automaticamente quando gli occhiali si riconnettono dopo una disconnessione.

Attenzione: Per far funzionare correttamente Hand Tracking su LeonardoXR, l’opzione Hand Tracking Subsystem deve essere attiva in All Features di OpenXR.

Per l’integrazione completa dell’Hand Tracking con XR Interaction Toolkit, vedi Interaction Package Guides.

Foveated Rendering

Abilitare tramite Project Settings > XR Plug-in Management > OpenXR (scheda Android) > Snapdragon Spaces > Foveated Rendering.

Il foveated rendering riduce il carico GPU renderizzando la periferia del campo visivo a risoluzione inferiore, concentrando la risoluzione al centro dello sguardo. Le impostazioni di foveation persistono dopo la pausa e la ripresa dell’applicazione.

Livelli di foveation disponibili:

None — nessuna riduzione.
Low — riduzione leggera, impercettibile alla maggior parte degli utenti.
Medium — buon compromesso tra qualità e performance.
High — riduzione massima, consigliata solo per scene con molto contenuto 3D.

LeonardoXR Features

Le seguenti features sono specifiche di Leonardo XR e non fanno parte della piattaforma Snapdragon Spaces base.

Abilitare le LeonardoXR features tramite Project Settings > XR Plug-in Management > OpenXR (scheda Android) > LeonardoXR feature group.

Dual Camera Access

⚠️ Documentazione in preparazione.
Questa feature consente l’accesso ai frame delle due camere del dispositivo Leonardo XR in modo sincronizzato. La documentazione dettagliata sull’API, la configurazione e i sample sarà disponibile in una prossima versione della guida.

QNN Inference Plugin

⚠️ Documentazione in preparazione.
Questa feature espone le capacità di inferenza neurale hardware di Leonardo XR tramite il Qualcomm Neural Network (QNN) runtime. Permette di eseguire modelli AI/ML direttamente sull’NPU del dispositivo. La documentazione dettagliata sull’API, il workflow di conversione modelli e i sample sarà disponibile in una prossima versione della guida.

Intercept OpenXR Function

⚠️ Documentazione in preparazione.
Questa feature avanzata fornisce un meccanismo per intercettare e sovrascrivere funzioni OpenXR a basso livello. È destinata a casi d’uso specializzati che richiedono controllo diretto sul layer OpenXR. La documentazione dettagliata sull’utilizzo sarà disponibile in una prossima versione della guida.