# Jh Math Geometry

> 國中數學幾何圖形 SVG 產生器。當任何情境需要生成或繪製國中數學幾何圖形時，請一定要使用此技能。 【獨立使用觸發情境】「幫我畫直角三角形」、「畫一個標出ABCD的平行四邊形」、「畫圓心角與圓周角的示意圖」、 「畫三角形的重心/外心/內心」、「畫等腰梯形」、「畫四角柱」、「畫一次函數/拋物線的圖形」、 「幫我畫幾何圖、產生幾何圖、繪製幾何圖形」等。 【被其他技能呼叫觸發情境】出題技能（jh-math-exam）需要幾何題配圖時； 教學簡報技能（soil-teaching-deck）需要幾何插圖時；任何需要圖形素材的技能皆可呼叫此技能。 支援圖形類型（含標籤/代號/刻度/角弧等全套標記）： 三角形（一般/直角/等腰/等邊）、四邊形（平行四邊形/矩形/菱形/梯形）、 圓（弦/弧/切線/扇形/圓心角/圓周角）、坐標平面（直線/拋物線）、 立體圖形（角柱/圓柱/角錐/圓錐）、三角形三心、相似三角形、平行線截角。 圖形可匯出至 Word（.docx）或 PowerPoint（.pptx）。

- Skill: `mathruffian-dot/jh-math-geometry` (Agent Skill, multi-file: 6 files)
- Install (CLI): `npx skillmds@latest add mathruffian-dot/jh-math-geometry`
- Raw SKILL.md: https://api.skillmd.com/api/skills/mathruffian-dot/jh-math-geometry/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: mathruffian-dot (https://skillmd.com/u/mathruffian-dot)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/mathruffian-dot/jh-math-geometry

---


# 國中數學幾何圖形技能（jh-math-geometry）

## 技能概覽

本技能生成適合試卷、簡報、教材的幾何 SVG 圖形，並輸出為 PNG 圖片檔，
可直接插入 Word 文件或 PowerPoint 投影片。

**環境約定**（任何使用前先做）：
- 腳本在**本技能目錄**（這份 SKILL.md 所在資料夾）的 `scripts/`，以 `$GEOM_DIR` 代表
- 產出一律放**當前工作目錄**的 `output/geometry_output/`
- Windows 若無 `python3` 指令請改用 `python`；Bash 片段請在 Git Bash／WSL 執行

```bash
GEOM_DIR="<本技能目錄的絕對路徑>/scripts"   # 例：~/.claude/skills/jh-math-geometry/scripts
mkdir -p output/geometry_output
python3 -m pip install -q cairosvg python-docx python-pptx   # 首次使用安裝一次；Linux 系統 Python 拒絕時加 --break-system-packages
```

---

## 處理流程

### Step 1：理解需求

根據使用者的描述，判斷需要哪些圖形。若不確定，先快速確認：
- 哪個單元（三角形/四邊形/圓/立體...）？
- 需要標哪些字母/數字？
- 是否有特殊標記（直角符號、等邊刻度、角弧）？
- 輸出目標：Word、PPTX 或純圖片下載？

### Step 2：建立圖形規格 JSON

依需求建立 spec，儲存至 `output/geometry_spec.json`：

```json
{
  "figures": [
    {
      "id": "fig1",
      "type": "triangle",
      "config": {
        "subtype": "right",
        "vertex_labels": ["A", "B", "C"],
        "right_angle_at": "C",
        "side_labels": {"AB": "5", "BC": "3", "CA": "4"}
      },
      "canvas": {"width": 280, "height": 220}
    }
  ],
  "options": {"format": "png", "dpi": 150}
}
```

> 詳細參數見本技能目錄下的 `references/figure-catalog.md`（讀取該檔案）。

### Step 3：執行渲染

```bash
python3 "$GEOM_DIR/geometry_renderer.py" output/geometry_spec.json output/geometry_output/
ls output/geometry_output/
```

### Step 4：視覺確認

讀取產生的 `.svg`（或 `.png`）檔案確認圖形是否正確。
若有錯誤（標籤偏移、比例不佳），調整 `config` 後重新執行。

### Step 5：輸出

#### 純圖片
PNG 已在 `output/geometry_output/<id>.png`，直接告知使用者路徑。

#### 插入 Word
```bash
python3 - <<EOF
from docx import Document
from docx.shared import Cm
from docx.enum.text import WD_ALIGN_PARAGRAPH
import sys; sys.path.insert(0, "$GEOM_DIR")
from insert_to_docx import insert_figure, figures_from_manifest

doc = Document()   # 或 Document('existing.docx')
figures_from_manifest('output/geometry_output/manifest.json', doc, width_cm=7.0)
doc.save('output/geometry.docx')
print("✅ output/geometry.docx")
EOF
```

