Ontwikkelgids voor rand- en hoeksnapping

De LCC Unity SDK ondersteunt rand- en hoekdetectie en snap-preview op 3DGS-oppervlakken, die kunnen worden gebruikt in interactiescenario's die nauwkeurige positionering vereisen, zoals meten, annoteren en plaatsen. Hieronder worden de volledige stappen beschreven voor het implementeren van rand-/hoekdetectie en snapping.

Opmerking:
De snapping-functie (rand-/hoekdetectie, snap-preview en raycasting met snapping) wordt alleen ondersteund op pc- / Mac-platformen. Het aanroepen van de gerelateerde API's op mobiele / VR-platformen heeft geen effect en geeft een waarschuwing.

Stap 1: De scène en GameObjects aanmaken

Maak een gloednieuwe scène aan in Unity. Unity maakt standaard Main Camera en Directional Light aan.

Main Camera instellen

Selecteer Main Camera in het Hiërarchie-venster en stel de eigenschappen in het Inspector-venster in zoals hieronder wordt weergegeven.

Stel de eigenschappen van Main Camera in

LCCManager aanmaken

Klik met de rechtermuisknop op een leeg gebied in het Hiërarchie-venster, selecteer Create Empty in het pop-upmenu om een leeg GameObject aan te maken, geef het de naam LCCManager, normaliseer de Transform en voeg het LCCManager-script eraan toe via Component toevoegen.

Maak het LCCManager-GameObject aan en voeg het LCCManager-script toe

LCCRenderer aanmaken

Klik met de rechtermuisknop op een leeg gebied in het Hiërarchie-venster, selecteer Create Empty om een leeg GameObject aan te maken, geef het de naam LCCRenderer en stel de Transform in op Rotation.x = -90 en Scale.x = -1.

Maak LCCRenderer aan en stel de Transform in (Rotation.x = -90, Scale.x = -1)

Opmerking:
De Transform-instellingen van het LCCRenderer-GameObject (Rotation.x = -90, Scale.x = -1) lijnen het uit met het coördinatensysteem van de LCC-gegevens. Zie "Coördinatensysteem van LCC-gegevens" in LCC Unity SDK Introductie voor meer informatie over de uitlijning van het coördinatensysteem.

Stap 2: Een Render Feature toevoegen

Selecteer in de Unity-menubalk Bestand → Projectinstellingen, kies links Grafisch en controleer de huidige Default Render Pipeline Asset. Dit voorbeeld gebruikt URP (Universal Render Pipeline Asset).

Controleer de Default Render Pipeline Asset in de grafische instellingen

Klik op dat Asset, zoek het bijbehorende assetbestand in het Project-venster en zoek de bijbehorende Renderer (in dit voorbeeld URP_Renderer.asset).
Selecteer dat Renderer-assetbestand, klik in het Inspector-venster op Add Renderer Feature en voeg de Snap Frame Capture Feature toe.

Voeg de Snap Frame Capture Feature toe aan de URP Renderer

Stap 3: Een script schrijven om snapping in te schakelen

Maak een nieuw C#-script aan met de naam Snap.cs met de volgende code:

using LCCCore;
using UnityEngine;

public class Snap : MonoBehaviour
{
    public LCCManager m_manager;
    public string m_FilePath;
    private LCCCore.Renderer m_renderer;
    private bool m_loaded = false;
    private Camera m_camera;

    void Start()
    {
        m_camera = Camera.main;
        m_manager.SetPlatformType(PlatformType.PC);
        Debug.Log("Gestart ");
        m_renderer = m_manager.GetRender(this.transform);
        m_renderer.Load(m_FilePath, onProgress, onComplete);
    }

    private void onProgress(float _progress)
    {
        Debug.Log($"[LCCRenderer] laadvoortgang van het bestand: {_progress:P1}");
    }

