カラー調整開発ガイド
LCC Unity SDK は、3DGS シーンに対するハイライト、クリッピング、カラー調整などの編集操作に対応しています。このガイドでは、カラー調整操作を説明します。2D 投影テクスチャ、3D ジオメトリ、またはその組み合わせで領域を選択し、選択領域の明るさ、彩度、コントラストを調整します。通常選択と反転選択に対応しています。
注:
現在のカラー調整機能はランタイムの表示効果のみで、元のデータファイルを一切変更せず、編集結果の保存やエクスポートにも対応していません。データのカラー調整・クリッピング・保存が必要な場合は、XGRIDS LCC Editor ソフトウェアツールを使用してください。
データを変更したくない場合は、操作を記録しておき、次回データ読み込み完了後に再生(設定を実行)することもできます。
前提条件
SDK でシーンをカラー調整するには、以下の条件が必要です。
- データ読み込み前に編集状態に入る。 SDK はデフォルトで閲覧状態(View)で、最も高い性能を提供し、通常の閲覧に推奨されます。カラー調整などの編集操作を行うには、
Loadを呼び出す前にSetEditorMode(true)で編集状態に切り替えます。このメソッドはすべてのデータを読み込む前に呼び出した場合のみ有効です。 - データ読み込み完了後にカラー調整操作を行う。 カラー調整インターフェースは、シーンデータが完全に読み込まれた後に呼び出す必要があります。
手順 1:シーンをセットアップする
カラー調整に必要な GameObject をシーンに準備します。
- Main Camera:シーンカメラ。2D カラー調整はそのビュー行列と投影行列を使用します。
- LCCManager:Transform を正規化した空の GameObject で、
LCCManagerスクリプトを追加します。 - LCCRenderer:Transform を Rotation.x = -90、Scale.x = -1 に設定した空の GameObject(LCC データ座標系にアライメント)で、後述の
Toneスクリプトをアタッチします。 - 3D 選択ジオメトリ(省略可):3D カラー調整の補助オブジェクト。この例では 1 つの Cube(
Box1)を用意します。移動・スケーリングすると、3D カラー調整選択の位置とサイズを制御できます。
注:
レンダリングカメラ、LCCManager、LCCRenderer GameObject に関する設定は、PC クイックスタートガイド と プロジェクト設定の最適化ガイド の関連セクションを参照してください。
手順 2:データ構造を理解する
カラー調整は ToneMix データ構造を使用します。これは 2D テクスチャ選択と 3D ジオメトリ選択を同時に記述でき、カラー調整パラメータを保持します。使用する列挙型と構造体は以下のとおりです。
public enum SelectMode { normal, invert, clip } // 通常選択、反転、リアルタイムクリッピング
public enum OperationMode { normal, erase } // 通常選択、選択の消去
public enum ShapeType { box, sphere } // 3D Box 選択、3D Sphere 選択
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 は未使用
}
カラー調整リストについて注意すべき点は 3 つあります。
- リストは順序付きです。 2D でも 3D でも、リスト内のエントリは順番に有効になります。追加順が期待と一致することを確認してください。
- 反転にはカラー調整データが必要です。 これはカラー調整とハイライト/クリッピングの最も重要な違いです。ハイライト/クリッピングの反転は純粋なコマンドでデータとの関連付けは不要ですが、カラー調整の反転エントリは
mode = SelectMode.invertに加えて、brightness、saturation、contrastも設定し、選択外領域のカラー調整効果を指定する必要があります。 - 1 つのリストの最大エントリ数は 255 です。 超えるとエラーコードが返ります。
手順 3:カラー調整 API を理解する
カラー調整関連のインターフェースはすべて LCCManager が提供します。SetTone メソッド 1 つと終了メソッド 1 つがあります。
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(選択済み)の 2 つの値のみを使用します。
手順 5:スクリプトを書く
Tone.cs という名前の新しい C# スクリプトを作成します。まず基本の骨組みを完成させます。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 に失敗しました。マネージャが正しく設定され、ファイルパスが有効か確認してください。");
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コールバック発火後)に呼び出す必要があります。3 つのスライダーm_brightness、m_saturation、m_contrastは実行時にカラー調整パラメータを動的に調整するために使用し、必要に応じて利用できます。
手順 6:スクリプトをアタッチしてプロパティを設定する
Tone.csスクリプトを LCCRenderer GameObject にアタッチします。- Inspector ウィンドウで LCCManager GameObject をスクリプトの Manager プロパティへドラッグします。
- File Path プロパティに LCC ファイルパスを入力します。
- シーン内の
Box1をスクリプトの Box1 プロパティへドラッグし、3 つのスライダーをそれぞれ Brightness、Saturation、Contrast プロパティへドラッグして、3D カラー調整と実行時パラメータ調整に使用します。

Inspector で Tone スクリプトのプロパティを設定
手順 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)を呼び出して編集状態に入ります。 - データ読み込み後(
onLoadCallbackコールバック発火後、またはボタン/イベントでトリガー)にSetToneを呼び出します。 ToneMixのbrightness、saturation、contrast(範囲[0, 3]、デフォルト1.0)でカラー調整効果を制御し、カラー調整リストの追加順が期待と一致することを確認します。- 2D マスクテクスチャは 1024 × 1024 固定、
R8単一チャンネルです。ピクセル値は規約(128デフォルト、240選択済み)に従って埋めます。 - カラー調整の反転(
SelectMode.invert)は 必ずbrightness、saturation、contrastデータを保持します。これがハイライト/クリッピングの反転との重要な違いです。 - カラー調整のクリアや切り替え時は、先に
QuitToneMode()を呼び出します。