Guida allo sviluppo della regolazione del tono

L'LCC Unity SDK supporta operazioni di modifica come l'evidenziazione, il ritaglio e la regolazione del tono sulle scene 3DGS. Questa guida illustra le operazioni di regolazione del tono: selezionare un'area tramite texture proiettate 2D, geometria 3D o un mix di entrambe, e regolare luminosità, saturazione e contrasto dell'area selezionata, supportando la selezione normale e l'inversione della selezione.

Nota:
L'attuale funzionalità di regolazione del tono è solo un effetto di visualizzazione in fase di esecuzione; non modifica in alcun modo il file dati originale e non supporta il salvataggio o l'esportazione del risultato della modifica. Se devi regolare il tono, ritagliare e salvare i dati, usa lo strumento software XGRIDS LCC Editor.
Se non vuoi modificare i dati, puoi anche registrare le operazioni e riprodurle (eseguire le impostazioni) dopo che i dati avranno terminato il caricamento la volta successiva.

Prerequisiti

La regolazione del tono di una scena tramite l'SDK richiede le seguenti condizioni:

Entra nello stato di modifica prima di caricare i dati. L'SDK è nello stato di navigazione (View) per impostazione predefinita, che offre le migliori prestazioni ed è consigliato per la navigazione normale. Per eseguire operazioni di modifica come la regolazione del tono, passa allo stato di modifica tramite SetEditorMode(true) prima di chiamare Load. Questo metodo ha effetto solo se chiamato prima del caricamento di tutti i dati.
Esegui l'operazione di regolazione del tono dopo che i dati hanno terminato il caricamento. L'interfaccia di regolazione del tono deve essere chiamata dopo che i dati della scena sono stati completamente caricati.

Passaggio 1: configura la scena

Prepara i GameObject necessari per la regolazione del tono nella scena:

Camera principale: la camera della scena; la regolazione del tono 2D usa le sue matrici di vista e proiezione.
LCCManager: un GameObject vuoto con un Transform normalizzato, con lo script LCCManager aggiunto.
LCCRenderer: un GameObject vuoto con Transform impostato su Rotation.x = -90, Scale.x = -1 (allineato al sistema di coordinate dei dati LCC), usato per associare lo script Tone scritto in seguito.
Geometria di selezione 3D (opzionale): oggetti ausiliari per la regolazione del tono 3D. L'esempio prepara un Cubo (Box1); spostandolo e ridimensionandolo si controllano la posizione e la dimensione della selezione di regolazione del tono 3D.

Nota:
Per le impostazioni relative alla camera di rendering e ai GameObject LCCManager e LCCRenderer, consulta le sezioni pertinenti della Guida rapida per PC e della Guida all'ottimizzazione delle impostazioni di progetto.

Passaggio 2: comprendi la struttura dati

La regolazione del tono usa la struttura dati ToneMix, che può descrivere sia una selezione tramite texture 2D sia una selezione tramite geometria 3D contemporaneamente, e porta con sé i parametri di regolazione del tono. Gli enum e le struct usati sono i seguenti.

public enum SelectMode    { normal, invert, clip }  // selezione normale, inversione, ritaglio in tempo reale
public enum OperationMode { normal, erase }         // selezione normale, cancellazione della selezione
public enum ShapeType     { box, sphere }           // selezione Box 3D, selezione Sfera 3D
public enum EditType      { Edit2D, Edit3D }        // modifica 2D, modifica 3D

// Selezione per la regolazione del tono
public struct ToneMix
{
    public EditType editType;       // tipo di modifica (obbligatorio; determina se vengono usati i campi 2D o 3D)
    public Texture2D texture;       // texture maschera 2D (usata da Edit2D)
    public Matrix4x4 mv;            // matrice di vista della camera (usata da Edit2D)
    public Matrix4x4 mvp;           // matrice di vista-proiezione della camera (usata da Edit2D)
    public ShapeType type;          // tipo di geometria (usato da Edit3D)
    public Matrix4x4 invMat;        // matrice inversa della geometria (usata da Edit3D)
    public OperationMode operation; // tipo di operazione (usato da Edit3D)
    public SelectMode mode;         // modalità di selezione (obbligatorio)

    public float brightness;        // luminosità, intervallo [0, 3], predefinito 1.0
    public float saturation;        // saturazione, intervallo [0, 3], predefinito 1.0
    public float contrast;          // contrasto, intervallo [0, 3], predefinito 1.0
    public int lutid;               // indice della tabella LUT (riservato), 0 significa non usato
}

