XGRIDSDocs

Przewodnik podświetlania

LCC Unity SDK obsługuje operacje edycji, takie jak podświetlanie i przycinanie, na scenach 3DGS. Ten przewodnik przedstawia operacje związane z podświetlaniem: zaznaczanie obszaru za pomocą rzutowanych tekstur 2D, geometrii 3D lub mieszanki obu, tak aby zaznaczony obszar był podświetlony, z obsługą zaznaczenia normalnego i zaznaczenia odwróconego.

Uwaga:

Obecna funkcja podświetlania jest tylko efektem wyświetlania w czasie działania; w żaden sposób nie modyfikuje oryginalnego pliku danych i nie obsługuje zapisywania ani eksportowania wyniku edycji. Jeśli potrzebujesz korekcji kolorów, przycinania i zapisywania danych, użyj narzędzia XGRIDS LCC Editor.

Jeśli nie chcesz modyfikować danych, możesz również zarejestrować operacje i odtworzyć je po ponownym zakończeniu ładowania danych.

Wymagania wstępne

Podświetlanie sceny przez SDK wymaga następujących warunków:

  1. Wejdź w stan edycji przed załadowaniem danych. SDK jest domyślnie w stanie przeglądania (View), który zapewnia najlepszą wydajność i jest zalecany do normalnego przeglądania. Aby wykonywać operacje edycji, takie jak podświetlanie, przełącz się w stan edycji przez SetEditorMode(true) przed wywołaniem Load. Ta metoda działa tylko wtedy, gdy zostanie wywołana przed załadowaniem wszystkich danych.
  2. Wykonaj operację podświetlania po zakończeniu ładowania danych. Interfejs podświetlania musi być wywołany po pełnym załadowaniu danych sceny.

Krok 1: Skonfiguruj scenę

Przygotuj GameObjects potrzebne do podświetlania w scenie, jak pokazano poniżej.

Struktura hierarchii sceny dla przykładu podświetlania

Struktura hierarchii sceny dla przykładu podświetlania

  • Kamera główna: kamera sceny; podświetlanie 2D używa jej macierzy widoku i rzutowania.
  • LCCManager: pusty GameObject ze znormalizowanym Transform, z dodanym skryptem LCCManager.
  • LCCRenderer: pusty GameObject z Transform ustawionym na Rotation.x = -90, Scale.x = -1 (wyrównany z układem współrzędnych danych LCC), używany do dołączenia skryptu Highlight napisanego później.
  • Geometria zaznaczenia 3D: obiekty pomocnicze do podświetlania 3D. Przykład przygotowuje 3 Sześciany (Box1, Box2, Box3) i 1 Kulę (Clipsphere); przesuwanie i skalowanie tych obiektów steruje pozycją i rozmiarem zaznaczenia podświetlenia.

Uwaga:

Ustawienia związane z kamerą renderującą, LCCManager i GameObject LCCRenderer znajdziesz w odpowiednich sekcjach Przewodnik szybkiego startu dla PC i Przewodnik optymalizacji ustawień projektu.

Geometria zaznaczenia używana do podświetlania 3D

Geometria zaznaczenia używana do podświetlania 3D (Box1 / Box2 / Box3 / Clipsphere)

Krok 2: Poznaj struktury danych

Podświetlanie obejmuje trzy metody operacji — 2D, 3D i mieszaną 2D/3D. Używane typy wyliczeniowe i struktury są następujące.

public enum SelectMode    { normal, invert, clip }  // zaznaczenie normalne, odwrócenie, przycinanie w czasie rzeczywistym
public enum OperationMode { normal, erase }         // zaznaczenie normalne, wymazywanie zaznaczenia
public enum ShapeType     { box, sphere }           // zaznaczenie 3D Box, zaznaczenie 3D Sphere
public enum EditType      { Edit2D, Edit3D }        // edycja 2D, edycja 3D

// zaznaczenie teksturą 2D
public struct Data2D
{
    public Texture2D texture;   // tekstura maski 2D
    public Matrix4x4 mv;        // macierz widoku kamery
    public Matrix4x4 mvp;       // macierz widokowo-rzutowa kamery
    public SelectMode mode;     // tryb zaznaczenia
}

