Ontwikkelgids voor kleuraanpassing

De LCC Unity SDK ondersteunt bewerkingsbewerkingen zoals markeren, knippen en kleuraanpassing op 3DGS-scènes. Deze gids behandelt kleuraanpassingsbewerkingen: het selecteren van een gebied via 2D-geprojecteerde texturen, 3D-geometrie of een combinatie van beide, en het aanpassen van de helderheid, verzadiging en het contrast van het geselecteerde gebied, met ondersteuning voor normale selectie en omgekeerde selectie.

Opmerking:
De huidige kleuraanpassingsfunctie is slechts een runtime-weergave-effect; het wijzigt het oorspronkelijke gegevensbestand op geen enkele manier en ondersteunt het opslaan of exporteren van het bewerkingsresultaat niet. Gebruik de XGRIDS LCC Editor-softwaretool als je kleuraanpassing, knippen en opslaan van gegevens nodig hebt.
Als je de gegevens niet wilt wijzigen, kun je de bewerkingen ook opnemen en ze (de instellingen uitvoeren) de volgende keer na het laden van de gegevens opnieuw afspelen.

Vereisten

Het aanpassen van de kleur van een scène via de SDK vereist de volgende voorwaarden:

Ga vóór het laden van de gegevens naar de bewerkstatus. De SDK bevindt zich standaard in de browse-status (View), die de beste prestaties biedt en wordt aanbevolen voor normaal browsen. Schakel voor bewerkingsbewerkingen zoals kleuraanpassing via SetEditorMode(true) naar de bewerkstatus voordat je Load aanroept. Deze methode werkt alleen als deze wordt aangeroepen vóór het laden van alle gegevens.
Voer de kleuraanpassingsbewerking uit nadat de gegevens zijn geladen. De kleuraanpassingsinterface moet worden aangeroepen nadat de scènegegevens volledig zijn geladen.

Stap 1: De scène opzetten

Bereid de GameObjects voor die nodig zijn voor kleuraanpassing in de scène:

Main Camera: de scènecamera; 2D-kleuraanpassing gebruikt de view- en projectiematrices ervan.
LCCManager: een leeg GameObject met een genormaliseerde Transform, waaraan het LCCManager-script is toegevoegd.
LCCRenderer: een leeg GameObject met de Transform ingesteld op Rotation.x = -90, Scale.x = -1 (uitgelijnd met het coördinatensysteem van de LCC-gegevens), gebruikt om het later te schrijven Tone-script aan toe te voegen.
3D-selectiegeometrie (optioneel): hulpobjecten voor 3D-kleuraanpassing. Het voorbeeld bevat één Cube (Box1); door deze te verplaatsen en te schalen, worden de positie en grootte van de 3D-kleuraanpassingsselectie bepaald.

Opmerking:
Raadpleeg voor instellingen met betrekking tot de rendercamera, LCCManager en LCCRenderer-GameObjects de relevante secties van Snelstartgids voor pc en Optimalisatiegids voor projectinstellingen.

Stap 2: De gegevensstructuur begrijpen

Kleuraanpassing gebruikt de gegevensstructuur ToneMix, die tegelijk een 2D-textuurselectie en een 3D-geometrieselectie kan beschrijven en de kleuraanpassingsparameters meedraagt. De gebruikte enums en structs zijn als volgt.

public enum SelectMode    { normal, invert, clip }  // normale selectie, inverteren, realtime knippen
public enum OperationMode { normal, erase }         // normale selectie, selectie wissen
public enum ShapeType     { box, sphere }           // 3D Box-selectie, 3D Sphere-selectie
public enum EditType      { Edit2D, Edit3D }        // 2D-bewerking, 3D-bewerking

// Kleuraanpassingsselectie
public struct ToneMix
{
    public EditType editType;       // bewerkingstype (vereist; bepaalt of 2D- of 3D-velden worden gebruikt)
    public Texture2D texture;       // 2D-maskertextuur (gebruikt door Edit2D)
    public Matrix4x4 mv;            // cameraviewmatrix (gebruikt door Edit2D)
    public Matrix4x4 mvp;           // cameraview-projectiematrix (gebruikt door Edit2D)
    public ShapeType type;          // geometrietype (gebruikt door Edit3D)
    public Matrix4x4 invMat;        // inverse matrix van de geometrie (gebruikt door Edit3D)
    public OperationMode operation; // bewerkingstype (gebruikt door Edit3D)
    public SelectMode mode;         // selectiemodus (vereist)

    public float brightness;        // helderheid, bereik [0, 3], standaard 1.0
    public float saturation;        // verzadiging, bereik [0, 3], standaard 1.0
    public float contrast;          // contrast, bereik [0, 3], standaard 1.0
    public int lutid;               // LUT-tabelindex (gereserveerd), 0 betekent niet gebruikt
}

