Руководство по разработке коррекции цвета

LCC Unity SDK поддерживает операции редактирования, такие как подсветка, обрезка и коррекция цвета, на сценах 3DGS. Это руководство знакомит с операциями коррекции цвета: выделение области через 2D-проецируемые текстуры, 3D-геометрию или их смесь и настройка яркости, насыщенности и контрастности выбранной области, с поддержкой обычного выделения и инвертированного выделения.

Примечание:
Текущая функция коррекции цвета — это только эффект отображения во время выполнения; она никак не изменяет исходный файл данных и не поддерживает сохранение или экспорт результата редактирования. Если нужно выполнить коррекцию цвета, обрезку и сохранить данные, используйте программный инструмент XGRIDS LCC Editor.
Если вы не хотите изменять данные, можно также записать операции и воспроизвести их (выполнить настройки) после следующего завершения загрузки данных.

Предварительные требования

Для коррекции цвета сцены через SDK требуются следующие условия:

Войдите в состояние редактирования перед загрузкой данных. По умолчанию SDK находится в состоянии просмотра (View), которое обеспечивает наилучшую производительность и рекомендуется для обычного просмотра. Для выполнения операций редактирования, таких как коррекция цвета, переключитесь в состояние редактирования через SetEditorMode(true) перед вызовом Load. Этот метод действует только если вызван до загрузки всех данных.
Выполняйте операцию коррекции цвета после завершения загрузки данных. Интерфейс коррекции цвета должен вызываться после полной загрузки данных сцены.

Шаг 1: Настройте сцену

Подготовьте GameObject, необходимые для коррекции цвета, в сцене:

Main Camera: камера сцены; 2D-коррекция цвета использует её матрицы вида и проекции.
LCCManager: пустой GameObject с нормализованным Transform, с добавленным скриптом LCCManager.
LCCRenderer: пустой GameObject с Transform, заданным как Rotation.x = -90, Scale.x = -1 (выровнен с системой координат данных LCC), используемый для прикрепления скрипта Tone, написанного позже.
3D-геометрия выделения (необязательно): вспомогательные объекты для 3D-коррекции цвета. В примере подготовлен один Cube (Box1); перемещение и масштабирование управляет позицией и размером выделения 3D-коррекции цвета.

Примечание:
По настройкам, связанным с камерой рендеринга, GameObject LCCManager и LCCRenderer, см. соответствующие разделы Руководство по быстрому старту для PC и Руководство по оптимизации настроек проекта.

Шаг 2: Разберитесь в структуре данных

Коррекция цвета использует структуру данных ToneMix, которая может одновременно описывать выделение 2D-текстурой и выделение 3D-геометрией и несёт параметры коррекции цвета. Используемые перечисления и структуры следующие.

public enum SelectMode    { normal, invert, clip }  // обычное выделение, инверсия, обрезка в реальном времени
public enum OperationMode { normal, erase }         // обычное выделение, стирание выделения
public enum ShapeType     { box, sphere }           // выделение 3D-боксом, выделение 3D-сферой
public enum EditType      { Edit2D, Edit3D }        // 2D-редактирование, 3D-редактирование

// выделение для коррекции цвета
public struct ToneMix
{
    public EditType editType;       // тип редактирования (обязательное; определяет, используются ли поля 2D или 3D)
    public Texture2D texture;       // 2D-текстура маски (используется Edit2D)
    public Matrix4x4 mv;            // матрица вида камеры (используется Edit2D)
    public Matrix4x4 mvp;           // матрица вида-проекции камеры (используется Edit2D)
    public ShapeType type;          // тип геометрии (используется Edit3D)
    public Matrix4x4 invMat;        // обратная матрица геометрии (используется Edit3D)
    public OperationMode operation; // тип операции (используется Edit3D)
    public SelectMode mode;         // режим выделения (обязательное)

    public float brightness;        // яркость, диапазон [0, 3], по умолчанию 1.0
    public float saturation;        // насыщенность, диапазон [0, 3], по умолчанию 1.0
    public float contrast;          // контрастность, диапазон [0, 3], по умолчанию 1.0
    public int lutid;               // индекс таблицы LUT (зарезервировано), 0 означает не используется
}

