XGRIDSDocumentazione
  • 简体中文
  • English
  • 繁體中文
  • 日本語
  • Deutsch
  • Español
  • Italiano
  • Français
  • Русский
  • Polski
  • Nederlands
  • 简体中文
  • English
  • 繁體中文
  • 日本語
  • Deutsch
  • Español
  • Italiano
  • Français
  • Русский
  • Polski
  • Nederlands
  • Serie Lixel PortalCam

    • PortalCam P1

      • Panoramica del prodotto
      • Operazioni di base
      • Uso della LCC Scan App
      • Manutenzione e cura
      • FAQ
  • Serie Lixel K

    • Lixel K1

      • Panoramica del prodotto
      • Operazioni di base
      • Attivazione e connessione del dispositivo
      • Flusso di scansione
      • Ottenere una nuvola di punti con coordinate assolute
      • Fusione delle mappe
      • Consigli di pianificazione dei percorsi per scene tipiche
      • Precauzioni
      • FAQ
    • Lixel K2

      • Panoramica del prodotto
      • Operazioni di base
      • Attivazione e connessione
      • Flusso di scansione
      • Acquisire una nuvola di punti con coordinate assolute
      • Fusione mappe
      • Consigli di pianificazione dei percorsi per scene tipiche
      • Precauzioni
      • FAQ
  • Serie Lixel L

    • Lixel L2 Pro

      • Panoramica del prodotto
      • Operazioni di base
      • Attivazione e connessione del dispositivo
      • Flusso di scansione
      • Ottenere una nuvola di punti con coordinate assolute
      • Punto di misura
      • Appendice
      • FAQ
    • Lixel L3

      • Panoramica del prodotto
      • Operazioni di base
      • Attivazione e connessione del dispositivo
      • Acquisizione dei dati
      • Acquisizione di coordinate assolute
      • Appendice
  • Lixel Studio

    • Versione e copyright
    • Installazione e attivazione
    • Interfaccia del software
    • Operazioni sui file
    • Elaborazione del progetto
    • Strumenti
    • Disegno 2D
    • Applicazioni di settore
    • Impostazioni
    • Connessione del dispositivo
    • Domande Frequenti
  • Lixel CyberColor

    • LCC Studio

      • Introduzione
      • Versione e aggiornamenti
      • Download e installazione
      • Panoramica dell'interfaccia e navigazione
      • Operazioni preliminari alla ricostruzione
      • Prima della ricostruzione
      • Ricostruzione del modello
      • Ricostruzione modello singolo
      • Fusione delle mappe
      • Fusione aria-terra
      • Ricostruzione aerea
      • I miei modelli
      • Altre funzioni
      • Impostazioni e account
      • Convertitore
      • Ricostruzione video
      • Domande Frequenti / FAQ
    • LCC Scene Editor

      • Versione e aggiornamenti
      • Account e accesso
      • Panoramica del prodotto e home page
      • Interfaccia dell'editor
      • Modalità di navigazione
      • File
      • Impostazioni
      • Modifica
      • Finestra
      • Barra degli strumenti globale
      • Asset e proprietà
      • Barra degli strumenti sinistra
      • Punti di vista
      • Portale
      • Skybox
      • Annotazioni
      • Misurazione
      • Flythrough
      • Rapporto scena
      • 3D Layout
      • Mini-mappa
      • Modalità Anteprima (Viewer)
      • Aiuto
      • Domande frequenti (FAQ)
      • Punto di spawn
    • LCC Model Editor

      • Versione e aggiornamenti
      • Guida utente
      • Panoramica e interfaccia
      • Operazioni sui file
      • Selettori
      • Modifica dei modelli
      • Misurazione
      • Correzione colore
      • Gestione degli asset
      • Impostazioni e Aiuto
      • Domande frequenti
    • Capture Guide

      • Panoramica
      • Panoramica dei dispositivi di acquisizione
      • Principi generali di acquisizione
      • Acquisizione di scene interne
      • Acquisizione di scene esterne
      • Acquisizione su larga scala (map fusion)
      • Acquisizione per aerial-ground map fusion
      • Acquisizione di oggetti
      • Acquisizione di persone
      • Acquisizione per ricostruzione da video
      • HD Enhancement
      • Control points (Lixel P1)
      • FAQ e risoluzione dei problemi
    • Buone Pratiche

      • Unione di più modelli 3DGS di grandi dimensioni
    • Cronologia versioni
  • Plugin e SDK

    • Unreal

      • Introduzione
      • Avvio rapido - Windows
      • Avvio rapido - Linux
      • Avvio rapido - Quest3
      • Edizioni e licenze
      • Rendering
      • Rasterizzazione Tiled (sperimentale)
      • Impostazioni visive
      • Normali e illuminazione
      • Modifica della scena
      • Parametri di prestazione
      • Guida alle prestazioni
      • Integrazione con plugin di terze parti e del motore
      • Proxy Mesh
      • Animazione di caricamento
      • Collisioni
      • Supporto del Navigation System
      • Supporto di Single Layer Water
      • Localizzazione
      • FAQ
      • Risoluzione dei problemi
      • Log e diagnostica
      • Contattaci
      • Buone pratiche

        • Rilluminare il 3DGS con una mesh di LixelStudio
      • Riferimento API

        • ALCCActorBase
        • ULCCComponentBase
        • ULCCComponent
        • ULCC2Component
        • Actor SOG / SPZ / PLY
        • ALCC2ProxyMesh
        • ALCCClippingVolume
        • ALCCSectionPlane
        • ALCCLoadVolume
        • ULCCUtilLibrary
        • Enum
        • Struct
      • Registro delle modifiche

        • v3.4.0
        • v3.3.1
        • v3.0.0
        • v2.2.1
        • v1.0.0
        • v0.9.0
        • v0.8.0
        • v0.7.1
        • v0.6.1
        • v0.5.2
        • v0.4.1
        • v0.4.0
        • v0.3.0
        • v0.0.5
        • v0.0.4
        • v0.0.3
        • v0.0.2
        • v0.0.1
    • Unity

      • Introduzione all'Unity SDK
      • Caratteristiche tecniche
      • Requisiti dell'ambiente di sviluppo
      • Guida rapida per PC
      • Guida all'ottimizzazione delle impostazioni di progetto
      • Guida allo sviluppo per Pico 4 Ultra
      • Guida allo streaming PC per Pico 4 Ultra
      • Guida allo sviluppo per Quest 3
      • Guida allo streaming PC per Quest 3
      • Guida allo sviluppo OpenXR
      • Guida allo streaming Business per Pico 4 Ultra
      • Glossario
      • FAQ
      • Contattaci
      • Guida allo sviluppo delle funzionalità

        • Guida allo sviluppo del rendering misto multi-scena
        • Guida allo sviluppo della ricezione delle ombre
        • Guida allo sviluppo dell'illuminazione in tempo reale
        • Guida allo sviluppo del rendering multi-camera
        • Guida allo sviluppo del rendering di immagini ad alta risoluzione
        • Guida allo sviluppo della compatibilità dei formati dati LCC e LCC2
        • Guida allo sviluppo dell'effetto di caricamento
        • Guida allo sviluppo del cambio di modalità di rendering Mip
        • Guida allo sviluppo dello snap a bordi e angoli
        • Guida allo sviluppo della decal proiettata
        • Guida allo sviluppo della decal proiettata video
        • Guida allo sviluppo dell'evidenziazione
        • Guida allo sviluppo del ritaglio in tempo reale
        • Guida allo sviluppo della regolazione del tono
        • Guida allo sviluppo dell'ottenimento dei dati Mesh della scena
        • Guida allo sviluppo della modalità Editor
        • Guida alla configurazione dei parametri di prestazioni di rendering
        • Guida allo sviluppo del co-impacchettamento di applicazione e dati
        • Guida allo sviluppo del sistema di collisione
        • Guida ai problemi di autorizzazione nello sviluppo su macOS
        • Guida allo sviluppo di compilazione e packaging per dispositivi iOS
      • Riferimento API

        • LCCManager
        • Renderer
        • Tipi di dati
      • Registro delle modifiche

        • v2.3.0
        • v2.2.10
        • v2.2.0
        • v2.1.19
        • v2.0.14
    • Web

      • Introduzione
      • Guida all'ottimizzazione delle prestazioni di rendering
      • Configurazione grafica
      • Domande frequenti
      • Riferimento API

        • LCCRender::clearIndexDB
        • LCCRender::dispose
        • LCCRender::load
        • LCCRender::setCamera
        • LCCRender::unload
        • LCCRender::update
        • LCCObject::checkRenderNextFrame
        • LCCObject::clearRenderNextFrame
        • LCCObject::ecef2Prj
        • LCCObject::getBounds
        • LCCObject::getEnvInstancedMesh
        • LCCObject::getInstancedMesh
        • LCCObject::getLodInfos
        • LCCObject::getOriginPosition
        • LCCObject::getProjectionCoordinateSystemInfos
        • LCCObject::hasCollision
        • LCCObject::hasEnvironment
        • LCCObject::hasShcoef
        • LCCObject::intersectsCapsule
        • LCCObject::intersectsRayExt
        • LCCObject::intersectsRayFromOriginExt
        • LCCObject::intersectsSphere
        • LCCObject::lowerToBottom
        • LCCObject::prj2Ecef
        • LCCObject::raiseToTop
        • LCCObject::raycast
        • LCCObject::raycastFromOrigin
        • LCCObject::setAlpha
        • LCCObject::setClipBox
        • LCCObject::setClipPlane
        • LCCObject::setEndLod
        • LCCObject::setLodAutoLevelUp
        • LCCObject::setMaxDistance
        • LCCObject::setMaxNodeSplats
        • LCCObject::setMaxSplats
        • LCCObject::setOriginPosition
        • LCCObject::setPointsColor
        • LCCObject::setRenderState
        • LCCObject::setRotation
        • LCCObject::setScale
        • LCCObject::setSemantic
        • LCCObject::setSemanticColor
        • LCCObject::setSmooth
        • LCCObject::setStartLod
        • LCCObject::setTranslation
        • LCCObject::setVisible
        • LCCObject::togglePointsDisplayMode
        • LCCObject::useEnvironment
        • LCCObject::useShcoef
      • Registro delle modifiche

        • v0.6.3
        • v0.6.2
        • v0.6.1
        • v0.6.0
        • v0.5.5
        • v0.5.4
        • v0.5.3
        • v0.5.2
        • v0.5.1
        • v0.5.0
        • v0.4.1
        • v0.4.0
        • v0.3.1
        • v0.3.0
        • v0.2.0

