Add ephemeris download script and update README

- Add download_ephemeris.sh script for automated JPL ephemeris file downloads - Support de421, de422, and de440s ephemeris files - Update README.md with download script usage instructions - All text in Traditional Chinese Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
2026-03-09 14:15:25 +08:00
parent 5b78b3c6d9
commit 3407170b8c
2 changed files with 165 additions and 6 deletions
--- a/README.md
+++ b/README.md
@@ -21,7 +21,8 @@ lunar-converter/
 ├── api.py                      # FastAPI REST API 伺服器
 ├── age_calculator.py           # 年齡計算器
 ├── generate_lunar_calendar_json.py  # 批量生成農曆資料
-├── de421.bsp / de422.bsp       # JPL 星曆檔案（需另行下載）
+├── download_ephemeris.sh        # JPL 星曆檔案下載腳本
+├── de421.bsp / de422.bsp       # JPL 星曆檔案
 └── lunar_json/                 # 生成的農曆資料 JSON 檔案
 ```

@@ -46,13 +47,24 @@ pip install skyfield jplephem numpy fastapi uvicorn loguru

 ### 3. 下載 JPL 星曆檔案

-從 [JPL 星曆官網](https://naif.jpl.nasa.gov/pub/naif/generic_kernels/spk/planets/) 下載其中一個：
+使用提供的下載腳本自動下載：

- `de421.bsp` (預設，涵蓋 1900-2050)
- `de422.bsp` (較新，涵蓋更長時間範圍)
- `de440s.bsp` (精簡版，適合 1900-2150)
+```bash
+# 下載預設的 de421 (推薦，涵蓋 1900-2050，約 15MB)
+./download_ephemeris.sh

-將檔案放在專案根目錄。
+# 或下載其他版本
+./download_ephemeris.sh de422   # 涵蓋更長時間範圍，約 500MB
+./download_ephemeris.sh de440s  # 精簡版，1900-2150，約 30MB
+./download_ephemeris.sh all     # 下載全部版本
+```
+
+或從 [JPL 星曆官網](https://naif.jpl.nasa.gov/pub/naif/generic_kernels/spk/planets/) 手動下載，將檔案放在專案根目錄。
+
+**各版本說明：**
+- `de421.bsp` - 預設推薦，涵蓋 1900-2050，約 15MB
+- `de422.bsp` - 涵蓋更長時間範圍（-13000+17000），約 500MB
+- `de440s.bsp` - 精簡版，涵蓋 1900-2150，約 30MB

 ### 4. 生成農曆資料

--- a/download_ephemeris.sh
+++ b/download_ephemeris.sh
@@ -0,0 +1,147 @@
+#!/usr/bin/env bash
+# 下載 JPL 星曆表檔案用於陰曆計算
+# 使用方式: ./download_ephemeris.sh [de421|de422|de440s|all]
+# 預設: de421
+
+set -e
+
+# 輸出顏色
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+NC='\033[0m' # 無顏色
+
+# JPL 星曆表檔案下載網址
+BASE_URL="https://naif.jpl.nasa.gov/pub/naif/generic_kernels/spk/planets"
+
+# 檔案資訊: 名稱 大小mb 說明
+declare -A FILES=(
+    ["de421"]="de421.bsp 15 JPL DE421 (1900-2050, ~15MB)"
+    ["de422"]="de422.bsp 500 JPL DE422 (較長時期範圍, ~500MB)"
+    ["de440s"]="de440s.bsp 30 JPL DE440s (1900-2150, ~30MB)"
+)
+
+# 輸出資訊
+print_info() {
+    echo -e "${GREEN}[資訊]${NC} $1"
+}
+
+# 輸出警告
+print_warn() {
+    echo -e "${YELLOW}[警告]${NC} $1"
+}
+
+# 輸出錯誤
+print_error() {
+    echo -e "${RED}[錯誤]${NC} $1"
+}
+
+# 下載檔案
+download_file() {
+    local name=$1
+    local url=$2
+    local filename=$(basename "$url")
+
+    print_info "正在下載 $filename..."
+
+    if [ -f "$filename" ]; then
+        print_warn "$filename 已存在，跳過下載"
+        return 0
+    fi
+
+    if curl -L -o "$filename" "$url"; then
+        print_info "$filename 下載完成"
+        return 0
+    else
+        print_error "$filename 下載失敗"
+        return 1
+    fi
+}
+
+# 驗證檔案大小
+verify_file() {
+    local filename=$1
+    local expected_size_mb=$2
+
+    if [ ! -f "$filename" ]; then
+        print_error "檔案 $filename 不存在"
+        return 1
+    fi
+
+    local actual_size=$(du -m "$filename" | cut -f1)
+
+    if [ "$actual_size" -lt 1 ]; then
+        print_error "$filename 檔案大小異常"
+        rm -f "$filename"
+        return 1
+    fi
+
+    print_info "$filename 檔案大小: ${actual_size}MB"
+    return 0
+}
+
+# 主下載函式
+download_ephemeris() {
+    local target=${1:-de421}
+
+    case "$target" in
+        de421)
+            print_info "下載 DE421 (推薦，涵蓋 1900-2050)"
+            download_file "de421" "$BASE_URL/a_old_versions/de421.bsp"
+            verify_file "de421.bsp" 15
+            ;;
+        de422)
+            print_info "下載 DE422 (大檔案，涵蓋更長時間)"
+            print_warn "DE422 約 500MB，下載可能需要較長時間..."
+            download_file "de422" "$BASE_URL/a_old_versions/de422.bsp"
+            verify_file "de422.bsp" 500
+            ;;
+        de440s)
+            print_info "下載 DE440s (精簡版，涵蓋 1900-2150)"
+            download_file "de440s" "$BASE_URL/de440s.bsp"
+            verify_file "de440s.bsp" 30
+            ;;
+        all)
+            print_info "下載所有星曆表檔案"
+            for key in "${!FILES[@]}"; do
+                download_ephemeris "$key"
+                echo
+            done
+            ;;
+        list)
+            echo "可用的星曆表檔案:"
+            for key in "${!FILES[@]}"; do
+                echo "  - $key: ${FILES[$key]}"
+            done
+            ;;
+        *)
+            print_error "未知的選項: $target"
+            echo
+            echo "用法: $0 [de421|de422|de440s|all|list]"
+            echo
+            echo "說明:"
+            for key in "${!FILES[@]}"; do
+                echo "  $key - ${FILES[$key]}"
+            done
+            exit 1
+            ;;
+    esac
+}
+
+# 無參數時顯示說明
+if [ $# -eq 0 ]; then
+    echo "下載 JPL 星曆表檔案"
+    echo
+    echo "用法: $0 [de421|de422|de440s|all|list]"
+    echo
+    echo "預設下載: de421"
+    echo
+    download_ephemeris "list"
+    echo
+    read -p "按 Enter 下載 de421，或按 Ctrl+C 取消..."
+    download_ephemeris "de421"
+else
+    download_ephemeris "$1"
+fi
+
+print_info "完成！"