    private void onComplete()
    {
        Debug.Log($"[LCCRenderer] bestand geladen");
        m_loaded = true;
        // Schakel rand-/hoekdetectie en snap-preview in
        m_manager.SetSnapEnabled(true);
        m_manager.SetSnapPreviewEnabled(true);
    }

    private void Update()
    {
        if (!m_loaded) return;
        // Werk de snap-preview in realtime bij op basis van de huidige muispositie
        m_manager.UpdateSnapPreview(Input.mousePosition, m_camera);
        if (Input.GetMouseButtonDown(1))
        {
            m_manager.RaycastWithSnap(Input.mousePosition, m_camera, out HitResult result);
            if (result.isHit)
            {
                GameObject sphere = GameObject.CreatePrimitive(PrimitiveType.Sphere);
                sphere.transform.position = result.hitPos;
                sphere.GetComponent<UnityEngine.Renderer>().material.color = Color.red;
                sphere.transform.localScale = new Vector3(0.1f, 0.1f, 0.1f);
            }
        }
    }
}

Opmerking:
Rand-/hoekdetectie (SetSnapEnabled) en snap-preview (SetSnapPreviewEnabled) moeten worden ingeschakeld nadat de LCC-scène is geladen, dus beide worden aangeroepen in de onComplete-callback. Snap-preview moet bovendien continu worden bijgewerkt via UpdateSnapPreview in Update.

In het bovenstaande voorbeeld worden de volgende punten gedemonstreerd:

Rand- en hoekdetectie inschakelen: m_manager.SetSnapEnabled(true)
Snap-preview inschakelen: m_manager.SetSnapPreviewEnabled(true)
Snap-preview in realtime bijwerken: m_manager.UpdateSnapPreview(Input.mousePosition, m_camera)
Raycasten op het snap-punt en een bol aanmaken op het trefferpunt: m_manager.RaycastWithSnap(...); bij een treffer wordt een rode bol aangemaakt op result.hitPos

Stap 4: Het script toevoegen en het gegevenspad instellen

Voeg het Snap.cs-script toe aan het LCCRenderer-GameObject in het Hiërarchie-venster.
Sleep in het Inspector-venster het LCCManager-GameObject naar de eigenschap Manager van het script.
Vul het LCC-bestandspad in bij de eigenschap File Path van het script.

Stap 5: Uitvoeren

Klik op de knop Play in het Game-venster om de in realtime gedetecteerde randen en hoeken en het preview-pictogram van het snap-doel te zien. Terwijl je de muis beweegt, volgt het preview-pictogram het dichtstbijzijnde snap-doel in realtime; met een rechtermuisklik wordt er een raycast op het snap-punt uitgevoerd en wordt er een rode bol aangemaakt.

Randen, hoeken en het snap-preview-pictogram die na het uitvoeren in realtime worden gedetecteerd

Veelgestelde vraag: Compatibiliteitsmodus uitschakelen

Als het Console-venster van Unity fouten meldt en er geen snap-preview-pictogram verschijnt, schakel dan de compatibiliteitsmodus uit: open het instellingenpaneel via Bewerken → Projectinstellingen → Grafisch, selecteer het tabblad URP en vink niet het selectievakje aan na Render Graph → Compatibility Mode (Render Graph Disabled).

Vink de compatibiliteitsmodus van Render Graph niet aan (Render Graph Disabled)

Belangrijkste stappen

De belangrijkste stappen voor het implementeren van rand-/hoekdetectie en snapping:

Zorg ervoor dat de Snap Frame Capture Feature is toegevoegd aan de URP Renderer.
Zorg ervoor dat rand-/hoekdetectie (SetSnapEnabled(true)) en snap-preview (SetSnapPreviewEnabled(true)) in code zijn ingeschakeld nadat de LCC-scène is geladen.
Zorg ervoor dat UpdateSnapPreview in realtime in Update wordt aangeroepen om het preview-pictogram bij te werken.

Snap-gerelateerde API's