Er zijn drie punten om op te letten bij de kleuraanpassingslijst:

De lijst is geordend. Of het nu 2D of 3D is, items in de lijst worden op volgorde van kracht; zorg ervoor dat de volgorde van toevoegen overeenkomt met je verwachting.
Inverteren moet kleuraanpassingsgegevens meedragen. Dit is het meest kritieke verschil tussen kleuraanpassing en markeren/knippen — het inverteren van markeren/knippen is een pure opdracht en hoeft niet aan gegevens te worden gekoppeld; maar het inverteren-item van kleuraanpassing moet naast mode = SelectMode.invert ook brightness, saturation en contrast instellen, om het kleuraanpassingseffect voor het gebied buiten de selectie op te geven.
Het maximumaantal items in één lijst is 255. Bij overschrijding wordt een foutcode geretourneerd.

Stap 3: De kleuraanpassings-API's begrijpen

Alle kleuraanpassingsgerelateerde interfaces worden geleverd door LCCManager, waaronder één SetTone-methode en één afsluitmethode.

SetTone

// Retourwaarde: int
// 0: succes
// 1: lijst is null of heeft 0 elementen
// 2: lijstelementen overschrijden het maximum van 255
public int SetTone(List<ToneMix> _Mix)

Voert kleuraanpassing uit op het geselecteerde gebied, met ondersteuning voor aanpassing van helderheid, verzadiging en contrast. 2D-textuuritems en 3D-geometrie-items kunnen in dezelfde lijst worden gemengd.

QuitToneMode

// Retourwaarde: void
public void QuitToneMode()

Sluit de kleuraanpassingsmodus af en herstelt de oorspronkelijke kleuren van de scène.

Tip:
Roep bij het wisselen van kleuraanpassingsparameters of het wissen van de huidige kleuraanpassing eerst QuitToneMode() aan en stel vervolgens de nieuwe kleuraanpassing in.

Stap 4: Specificatie van de 2D-maskertextuur

2D-kleuraanpassing beschrijft de selectie via een maskertextuur en ondersteunt diverse selectiemethoden zoals vierhoeken, driehoeken, penselen en lasso's — markeer eenvoudig de overeenkomstige pixels in de textuur met de geselecteerde waarde. Bij 2D-bewerkingen moet de camera worden vergrendeld en moet de textuur vanuit een vast gezichtspunt worden gemarkeerd. De textuur- en pixelwaarden volgen deze conventies:

De textuur is vast op 1024 × 1024, R8 enkel kanaal, geen Mipmap, puntfiltering (FilterMode.Point) en geklemde sampling (TextureWrapMode.Clamp).
Conventies voor pixelwaarden:

Pixelwaarde	Betekenis
`128`	Standaard (niet geselecteerd)
`240`	Geselecteerd
`180`	Deselecteren (het al geselecteerde gebied wissen)
`0`	Knippen

In een kleuraanpassingsscenario worden doorgaans alleen de twee waarden 128 (standaard) en 240 (geselecteerd) gebruikt.

Stap 5: Het script schrijven

Maak een nieuw C#-script aan met de naam Tone.cs. Voltooi eerst het basisskelet: ga in Start naar de bewerkstatus en laad de gegevens; stel na het laden de laadmarkering in zodat de latere kleuraanpassingsmethoden deze kunnen controleren.

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

        // Ga naar de bewerkmodus; moet vóór Load worden aangeroepen
        m_manager.SetEditorMode(true);

        m_renderer = m_manager.GetRender(this.transform);
        if (m_renderer == null)
            Debug.LogError("GetRender mislukt, controleer of de manager correct is ingesteld en of het bestandspad geldig is.");

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

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

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

    // Kleuraanpassingsmethoden hieronder
}

Opmerking:
SetEditorMode(true) moet vóór Load worden aangeroepen om van kracht te worden; en SetTone moet worden aangeroepen nadat de gegevens zijn geladen (nadat de onLoadCallback-callback is geactiveerd). De drie sliders m_brightness, m_saturation en m_contrast worden gebruikt om de kleuraanpassingsparameters tijdens runtime dynamisch aan te passen en kunnen naar behoefte worden gebruikt.

Stap 6: Het script toevoegen en eigenschappen instellen

Voeg het Tone.cs-script toe aan het LCCRenderer-GameObject.
Sleep in het Inspector-venster het LCCManager-GameObject naar de eigenschap Manager van het script.
Vul het LCC-bestandspad in bij de eigenschap File Path.
Sleep Box1 in de scène naar de eigenschap Box1 van het script en sleep de drie sliders respectievelijk naar de eigenschappen Brightness, Saturation en Contrast, voor 3D-kleuraanpassing en runtime-parameteraanpassing.

