From 820679df66a3db0466f003ad6f375952de17ae67 Mon Sep 17 00:00:00 2001 From: gbanyan Date: Mon, 15 Dec 2025 23:18:24 +0800 Subject: [PATCH] Add Traditional Chinese README with language switching MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Create README.zh-TW.md with full Traditional Chinese translation - Keep professional terms (NSGC, PED, Phenotype, etc.) in English - Add language switching links at the top of both README files 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 --- README.md | 17 +++ README.zh-TW.md | 299 ++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 316 insertions(+) create mode 100644 README.zh-TW.md diff --git a/README.md b/README.md index 898c4aa..72b65a9 100644 --- a/README.md +++ b/README.md @@ -1,7 +1,24 @@ # Pedigree Draw +**English** | [繁體中文](README.zh-TW.md) + A professional pedigree (family tree) drawing tool for genetic counselors and bioinformatics professionals. +## Motivation & Background + +This project is created by an author with Usher syndrome. + +The motivation behind this work is to support research +in genetics, genealogy, and bioinformatics, and to explore +how visualization tools may assist in understanding +hereditary conditions. + +The author explicitly supports research related to +Usher syndrome and other genetic disorders, and hopes +this project may contribute, even in a small way, +to the bioinformatics research community. + + ## Features - Import/Export GATK PED files diff --git a/README.zh-TW.md b/README.zh-TW.md new file mode 100644 index 0000000..a6c9bbb --- /dev/null +++ b/README.zh-TW.md @@ -0,0 +1,299 @@ +# Pedigree Draw + +[English](README.md) | **繁體中文** + +專為遺傳諮詢師和生物資訊專業人員設計的 Pedigree（家族樹）繪圖工具。 + +## 動機與背景 + +本專案由一位患有 Usher syndrome 的作者所建立。 + +建立此工具的動機是為了支援遺傳學、系譜學和 Bioinformatics 領域的研究， +並探索視覺化工具如何幫助理解遺傳性疾病。 + +作者明確支持與 Usher syndrome 及其他遺傳疾病相關的研究， +並希望此專案能以某種方式為 Bioinformatics 研究社群做出貢獻。 + +## 功能特色 + +- 匯入/匯出 GATK PED 檔案 +- 互動式網頁編輯器 +- 支援標準 Pedigree 符號（NSGC 標準） +- 匯出為 SVG、PNG 或 PED 格式 +- 完整 Pedigree 功能：Affected/Unaffected/Carrier 狀態、雙胞胎、近親婚配、領養標記等 + +--- + +## 快速開始 + +### 前置需求 + +您的電腦需要安裝 **Node.js**（版本 18 或更高）。 + +#### 檢查 Node.js 是否已安裝： + +```bash +node --version +npm --version +``` + +如果兩個指令都顯示版本號（例如 `v20.10.0` 和 `10.2.0`），就可以開始了！ + +#### 如果尚未安裝 Node.js： + +**Windows：** +1. 前往 https://nodejs.org/ +2. 下載 **LTS** 版本（推薦） +3. 執行安裝程式，點擊「下一步」完成所有步驟 +4. 安裝完成後重新啟動終端機/命令提示字元 + +**macOS：** +```bash +# 使用 Homebrew（推薦） +brew install node + +# 或從 https://nodejs.org/ 下載 +``` + +**Linux (Ubuntu/Debian)：** +```bash +curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash - +sudo apt-get install -y nodejs +``` + +--- + +### 步驟 1：安裝相依套件（僅首次需要） + +開啟終端機並切換到專案資料夾： + +```bash +cd /path/to/pedigree-draw +``` + +安裝必要的套件： + +```bash +npm install +``` + +這會下載所有必要的相依套件。您只需要執行一次（或在更新程式碼後重新執行）。 + +--- + +### 步驟 2：啟動伺服器 + +執行啟動腳本： + +```bash +./start.sh +``` + +**Windows 使用者**請執行： +```bash +npm run dev +``` + +您應該會看到類似以下的輸出： +``` +========================================== + Pedigree Draw Server Started! +========================================== + + Local: http://localhost:5173/pedigree-draw/ + Network: http://192.168.x.x:5173/pedigree-draw/ + + To stop the server, run: ./stop.sh +========================================== +``` + +--- + +### 步驟 3：在瀏覽器中開啟 + +開啟您的網頁瀏覽器並前往： + +- **本機存取：** http://localhost:5173/pedigree-draw/ +- **從同一網路中的其他裝置存取：** 使用上方顯示的 Network URL + +--- + +### 步驟 4：停止伺服器 + +使用完畢後，停止伺服器： + +```bash +./stop.sh +``` + +**Windows 使用者**請在終端機中按 `Ctrl+C` 停止伺服器。 + +--- + +## 如何使用應用程式 + +### 建立新的 Pedigree + +1. 點擊左側面板中的 **「New Pedigree」** +2. 輸入 Family ID（例如「FAM001」） + +### 新增成員 + +使用頂部工具列： + +| 按鈕 | 說明 | +|------|------| +| Male | 新增男性 | +| Female | 新增女性 | +| Unknown | 新增未知性別 | + +### 選取成員 + +- **點擊**成員以選取 +- 選取的成員周圍會顯示藍色虛線邊框 +- 右側面板會顯示可編輯的屬性 + +### 新增關係 + +首先**選取一個成員**，然後使用這些工具列按鈕： + +| 按鈕 | 說明 | +|------|------| +| Spouse | 在選取成員旁邊建立配偶並連接 | +| Child | 在選取成員下方建立子女 | +| Parents | 在選取成員上方建立父母 | + +### 編輯屬性 + +選取成員後，使用右側面板編輯： + +- **Label**：顯示名稱 +- **Sex**：Male / Female / Unknown +- **Phenotype**：Unaffected / Affected / Carrier / Unknown +- **Status**：Deceased、Proband、Adopted、Miscarriage、Stillbirth + +### 畫布控制 + +| 按鈕 | 說明 | +|------|------| +| + | 放大 | +| - | 縮小 | +| Reset | 重設為 100% 縮放，置中顯示 | +| Fit | 自動調整以顯示所有內容 | + +您也可以： +- **拖曳**成員來重新定位 +- **拖曳**背景來平移畫布 +- **滾動**滑鼠滾輪來縮放 + +### 匯入 PED 檔案 + +1. 點擊左側面板中的 **「Import PED」**，或 +2. 將 `.ped` 檔案拖放到拖放區域 + +### 匯出 + +| 按鈕 | 說明 | +|------|------| +| Export SVG | 向量圖檔（可在 Illustrator 等軟體中編輯） | +| Export PNG | 點陣圖檔（適用於文件、簡報） | +| Export PED | GATK PED 格式檔案 | + +### 鍵盤快捷鍵 + +| 快捷鍵 | 動作 | +|--------|------| +| **Delete** 或 **Backspace** | 刪除選取的成員或關係 | +| **Escape** | 取消選取 | +| **Ctrl+Z** | 復原 | +| **Ctrl+Y** 或 **Ctrl+Shift+Z** | 重做 | + +### 編輯關係 + +1. 點擊兩人之間的**連接線**以選取關係 +2. 右側面板會顯示關係選項： + - **Add Child**：為這對夫妻新增 Male/Female/Unknown 子女 + - **Partnership Status**：Married、Unmarried、Separated、Divorced + - **Consanguinity**：標記為近親婚配（血親關係） + - **Children Status**：Infertility 或 No children by choice + +### 自動對齊 + +如果拖曳後元素位置變得混亂，點擊工具列中的 **Auto Align** 按鈕，即可根據世代和關係自動重新排列所有家族成員。 + +--- + +## PED 檔案格式 + +本工具支援標準 GATK PED 格式（6 欄，以空白分隔）： + +``` +FamilyID IndividualID PaternalID MaternalID Sex Phenotype +FAM001 father 0 0 1 1 +FAM001 mother 0 0 2 1 +FAM001 child1 father mother 1 2 +``` + +- **Sex**：1 = Male、2 = Female、0 = Unknown +- **Phenotype**：1 = Unaffected、2 = Affected、0 = Unknown +- **PaternalID/MaternalID**：使用「0」表示未知/創始者 + +--- + +## 疑難排解 + +### 執行 ./start.sh 時出現「Permission denied」 + +確保腳本具有執行權限： +```bash +chmod +x start.sh stop.sh +``` + +### 伺服器無法啟動 + +1. 檢查 port 5173 是否已被使用： + ```bash + lsof -i :5173 + ``` + +2. 終止現有程序後重試： + ```bash + ./stop.sh + ./start.sh + ``` + +### 網頁無法載入 + +- 確認您使用的 URL 結尾有 `/pedigree-draw/` +- 嘗試清除瀏覽器快取並重新整理 + +### 無法從其他裝置存取 + +- 確保兩台裝置在同一網路中 +- 檢查防火牆設定是否允許 port 5173 +- 使用 Network URL（而非 localhost） + +--- + +## 開發 + +### 建置 Production 版本 + +```bash +npm run build +``` + +輸出將在 `dist/` 資料夾中。 + +### 部署到 GitHub Pages + +```bash +npm run build +# 然後將 dist/ 資料夾內容上傳到您的 GitHub Pages +``` + +--- + +## 授權條款 + +MIT