vrm-mtoon-outline

VRM MToon 轮廓粗细调整

本技能介绍如何调整 @pixiv/three-vrm 中使用 MToon 材质的 VRM 模型的轮廓粗细。

常见症状

1. 模型放大或摄像机靠近时，轮廓过粗
2. 在不同缩放级别下，轮廓粗细不一致
3. 需要在运行时以编程方式调整轮廓粗细

---

关键概念

轮廓宽度模式

MToon 材质有两种主要的轮廓宽度模式：

模式	描述	行为
'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	用于调节轮廓宽度的纹理