Kenar ve Köşe Yakalama Geliştirme Kılavuzu

LCC Unity SDK, 3DGS yüzeylerinde kenar ve köşe algılamayı ve yakalama önizlemesini destekler. Bu özellik; ölçüm, açıklama ekleme ve yerleştirme gibi hassas konumlandırma gerektiren etkileşim senaryolarında kullanılabilir. Aşağıda kenar/köşe algılama ve yakalamayı uygulamanın tüm adımları açıklanmıştır.

Not:

Yakalama (snap) özelliği (kenar/köşe algılama, yakalama önizlemesi ve yakalamalı ışın gönderme) yalnızca PC / Mac platformlarında desteklenir. İlgili API'lerin mobil / VR platformlarında çağrılması etki etmez ve uyarı çıktısı verir.

Adım 1: Sahneyi ve GameObject'leri Oluşturma

Unity'de yepyeni bir sahne oluşturun. Unity varsayılan olarak Main Camera ve Directional Light oluşturur.

Main Camera Ayarlama

Hierarchy penceresinde Main Camera nesnesini seçin ve özelliklerini Inspector penceresinde aşağıda gösterildiği gibi ayarlayın.

Main Camera özelliklerini ayarlama

LCCManager Oluşturma

Hierarchy penceresinde boş bir alana sağ tıklayın, açılan menüden Create Empty seçeneğini seçerek boş bir GameObject oluşturun, adını LCCManager yapın, Transform değerini normalleştirin ve Add Component ile bu nesneye LCCManager betiğini ekleyin.

LCCManager GameObject'ini oluşturun ve LCCManager betiğini ekleyin

LCCRenderer Oluşturma

Hierarchy penceresinde boş bir alana sağ tıklayın, Create Empty seçeneğini seçerek boş bir GameObject oluşturun, adını LCCRenderer yapın ve Transform değerlerini Rotation.x = -90 ve Scale.x = -1 olarak ayarlayın.

LCCRenderer oluşturma ve Transform ayarı (Rotation.x = -90, Scale.x = -1)

Not:

LCCRenderer GameObject'inin Transform ayarları (Rotation.x = -90, Scale.x = -1) onu LCC veri koordinat sistemiyle hizalar. Koordinat sistemi hizalaması hakkında ayrıntılar için Unity SDK'ya Giriş belgesindeki "LCC Veri Koordinat Sistemi" bölümüne bakın.

2. Adım: Render Feature Ekleme

1. Unity menü çubuğunda File → Project Settings seçeneğini seçin, soldan Graphics sekmesini açın ve geçerli Default Render Pipeline Asset değerini doğrulayın. Bu örnekte URP (Universal Render Pipeline Asset) kullanılmaktadır.

Graphics ayarlarında Default Render Pipeline Asset değerini doğrulayın

2. Bu Asset'e tıklayın, Project penceresinde ilgili asset dosyasını bulun ve ona bağlı Renderer öğesini belirleyin (bu örnekte URP_Renderer.asset).
3. İlgili Renderer asset dosyasını seçin, Inspector penceresinde Add Renderer Feature öğesine tıklayın ve Snap Frame Capture Feature özelliğini ekleyin.

Snap Frame Capture Feature'ı URP Renderer'a Ekleme

Adım 3: Yakalamayı Etkinleştirmek İçin Betik Yazma

Aşağıdaki kodla Snap.cs adında yeni bir C# betiği oluşturun:

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("Started ");
        m_renderer = m_manager.GetRender(this.transform);
        m_renderer.Load(m_FilePath, onProgress, onComplete);
    }

    private void onProgress(float _progress)
    {
        Debug.Log($"[LCCRenderer] file load progress: {_progress:P1}");
    }

    private void onComplete()
    {
        Debug.Log($"[LCCRenderer] file loaded");
        m_loaded = true;
        // Enable edge/corner detection and snap preview
        m_manager.SetSnapEnabled(true);
        m_manager.SetSnapPreviewEnabled(true);
    }

    private void Update()
    {
        if (!m_loaded) return;
        // Update the snap preview in real time based on the current mouse position
        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);
            }
        }
    }
}

Not:

Kenar/köşe algılama (SetSnapEnabled) ve yakalama önizlemesi (SetSnapPreviewEnabled), LCC sahnesinin yüklenmesi tamamlandıktan sonra etkinleştirilmelidir. Bu nedenle ikisi de onComplete geri çağrısında çağrılır. Yakalama önizlemesi ayrıca Update içinde UpdateSnapPreview ile sürekli güncellenmelidir.

Yukarıdaki örnek şu noktaları gösterir:

