# magic_geo_demo

**Repository Path**: sunfulv/magic_geo_demo

## Basic Information

- **Project Name**: magic_geo_demo
- **Description**: 参考MagicGeo: Training-Free Text-Guided Geometric Diagram Generation论文，借助deepseek大模型，将使用自然语言描述的几何图形，转换为TiKZ代码
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: develop
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-19
- **Last Updated**: 2026-05-27

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# MagicGeo

自然语言 → 精确几何图形的三阶段流水线系统。输入一句中文描述（如"直角三角形ABC中，角A=60度，角B=90度，AB=5"），自动生成可直接编译的 LaTeX TikZ 几何图形代码。

## 工作原理

```
自然语言描述 ──[Stage 1]──> 形式化约束 ──[Stage 2]──> 精确坐标 ──[Stage 3]──> TikZ 代码
      ↑                        │                    │                    │
      └──────── 求解失败时反馈重试 ────────────────────┘                    │
                                                                         │
                                                              ┌─> magic_geo_output.tex
                                                              │   (可直接用 LaTeX 编译为 PDF)
```

### Stage 1 — LLM 自动形式化

使用 DeepSeek 大模型将自然语言描述转换为结构化的几何约束表示（变量 + 约束列表），支持隐含关系推断（如"正方形"→四边相等+四角90°）。

### Stage 2 — 约束求解

自研的数值几何约束求解器，采用自适应梯度下降 + 随机重启策略求解非线性几何约束方程组。所有残差经过归一化处理，支持最多 30 次随机重启和 3000 次迭代优化。

### Stage 3 — TikZ 代码生成

根据精确坐标，由 LLM 生成比例均衡的 LaTeX TikZ 绘图代码，自动计算标注尺寸并包裹为完整的 standalone 文档。

## 支持的几何约束 (17种)

| 约束类型 | 格式 | 说明 |
|---------|------|------|
| `distance` | `distance(A, B, 5)` | 两点距离 |
| `angle` | `angle(A, B, C, 90)` | 三点角度 (∠ABC) |
| `parallel` | `parallel(A, B, C, D)` | AB 平行于 CD |
| `perpendicular` | `perpendicular(A, B, C, D)` | AB 垂直于 CD |
| `collinear` | `collinear(A, B, C)` | 三点共线 (无限直线) |
| `on_segment` | `on_segment(A, D, B)` | 点 D 在线段 AB 上 |
| `midpoint` | `midpoint(A, B, M)` | M 是 AB 中点 |
| `on_circle` | `on_circle(A, O, 3)` | A 在圆 O 上 |
| `equal_radius` | `equal_radius(O, A, B, C)` | 多点到圆心等距 |
| `equal_angle` | `equal_angle(A, B, C, D, E, F)` | ∠ABC = ∠DEF |
| `equal_segment` | `equal_segment(A, B, C, D)` | AB = CD |
| `angle_bisector` | `angle_bisector(A, D, B, C)` | AD 平分 ∠BAC |
| `online_extension` | `online_extension(B, D, C)` | D 在 BC 延长线上 |
| `line_ratio` | `line_ratio(A, B, C, D, 2)` | CD = 2 × AB |
| `angle_relation` | `angle_relation(A, B, C, D, E, F, 2)` | ∠ABC = 2 × ∠DEF |
| `is_point_in_triangle` | `is_point_in_triangle(A, B, C, P)` | P 在 △ABC 内部 |
| `is_point_out_triangle` | `is_point_out_triangle(A, B, C, P)` | P 在 △ABC 外部 |

## 快速开始

### 环境要求

- Python 3.10+
- DeepSeek API Key

### 安装

```bash
pip install -r requirements.txt
```

### 设置 API Key

```bash
export DEEPSEEK_API_KEY="your-api-key"   # Linux/macOS
set DEEPSEEK_API_KEY=your-api-key        # Windows CMD
```

### 运行

```bash
# 完整流水线 (命令行)
python -m magic_geo.main "正方形ABCD边长为5"

# 完整流水线 (Python API)
python example_demo.py

# 仅测试求解器 (无需 API)
python test_solver.py
```

### Python API 示例

```python
from magic_geo.main import MagicGeoPipeline

pipeline = MagicGeoPipeline()
result = pipeline.run("三角形ABC中，角A=60度，角B=90度，AB=5")

print(result["coords"])      # {"A": (0, 0), "B": (5, 0), "C": (5.0, 8.66)}
print(result["tikz_code"])   # TikZ LaTeX 代码
print(result["full_doc"])    # 完整 LaTeX 文档
```

输出文件 `magic_geo_output.tex` 可用任意 LaTeX 引擎编译：

```bash
pdflatex magic_geo_output.tex
```

## 项目结构

```
magic_geo/
├── __init__.py             # 包入口
├── main.py                 # 三阶段流水线编排
├── config.py               # 系统配置 (API、求解器参数)
├── llm_client.py           # DeepSeek API 客户端
├── stage1_formalizer.py    # Stage 1: 自然语言 → 形式化约束 (LLM)
├── stage2_solver.py        # Stage 2: 约束求解器 (数值优化)
├── stage3_tikz.py          # Stage 3: 坐标 → TikZ 代码 (LLM)
├── constraint_parser.py    # 约束字符串解析 + 残差计算
├── validator.py            # 求解结果验证
└── geometry_utils.py       # 几何工具函数
test_solver.py              # 求解器单元测试
example_demo.py             # 完整流程演示
requirements.txt            # 依赖
```

## 配置说明

在 `magic_geo/config.py` 中可调整：

| 参数 | 默认值 | 说明 |
|------|--------|------|
| `DEEPSEEK_MODEL` | `deepseek-v4-pro` | LLM 模型名 |
| `MAX_ITERATIONS` | 3000 | 梯度下降最大迭代次数 |
| `MAX_RESTARTS` | 30 | 随机重启次数 |
| `CONVERGENCE_THRESHOLD` | 1e-10 | 收敛阈值 |
| `MAX_FEEDBACK_LOOPS` | 5 | 形式化修复的最大重试次数 |

## 参考资料

- **论文**: [MagicGeo: Training-Free Text-Guided Geometric Diagram Generation](https://arxiv.org/abs/2502.13855v1)
- **官方开源仓库**: [hellozting/MagicGeo](https://github.com/hellozting/MagicGeo)