Renk Ayarı Geliştirme Kılavuzu

LCC Unity SDK, 3DGS sahnelerinde vurgulama, kırpma ve renk ayarı gibi düzenleme işlemlerini destekler. Bu kılavuz renk ayarı işlemlerini tanıtır: 2D izdüşüm dokuları, 3D geometri veya her ikisinin karışımıyla bir alan seçilir ve seçilen alanın parlaklığı, doygunluğu ve kontrastı ayarlanır. Normal seçim ve ters seçim desteklenir.

Not:

Mevcut renk ayarı özelliği yalnızca çalışma zamanı görüntüleme efektidir; özgün veri dosyasını hiçbir şekilde değiştirmez ve düzenleme sonucunu kaydetmeyi veya dışa aktarmayı desteklemez. Veriye renk ayarı yapmak, veriyi kırpmak ve kaydetmek istiyorsanız XGRIDS LCC Editor yazılım aracını kullanın.

Veriyi değiştirmek istemiyorsanız, işlemleri kaydedip bir sonraki veri yüklemesi bittikten sonra yeniden uygulayabilirsiniz (ayarları çalıştırabilirsiniz).

Ön Koşullar

SDK üzerinden bir sahnenin renklerini ayarlamak için aşağıdaki koşullar gerekir:

1. Veriyi 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. Renk ayarı gibi düzenleme işlemlerini yapmak için Load çağrısından önce SetEditorMode(true) ile düzenleme durumuna geçin. Bu yöntem yalnızca tüm veri yüklenmeden önce çağrılırsa etkili olur.
2. Renk ayarı işlemini veri yüklemesi bittikten sonra yapın. Renk ayarı arayüzü, sahne verisi tamamen yüklendikten sonra çağrılmalıdır.

1. Adım: Sahneyi Hazırlama

Sahnede renk ayarı için gereken GameObject nesnelerini hazırlayın:

• Main Camera: sahne kamerasıdır. 2B renk ayarı 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ış boş bir GameObject'tir (LCC veri koordinat sistemiyle hizalıdır). Daha sonra yazılacak Tone betiğini bağlamak için kullanılır.
• 3B seçim geometrisi (isteğe bağlı): 3B renk ayarı için yardımcı nesnelerdir. Örnekte bir Cube (Box1) hazırlanır. Bu nesneyi taşıyarak ve ölçekleyerek 3B renk ayarı seçiminin konumunu ve boyutunu belirlersiniz.

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.

Adım 2: Veri Yapısını Anlama

Renk ayarı, ToneMix veri yapısını kullanır. Bu yapı hem 2B doku seçimini hem de 3B geometri seçimini aynı anda tanımlayabilir ve renk ayarı parametrelerini taşır. Kullanılan enum ve struct yapıları aşağıdadır.

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

// Color adjustment selection
public struct ToneMix
{
    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)

    public float brightness;        // brightness, range [0, 3], default 1.0
    public float saturation;        // saturation, range [0, 3], default 1.0
    public float contrast;          // contrast, range [0, 3], default 1.0
    public int lutid;               // LUT table index (reserved), 0 means not used
}

Renk ayarı 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. Ters çevirme (invert) girdisi renk ayarı verisi taşımalıdır. Renk ayarını vurgulama/kırpmadan ayıran en önemli fark budur. Vurgulama/kırpmadaki ters çevirme yalnızca bir komuttur ve veriyle ilişkilendirilmesi gerekmez. Renk ayarındaki ters çevirme girdisinde ise mode = SelectMode.invert ayarının yanı sıra brightness, saturation ve contrast değerleri de ayarlanmalıdır. Böylece seçim dışındaki alan için renk ayarı efekti belirlenir.
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: Renk Ayarı API'lerini Anlama

Renk ayarıyla ilgili tüm arayüzleri LCCManager sağlar. Bunlar bir SetTone yöntemi ve bir çıkış yöntemidir.

SetTone

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

