İçeriğe geç
TREN
Atlıhan Harita

LCC for Unity Kullanım Kılavuzu · Özellik Geliştirme Kılavuzu

Vurgulama Geliştirme Kılavuzu

Bölüm 15.12 / 17Kılavuz sürümü v2.3.0Türkçe

LCC Unity SDK, 3DGS sahnelerinde vurgulama ve kırpma gibi düzenleme işlemlerini destekler. Bu kılavuz vurgulamayla ilgili işlemleri tanıtır: 2B projeksiyon dokuları, 3B geometri veya ikisinin karışımı ile bir alan seçilir ve seçilen alan vurgulanır. Normal seçim ve ters seçim desteklenir.

Not:

Mevcut vurgulama özelliği yalnızca çalışma zamanında görüntülenen bir efekttir. Orijinal veri dosyasını hiçbir şekilde değiştirmez ve düzenleme sonucunu kaydetmeyi veya dışa aktarmayı desteklemez. Verilerde renk ayarı, kırpma yapmak ve bunları kaydetmek isterseniz XGRIDS LCC Editor yazılım aracını kullanın.

Verileri değiştirmek istemiyorsanız işlemleri kaydedebilir ve bir sonraki veri yüklemesi tamamlandıktan sonra yeniden oynatabilirsiniz.

Ön Koşullar

SDK ile bir sahneyi vurgulamak için aşağıdaki koşullar gerekir:

  1. Verileri yüklemeden önce düzenleme durumuna geçin. SDK varsayılan olarak gezinme durumundadır (View). Bu durum en iyi performansı sağlar ve normal gezinme için önerilir. Vurgulama gibi düzenleme işlemleri yapmak için Load çağrısından önce SetEditorMode(true) ile düzenleme durumuna geçin. Bu yöntem yalnızca tüm veriler yüklenmeden önce çağrılırsa etkili olur.
  2. Vurgulama işlemini veriler yüklendikten sonra yapın. Vurgulama arayüzü, sahne verileri tamamen yüklendikten sonra çağrılmalıdır.

1. Adım: Sahneyi Hazırlama

Vurgulama için gereken GameObject nesnelerini sahnede aşağıda gösterildiği gibi hazırlayın.

Vurgulama örneği için sahne hiyerarşisi yapısı

Vurgulama örneği için sahne hiyerarşisi yapısı

  • Main Camera: Sahne kamerasıdır. 2B vurgulama, bu kameranın görünüm ve projeksiyon matrislerini kullanır.
  • LCCManager: Normalleştirilmiş Transform değerine sahip boş bir GameObject nesnesidir ve LCCManager betiği eklenmiştir.
  • LCCRenderer: Transform değerleri Rotation.x = -90 ve Scale.x = -1 olarak ayarlanmış (LCC veri koordinat sistemiyle hizalı) boş bir GameObject. Daha sonra yazılacak Highlight betiğini eklemek için kullanılır.
  • 3D seçim geometrisi: 3D vurgulama için yardımcı nesnelerdir. Örnekte 3 Cube (Box1, Box2, Box3) ve 1 Sphere (Clipsphere) hazırlanır. Bu nesneleri taşıyarak ve ölçekleyerek vurgu seçiminin konumunu ve boyutunu kontrol edersiniz.

Not:

Görüntüleme kamerası, LCCManager ve LCCRenderer GameObject nesnelerine ilişkin ayarlar için PC Hızlı Başlangıç Kılavuzu ve Proje Ayarları Optimizasyon Kılavuzu bölümlerine bakın.

3D vurgulama için kullanılan seçim geometrisi

3D vurgulama için kullanılan seçim geometrisi (Box1 / Box2 / Box3 / Clipsphere)

Adım 2: Veri Yapılarını Anlayın

Vurgulama üç işlem yöntemi içerir: 2D, 3D ve 2D/3D karma. Kullanılan enum ve struct yapıları şöyledir.

public enum SelectMode    { normal, invert, clip }  // normal selection, invert, real-time clipping
public enum OperationMode { normal, erase }         // normal selection, erase selection
public enum ShapeType     { box, sphere }           // 3D Box selection, 3D Sphere selection
public enum EditType      { Edit2D, Edit3D }        // 2D edit, 3D edit

// 2D texture selection
public struct Data2D
{
    public Texture2D texture;   // 2D mask texture
    public Matrix4x4 mv;        // camera view matrix
    public Matrix4x4 mvp;       // camera view projection matrix
    public SelectMode mode;     // selection mode
}