• Kenar ve köşe algılamayı etkinleştirme: m_manager.SetSnapEnabled(true)
• Yakalama önizlemesini etkinleştirme: m_manager.SetSnapPreviewEnabled(true)
• Yakalama önizlemesini gerçek zamanlı güncelleme: m_manager.UpdateSnapPreview(Input.mousePosition, m_camera)
• Yakalama noktasına ışın gönderme ve isabet noktasında küre oluşturma: m_manager.RaycastWithSnap(...); isabet olduğunda result.hitPos konumunda kırmızı bir küre oluşturulur

4. Adım: Betiği Ekleme ve Veri Yolunu Ayarlama

1. Snap.cs betiğini Hierarchy penceresindeki LCCRenderer GameObject'ine ekleyin.
2. Inspector penceresinde LCCManager GameObject'ini betiğin Manager özelliğine sürükleyin.
3. Betiğin File Path özelliğine LCC dosya yolunu girin.

Adım 5: Çalıştırma

Gerçek zamanlı algılanan kenarları, köşeleri ve yakalama hedefinin önizleme simgesini görmek için Game penceresinde Play düğmesine tıklayın. Fareyi hareket ettirdikçe önizleme simgesi en yakın yakalama hedefini gerçek zamanlı takip eder; sağ tıklama yakalama noktasında ışın gönderir ve kırmızı bir küre oluşturur.

Çalıştırma sonrasında gerçek zamanlı algılanan kenarlar, köşeler ve yakalama önizleme simgesi

Sık Sorulan Sorular: Uyumluluk Modunu Devre Dışı Bırakma

Unity Console penceresi hata bildiriyorsa ve yakalama önizleme simgesi görünmüyorsa uyumluluk modunu devre dışı bırakın: Edit → Project Settings → Graphics yoluyla ayarlar panelini açın, URP sekmesini seçin ve Render Graph → Compatibility Mode (Render Graph Disabled) seçeneğinin yanındaki onay kutusunu işaretlemeyin.

Render Graph uyumluluk modunu işaretlemeyin (Render Graph Disabled)

Temel Adımlar

Kenar/köşe algılama ve yakalamayı uygulamanın temel adımları:

1. Snap Frame Capture Feature özelliğinin URP Renderer'a eklendiğinden emin olun.
2. Kenar/köşe algılamanın (SetSnapEnabled(true)) ve yakalama önizlemesinin (SetSnapPreviewEnabled(true)) kodda LCC sahnesinin yüklenmesi tamamlandıktan sonra etkinleştirildiğinden emin olun.
3. Önizleme simgesini güncellemek için UpdateSnapPreview metodunun Update içinde gerçek zamanlı çağrıldığından emin olun.

Yakalama ile İlgili API'ler

LCC Unity SDK, yakalama ile ilgili aşağıdaki API'leri LCCManager üzerinden sunar. Bunlar yalnızca PC / Mac platformlarında desteklenir; mobil / VR platformlarında çağrılmaları etki etmez ve uyarı çıktısı verir. Hepsi LCC sahnesinin yüklenmesi tamamlandıktan sonra çağrılmalıdır.

SetSnapEnabled

// Return value: void
public void SetSnapEnabled(bool enable)

Yakalama özelliğini açar veya kapatır. Etkinleştirildiğinde RaycastWithSnap, yakalanacak yakındaki kenarları/köşeleri otomatik olarak arar.

Kullanım örneği:

m_manager.SetSnapEnabled(true);

Notlar:

• Varsayılan olarak kapalıdır.
• Yalnızca PC / Mac'te desteklenir; mobil / VR'de çağrılması etki etmez ve uyarı çıktısı verir.
• Etkinleştirildiğinde GPU kaynakları ayrılır (EdgeDetect / CornerDetect / SnapSearch).

SetSnapRadius

// Return value: void
public void SetSnapRadius(float pixels)

Yakalama arama yarıçapını ayarlar. En yakın kenar/köşe bu piksel aralığı içinde aranır.

Kullanım örneği:

m_manager.SetSnapRadius(30f);

Notlar:

• Varsayılan değer 20 pikseldir.
• Değer büyüdükçe arama aralığı genişler, ancak istenmeyen hedeflere yakalanabilir.
• Yalnızca PC / Mac'te desteklenir.

SetEdgeThreshold

// Return value: void
public void SetEdgeThreshold(float threshold)

Sobel kenar algılama eşiğini ayarlar. Değer küçüldükçe daha fazla kenar algılanır.

Kullanım örneği:

m_manager.SetEdgeThreshold(0.2f);

Notlar:

• Varsayılan değer 0,3'tür.
• Önerilen aralık: [0.1, 0.8].
• Çok küçük bir değer çok sayıda gürültülü kenar üretir.
• Yalnızca PC / Mac'te desteklenir.

SetSnapPreviewEnabled

