Przewodnik korekcji kolorów

LCC Unity SDK obsługuje operacje edycji, takie jak podświetlanie, przycinanie i korekcja kolorów, na scenach 3DGS. Ten przewodnik przedstawia operacje korekcji kolorów: zaznaczanie obszaru za pomocą rzutowanych tekstur 2D, geometrii 3D lub mieszanki obu oraz dostosowywanie jasności, nasycenia i kontrastu zaznaczonego obszaru, z obsługą zaznaczenia normalnego i zaznaczenia odwróconego.

Uwaga:
Obecna funkcja korekcji kolorów jest tylko efektem wyświetlania w czasie działania; w żaden sposób nie modyfikuje oryginalnego pliku danych i nie obsługuje zapisywania ani eksportowania wyniku edycji. Jeśli potrzebujesz korekcji kolorów, przycinania i zapisywania danych, użyj narzędzia XGRIDS LCC Editor.
Jeśli nie chcesz modyfikować danych, możesz również zarejestrować operacje i odtworzyć je (wykonać ustawienia) po ponownym zakończeniu ładowania danych.

Wymagania wstępne

Korekcja kolorów sceny przez SDK wymaga następujących warunków:

Wejdź w stan edycji przed załadowaniem danych. SDK jest domyślnie w stanie przeglądania (View), który zapewnia najlepszą wydajność i jest zalecany do normalnego przeglądania. Aby wykonywać operacje edycji, takie jak korekcja kolorów, przełącz się w stan edycji przez SetEditorMode(true) przed wywołaniem Load. Ta metoda działa tylko wtedy, gdy zostanie wywołana przed załadowaniem wszystkich danych.
Wykonaj operację korekcji kolorów po zakończeniu ładowania danych. Interfejs korekcji kolorów musi być wywołany po pełnym załadowaniu danych sceny.

Krok 1: Skonfiguruj scenę

Przygotuj GameObjects potrzebne do korekcji kolorów w scenie:

Kamera główna: kamera sceny; korekcja kolorów 2D używa jej macierzy widoku i rzutowania.
LCCManager: pusty GameObject ze znormalizowanym Transform, z dodanym skryptem LCCManager.
LCCRenderer: pusty GameObject z Transform ustawionym na Rotation.x = -90, Scale.x = -1 (wyrównany z układem współrzędnych danych LCC), używany do dołączenia skryptu Tone napisanego później.
Geometria zaznaczenia 3D (opcjonalna): obiekty pomocnicze do korekcji kolorów 3D. Przykład przygotowuje jeden Sześcian (Box1); przesuwanie i skalowanie go steruje pozycją i rozmiarem zaznaczenia korekcji kolorów 3D.

Uwaga:
Ustawienia związane z kamerą renderującą, LCCManager i GameObject LCCRenderer znajdziesz w odpowiednich sekcjach Przewodnik szybkiego startu dla PC i Przewodnik optymalizacji ustawień projektu.

Krok 2: Poznaj strukturę danych

Korekcja kolorów używa struktury danych ToneMix, która może opisywać jednocześnie zaznaczenie teksturą 2D i zaznaczenie geometrią 3D oraz przenosi parametry korekcji kolorów. Używane typy wyliczeniowe i struktury są następujące.

public enum SelectMode    { normal, invert, clip }  // zaznaczenie normalne, odwrócenie, przycinanie w czasie rzeczywistym
public enum OperationMode { normal, erase }         // zaznaczenie normalne, wymazywanie zaznaczenia
public enum ShapeType     { box, sphere }           // zaznaczenie 3D Box, zaznaczenie 3D Sphere
public enum EditType      { Edit2D, Edit3D }        // edycja 2D, edycja 3D

// Zaznaczenie korekcji kolorów
public struct ToneMix
{
    public EditType editType;       // typ edycji (wymagany; określa, czy używane są pola 2D czy 3D)
    public Texture2D texture;       // tekstura maski 2D (używana przez Edit2D)
    public Matrix4x4 mv;            // macierz widoku kamery (używana przez Edit2D)
    public Matrix4x4 mvp;           // macierz widokowo-rzutowa kamery (używana przez Edit2D)
    public ShapeType type;          // typ geometrii (używany przez Edit3D)
    public Matrix4x4 invMat;        // macierz odwrotna geometrii (używana przez Edit3D)
    public OperationMode operation; // typ operacji (używany przez Edit3D)
    public SelectMode mode;         // tryb zaznaczenia (wymagany)

    public float brightness;        // jasność, zakres [0, 3], domyślnie 1.0
    public float saturation;        // nasycenie, zakres [0, 3], domyślnie 1.0
    public float contrast;          // kontrast, zakres [0, 3], domyślnie 1.0
    public int lutid;               // indeks tabeli LUT (zarezerwowany), 0 oznacza nieużywany
}