// 3D geometry selection
public struct Data3D
{
    public ShapeType type;          // geometry type (box / sphere)
    public Matrix4x4 invMat;        // geometry's world-to-local (inverse) matrix
    public OperationMode operation; // operation type (normal union / erase difference)
    public SelectMode mode;         // selection mode
}

// 2D / 3D mixed selection
public struct DataMix
{
    public EditType editType;       // edit type (required; determines whether 2D or 3D fields are used)
    public Texture2D texture;       // 2D mask texture (used by Edit2D)
    public Matrix4x4 mv;            // camera view matrix (used by Edit2D)
    public Matrix4x4 mvp;           // camera view projection matrix (used by Edit2D)
    public ShapeType type;          // geometry type (used by Edit3D)
    public Matrix4x4 invMat;        // geometry inverse matrix (used by Edit3D)
    public OperationMode operation; // operation type (used by Edit3D)
    public SelectMode mode;         // selection mode (required)
}

Seçim listesiyle ilgili dikkat edilmesi gereken üç nokta vardır:

  1. Liste sıralıdır. 2D ya da 3D olsun, listedeki girdiler sırayla uygulanır. Ekleme sırasının beklentinizle uyuştuğundan emin olun.
  2. Invert bir işlem komutudur ve belirli bir seçim verisiyle ilişkilendirilmesi gerekmez. Geçerli seçili alanı ters çevirmek için listeye mode = SelectMode.invert olan bir girdi eklemeniz yeterlidir.
  3. Tek bir listedeki en fazla girdi sayısı 255'tir. Bu sınır aşılırsa bir hata kodu döndürülür.

Adım 3: Vurgulama API'lerini Anlayın

Vurgulamayla ilgili tüm arayüzler LCCManager tarafından sağlanır. Bunlar üç SetHighlight aşırı yüklemesini ve bir çıkış yöntemini içerir.

SetHighlight (2D doku vurgulama)

// Return value: int
// 0: success
// 1: list is null or has 0 elements
// 2: list elements exceed the maximum of 255
public int SetHighlight(List<Data2D> _2Ds)

Sahneyi 2D izdüşüm doku maskesiyle vurgular. Vurgulanan alanın dışında kalan bölüm karartılır.

SetHighlight (3D geometri vurgulama)

// Return value: int
// 0: success
// 1: list is null or has 0 elements
// 2: list elements exceed the maximum of 255
// 3: the number of selection geometry boxes is 0
public int SetHighlight(List<Data3D> _3Ds)

Vurgu alanını 3D geometriyle (dikdörtgen prizma, küp, küre) tanımlar. Birleşim ve fark kombinasyonlarını destekler. operation == OperationMode.normal olan en az bir geometri gereklidir.

SetHighlight (karma mod vurgulama)

// Return value: int
// 0: success
// 1: list is null or has 0 elements
// 2: list elements exceed the maximum of 255
public int SetHighlight(List<DataMix> _Mix)

Vurgu alanını aynı anda 2D dokular ve 3D geometriyle tanımlar. Her girdinin 2D mi 3D mi işleneceği editType ile belirlenir.

QuitHighlightMode

// Return value: void
public void QuitHighlightMode()

Vurgulama modundan çıkar ve sahnenin normal görünümünü geri yükler.

İpucu:

Üç SetHighlight aşırı yüklemesi birbirini dışlar. Vurgulama yöntemini değiştirirken veya mevcut vurguyu temizlerken önce QuitHighlightMode() çağrısını yapın, ardından yeni vurguyu ayarlayın.

Adım 4: 2D Maske Dokusu Özellikleri

2D vurgulama, seçimi bir maske dokusuyla tanımlar. Dörtgen, üçgen, fırça ve kement gibi çeşitli seçim yöntemlerini destekler. Dokudaki ilgili pikselleri seçili değerle işaretlemeniz yeterlidir. 2D işlemleri kullanırken kamera kilitlenmeli ve doku sabit bir bakış noktasından işaretlenmelidir. Doku ve piksel değerleri için şu kurallar geçerlidir:

  • Doku 1024 × 1024 boyutunda sabittir; R8 tek kanal, Mipmap yok, nokta filtreleme (FilterMode.Point) ve sınırlı örnekleme (TextureWrapMode.Clamp) kullanılır.
  • Piksel değeri kuralları:
Piksel değeriAnlamı
128Varsayılan (seçili değil)
240Seçili
180Seçimi kaldır (daha önce seçilen alanı sil)
0Kırpma

Vurgulama senaryosunda genellikle yalnızca 128 (varsayılan) ve 240 (seçili) değerleri kullanılır.

Adım 5: Betiği Yazın

