threejs-impl-lighting

threejs-impl-lighting

クイックリファレンス

ライトの種類一覧

ライト	影	方向	コスト	強度の単位（r160以降）
AmbientLight	なし	なし（均一）	ごくわずか	単位なしの乗数
HemisphereLight	なし	垂直方向のグラデーション	ごくわずか	単位なしの乗数
DirectionalLight	あり	平行光線	中程度	ルクス
PointLight	あり（6パス！）	全方向	高い	カンデラ
SpotLight	あり	円錐	高い	カンデラ
RectAreaLight	なし	平面放射	非常に高い	ニト（cd/m2）
LightProbe	なし	球面調和関数	低い	単位なしの乗数

重要な警告

絶対に AmbientLight を唯一の光源として使用しないでください。陰影がなく、立体感のないレンダリングになります。必ず、少なくとも1つの DirectionalLight または PointLight と組み合わせてください。

絶対に DirectionalLight または SpotLight のターゲットを移動するときに、light.target をシーンに追加し忘れないでください。追加しないと、方向ベクトルは更新されません。

絶対に RectAreaLightUniformsLib.init()（WebGLRenderer）または RectAreaLightTexturesLib（WebGPURenderer）を先に呼び出さずに RectAreaLight を使用しないでください。ライトが正しくレンダリングされないか、まったく表示されません。

絶対に 影を落とす PointLight は1～2個を超えて使用しないでください。それぞれに6回のシャドウマップのレンダリングパスが必要です。より低コストな代替手段として、影を有効にした SpotLight を使用してください。

環境マップを生成した後は、必ず pmremGenerator.dispose() を呼び出してください。PMREMGenerator は大量の GPU メモリを使用します。

物理的に正しい強度の値を使用する場合は、必ず renderer.toneMapping を設定してください。トーンマッピングがないと、高いルクス値やカンデラ値によってシーン全体が白飛びします。

---

Light クラスの階層

すべてのライトは、Object3D を拡張する Light を継承します。

Object3D
  └── Light (abstract: .color, .intensity, .dispose())
        ├── AmbientLight        — uniform fill
        ├── HemisphereLight     — sky/ground gradient
        ├── DirectionalLight    — parallel rays (sun)
        ├── PointLight          — omnidirectional (bulb)
        ├── SpotLight           — cone (flashlight)
        ├── RectAreaLight       — planar (window/panel)
        └── LightProbe          — spherical harmonics (IBL)

Light 基底クラスが提供するもの：

• .color（Color）— ライトの色。デフォルトは 0xffffff です。
• .intensity（number）— 強度の乗数。デフォルトは 1 です。
• .isLight（boolean、読み取り専用）— 常に true です。
• .dispose() — GPU リソースを解放します。

---

物理的に正しいライティング（r160以降）

r160以降、すべてのライティングではデフォルトで物理ベースの単位が使用されます。従来の renderer.useLegacyLights プロパティは削除されました。

ライトの種類	強度の単位	説明
DirectionalLight	ルクス（lm/m2）	太陽光：50,000～100,000ルクス
PointLight	カンデラ（lm/sr）	100W電球：約1700 cd
SpotLight	カンデラ（lm/sr）	舞台用スポットライト：約10,000 cd
RectAreaLight	ニト（cd/m2）	LEDパネル：約500～5000ニト
AmbientLight	単位なし	乗数。物理単位なし
HemisphereLight	単位なし	乗数。物理単位なし

PointLight、SpotLight、RectAreaLight の .power プロパティは、光束をルーメンで表します。

• PointLight：power = intensity * 4 * Math.PI
• SpotLight：power = intensity * Math.PI

物理的に正しい強度には、必ずトーンマッピングを組み合わせてください。

import * as THREE from 'three';

renderer.toneMapping = THREE.ACESFilmicToneMapping;
renderer.toneMappingExposure = 1.0;

---

7種類のライト

AmbientLight

均一な補助光です。方向はなく、影もありません。ベースとなる照明にのみ使用してください。

const ambient = new THREE.AmbientLight(0x404040, 0.5);
scene.add(ambient);

HemisphereLight

空から地面へと変化するグラデーションです。影はありません。空と地面からの反射光による屋外の環境光を再現します。

const hemi = new THREE.HemisphereLight(0xffffbb, 0x080820, 1.0);
scene.add(hemi);

プロパティ：.groundColor（Color）— 下半球の色です。

DirectionalLight

遠方からの光（日光など）を模した平行光線です。方向は light.position から light.target.position への向きです。

const sun = new THREE.DirectionalLight(0xffffff, 3);
sun.position.set(5, 10, 7.5);
scene.add(sun);
scene.add(sun.target); // REQUIRED for target repositioning

プロパティ：.target（Object3D）、.shadow（DirectionalLightShadow）。

PointLight

単一点から全方向に放射される光です。影には6回のレンダリングパスが必要です。

const bulb = new THREE.PointLight(0xffaa44, 800, 20, 2);
bulb.position.set(0, 3, 0);
scene.add(bulb);

プロパティ：.distance（number、0＝無限）、.decay（number、2＝物理的に正しい値）、.power（ルーメン）。

SpotLight

円錐状の光です。リアルな柔らかい境界にするには、必ず penumbra >= 0.1 に設定してください。

const spot = new THREE.SpotLight(0xffffff, 1000);
spot.position.set(0, 10, 0);
spot.angle = Math.PI / 6;
spot.penumbra = 0.3;
spot.decay = 2;
scene.add(spot);
scene.add(spot.target); // REQUIRED for target repositioning

プロパティ：.angle（最大 Math.PI/2）、.penumbra（0～1）、.distance、.decay、.power、.map（クッキーテクスチャ。castShadow = true が必須）、.target、.shadow。