Seçili alana renk ayarı uygular. Parlaklık, doygunluk ve kontrast ayarlarını destekler. Aynı listede 2B doku girdileri ile 3B geometri girdileri birlikte kullanılabilir.

QuitToneMode

// Return value: void
public void QuitToneMode()

Renk ayarı modundan çıkar ve sahnenin özgün renklerini geri yükler.

İpucu:

Renk ayarı parametrelerini değiştirirken veya mevcut renk ayarını temizlerken önce QuitToneMode() çağrısını yapın, ardından yeni renk ayarını uygulayın.

Adım 4: 2D Maske Dokusu Özellikleri

2B renk ayarı, seçimi bir maske dokusu üzerinden tanımlar. Dörtgen, üçgen, fırça ve kement gibi çeşitli seçim yöntemlerini destekler. Dokuda ilgili pikselleri seçili değerle işaretlemeniz yeterlidir. 2B işlemlerde kamera kilitlenmeli ve doku sabit bir bakış noktasından işaretlenmelidir. Doku ve piksel değerleri için aşağıdaki 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ı:

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

Adım 5: Betiği Yazın

Tone.cs adlı yeni bir C# betiği oluşturun. Önce temel iskeleti tamamlayın: Start içinde düzenleme durumuna geçin ve veriyi yükleyin. Yükleme tamamlandıktan sonra, sonraki renk ayarı yöntemlerinin kontrol edeceği yükleme bayrağını ayarlayın.

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

public class Tone : MonoBehaviour
{
    public LCCManager m_manager;
    public string m_FilePath;
    public GameObject m_Box1;
    public Slider m_brightness;
    public Slider m_saturation;
    public Slider m_contrast;

    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;
    }

    // Color adjustment methods below
}

Not:

SetEditorMode(true) çağrısının etkili olması için Load öncesinde çağrılması gerekir. SetTone ise veri yüklemesi bittikten sonra (onLoadCallback geri çağrısı tetiklendikten sonra) çağrılmalıdır. m_brightness, m_saturation ve m_contrast kaydırıcıları, çalışma zamanında renk ayarı parametrelerini dinamik olarak değiştirmek için kullanılır ve gerektiğinde kullanılabilir.

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

1. Tone.cs betiğini LCCRenderer GameObject'ine bağlayın.
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 nesnesini betiğin Box1 özelliğine sürükleyin. Üç kaydırıcıyı da sırasıyla Brightness, Saturation ve Contrast özelliklerine sürükleyin. Böylece 3B renk ayarı ve çalışma zamanında parametre ayarı yapabilirsiniz.

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

Adım 7: Renk Ayarı İşlem Örnekleri

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

Normal Renk Ayarı

Bir R8 maske dokusu oluşturun. Rengi ayarlanacak pikselleri 240, diğerlerini 128 olarak işaretleyin. Ardından kamera matrisleriyle ToneMix oluşturun, brightness, saturation ve contrast değerlerini ayarlayın ve listeye ekleyin.

public void onTone()
{
    // 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<ToneMix> _tMixs = new List<ToneMix>();
    ToneMix _tmix01 = new ToneMix();
    _tmix01.editType = EditType.Edit2D;
    _tmix01.mv = m_camera.worldToCameraMatrix * this.transform.localToWorldMatrix;
    _tmix01.texture = _texture;
    _tmix01.mode = SelectMode.normal;
    _tmix01.mvp = GL.GetGPUProjectionMatrix(m_camera.projectionMatrix, true) * m_camera.worldToCameraMatrix * this.transform.localToWorldMatrix;
    _tmix01.brightness = 2.0f;
    _tmix01.saturation = 2.0f;
    _tmix01.contrast = 0.4f;
    _tMixs.Add(_tmix01);

    m_manager.SetTone(_tMixs);
}

Kod açıklaması: Ekranın üst yarısını seçen bir maske dokusu oluşturulur (ekran orijini sol alt köşedir). Seçili alana parlaklık 2.0, doygunluk 2.0 ve kontrast 0.4 değerleriyle renk ayarı uygulanır. Örnek efekt aşağıdadır.

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. Ayrıca brightness, saturation ve contrast değerlerini kaydırıcılar üzerinden dinamik olarak iletebilirsiniz.