// zaznaczenie geometrią 3D
public struct Data3D
{
    public ShapeType type;          // typ geometrii (box / sphere)
    public Matrix4x4 invMat;        // macierz świata-do-lokalnego (odwrotna) geometrii
    public OperationMode operation; // typ operacji (suma normalna / różnica wymazywania)
    public SelectMode mode;         // tryb zaznaczenia
}

// zaznaczenie mieszane 2D / 3D
public struct DataMix
{
    public EditType editType;       // typ edycji (wymagany; określa, czy używane są pola 2D czy 3D)
    public Texture2D texture;       // tekstura maski 2D (używana przez Edit2D)
    public Matrix4x4 mv;            // macierz widoku kamery (używana przez Edit2D)
    public Matrix4x4 mvp;           // macierz widokowo-rzutowa kamery (używana przez Edit2D)
    public ShapeType type;          // typ geometrii (używany przez Edit3D)
    public Matrix4x4 invMat;        // macierz odwrotna geometrii (używana przez Edit3D)
    public OperationMode operation; // typ operacji (używany przez Edit3D)
    public SelectMode mode;         // tryb zaznaczenia (wymagany)
}

Istnieją trzy punkty do odnotowania na temat listy zaznaczeń:

  1. Lista jest uporządkowana. Niezależnie od tego, czy 2D czy 3D, wpisy na liście działają w kolejności; upewnij się, że kolejność dodawania odpowiada Twoim oczekiwaniom.
  2. Odwrócenie jest poleceniem operacji i nie musi być powiązane z konkretnymi danymi zaznaczenia. Po prostu dołącz wpis z mode = SelectMode.invert, aby odwrócić aktualnie zaznaczony obszar.
  3. Maksymalna liczba wpisów na jednej liście to 255. Przekroczenie jej zwraca kod błędu.

Krok 3: Poznaj API podświetlania

Wszystkie interfejsy związane z podświetlaniem są udostępniane przez LCCManager, w tym trzy przeciążenia SetHighlight i jedna metoda wyjścia.

SetHighlight (podświetlanie teksturą 2D)

// Wartość zwracana: int
// 0: sukces
// 1: lista jest null lub ma 0 elementów
// 2: elementy listy przekraczają maksimum 255
public int SetHighlight(List<Data2D> _2Ds)

Podświetla scenę za pomocą rzutowanej tekstury maski 2D; część poza podświetlonym obszarem jest przyciemniana.

SetHighlight (podświetlanie geometrią 3D)

// Wartość zwracana: int
// 0: sukces
// 1: lista jest null lub ma 0 elementów
// 2: elementy listy przekraczają maksimum 255
// 3: liczba geometrii zaznaczenia wynosi 0
public int SetHighlight(List<Data3D> _3Ds)

Definiuje obszar podświetlenia za pomocą geometrii 3D (prostopadłościan, sześcian, kula), obsługując kombinacje sumy i różnicy. Wymagana jest co najmniej jedna geometria z operation == OperationMode.normal.

SetHighlight (podświetlanie w trybie mieszanym)

// Wartość zwracana: int
// 0: sukces
// 1: lista jest null lub ma 0 elementów
// 2: elementy listy przekraczają maksimum 255
public int SetHighlight(List<DataMix> _Mix)

Definiuje obszar podświetlenia za pomocą tekstur 2D i geometrii 3D jednocześnie; każdy wpis określa, czy jest przetwarzany jako 2D czy 3D, przez editType.

QuitHighlightMode

// Wartość zwracana: void
public void QuitHighlightMode()

Wychodzi z trybu podświetlania i przywraca normalne wyświetlanie sceny.

Wskazówka:

Trzy przeciążenia SetHighlight są wzajemnie wykluczające. Przy przełączaniu metod podświetlania lub czyszczeniu bieżącego podświetlenia najpierw wywołaj QuitHighlightMode(), a następnie ustaw nowe podświetlenie.

Krok 4: Specyfikacja tekstury maski 2D

Podświetlanie 2D opisuje zaznaczenie przez teksturę maski, obsługując różne metody zaznaczania, takie jak czworokąty, trójkąty, pędzle i lassa — po prostu oznacz odpowiednie piksele w teksturze wartością zaznaczenia. Przy operacjach 2D kamera powinna być zablokowana, a tekstura oznaczana ze stałego punktu widzenia. Tekstura i wartości pikseli mają następujące konwencje:

  • Tekstura jest stała 1024 × 1024, R8 jednokanałowa, bez Mipmap, filtrowanie punktowe (FilterMode.Point) i próbkowanie z przycinaniem (TextureWrapMode.Clamp).
  • Konwencje wartości pikseli:
Wartość pikselaZnaczenie
128Domyślna (niezaznaczone)
240Zaznaczone
180Odznacz (wymaż już zaznaczony obszar)
0Przycinanie

W scenariuszu podświetlania zwykle używane są tylko dwie wartości: 128 (domyślna) i 240 (zaznaczone).

Krok 5: Napisz skrypt

Utwórz nowy skrypt C# o nazwie Highlight.cs. Najpierw ukończ podstawowy szkielet: w Start wejdź w stan edycji i załaduj dane; po zakończeniu ładowania ustaw flagę ładowania do sprawdzenia przez kolejne metody podświetlania.

using LCCCore;
using System.Collections.Generic;
using UnityEngine;

public class Highlight : MonoBehaviour
{
    public LCCManager m_manager;
    public string m_FilePath;
    public GameObject m_Box1;
    public GameObject m_Box2;
    public GameObject m_Box3;
    public GameObject m_Clipsphere;

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

        // Wejdź w tryb edycji; musi być wywołane przed Load
        m_manager.SetEditorMode(true);

        m_renderer = m_manager.GetRender(this.transform);
        if (m_renderer == null)
            Debug.LogError("GetRender nie powiódł się; sprawdź, czy menedżer jest ustawiony poprawnie i czy ścieżka pliku jest prawidłowa.");

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

    private void onLoadProgress(float value)
    {
        Debug.Log($"postęp ładowania: {value}");
    }

    private void onLoadCallback()
    {
        Debug.Log("dane załadowane !!!");
        m_isLoaded = true;
    }

    // metody podświetlania 2D / 3D / mieszane poniżej
}

Uwaga:

SetEditorMode(true) musi być wywołane przed Load, aby zadziałało; a SetHighlight musi być wywołane po zakończeniu ładowania danych (po wywołaniu zwrotnym onLoadCallback).

Krok 6: Dołącz skrypt i ustaw właściwości

  1. Dołącz skrypt Highlight.cs do GameObject LCCRenderer.
  2. W oknie Inspektor przeciągnij GameObject LCCManager na właściwość Manager skryptu.
  3. Wpisz ścieżkę pliku LCC we właściwości File Path.
  4. Przeciągnij Box1, Box2, Box3 i Clipsphere ze sceny odpowiednio na odpowiadające właściwości skryptu.
Ustaw właściwości skryptu Highlight w Inspektorze

Ustaw właściwości skryptu Highlight w Inspektorze

Krok 7: Przykłady operacji podświetlania

Dodaj poniższe metody do klasy Highlight i wywołaj odpowiednią metodę po uruchomieniu i po zakończeniu ładowania danych.

Podświetlanie teksturą 2D

Skonstruuj dwie tekstury maski R8, oznacz piksele do podświetlenia jako 240, a resztę jako 128, następnie skonstruuj Data2D z macierzami kamery i dodaj je do listy.

public void on2DHighlight()
{
    // Rozmiar tekstury jest stały 1024*1024; zachowaj pozostałe właściwości tak jak w przykładzie
    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] = 240;    // 240 oznacza zaznaczone, 128 oznacza domyślne, 0 oznacza przycinanie
        else
            _values[i] = 128;
    }
    _texture.SetPixelData(_values, 0);

    Texture2D _texture2 = new Texture2D(1024, 1024, TextureFormat.R8, false);
    _texture2.filterMode = FilterMode.Point;
    _texture2.wrapMode = TextureWrapMode.Clamp;
    byte[] _values2 = new byte[_count];
    for (int i = 0; i < _count; i++)
    {
        if (i > _count * 0.75 && i < _count * 0.9)
            _values2[i] = 240;
        else
            _values2[i] = 128;
    }
    _texture2.SetPixelData(_values2, 0);

    List<Data2D> _2Ds = new List<Data2D>();
    Data2D _2d01 = new Data2D();
    _2d01.mv = m_camera.worldToCameraMatrix;
    _2d01.texture = _texture;
    _2d01.mode = SelectMode.normal;
    _2d01.mvp = GL.GetGPUProjectionMatrix(m_camera.projectionMatrix, true) * m_camera.worldToCameraMatrix;
    _2Ds.Add(_2d01);

    Data2D _2d02 = new Data2D();
    _2d02.mv = m_camera.worldToCameraMatrix;
    _2d02.texture = _texture2;
    _2d02.mode = SelectMode.normal;
    _2d02.mvp = GL.GetGPUProjectionMatrix(m_camera.projectionMatrix, true) * m_camera.worldToCameraMatrix;
    _2Ds.Add(_2d02);

    m_manager.SetHighlight(_2Ds);
}

