# surflab

**Repository Path**: zhuangbo/surflab

## Basic Information

- **Project Name**: surflab
- **Description**: 开源 3D 数学曲面教学工具
- **Primary Language**: HTML
- **License**: MulanPSL-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-02-18
- **Last Updated**: 2026-02-19

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Surflab - 数学曲面可视化实验室

> 用于教学和学习的交互式数学曲面3D可视化项目

## 简介

**Surflab** 是一个开源的数学曲面可视化项目，致力于为数学教学和学习提供直观、互动的3D可视化工具。

通过 Surflab，你可以：
- 🎨 交互式探索各种经典数学曲面
- 📐 直观理解几何参数的意义
- 📚 学习微分几何和拓扑学的基础概念
- 🎓 为课堂教学提供生动的演示材料

## 特点

- **纯前端实现**：无需后端服务器，直接在浏览器中运行
- **交互式控制**：滑块调节参数，实时观察曲面变化
- **多种显示模式**：彩色表面、线框、高度渐变等
- **配色主题**：多种配色方案
- **响应式设计**：适配不同屏幕尺寸

## 已实现曲面

| 曲面名称 | 文件 | 直纹面 |
|---------|------|--------|
| 马鞍面 (双曲抛物面) | [saddle-surface.html](saddle-surface.html) | ✅ |
| 椭圆抛物面 | [paraboloid.html](paraboloid.html) | ✅ |
| 圆环面 | [torus.html](torus.html) | ✅ |
| 单叶双曲面 | [hyperboloid-1sheet.html](hyperboloid-1sheet.html) | ✅ |
| 双叶双曲面 | [hyperboloid-2sheets.html](hyperboloid-2sheets.html) | ✅ |
| 螺旋面 | [helicoid.html](helicoid.html) | ✅ |
| 莫比乌斯带 | [mobius-strip.html](mobius-strip.html) | ✅ |


## 快速开始

### 安装

Surflab 不需要任何安装！只需克隆或下载项目即可。

```bash
git clone https://gitee.com/zhuangbo/surflab.git
cd surflab
```

### 运行

直接在浏览器中打开任意 `.html` 文件即可使用！

```bash
# 或者在项目目录启动一个简单的 HTTP 服务器
# Python 3
python -m http.server 8080

# 然后在浏览器访问
# http://localhost:8080/torus.html
```

## 使用指南

### 独立3D展示页面

每个曲面都有一个独立的全屏3D展示页面，提供最完整的交互体验：

| 操作 | 说明 |
|------|------|
| 拖动鼠标 | 旋转视角 |
| 滚轮 | 缩放 |
| 右下角设置按钮 | 打开参数面板 |

### 参数面板

参数面板提供以下控制：

- **参数滑块**：调节曲面的几何参数
- **图标开关**：
  - 📐 显示/隐藏坐标轴
  - ╱ 显示/隐藏直母线（仅直纹面）
  - 🔄 自动旋转
- **显示模式**：
  - 🎨 彩色表面
  - ▦ 线框模式
  - 📊 高度渐变
- **配色主题**：多种预设配色方案

## 技术栈

| 技术 | 用途 |
|------|------|
| [Three.js](https://threejs.org/) | 3D 渲染引擎 |
| [KaTeX](https://katex.org/) | 数学公式渲染 |
| [Font Awesome](https://fontawesome.com/) | 图标库 |

## 设计理念

Surflab 遵循极简设计原则：

- **图标优先**：用图标代替文字标签，减少认知负荷
- **悬停提示**：Tooltip 提供辅助说明，不常驻显示
- **分组布局**：相关功能聚合成视觉组
- **渐变反馈**：选中状态使用渐变色高亮

详细的设计规范请参考 [SKILL.md](SKILL.md)。

## 项目结构

```
surflab/
├── {surface-name}.html        # 3D展示页面
├── SKILL.md                   # 设计规范文档
├── README.md                  # 项目说明
└── .agents/
    └── skills/
        └── math-surface-visualization/  # 开发工具
```

## 贡献指南

欢迎贡献！你可以：

1. 提交 Bug 报告或功能建议
2. 实现新的数学曲面
3. 改进现有可视化效果
4. 完善文档

请参阅 [CONTRIBUTING.md](CONTRIBUTING.md) 了解详情。

### 添加新曲面的步骤

1. 参考现有的 `*.html` 模板
2. 实现参数方程的几何生成
3. 添加合适的参数控制和显示选项

> 可以直接使用 AI Agent Skill 来实现新的曲面。

## 学习资源

### 推荐教材

- 《微分几何讲义》 - 陈省身
- 《曲线与曲面的微分几何》 - Do Carmo
- 《拓扑学导论》 - Munkres

### 在线资源

- [MathWorld](https://mathworld.wolfram.com/) - Wolfram 数学世界
- [Wikipedia - Differential geometry](https://en.wikipedia.org/wiki/Differential_geometry)
- [Three.js 文档](https://threejs.org/docs/)

## 致谢

感谢所有为本项目做出贡献的开发者！

## 许可证

MulanPSL-2.0 © Surflab

本项目采用 [木兰宽松许可证第2版](https://license.coscl.org.cn/MulanPSL2) 开源协议。

---

**Surflab** - 数学，看得见！