Guida allo sviluppo della decal proiettata

Panoramica della funzionalità

La proiezione della decal (Decal Projector) proietta un'immagine 2D sulla superficie della nuvola di punti 3DGS come un proiettore di diapositive. Il proiettore è un frustum prospettico fisso nello spazio mondo; la nuvola di punti all'interno del frustum viene coperta dal colore della decal, mentre la nuvola di punti all'esterno del frustum non viene influenzata. La decal è uno stato di ombreggiatura globale che produce un effetto di ombreggiatura coerente sull'intera scena 3DGS.

Oltre alla proiezione di base, è possibile abilitare facoltativamente l'occlusion culling. Per impostazione predefinita la decal è simile ai raggi X: poiché il 3DGS stesso non ha il concetto di superficie, la decal penetra fino alle facce posteriori occluse dagli oggetti frontali e attraversa l'intera scena 3DGS. Dopo aver abilitato l'occlusion culling, solo la superficie frontale rivolta verso il proiettore viene colorata, mentre le facce posteriori occluse e le scene occluse non vengono più colorate, producendo un effetto realistico di proiettore di diapositive.

Nota:

Decal e occlusion culling hanno effetto solo su PC / Mac (pipeline URP). La chiamata delle interfacce correlate sulle piattaforme mobile o VR viene ignorata dall'SDK, che stampa un log di avviso. Non è necessario eseguire controlli di piattaforma sul lato business, ma non aspettarti di vedere l'effetto su quelle piattaforme.