#### 插入 PowerPoint
```bash
python3 - <<EOF
from pptx import Presentation
import sys; sys.path.insert(0, "$GEOM_DIR")
from insert_to_pptx import figures_from_manifest

prs = Presentation()   # 或 Presentation('existing.pptx')
figures_from_manifest('output/geometry_output/manifest.json', prs,
                      mode='individual', title_prefix='幾何圖形')
prs.save('output/geometry.pptx')
print("✅ output/geometry.pptx")
EOF
```

最後在對話中列出產出檔案的路徑。

---

## 被其他技能呼叫的標準流程

當 `jh-math-exam` 或 `soil-teaching-deck` 等技能需要幾何圖形時，
直接在那個技能的流程中插入以下步驟：

```bash
# 1. 找到腳本目錄：同 repo 的 skills/jh-math-geometry/scripts/，或已安裝的 jh-math-geometry 技能
GEOM_DIR=""
for d in "$SKILL_DIR/../jh-math-geometry/scripts" "$HOME/.claude/skills/jh-math-geometry/scripts" \
         "./skills/jh-math-geometry/scripts"; do
  [ -f "$d/geometry_renderer.py" ] && GEOM_DIR="$d" && break
done
python3 -m pip install -q cairosvg

# 2. 建立圖形 spec（Claude 根據題目需求自行決定內容）
mkdir -p output/geometry_output
cat > output/geometry_spec.json << 'SPEC'
{
  "figures": [
    {"id": "q3_fig", "type": "triangle", "config": {...}, "canvas": {"width":250,"height":200}}
  ],
  "options": {"format": "png", "dpi": 150}
}
SPEC

# 3. 渲染
python3 "$GEOM_DIR/geometry_renderer.py" output/geometry_spec.json output/geometry_output/

# 4. 取得 PNG 路徑供插入
FIGURE_PNG="output/geometry_output/q3_fig.png"
```

---

## 圖形類型速查表

| type 值 | 說明 | 常用 subtype |
|---------|------|------------|
| `triangle` | 三角形 | `general` `right` `isosceles` `equilateral` |
| `quadrilateral` | 四邊形 | `parallelogram` `rectangle` `rhombus` `square` `trapezoid` `right_trapezoid` |
| `circle` | 圓 | （無 subtype，用 elements 控制）|
| `coordinate_plane` | 坐標平面 | （含直線、拋物線、點、線段）|
| `solid_3d` | 立體圖形 | `rectangular_prism` `cylinder` `cone` `triangular_prism` `square_pyramid` `triangular_pyramid` |
| `parallel_lines` | 平行線截角 | （n_parallel 控制條數）|
| `triangle_center` | 三角形的心 | `centroid` `circumcenter` `incenter` |
| `similar_triangles` | 相似三角形 | （triangle1 + triangle2 各自設定）|

---

## 標記系統

| 功能 | 參數 | 說明 |
|------|------|------|
| 頂點標籤 | `vertex_labels` | 預設 `["A","B","C"]` |
| 直角符號 | `right_angle_at` | 指定頂點 |
| 角弧 | `angle_arcs` | `{"A":1}` = 一條弧，`{"A":2}` = 兩條弧（全等角）|
| 等邊刻度 | `equal_marks` | `{"AB":1,"CD":1}` = 同一組，`{"EF":2}` = 另一組 |
| 邊長/邊名 | `side_labels` | `{"AB":"5"}` 或 `{"AB":"a"}` |
| 虛線邊 | `dashed_sides` | `["AB"]` |
| 高 | `altitude_from` | 從指定頂點畫高 |
| 中線 | `median_from` | 從指定頂點畫中線 |

---

## 參考資料位置

以下路徑皆相對於**本技能目錄**：

| 需要什麼 | 讀取哪個檔案 |
|----------|-------------|
| 所有圖形類型的完整參數 + 快速複製範例 | `references/figure-catalog.md` |
| SVG 產生引擎原始碼 | `scripts/geometry_renderer.py` |
| SVG → PNG 轉換 | `scripts/svg_to_image.py` |
| 插入 Word 的函式 | `scripts/insert_to_docx.py` |
| 插入 PPTX 的函式 | `scripts/insert_to_pptx.py` |

---

## 注意事項

1. **cairosvg 安裝**：首次使用先 `pip install cairosvg`；Windows 裝不了 cairo 時，渲染器仍會輸出 SVG，可用 `scripts/svg_to_image.py`（Inkscape 備援）或 Edge headless（`msedge --headless --screenshot=<out.png> file:///<abs.svg>`）轉 PNG
2. **座標確認**：讀取 `.svg` 確認後再插入文件
3. **畫布尺寸**：試卷用圖建議 `280×220`；簡報用圖建議 `360×280`
4. **字體**：SVG 使用 serif，匯出 PNG 後在 Word/PPTX 中外觀一致
5. **多圖批次**：figures 陣列可一次放多個圖形，manifest.json 記錄所有輸出路徑