Guía de desarrollo de ajuste de color

El LCC Unity SDK admite operaciones de edición como el resaltado, el recorte y el ajuste de color en escenas 3DGS. Esta guía presenta las operaciones de ajuste de color: seleccionar un área mediante texturas proyectadas 2D, geometría 3D o una mezcla de ambas, y ajustar el brillo, la saturación y el contraste del área seleccionada, con compatibilidad para la selección normal y la selección invertida.

Nota:
La función de ajuste de color actual es solo un efecto de visualización en tiempo de ejecución; no modifica el archivo de datos original de ninguna manera y no admite guardar ni exportar el resultado de la edición. Si necesitas ajustar el color, recortar y guardar datos, usa la herramienta de software XGRIDS LCC Editor.
Si no quieres modificar los datos, también puedes registrar las operaciones y reproducirlas (ejecutar los ajustes) después de que los datos terminen de cargarse la próxima vez.

Requisitos previos

Ajustar el color de una escena a través del SDK requiere las siguientes condiciones:

Entrar en el estado de edición antes de cargar los datos. El SDK está en el estado de navegación (View) por defecto, que proporciona el mejor rendimiento y se recomienda para la navegación normal. Para realizar operaciones de edición como el ajuste de color, cambia al estado de edición mediante SetEditorMode(true) antes de llamar a Load. Este método solo surte efecto si se llama antes de cargar todos los datos.
Realizar la operación de ajuste de color después de que los datos terminen de cargarse. La interfaz de ajuste de color debe llamarse después de que los datos de la escena se hayan cargado por completo.

Paso 1: Configurar la escena

Prepara los GameObjects necesarios para el ajuste de color en la escena:

Main Camera: la cámara de la escena; el ajuste de color 2D usa sus matrices de vista y proyección.
LCCManager: un GameObject vacío con un Transform normalizado, con el script LCCManager añadido.
LCCRenderer: un GameObject vacío con el Transform establecido como Rotation.x = -90, Scale.x = -1 (alineado con el sistema de coordenadas de los datos LCC), usado para adjuntar el script Tone escrito más adelante.
Geometría de selección 3D (opcional): objetos auxiliares para el ajuste de color 3D. El ejemplo prepara un Cube (Box1); moverlo y escalarlo controla la posición y el tamaño de la selección de ajuste de color 3D.

Nota:
Para los ajustes relacionados con los GameObjects de la cámara de renderizado, LCCManager y LCCRenderer, consulta las secciones relevantes de Guía de inicio rápido para PC y Guía de optimización de ajustes del proyecto.

Paso 2: Comprender la estructura de datos

El ajuste de color usa la estructura de datos ToneMix, que puede describir tanto una selección por textura 2D como una selección por geometría 3D al mismo tiempo, y lleva los parámetros de ajuste de color. Los enums y structs usados son los siguientes.

public enum SelectMode    { normal, invert, clip }  // selección normal, inversión, recorte en tiempo real
public enum OperationMode { normal, erase }         // selección normal, borrar selección
public enum ShapeType     { box, sphere }           // selección 3D Box, selección 3D Sphere
public enum EditType      { Edit2D, Edit3D }        // edición 2D, edición 3D

// Selección de ajuste de color
public struct ToneMix
{
    public EditType editType;       // tipo de edición (obligatorio; determina si se usan los campos 2D o 3D)
    public Texture2D texture;       // textura de máscara 2D (usada por Edit2D)
    public Matrix4x4 mv;            // matriz de vista de la cámara (usada por Edit2D)
    public Matrix4x4 mvp;           // matriz de vista-proyección de la cámara (usada por Edit2D)
    public ShapeType type;          // tipo de geometría (usado por Edit3D)
    public Matrix4x4 invMat;        // matriz inversa de la geometría (usada por Edit3D)
    public OperationMode operation; // tipo de operación (usado por Edit3D)
    public SelectMode mode;         // modo de selección (obligatorio)

    public float brightness;        // brillo, rango [0, 3], por defecto 1.0
    public float saturation;        // saturación, rango [0, 3], por defecto 1.0
    public float contrast;          // contraste, rango [0, 3], por defecto 1.0
    public int lutid;               // índice de la tabla LUT (reservado), 0 significa no usado
}