Passaggio 1: crea la scena e i GameObject

Crea una scena completamente nuova in Unity. Unity crea Camera principale e Luce direzionale per impostazione predefinita.

Configura la Camera principale

Seleziona Camera principale nella finestra Gerarchia e imposta le sue proprietà nella finestra Inspector come mostrato di seguito.

Imposta le proprietà della Camera principale

Imposta le proprietà della Camera principale

Crea LCCManager

Fai clic con il pulsante destro su un'area vuota nella finestra Gerarchia, seleziona Crea vuoto dal menu a comparsa per creare un GameObject vuoto, assegna il nome LCCManager, normalizza il suo Transform e aggiungi lo script LCCManager tramite Aggiungi componente.

Crea il GameObject LCCManager e aggiungi lo script LCCManager

Crea il GameObject LCCManager e aggiungi lo script LCCManager

Crea LCCRenderer

Fai clic con il pulsante destro su un'area vuota nella finestra Gerarchia, seleziona Crea vuoto per creare un GameObject vuoto, assegna il nome LCCRenderer e imposta il suo Transform su Rotation.x = -90 e Scale.x = -1.

Crea LCCRenderer e imposta il suo Transform

Crea LCCRenderer e imposta il suo Transform (Rotation.x = -90, Scale.x = -1)

Nota:

Le impostazioni Transform del GameObject LCCRenderer (Rotation.x = -90, Scale.x = -1) lo allineano al sistema di coordinate dei dati LCC. Per i dettagli sull'allineamento del sistema di coordinate, vedi "Sistema di coordinate dei dati LCC" in Introduzione all'Unity SDK.

Crea Projector

Fai clic con il pulsante destro su un'area vuota nella finestra Gerarchia, seleziona Crea vuoto per creare un GameObject vuoto denominato Projector. Lo scopo di creare questo oggetto vuoto è usare il suo componente Transform per controllare la posizione e l'orientamento del proiettore; dopo averlo associato al codice dello script, puoi regolare le proprietà del proiettore in fase di esecuzione. Il proiettore proietta lungo la sua direzione +Z e le sue proprietà possono essere impostate secondo necessità.

Crea il GameObject vuoto Projector come proiettore

Crea il GameObject vuoto Projector come proiettore (+Z è la direzione di proiezione)

Passaggio 2: aggiungi una Render Feature

  1. Nella barra dei menu di Unity, seleziona File → Impostazioni progetto, scegli Graphics a sinistra e conferma il Default Render Pipeline Asset corrente. Questo esempio usa URP (Universal Render Pipeline Asset).
Conferma il Default Render Pipeline Asset nelle impostazioni Graphics

Conferma il Default Render Pipeline Asset nelle impostazioni Graphics

  1. Fai clic su quell'Asset, individua il file asset corrispondente nella finestra Progetto e trova il suo Renderer associato (URP_Renderer.asset in questo esempio).

  2. Seleziona quel file asset Renderer, fai clic su Aggiungi Renderer Feature nella finestra Inspector e aggiungi la Decal Depth Feature.

Aggiungi la Decal Depth Feature al Renderer URP

Aggiungi la Decal Depth Feature al Renderer URP

Nota:

La Decal Depth Feature è un prerequisito per l'occlusion culling. Se usi solo la proiezione di base (decal a raggi X), non è necessario aggiungerla; ma per abilitare l'occlusion culling, devi prima registrare questa Feature nell'URP Renderer Asset, altrimenti la depth map di occlusione non verrà generata e l'occlusione non avrà effetto.