// Return value: void
public void SetSnapPreviewEnabled(bool enable)

Yakalama önizleme özelliğini açar veya kapatır. Etkinleştirildiğinde, fare hareket ettikçe en yakın yakalama hedefi göstergesi gerçek zamanlı olarak görüntülenir.

Kullanım örneği:

m_manager.SetSnapPreviewEnabled(true);

Notlar:

• Önce SetSnapEnabled(true) çağrılmalıdır.
• Önizleme GPU kaynaklarını sürekli tüketir (her karede algılama yapılır).
• Yalnızca PC / Mac'te desteklenir.

UpdateSnapPreview

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

Yakalama önizleme durumunu günceller. Önizleme göstergesinin konumunu güncellemek için fare hareket ettikçe çağırın.

Kullanım örneği:

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

Notlar:

• Önce SetSnapPreviewEnabled(true) çağrılmalıdır.
• Update içinde sürekli çağrılması önerilir.
• Yalnızca PC / Mac'te desteklenir.

GetSnapPreviewState

// Return value: SnapPreviewState (screenPos is in screen coordinates)
public SnapPreviewState GetSnapPreviewState()

Geçerli yakalama önizleme durumunu alır. Bu durum, yakalama hedefinin olup olmadığını, hedef türünü, hedefin ekran konumunu ve fareye olan piksel mesafesini içerir.

Kullanım örneği:

var state = m_manager.GetSnapPreviewState();
if (state.hasTarget)
{
    // state.snapType: Corner / Edge
    // state.screenPos: snap target screen position
    // state.distanceToMouse: pixel distance
}

Notlar:

• Önce SetSnapPreviewEnabled(true) ve UpdateSnapPreview çağrılmalıdır.
• Hedef olmadığında default(SnapPreviewState) döndürür.
• screenPos bir ekran koordinatıdır, dünya koordinatı değildir; dünya koordinatına ihtiyacınız varsa HitResult.hitPos değerini almak için RaycastWithSnap kullanın.
• Yalnızca PC / Mac'te desteklenir.

RaycastWithSnap

// Return value: bool (true = hit)
public bool RaycastWithSnap(Vector2 screenPos, Camera cam, out HitResult result)

Yakalamalı ışın gönderme. Önce normal bir Raycast gerçekleştirir, ardından isabet noktasının yakınında yakalanacak kenarları/köşeleri arar.

Kullanım örneği:

if (m_manager.RaycastWithSnap(Input.mousePosition, m_camera, out HitResult hit))
{
    // hit.snapType: Corner / Edge / None
    // hit.hitPos: world position after snapping
    // hit.originalHitPos: original hit point before snapping
}

Notlar:

• Önce SetSnapEnabled(true) çağrılmalıdır.
• Yakalama önceliği: Köşe > Kenar > Yok.
• Bu giriş noktası ana iş parçacığını eşzamanlı olarak bloke eder (GPU geri okuma sonucunu bekler); yalnızca etkileşim olaylarında (tıklama gibi) çağrılması önerilir, her karede çağrılmamalıdır.
• Önizleme modunda (SetSnapPreviewEnabled(true)), zaten bir yakalama hedefi varsa önizleme önbelleği yeniden hesaplanmadan doğrudan kullanılır; aksi halde normal yakalama akışı uygulanır.
• Yalnızca PC / Mac'te desteklenir.

İlgili Veri Yapıları

SnapType

public enum SnapType { None, Edge, Corner }

Yakalama hedef türü: yok / kenar / köşe.

SnapPreviewState

public struct SnapPreviewState {
    public bool hasTarget;          // whether there is a snap target
    public SnapType snapType;       // None / Edge / Corner
    public Vector2 screenPos;       // snap target screen position (not world position)
    public float distanceToMouse;   // pixel distance to the mouse position
}

⚠️ screenPos bir ekran piksel koordinatıdır, dünya koordinatı değildir. Dünya koordinatına ihtiyacınız varsa HitResult.hitPos değerini almak için RaycastWithSnap kullanın.

HitResult

public struct HitResult {
    public bool isHit;             // whether hit
    public float distance;         // distance
    public Vector3 hitPos;         // hit point world position (field name is hitPos, not position)
    public Vector3 normal;         // hit normal
    public float hitAlpha;         // alpha of the hit ellipsoid
    public float dist2Origin;      // distance to the ray origin
    public float scale;            // ellipsoid scale
    public SnapType snapType;      // snap type (None / Edge / Corner)
    public Vector3 originalHitPos; // original hit point before snapping
}

⚠️ Alan adlandırma farkı: isabet noktasının dünya konumu alanı hitPos adını taşır (position değil); çağıranlar bu alana gerçek alan adıyla erişmelidir.