Istnieją trzy punkty do odnotowania na temat listy korekcji kolorów:

Lista jest uporządkowana. Niezależnie od tego, czy 2D czy 3D, wpisy na liście działają w kolejności; upewnij się, że kolejność dodawania odpowiada Twoim oczekiwaniom.
Odwrócenie musi przenosić dane korekcji kolorów. To najbardziej krytyczna różnica między korekcją kolorów a podświetlaniem/przycinaniem — odwrócenie podświetlania/przycinania jest czystym poleceniem i nie musi być powiązane z danymi; ale wpis odwrócenia korekcji kolorów, oprócz mode = SelectMode.invert, musi również ustawić brightness, saturation i contrast, aby określić efekt korekcji kolorów dla obszaru poza zaznaczeniem.
Maksymalna liczba wpisów na jednej liście to 255. Przekroczenie jej zwraca kod błędu.

Krok 3: Poznaj API korekcji kolorów

Wszystkie interfejsy związane z korekcją kolorów są udostępniane przez LCCManager, w tym jedna metoda SetTone i jedna metoda wyjścia.

SetTone

// Wartość zwracana: int
// 0: sukces
// 1: lista jest null lub ma 0 elementów
// 2: elementy listy przekraczają maksimum 255
public int SetTone(List<ToneMix> _Mix)

Wykonuje korekcję kolorów na zaznaczonym obszarze, obsługując regulację jasności, nasycenia i kontrastu. Wpisy tekstury 2D i wpisy geometrii 3D mogą być mieszane na tej samej liście.

QuitToneMode

// Wartość zwracana: void
public void QuitToneMode()

Wychodzi z trybu korekcji kolorów i przywraca oryginalne kolory sceny.

Wskazówka:
Przy przełączaniu parametrów korekcji kolorów lub czyszczeniu bieżącej korekcji kolorów najpierw wywołaj QuitToneMode(), a następnie ustaw nową korekcję kolorów.

Krok 4: Specyfikacja tekstury maski 2D

Korekcja kolorów 2D opisuje zaznaczenie przez teksturę maski, obsługując różne metody zaznaczania, takie jak czworokąty, trójkąty, pędzle i lassa — po prostu oznacz odpowiednie piksele w teksturze wartością zaznaczenia. Przy operacjach 2D kamera powinna być zablokowana, a tekstura oznaczana ze stałego punktu widzenia. Tekstura i wartości pikseli mają następujące konwencje:

Tekstura jest stała 1024 × 1024, R8 jednokanałowa, bez Mipmap, filtrowanie punktowe (FilterMode.Point) i próbkowanie z przycinaniem (TextureWrapMode.Clamp).
Konwencje wartości pikseli:

Wartość piksela	Znaczenie
`128`	Domyślna (niezaznaczone)
`240`	Zaznaczone
`180`	Odznacz (wymaż już zaznaczony obszar)
`0`	Przycinanie

W scenariuszu korekcji kolorów zwykle używane są tylko dwie wartości: 128 (domyślna) i 240 (zaznaczone).

Krok 5: Napisz skrypt

Utwórz nowy skrypt C# o nazwie Tone.cs. Najpierw ukończ podstawowy szkielet: w Start wejdź w stan edycji i załaduj dane; po zakończeniu ładowania ustaw flagę ładowania do sprawdzenia przez kolejne metody korekcji kolorów.

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

        // Wejdź w tryb edycji; musi być wywołane przed Load
        m_manager.SetEditorMode(true);

        m_renderer = m_manager.GetRender(this.transform);
        if (m_renderer == null)
            Debug.LogError("GetRender nie powiódł się; sprawdź, czy menedżer jest ustawiony poprawnie i czy ścieżka pliku jest prawidłowa.");

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

    private void onLoadProgress(float value)
    {
        Debug.Log($"postęp ładowania: {value}");
    }

    private void onLoadCallback()
    {
        Debug.Log("dane załadowane !!!");
        m_isLoaded = true;
    }

    // Metody korekcji kolorów poniżej
}

Uwaga:
SetEditorMode(true) musi być wywołane przed Load, aby zadziałało; a SetTone musi być wywołane po zakończeniu ładowania danych (po wywołaniu zwrotnym onLoadCallback). Trzy suwaki m_brightness, m_saturation i m_contrast służą do dynamicznego dostosowywania parametrów korekcji kolorów w czasie działania i można ich używać w razie potrzeby.

Krok 6: Dołącz skrypt i ustaw właściwości

Dołącz skrypt Tone.cs do GameObject LCCRenderer.
W oknie Inspektor przeciągnij GameObject LCCManager na właściwość Manager skryptu.
Wpisz ścieżkę pliku LCC we właściwości File Path.
Przeciągnij Box1 ze sceny na właściwość Box1 skryptu i przeciągnij trzy suwaki odpowiednio na właściwości Brightness, Saturation i Contrast, dla korekcji kolorów 3D i dostosowywania parametrów w czasie działania.