Highlight.cs adında yeni bir C# betiği oluşturun. Önce temel iskeleti tamamlayın: Start içinde düzenleme durumuna girin ve veriyi yükleyin. Yükleme tamamlandığında, sonraki vurgulama yöntemlerinin kontrol edeceği yükleme bayrağını ayarlayın.

using LCCCore;
using System.Collections.Generic;
using UnityEngine;

public class Highlight : MonoBehaviour
{
    public LCCManager m_manager;
    public string m_FilePath;
    public GameObject m_Box1;
    public GameObject m_Box2;
    public GameObject m_Box3;
    public GameObject m_Clipsphere;

    private LCCCore.Renderer m_renderer;
    private Camera m_camera;
    private bool m_isLoaded = false;

    void Start()
    {
        m_camera = Camera.main;
        m_manager.SetPlatformType(PlatformType.PC);

        // Enter edit mode; must be called before Load
        m_manager.SetEditorMode(true);

        m_renderer = m_manager.GetRender(this.transform);
        if (m_renderer == null)
            Debug.LogError("GetRender failed, check if the manager is set correctly and the file path is valid.");

        m_renderer.Load(m_FilePath, onLoadProgress, onLoadCallback);
    }

    private void onLoadProgress(float value)
    {
        Debug.Log($"loading progress: {value}");
    }

    private void onLoadCallback()
    {
        Debug.Log("data loaded !!!");
        m_isLoaded = true;
    }

    // 2D / 3D / mixed highlight methods below
}

Not:

SetEditorMode(true) çağrısı etkili olması için Load öncesinde yapılmalıdır. SetHighlight ise veri yüklemesi bittikten sonra (onLoadCallback geri çağrısı tetiklendikten sonra) çağrılmalıdır.

Adım 6: Betiği Ekleyin ve Özellikleri Ayarlayın

  1. Highlight.cs betiğini LCCRenderer GameObject nesnesine ekleyin.
  2. Inspector penceresinde LCCManager GameObject'ini betiğin Manager özelliğine sürükleyin.
  3. LCC dosya yolunu File Path özelliğine girin.
  4. Sahnedeki Box1, Box2, Box3 ve Clipsphere nesnelerini betiğin ilgili özelliklerine sırasıyla sürükleyin.
Inspector'da Highlight betiği özelliklerini ayarlayın

Inspector'da Highlight betiği özelliklerini ayarlayın

Adım 7: Vurgulama İşlemi Örnekleri

Aşağıdaki yöntemleri Highlight sınıfına ekleyin. Uygulamayı çalıştırıp veri yüklemesi bittikten sonra ilgili yöntemi çağırın.

2D Doku Vurgulama

İki adet R8 maske dokusu oluşturun. Vurgulanacak pikselleri 240, diğerlerini 128 olarak işaretleyin. Ardından kamera matrisleriyle Data2D oluşturup listeye ekleyin.

public void on2DHighlight()
{
    // Texture size is fixed at 1024*1024; keep other properties the same as the example
    Texture2D _texture = new Texture2D(1024, 1024, TextureFormat.R8, false);
    _texture.filterMode = FilterMode.Point;
    _texture.wrapMode = TextureWrapMode.Clamp;

    int _count = 1024 * 1024;
    int _half = _count / 2;
    byte[] _values = new byte[_count];
    for (int i = 0; i < _count; i++)
    {
        if (i < _half)
            _values[i] = 240;    // 240 means selected, 128 means default, 0 means clipping
        else
            _values[i] = 128;
    }
    _texture.SetPixelData(_values, 0);

    Texture2D _texture2 = new Texture2D(1024, 1024, TextureFormat.R8, false);
    _texture2.filterMode = FilterMode.Point;
    _texture2.wrapMode = TextureWrapMode.Clamp;
    byte[] _values2 = new byte[_count];
    for (int i = 0; i < _count; i++)
    {
        if (i > _count * 0.75 && i < _count * 0.9)
            _values2[i] = 240;
        else
            _values2[i] = 128;
    }
    _texture2.SetPixelData(_values2, 0);

    List<Data2D> _2Ds = new List<Data2D>();
    Data2D _2d01 = new Data2D();
    _2d01.mv = m_camera.worldToCameraMatrix;
    _2d01.texture = _texture;
    _2d01.mode = SelectMode.normal;
    _2d01.mvp = GL.GetGPUProjectionMatrix(m_camera.projectionMatrix, true) * m_camera.worldToCameraMatrix;
    _2Ds.Add(_2d01);

    Data2D _2d02 = new Data2D();
    _2d02.mv = m_camera.worldToCameraMatrix;
    _2d02.texture = _texture2;
    _2d02.mode = SelectMode.normal;
    _2d02.mvp = GL.GetGPUProjectionMatrix(m_camera.projectionMatrix, true) * m_camera.worldToCameraMatrix;
    _2Ds.Add(_2d02);

    m_manager.SetHighlight(_2Ds);
}