Stel de eigenschappen van het Tone-script in de Inspector in

Stap 7: Voorbeelden van kleuraanpassingsbewerkingen

Voeg de onderstaande methoden toe aan de klasse Tone en roep de bijbehorende methode na het uitvoeren en na het laden van de gegevens aan.

Normale kleuraanpassing

Maak een R8-maskertextuur, markeer de aan te passen pixels als 240 en de rest als 128, maak vervolgens ToneMix met de cameramatrices, stel brightness, saturation en contrast in en voeg deze toe aan de lijst.

public void onTone()
{
    // Textuurgrootte is vast op 1024*1024; houd de overige eigenschappen gelijk aan het voorbeeld
    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 betekent standaard, 240 betekent geselecteerd, 0 betekent knippen
        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-uitleg: er wordt een maskertextuur opgebouwd die de bovenste helft van het scherm selecteert (de schermoorsprong is de linkerbenedenhoek) en op het geselecteerde gebied wordt een kleuraanpassing van helderheid 2.0, verzadiging 2.0 en contrast 0.4 toegepast. Het voorbeeldeffect is als volgt.

In de praktijk kun je verschillende selectietools zoals rechthoeken, driehoeken, penselen en lasso's gebruiken om de overeenkomstige posities op het masker te selecteren en kun je ook de waarden van brightness, saturation en contrast dynamisch via sliders doorgeven.

Effect van normale kleuraanpassing

Inverteren kleuraanpassing

Het inverteren van kleuraanpassing verschilt van markeren en knippen: het inverteren-item moet naast het instellen van mode = SelectMode.invert kleuraanpassingsgegevens meedragen (brightness, saturation, contrast) om het kleuraanpassingseffect voor het gebied buiten de selectie op te geven. Voeg op basis van de normale kleuraanpassing hierboven eenvoudig een inverteren-item toe.

public void onToneInvert()
{
    // Textuurgrootte is vast op 1024*1024; houd de overige eigenschappen gelijk aan het voorbeeld
    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 betekent standaard, 240 betekent geselecteerd, 0 betekent knippen
        else
            _values[i] = 240;
    }
    _texture.SetPixelData(_values, 0);

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

    // Kleuraanpassing van normale selectie
    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);

    // Inverteren: moet kleuraanpassingsgegevens (helderheid/verzadiging/contrast) meedragen, geen pure opdracht
    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-uitleg: er wordt een inverteren-item toegevoegd bovenop de normale kleuraanpassing, waarmee een kleuraanpassing van helderheid 0.5, verzadiging 0.5 en contrast 2.0 wordt toegepast op het gebied buiten de selectie. Op deze manier kunnen binnen en buiten de selectie verschillende kleuraanpassingsparameters worden toegepast. Het voorbeeldeffect is als volgt.

Effect van inverteren kleuraanpassing

Opmerking:
Het inverteren van markeren en knippen is een pure opdracht: het toevoegen van een item met mode = SelectMode.invert is voldoende, er zijn geen andere gegevens vereist. Maar het inverteren-item van kleuraanpassing moet ook brightness, saturation en contrast instellen; anders gebruikt het geïnverteerde gebied de standaardwaarden (1.0) en wordt het verwachte effect niet bereikt.

Stap 8: Kleuraanpassing afsluiten

Roep QuitToneMode() aan om de huidige kleuraanpassing te wissen en de oorspronkelijke kleuren van de scène te herstellen.

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

Belangrijkste stappen

De belangrijkste stappen voor het aanpassen van de kleur van een 3DGS-scène:

Roep SetEditorMode(true) vóór het laden van de gegevens aan om naar de bewerkstatus te gaan.
Roep SetTone nadat de gegevens zijn geladen aan (nadat de onLoadCallback-callback is geactiveerd, of geactiveerd via een knop/gebeurtenis).
Beheer het kleuraanpassingseffect via brightness, saturation en contrast van ToneMix (bereik [0, 3], standaard 1.0) en zorg ervoor dat de volgorde van toevoegen van de kleuraanpassingslijst overeenkomt met je verwachting.
De 2D-maskertextuur is vast op 1024 × 1024, R8 enkel kanaal; vul de pixelwaarden volgens conventie in (128 standaard, 240 geselecteerd).
Het inverteren van kleuraanpassing (SelectMode.invert) moet brightness, saturation en contrast meedragen — dit is het belangrijkste verschil met het inverteren van markeren/knippen.
Roep bij het wissen of wisselen van kleuraanpassing eerst QuitToneMode() aan.