Passaggio 3: scrivi lo script

Crea un nuovo script C# denominato Decal.cs. Il codice completo di seguito simula la prospettiva dell'integratore e copre tutti i 7 metodi relativi alla decal (5 per la proiezione di base + 2 per l'occlusion culling); può essere copiato direttamente nel tuo progetto.

using LCCCore;
using UnityEngine;

/// <summary>
/// Proiezione decal — esempio minimo di utilizzo per sviluppatori.
///
/// Questo script simula uno "script integratore": chiama solo le API pubbliche di LCCManager e non tocca le parti interne dell'SDK.
/// Copre tutte le 7 API della decal:
///   Proiezione di base (5): SetDecalEnabled / SetDecalTexture / SetDecalProjection / SetDecalOpacity / SetDecalEdgeFade
///   Occlusion culling (2): SetDecalOcclusion / SetDecalOcclusionSettings
///
/// Passaggi di utilizzo:
///   1) Crea un GameObject vuoto e associa questo script;
///   2) Nell'Inspector, trascina l'LCCManager della scena su m_manager;
///   3) Imposta m_filePath su un percorso scena LCC valido;
///   4) Trascina l'immagine da proiettare su m_decalTexture (si consiglia di abilitare Read/Write nelle sue impostazioni di importazione);
///   5) Trascina un oggetto vuoto su m_projector come proiettore (lascia vuoto per usare questo oggetto); il suo asse +Z è la direzione di proiezione;
///   6) Avvia. Dopo che la scena ha terminato il caricamento, la decal si attiva automaticamente; trascina il proiettore per vedere la decal sulla nuvola di punti in tempo reale.
///
/// Nota piattaforma: decal e occlusion culling hanno effetto solo su PC/Mac (URP). Le chiamate su mobile/VR vengono ignorate dall'SDK e registrate come avvisi.
/// </summary>
public class Decal : MonoBehaviour
{
    [Header("Obbligatorio")]
    [Tooltip("L'istanza LCCManager nella scena")]
    public LCCManager m_manager;
    [Tooltip("Un percorso scena LCC valido")]
    public string m_filePath;
    [Tooltip("L'immagine della decal da proiettare. RGB=colore, A=maschera propria della decal")]
    public Texture2D m_decalTexture;

    [Header("Proiettore (proietta lungo +Z)")]
    [Tooltip("Posa del proiettore. Lascia vuoto per usare il transform di questo oggetto")]
    public Transform m_projector;
    [Range(1f, 179f)] public float m_fov = 60f;
    [Tooltip("Rapporto d'aspetto della proiezione; <=0 usa automaticamente il rapporto d'aspetto dell'immagine della decal")]
    public float m_aspect = 0f;
    public float m_near = 0.1f;
    public float m_far = 100f;

    [Header("Aspetto della Decal")]
    [Range(0f, 1f)] public float m_opacity = 1.0f;
    [Range(0f, 0.5f)][Tooltip("Larghezza della sfumatura del bordo (rapporto UV). 0 = bordo netto")]
    public float m_edgeFade = 0.1f;
    [Tooltip("Aggiorna la proiezione a ogni fotogramma, così puoi trascinare il proiettore / regolare i parametri in fase di esecuzione")]
    public bool m_updateEveryFrame = true;

    [Header("Occlusion Culling (solo PC/Mac)")]
    [Tooltip("Quando è attivo, i punti retrostanti/occlusi dietro la geometria frontale non vengono più colorati dalla decal (effetto proiettore di diapositive); quando è disattivo è a raggi X")]
    public bool m_occlusion = false;
    [Range(0f, 1f)][Tooltip("Soglia di opacità: solo gli splat con opacità >= a questo valore contribuiscono alla depth map, filtrando i punti fluttuanti/nebbiosi. 0 = partecipano tutti")]
    public float m_occlusionCutoff = 0f;
    [Range(0f, 0.5f)][Tooltip("Tolleranza di profondità relativa. Troppo piccola -> auto-occlusione vicino alla superficie; troppo grande -> colorazione a raggi X diffusa. Predefinito 0.05")]
    public float m_occlusionBias = 0.05f;
    [Range(0, 16)][Tooltip("Limite del raggio dell'impronta quadrata (px), la principale manopola per eliminare la trasparenza a raggi X. 0 = singolo texel, predefinito 2")]
    public int m_occlusionFootprint = 2;
    [Tooltip("Risoluzione della depth map (px, potenza di due 256~4096). Abbassala per riempire i buchi ad angoli radenti. Predefinito 1024")]
    public int m_occlusionResolution = 1024;

    // -- Stato di runtime --
    private bool m_loaded;
    private bool m_lastOcclusion;
    private float m_lastCutoff = float.NaN;
    private float m_lastBias = float.NaN;
    private int m_lastFootprint = -1;
    private int m_lastResolution = -1;