О списке коррекции цвета следует отметить три момента:

Список упорядочен. Будь то 2D или 3D, записи в списке вступают в силу по порядку; убедитесь, что порядок добавления соответствует вашим ожиданиям.
Инверсия должна нести данные коррекции цвета. Это самое критичное отличие коррекции цвета от подсветки/обрезки — инверсия подсветки/обрезки является чистой командой и не нуждается в связывании с данными; но запись инверсии коррекции цвета, помимо mode = SelectMode.invert, должна также задать brightness, saturation и contrast, чтобы указать эффект коррекции цвета для области вне выделения.
Максимальное количество записей в одном списке — 255. При превышении возвращается код ошибки.

Шаг 3: Разберитесь в API коррекции цвета

Все интерфейсы, связанные с коррекцией цвета, предоставляются LCCManager, включая один метод SetTone и один метод выхода.

SetTone

// Возвращаемое значение: int
// 0: успех
// 1: список равен null или имеет 0 элементов
// 2: элементы списка превышают максимум 255
public int SetTone(List<ToneMix> _Mix)

Выполняет коррекцию цвета выбранной области, поддерживая настройку яркости, насыщенности и контрастности. Записи 2D-текстур и записи 3D-геометрии можно смешивать в одном списке.

QuitToneMode

// Возвращаемое значение: void
public void QuitToneMode()

Выходит из режима коррекции цвета и восстанавливает исходные цвета сцены.

Совет:
При переключении параметров коррекции цвета или очистке текущей коррекции сначала вызовите QuitToneMode(), а затем задайте новую коррекцию цвета.

Шаг 4: Спецификация 2D-текстуры маски

2D-коррекция цвета описывает выделение через текстуру маски, поддерживая различные способы выделения, такие как четырёхугольники, треугольники, кисти и лассо — просто пометьте соответствующие пиксели в текстуре выбранным значением. При использовании 2D-операций камера должна быть заблокирована, а текстура помечена с фиксированной точки обзора. Для текстуры и значений пикселей действуют следующие соглашения:

Текстура фиксирована на 1024 × 1024, R8 один канал, без Mipmap, точечная фильтрация (FilterMode.Point) и зажатое сэмплирование (TextureWrapMode.Clamp).
Соглашения о значениях пикселей:

Значение пикселя	Значение
`128`	По умолчанию (не выделено)
`240`	Выделено
`180`	Снять выделение (стереть уже выделенную область)
`0`	Обрезка

В сценарии коррекции цвета обычно используются только два значения — 128 (по умолчанию) и 240 (выделено).

Шаг 5: Напишите скрипт

Создайте новый скрипт C# с именем Tone.cs. Сначала завершите базовый каркас: в Start войдите в состояние редактирования и загрузите данные; после завершения загрузки установите флаг загрузки для проверки последующими методами коррекции цвета.

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

        // Входим в режим редактирования; должен вызываться перед Load
        m_manager.SetEditorMode(true);

        m_renderer = m_manager.GetRender(this.transform);
        if (m_renderer == null)
            Debug.LogError("GetRender завершился ошибкой: проверьте, правильно ли задан manager и валиден ли путь к файлу.");

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

    private void onLoadProgress(float value)
    {
        Debug.Log($"прогресс загрузки: {value}");
    }

    private void onLoadCallback()
    {
        Debug.Log("данные загружены !!!");
        m_isLoaded = true;
    }

    // ниже методы коррекции цвета
}

Примечание:
SetEditorMode(true) должен вызываться перед Load, чтобы вступить в силу; а SetTone должен вызываться после завершения загрузки данных (после срабатывания обратного вызова onLoadCallback). Три слайдера m_brightness, m_saturation и m_contrast используются для динамической настройки параметров коррекции цвета во время выполнения и могут использоваться по мере необходимости.

Шаг 6: Прикрепите скрипт и настройте свойства

