d1kt/KMEANS_QUICKSTART.md

# K-Means 算法演示页面 - 快速开始

## 🎯 功能概览

这是一个完整的 K-Means 聚类算法可视化演示工具，集成在您的打字练习网站中。

### ✨ 核心功能

| 功能 | 说明 |
|------|------|
| 🎨 **可视化画布** | 800x600 像素的交互式画布 |
| 🎲 **随机生成点** | 可生成 1-200 个随机数据点 |
| 🖱️ **交互操作** | 左键添加点/质心，右键清空 |
| 🎯 **K值调节** | 支持 1-10 个聚类中心 |
| 📊 **算法演示** | 逐步展示 K-Means 算法过程 |
| 📏 **距离可视化** | 实时显示点到质心的距离 |
| 📑 **坐标显示** | 可选显示所有点的坐标 |
| 💾 **Excel支持** | 导入/导出数据到 Excel 文件 |

## 🚀 快速开始

### 步骤 1: 访问页面

- **开发环境**: http://localhost:3001/kmeans
- **导航入口**: 点击网站顶部导航栏的 "K-Means演示"

### 步骤 2: 基础操作

1. **设置参数**
   ```
   K值: 3 (想要分成几个簇)
   点的数量: 50
   ```

2. **生成数据**
   - 点击 "生成随机点" 按钮

3. **设置质心**
   - 在画布上点击 3 次（与K值相同）
   - 每个质心会用不同颜色标识

4. **运行算法**
   - 点击 "执行一步" 按钮
   - 观察算法逐步执行过程

5. **保存结果**
   - 点击 "导出Excel" 保存数据

## 📖 使用示例

### 示例 1: 基础聚类

```
目标: 将 50 个点分成 3 个簇

操作:
1. K值 = 3
2. 点的数量 = 50
3. 生成随机点
4. 点击画布 3 次设置质心
5. 持续点击"执行一步"直到完成
```

### 示例 2: 手动创建数据

```
目标: 手动创建特定分布的数据

操作:
1. K值 = 2
2. 在画布左侧点击 2 次设置质心
3. 在画布不同区域手动点击添加数据点
4. 勾选"显示坐标"查看具体位置
5. 执行算法查看聚类结果
```

### 示例 3: 导入已有数据

```
目标: 使用之前保存的数据

操作:
1. 点击"导入Excel"
2. 选择之前导出的 Excel 文件
3. 数据自动加载到画布
4. 继续执行算法或修改数据
```

## 🎨 界面说明

```
┌─────────────────────────────────────────────────┐
│  控制面板                                        │
│  [点数] [生成] [K值] [☑显示坐标] [执行] [清空]  │
│  [导出Excel] [导入Excel]                        │
├─────────────────────────────────────────────────┤
│                                                 │
│                  画布区域                        │
│              (800 x 600 像素)                   │
│                                                 │
│  ● 灰色点 = 未分配的数据点                      │
│  ● 彩色点 = 已分配到簇的点                      │
│  ◉ 大圆圈 = 质心点 (标记为 C1, C2, ...)         │
│  ─── 线段 = 距离连线（显示数值）                │
│                                                 │
├─────────────────────────────────────────────────┤
│  操作说明                                        │
│  • 左键: 添加点/质心                            │
│  • 右键: 清空画布                               │
│  • 当前迭代: 0                                  │
│  • 状态: 等待开始                               │
└─────────────────────────────────────────────────┘
```

## 🔍 算法过程详解

### 阶段 1: 初始化
- 设置 K 个质心点
- 生成或添加数据点

### 阶段 2: 分配簇（点击"执行一步"）
```
对于每个数据点:
  1. 计算到所有质心的距离 (显示线段和数值)
  2. 找出最短距离 (高亮显示为绿色)
  3. 将点分配给最近的质心 (点变成质心颜色)
  4. 清除距离线，处理下一个点
```

### 阶段 3: 更新质心
```
当所有点处理完毕:
  1. 计算每个簇的几何中心
  2. 移动质心到新的位置
  3. 检查是否收敛
```

### 阶段 4: 迭代或结束
```
如果质心位置改变:
  → 返回阶段 2，继续下一轮迭代

如果质心位置不变:
  → 算法收敛，显示"聚类完成"
```

## 📁 Excel 文件格式

导出的 Excel 文件包含以下列：

| 列名 | 说明 | 示例 |
|------|------|------|
| 类型 | 数据点或质心 | 数据点 / 质心 |
| 索引 | 编号 | 1, 2, 3... |
| X坐标 | 横坐标值 | 123.45 |
| Y坐标 | 纵坐标值 | 234.56 |
| 所属簇/颜色 | 簇编号或颜色代码 | 簇1 / #FF6B6B |

## ⌨️ 键盘快捷键

| 操作 | 快捷键 |
|------|--------|
| 清空画布 | 右键点击画布 |
| 添加点 | 左键点击画布 |

## 💡 使用技巧

### 技巧 1: 观察收敛过程
- 每次点击"执行一步"只处理一个点
- 可以清楚看到每个点如何选择最近的质心
- 适合教学演示

### 技巧 2: 测试不同 K 值
```
相同数据，不同K值的效果:
K=2: 粗分类
K=3: 中等细分
K=5: 细分类
```

### 技巧 3: 保存实验数据
- 每次实验后导出 Excel
- 可以在不同场景下重复使用相同数据
- 便于比较不同参数的效果

### 技巧 4: 质心初始化的影响
- 尝试在不同位置设置初始质心
- 观察对最终聚类结果的影响
- 理解 K-Means++ 的重要性

## ⚠️ 注意事项

1. **质心数量**: 必须设置完整的 K 个质心才能开始算法
2. **算法运行中**: 无法修改参数或添加新点
3. **右键操作**: 会清空整个画布，请谨慎使用
4. **浏览器兼容**: 需要支持 Canvas API 的现代浏览器
5. **性能考虑**: 建议点的数量不超过 200 个

## 🐛 常见问题

**Q: 为什么点击"执行一步"没反应？**
```
检查清单:
☐ 是否已设置了 K 个质心？
☐ 质心数量是否等于设置的 K 值？
☐ 是否有数据点？
```

**Q: 如何重新开始？**
```
方法 1: 点击"清空画布"按钮
方法 2: 右键点击画布
然后重新设置质心和数据点
```

**Q: Excel 导入失败？**
```
检查文件格式:
☐ 文件扩展名是 .xlsx 或 .xls
☐ 包含必需的列（类型、X坐标、Y坐标）
☐ 数值格式正确
```

**Q: 算法什么时候停止？**
```
停止条件:
• 各簇成员不再变化
• 质心位置稳定
• 显示"聚类完成"提示
```

## 🎓 教学场景

### 场景 1: 课堂演示
```
时间: 15-20分钟
内容:
1. 介绍 K-Means 基本概念 (5分钟)
2. 现场演示算法过程 (10分钟)
3. 讨论初始化和收敛 (5分钟)
```

### 场景 2: 实验课
```
时间: 45-60分钟
任务:
1. 不同 K 值的效果对比
2. 初始质心位置的影响
3. 记录迭代次数和结果
4. 提交实验报告（导出Excel）
```

### 场景 3: 自学练习
```
学习路径:
1. 阅读 KMEANS_README.md
2. 完成基础示例操作
3. 尝试不同参数组合
4. 理解算法原理
```

## 📚 相关文档

- **KMEANS_README.md** - 详细使用说明
- **KMEANS_DEPLOYMENT.md** - 部署和配置指南

## 🔗 访问链接

开发环境: http://localhost:3001/kmeans

立即体验 K-Means 算法的魅力！ 🚀