Entwicklungsanleitung für Farbanpassung

Das LCC Unity SDK unterstützt Bearbeitungsoperationen wie Hervorhebung, Clipping und Farbanpassung auf 3DGS-Szenen. Diese Anleitung stellt Farbanpassungsoperationen vor: das Auswählen eines Bereichs über 2D-projizierte Texturen, 3D-Geometrie oder eine Mischung aus beidem und das Anpassen von Helligkeit, Sättigung und Kontrast des ausgewählten Bereichs, wobei normale Auswahl und invertierte Auswahl unterstützt werden.

Hinweis:
Die aktuelle Farbanpassungsfunktion ist nur ein Laufzeit-Anzeigeeffekt; sie verändert die ursprüngliche Datendatei in keiner Weise und unterstützt weder das Speichern noch das Exportieren des Bearbeitungsergebnisses. Wenn Sie Daten farbanpassen, zuschneiden und speichern müssen, verwenden Sie das Software-Tool XGRIDS LCC Editor.
Wenn Sie die Daten nicht verändern möchten, können Sie die Operationen auch aufzeichnen und sie (die Einstellungen ausführen) nach dem nächsten Abschluss des Datenladens erneut abspielen.

Voraussetzungen

Das Farbanpassen einer Szene über das SDK erfordert folgende Bedingungen:

Vor dem Laden der Daten in den Bearbeitungszustand wechseln. Das SDK befindet sich standardmäßig im Durchsuchen-Zustand (View), der die beste Leistung bietet und für das normale Durchsuchen empfohlen wird. Um Bearbeitungsoperationen wie Farbanpassung auszuführen, wechseln Sie vor dem Aufruf von Load über SetEditorMode(true) in den Bearbeitungszustand. Diese Methode wirkt nur, wenn sie vor dem Laden aller Daten aufgerufen wird.
Die Farbanpassungsoperation nach Abschluss des Datenladens ausführen. Die Farbanpassungsschnittstelle muss aufgerufen werden, nachdem die Szenendaten vollständig geladen sind.

Schritt 1: Die Szene einrichten

Bereiten Sie die für die Farbanpassung benötigten GameObjects in der Szene vor:

Hauptkamera: die Szenenkamera; die 2D-Farbanpassung verwendet ihre View- und Projektionsmatrizen.
LCCManager: ein leeres GameObject mit normalisierter Transform und dem hinzugefügten Skript LCCManager.
LCCRenderer: ein leeres GameObject mit Transform Rotation.x = -90, Scale.x = -1 (am LCC-Daten-Koordinatensystem ausgerichtet), zum Anhängen des später geschriebenen Skripts Tone.
3D-Auswahlgeometrie (optional): Hilfsobjekte für die 3D-Farbanpassung. Das Beispiel bereitet einen Würfel (Box1) vor; das Verschieben und Skalieren steuert Position und Größe der 3D-Farbanpassungsauswahl.

Hinweis:
Für Einstellungen im Zusammenhang mit den GameObjects Rendering-Kamera, LCCManager und LCCRenderer siehe die relevanten Abschnitte der PC-Schnellstartanleitung und des Leitfadens zur Optimierung der Projekteinstellungen.

Schritt 2: Die Datenstruktur verstehen

Die Farbanpassung verwendet die Datenstruktur ToneMix, die gleichzeitig eine 2D-Texturauswahl und eine 3D-Geometrieauswahl beschreiben kann und die Farbanpassungsparameter trägt. Die verwendeten Enums und Structs sind wie folgt.

public enum SelectMode    { normal, invert, clip }  // normale Auswahl, invertieren, Echtzeit-Clipping
public enum OperationMode { normal, erase }         // normale Auswahl, Auswahl löschen
public enum ShapeType     { box, sphere }           // 3D-Box-Auswahl, 3D-Kugel-Auswahl
public enum EditType      { Edit2D, Edit3D }        // 2D-Bearbeitung, 3D-Bearbeitung

// Farbanpassungs-Auswahl
public struct ToneMix
{
    public EditType editType;       // Bearbeitungstyp (erforderlich; bestimmt, ob 2D- oder 3D-Felder verwendet werden)
    public Texture2D texture;       // 2D-Maskentextur (von Edit2D verwendet)
    public Matrix4x4 mv;            // Kamera-View-Matrix (von Edit2D verwendet)
    public Matrix4x4 mvp;           // Kamera-View-Projection-Matrix (von Edit2D verwendet)
    public ShapeType type;          // Geometrietyp (von Edit3D verwendet)
    public Matrix4x4 invMat;        // Geometrie-Inversmatrix (von Edit3D verwendet)
    public OperationMode operation; // Operationstyp (von Edit3D verwendet)
    public SelectMode mode;         // Auswahlmodus (erforderlich)

    public float brightness;        // Helligkeit, Bereich [0, 3], Standard 1.0
    public float saturation;        // Sättigung, Bereich [0, 3], Standard 1.0
    public float contrast;          // Kontrast, Bereich [0, 3], Standard 1.0
    public int lutid;               // LUT-Tabellenindex (reserviert), 0 bedeutet nicht verwendet
}