Ci sono tre punti da notare sull'elenco di regolazione del tono:

L'elenco è ordinato. Sia in 2D che in 3D, le voci dell'elenco hanno effetto in ordine; assicurati che l'ordine di aggiunta corrisponda alle tue aspettative.
L'inversione deve portare i dati di regolazione del tono. Questa è la differenza più critica tra la regolazione del tono e l'evidenziazione/ritaglio — l'inversione di evidenziazione/ritaglio è un comando puro e non deve essere associata a dati; ma la voce di inversione della regolazione del tono, oltre a mode = SelectMode.invert, deve anche impostare brightness, saturation e contrast, per specificare l'effetto di regolazione del tono per l'area esterna alla selezione.
Il numero massimo di voci in un singolo elenco è 255. Superarlo restituisce un codice di errore.

Passaggio 3: comprendi le API di regolazione del tono

Tutte le interfacce relative alla regolazione del tono sono fornite da LCCManager, inclusi un metodo SetTone e un metodo di uscita.

SetTone

// Valore restituito: int
// 0: operazione riuscita
// 1: l'elenco è null o ha 0 elementi
// 2: gli elementi dell'elenco superano il massimo di 255
public int SetTone(List<ToneMix> _Mix)

Esegue la regolazione del tono sull'area selezionata, supportando regolazioni di luminosità, saturazione e contrasto. Le voci di texture 2D e le voci di geometria 3D possono essere mescolate nello stesso elenco.

QuitToneMode

// Valore restituito: void
public void QuitToneMode()

Esce dalla modalità di regolazione del tono e ripristina i colori originali della scena.

Suggerimento:
Quando cambi i parametri di regolazione del tono o cancelli la regolazione del tono corrente, chiama prima QuitToneMode() e poi imposta la nuova regolazione del tono.

Passaggio 4: specifica della texture maschera 2D

La regolazione del tono 2D descrive la selezione tramite una texture maschera, supportando vari metodi di selezione come quadrilateri, triangoli, pennelli e lazo — basta contrassegnare i pixel corrispondenti nella texture con il valore selezionato. Quando usi operazioni 2D, la camera dovrebbe essere bloccata e la texture contrassegnata da un punto di vista fisso. La texture e i valori dei pixel hanno le seguenti convenzioni:

La texture è fissa a 1024 × 1024, R8 canale singolo, senza Mipmap, filtro punto (FilterMode.Point) e campionamento bloccato (TextureWrapMode.Clamp).
Convenzioni dei valori dei pixel:

Valore pixel	Significato
`128`	Predefinito (non selezionato)
`240`	Selezionato
`180`	Deseleziona (cancella l'area già selezionata)
`0`	Ritaglio

In uno scenario di regolazione del tono, di solito vengono usati solo i due valori 128 (predefinito) e 240 (selezionato).

Passaggio 5: scrivi lo script

Crea un nuovo script C# denominato Tone.cs. Completa prima lo scheletro di base: in Start, entra nello stato di modifica e carica i dati; dopo il completamento del caricamento, imposta il flag di caricamento per i successivi metodi di regolazione del tono da verificare.

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

        // Entra in modalità di modifica; deve essere chiamato prima di Load
        m_manager.SetEditorMode(true);

        m_renderer = m_manager.GetRender(this.transform);
        if (m_renderer == null)
            Debug.LogError("GetRender non riuscito, verifica che il manager sia impostato correttamente e che il percorso del file sia valido.");

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

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

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

    // Metodi di regolazione del tono di seguito
}

Nota:
SetEditorMode(true) deve essere chiamato prima di Load per avere effetto; e SetTone deve essere chiamato dopo che i dati hanno terminato il caricamento (dopo che il callback onLoadCallback viene attivato). I tre slider m_brightness, m_saturation e m_contrast vengono usati per regolare dinamicamente i parametri di regolazione del tono in fase di esecuzione e possono essere usati secondo necessità.

Passaggio 6: associa lo script e imposta le proprietà

Associa lo script Tone.cs al GameObject LCCRenderer.
Nella finestra Inspector, trascina il GameObject LCCManager sulla proprietà Manager dello script.
Inserisci il percorso del file LCC nella proprietà File Path.
Trascina Box1 della scena sulla proprietà Box1 dello script e trascina i tre slider rispettivamente sulle proprietà Brightness, Saturation e Contrast, per la regolazione del tono 3D e la regolazione dei parametri in fase di esecuzione.