    void Start()
    {
        if (m_manager == null || string.IsNullOrEmpty(m_filePath))
        {
            Debug.LogError("[DecalDemo] m_manager o m_filePath non è assegnato.");
            enabled = false;
            return;
        }

        // 1) Inizializza la pipeline di rendering in modalità editor a scena singola per PC
        m_manager.SetPlatformType(PlatformType.PC);
        m_manager.SwitchRenderPass(ActiveRenderMode.SingleRender);
        m_manager.SetEditorMode(true);

        // 2) Carica la scena della nuvola di punti, poi abilita la decal dopo il completamento (la decal è uno stato globale; impostarla dopo che la scena è pronta è più sicuro)
        var renderer = m_manager.GetRender(this.transform);
        Debug.Log($"[DecalDemo] Avvio caricamento: {m_filePath}");
        renderer.Load(m_filePath,
            _ => { /* callback di avanzamento, non usato nell'esempio */ },
            OnSceneLoaded);
    }

    private void OnSceneLoaded()
    {
        Debug.Log("[DecalDemo] Caricamento completato, abilitazione della proiezione decal.");

        // -- Proiezione di base: 5 API --
        m_manager.SetDecalTexture(m_decalTexture);   // contenuto della decal
        m_manager.SetDecalOpacity(m_opacity);        // opacità complessiva
        m_manager.SetDecalEdgeFade(m_edgeFade);      // sfumatura del bordo
        ApplyProjection();                           // posa del proiettore (chiama internamente SetDecalProjection)
        m_manager.SetDecalEnabled(true);             // abilita la decal (keyword _DECAL)

        // -- Occlusion culling: 2 API -- devono seguire ApplyProjection (la depth map necessita di una VP del proiettore valida)
        m_manager.SetDecalOcclusionSettings(BuildOcclusionSettings());
        m_manager.SetDecalOcclusion(m_occlusion);
        CacheOcclusionState();

        m_loaded = true;
    }

    /// <summary>
    /// Solo a scopo dimostrativo. Nei progetti reali, per ottenere prestazioni migliori non è necessario chiamare
    /// SetDecalProjection / SetDecalOpacity / SetDecalEdgeFade a ogni fotogramma in Update();
    /// chiama l'API corrispondente solo quando il parametro cambia.
    /// </summary>
    void Update()
    {
        if (!m_loaded) return;

        // attiva/disattiva l'occlusione in fase di esecuzione
        if (m_occlusion != m_lastOcclusion)
        {
            m_manager.SetDecalOcclusion(m_occlusion);
            m_lastOcclusion = m_occlusion;
        }

        // un parametro di qualità dell'occlusione è cambiato -> invia la struct una volta
        if (!Mathf.Approximately(m_occlusionCutoff, m_lastCutoff) ||
            !Mathf.Approximately(m_occlusionBias, m_lastBias) ||
            m_occlusionFootprint != m_lastFootprint ||
            m_occlusionResolution != m_lastResolution)
        {
            m_manager.SetDecalOcclusionSettings(BuildOcclusionSettings());
            CacheOcclusionState();
        }

        // aggiorna proiettore / aspetto a ogni fotogramma per un comodo debug in tempo reale
        if (!m_updateEveryFrame) return;
        m_manager.SetDecalOpacity(m_opacity);
        m_manager.SetDecalEdgeFade(m_edgeFade);
        ApplyProjection();
    }

    /// <summary>Costruisce la matrice di proiezione dalla posa corrente del proiettore e dai parametri prospettici.</summary>
    private void ApplyProjection()
    {
        Transform p = m_projector != null ? m_projector : this.transform;
        float aspect = m_aspect > 0f
            ? m_aspect
            : (m_decalTexture != null ? (float)m_decalTexture.width / m_decalTexture.height : 1f);
        m_manager.SetDecalProjection(p.position, p.rotation, m_fov, aspect, m_near, m_far);
    }

    /// <summary>Raccoglie i 4 parametri di occlusione in una struct.</summary>
    private DecalOcclusionSettings BuildOcclusionSettings()
    {
        return new DecalOcclusionSettings
        {
            opacityCutoff  = m_occlusionCutoff,
            depthBias      = m_occlusionBias,
            footprintMaxPx = m_occlusionFootprint,
            resolution     = m_occlusionResolution,
        };
    }

    private void CacheOcclusionState()
    {
        m_lastOcclusion  = m_occlusion;
        m_lastCutoff     = m_occlusionCutoff;
        m_lastBias       = m_occlusionBias;
        m_lastFootprint  = m_occlusionFootprint;
        m_lastResolution = m_occlusionResolution;
    }

    // -- Punti di ingresso di debug comodi (clic destro nell'Inspector) --
    [ContextMenu("Attiva Decal")]  private void DecalOn()  { m_manager?.SetDecalEnabled(true); }
    [ContextMenu("Disattiva Decal")] private void DecalOff() { m_manager?.SetDecalEnabled(false); }
    [ContextMenu("Attiva Occlusione")]  private void OcclusionOn()  { m_occlusion = true;  m_manager?.SetDecalOcclusion(true);  m_lastOcclusion = true; }
    [ContextMenu("Disattiva Occlusione")] private void OcclusionOff() { m_occlusion = false; m_manager?.SetDecalOcclusion(false); m_lastOcclusion = false; }
}

Nota:

