vrm-mtoon-outline

VRM MToon アウトラインの太さの調整

このスキルでは、@pixiv/three-vrm の MToon マテリアルを使用する VRM モデルのアウトラインの太さを調整する方法を説明します。

よくある症状

1. モデルを拡大したときやカメラを近づけたときに、アウトラインが太すぎる
2. ズームレベルによってアウトラインの太さが一定しない
3. 実行時にプログラムからアウトラインの太さを調整したい

---

主な概念

アウトライン幅のモード

MToon マテリアルには、主に 2 つのアウトライン幅モードがあります。

モード	説明	動作
'worldCoordinates'	アウトライン幅が物理的なワールド空間のサイズになります	モデルを拡大したときやカメラを近づけたときに、アウトラインが太く表示されます
'screenCoordinates'	アウトライン幅が画面ピクセルに対する相対的なサイズになります	ズームやスケールに関係なく、アウトラインのサイズが一定に保たれます

重要なプロパティ

material.outlineWidthMode    // 'none' | 'worldCoordinates' | 'screenCoordinates'
material.outlineWidthFactor  // Number - the actual width value
material.isMToonMaterial     // Boolean - true for MToon materials
material.needsUpdate         // Set to true after modifying properties

---

解決策：スクリーン座標に切り替える

ズームやスケールに関係なくアウトラインの太さを一定にするには、次のようにします。

function adjustOutlineThickness(vrm, screenFactor = 0.005) {
    vrm.scene.traverse((object) => {
        if (object.isMesh || object.isSkinnedMesh) {
            const materials = Array.isArray(object.material) ? object.material : [object.material];
            
            materials.forEach(material => {
                if (!material || !material.isMToonMaterial) return;
                
                // Check if this material has outlines enabled
                const hasOutline = material.outlineWidthFactor > 0 && 
                                   material.outlineWidthMode !== 'none';
                
                if (hasOutline) {
                    // Switch to screen coordinates mode
                    material.outlineWidthMode = 'screenCoordinates';
                    material.outlineWidthFactor = screenFactor;
                    material.needsUpdate = true;
                }
            });
        }
    });
}

係数値の目安

screenCoordinates モードの場合：

係数値	おおよその効果
0.002 - 0.003	非常に細いアウトライン（1 ピクセル）
0.005	細いアウトライン（1〜2 ピクセル）
0.01	中程度のアウトライン（2〜3 ピクセル）
0.02+	太いアウトライン

---

検出方法

アウトラインの問題を診断するには、すべてのマテリアルをログに出力します。

function debugOutlineMaterials(vrm) {
    let count = 0;
    vrm.scene.traverse((object) => {
        if (!object.isMesh && !object.isSkinnedMesh) return;
        
        const materials = Array.isArray(object.material) ? object.material : [object.material];
        materials.forEach(material => {
            if (material?.isMToonMaterial || 'outlineWidthFactor' in material) {
                count++;
                console.log({
                    name: material.name || '未命名',
                    type: material.type,
                    isMToonMaterial: material.isMToonMaterial,
                    outlineWidthMode: material.outlineWidthMode,
                    outlineWidthFactor: material.outlineWidthFactor
                });
            }
        });
    });
    console.log(`Found ${count} MToon/Outline materials`);
}

---

重要な注意事項

重要

呼び出すタイミングが重要です！ この関数は、currentModel が設定された後に呼び出す必要があります。vrm-core.js では、loadModel() 関数が 923 行目付近で manager.currentModel を設定します。currentModel にアクセスする関数は、必ずこの処理の後に呼び出してください。

メモ

"XXX (Outline)" という名前のマテリアルは、three-vrm によって自動作成されるアウトラインパス用のマテリアルです。メインのマテリアルとプロパティを共有し、アウトライン効果をレンダリングします。

---

API リファレンス（three-vrm MToon）

outlineWidthMode の列挙値：

// From three-vrm.module.min.js
{
    None: "none",
    WorldCoordinates: "worldCoordinates", 
    ScreenCoordinates: "screenCoordinates"
}

プロパティ	型	説明
outlineWidthMode	string	幅の計算モード
outlineWidthFactor	number	幅の値（意味はモードによって異なります）
outlineColorFactor	Color	アウトラインの色
outlineLightingMixFactor	number	アウトラインに対するライティングの影響度
outlineWidthMultiplyTexture	Texture	アウトライン幅を調整するテクスチャ