Imposta le proprietà dello script Tone nell'Inspector

Passaggio 7: esempi di operazioni di regolazione del tono

Aggiungi i metodi seguenti alla classe Tone e chiama il metodo corrispondente dopo l'esecuzione e dopo che i dati hanno terminato il caricamento.

Regolazione del tono normale

Costruisci una texture maschera R8, contrassegna i pixel da regolare come 240 e il resto come 128, poi costruisci ToneMix con le matrici della camera, imposta brightness, saturation e contrast e aggiungila all'elenco.

public void onTone()
{
    // La dimensione della texture è fissa a 1024*1024; mantieni le altre proprietà uguali all'esempio
    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 significa predefinito, 240 significa selezionato, 0 significa ritaglio
        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);
}

Spiegazione del codice: viene costruita una texture maschera che seleziona la metà superiore dello schermo (l'origine dello schermo è l'angolo inferiore sinistro) e all'area selezionata viene applicata una regolazione del tono di luminosità 2.0, saturazione 2.0 e contrasto 0.4. L'effetto dell'esempio è il seguente.

Nell'uso reale, puoi usare vari strumenti di selezione come rettangoli, triangoli, pennelli e lazo per selezionare le posizioni corrispondenti sulla maschera, e anche passare dinamicamente i valori di brightness, saturation e contrast tramite gli slider.

Effetto della regolazione del tono normale

Regolazione del tono invertita

L'inversione della regolazione del tono differisce da evidenziazione e ritaglio: la voce di inversione, oltre a impostare mode = SelectMode.invert, deve portare i dati di regolazione del tono (brightness, saturation, contrast) per specificare l'effetto di regolazione del tono per l'area esterna alla selezione. Basandoti sulla regolazione del tono normale sopra, aggiungi semplicemente una voce di inversione.

public void onToneInvert()
{
    // La dimensione della texture è fissa a 1024*1024; mantieni le altre proprietà uguali all'esempio
    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 significa predefinito, 240 significa selezionato, 0 significa ritaglio
        else
            _values[i] = 240;
    }
    _texture.SetPixelData(_values, 0);

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

    // Regolazione del tono della selezione normale
    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);

    // Inversione: deve portare i dati di regolazione del tono (luminosità/saturazione/contrasto), non un comando puro
    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);
}

Spiegazione del codice: una voce di inversione viene aggiunta sopra la regolazione del tono normale, applicando una regolazione del tono di luminosità 0.5, saturazione 0.5 e contrasto 2.0 all'area esterna alla selezione. In questo modo, possono essere applicati parametri di regolazione del tono diversi dentro e fuori la selezione. L'effetto dell'esempio è il seguente.

Effetto della regolazione del tono invertita

Nota:
L'inversione di evidenziazione e ritaglio è un comando puro: aggiungere una voce con mode = SelectMode.invert è sufficiente, senza altri dati richiesti. Ma la voce di inversione della regolazione del tono deve anche impostare brightness, saturation e contrast; altrimenti l'area invertita usa i valori predefiniti (1.0) e non ottiene l'effetto previsto.

Passaggio 8: esci dalla regolazione del tono

Chiama QuitToneMode() per cancellare la regolazione del tono corrente e ripristinare i colori originali della scena.

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

Punti chiave

I passaggi chiave per regolare il tono di una scena 3DGS:

Chiama SetEditorMode(true) prima di caricare i dati per entrare nello stato di modifica.
Chiama SetTone dopo che i dati hanno terminato il caricamento (dopo che il callback onLoadCallback viene attivato, o tramite un pulsante/evento).
Controlla l'effetto di regolazione del tono tramite brightness, saturation e contrast di ToneMix (intervallo [0, 3], predefinito 1.0) e assicurati che l'ordine di aggiunta dell'elenco di regolazione del tono corrisponda alle tue aspettative.
La texture maschera 2D è fissa a 1024 × 1024, R8 canale singolo; riempi i valori dei pixel per convenzione (128 predefinito, 240 selezionato).
L'inversione della regolazione del tono (SelectMode.invert) deve portare i dati brightness, saturation e contrast — questa è la differenza chiave rispetto all'inversione di evidenziazione/ritaglio.
Quando cancelli o cambi la regolazione del tono, chiama prima QuitToneMode().