Прикрепите скрипт Tone.cs к GameObject LCCRenderer.
В окне Inspector перетащите GameObject LCCManager на свойство Manager скрипта.
Заполните путь к файлу LCC в свойстве File Path.
Перетащите Box1 в сцене на свойство Box1 скрипта и перетащите три слайдера на свойства Brightness, Saturation и Contrast соответственно — для 3D-коррекции цвета и настройки параметров во время выполнения.

Настройка свойств скрипта Tone в Inspector

Шаг 7: Примеры операций коррекции цвета

Добавьте методы ниже в класс Tone и вызовите соответствующий метод после запуска и после завершения загрузки данных.

Обычная коррекция цвета

Создайте текстуру маски R8, пометьте пиксели для коррекции цвета значением 240, а остальные — 128, затем создайте ToneMix с матрицами камеры, задайте brightness, saturation и contrast и добавьте его в список.

public void onTone()
{
    // Размер текстуры фиксирован 1024*1024; остальные свойства оставьте такими же, как в примере
    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 означает по умолчанию, 240 означает выделено, 0 означает обрезку
        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);
}

Объяснение кода: создаётся текстура маски, которая выделяет верхнюю половину экрана (начало координат экрана — нижний левый угол), и к выбранной области применяется коррекция цвета с яркостью 2.0, насыщенностью 2.0 и контрастностью 0.4. Эффект примера следующий.

При фактическом использовании вы можете использовать различные инструменты выделения, такие как прямоугольники, треугольники, кисти и лассо, чтобы выбрать соответствующие позиции на маске, а также динамически передавать значения brightness, saturation и contrast через слайдеры.

Эффект обычной коррекции цвета

Инвертированная коррекция цвета

Инверсия коррекции цвета отличается от подсветки и обрезки: запись инверсии, помимо задания mode = SelectMode.invert, должна нести данные коррекции цвета (brightness, saturation, contrast), чтобы указать эффект коррекции цвета для области вне выделения. На основе обычной коррекции цвета выше просто добавьте запись инверсии.

public void onToneInvert()
{
    // Размер текстуры фиксирован 1024*1024; остальные свойства оставьте такими же, как в примере
    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 означает по умолчанию, 240 означает выделено, 0 означает обрезку
        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);

    // Инверсия: должна нести данные коррекции цвета (яркость/насыщенность/контрастность), а не чистую команду
    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);
}

Объяснение кода: поверх обычной коррекции цвета добавляется запись инверсии, применяющая коррекцию цвета с яркостью 0.5, насыщенностью 0.5 и контрастностью 2.0 к области вне выделения. Таким образом, внутри и вне выделения можно применить разные параметры коррекции цвета. Эффект примера следующий.

Эффект инвертированной коррекции цвета

Примечание:
Инверсия подсветки и обрезки — это чистая команда: достаточно добавить запись с mode = SelectMode.invert, без других данных. Но запись инверсии коррекции цвета обязана также задать brightness, saturation и contrast; иначе инвертированная область использует значения по умолчанию (1.0) и не достигает ожидаемого эффекта.

Шаг 8: Выход из коррекции цвета

Вызовите QuitToneMode() для очистки текущей коррекции цвета и восстановления исходных цветов сцены.

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

Ключевые шаги

Ключевые шаги для коррекции цвета сцены 3DGS:

Вызовите SetEditorMode(true) перед загрузкой данных, чтобы войти в состояние редактирования.
Вызовите SetTone после завершения загрузки данных (после срабатывания обратного вызова onLoadCallback или через кнопку/событие).
Управляйте эффектом коррекции цвета через brightness, saturation и contrast структуры ToneMix (диапазон [0, 3], по умолчанию 1.0) и убедитесь, что порядок добавления в список коррекции цвета соответствует вашим ожиданиям.
2D-текстура маски фиксирована на 1024 × 1024, R8 один канал; заполняйте значения пикселей согласно соглашению (128 по умолчанию, 240 выделено).
Инверсия коррекции цвета (SelectMode.invert) должна нести данные brightness, saturation и contrast — это ключевое отличие от инверсии подсветки/обрезки.
При очистке или переключении коррекции цвета сначала вызовите QuitToneMode().