Zur Farbanpassungsliste gibt es drei Punkte zu beachten:

Die Liste ist geordnet. Ob 2D oder 3D, Einträge in der Liste wirken in Reihenfolge; stellen Sie sicher, dass die Reihenfolge des Hinzufügens Ihrer Erwartung entspricht.
Invertieren muss Farbanpassungsdaten tragen. Dies ist der entscheidende Unterschied zwischen Farbanpassung und Hervorhebung/Clipping – das Invertieren von Hervorhebung/Clipping ist ein reiner Befehl und muss nicht mit Daten verknüpft werden; aber der Invertier-Eintrag der Farbanpassung muss neben mode = SelectMode.invert auch brightness, saturation und contrast setzen, um den Farbanpassungseffekt für den Bereich außerhalb der Auswahl anzugeben.
Die maximale Anzahl von Einträgen in einer einzelnen Liste beträgt 255. Bei Überschreitung wird ein Fehlercode zurückgegeben.

Schritt 3: Die Farbanpassungs-APIs verstehen

Alle farbanpassungsbezogenen Schnittstellen werden von LCCManager bereitgestellt, einschließlich einer SetTone-Methode und einer Beenden-Methode.

SetTone

// Rückgabewert: int
// 0: Erfolg
// 1: Liste ist null oder hat 0 Elemente
// 2: Listenelemente überschreiten das Maximum von 255
public int SetTone(List<ToneMix> _Mix)

Führt eine Farbanpassung des ausgewählten Bereichs durch und unterstützt Helligkeits-, Sättigungs- und Kontrastanpassungen. 2D-Textur-Einträge und 3D-Geometrie-Einträge können in derselben Liste gemischt werden.

QuitToneMode

// Rückgabewert: void
public void QuitToneMode()

Beendet den Farbanpassungsmodus und stellt die ursprünglichen Farben der Szene wieder her.

Tipp:
Rufen Sie beim Wechseln der Farbanpassungsparameter oder beim Löschen der aktuellen Farbanpassung zuerst QuitToneMode() auf und setzen Sie dann die neue Farbanpassung.

Schritt 4: Spezifikation der 2D-Maskentextur

Die 2D-Farbanpassung beschreibt die Auswahl über eine Maskentextur und unterstützt verschiedene Auswahlmethoden wie Vierecke, Dreiecke, Pinsel und Lasso – markieren Sie einfach die entsprechenden Pixel in der Textur mit dem Auswahlwert. Bei 2D-Operationen sollte die Kamera gesperrt und die Textur von einem festen Blickpunkt aus markiert werden. Die Textur und die Pixelwerte haben folgende Konventionen:

Die Textur ist fest 1024 × 1024, R8-Einkanal, ohne Mipmap, Punktfilterung (FilterMode.Point) und geklemmtes Sampling (TextureWrapMode.Clamp).
Pixelwert-Konventionen:

Pixelwert	Bedeutung
`128`	Standard (nicht ausgewählt)
`240`	Ausgewählt
`180`	Abwählen (den bereits ausgewählten Bereich löschen)
`0`	Clipping

In einem Farbanpassungsszenario werden normalerweise nur die beiden Werte 128 (Standard) und 240 (ausgewählt) verwendet.

Schritt 5: Das Skript schreiben

Erstellen Sie ein neues C#-Skript namens Tone.cs. Vervollständigen Sie zunächst das Grundskelett: In Start in den Bearbeitungszustand wechseln und Daten laden; nach Abschluss des Ladens das Ladeflag setzen, damit die nachfolgenden Farbanpassungsmethoden es prüfen können.

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

        // In den Bearbeitungsmodus wechseln; muss vor Load aufgerufen werden
        m_manager.SetEditorMode(true);

        m_renderer = m_manager.GetRender(this.transform);
        if (m_renderer == null)
            Debug.LogError("GetRender fehlgeschlagen. Prüfen Sie, ob der Manager korrekt gesetzt ist und der Dateipfad gültig ist.");

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

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

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

    // Farbanpassungsmethoden unten
}

Hinweis:
SetEditorMode(true) muss vor Load aufgerufen werden, um zu wirken; und SetTone muss nach Abschluss des Datenladens aufgerufen werden (nachdem der Callback onLoadCallback ausgelöst wurde). Die drei Slider m_brightness, m_saturation und m_contrast dienen zum dynamischen Anpassen der Farbanpassungsparameter zur Laufzeit und können nach Bedarf verwendet werden.

Schritt 6: Das Skript anhängen und Eigenschaften festlegen

Hängen Sie das Skript Tone.cs an das GameObject LCCRenderer.
Ziehen Sie im Fenster Inspektor das GameObject LCCManager auf die Eigenschaft Manager des Skripts.
Tragen Sie den LCC-Dateipfad in die Eigenschaft File Path ein.
Ziehen Sie Box1 in der Szene auf die Eigenschaft Box1 des Skripts und die drei Slider auf die Eigenschaften Brightness, Saturation und Contrast – für die 3D-Farbanpassung und die Laufzeit-Parameteranpassung.