Kod açıklaması: İki maske dokusu oluşturulur. Birinci maske ekranın alt yarısını seçer (ekran orijini sol alt köşedir). İkinci maske ekranın üst yarısındaki 0,75 ile 0,9 arasındaki bölgeyi seçer. Örnek sonuç aşağıdaki gibidir.

Gerçek kullanımda maske üzerinde ilgili konumları seçmek için dikdörtgen, üçgen, fırça ve kement gibi çeşitli seçim araçlarını kullanabilirsiniz.

2D doku vurgulama sonucu

2D doku vurgulama sonucu

3D Geometri Vurgulama

Geometrinin worldToLocalMatrix değerini seçim ters matrisi olarak kullanın. operation üzerinden birleşim (normal) ve farkı (erase) birleştirin. Ters seçimi ise mode = SelectMode.invert olan bir girdiyle uygulayın.

public void on3DHighlight()
{
    List<Data3D> _3Ds = new List<Data3D>();
    var _mat1 = m_Box1.transform.worldToLocalMatrix;
    var _mat2 = m_Box2.transform.worldToLocalMatrix;
    var _mat3 = m_Box3.transform.worldToLocalMatrix;
    var _mat4 = m_Clipsphere.transform.worldToLocalMatrix;

    // Box selection
    Data3D _3d01 = new Data3D();
    _3d01.type = ShapeType.box;
    _3d01.operation = OperationMode.normal;
    _3d01.mode = SelectMode.normal;
    _3d01.invMat = _mat1;
    _3Ds.Add(_3d01);

    Data3D _3d02 = new Data3D();
    _3d02.type = ShapeType.box;
    _3d02.operation = OperationMode.normal;
    _3d02.mode = SelectMode.normal;
    _3d02.invMat = _mat2;
    _3Ds.Add(_3d02);

    // Sphere selection
    Data3D _3d04 = new Data3D();
    _3d04.type = ShapeType.sphere;
    _3d04.operation = OperationMode.normal;
    _3d04.mode = SelectMode.normal;
    _3d04.invMat = _mat4;
    _3Ds.Add(_3d04);

    // Erase Box/Sphere (difference)
    Data3D _3d03 = new Data3D();
    _3d03.type = ShapeType.box;
    _3d03.operation = OperationMode.erase;
    _3d03.mode = SelectMode.normal;
    _3d03.invMat = _mat3;
    _3Ds.Add(_3d03);

    // Invert
    //Data3D _3d05 = new Data3D();
    //_3d05.mode = SelectMode.invert;
    //_3Ds.Add(_3d05);

    m_manager.SetHighlight(_3Ds);
}

Kod açıklaması: 4 geometri kullanılır. Box1, Box2 ve Sphere normal seçimdir; Box3 ise silme seçimidir, yani daha önce seçilen alanı siler. Ters çevirmeyle ilgili kod yorum satırı yapıldığında örnek sonuç şöyledir:

3D geometri vurgulama sonucu

3D geometri vurgulama sonucu

Ters çevirmenin etkili olması için ters çevirme kodundaki yorum işaretlerini kaldırın. Örnek sonuç aşağıdaki gibidir. Invert, daha önce seçilen alanı tersine çevirir. Bir komuttur ve işlem verisiyle ilişkilendirilmesi gerekmez.

Özellikle listenin sıralı olduğuna dikkat edin. Farklı işlem adımları farklı nihai sonuçlar üretir.

3D geometri + ters çevirme vurgulama sonucu

3D geometri + ters çevirme vurgulama sonucu

Karma Mod Vurgulama

2D doku ve 3D geometri girdilerini aynı listede birleştirin. Her girdi işlenme yöntemini editType ile belirtir.