RectAreaLight

窓、パネル、ストリップライト向けの平面エミッターです。MeshStandardMaterial と MeshPhysicalMaterial でのみ動作します。シャドウを投影できません。

import { RectAreaLightUniformsLib } from 'three/addons/lights/RectAreaLightUniformsLib.js';

RectAreaLightUniformsLib.init(); // MUST call before creating any RectAreaLight

const panel = new THREE.RectAreaLight(0xffffff, 5, 4, 10);
panel.position.set(5, 5, 0);
panel.lookAt(0, 0, 0); // Orient using lookAt, NOT rotation
scene.add(panel);

プロパティ：.width、.height、.power（ルーメン）。

LightProbe

球面調和関数に基づく環境光です。AR やベイク済みの環境ライティングに便利です。

import { LightProbeGenerator } from 'three/addons/lights/LightProbeGenerator.js';

const probe = LightProbeGenerator.fromCubeTexture(cubeTexture);
scene.add(probe);

---

環境マップ（IBL）

イメージベースドライティング（IBL）は、PBR マテリアルに最もリアルな環境光を提供します。標準的なワークフローでは RGBELoader と PMREMGenerator を使用します。

標準的な HDR 環境ワークフロー

import * as THREE from 'three';
import { RGBELoader } from 'three/addons/loaders/RGBELoader.js';

const pmremGenerator = new THREE.PMREMGenerator(renderer);
const rgbeLoader = new RGBELoader();

rgbeLoader.load('environment.hdr', (hdrTexture) => {
  const envMap = pmremGenerator.fromEquirectangular(hdrTexture);

  scene.environment = envMap.texture;  // ALL PBR materials auto-use this
  scene.background = envMap.texture;   // Optional: visible HDR background

  hdrTexture.dispose();                // Free source texture
  pmremGenerator.dispose();            // ALWAYS dispose after use
});

scene.environment と scene.background

プロパティ	効果	使用する場面
scene.environment	すべての Standard/Physical マテリアルに対する PBR 反射と環境光	リアルな PBR では常に使用
scene.background	表示されるスカイボックス／背景	HDR を表示したい場合
両方に同じテクスチャを設定	環境が表示される完全な IBL	プロダクトショットで最も一般的
scene.backgroundBlurriness	背景をぼかす（0～1）	背景に被写界深度の効果を加える
scene.environmentIntensity	IBL の寄与を調整	環境光のレベルを微調整
scene.environmentRotation	環境マップを回転	ライトを動かさずに光の方向を調整

scene.environment が設定されると、すべての MeshStandardMaterial と MeshPhysicalMaterial のインスタンスが、反射と環境光にこれを自動的に使用します。マテリアルごとの設定は不要です。

PMREMGenerator のメソッド

メソッド	入力	目的
fromEquirectangular(texture)	正距円筒図法テクスチャ	HDR パノラマを PMREM に変換
fromScene(scene, sigma?)	Three.js Scene	3D シーンから PMREM を生成
fromCubemap(texture)	CubeTexture	キューブマップを PMREM に変換
dispose()	--	GPU メモリを解放（必ず呼び出してください）

EXR の代替方法

import { EXRLoader } from 'three/addons/loaders/EXRLoader.js';

new EXRLoader().load('environment.exr', (exrTexture) => {
  const envMap = pmremGenerator.fromEquirectangular(exrTexture);
  scene.environment = envMap.texture;
  exrTexture.dispose();
  pmremGenerator.dispose();
});

---

ライトヘルパー

ヘルパー	インポート	コンストラクター
DirectionalLightHelper	three	new DirectionalLightHelper(light, size?, color?)
SpotLightHelper	three	new SpotLightHelper(light, color?)
PointLightHelper	three	new PointLightHelper(light, sphereSize?, color?)
HemisphereLightHelper	three	new HemisphereLightHelper(light, size, color?)
RectAreaLightHelper	three/addons/helpers/RectAreaLightHelper.js	new RectAreaLightHelper(light)
LightProbeHelper	three/addons/helpers/LightProbeHelper.js	new LightProbeHelper(probe, size)

ヘルパーが自動更新されない場合は、ライトのプロパティを変更したあと、必ず helper.update() を呼び出してください。

const helper = new THREE.DirectionalLightHelper(dirLight, 5);
scene.add(helper);
// After changing dirLight properties:
helper.update();

---

パフォーマンス予算

カテゴリー	予算
モバイル WebGL	リアルタイムライトは合計最大 4～5 個
デスクトップ WebGL	シーンに応じてライトは最大 8～16 個
シャドウを投影する PointLight	最大 1～2 個（それぞれ 6 パス）
RectAreaLights	最大 2～3 個（LTC の評価コストが高い）

静的な環境では、リアルタイムライトよりもベイク済みライティングを必ず優先してください。

複数のフィルライトではなく、環境マップ（IBL）を主な環境光源として必ず使用してください。

---

参考リンク

• references/methods.md -- すべてのライトタイプと PMREMGenerator の API シグネチャーの一覧
• references/examples.md -- 屋外、屋内、スタジオ、プロダクト向けのライティングレシピ
• references/anti-patterns.md -- よくあるライティングの間違いとその修正方法

公式ソース

• https://threejs.org/docs/#api/en/lights/AmbientLight
• https://threejs.org/docs/#api/en/lights/DirectionalLight
• https://threejs.org/docs/#api/en/lights/PointLight
• https://threejs.org/docs/#api/en/lights/SpotLight
• https://threejs.org/docs/#api/en/lights/RectAreaLight
• https://threejs.org/docs/#api/en/lights/HemisphereLight
• https://threejs.org/docs/#api/en/lights/LightProbe
• https://threejs.org/docs/#api/en/extras/PMREMGenerator