Hay tres puntos a tener en cuenta sobre la lista de ajuste de color:

La lista está ordenada. Ya sea 2D o 3D, las entradas de la lista surten efecto en orden; asegúrate de que el orden de adición coincide con tu expectativa.
Invertir debe llevar datos de ajuste de color. Esta es la diferencia más crítica entre el ajuste de color y el resaltado/recorte — la inversión del resaltado/recorte es un comando puro y no necesita asociarse con datos; pero la entrada de inversión del ajuste de color, además de mode = SelectMode.invert, también debe establecer brightness, saturation y contrast, para especificar el efecto de ajuste de color del área fuera de la selección.
El número máximo de entradas en una sola lista es 255. Superarlo devuelve un código de error.

Paso 3: Comprender las API de ajuste de color

Todas las interfaces relacionadas con el ajuste de color las proporciona LCCManager, incluido un método SetTone y un método de salida.

SetTone

// Valor de retorno: int
// 0: éxito
// 1: la lista es null o tiene 0 elementos
// 2: los elementos de la lista superan el máximo de 255
public int SetTone(List<ToneMix> _Mix)

Realiza el ajuste de color en el área seleccionada, admitiendo ajustes de brillo, saturación y contraste. Las entradas de textura 2D y las entradas de geometría 3D pueden mezclarse en la misma lista.

QuitToneMode

// Valor de retorno: void
public void QuitToneMode()

Sale del modo de ajuste de color y restaura los colores originales de la escena.

Consejo:
Al cambiar los parámetros de ajuste de color o limpiar el ajuste de color actual, llama primero a QuitToneMode() y luego establece el nuevo ajuste de color.

Paso 4: Especificación de la textura de máscara 2D

El ajuste de color 2D describe la selección mediante una textura de máscara, admitiendo varios métodos de selección como cuadriláteros, triángulos, pinceles y lazos — simplemente marca los píxeles correspondientes en la textura con el valor seleccionado. Al usar operaciones 2D, la cámara debe estar bloqueada y la textura marcada desde un punto de vista fijo. La textura y los valores de píxel tienen las siguientes convenciones:

La textura está fijada en 1024 × 1024, R8 de un solo canal, sin Mipmap, con filtrado por puntos (FilterMode.Point) y muestreo limitado (TextureWrapMode.Clamp).
Convenciones de valor de píxel:

Valor de píxel	Significado
`128`	Por defecto (no seleccionado)
`240`	Seleccionado
`180`	Deseleccionar (borrar el área ya seleccionada)
`0`	Recorte

En un escenario de ajuste de color, normalmente solo se usan los dos valores 128 (por defecto) y 240 (seleccionado).

Paso 5: Escribir el script

Crea un nuevo script C# llamado Tone.cs. Primero completa el esqueleto básico: en Start, entra en el estado de edición y carga los datos; después de que la carga finalice, establece el indicador de carga para que los métodos de ajuste de color posteriores lo comprueben.

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 en el modo de edición; debe llamarse antes de Load
        m_manager.SetEditorMode(true);

        m_renderer = m_manager.GetRender(this.transform);
        if (m_renderer == null)
            Debug.LogError("Error en GetRender, comprueba que el manager esté configurado correctamente y que la ruta del archivo sea válida.");

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

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

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

    // Métodos de ajuste de color a continuación
}

Nota:
SetEditorMode(true) debe llamarse antes de Load para surtir efecto; y SetTone debe llamarse después de que los datos terminen de cargarse (después de que se dispare la devolución de llamada onLoadCallback). Los tres sliders m_brightness, m_saturation y m_contrast se usan para ajustar dinámicamente los parámetros de ajuste de color en tiempo de ejecución y pueden usarse según sea necesario.

Paso 6: Adjuntar el script y establecer propiedades

Adjunta el script Tone.cs al GameObject LCCRenderer.
En la ventana Inspector, arrastra el GameObject LCCManager a la propiedad Manager del script.
Rellena la ruta del archivo LCC en la propiedad File Path.
Arrastra Box1 de la escena a la propiedad Box1 del script, y arrastra los tres sliders a las propiedades Brightness, Saturation y Contrast respectivamente, para el ajuste de color 3D y el ajuste de parámetros en tiempo de ejecución.