Die Eigenschaften des Tone-Skripts im Inspektor festlegen

Schritt 7: Beispiele für Farbanpassungsoperationen

Fügen Sie die folgenden Methoden zur Klasse Tone hinzu und rufen Sie die entsprechende Methode nach dem Ausführen und nach Abschluss des Datenladens auf.

Normale Farbanpassung

Konstruieren Sie eine R8-Maskentextur, markieren Sie die farbanzupassenden Pixel mit 240 und den Rest mit 128, konstruieren Sie dann ToneMix mit den Kameramatrizen, setzen Sie brightness, saturation und contrast und fügen Sie es der Liste hinzu.

public void onTone()
{
    // Die Texturgröße ist fest 1024*1024; die übrigen Eigenschaften wie im Beispiel beibehalten
    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 bedeutet Standard, 240 bedeutet ausgewählt, 0 bedeutet 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);
}

Code-Erläuterung: Es wird eine Maskentextur erstellt, die die obere Bildschirmhälfte auswählt (der Bildschirmursprung ist die untere linke Ecke), und auf den ausgewählten Bereich wird eine Farbanpassung mit Helligkeit 2,0, Sättigung 2,0 und Kontrast 0,4 angewendet. Der Beispieleffekt ist wie folgt.

In der Praxis können Sie verschiedene Auswahlwerkzeuge wie Rechtecke, Dreiecke, Pinsel und Lasso verwenden, um die entsprechenden Positionen auf der Maske auszuwählen, und die Werte von brightness, saturation und contrast dynamisch über Slider übergeben.

Effekt der normalen Farbanpassung

Invertierte Farbanpassung

Das Invertieren der Farbanpassung unterscheidet sich von Hervorhebung und Clipping: Der Invertier-Eintrag muss neben dem Setzen von mode = SelectMode.invert Farbanpassungsdaten tragen (brightness, saturation, contrast), um den Farbanpassungseffekt für den Bereich außerhalb der Auswahl anzugeben. Basierend auf der obigen normalen Farbanpassung einfach einen Invertier-Eintrag anhängen.

public void onToneInvert()
{
    // Die Texturgröße ist fest 1024*1024; die übrigen Eigenschaften wie im Beispiel beibehalten
    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 bedeutet Standard, 240 bedeutet ausgewählt, 0 bedeutet Clipping
        else
            _values[i] = 240;
    }
    _texture.SetPixelData(_values, 0);

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

    // Farbanpassung der normalen Auswahl
    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);

    // Invertieren: muss Farbanpassungsdaten tragen (brightness/saturation/contrast), kein reiner Befehl
    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);
}

Code-Erläuterung: Auf die normale Farbanpassung wird ein Invertier-Eintrag angehängt, der auf den Bereich außerhalb der Auswahl eine Farbanpassung mit Helligkeit 0,5, Sättigung 0,5 und Kontrast 2,0 anwendet. Auf diese Weise können innerhalb und außerhalb der Auswahl unterschiedliche Farbanpassungsparameter angewendet werden. Der Beispieleffekt ist wie folgt.

Effekt der invertierten Farbanpassung

Hinweis:
Das Invertieren von Hervorhebung und Clipping ist ein reiner Befehl: Es genügt, einen Eintrag mit mode = SelectMode.invert anzuhängen, ohne dass weitere Daten erforderlich sind. Der Invertier-Eintrag der Farbanpassung muss jedoch auch brightness, saturation und contrast setzen; andernfalls verwendet der invertierte Bereich die Standardwerte (1,0) und erzielt nicht den erwarteten Effekt.

Schritt 8: Farbanpassung beenden

Rufen Sie QuitToneMode() auf, um die aktuelle Farbanpassung zu löschen und die ursprünglichen Farben der Szene wiederherzustellen.

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

Schlüsselschritte

Die Schlüsselschritte zum Farbanpassen einer 3DGS-Szene:

SetEditorMode(true) vor dem Laden der Daten aufrufen, um in den Bearbeitungszustand zu wechseln.
SetTone nach Abschluss des Datenladens aufrufen (nachdem der Callback onLoadCallback ausgelöst wurde, oder über einen Button/ein Ereignis ausgelöst).
Den Farbanpassungseffekt über brightness, saturation und contrast von ToneMix steuern (Bereich [0, 3], Standard 1.0) und sicherstellen, dass die Hinzufüge-Reihenfolge der Farbanpassungsliste Ihrer Erwartung entspricht.
Die 2D-Maskentextur ist fest 1024 × 1024, R8-Einkanal; Pixelwerte gemäß Konvention füllen (128 Standard, 240 ausgewählt).
Das Invertieren der Farbanpassung (SelectMode.invert) muss brightness, saturation und contrast-Daten tragen – dies ist der entscheidende Unterschied zum Invertieren von Hervorhebung/Clipping.
Beim Löschen oder Wechseln der Farbanpassung zuerst QuitToneMode() aufrufen.