Wyjaśnienie kodu: budowane są dwie tekstury maski. Pierwsza maska zaznacza dolną połowę ekranu (początek ekranu to lewy dolny róg), a druga maska zaznacza region od 0.75 do 0.9 górnej połowy ekranu. Przykładowy efekt jest następujący.

W rzeczywistym użyciu możesz używać różnych narzędzi zaznaczania, takich jak prostokąty, trójkąty, pędzle i lassa, aby zaznaczyć odpowiednie pozycje na masce.

Efekt podświetlenia teksturą 2D

Efekt podświetlenia teksturą 2D

Podświetlanie geometrią 3D

Użyj worldToLocalMatrix geometrii jako macierzy odwrotnej zaznaczenia, łącz sumę (normal) i różnicę (erase) przez operation, a odwrócenie zaznaczenia zaimplementuj przez wpis z mode = SelectMode.invert.

public void on3DHighlight()
{
    List<Data3D> _3Ds = new List<Data3D>();
    var _mat1 = m_Box1.transform.worldToLocalMatrix;
    var _mat2 = m_Box2.transform.worldToLocalMatrix;
    var _mat3 = m_Box3.transform.worldToLocalMatrix;
    var _mat4 = m_Clipsphere.transform.worldToLocalMatrix;

    // Zaznaczenie Box
    Data3D _3d01 = new Data3D();
    _3d01.type = ShapeType.box;
    _3d01.operation = OperationMode.normal;
    _3d01.mode = SelectMode.normal;
    _3d01.invMat = _mat1;
    _3Ds.Add(_3d01);

    Data3D _3d02 = new Data3D();
    _3d02.type = ShapeType.box;
    _3d02.operation = OperationMode.normal;
    _3d02.mode = SelectMode.normal;
    _3d02.invMat = _mat2;
    _3Ds.Add(_3d02);

    // Zaznaczenie Sphere
    Data3D _3d04 = new Data3D();
    _3d04.type = ShapeType.sphere;
    _3d04.operation = OperationMode.normal;
    _3d04.mode = SelectMode.normal;
    _3d04.invMat = _mat4;
    _3Ds.Add(_3d04);

    // Wymaż Box/Sphere (różnica)
    Data3D _3d03 = new Data3D();
    _3d03.type = ShapeType.box;
    _3d03.operation = OperationMode.erase;
    _3d03.mode = SelectMode.normal;
    _3d03.invMat = _mat3;
    _3Ds.Add(_3d03);

    // Odwrócenie
    //Data3D _3d05 = new Data3D();
    //_3d05.mode = SelectMode.invert;
    //_3Ds.Add(_3d05);

    m_manager.SetHighlight(_3Ds);
}

Wyjaśnienie kodu: używane są 4 geometrie, gdzie Box1, Box2 i Sphere to zaznaczenia normalne, a Box3 to zaznaczenie wymazywania, czyli wymazywanie wcześniej zaznaczonego obszaru. Przy zakomentowanym kodzie związanym z odwróceniem przykładowy efekt jest następujący:

Efekt podświetlenia geometrią 3D

Efekt podświetlenia geometrią 3D

Odkomentuj kod odwrócenia, aby odwrócenie zadziałało; przykładowy efekt jest następujący. Odwrócenie przerzuca wcześniej zaznaczony obszar; jest to polecenie i nie musi być powiązane z danymi operacji.

W szczególności zwróć uwagę, że lista jest uporządkowana; różne kroki operacji dają różne efekty końcowe.

Efekt podświetlenia geometrią 3D + odwrócenie

Efekt podświetlenia geometrią 3D + odwrócenie

Podświetlanie w trybie mieszanym

Mieszaj wpisy tekstury 2D i geometrii 3D na tej samej liście; każdy wpis określa swoją metodę przetwarzania przez editType.