Establecer las propiedades del script Tone en el Inspector

Paso 7: Ejemplos de operación de ajuste de color

Añade los métodos siguientes a la clase Tone y llama al método correspondiente después de ejecutar y después de que los datos terminen de cargarse.

Ajuste de color normal

Construye una textura de máscara R8, marca los píxeles a ajustar el color como 240 y el resto como 128, luego construye ToneMix con las matrices de la cámara, establece brightness, saturation y contrast, y añádelo a la lista.

public void onTone()
{
    // El tamaño de la textura está fijado en 1024*1024; mantén las demás propiedades igual que el ejemplo
    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 por defecto, 240 significa seleccionado, 0 significa recorte
        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);
}

Explicación del código: se construye una textura de máscara que selecciona la mitad superior de la pantalla (el origen de la pantalla es la esquina inferior izquierda), y se aplica un ajuste de color de brillo 2.0, saturación 2.0 y contraste 0.4 al área seleccionada. El efecto del ejemplo es el siguiente.

En el uso real, puedes usar varias herramientas de selección como rectángulos, triángulos, pinceles y lazos para seleccionar las posiciones correspondientes en la máscara, y también pasar dinámicamente los valores de brightness, saturation y contrast mediante sliders.

Efecto de ajuste de color normal

Ajuste de color con inversión

La inversión del ajuste de color difiere del resaltado y el recorte: la entrada de inversión, además de establecer mode = SelectMode.invert, debe llevar datos de ajuste de color (brightness, saturation, contrast) para especificar el efecto de ajuste de color del área fuera de la selección. Sobre la base del ajuste de color normal anterior, simplemente añade una entrada de inversión.

public void onToneInvert()
{
    // El tamaño de la textura está fijado en 1024*1024; mantén las demás propiedades igual que el ejemplo
    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 por defecto, 240 significa seleccionado, 0 significa recorte
        else
            _values[i] = 240;
    }
    _texture.SetPixelData(_values, 0);

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

    // Ajuste de color de selección normal
    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);

    // Invertir: debe llevar datos de ajuste de color (brillo/saturación/contraste), no es 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);
}

Explicación del código: se añade una entrada de inversión sobre el ajuste de color normal, aplicando un ajuste de color de brillo 0.5, saturación 0.5 y contraste 2.0 al área fuera de la selección. De esta manera, se pueden aplicar diferentes parámetros de ajuste de color dentro y fuera de la selección. El efecto del ejemplo es el siguiente.

Efecto de ajuste de color con inversión

Nota:
La inversión del resaltado y el recorte es un comando puro: añadir una entrada con mode = SelectMode.invert es suficiente, sin requerir otros datos. Pero la entrada de inversión del ajuste de color debe establecer también brightness, saturation y contrast; de lo contrario, el área invertida usa los valores por defecto (1.0) y no logra el efecto esperado.

Paso 8: Salir del ajuste de color

Llama a QuitToneMode() para limpiar el ajuste de color actual y restaurar los colores originales de la escena.

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

Pasos clave

Los pasos clave para ajustar el color de una escena 3DGS:

Llama a SetEditorMode(true) antes de cargar los datos para entrar en el estado de edición.
Llama a SetTone después de que los datos terminen de cargarse (después de que se dispare la devolución de llamada onLoadCallback, o se active mediante un botón/evento).
Controla el efecto de ajuste de color mediante brightness, saturation y contrast de ToneMix (rango [0, 3], por defecto 1.0), y asegúrate de que el orden de adición de la lista de ajuste de color coincide con tu expectativa.
La textura de máscara 2D está fijada en 1024 × 1024, R8 de un solo canal; rellena los valores de píxel según la convención (128 por defecto, 240 seleccionado).
La inversión del ajuste de color (SelectMode.invert) debe llevar datos de brightness, saturation y contrast — esta es la diferencia clave con la inversión del resaltado/recorte.
Al limpiar o cambiar el ajuste de color, llama primero a QuitToneMode().