La decal è uno stato di ombreggiatura globale e deve essere impostata dopo che la scena LCC ha terminato il caricamento (ovvero nel callback onComplete).

L'esempio inserisce SetDecalTexture / SetDecalProjection / SetDecalEnabled nel callback di completamento di Load (OnSceneLoaded) per evitare di impostarle prima che la nuvola di punti sia pronta.

Le API relative all'occlusion culling SetDecalOcclusionSettings / SetDecalOcclusion devono essere chiamate dopo ApplyProjection (ovvero SetDecalProjection), perché la depth map di occlusione necessita di una matrice view-projection del proiettore valida.

Passaggio 4: associa lo script e configura le proprietà

  1. Associa lo script Decal.cs al GameObject LCCRenderer nella finestra Gerarchia.
  2. Nella finestra Inspector, trascina il GameObject LCCManager sulla proprietà Manager dello script.
  3. Trascina il GameObject Projector sulla proprietà Projector dello script.
  4. Inserisci il percorso del file LCC nella proprietà File Path dello script e trascina l'immagine della texture della decal sulla proprietà Decal Texture.
  5. Gli altri parametri delle proprietà possono essere regolati secondo necessità; il significato di ogni proprietà è mostrato nella tabella seguente.
Impostazioni delle proprietà nell'Inspector per lo script Decal

Impostazioni delle proprietà nell'Inspector per lo script Decal

CampoSignificatoValore predefinito
ManagerL'istanza LCCManager nella scenaObbligatorio
File PathUn percorso scena LCC validoObbligatorio
Decal TextureL'immagine della decal da proiettare, RGB è il colore e A è la maschera propria della decalObbligatorio
ProjectorPosa del proiettore, +Z è la direzione di proiezione; vuoto usa il Transform di questo oggettoVuoto
FovCampo visivo prospettico del proiettore60
AspectRapporto d'aspetto della proiezione; quando è minore o uguale a 0, viene calcolato automaticamente dal rapporto d'aspetto dell'immagine della decal0 (auto)
Near / FarPiani di ritaglio vicino / lontano del frustum del proiettore0.1 / 100
OpacityOpacità complessiva della decal1
Edge FadeLarghezza della sfumatura del bordo (rapporto UV), 0 è un bordo netto0.1
Update Every FrameAggiorna la proiezione a ogni fotogramma, comodo per trascinare il proiettore o cambiare i parametri in fase di esecuzioneSelezionato
OcclusionIndica se abilitare l'occlusion cullingDisattivo
Occlusion CutoffSoglia di opacità; solo gli splat con opacità non inferiore a questo valore contribuiscono alla depth map0
Occlusion BiasTolleranza di profondità relativa0.05
Occlusion FootprintLimite del raggio dell'impronta quadrata (px), la principale manopola per eliminare la trasparenza a raggi X2
Occlusion ResolutionRisoluzione della depth map di occlusione (px, potenza di due 256~4096)1024

Passaggio 5: esegui e osserva l'effetto

Fai clic sul pulsante Play in Unity. Dopo che la scena ha terminato il caricamento, la decal si attiva automaticamente. Quando Update Every Frame è selezionato, puoi trascinare direttamente l'oggetto proiettore nella vista Scene durante l'esecuzione e vedere la decal muoversi sulla superficie 3DGS in tempo reale; anche la regolazione di parametri come Opacity ed Edge Fade ha effetto immediato. Il menu del clic destro del componente dello script fornisce inoltre quattro scorciatoie — Attiva/Disattiva Decal e Attiva/Disattiva Occlusione — per verificare comodamente l'effetto di attivazione/disattivazione separatamente.

Decal proiettata sulla superficie 3DGS dopo l'esecuzione (proiezione di base)

Decal proiettata sulla superficie 3DGS dopo l'esecuzione (proiezione di base, penetrazione a raggi X)

Solo la superficie frontale rivolta verso il proiettore viene colorata dopo l'abilitazione dell'occlusion culling

Dopo l'abilitazione dell'occlusion culling, solo la superficie frontale rivolta verso il proiettore viene colorata (effetto proiettore di diapositive)

FAQ: disabilita la modalità di compatibilità

Se la finestra Console di Unity segnala errori e non appare alcun effetto decal, disabilita la modalità di compatibilità: apri il pannello delle impostazioni tramite Modifica → Impostazioni progetto → Graphics, seleziona la scheda URP e non selezionare la casella dopo Render Graph → Compatibility Mode (Render Graph Disabled).

Non selezionare la modalità di compatibilità Render Graph

Non selezionare la modalità di compatibilità Render Graph (Render Graph Disabled)

Occlusion Culling e regolazione

L'occlusion culling deve essere abilitato dopo che il proiettore è stato configurato. L'esempio chiama prima SetDecalProjection nel callback di completamento del caricamento della scena, poi chiama SetDecalOcclusionSettings e SetDecalOcclusion, per garantire che la depth map di occlusione ottenga una matrice view-projection del proiettore valida. In fase di esecuzione, attiva la casella Occlusion nell'Inspector per vedere i blocchi penetrati eliminati e solo la superficie frontale rivolta verso il proiettore mantenuta.

Prerequisito:

Prima di abilitare l'occlusion culling, la Decal Depth Feature deve essere già registrata nell'URP Renderer Asset (in questo progetto è stata scritta in URP_Renderer.asset come sotto-asset). Se non è registrata, la depth map di occlusione non verrà generata e l'occlusione non avrà effetto.

La qualità dell'occlusione è controllata da quattro parametri, forniti tutti insieme tramite una struct. I quattro sono reciprocamente ortogonali; regolali secondo la tabella seguente:

ParametroEffettoPredefinitoSuggerimento di regolazione
opacityCutoffFiltra gli splat fluttuanti / nebbiosi affinché non avvicinino la superficie di occlusione0Aumenta moderatamente quando compare rumore a blocchi in primo piano; un valore troppo grande causa una colorazione mancata
depthBiasTolleranza di profondità relativa che assorbe lo spessore della superficie della nuvola di punti in base alla distanza0.05Aumenta quando compare rumore di auto-occlusione sulla superficie vicina; diminuisci quando gli occlusori sottili traspirano
footprintMaxPxLa profondità vicina della superficie frontale riempie i vuoti sparsi su scala mondo, la principale manopola per correggere la trasparenza a raggi X2Aumenta quando restano blocchi penetrati; diminuisci quando i contorni sono eccessivamente occlusi, 0 è un singolo texel
resolutionRisoluzione della depth map di occlusione1024Abbassala (ad es. 512 / 256) quando compaiono ampie zone di blocchi piccoli con colorazione mancata sulle superfici radenti, al costo di confini di occlusione leggermente più grezzi

Punti chiave

I passaggi chiave per implementare la decal proiettata:

  1. Crea l'oggetto vuoto Projector nella scena come proiettore; il suo asse +Z è la direzione di proiezione.
  2. Se è necessario l'occlusion culling, assicurati che la Decal Depth Feature sia stata aggiunta al Renderer URP.
  3. Dopo che la scena LCC ha terminato il caricamento, imposta in ordine la texture della decal, l'aspetto e la posa del proiettore, poi abilita la decal (SetDecalEnabled(true)).
  4. L'occlusion culling SetDecalOcclusionSettings / SetDecalOcclusion deve essere chiamato dopo SetDecalProjection.

API relative alla decal

I seguenti metodi sono tutti sulla classe façade LCCManager e hanno effetto solo su PC / Mac (pipeline URP); le chiamate su mobile / VR vengono ignorate e viene stampato un avviso.

SetDecalEnabled

// Valore restituito: void
public void SetDecalEnabled(bool enable)

Attiva/disattiva la proiezione della decal. Quando è abilitata, i parametri di opacità / sfumatura del bordo attualmente in cache vengono inviati alla GPU e la keyword dello shader _DECAL viene abilitata. La decal è uno stato globale fisso nel mondo, coerente per tutte le camere. Devi anche chiamare SetDecalTexture e SetDecalProjection per impostare il contenuto e la posa del proiettore.

ParametroTipoDescrizione
enableboolIndica se abilitare la proiezione della decal

Esempio di utilizzo:

m_manager.SetDecalEnabled(true);
m_manager.SetDecalTexture(decalTex);
m_manager.SetDecalProjection(projectorPos, projectorRot, 60f, 1.778f, 0.1f, 20f);

Note:

  • Quando è disabilitata, viene disabilitata solo la keyword _DECAL; la texture / i parametri in cache non vengono cancellati.

SetDecalTexture

// Valore restituito: void
public void SetDecalTexture(Texture2D tex)

Imposta la texture della decal. RGB è il colore e A è la maschera propria della decal, che viene moltiplicata con l'opacità globale e la sfumatura del bordo.

ParametroTipoDescrizione
texTexture2DTexture della decal

Esempio di utilizzo:

m_manager.SetDecalTexture(logoTex);

Note:

  • Passando null si cancella il riferimento globale alla texture.

SetDecalProjection

// Valore restituito: void
public void SetDecalProjection(Vector3 pos, Quaternion rot, float fov, float aspect, float near, float far)

Imposta la posa del proiettore della decal e i parametri prospettici. Il proiettore proietta lungo la sua direzione avanti (+Z) e i punti all'interno del frustum vengono coperti dalla decal.

ParametroTipoDescrizione
posVector3Posizione mondo del proiettore
rotQuaternionOrientamento del proiettore
fovfloatFOV verticale (gradi), limitato a [1, 179]
aspectfloatRapporto d'aspetto, minimo 1e-4
nearfloatPiano di ritaglio vicino, minimo 1e-3
farfloatPiano di ritaglio lontano, minimo near + 1e-3

Esempio di utilizzo:

m_manager.SetDecalProjection(new Vector3(0, 10, 0), Quaternion.Euler(90, 0, 0), 60f, 1.778f, 0.1f, 20f);

Note:

  • Se SetDecalOcclusion(true) è già abilitato, questo metodo inoltra in modo sincrono la nuova VP / vista alla Decal Depth Feature.

SetDecalOpacity

// Valore restituito: void
public void SetDecalOpacity(float opacity)

Imposta l'opacità complessiva della decal, inviandola immediatamente alla GPU e memorizzandola in cache per il riutilizzo alla prossima chiamata di SetDecalEnabled(true).

