Guide de développement du réglage des couleurs

Le LCC Unity SDK prend en charge des opérations d'édition telles que le surlignage, la découpe et le réglage des couleurs sur les scènes 3DGS. Ce guide présente les opérations de réglage des couleurs : sélectionner une zone via des textures projetées 2D, une géométrie 3D, ou un mélange des deux, et ajuster la luminosité, la saturation et le contraste de la zone sélectionnée, avec prise en charge de la sélection normale et de la sélection inversée.

Remarque :
La fonctionnalité de réglage des couleurs actuelle n'est qu'un effet d'affichage à l'exécution ; elle ne modifie en aucune façon le fichier de données d'origine et ne prend pas en charge l'enregistrement ou l'exportation du résultat d'édition. Si vous devez ajuster les couleurs, découper et enregistrer des données, utilisez l'outil logiciel XGRIDS LCC Editor.
Si vous ne souhaitez pas modifier les données, vous pouvez également enregistrer les opérations et les rejouer (exécuter les réglages) après la fin du chargement des données la prochaine fois.

Prérequis

Le réglage des couleurs d'une scène via le SDK nécessite les conditions suivantes :

Entrer dans l'état d'édition avant de charger les données. Le SDK est dans l'état de navigation (View) par défaut, qui offre les meilleures performances et est recommandé pour la navigation normale. Pour effectuer des opérations d'édition telles que le réglage des couleurs, passez à l'état d'édition via SetEditorMode(true) avant d'appeler Load. Cette méthode ne prend effet que si elle est appelée avant le chargement de toutes les données.
Effectuer l'opération de réglage des couleurs après la fin du chargement des données. L'interface de réglage des couleurs doit être appelée après le chargement complet des données de la scène.

Étape 1 : Configurer la scène

Préparez les GameObjects nécessaires au réglage des couleurs dans la scène :

Caméra principale : la caméra de la scène ; le réglage des couleurs 2D utilise ses matrices de vue et de projection.
LCCManager : un GameObject vide avec un Transform normalisé, avec le script LCCManager ajouté.
LCCRenderer : un GameObject vide avec Transform défini sur Rotation.x = -90, Scale.x = -1 (aligné avec le système de coordonnées des données LCC), utilisé pour attacher le script Tone écrit plus tard.
Géométrie de sélection 3D (optionnelle) : objets auxiliaires pour le réglage des couleurs 3D. L'exemple prépare un Cube (Box1) ; le déplacer et le mettre à l'échelle contrôle la position et la taille de la sélection de réglage des couleurs 3D.

Remarque :
Pour les réglages liés à la caméra de rendu, aux GameObjects LCCManager et LCCRenderer, reportez-vous aux sections pertinentes du Guide de démarrage rapide PC et du Guide d'optimisation des paramètres de projet.

Étape 2 : Comprendre la structure de données

Le réglage des couleurs utilise la structure de données ToneMix, qui peut décrire à la fois une sélection par texture 2D et une sélection par géométrie 3D en même temps, et porte les paramètres de réglage des couleurs. Les enums et structs utilisés sont les suivants.

public enum SelectMode    { normal, invert, clip }  // sélection normale, inversion, découpe en temps réel
public enum OperationMode { normal, erase }         // sélection normale, effacement de la sélection
public enum ShapeType     { box, sphere }           // sélection par boîte 3D, sélection par sphère 3D
public enum EditType      { Edit2D, Edit3D }        // édition 2D, édition 3D

// Sélection de réglage des couleurs
public struct ToneMix
{
    public EditType editType;       // type d'édition (requis ; détermine si les champs 2D ou 3D sont utilisés)
    public Texture2D texture;       // texture de masque 2D (utilisée par Edit2D)
    public Matrix4x4 mv;            // matrice de vue de la caméra (utilisée par Edit2D)
    public Matrix4x4 mvp;           // matrice de vue-projection de la caméra (utilisée par Edit2D)
    public ShapeType type;          // type de géométrie (utilisé par Edit3D)
    public Matrix4x4 invMat;        // matrice inverse de la géométrie (utilisée par Edit3D)
    public OperationMode operation; // type d'opération (utilisé par Edit3D)
    public SelectMode mode;         // mode de sélection (requis)

    public float brightness;        // luminosité, plage [0, 3], défaut 1.0
    public float saturation;        // saturation, plage [0, 3], défaut 1.0
    public float contrast;          // contraste, plage [0, 3], défaut 1.0
    public int lutid;               // index de la table LUT (réservé), 0 signifie non utilisé
}