De LCC Unity SDK biedt via LCCManager de volgende snap-gerelateerde API's. Ze worden alleen ondersteund op pc- / Mac-platformen — aanroepen op mobiele / VR-platformen heeft geen effect en geeft een waarschuwing — en ze moeten allemaal worden aangeroepen nadat de LCC-scène is geladen.

SetSnapEnabled

// Retourwaarde: void
public void SetSnapEnabled(bool enable)

Schakelt de snapping-functie in of uit. Wanneer ingeschakeld, zoekt RaycastWithSnap automatisch naar nabijgelegen randen/hoeken om naar te snappen.

Parameter	Type	Beschrijving
`enable`	`bool`	Of snapping moet worden ingeschakeld

Gebruiksvoorbeeld:

m_manager.SetSnapEnabled(true);

Opmerkingen:

Standaard uitgeschakeld.
Alleen ondersteund op pc / Mac; aanroepen op mobiel / VR heeft geen effect en geeft een waarschuwing.
Wanneer ingeschakeld, worden GPU-resources toegewezen (EdgeDetect / CornerDetect / SnapSearch).

SetSnapRadius

// Retourwaarde: void
public void SetSnapRadius(float pixels)

Stelt de zoekstraal voor snapping in. Binnen dit pixelbereik wordt naar de dichtstbijzijnde rand/hoek gezocht.

Parameter	Type	Beschrijving
`pixels`	`float`	Zoekstraal voor snapping (pixels)

Gebruiksvoorbeeld:

m_manager.SetSnapRadius(30f);

Opmerkingen:

Standaard 20 pixels.
Hoe groter de waarde, hoe breder het zoekbereik, maar het kan naar onbedoelde doelen snappen.
Alleen ondersteund op pc / Mac.

SetEdgeThreshold

// Retourwaarde: void
public void SetEdgeThreshold(float threshold)

Stelt de Sobel-randdetectiedrempel in. Hoe kleiner de waarde, hoe meer randen er worden gedetecteerd.

Parameter	Type	Beschrijving
`threshold`	`float`	Randdetectiedrempel

Gebruiksvoorbeeld:

m_manager.SetEdgeThreshold(0.2f);

Opmerkingen:

Standaard 0.3.
Aanbevolen bereik [0.1, 0.8].
Een te kleine waarde produceert veel ruisige randen.
Alleen ondersteund op pc / Mac.

SetSnapPreviewEnabled

// Retourwaarde: void
public void SetSnapPreviewEnabled(bool enable)

Schakelt de snap-preview-functie in of uit. Wanneer ingeschakeld, wordt de indicator van het dichtstbijzijnde snap-doel in realtime weergegeven terwijl de muis beweegt.

Parameter	Type	Beschrijving
`enable`	`bool`	Of snap-preview moet worden ingeschakeld

Gebruiksvoorbeeld:

m_manager.SetSnapPreviewEnabled(true);

Opmerkingen:

Vereist dat SetSnapEnabled(true) eerst is aangeroepen.
Preview verbruikt continu GPU-resources (detectie elke frame).
Alleen ondersteund op pc / Mac.

UpdateSnapPreview

// Retourwaarde: void
public void UpdateSnapPreview(Vector2 mousePos, Camera cam)

Werkt de snap-preview-status bij. Roep het aan terwijl de muis beweegt om de positie van de preview-indicator bij te werken.

Parameter	Type	Beschrijving
`mousePos`	`Vector2`	Huidige schermcoördinaat van de muis
`cam`	`Camera`	Camera

Gebruiksvoorbeeld:

void Update()
{
    m_manager.UpdateSnapPreview(Input.mousePosition, Camera.main);
}

Opmerkingen:

Vereist dat SetSnapPreviewEnabled(true) eerst is aangeroepen.
Het wordt aanbevolen om het continu in Update aan te roepen.
Alleen ondersteund op pc / Mac.

GetSnapPreviewState

// Retourwaarde: SnapPreviewState (screenPos is in schermcoördinaten)
public SnapPreviewState GetSnapPreviewState()