Ustaw właściwości skryptu Tone w Inspektorze

Krok 7: Przykłady operacji korekcji kolorów

Dodaj poniższe metody do klasy Tone i wywołaj odpowiednią metodę po uruchomieniu i po zakończeniu ładowania danych.

Normalna korekcja kolorów

Skonstruuj teksturę maski R8, oznacz piksele do korekcji kolorów jako 240, a resztę jako 128, następnie skonstruuj ToneMix z macierzami kamery, ustaw brightness, saturation i contrast i dodaj go do listy.

public void onTone()
{
    // Rozmiar tekstury jest stały 1024*1024; zachowaj pozostałe właściwości tak jak w przykładzie
    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 oznacza domyślne, 240 oznacza zaznaczone, 0 oznacza przycinanie
        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);
}

Wyjaśnienie kodu: budowana jest tekstura maski zaznaczająca górną połowę ekranu (początek ekranu to lewy dolny róg), a do zaznaczonego obszaru stosowana jest korekcja kolorów o jasności 2.0, nasyceniu 2.0 i kontraście 0.4. Przykładowy efekt jest następujący.

W rzeczywistym użyciu możesz używać różnych narzędzi zaznaczania, takich jak prostokąty, trójkąty, pędzle i lassa, aby zaznaczyć odpowiednie pozycje na masce, a także dynamicznie przekazywać wartości brightness, saturation i contrast przez suwaki.

Efekt normalnej korekcji kolorów

Odwrócona korekcja kolorów

Odwrócenie korekcji kolorów różni się od podświetlania i przycinania: wpis odwrócenia, oprócz ustawienia mode = SelectMode.invert, musi przenosić dane korekcji kolorów (brightness, saturation, contrast), aby określić efekt korekcji kolorów dla obszaru poza zaznaczeniem. Na podstawie powyższej normalnej korekcji kolorów po prostu dołącz wpis odwrócenia.

public void onToneInvert()
{
    // Rozmiar tekstury jest stały 1024*1024; zachowaj pozostałe właściwości tak jak w przykładzie
    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 oznacza domyślne, 240 oznacza zaznaczone, 0 oznacza przycinanie
        else
            _values[i] = 240;
    }
    _texture.SetPixelData(_values, 0);

    List<ToneMix> _tMixs = new List<ToneMix>();

    // Korekcja kolorów zaznaczenia normalnego
    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);

    // Odwrócenie: musi przenosić dane korekcji kolorów (jasność/nasycenie/kontrast), nie jest czystym poleceniem
    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);
}

Wyjaśnienie kodu: wpis odwrócenia jest dołączany na wierzch normalnej korekcji kolorów, stosując korekcję kolorów o jasności 0.5, nasyceniu 0.5 i kontraście 2.0 do obszaru poza zaznaczeniem. W ten sposób wewnątrz i na zewnątrz zaznaczenia można stosować różne parametry korekcji kolorów. Przykładowy efekt jest następujący.

Efekt odwróconej korekcji kolorów

Uwaga:
Odwrócenie podświetlania i przycinania jest czystym poleceniem: dołączenie wpisu z mode = SelectMode.invert wystarczy, bez innych danych. Ale wpis odwrócenia korekcji kolorów musi również ustawić brightness, saturation i contrast; w przeciwnym razie odwrócony obszar używa wartości domyślnych (1.0) i nie osiąga oczekiwanego efektu.

Krok 8: Wyjdź z korekcji kolorów

Wywołaj QuitToneMode(), aby wyczyścić bieżącą korekcję kolorów i przywrócić oryginalne kolory sceny.

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

Kluczowe kroki

Kluczowe kroki korekcji kolorów sceny 3DGS:

Wywołaj SetEditorMode(true) przed załadowaniem danych, aby wejść w stan edycji.
Wywołaj SetTone po zakończeniu ładowania danych (po wywołaniu zwrotnym onLoadCallback lub wyzwolone przez przycisk/zdarzenie).
Steruj efektem korekcji kolorów przez brightness, saturation i contrast struktury ToneMix (zakres [0, 3], domyślnie 1.0) i upewnij się, że kolejność dodawania listy korekcji kolorów odpowiada Twoim oczekiwaniom.
Tekstura maski 2D jest stała 1024 × 1024, R8 jednokanałowa; wypełnij wartości pikseli zgodnie z konwencją (128 domyślne, 240 zaznaczone).
Odwrócenie korekcji kolorów (SelectMode.invert) musi przenosić dane brightness, saturation i contrast — to kluczowa różnica w stosunku do odwrócenia podświetlania/przycinania.
Przy czyszczeniu lub przełączaniu korekcji kolorów najpierw wywołaj QuitToneMode().