Il y a trois points à noter concernant la liste de réglage des couleurs :

La liste est ordonnée. Qu'il s'agisse de 2D ou de 3D, les entrées de la liste prennent effet dans l'ordre ; assurez-vous que l'ordre d'ajout correspond à votre attente.
Invert doit porter les données de réglage des couleurs. C'est la différence la plus critique entre le réglage des couleurs et le surlignage/découpe — l'inversion du surlignage/découpe est une commande pure et n'a pas besoin d'être associée à des données ; mais l'entrée d'inversion du réglage des couleurs, en plus de mode = SelectMode.invert, doit également définir brightness, saturation et contrast, pour spécifier l'effet de réglage des couleurs de la zone en dehors de la sélection.
Le nombre maximum d'entrées dans une seule liste est de 255. Le dépasser retourne un code d'erreur.

Étape 3 : Comprendre les API de réglage des couleurs

Toutes les interfaces liées au réglage des couleurs sont fournies par LCCManager, incluant une méthode SetTone et une méthode de sortie.

SetTone

// Valeur de retour : int
// 0 : succès
// 1 : la liste est nulle ou comporte 0 élément
// 2 : les éléments de la liste dépassent le maximum de 255
public int SetTone(List<ToneMix> _Mix)

Effectue un réglage des couleurs sur la zone sélectionnée, prenant en charge les réglages de luminosité, de saturation et de contraste. Les entrées de texture 2D et de géométrie 3D peuvent être mélangées dans la même liste.

QuitToneMode

// Valeur de retour : void
public void QuitToneMode()

Sort du mode de réglage des couleurs et restaure les couleurs d'origine de la scène.

Conseil :
Lors du changement des paramètres de réglage des couleurs ou de l'effacement du réglage des couleurs actuel, appelez d'abord QuitToneMode() puis définissez le nouveau réglage des couleurs.

Étape 4 : Spécification de la texture de masque 2D

Le réglage des couleurs 2D décrit la sélection via une texture de masque, prenant en charge diverses méthodes de sélection telles que les quadrilatères, les triangles, les pinceaux et les lassos — il suffit de marquer les pixels correspondants dans la texture avec la valeur sélectionnée. Lors de l'utilisation d'opérations 2D, la caméra doit être verrouillée et la texture marquée depuis un point de vue fixe. La texture et les valeurs de pixel suivent les conventions suivantes :

La texture est fixée à 1024 × 1024, R8 monocanal, sans Mipmap, filtrage par points (FilterMode.Point), et échantillonnage borné (TextureWrapMode.Clamp).
Conventions de valeurs de pixel :

Valeur de pixel	Signification
`128`	Défaut (non sélectionné)
`240`	Sélectionné
`180`	Désélectionner (effacer la zone déjà sélectionnée)
`0`	Découpe

Dans un scénario de réglage des couleurs, seules les deux valeurs 128 (défaut) et 240 (sélectionné) sont généralement utilisées.

Étape 5 : Écrire le script

Créez un nouveau script C# nommé Tone.cs. Complétez d'abord le squelette de base : dans Start, entrez dans l'état d'édition et chargez les données ; après la fin du chargement, définissez le drapeau de chargement que les méthodes de réglage des couleurs suivantes vérifieront.

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

        // Entrer en mode édition ; doit être appelé avant Load
        m_manager.SetEditorMode(true);

        m_renderer = m_manager.GetRender(this.transform);
        if (m_renderer == null)
            Debug.LogError("Échec de GetRender, vérifiez que le manager est correctement défini et que le chemin du fichier est valide.");

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

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

    private void onLoadCallback()
    {
        Debug.Log("données chargées !!!");
        m_isLoaded = true;
    }

    // Méthodes de réglage des couleurs ci-dessous
}

Remarque :
SetEditorMode(true) doit être appelé avant Load pour prendre effet ; et SetTone doit être appelé après la fin du chargement des données (après le déclenchement du callback onLoadCallback). Les trois sliders m_brightness, m_saturation et m_contrast sont utilisés pour ajuster dynamiquement les paramètres de réglage des couleurs à l'exécution et peuvent être utilisés selon les besoins.

Étape 6 : Attacher le script et définir les propriétés

Attachez le script Tone.cs au GameObject LCCRenderer.
Dans la fenêtre Inspecteur, faites glisser le GameObject LCCManager sur la propriété Manager du script.
Renseignez le chemin du fichier LCC dans la propriété File Path.
Faites glisser Box1 de la scène sur la propriété Box1 du script, et faites glisser les trois sliders sur les propriétés Brightness, Saturation et Contrast respectivement, pour le réglage des couleurs 3D et l'ajustement des paramètres à l'exécution.