public void onMixHighlight()
{
    // --- Przygotowanie zaznaczenia 2D ---
    // Rozmiar tekstury jest stały 1024*1024; zachowaj pozostałe właściwości tak jak w przykładzie
    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 oznacza domyślne, 240 oznacza zaznaczone, 0 oznacza przycinanie
        else
            _values[i] = 240;
    }
    _texture.SetPixelData(_values, 0);

    List<DataMix> _Mixs = new List<DataMix>();
    DataMix _mix01 = new DataMix();
    _mix01.editType = EditType.Edit2D;
    _mix01.mv = m_camera.worldToCameraMatrix;
    _mix01.texture = _texture;
    _mix01.mode = SelectMode.normal;
    _mix01.mvp = GL.GetGPUProjectionMatrix(m_camera.projectionMatrix, true) * m_camera.worldToCameraMatrix;
    _Mixs.Add(_mix01);

    // --- Przygotowanie zaznaczenia 3D ---
    var _mat1 = m_Box1.transform.worldToLocalMatrix;
    var _mat2 = m_Box2.transform.worldToLocalMatrix;
    var _mat3 = m_Box3.transform.worldToLocalMatrix;
    var _mat4 = m_Clipsphere.transform.worldToLocalMatrix;

    // Zaznaczenie Box
    DataMix _mix02 = new DataMix();
    _mix02.editType = EditType.Edit3D;
    _mix02.type = ShapeType.box;
    _mix02.operation = OperationMode.normal;
    _mix02.mode = SelectMode.normal;
    _mix02.invMat = _mat1;
    _Mixs.Add(_mix02);

    DataMix _mix03 = new DataMix();
    _mix03.editType = EditType.Edit3D;
    _mix03.type = ShapeType.box;
    _mix03.operation = OperationMode.normal;
    _mix03.mode = SelectMode.normal;
    _mix03.invMat = _mat2;
    _Mixs.Add(_mix03);

    // Zaznaczenie Sphere
    DataMix _mix04 = new DataMix();
    _mix04.editType = EditType.Edit3D;
    _mix04.type = ShapeType.sphere;
    _mix04.operation = OperationMode.normal;
    _mix04.mode = SelectMode.normal;
    _mix04.invMat = _mat4;
    _Mixs.Add(_mix04);

    // Wymaż Box/Sphere (różnica)
    DataMix _mix05 = new DataMix();
    _mix05.editType = EditType.Edit3D;
    _mix05.type = ShapeType.box;
    _mix05.operation = OperationMode.erase;
    _mix05.mode = SelectMode.normal;
    _mix05.invMat = _mat3;
    _Mixs.Add(_mix05);

    // Odwrócenie (włącz w razie potrzeby)
    DataMix _mix06 = new DataMix();
    _mix06.editType = EditType.Edit3D;
    _mix06.type = ShapeType.box;
    _mix06.mode = SelectMode.invert;
    //_Mixs.Add(_mix06);

    m_manager.SetHighlight(_Mixs);
}

Wyjaśnienie kodu: używane są 4 geometrie i 1 tekstura 2D, co umożliwia mieszane przetwarzanie 2D i 3D. Przykładowy efekt jest następujący:

Efekt podświetlania w trybie mieszanym

Efekt podświetlania w trybie mieszanym

Krok 8: Wyjdź z podświetlania

Wywołaj QuitHighlightMode(), aby wyczyścić bieżące podświetlenie i przywrócić normalne wyświetlanie sceny.

public void onClearHighlight()
{
    m_manager.QuitHighlightMode();
}

Kluczowe kroki

Kluczowe kroki podświetlania sceny 3DGS:

  1. Wywołaj SetEditorMode(true) przed załadowaniem danych, aby wejść w stan edycji.
  2. Wywołaj SetHighlight po zakończeniu ładowania danych (po wywołaniu zwrotnym onLoadCallback lub wyzwolone przez przycisk/zdarzenie).
  3. Wybierz teksturę 2D, geometrię 3D lub tryb mieszany w zależności od potrzeb i upewnij się, że kolejność dodawania listy zaznaczeń odpowiada Twoim oczekiwaniom.
  4. Tekstura maski 2D jest stała 1024 × 1024, R8 jednokanałowa; wypełnij wartości pikseli zgodnie z konwencją (128 domyślne, 240 zaznaczone).
  5. Przy czyszczeniu lub przełączaniu podświetleń najpierw wywołaj QuitHighlightMode().