ParametroTipoDescrizione
opacityfloatOpacità complessiva della decal, intervallo [0, 1]

Esempio di utilizzo:

m_manager.SetDecalOpacity(0.8f);

Note:

  • Intervallo [0, 1]; i valori fuori intervallo vengono limitati automaticamente.

SetDecalEdgeFade

// Valore restituito: void
public void SetDecalEdgeFade(float edgeFade)

Imposta la larghezza della sfumatura del bordo della decal. 0 è un bordo netto, e maggiore è il valore, più morbida è la transizione del bordo.

ParametroTipoDescrizione
edgeFadefloatLarghezza della sfumatura del bordo, un rapporto in spazio UV, intervallo [0, 0.5)

Esempio di utilizzo:

m_manager.SetDecalEdgeFade(0.1f);

Note:

  • Intervallo [0, 0.5); i valori fuori intervallo vengono limitati automaticamente.

SetDecalOcclusion

// Valore restituito: void
public void SetDecalOcclusion(bool enable)

Attiva/disattiva l'occlusion culling della decal (basato sulla depth map del proiettore), che è ortogonale e attivato in modo indipendente rispetto alla funzionalità di ombra. SetDecalProjection dovrebbe essere stato chiamato per impostare il proiettore prima dell'abilitazione, altrimenti la depth map non ha una VP valida.

ParametroTipoDescrizione
enableboolIndica se abilitare l'occlusion culling della decal

Esempio di utilizzo:

m_manager.SetDecalOcclusion(true);

Note:

  • Supportato solo su URP (le chiamate sulla pipeline Built-in sono un no-op e stampano un log).
  • Richiede che la Decal Depth Feature sia registrata nell'URP Renderer Asset.
  • Dipende dai parametri di qualità configurati da SetDecalOcclusionSettings.

SetDecalOcclusionSettings

// Valore restituito: void
public void SetDecalOcclusionSettings(DecalOcclusionSettings settings)

Imposta tutti i parametri di qualità dell'occlusion culling della decal in una volta sola (vedi la struct di seguito e la tabella "Occlusion Culling e regolazione" per il significato dei quattro elementi).

ParametroTipoDescrizione
settingsDecalOcclusionSettingsParametri di qualità dell'occlusion culling

Esempio di utilizzo:

m_manager.SetDecalOcclusionSettings(DecalOcclusionSettings.Default);
m_manager.SetDecalOcclusionSettings(new DecalOcclusionSettings {
    opacityCutoff = 0.1f,
    depthBias = 0.05f,
    footprintMaxPx = 2,
    resolution = 1024
});

Note:

  • Può essere regolato in qualsiasi momento; i parametri vengono immediatamente inviati alla GPU e alla Decal Depth Feature.
  • La modifica di resolution attiva una ricostruzione della RT della depth map.

Strutture dati correlate

DecalOcclusionSettings

public struct DecalOcclusionSettings {
    public float opacityCutoff;   // [0,1] opacità minima affinché uno splat partecipi alla depth map, predefinito 0 (partecipano tutti)
    public float depthBias;       // rapporto di tolleranza di profondità relativa, predefinito 0.05
    public int   footprintMaxPx;  // limite del raggio dell'impronta quadrata (px), 0~16, predefinito 2
    public int   resolution;      // risoluzione della depth map (px, potenza di due, 256~4096), predefinito 1024

    public static DecalOcclusionSettings Default { get; } // cutoff=0, bias=0.05, footprint=2, resolution=1024
}

Usata da SetDecalOcclusionSettings(); il valore predefinito può essere ottenuto tramite DecalOcclusionSettings.Default.

CampoSignificatoPredefinito
opacityCutofffloat, [0,1], soglia di opacità; solo gli splat con opacità non inferiore a questo valore partecipano alla depth map0
depthBiasfloat, tolleranza di profondità relativa0.05
footprintMaxPxint, 0~16, limite del raggio dell'impronta quadrata (px)2
resolutionint, potenza di due 256~4096, risoluzione della depth map di occlusione1024

Note

  • Efficace solo su PC / Mac. Le chiamate alle interfacce relative alla decal sulle piattaforme mobile e VR vengono ignorate e stampano un avviso. Non è necessario eseguire controlli di piattaforma sul lato business, ma non aspettarti di vedere l'effetto su quelle piattaforme.
  • Si consiglia di impostare la decal dopo che la scena ha terminato il caricamento. La decal è uno stato di ombreggiatura globale; l'esempio inserisce SetDecalTexture / SetDecalProjection / SetDecalEnabled nel callback di completamento di Load per evitare di impostarle prima che la nuvola di punti sia pronta.
  • L'occlusion culling dipende da due prerequisiti. Primo, l'URP Renderer Asset ha registrato la Decal Depth Feature; secondo, SetDecalProjection è stato chiamato per impostare il proiettore. L'occlusione non ha effetto se manca uno dei due.
  • La proiezione statica ha quasi zero overhead aggiuntivo. La depth map di occlusione viene ricalcolata solo quando cambiano la posa del proiettore o la nuvola di punti; quando il proiettore è fermo, non c'è alcun calcolo aggiuntivo per fotogramma.