Définir les propriétés du script Tone dans l'Inspecteur

Étape 7 : Exemples d'opération de réglage des couleurs

Ajoutez les méthodes ci-dessous à la classe Tone, et appelez la méthode correspondante après l'exécution et après la fin du chargement des données.

Réglage des couleurs normal

Construisez une texture de masque R8, marquez les pixels à ajuster comme 240 et le reste comme 128, puis construisez ToneMix avec les matrices de la caméra, définissez brightness, saturation et contrast, et ajoutez-le à la liste.

public void onTone()
{
    // La taille de la texture est fixée à 1024*1024 ; gardez les autres propriétés identiques à l'exemple
    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 signifie défaut, 240 signifie sélectionné, 0 signifie découpe
        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);
}

Explication du code : une texture de masque est construite qui sélectionne la moitié supérieure de l'écran (l'origine de l'écran est le coin inférieur gauche), et un réglage des couleurs de luminosité 2.0, saturation 2.0 et contraste 0.4 est appliqué à la zone sélectionnée. L'effet d'exemple est le suivant.

En utilisation réelle, vous pouvez utiliser divers outils de sélection tels que des rectangles, des triangles, des pinceaux et des lassos pour sélectionner les positions correspondantes sur le masque, et également transmettre dynamiquement les valeurs de brightness, saturation et contrast via des sliders.

Effet de réglage des couleurs normal

Réglage des couleurs inversé

L'inversion du réglage des couleurs diffère du surlignage et de la découpe : l'entrée d'inversion, en plus de définir mode = SelectMode.invert, doit porter les données de réglage des couleurs (brightness, saturation, contrast) pour spécifier l'effet de réglage des couleurs de la zone en dehors de la sélection. Sur la base du réglage des couleurs normal ci-dessus, ajoutez simplement une entrée d'inversion.

public void onToneInvert()
{
    // La taille de la texture est fixée à 1024*1024 ; gardez les autres propriétés identiques à l'exemple
    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 signifie défaut, 240 signifie sélectionné, 0 signifie découpe
        else
            _values[i] = 240;
    }
    _texture.SetPixelData(_values, 0);

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

    // Réglage des couleurs de sélection 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);

    // Inversion : doit porter les données de réglage des couleurs (brightness/saturation/contrast), pas une commande pure
    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);
}

Explication du code : une entrée d'inversion est ajoutée en plus du réglage des couleurs normal, appliquant un réglage des couleurs de luminosité 0.5, saturation 0.5 et contraste 2.0 à la zone en dehors de la sélection. De cette façon, différents paramètres de réglage des couleurs peuvent être appliqués à l'intérieur et à l'extérieur de la sélection. L'effet d'exemple est le suivant.

Effet de réglage des couleurs inversé

Remarque :
L'inversion du surlignage et de la découpe est une commande pure : ajouter une entrée avec mode = SelectMode.invert suffit, sans autre donnée requise. Mais l'entrée d'inversion du réglage des couleurs doit également définir brightness, saturation et contrast ; sinon la zone inversée utilise les valeurs par défaut (1.0) et n'obtient pas l'effet attendu.

Étape 8 : Sortir du réglage des couleurs

Appelez QuitToneMode() pour effacer le réglage des couleurs actuel et restaurer les couleurs d'origine de la scène.

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

Étapes clés

Les étapes clés pour ajuster les couleurs d'une scène 3DGS :

Appelez SetEditorMode(true) avant de charger les données pour entrer dans l'état d'édition.
Appelez SetTone après la fin du chargement des données (après le déclenchement du callback onLoadCallback, ou déclenché via un bouton/événement).
Contrôlez l'effet de réglage des couleurs via brightness, saturation et contrast de ToneMix (plage [0, 3], défaut 1.0), et assurez-vous que l'ordre d'ajout de la liste de réglage des couleurs correspond à votre attente.
La texture de masque 2D est fixée à 1024 × 1024, R8 monocanal ; remplissez les valeurs de pixel selon la convention (128 défaut, 240 sélectionné).
L'inversion du réglage des couleurs (SelectMode.invert) doit porter les données brightness, saturation et contrast — c'est la différence clé avec l'inversion du surlignage/découpe.
Lors de l'effacement ou du changement de réglage des couleurs, appelez d'abord QuitToneMode().