# Mask To Vertex Color Pro 使用文档

## 目录
1. [插件简介](#插件简介)
2. [安装与启用](#安装与启用)
3. [界面详解](#界面详解)
   - [标题区域](#标题区域)
   - [图像文件选择区域](#图像文件选择区域)
   - [处理设置区域](#处理设置区域)
   - [单对象处理区域](#单对象处理区域)
   - [批量处理区域](#批量处理区域)
   - [工具区域](#工具区域)
   - [工作流程说明](#工作流程说明)
   - [版本信息](#版本信息)
4. [使用流程](#使用流程)
5. [常见问题](#常见问题)

---

## 插件简介

**Mask To Vertex Color Pro** 是一款专业的 Blender 插件，用于将遮罩贴图（黑白图像或带透明通道的图像）转换为 3D 模型的顶点色 Alpha 通道。该插件支持单对象处理和批量处理，提供了丰富的处理选项和混合模式，适用于游戏开发、3D 渲染等场景。

### 主要特性
- ✅ 支持多种遮罩源（Alpha通道、灰度值、RGB通道等）
- ✅ 多种混合模式（替换、相乘、相加等）
- ✅ 单对象快速处理
- ✅ 批量处理多个对象
- ✅ UV坐标修复和验证功能
- ✅ 支持简体中文、繁体中文、英文

---

## 安装与启用

### 安装步骤
1. 下载插件文件（`add-on-MaskToVertexColorPro-vX.X.X.zip`）
2. 打开 Blender，进入 `编辑` > `偏好设置` > `插件`
3. 点击 `安装...` 按钮
4. 选择插件 `add-on-MaskToVertexColorPro-vX.X.X.zip` 文件
5. 在插件列表中搜索 "Mask To Vertex Color Pro"
6. 勾选插件名称旁的复选框以启用插件

### 访问插件
插件启用后，在 3D 视图的右侧边栏（按 `N` 键打开/关闭）中找到 **"M2VC Pro"** 标签页。

---

## 界面详解

### 标题区域

位于插件面板最顶部，显示插件的基本信息。

#### 版本号
- **显示内容**: "vX.0"
- **功能**: 显示当前插件版本
- **说明**: 插件的版本，便于问题反馈和更新

#### Blender 版本信息
- **显示内容**: "Blender [版本号]"
- **功能**: 显示当前使用的 Blender 版本
- **说明**: 用于兼容性参考

---

### 图像文件选择区域

用于选择和显示要使用的遮罩图像文件。

#### 文件路径显示
- **显示内容**: 
  - 如果已选择图像：显示文件名（超过25个字符会截断并显示"..."）
  - 如果未选择图像：显示"未选择图像" + 问号图标
- **功能**: 显示当前选择的图像文件
- **说明**: 
  - 如果文件不存在，会在文件名旁显示错误图标（红色感叹号）
  - 文件名过长时会自动截断以便界面整洁

#### 选择图像按钮
- **按钮文本**: 
  - 未选择图像时：显示"选择图像"
  - 已选择图像时：显示"更换图像"
- **图标**: 文件夹图标
- **功能**: 打开文件浏览器，选择遮罩图像文件
- **说明**: 
  - 支持常见图像格式（PNG、JPG、TGA等）
  - 点击后会打开系统文件浏览器
  - 选择图像后，所有处理操作（单对象和批量）都会使用此图像

---

### 处理设置区域

配置遮罩转换的各种参数，这些设置会应用到所有处理操作（单对象和批量）。

#### 遮罩源 (Mask Source)
- **类型**: 下拉菜单
- **功能**: 选择遮罩信息的来源通道
- **选项说明**:
  - **自动检测**: 插件自动分析图像，选择最佳的遮罩源（推荐）
  - **Alpha通道**: 使用图像的透明通道作为遮罩（适用于PNG等带透明通道的图像）
  - **灰度值**: 将RGB颜色转换为灰度值作为遮罩（适用于黑白图像）
  - **红色通道**: 使用图像的红色通道作为遮罩
  - **绿色通道**: 使用图像的绿色通道作为遮罩
  - **蓝色通道**: 使用图像的蓝色通道作为遮罩
  - **亮度**: 使用图像的亮度值作为遮罩
- **默认值**: 自动检测
- **使用建议**: 
  - 对于黑白图像，选择"灰度值"
  - 对于带透明通道的图像，选择"Alpha通道"
  - 不确定时选择"自动检测"

#### 混合模式 (Blend Mode)
- **类型**: 下拉菜单
- **功能**: 选择遮罩与现有顶点色的混合方式
- **选项说明**:
  - **替换**: 直接用遮罩值替换现有的Alpha值（最常用）
  - **相乘**: 遮罩值与现有Alpha值相乘（用于减弱效果）
  - **相加**: 遮罩值与现有Alpha值相加（用于增强效果）
  - **相减**: 从现有Alpha值中减去遮罩值（用于反向效果）
  - **最小值**: 取遮罩值和现有Alpha值的较小者
  - **最大值**: 取遮罩值和现有Alpha值的较大者
  - **叠加**: 叠加模式（类似Photoshop的叠加模式）
  - **滤色**: 滤色模式（类似Photoshop的滤色模式）
- **默认值**: 替换
- **使用建议**: 
  - 首次使用建议选择"替换"
  - 如果需要与现有顶点色混合，选择"相乘"或"相加"

#### 混合强度 (Blend Factor)
- **类型**: 滑块（0.0 - 1.0）
- **功能**: 控制混合效果的强度
- **说明**: 
  - 0.0: 无效果
  - 1.0: 完全效果（默认）
  - 中间值: 按比例混合
- **默认值**: 1.0
- **使用建议**: 用于微调遮罩的强度，例如让遮罩效果更柔和

#### UV包裹 (UV Wrap)
- **类型**: 开关按钮
- **功能**: 将超出0-1范围的UV坐标包裹回范围内
- **说明**: 
  - 开启：UV坐标超出1.0时会包裹回0.0（例如1.5变成0.5）
  - 关闭：不进行包裹处理
- **默认值**: 开启
- **使用建议**: 
  - 如果模型有重复的UV（平铺纹理），保持开启
  - 如果UV超出范围是错误，应该先修复UV

#### UV限制 (UV Clamp)
- **类型**: 开关按钮
- **功能**: 将UV坐标限制在0-1范围内（不包裹）
- **说明**: 
  - 开启：UV坐标会被限制在0.0-1.0之间（超出部分会被裁剪）
  - 关闭：不进行限制
- **默认值**: 关闭
- **使用建议**: 
  - 与"UV包裹"互斥，通常只开启其中一个
  - 如果UV超出范围是错误，使用此选项可以防止采样错误区域

#### 垂直翻转 (Flip Vertical)
- **类型**: 开关按钮
- **功能**: 垂直翻转图像（修复上下颠倒的问题）
- **说明**: 
  - 开启：图像上下翻转
  - 关闭：不翻转
- **默认值**: 开启
- **使用建议**: 
  - 如果遮罩方向与预期相反，切换此选项
  - 通常Blender的UV坐标系统需要此选项

#### 水平翻转 (Flip Horizontal)
- **类型**: 开关按钮
- **功能**: 水平翻转图像（修复左右颠倒的问题）
- **说明**: 
  - 开启：图像左右翻转
  - 关闭：不翻转
- **默认值**: 开启
- **使用建议**: 
  - 如果遮罩方向与预期相反，切换此选项
  - 根据实际效果调整

#### 调试模式 (Debug Mode)
- **类型**: 开关按钮
- **功能**: 启用调试信息输出
- **说明**: 
  - 开启：在控制台输出详细的处理信息（用于排查问题）
  - 关闭：不输出调试信息
- **默认值**: 关闭
- **使用建议**: 
  - 仅在遇到问题时开启
  - 开启后会在Blender的控制台（Window > Toggle System Console）显示详细信息

---

### 单对象处理区域

用于快速处理当前选中的单个对象。

#### 顶点色名称 (Vertex Color Name)
- **类型**: 文本输入框
- **功能**: 指定要创建或更新的顶点色图层名称
- **说明**: 
  - 如果指定的顶点色图层不存在，插件会自动创建
  - 如果已存在，会更新该图层
- **默认值**: "MaskAlpha"
- **使用建议**: 
  - 可以使用有意义的名称，如"Mask"、"Alpha"等
  - 名称不能为空

#### 应用到当前选中对象按钮
- **按钮文本**: "应用到当前选中对象"
- **图标**: Alpha通道图标
- **功能**: 将遮罩应用到当前在3D视图中选中的对象
- **前置条件**: 
  - 必须已选择图像文件
  - 必须在3D视图中选中一个对象
- **说明**: 
  - 只处理当前选中的一个对象
  - 如果选中多个对象，只处理第一个
  - 处理完成后会在信息栏显示结果

#### 提示信息
- **显示内容**: 
  - 如果已选择图像：显示"注意: 仅处理当前选中的一个对象" + 信息图标
  - 如果未选择图像：显示"请先选择图像文件" + 信息图标

---

### 批量处理区域

用于批量处理多个对象，支持添加对象到列表、管理列表、批量应用遮罩。

#### 对象列表
- **类型**: 可滚动列表
- **功能**: 显示和管理要批量处理的对象列表
- **列表项显示内容**:
  - **复选框**: 控制该对象是否参与批量处理
  - **选中指示器**: 圆点图标，表示当前选中的列表项
  - **对象图标**: 标识这是一个对象
  - **对象名称**: 显示对象的名称
  - **状态图标**: 显示处理状态（等待/处理中/完成/错误）
  - **状态文本**: 简短的状态描述
- **列表操作**:
  - 点击列表项可以选中它
  - 勾选/取消复选框可以启用/禁用该对象
  - 列表最多显示5行，超出部分可以滚动查看

#### 列表操作按钮（位于列表右侧）

##### 添加按钮 (+)
- **图标**: 加号图标
- **功能**: 将当前在3D视图中选中的对象添加到批量处理列表
- **说明**: 
  - 可以一次选择多个对象，然后点击此按钮
  - 已存在的对象不会被重复添加
  - 如果列表为空，此按钮会显示为带文本的按钮："添加选中对象到列表"

##### 移除按钮 (-)
- **图标**: 减号图标
- **功能**: 从列表中移除当前选中的列表项
- **说明**: 
  - 必须先选中列表中的某个项
  - 移除后，如果列表还有项，会自动选中下一个

##### 移除已启用按钮 (X)
- **图标**: X图标
- **功能**: 从列表中移除所有已启用（勾选）的对象
- **说明**: 
  - 用于快速清理已处理完成的对象
  - 只移除已勾选的对象，未勾选的对象保留

##### 清空所有按钮 (垃圾桶)
- **图标**: 垃圾桶图标
- **功能**: 清空整个批量处理列表
- **说明**: 
  - 会移除列表中的所有对象
  - 操作不可撤销，请谨慎使用

##### 全部启用按钮 (已勾选复选框)
- **图标**: 已勾选的复选框图标
- **功能**: 启用列表中的所有对象（全部勾选）
- **说明**: 
  - 快速启用所有对象参与批量处理
  - 如果对象已启用，不会重复操作

##### 全部禁用按钮 (未勾选复选框)
- **图标**: 未勾选的复选框图标
- **功能**: 禁用列表中的所有对象（全部取消勾选）
- **说明**: 
  - 快速禁用所有对象
  - 用于临时排除所有对象，稍后可以重新启用

#### 批量应用按钮
- **按钮文本**: "批量应用到 [数量] 个对象"
- **图标**: 播放图标
- **功能**: 对列表中所有已启用的对象应用遮罩转换
- **前置条件**: 
  - 必须已选择图像文件
  - 列表中至少有一个对象被启用（勾选）
- **说明**: 
  - 会按顺序处理所有启用的对象
  - 每个对象可以有不同的顶点色名称（在列表项中设置）
  - 处理过程中会显示进度和状态
  - 处理完成后会在信息栏显示总结

#### 批量处理提示信息
- **显示内容**:
  - 如果有已启用的对象且已选择图像：显示"注意: 将处理列表中所有启用的对象 ([数量]个)" + 信息图标
  - 如果有已启用的对象但未选择图像：显示"请先选择图像文件" + 信息图标
  - 如果没有已启用的对象：显示"请在列表中启用至少一个对象" + 信息图标
  - 如果列表为空：显示"批量列表为空" + 信息图标
- **功能**: 提示用户当前状态和操作要求

#### 使用说明（仅当列表为空时显示）
- **显示内容**: 
  - "使用方法:" + 问号图标
  - "1. 在3D视图中选择多个对象"
  - "2. 点击'添加选中对象到列表'"
  - "3. 在列表中勾选要处理的对象"
  - "4. 点击'批量应用到X个对象'"

---

### 工具区域

提供额外的实用工具，用于辅助处理。

#### 修复UV坐标按钮
- **按钮文本**: "修复UV坐标"
- **图标**: UV图标
- **功能**: 修复当前选中对象的UV坐标问题
- **说明**: 
  - 修复无效的UV坐标（NaN、Infinity等）
  - 将UV坐标规范化到合理范围
  - 只处理当前选中的对象
  - 如果对象没有UV坐标，会创建默认的UV层
- **使用场景**: 
  - 当遮罩应用出现异常时，可能是UV坐标有问题
  - 导入的模型UV坐标可能包含无效值
  - 处理前预防性修复

#### 验证模型按钮
- **按钮文本**: "验证模型"
- **图标**: 勾选标记图标
- **功能**: 检查当前选中对象的状态
- **检查内容**: 
  - UV坐标层数量和有效性
  - 无效UV坐标的数量
  - 顶点色层的数量
  - 多边形和顶点数量
- **使用场景**: 
  - 处理前检查模型状态
  - 排查处理失败的原因
  - 了解模型的详细信息

---

### 工作流程说明

#### 流程步骤
1. **选择图像文件**
   - 第一步：选择要使用的遮罩图像

2. **配置处理设置**
   - 第二步：根据需要调整处理参数

3. **快速处理单个对象（上）**
   - 第三步：先用单个对象测试效果

4. **批量处理多个对象（下）**
   - 第四步：确认效果后批量应用

#### 重要提示
- **所有操作共享同一图像和设置**
  - 单对象处理和批量处理使用相同的图像和设置，便于保持一致

- **先处理单个测试效果，再批量应用**
  - 建议的工作流程：先用单个对象测试，确认效果后再批量处理，避免批量处理出错

---

### 版本信息

显示插件的版本和作者信息。

#### 版本详情
- **插件版本**: 显示当前版本号（如 v2.0）
- **优化说明**: 显示最近的优化内容
- **作者**: 墨泪
- **主页**: https://www.kiiiii.com

---

## 使用流程

### 快速开始（单对象处理）

1. **打开插件面板**
   - 在3D视图中按 `N` 键打开右侧边栏
   - 点击 **"M2VC Pro"** 标签页

2. **选择图像文件**
   - 点击 **"选择图像"** 按钮
   - 在文件浏览器中选择遮罩图像文件

3. **配置处理设置**（可选）
   - 根据需要调整遮罩源、混合模式等参数
   - 首次使用可以保持默认设置

4. **设置顶点色名称**（可选）
   - 在"单对象处理"区域的"顶点色名称"输入框中输入名称
   - 默认值为 "MaskAlpha"

5. **选择对象并应用**
   - 在3D视图中选择一个对象
   - 点击 **"应用到当前选中对象"** 按钮
   - 等待处理完成，查看结果

### 批量处理流程

1. **准备图像和设置**（同单对象处理步骤1-3）

2. **添加对象到列表**
   - 在3D视图中选择多个要处理的对象
   - 点击批量处理区域的 **"添加选中对象到列表"** 按钮（或列表右侧的 **"+"** 按钮）

3. **管理列表**
   - 在列表中勾选要处理的对象（取消勾选的对象会被跳过）
   - 可以为每个对象设置不同的顶点色名称（在列表项中）
   - 使用列表操作按钮管理列表（移除、清空、启用/禁用等）

4. **批量应用**
   - 确认列表中至少有一个对象被启用
   - 点击 **"批量应用到 X 个对象"** 按钮
   - 等待处理完成，查看结果

### 推荐工作流程

1. **测试阶段**
   - 选择图像文件
   - 选择一个测试对象
   - 使用单对象处理测试效果
   - 根据需要调整处理设置
   - 验证结果是否符合预期

2. **批量处理阶段**
   - 确认测试效果满意后
   - 添加所有要处理的对象到批量列表
   - 检查每个对象的设置（顶点色名称等）
   - 执行批量处理
   - 检查处理结果

3. **问题排查**（如需要）
   - 如果处理失败，使用 **"验证模型"** 按钮检查对象状态
   - 如果UV有问题，使用 **"修复UV坐标"** 按钮修复
   - 开启调试模式查看详细信息

---

## 常见问题

### Q1: 为什么遮罩没有正确应用？
**可能原因**:
- UV坐标有问题：使用 **"修复UV坐标"** 按钮修复
- 遮罩源选择错误：尝试不同的遮罩源选项
- 图像方向错误：调整垂直翻转或水平翻转选项
- 对象没有UV坐标：需要先为对象添加UV坐标

**解决方法**:
1. 使用 **"验证模型"** 按钮检查对象状态
2. 尝试不同的遮罩源（如从"自动检测"改为"Alpha通道"或"灰度值"亦或者其他通道选项）
3. 调整翻转选项
4. 开启调试模式查看详细信息

### Q2: 批量处理时某些对象失败？
**可能原因**:
- 对象没有UV坐标
- 对象不是网格对象
- UV坐标无效（NaN或Infinity）

**解决方法**:
1. 使用 **"验证模型"** 按钮检查失败的对象
2. 使用 **"修复UV坐标"** 按钮修复问题对象
3. 确保所有对象都是有效的网格对象

### Q3: 如何查看处理结果？
**方法**:
- 在材质编辑器中查看顶点色
- 在视口着色模式中启用顶点色显示
- 使用 **"验证模型"** 按钮查看顶点色层信息

### Q4: 顶点色名称可以自定义吗？
**可以**:
- 单对象处理：在"顶点色名称"输入框中输入自定义名称
- 批量处理：可以在列表项中为每个对象设置不同的顶点色名称

### Q5: 处理设置会影响哪些操作？
**所有操作**:
- 单对象处理和批量处理都使用相同的处理设置
- 更改设置后，所有后续操作都会使用新设置
- 建议在批量处理前先用单对象测试新设置

### Q6: 如何移除批量列表中的对象？
**方法**:
- 选中列表项，点击 **"-"** 按钮移除单个对象
- 点击 **"X"** 按钮移除所有已启用的对象
- 点击 **"垃圾桶"** 按钮清空整个列表

### Q7: 插件支持哪些图像格式？
**支持格式**:
- PNG（推荐，支持透明通道）
- JPG/JPEG
- TGA
- 其他Blender支持的图像格式都可以尝试，具体的大家自行测试

### Q8: 如何切换语言？
**方法**:
- 在Blender的偏好设置中更改界面语言
- 插件会自动适配简体中文、繁体中文和英文
- 重启Blender或重新加载插件后生效
- 因为实在不知道Blender4.0+的繁体中文不生效的问题怎么解决，所以4.0+之后的版本不支持繁体中文

---

## 技术支持

如有问题或建议，请访问：
- **主页**: https://www.kiiiii.com
- **作者**: 墨泪

---

**文档版本**: 1.0  
**最后更新**: 2025  
**插件版本**: v2.0.4