public void onMixHighlight()
{
    // --- 2D selection preparation ---
    // Texture size is fixed at 1024*1024; keep other properties the same as the example
    Texture2D _texture = new Texture2D(1024, 1024, TextureFormat.R8, false);
    _texture.filterMode = FilterMode.Point;
    _texture.wrapMode = TextureWrapMode.Clamp;

    int _count = 1024 * 1024;
    int _half = _count / 2;
    byte[] _values = new byte[_count];
    for (int i = 0; i < _count; i++)
    {
        if (i < _half)
            _values[i] = 128;    // 128 means default, 240 means selected, 0 means clipping
        else
            _values[i] = 240;
    }
    _texture.SetPixelData(_values, 0);

    List<DataMix> _Mixs = new List<DataMix>();
    DataMix _mix01 = new DataMix();
    _mix01.editType = EditType.Edit2D;
    _mix01.mv = m_camera.worldToCameraMatrix;
    _mix01.texture = _texture;
    _mix01.mode = SelectMode.normal;
    _mix01.mvp = GL.GetGPUProjectionMatrix(m_camera.projectionMatrix, true) * m_camera.worldToCameraMatrix;
    _Mixs.Add(_mix01);

    // --- 3D selection preparation ---
    var _mat1 = m_Box1.transform.worldToLocalMatrix;
    var _mat2 = m_Box2.transform.worldToLocalMatrix;
    var _mat3 = m_Box3.transform.worldToLocalMatrix;
    var _mat4 = m_Clipsphere.transform.worldToLocalMatrix;

    // Box selection
    DataMix _mix02 = new DataMix();
    _mix02.editType = EditType.Edit3D;
    _mix02.type = ShapeType.box;
    _mix02.operation = OperationMode.normal;
    _mix02.mode = SelectMode.normal;
    _mix02.invMat = _mat1;
    _Mixs.Add(_mix02);

    DataMix _mix03 = new DataMix();
    _mix03.editType = EditType.Edit3D;
    _mix03.type = ShapeType.box;
    _mix03.operation = OperationMode.normal;
    _mix03.mode = SelectMode.normal;
    _mix03.invMat = _mat2;
    _Mixs.Add(_mix03);

    // Sphere selection
    DataMix _mix04 = new DataMix();
    _mix04.editType = EditType.Edit3D;
    _mix04.type = ShapeType.sphere;
    _mix04.operation = OperationMode.normal;
    _mix04.mode = SelectMode.normal;
    _mix04.invMat = _mat4;
    _Mixs.Add(_mix04);

    // Erase Box/Sphere (difference)
    DataMix _mix05 = new DataMix();
    _mix05.editType = EditType.Edit3D;
    _mix05.type = ShapeType.box;
    _mix05.operation = OperationMode.erase;
    _mix05.mode = SelectMode.normal;
    _mix05.invMat = _mat3;
    _Mixs.Add(_mix05);

    // Invert (enable as needed)
    DataMix _mix06 = new DataMix();
    _mix06.editType = EditType.Edit3D;
    _mix06.type = ShapeType.box;
    _mix06.mode = SelectMode.invert;
    //_Mixs.Add(_mix06);

    m_manager.SetHighlight(_Mixs);
}

Kod açıklaması: 4 geometri ve 1 adet 2D doku kullanılır. Böylece 2D ve 3D karma işleme yapılabilir. Örnek sonuç şöyledir:

Karma mod vurgulama sonucu

Karma mod vurgulama sonucu

Adım 8: Vurgulamadan Çıkın

Mevcut vurguyu temizlemek ve sahnenin normal görünümünü geri yüklemek için QuitHighlightMode() çağrısını yapın.

public void onClearHighlight()
{
    m_manager.QuitHighlightMode();
}

Temel Adımlar

Bir 3DGS sahnesini vurgulamanın temel adımları:

  1. Düzenleme durumuna girmek için veriyi yüklemeden önce SetEditorMode(true) çağrısını yapın.
  2. SetHighlight çağrısını veri yüklemesi bittikten sonra yapın (onLoadCallback geri çağrısı tetiklendikten sonra ya da bir düğme/olay aracılığıyla).
  3. İhtiyacınıza göre 2D doku, 3D geometri veya karma modu seçin ve seçim listesinin ekleme sırasının beklentinizle uyuştuğundan emin olun.
  4. 2D maske dokusu 1024 × 1024 olarak sabittir, R8 tek kanallıdır; piksel değerlerini kurala göre doldurun (128 varsayılan, 240 seçili).
  5. Vurguları temizlerken veya değiştirirken önce QuitHighlightMode() çağırın.

Bu bölüm XGRIDS'in resmî kullanım kılavuzundan Türkçeye çevrildi; ekran görüntüleri ve arayüz adları özgün haliyle İngilizcedir. İngilizce aslı (yeni sekmede açılır) · Güncelleme:

XGRIDS Türkiye

Kurulumda ve Sahada Yanınızdayız

Atlıhan Harita; cihaz kurulumu, firmware güncellemesi, yazılım kullanımı ve saha uygulamalarında eğitim ve teknik destek verir. Sorunuzu iletin, uzmanımız size dönsün.

Uzmanla Görüşün Demo Talep Et
+90 216 546 0804