mathruffian-dot 國中數學幾何圖形技能（jh-math-geometry）
技能概覽
本技能生成適合試卷、簡報、教材的幾何 SVG 圖形，並輸出為 PNG 圖片檔， 可直接插入 Word 文件或 PowerPoint 投影片。
環境約定（任何使用前先做）：
- 腳本在本技能目錄（這份 SKILL.md 所在資料夾）的
scripts/，以$GEOM_DIR代表 - 產出一律放當前工作目錄的
output/geometry_output/ - Windows 若無
python3指令請改用python；Bash 片段請在 Git Bash／WSL 執行
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：
{
"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：執行渲染
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
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
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 等技能需要幾何圖形時，
直接在那個技能的流程中插入以下步驟：
# 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 |
注意事項
- cairosvg 安裝：首次使用先
pip install cairosvg；Windows 裝不了 cairo 時，渲染器仍會輸出 SVG，可用scripts/svg_to_image.py（Inkscape 備援）或 Edge headless（msedge --headless --screenshot=<out.png> file:///<abs.svg>）轉 PNG - 座標確認：讀取
.svg確認後再插入文件 - 畫布尺寸：試卷用圖建議
280×220；簡報用圖建議360×280 - 字體：SVG 使用 serif，匯出 PNG 後在 Word/PPTX 中外觀一致
- 多圖批次：figures 陣列可一次放多個圖形，manifest.json 記錄所有輸出路徑