trip-moments-skill 1.0.0

package/.agents/skills/trip-moments/scripts/crop.py

@@ -0,0 +1,367 @@
+#!/usr/bin/env python3
+"""Batch smart-crop photos for WeChat Moments (trip-moments skill).
+
+Crops to a target aspect ratio using an energy-based window (keeps the
+busiest, most detailed region instead of a blind center crop), then resizes
+to a Moments-friendly width.
+
+Composition is NOT fixed: with --ai-compose the vision model reviews all
+photos in one call and suggests each photo's best ratio + framing note
+(subject, negative space, horizon), then every photo is cropped at its own
+suggested ratio. Falls back to --ratio when AI is unavailable.
+
+usage:
+  python crop.py <file-or-folder>... [--ratio 3:4] [--ai-compose] [--width 1080]
+                 [--all] [-o OUTDIR] [--quality 92]
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import shutil
+import sys
+from pathlib import Path
+
+import numpy as np
+from PIL import Image
+
+if sys.platform == "win32":
+    try:
+        sys.stdout.reconfigure(encoding="utf-8")
+        sys.stderr.reconfigure(encoding="utf-8")
+    except Exception:
+        pass
+
+sys.path.insert(0, str(Path(__file__).parent))
+from imquality import list_images, load_rgb
+
+RATIO_PRESETS = {"1:1", "3:4", "4:3", "16:9", "9:16"}
+
+
+def _energy(gray: np.ndarray) -> np.ndarray:
+    gx, gy = np.gradient(gray)
+    return np.hypot(gx, gy)
+
+
+def _best_window(profile: np.ndarray, width: int) -> int:
+    """Start index of the `width` window with the largest sum (energy)."""
+    if width >= len(profile):
+        return 0
+    prefix = np.concatenate(([0.0], np.cumsum(profile)))
+    sums = prefix[width:] - prefix[:-width]
+    return int(np.argmax(sums))
+
+
+def _saliency_map(img: Image.Image) -> np.ndarray:
+    """Per-pixel saliency in [0, ~2] (smartcrop.js-style feature fusion).
+
+    detail (Laplacian edges on luma) + skin tones (highest weight: people are
+    the usual subject) + saturation, all under brightness constraints.
+    Near-black / blown-out pixels are dead zones: multiplied to ~zero so dead
+    bands never anchor the crop window.
+    """
+    rgb = np.asarray(img, dtype=np.float64) / 255.0
+    r, g, b = rgb[..., 0], rgb[..., 1], rgb[..., 2]
+    luma = 0.2126 * r + 0.7152 * g + 0.0722 * b
+
+    lap = np.zeros_like(luma)
+    lap[1:-1, 1:-1] = (4 * luma[1:-1, 1:-1] - luma[:-2, 1:-1] - luma[2:, 1:-1]
+                       - luma[1:-1, :-2] - luma[1:-1, 2:])
+    detail = np.clip(np.abs(lap) * 1.5, 0, 1)
+
+    skin_dist = np.sqrt((r - 0.78) ** 2 + (g - 0.57) ** 2 + (b - 0.44) ** 2)
+    skin = np.clip((0.30 - skin_dist) / 0.30, 0, 1)
+    skin *= np.clip((luma - 0.15) / 0.15, 0, 1) * np.clip((0.93 - luma) / 0.15, 0, 1)
+
+    sat = rgb.max(axis=2) - rgb.min(axis=2)
+    sat_score = np.clip(sat / 0.45, 0, 1) * np.clip((luma - 0.08) / 0.12, 0, 1) \
+        * np.clip((0.92 - luma) / 0.12 + 0.4, 0, 1)
+
+    dead = np.clip((0.055 - luma) / 0.055, 0, 1)  # 1 where crushed black
+    score = (detail * 0.6 + skin * 1.2 + sat_score * 0.5) * (1.0 - dead)
+    return score
+
+
+def _pos_weight(w: int, h: int) -> np.ndarray:
+    """Composition prior: thirds-line bonus + edge penalty + mild center bias."""
+    def axis(n: int) -> np.ndarray:
+        v = (np.arange(n) + 0.5) / n
+        bonus = np.zeros(n)
+        for t in (1.0 / 3, 2.0 / 3):
+            bonus += 0.30 * np.exp(-((v - t) / 0.07) ** 2)
+        bonus += 0.12 * np.exp(-((v - 0.5) / 0.25) ** 2)
+        edge = np.clip((0.06 - np.minimum(v, 1.0 - v)) / 0.06, 0, 1)
+        return 1.0 + bonus - 0.45 * edge
+    return np.outer(axis(h), axis(w))
+
+
+def smart_crop(img: Image.Image, ratio: tuple[int, int], anchor: tuple[float, float] | None = None) -> Image.Image:
+    """Saliency-aware crop: build a feature map (detail/skin/saturation, dead
+    zones excluded), weight it by composition priors (thirds/center/edges),
+    then slide the crop window along the long axis to the max-saliency spot.
+    """
+    rw, rh = ratio
+    w, h = img.size
+    work = img.copy()
+    work.thumbnail((1024, 1024), Image.LANCZOS)
+    sal = _saliency_map(work)
+    sal *= _pos_weight(sal.shape[1], sal.shape[0])
+    scale = w / sal.shape[1]
+
+    if anchor is None:
+        anchor = _saliency_focus(sal)
+
+    target = rw / rh
+    ww, hh = work.size
+    if ww / hh > target:  # too wide: slide horizontally
+        cw = min(ww, round(hh * target))
+        profile = sal.sum(axis=0)
+        w_idx = max(1, round(cw / scale))
+        x0 = _best_window_anchored(profile, w_idx,
+                                   anchor[0] * sal.shape[1] if anchor else None)
+        x0s = int(x0 * scale)
+        return img.crop((x0s, 0, x0s + cw, h))
+    ch = min(hh, round(ww / target))
+    profile = sal.sum(axis=1)
+    h_idx = max(1, round(ch / scale))
+    y0 = _best_window_anchored(profile, h_idx,
+                               anchor[1] * sal.shape[0] if anchor else None)
+    y0s = int(y0 * scale)
+    return img.crop((0, y0s, w, y0s + ch))
+
+
+def _saliency_focus(sal: np.ndarray) -> tuple[float, float]:
+    """Normalized (x, y) centroid of the top-5% saliency mass."""
+    total = float(sal.sum())
+    if total <= 0:
+        return (0.5, 0.5)
+    flat = sal.ravel()
+    k = max(1, int(flat.size * 0.05))
+    thr = np.partition(flat, -k)[-k]
+    ys, xs = np.nonzero(sal >= thr)
+    wts = sal[sal >= thr]
+    cx = float((xs * wts).sum() / wts.sum()) / sal.shape[1]
+    cy = float((ys * wts).sum() / wts.sum()) / sal.shape[0]
+    return (cx, cy)
+
+
+def _best_window_anchored(profile: np.ndarray, width: int, anchor: float | None) -> int:
+    """Best-saliency window; with an anchor, restricted to windows covering it."""
+    n = len(profile)
+    if width >= n:
+        return 0
+    prefix = np.concatenate(([0.0], np.cumsum(profile)))
+    sums = prefix[width:] - prefix[:-width]
+    if anchor is None:
+        return int(np.argmax(sums))
+    a = min(n - 1, max(0, int(anchor)))
+    lo, hi = max(0, a - width + 1), min(a, n - width)
+    if lo > hi:
+        return int(np.argmax(sums))
+    return lo + int(np.argmax(sums[lo:hi + 1]))
+
+
+def smart_crop_centered(img: Image.Image, ratio: tuple[int, int],
+                        anchor: tuple[float, float]) -> Image.Image:
+    """Fallback refit: window dead-centered on the subject, saliency ignored."""
+    rw, rh = ratio
+    w, h = img.size
+    target = rw / rh
+    if w / h > target:
+        cw = min(w, round(h * target))
+        x0 = min(w - cw, max(0, round(anchor[0] * w - cw / 2)))
+        return img.crop((x0, 0, x0 + cw, h))
+    ch = min(h, round(w / target))
+    y0 = min(h - ch, max(0, round(anchor[1] * h - ch / 2)))
+    return img.crop((0, y0, w, y0 + ch))
+
+
+VERIFY_PROMPT = """你将看到成对的图片，每对两张：第一张是原图，第二张是按建议构图裁剪后的结果。
+请严格核查以下两点：
+1. 主体完整性：裁剪后画面主体（人物/建筑/景物等）是否完整保留，没有被切掉一半或肢体只剩残缺；
+2. 构图合理性：构图是否自然美观、主体突出，没有灾难性的严重切边。
+原图本身如果已经有残缺，请按照原图所具备的完整度来核定。
+只输出 JSON 数组，每对图片一个对象：
+[{"i":1,"主体完整":true,"构图合理":true,"原因":"<=14字说明，没有问题则空着"}]"""
+
+
+def verify_crops(pairs: list[tuple[Path, Path]]) -> list[tuple[Path, Path, str]]:
+    """Self-review: original vs cropped, per pair. Returns failing pairs+reason."""
+    from aiclient import AIError, json_from_reply, vision_client
+    from imquality import thumbnail_data_url
+
+    urls = []
+    for src, dst in pairs:
+        urls.append(thumbnail_data_url(src, max_side=640))
+        urls.append(thumbnail_data_url(dst, max_side=640))
+    try:
+        client, model = vision_client()
+        reply = client.chat_vision(urls, VERIFY_PROMPT, model=model, timeout=180)
+        items = json_from_reply(reply)
+        if not isinstance(items, list):
+            return []
+        problems = []
+        for item, pair in zip(items, pairs):
+            if not (item.get("主体完整", True) and item.get("构图合理", True)):
+                problems.append((pair[0], pair[1], str(item.get("原因", "")).strip()))
+        if problems:
+            print(f"[warn] 视觉复核发现 {len(problems)} 处裁剪截断风险，自动居中回退重裁")
+        else:
+            print(f"[ok] 视觉复核通过：{len(pairs)} 组裁剪均主体完整")
+        return problems
+    except (AIError, ValueError) as exc:
+        print(f"[warn] 视觉复核未执行: {exc}")
+        return []
+
+
+def parse_ratio(text: str) -> tuple[int, int]:
+    try:
+        w, h = text.lower().split(":", 1)
+        return int(w), int(h)
+    except ValueError:
+        raise SystemExit(f"[error] 非法比例格式 '{text}' (支持如 3:4, 16:9, 1:1)")
+
+
+COMPOSE_PROMPT = """请通览这组旅游照片的构图与意境。这些照片要发朋友圈，请综合判断每张最适合的画幅比例。
+可选比例：1:1 (正方形局部)、3:4 (竖构图标准朋友圈画幅)、4:3 (横构图风景)、
+16:9 (超宽风景视野)、9:16 (通天长构图，适合极高建筑或前后景拉伸)、
+**原图** (原图构图已经极好或地平线非常舒展，不需要任何裁剪，保留原样)。
+判断依据：主体形态、视觉延伸方向、故事重心位置、地平线；只有在裁剪后能明显提升视觉冲击力时才建议裁剪。
+找出每张照片的“核心视觉主体”（例如人物/脸/手/主体建筑物），并给出该主体中心点的
+百分比坐标（x 从左到右，y 从上到下，0-100 整数）。如果照片是人像写真（带头肩），
+请确保坐标落在主体面部或上半身中心。
+
+只输出严格的 JSON 数组，每张照片一个对象：
+[{"i":1,"比例":"3:4 或 原图","原因":"<=16字","主体":"说明","主体x":50,"主体y":45}]"""
+
+
+def ai_compose(files: list[Path]) -> dict[Path, dict]:
+    """One batched vision call -> per-photo {ratio, reason, anchor}. Never raises."""
+    from aiclient import AIError, json_from_reply, vision_client
+    from imquality import thumbnail_data_url
+
+    urls = [thumbnail_data_url(p, max_side=768) for p in files]
+    try:
+        client, model = vision_client()
+        reply = client.chat_vision(urls, COMPOSE_PROMPT, model=model, timeout=120)
+        items = json_from_reply(reply)
+        if not isinstance(items, list):
+            raise ValueError("not a list")
+        out: dict[Path, dict] = {}
+        for item, src in zip(items, files):
+            raw_ratio = str(item.get("比例", "3:4"))
+            keep = any(w in raw_ratio for w in ("原图", "保留", "不裁", "原始"))
+            if keep:
+                ratio = None  # None = keep original
+            else:
+                try:
+                    ratio = parse_ratio(raw_ratio)
+                except SystemExit:
+                    ratio = (3, 4)
+            try:
+                ax = min(100.0, max(0.0, float(item.get("主体x", 50)))) / 100
+                ay = min(100.0, max(0.0, float(item.get("主体y", 50)))) / 100
+            except (TypeError, ValueError):
+                ax, ay = 0.5, 0.5
+            out[src] = {"ratio": ratio, "reason": str(item.get("原因", "")).strip(),
+                        "subject": str(item.get("主体", "")).strip(), "anchor": (ax, ay)}
+        for f in files:
+            out.setdefault(f, {"ratio": (3, 4), "reason": "模型未返回建议，默认采用 3:4",
+                               "subject": "", "anchor": (0.5, 0.5)})
+        print(f"[ok] AI 智能构图完成 {len(out)}/{len(files)} 张 (模型: {model})")
+        return out
+    except (AIError, ValueError) as exc:
+        print(f"[warn] AI 智能构图失败，降级为默认 --ratio 裁剪: {exc}")
+        return {}
+
+
+def main() -> int:
+    ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
+    ap.add_argument("inputs", nargs="+", help="图片文件或文件夹路径")
+    ap.add_argument("--ratio", default="3:4", help="目标长宽比 W:H (默认 3:4；开启 --ai-compose 时作为兜底)")
+    ap.add_argument("--ai-compose", action="store_true",
+                    help="启用大模型多模态智能构图与画幅推荐")
+    ap.add_argument("--width", type=int, default=1080, help="输出宽度像素 (默认 1080)")
+    ap.add_argument("--all", action="store_true", help=f"生成全部预设比例: {sorted(RATIO_PRESETS)}")
+    ap.add_argument("-o", "--outdir", help="输出目录 (默认 <input dir>/trip-moments-output/cropped)")
+    ap.add_argument("--quality", type=int, default=92)
+    args = ap.parse_args()
+
+    ratios = [(1, 1), (3, 4), (4, 3), (16, 9), (9, 16)] if args.all else [parse_ratio(args.ratio)]
+
+    files: list[Path] = []
+    for item in args.inputs:
+        p = Path(item)
+        if not p.exists():
+            print(f"[warn] 路径不存在，已跳过: {p}")
+            continue
+        files.extend(list_images(p))
+    if not files:
+        print("[error] 未找到任何有效图片文件")
+        return 1
+
+    outroot = Path(args.outdir) if args.outdir else files[0].parent / "trip-moments-output" / "cropped"
+    outroot.mkdir(parents=True, exist_ok=True)
+
+    suggestions: dict[Path, dict] = {}
+    if args.ai_compose:
+        suggestions = ai_compose(files)
+        if not suggestions:
+            print("[error] --ai-compose 执行失败，已中止（避免生成未按 AI 建议裁剪的文件）。\n"
+                  "请检查网络或 AI 配置，或直接指定 --ratio 进行局部裁剪。")
+            return 2
+        compose_path = outroot / "compose.json"
+        compose_path.write_text(json.dumps({
+            src.name: {"ratio": list(s["ratio"]) if s["ratio"] else None,
+                       "subject": s["subject"], "anchor": s["anchor"],
+                       "reason": s["reason"]}
+            for src, s in suggestions.items()
+        }, ensure_ascii=False, indent=1), encoding="utf-8")
+        print(f"[ok] 构图建议已保存至 {compose_path.name} (grid9 拼图将自动复用主体锚点)")
+
+    cropped_pairs: list[tuple[Path, Path]] = []
+    kept_originals = 0
+    for src in files:
+        img = load_rgb(src)
+        if suggestions:
+            s = suggestions[src]
+            ratio, why = s["ratio"], s["reason"]
+            who = f", 主体:{s['subject']}" if s["subject"] else ""
+            if ratio is None:
+                dst = outroot / f"{src.stem}_原图{src.suffix.lower()}"
+                shutil.copy2(src, dst)
+                kept_originals += 1
+                print(f"{src.name}: 原图保留 ({why}{who}) -> {dst.name}")
+                continue
+            print(f"{src.name}: 裁剪建议 {ratio[0]}:{ratio[1]} ({why}{who})")
+            ratios_this = [ratio]
+            anchor = s["anchor"]
+        else:
+            ratios_this = ratios
+            anchor = None
+        for ratio in ratios_this:
+            cropped = smart_crop(img, ratio, anchor=anchor)
+            out_w = args.width
+            out_h = round(out_w * ratio[1] / ratio[0])
+            cropped = cropped.resize((out_w, out_h), Image.LANCZOS)
+            dst = outroot / f"{src.stem}_{ratio[0]}x{ratio[1]}.jpg"
+            cropped.save(dst, "JPEG", quality=args.quality)
+            cropped_pairs.append((src, dst))
+            print(f"  -> {dst.name} ({out_w}x{out_h})")
+
+    if suggestions and cropped_pairs:
+        for src, dst, prob in verify_crops(cropped_pairs):
+            refit = smart_crop_centered(load_rgb(src), suggestions[src]["ratio"],
+                                        suggestions[src]["anchor"])
+            out_w = args.width
+            ratio = suggestions[src]["ratio"]
+            refit = refit.resize((out_w, round(out_w * ratio[1] / ratio[0])), Image.LANCZOS)
+            refit.save(dst, "JPEG", quality=args.quality)
+            print(f"  [refit] {src.name}: 发现裁剪问题({prob or '主体截断'})，已居中主体重新裁剪 -> {dst.name}")
+    tail = f" (其中 {kept_originals} 张保留原图未裁)" if kept_originals else ""
+    print(f"[ok] {len(files)} 张图片处理完毕 -> {outroot}{tail}")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/.agents/skills/trip-moments/scripts/enhance.py

@@ -0,0 +1,79 @@
+#!/usr/bin/env python3
+"""Free local photo enhancement — the zero-cost base polish option (trip-moments skill).
+
+Conservative, non-destructive polish: auto-contrast, gentle saturation and
+sharpness lift, exposure-aware brightness. Pixels only get nudged, never
+repainted (unlike AI editing, content is guaranteed unchanged). No API key.
+
+For heavier retouching (去路人/换天气) use retouch.py instead — that repaints.
+
+usage:
+  python enhance.py <files-or-folder> [-o OUTDIR] [--strength 1.0]
+"""
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+from PIL import ImageEnhance, ImageOps
+
+if sys.platform == "win32":
+    try:
+        sys.stdout.reconfigure(encoding="utf-8")
+        sys.stderr.reconfigure(encoding="utf-8")
+    except Exception:
+        pass
+
+sys.path.insert(0, str(Path(__file__).parent))
+from imquality import exposure_stats, list_images, load_rgb
+
+
+def enhance(img, strength: float):
+    img = ImageOps.autocontrast(img, cutoff=1)
+    img = ImageEnhance.Color(img).enhance(1 + 0.10 * strength)
+    expo = exposure_stats(img)
+    if expo["mean"] < 90:  # 欠曝提亮，越暗提亮越多
+        img = ImageEnhance.Brightness(img).enhance(1 + 0.18 * strength * min(1.0, (90 - expo["mean"]) / 60))
+    elif expo["mean"] > 195:  # 过曝压高光
+        img = ImageEnhance.Brightness(img).enhance(1 - 0.10 * strength)
+    img = ImageEnhance.Sharpness(img).enhance(1 + 0.25 * strength)
+    return img
+
+
+def main() -> int:
+    ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
+    ap.add_argument("inputs", nargs="+", help="图片文件或文件夹路径")
+    ap.add_argument("--strength", type=float, default=1.0,
+                    help="调节强度 0.5=微调 / 1.0=标准 / 1.5=较强 (默认 1.0)")
+    ap.add_argument("-o", "--outdir", help="输出目录 (默认 <input dir>/trip-moments-output/enhanced)")
+    args = ap.parse_args()
+
+    files: list[Path] = []
+    for item in args.inputs:
+        p = Path(item)
+        if not p.exists():
+            print(f"[warn] 路径不存在，已跳过: {p}")
+            continue
+        files.extend(list_images(p))
+    if not files:
+        print("[error] 未找到任何有效图片文件")
+        return 1
+
+    outdir = Path(args.outdir) if args.outdir else files[0].parent / "trip-moments-output" / "enhanced"
+    outdir.mkdir(parents=True, exist_ok=True)
+    for src in files:
+        img = enhance(load_rgb(src), args.strength)
+        dst = outdir / f"{src.stem}_enh.jpg"
+        img.save(dst, "JPEG", quality=93)
+        print(f"  [ok] {src.name} -> {dst.name}")
+    print(f"[done] {len(files)} 张照片完成本地画质提升 (零成本、保真) -> {outdir}")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/.agents/skills/trip-moments/scripts/exif_gps.py

@@ -0,0 +1,170 @@
+#!/usr/bin/env python3
+"""Extract EXIF GPS + capture time from photos into JSON (trip-moments skill).
+
+Feeds route_map.py: outputs a time-sorted list of {file, time, lat, lon} plus
+GCJ-02 coordinates (the datum AMap uses — raw EXIF is WGS-84 and would sit
+~300-600m off a Chinese map if used directly).
+
+usage:
+  python exif_gps.py <folder-or-files...> [-o gps.json] [--wgs84]
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import math
+import sys
+from pathlib import Path
+
+from PIL import Image
+
+if sys.platform == "win32":
+    try:
+        sys.stdout.reconfigure(encoding="utf-8")
+        sys.stderr.reconfigure(encoding="utf-8")
+    except Exception:
+        pass
+
+sys.path.insert(0, str(Path(__file__).parent))
+from imquality import list_images
+
+# --- WGS-84 -> GCJ-02 (Mars coordinates) -----------------------------------
+_A = 6378245.0
+_EE = 0.00669342162296594323
+
+
+def _out_of_china(lon: float, lat: float) -> bool:
+    return not (73.66 < lon < 135.05 and 3.86 < lat < 53.55)
+
+
+def _tlat(x: float, y: float) -> float:
+    r = -100.0 + 2.0 * x + 3.0 * y + 0.2 * y * y + 0.1 * x * y + 0.2 * math.sqrt(abs(x))
+    r += (20.0 * math.sin(6.0 * x * math.pi) + 20.0 * math.sin(2.0 * x * math.pi)) * 2.0 / 3.0
+    r += (20.0 * math.sin(y * math.pi) + 40.0 * math.sin(y / 3.0 * math.pi)) * 2.0 / 3.0
+    r += (160.0 * math.sin(y / 12.0 * math.pi) + 320.0 * math.sin(y * math.pi / 30.0)) * 2.0 / 3.0
+    return r
+
+
+def _tlon(x: float, y: float) -> float:
+    r = 300.0 + x + 2.0 * y + 0.1 * x * x + 0.1 * x * y + 0.1 * math.sqrt(abs(x))
+    r += (20.0 * math.sin(6.0 * x * math.pi) + 20.0 * math.sin(2.0 * x * math.pi)) * 2.0 / 3.0
+    r += (20.0 * math.sin(x * math.pi) + 40.0 * math.sin(x / 3.0 * math.pi)) * 2.0 / 3.0
+    r += (150.0 * math.sin(x / 12.0 * math.pi) + 300.0 * math.sin(x / 30.0 * math.pi)) * 2.0 / 3.0
+    return r
+
+
+def wgs84_to_gcj02(lon: float, lat: float) -> tuple[float, float]:
+    """Transform GPS coordinates from WGS-84 to GCJ-02 (for Chinese maps)."""
+    if _out_of_china(lon, lat):
+        return lon, lat
+    dlat = _tlat(lon - 105.0, lat - 35.0)
+    dlon = _tlon(lon - 105.0, lat - 35.0)
+    radlat = lat / 180.0 * math.pi
+    magic = 1.0 - _EE * math.sin(radlat) ** 2
+    sqrtmagic = math.sqrt(magic)
+    dlat = (dlat * 180.0) / ((_A * (1 - _EE)) / (magic * sqrtmagic) * math.pi)
+    dlon = (dlon * 180.0) / (_A / sqrtmagic * math.cos(radlat) * math.pi)
+    return lon + dlon, lat + dlat
+
+
+# --- EXIF reading -----------------------------------------------------------
+def _rational_to_float(v) -> float:
+    """EXIF rationals arrive as IFDRational or tuples of (num, den)."""
+    try:
+        return float(v)
+    except (TypeError, ValueError):
+        pass
+    if isinstance(v, (tuple, list)) and len(v) >= 2:
+        try:
+            return float(v[0]) / float(v[1])
+        except (ZeroDivisionError, TypeError, ValueError):
+            return 0.0
+    return 0.0
+
+
+def _dms_to_deg(v, ref: str) -> float:
+    """Convert degrees/minutes/seconds list/tuple to decimal degrees."""
+    if not isinstance(v, (list, tuple)) or len(v) == 0:
+        return 0.0
+    deg = _rational_to_float(v[0])
+    min_ = _rational_to_float(v[1]) if len(v) > 1 else 0.0
+    sec_ = _rational_to_float(v[2]) if len(v) > 2 else 0.0
+    val = deg + min_ / 60.0 + sec_ / 3600.0
+    return -val if ref.strip().upper() in ("S", "W") else val
+
+
+def read_gps(path: str | Path) -> dict | None:
+    """Read EXIF metadata and extract GPS coordinates and capture time."""
+    try:
+        img = Image.open(path)
+        exif = img.getexif()
+    except Exception:
+        return None
+    gps = exif.get_ifd(0x8825)
+    if not gps:
+        return None
+
+    def ref(tag, default):
+        v = gps.get(tag)
+        if isinstance(v, bytes):
+            return v.decode(errors="ignore").strip() or default
+        return str(v).strip() if v else default
+
+    lat_v, lon_v = gps.get(2), gps.get(4)
+    if not lat_v or not lon_v:
+        return None
+    lat = _dms_to_deg(list(lat_v), ref(1, "N"))
+    lon = _dms_to_deg(list(lon_v), ref(3, "E"))
+
+    taken = None
+    sub = exif.get_ifd(0x8769)
+    for tag in (36867, 36868):  # DateTimeOriginal, DateTimeDigitized
+        if sub.get(tag):
+            taken = str(sub.get(tag))
+            break
+    return {"file": Path(path).name, "time": taken, "lat": lat, "lon": lon}
+
+
+def main() -> int:
+    ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
+    ap.add_argument("inputs", nargs="+", help="image files or folders")
+    ap.add_argument("-o", "--output", help="output JSON path (default <input dir>/trip-moments-output/gps.json)")
+    ap.add_argument("--wgs84", action="store_true", help="keep raw WGS-84, skip GCJ-02 conversion")
+    args = ap.parse_args()
+
+    files: list[Path] = []
+    for item in args.inputs:
+        p = Path(item)
+        if not p.exists():
+            print(f"[warn] 未找到路径, 已跳过: {p}")
+            continue
+        files.extend(list_images(p))
+    if not files:
+        print("[error] 未找到任何图片文件")
+        return 1
+
+    points = []
+    for f in files:
+        rec = read_gps(f)
+        if rec:
+            if not args.wgs84:
+                rec["lon_gcj"], rec["lat_gcj"] = wgs84_to_gcj02(rec["lon"], rec["lat"])
+            points.append(rec)
+
+    points.sort(key=lambda r: (r.get("time") or "", r["file"]))
+    if points:
+        out = Path(args.output) if args.output else files[0].parent / "trip-moments-output" / "gps.json"
+        out.parent.mkdir(parents=True, exist_ok=True)
+        out.write_text(json.dumps(points, ensure_ascii=False, indent=2), encoding="utf-8")
+        print(f"[ok] {len(points)}/{len(files)} 张照片提取到 EXIF GPS 信息 -> {out}")
+        for p in points:
+            lon = p.get("lon_gcj", p["lon"])
+            lat = p.get("lat_gcj", p["lat"])
+            print(f"  {p['file']}  {p.get('time') or '时间未知'}  {lat:.5f},{lon:.5f}")
+    else:
+        print("[warn] 照片不含 EXIF GPS 数据，后续路线图可直接通过文本站点列表生成")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())