Haalt de huidige snap-preview-status op, inclusief of er een snap-doel is, het doeltype, de schermpositie van het doel en de pixelafstand tot de muis.

Gebruiksvoorbeeld:

var state = m_manager.GetSnapPreviewState();
if (state.hasTarget)
{
    // state.snapType: Hoek / Rand
    // state.screenPos: schermpositie van het snap-doel
    // state.distanceToMouse: pixelafstand
}

Opmerkingen:

Vereist dat SetSnapPreviewEnabled(true) en UpdateSnapPreview eerst zijn aangeroepen.
Retourneert default(SnapPreviewState) wanneer er geen doel is.
screenPos is een schermcoördinaat, geen wereldcoördinaat; als je de wereldcoördinaat nodig hebt, gebruik dan RaycastWithSnap om HitResult.hitPos te krijgen.
Alleen ondersteund op pc / Mac.

RaycastWithSnap

// Retourwaarde: bool (true = treffer)
public bool RaycastWithSnap(Vector2 screenPos, Camera cam, out HitResult result)

Raycasting met snapping. Het voert eerst een normale Raycast uit en zoekt vervolgens naar randen/hoeken nabij het trefferpunt om naar te snappen.

Parameter	Type	Beschrijving
`screenPos`	`Vector2`	Schermcoördinaat
`cam`	`Camera`	Camera
`result`	`out HitResult`	Trefferresultaat (inclusief snapping-informatie)

Gebruiksvoorbeeld:

if (m_manager.RaycastWithSnap(Input.mousePosition, m_camera, out HitResult hit))
{
    // hit.snapType: Hoek / Rand / Geen
    // hit.hitPos: wereldpositie na snapping
    // hit.originalHitPos: oorspronkelijk trefferpunt vóór snapping
}

Opmerkingen:

Vereist dat SetSnapEnabled(true) eerst is aangeroepen.
Snap-prioriteit: Hoek > Rand > Geen.
Dit invoerpunt blokkeert de hoofdthread synchroon (wacht op het GPU-readbackresultaat); het wordt aanbevolen om het alleen aan te roepen bij interactiegebeurtenissen (zoals klikken), niet elke frame.
In de preview-modus (SetSnapPreviewEnabled(true)) wordt, als er al een snap-doel bestaat, de preview-cache rechtstreeks hergebruikt zonder herberekening; anders wordt de normale snap-flow gebruikt.
Alleen ondersteund op pc / Mac.

Gerelateerde gegevensstructuren

SnapType

public enum SnapType { None, Edge, Corner }

Snap-doeltype: geen / rand / hoek.

SnapPreviewState

public struct SnapPreviewState {
    public bool hasTarget;          // of er een snap-doel is
    public SnapType snapType;       // Geen / Rand / Hoek
    public Vector2 screenPos;       // schermpositie van het snap-doel (geen wereldpositie)
    public float distanceToMouse;   // pixelafstand tot de muispositie
}

⚠️ screenPos is een schermpixelcoördinaat, geen wereldcoördinaat. Gebruik RaycastWithSnap om HitResult.hitPos te krijgen als je de wereldcoördinaat nodig hebt.

HitResult

public struct HitResult {
    public bool isHit;             // of er een treffer is
    public float distance;         // afstand
    public Vector3 hitPos;         // wereldpositie van het trefferpunt (veldnaam is hitPos, niet position)
    public Vector3 normal;         // treffernormaal
    public float hitAlpha;         // alfa van de getroffen ellipsoïde
    public float dist2Origin;      // afstand tot de straaloorsprong
    public float scale;            // schaal van de ellipsoïde
    public SnapType snapType;      // snap-type (Geen / Rand / Hoek)
    public Vector3 originalHitPos; // oorspronkelijk trefferpunt vóór snapping
}

⚠️ Verschil in veldnaamgeving: het veld voor de wereldpositie van het trefferpunt is hitPos (niet position); aanroepers moeten dit benaderen met de daadwerkelijke veldnaam.