Normal renk ayarı efekti

Ters Çevirmeli Renk Ayarı

Renk ayarındaki ters seçim, vurgulama ve kırpmadan farklıdır: ters seçim girdisi mode = SelectMode.invert ayarına ek olarak, seçimin dışında kalan alandaki renk ayarı etkisini belirtmek için renk ayarı verisi taşımalıdır (brightness, saturation, contrast). Yukarıdaki normal renk ayarına bir ters seçim girdisi eklemeniz yeterlidir.

public void onToneInvert()
{
    // 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<ToneMix> _tMixs = new List<ToneMix>();

    // Normal selection color adjustment
    ToneMix _tmix01 = new ToneMix();
    _tmix01.editType = EditType.Edit2D;
    _tmix01.mv = m_camera.worldToCameraMatrix * this.transform.localToWorldMatrix;
    _tmix01.texture = _texture;
    _tmix01.mode = SelectMode.normal;
    _tmix01.mvp = GL.GetGPUProjectionMatrix(m_camera.projectionMatrix, true) * m_camera.worldToCameraMatrix * this.transform.localToWorldMatrix;
    _tmix01.brightness = 2.0f;
    _tmix01.saturation = 2.0f;
    _tmix01.contrast = 0.4f;
    _tMixs.Add(_tmix01);

    // Invert: must carry color adjustment data (brightness/saturation/contrast), not a pure command
    ToneMix _tmix02 = new ToneMix();
    _tmix02.editType = EditType.Edit2D;
    _tmix02.mode = SelectMode.invert;
    _tmix02.brightness = 0.5f;
    _tmix02.saturation = 0.5f;
    _tmix02.contrast = 2.0f;
    _tMixs.Add(_tmix02);

    m_manager.SetTone(_tMixs);
}

Kod açıklaması: Normal renk ayarının üzerine bir ters çevirme girdisi eklenir ve seçimin dışındaki alana parlaklık 0.5, doygunluk 0.5 ve kontrast 2.0 değerleriyle renk ayarı uygulanır. Böylece seçimin içine ve dışına farklı renk ayarı parametreleri uygulanabilir. Örnek efekt aşağıdadır.

Ters çevirmeli renk ayarı efekti

Not:

Vurgulama ve kırpmadaki ters çevirme yalnızca bir komuttur. mode = SelectMode.invert olan bir girdi eklemek yeterlidir, başka veri gerekmez. Ancak renk ayarındaki ters çevirme girdisinde brightness, saturation ve contrast değerleri de mutlaka ayarlanmalıdır. Aksi halde ters çevrilen alan varsayılan değerleri (1.0) kullanır ve beklenen efekt elde edilmez.

Adım 8: Renk Ayarından Çıkma

Mevcut renk ayarını temizlemek ve sahnenin özgün renklerini geri yüklemek için QuitToneMode() çağrısını yapın.

public void onToneClear()
{
    m_manager.QuitToneMode();
}

Temel Adımlar

Bir 3DGS sahnesinin renk ayarını yapmanın temel adımları:

1. Düzenleme durumuna girmek için veriyi yüklemeden önce SetEditorMode(true) çağrısını yapın.
2. SetTone çağrısını veri yüklemesi bittikten sonra yapın (onLoadCallback geri çağrısı tetiklendikten sonra veya bir düğme/olay aracılığıyla).
3. Renk ayarlama efektini ToneMix içindeki brightness, saturation ve contrast değerleriyle (aralık [0, 3], varsayılan 1.0) kontrol edin ve renk ayarlama listesindeki 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. Renk ayarlama tersine çevirme (SelectMode.invert) brightness, saturation ve contrast verilerini mutlaka taşımalıdır. Vurgulama/kırpma tersine çevirmesinden temel fark budur.
6. Renk ayarlamayı temizlerken veya değiştirirken önce QuitToneMode() çağırın.