first commit

.gitattributes

@@ -0,0 +1,35 @@
+*.7z filter=lfs diff=lfs merge=lfs -text
+*.arrow filter=lfs diff=lfs merge=lfs -text
+*.bin filter=lfs diff=lfs merge=lfs -text
+*.bz2 filter=lfs diff=lfs merge=lfs -text
+*.ckpt filter=lfs diff=lfs merge=lfs -text
+*.ftz filter=lfs diff=lfs merge=lfs -text
+*.gz filter=lfs diff=lfs merge=lfs -text
+*.h5 filter=lfs diff=lfs merge=lfs -text
+*.joblib filter=lfs diff=lfs merge=lfs -text
+*.lfs.* filter=lfs diff=lfs merge=lfs -text
+*.mlmodel filter=lfs diff=lfs merge=lfs -text
+*.model filter=lfs diff=lfs merge=lfs -text
+*.msgpack filter=lfs diff=lfs merge=lfs -text
+*.npy filter=lfs diff=lfs merge=lfs -text
+*.npz filter=lfs diff=lfs merge=lfs -text
+*.onnx filter=lfs diff=lfs merge=lfs -text
+*.ot filter=lfs diff=lfs merge=lfs -text
+*.parquet filter=lfs diff=lfs merge=lfs -text
+*.pb filter=lfs diff=lfs merge=lfs -text
+*.pickle filter=lfs diff=lfs merge=lfs -text
+*.pkl filter=lfs diff=lfs merge=lfs -text
+*.pt filter=lfs diff=lfs merge=lfs -text
+*.pth filter=lfs diff=lfs merge=lfs -text
+*.rar filter=lfs diff=lfs merge=lfs -text
+*.safetensors filter=lfs diff=lfs merge=lfs -text
+saved_model/**/* filter=lfs diff=lfs merge=lfs -text
+*.tar.* filter=lfs diff=lfs merge=lfs -text
+*.tar filter=lfs diff=lfs merge=lfs -text
+*.tflite filter=lfs diff=lfs merge=lfs -text
+*.tgz filter=lfs diff=lfs merge=lfs -text
+*.wasm filter=lfs diff=lfs merge=lfs -text
+*.xz filter=lfs diff=lfs merge=lfs -text
+*.zip filter=lfs diff=lfs merge=lfs -text
+*.zst filter=lfs diff=lfs merge=lfs -text
+*tfevents* filter=lfs diff=lfs merge=lfs -text

.gitignore

@@ -0,0 +1,11 @@
+
+.idea/
+
+__pycache__/
+
+data/
+logs/
+temp/
+trainede_models/
+
+

Dockerfile

@@ -0,0 +1,23 @@
+FROM python:3.12
+
+WORKDIR /code
+
+COPY . /code
+
+RUN apt-get update
+RUN apt-get install -y ffmpeg build-essential
+RUN apt-get install -y libnss3
+
+RUN pip install --upgrade pip
+RUN pip install --no-cache-dir --upgrade -r /code/requirements.txt
+
+RUN useradd -m -u 1000 user
+USER user
+ENV HOME=/home/user \
+    PATH=/home/user/.local/bin:$PATH
+
+WORKDIR $HOME/app
+
+COPY --chown=user . $HOME/app
+
+CMD ["python3", "main.py"]

README.md

@@ -0,0 +1,12 @@
+---
+title: KeyPoints
+emoji: 📈
+colorFrom: yellow
+colorTo: indigo
+sdk: docker
+pinned: false
+license: apache-2.0
+short_description: KeyPoints
+---
+
+Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference

examples/__init__.py

@@ -0,0 +1,3 @@
+#!/usr/bin/python3
+# -*- coding: utf-8 -*-
+

examples/keypoint_match/__init__.py

@@ -0,0 +1,3 @@
+#!/usr/bin/python3
+# -*- coding: utf-8 -*-
+

examples/keypoint_match/sift_multi_image_match.py

@@ -0,0 +1,118 @@
+#!/usr/bin/python3
+# -*- coding: utf-8 -*-
+
+"""
+示例：使用 SIFT 提取关键点 + 多模板匹配（不做仿射/单应性）。
+
+运行：
+python -m examples.keypoint_match.sift_multi_image_match
+
+或指定多个模板：
+python -m examples.keypoint_match.sift_multi_image_match --template_paths a.png b.png --search_path big.png
+"""
+
+from __future__ import annotations
+
+import argparse
+from pathlib import Path
+from typing import List, Tuple
+
+import cv2
+import numpy as np
+
+from project_settings import project_path
+from toolbox.keypoint_match import (
+    MultiImageDetector,
+    MultiImageDetectorConfig,
+    SiftExtractConfig,
+    SiftKeyPointExtract,
+)
+
+
+def _crop_template(image_bgr: np.ndarray, xyxy: Tuple[int, int, int, int]) -> np.ndarray:
+    x1, y1, x2, y2 = [int(v) for v in xyxy]
+    h, w = image_bgr.shape[:2]
+    x1 = max(0, min(w - 1, x1))
+    x2 = max(0, min(w, x2))
+    y1 = max(0, min(h - 1, y1))
+    y2 = max(0, min(h, y2))
+    if x2 <= x1 or y2 <= y1:
+        raise ValueError(f"无效裁剪框: {xyxy}, image_size={(h, w)}")
+    return image_bgr[y1:y2, x1:x2].copy()
+
+
+def get_args():
+    parser = argparse.ArgumentParser()
+    parser.add_argument(
+        "--search_path",
+        type=str,
+        # default=(project_path / "data/images/keyboard/g98-v2-pink/model/keyboard1.png").as_posix(),
+        # default=(project_path / "data/images/keyboard/g98-v2-pink/keyboard1.jpg").as_posix(),
+        # default=(project_path / "data/images/keyboard/g98-v2-pink/keyboard2.jpg").as_posix(),
+        default=(project_path / "data/images/keyboard/g98-v2-pink/keyboard3.jpg").as_posix(),
+    )
+    parser.add_argument(
+        "--template_paths",
+        type=str,
+        nargs="*",
+        default=[
+            (project_path / "data/images/keyboard/g98-v2-pink/model/local/roller/roller1.png").as_posix(),
+            (project_path / "data/images/keyboard/g98-v2-pink/local/roller/roller1.png").as_posix(),
+            (project_path / "data/images/keyboard/g98-v2-pink/local/roller/roller2.png").as_posix(),
+            (project_path / "data/images/keyboard/g98-v2-pink/local/roller/roller3.png").as_posix(),
+        ],
+        help="提供多个小图模板路径；为空则使用默认模板 + 从大图裁剪一个 patch 当作第二模板",
+    )
+    parser.add_argument("--max_keypoints", type=int, default=2000)
+    parser.add_argument("--ratio", type=float, default=0.95)
+    parser.add_argument("--max_matches", type=int, default=120)
+    return parser.parse_args()
+
+
+def main():
+    args = get_args()
+
+    search = cv2.imread(args.search_path)
+    if search is None:
+        raise FileNotFoundError(f"无法读取搜索图: {args.search_path}")
+
+    templates: List[np.ndarray] = []
+    template_ids: List[str] = []
+
+    for p in args.template_paths:
+        img = cv2.imread(p)
+        if img is None:
+            raise FileNotFoundError(f"无法读取模板图: {p}")
+        templates.append(img)
+        template_ids.append(Path(p).stem)
+
+    extractor = SiftKeyPointExtract(
+        SiftExtractConfig(
+            max_keypoints=int(args.max_keypoints),
+        )
+    )
+
+    detector = MultiImageDetector(
+        extractor=extractor,
+        config=MultiImageDetectorConfig(
+            ratio=float(args.ratio),
+            max_matches=int(args.max_matches),
+            max_keypoints=int(args.max_keypoints),
+        ),
+    )
+
+    result = detector.detect(templates, search, template_ids=template_ids)
+
+    for it in result.items:
+        print(f"template={it.template_id} kp_t={it.template_kp.n} kp_s={it.search_kp.n} matches={it.matches.m}")
+
+    title = "sift_multi_image_match | " + " , ".join([f"{it.template_id}:{it.matches.m}" for it in result.items])
+    cv2.imshow(title, result.vis_search)
+    cv2.waitKey(0)
+    cv2.destroyAllWindows()
+    return
+
+
+if __name__ == "__main__":
+    main()
+

examples/keypoint_match/superpoint_multi_image_match.py

@@ -0,0 +1,118 @@
+#!/usr/bin/python3
+# -*- coding: utf-8 -*-
+
+"""
+示例：使用 SuperPoint 提取关键点 + 多模板匹配（不做仿射/单应性）。
+
+运行：
+python -m examples.keypoint_match.superpoint_multi_image_match
+
+或指定多个模板：
+python -m examples.keypoint_match.superpoint_multi_image_match --template_paths a.png b.png --search_path big.png
+"""
+
+from __future__ import annotations
+
+import argparse
+from pathlib import Path
+from typing import List, Tuple
+
+import cv2
+import numpy as np
+
+from project_settings import project_path
+from toolbox.keypoint_match import (
+    MultiImageDetector,
+    MultiImageDetectorConfig,
+    SuperPointExtractConfig,
+    SuperPointKeyPointExtract,
+)
+
+
+def _crop_template(image_bgr: np.ndarray, xyxy: Tuple[int, int, int, int]) -> np.ndarray:
+    x1, y1, x2, y2 = [int(v) for v in xyxy]
+    h, w = image_bgr.shape[:2]
+    x1 = max(0, min(w - 1, x1))
+    x2 = max(0, min(w, x2))
+    y1 = max(0, min(h - 1, y1))
+    y2 = max(0, min(h, y2))
+    if x2 <= x1 or y2 <= y1:
+        raise ValueError(f"无效裁剪框: {xyxy}, image_size={(h, w)}")
+    return image_bgr[y1:y2, x1:x2].copy()
+
+
+def get_args():
+    parser = argparse.ArgumentParser()
+    parser.add_argument(
+        "--search_path",
+        type=str,
+        default=(project_path / "data/images/keyboard/g98-v2-pink/model/keyboard1.png").as_posix(),
+    )
+    parser.add_argument(
+        "--template_paths",
+        type=str,
+        nargs="*",
+        default=[
+            (project_path / "data/images/keyboard/g98-v2-pink/model/local/roller/roller1.png").as_posix(),
+            (project_path / "data/images/keyboard/g98-v2-pink/local/roller/roller1.png").as_posix(),
+            (project_path / "data/images/keyboard/g98-v2-pink/local/roller/roller2.png").as_posix(),
+            (project_path / "data/images/keyboard/g98-v2-pink/local/roller/roller3.png").as_posix(),
+        ],
+        help="提供多个小图模板路径；为空则使用默认模板 + 从大图裁剪一个 patch 当作第二模板",
+    )
+    parser.add_argument("--device", type=str, default="cpu")
+    parser.add_argument("--max_keypoints", type=int, default=2000)
+    parser.add_argument("--ratio", type=float, default=0.99)
+    parser.add_argument("--max_matches", type=int, default=120)
+    return parser.parse_args()
+
+
+def main():
+    args = get_args()
+
+    search = cv2.imread(args.search_path)
+    if search is None:
+        raise FileNotFoundError(f"无法读取搜索图: {args.search_path}")
+
+    templates: List[np.ndarray] = []
+    template_ids: List[str] = []
+
+    for p in args.template_paths:
+        img = cv2.imread(p)
+        if img is None:
+            raise FileNotFoundError(f"无法读取模板图: {p}")
+        templates.append(img)
+        template_ids.append(Path(p).stem)
+
+    extractor = SuperPointKeyPointExtract(
+        SuperPointExtractConfig(
+            device=str(args.device),
+            max_keypoints=int(args.max_keypoints),
+        )
+    )
+
+    detector = MultiImageDetector(
+        extractor=extractor,
+        config=MultiImageDetectorConfig(
+            ratio=float(args.ratio),
+            max_matches=int(args.max_matches),
+            max_keypoints=int(args.max_keypoints),
+        ),
+    )
+
+    result = detector.detect(templates, search, template_ids=template_ids)
+
+    # 打印每个模板的匹配数量（越多通常说明越像）
+    for it in result.items:
+        print(f"template={it.template_id} kp_t={it.template_kp.n} kp_s={it.search_kp.n} matches={it.matches.m}")
+
+    title = "superpoint_multi_image_match | " + " , ".join([f"{it.template_id}:{it.matches.m}" for it in result.items])
+    cv2.imshow(title, result.vis_search)
+    cv2.waitKey(0)
+    cv2.destroyAllWindows()
+    return
+
+
+if __name__ == "__main__":
+    main()
+

examples/keypoint_match/video_track_and_collect_templates.py

@@ -0,0 +1,278 @@
+#!/usr/bin/python3
+# -*- coding: utf-8 -*-
+
+"""
+通过视频录制目标多角度，用跟踪器持续估计目标在画面中的位置与大致范围（边界框），
+便于按帧裁剪保存为后续关键点匹配的模板小图。
+
+用法：
+  # 摄像头（Windows 上设备号多为 0）
+  python -m examples.keypoint_match.video_track_and_collect_templates --source 0
+
+  # 视频文件
+  python -m examples.keypoint_match.video_track_and_collect_templates --source path/to/video.mp4
+
+操作：
+  - 第一帧（或按 r 重选）：按住鼠标左键拖拽画矩形框选目标，松开鼠标后自动开始跟踪
+  - s：将当前帧中跟踪框区域（可带边距）裁剪保存到 --output_dir
+  - r：进入重选模式，在当前帧重新拖拽框选（跟踪漂移或丢目标时使用）
+  - 空格：暂停/继续
+  - q 或 ESC：退出
+
+跟踪器：
+  默认 mil（OpenCV 自带）。若本机有 Nano 权重可试 nano（需自行准备模型路径，见 --help）。
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+import time
+from pathlib import Path
+from typing import Optional, Tuple
+
+import cv2
+import numpy as np
+
+from project_settings import temp_directory
+
+
+Rect = Tuple[int, int, int, int]  # x, y, w, h
+
+
+def create_tracker(kind: str, nano_model: Optional[str] = None, nano_backend: Optional[str] = None):
+    """创建 OpenCV Tracker，按环境能力回退。"""
+    kind = (kind or "mil").lower().strip()
+
+    if kind == "nano":
+        if not hasattr(cv2, "TrackerNano_create"):
+            raise RuntimeError("当前 OpenCV 未提供 TrackerNano_create，请改用 --tracker mil")
+        params = cv2.TrackerNano_Params()
+        if nano_model:
+            params.backbone = nano_model
+        if nano_backend:
+            params.NNBackend = nano_backend
+        return cv2.TrackerNano_create(params)
+
+    if kind == "goturn":
+        if not hasattr(cv2, "TrackerGOTURN_create"):
+            raise RuntimeError("当前 OpenCV 未提供 TrackerGOTURN_create")
+        return cv2.TrackerGOTURN_create()
+
+    if kind == "dasiamrpn":
+        if not hasattr(cv2, "TrackerDaSiamRPN_create"):
+            raise RuntimeError("当前 OpenCV 未提供 TrackerDaSiamRPN_create")
+        return cv2.TrackerDaSiamRPN_create()
+
+    if kind == "mil":
+        return cv2.TrackerMIL_create()
+
+    raise ValueError(f"未知 tracker 类型: {kind}，可选: mil, nano, goturn, dasiamrpn")
+
+
+def clamp_rect(x: int, y: int, w: int, h: int, frame_w: int, frame_h: int) -> Rect:
+    x = max(0, min(x, frame_w - 1))
+    y = max(0, min(y, frame_h - 1))
+    w = max(1, min(w, frame_w - x))
+    h = max(1, min(h, frame_h - y))
+    return x, y, w, h
+
+
+class ROISelector:
+    """鼠标拖拽选框。"""
+
+    def __init__(self, window_name: str):
+        self.window_name = window_name
+        self.drawing = False
+        self.x0 = self.y0 = self.x1 = self.y1 = 0
+
+    def on_mouse(self, event, mx, my, flags, param):
+        if event == cv2.EVENT_LBUTTONDOWN:
+            self.drawing = True
+            self.x0 = self.x1 = mx
+            self.y0 = self.y1 = my
+        elif event == cv2.EVENT_MOUSEMOVE and self.drawing:
+            self.x1, self.y1 = mx, my
+        elif event == cv2.EVENT_LBUTTONUP:
+            self.drawing = False
+            self.x1, self.y1 = mx, my
+
+    def attach(self):
+        cv2.setMouseCallback(self.window_name, self.on_mouse)
+
+    def current_rect(self, frame_w: int, frame_h: int) -> Optional[Rect]:
+        x1, y1, x2, y2 = self.x0, self.y0, self.x1, self.y1
+        if abs(x2 - x1) < 3 or abs(y2 - y1) < 3:
+            return None
+        xa, xb = sorted((x1, x2))
+        ya, yb = sorted((y1, y2))
+        return clamp_rect(xa, ya, xb - xa, yb - ya, frame_w, frame_h)
+
+    def draw_preview(self, frame: np.ndarray) -> np.ndarray:
+        vis = frame.copy()
+        if self.drawing or abs(self.x1 - self.x0) > 1:
+            xa, xb = sorted((self.x0, self.x1))
+            ya, yb = sorted((self.y0, self.y1))
+            cv2.rectangle(vis, (xa, ya), (xb, yb), (0, 255, 255), 2)
+        return vis
+
+
+def open_capture(source: str) -> cv2.VideoCapture:
+    if source.isdigit():
+        cap = cv2.VideoCapture(int(source))
+    else:
+        cap = cv2.VideoCapture(source)
+    if not cap.isOpened():
+        raise RuntimeError(f"无法打开视频源: {source}")
+    return cap
+
+
+def get_args():
+    p = argparse.ArgumentParser(description="视频目标跟踪 + 裁剪保存模板小图")
+    p.add_argument(
+        "--source",
+        type=str,
+        default="0",
+        help="摄像头设备号（如 0）或视频文件路径",
+    )
+    p.add_argument(
+        "--output_dir",
+        type=str,
+        default=(temp_directory / "template_crops").as_posix(),
+        help="按 s 保存裁剪图到此目录",
+    )
+    p.add_argument(
+        "--tracker",
+        type=str,
+        default="mil",
+        choices=["mil", "nano", "goturn", "dasiamrpn"],
+        help="OpenCV 跟踪器��型（默认可用 mil）",
+    )
+    p.add_argument("--nano_model", type=str, default="", help="TrackerNano backbone 模型路径（可选）")
+    p.add_argument("--nano_backend", type=str, default="", help="TrackerNano NNBackend（可选，依 OpenCV 文档）")
+    p.add_argument(
+        "--crop_pad",
+        type=float,
+        default=0.08,
+        help="保存裁剪时在框四周按比例扩展（相对框宽高），便于包含上下文",
+    )
+    return p.parse_args()
+
+
+def expand_rect(rect: Rect, pad_ratio: float, fw: int, fh: int) -> Rect:
+    x, y, w, h = rect
+    px = int(w * pad_ratio)
+    py = int(h * pad_ratio)
+    return clamp_rect(x - px, y - py, w + 2 * px, h + 2 * py, fw, fh)
+
+
+def main():
+    args = get_args()
+    out_dir = Path(args.output_dir)
+    out_dir.mkdir(parents=True, exist_ok=True)
+
+    cap = open_capture(args.source)
+    win = "track_and_collect | drag ROI then release | s save | r reselect | space pause | q quit"
+    cv2.namedWindow(win, cv2.WINDOW_NORMAL)
+    selector = ROISelector(win)
+    selector.attach()
+
+    tracker = None
+    paused = False
+    need_init = True
+    ok_track = False
+    bbox: Optional[Rect] = None
+    save_idx = 0
+    nano_model = args.nano_model or None
+    nano_backend = args.nano_backend or None
+    prev_drawing = False
+
+    print(__doc__)
+    print(f"输出目录: {out_dir.resolve()}")
+
+    while True:
+        if not paused:
+            ret, frame = cap.read()
+            if not ret or frame is None:
+                print("视频结束或读取失败")
+                break
+            fh, fw = frame.shape[:2]
+        else:
+            fh, fw = frame.shape[:2]
+
+        key = cv2.waitKey(1) & 0xFF
+        if key in (ord("q"), 27):
+            break
+        if key == ord(" "):
+            paused = not paused
+            continue
+        if key == ord("r"):
+            need_init = True
+            tracker = None
+            ok_track = False
+            paused = True
+            print("重选模式：在本帧拖拽框选目标，松开鼠标后开始跟踪；可按空格继续/暂停")
+
+        display = frame.copy()
+
+        if need_init:
+            display = selector.draw_preview(display)
+            preview_rect = selector.current_rect(fw, fh)
+            if preview_rect is not None:
+                cv2.rectangle(
+                    display,
+                    (preview_rect[0], preview_rect[1]),
+                    (preview_rect[0] + preview_rect[2], preview_rect[1] + preview_rect[3]),
+                    (0, 255, 0),
+                    2,
+                )
+            # 松开鼠标：从拖拽 -> 非拖拽 的瞬间，若框有效则自动初始化跟踪器
+            if prev_drawing and not selector.drawing:
+                rect = selector.current_rect(fw, fh)
+                if rect is not None:
+                    tracker = create_tracker(args.tracker, nano_model=nano_model, nano_backend=nano_backend)
+                    tracker.init(frame, rect)
+                    bbox = rect
+                    need_init = False
+                    ok_track = True
+                    paused = False
+                    print(f"已初始化跟踪，bbox= {rect}")
+        else:
+            if tracker is not None and not paused:
+                ok_track, bbox = tracker.update(frame)
+            if bbox is not None:
+                x, y, w, h = [int(v) for v in bbox]
+                x, y, w, h = clamp_rect(x, y, w, h, fw, fh)
+                color = (0, 255, 0) if ok_track else (0, 0, 255)
+                cv2.rectangle(display, (x, y), (x + w, y + h), color, 2)
+                label = "tracking OK" if ok_track else "tracking LOST?"
+                cv2.putText(display, label, (x, max(0, y - 8)), cv2.FONT_HERSHEY_SIMPLEX, 0.5, color, 1, cv2.LINE_AA)
+
+            if key == ord("s") and bbox is not None and ok_track:
+                x, y, w, h = [int(v) for v in bbox]
+                x, y, w, h = clamp_rect(x, y, w, h, fw, fh)
+                ex = expand_rect((x, y, w, h), float(args.crop_pad), fw, fh)
+                crop = frame[ex[1] : ex[1] + ex[3], ex[0] : ex[0] + ex[2]]
+                ts = int(time.time() * 1000)
+                path = out_dir / f"template_{save_idx:04d}_{ts}.png"
+                cv2.imwrite(str(path), crop)
+                save_idx += 1
+                print(f"已保存: {path}")
+
+        hint = (
+            "Drag ROI (release=init) | s save | r reselect | space pause | q quit"
+            if need_init
+            else "s save | r reselect | space pause | q quit"
+        )
+        cv2.putText(display, hint, (10, fh - 12), cv2.FONT_HERSHEY_SIMPLEX, 0.45, (200, 200, 200), 1, cv2.LINE_AA)
+        cv2.imshow(win, display)
+
+        prev_drawing = selector.drawing
+
+    cap.release()
+    cv2.destroyAllWindows()
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

examples/keypoints/kornia/test.py

@@ -0,0 +1,69 @@
+"""
+https://github.com/kornia/kornia
+"""
+import cv2
+import torch
+import kornia as K
+import kornia.feature as KF
+import matplotlib.pyplot as plt
+from kornia_moons.viz import draw_LAF_matches
+
+
+def match_keyboards(img_path1, img_path2):
+    # 1. 加载图片并转换为 Tensor (Kornia 处理的是 Tensor)
+    # 键盘细节丰富，建议保持较高分辨率，不要缩放得太厉害
+    img1 = K.image_to_tensor(cv2.imread(img_path1), keepdim=False).float() / 255.0
+    img2 = K.image_to_tensor(cv2.imread(img_path2), keepdim=False).float() / 255.0
+
+    # 转换为灰度图用于特征提取
+    img1_gray = K.color.rgb_to_grayscale(K.color.bgr_to_rgb(img1))
+    img2_gray = K.color.rgb_to_grayscale(K.color.bgr_to_rgb(img2))
+
+    # 2. 定义特征提取器 (KeyNet + AffNet + HardNet)
+    # 这是一套非常强大的组合，对键盘这种重复纹理有很好的识别力
+    num_features = 2000  # 键盘字符多，建议点数设多一点
+    matcher = KF.LocalFeatureMatcher(
+        KF.KeyNetAffNetHardNet(num_features, pretrained=True),
+        KF.DescriptorMatcher('adalam', torch.device('cpu'))  # 'adalam' 是目前非常快的离群点过滤匹配算法
+    )
+
+    # 3. 执行匹配
+    input_dict = {"image0": img1_gray, "image1": img2_gray}
+    with torch.no_grad():
+        correspondences = matcher(input_dict)
+
+    # 提取匹配后的坐标点
+    mkpts0 = correspondences['keypoints0'].cpu().numpy()
+    mkpts1 = correspondences['keypoints1'].cpu().numpy()
+
+    print(f"找到匹配点数量: {len(mkpts0)}")
+
+    # 4. 可视化结果
+    # 我们用 OpenCV 把两张图拼在一起看连线
+    img1_cv = cv2.cvtColor(cv2.imread(img_path1), cv2.COLOR_BGR2RGB)
+    img2_cv = cv2.cvtColor(cv2.imread(img_path2), cv2.COLOR_BGR2RGB)
+
+    # 简单的可视化：画出前 50 个最强的匹配
+    fig, ax = plt.subplots(figsize=(15, 8))
+    draw_LAF_matches(
+        KF.laf_from_center_scale_ori(correspondences['keypoints0'].view(1, -1, 2)),
+        KF.laf_from_center_scale_ori(correspondences['keypoints1'].view(1, -1, 2)),
+        torch.arange(len(mkpts0)).view(1, -1, 1),
+        img1_cv,
+        img2_cv,
+        draw_dict={'inliers_fallback': True}
+    )
+    plt.show()
+
+    # 5. 判断逻辑
+    # 如果匹配点数量很多（比如 > 100）且连线平行度高，则极有可能是同一个键盘
+    if len(mkpts0) > 50:
+        print("结论：两张图片匹配度极高，很可能是同一个键盘或极其相似。")
+    else:
+        print("结论：匹配点过少，可能是不同键盘或拍摄角度偏差过大。")
+
+# 使用示例
+match_keyboards(
+    'keyboard_left.jpg',
+    'keyboard_right.jpg'
+)

examples/keypoints/superpoint/test.py

@@ -0,0 +1,111 @@
+"""
+https://github.com/rpautrat/SuperPointPretrainedNetwork
+
+"""
+import argparse
+import os
+
+os.environ["HF_ENDPOINT"] = "https://hf-mirror.com"
+
+import torch
+import cv2
+import numpy as np
+import requests
+from PIL import Image
+from transformers import AutoImageProcessor
+from transformers.models.superpoint.modeling_superpoint import SuperPointForKeypointDetection, SuperPointKeypointDescriptionOutput
+from project_settings import project_path, temp_directory
+
+
+def get_args():
+    parser = argparse.ArgumentParser()
+    parser.add_argument(
+        "--model_name",
+        default="magic-leap-community/superpoint",
+        type=str
+    )
+    parser.add_argument(
+        "--model_cache_dir",
+        default=(project_path / "../../hf_hub_models").as_posix(),
+        type=str
+    )
+    parser.add_argument(
+        "--image_path",
+        default=(project_path / "data/images/keyboard/g98-v2-pink/model/keyboard1.png").as_posix(),
+        type=str
+    )
+    args = parser.parse_args()
+    return args
+
+
+def show_image(image):
+    cv2.imshow("image", image)
+    cv2.waitKey(0)
+    cv2.destroyAllWindows()
+
+
+def main():
+    args = get_args()
+
+    processor = AutoImageProcessor.from_pretrained(
+        pretrained_model_name_or_path=args.model_name,
+        cache_dir=args.model_cache_dir,
+    )
+    model = SuperPointForKeypointDetection.from_pretrained(
+        pretrained_model_name_or_path=args.model_name,
+        cache_dir=args.model_cache_dir,
+    )
+
+    image = Image.open(args.image_path).convert("RGB")
+
+    inputs = processor(image, return_tensors="pt")
+    output: SuperPointKeypointDescriptionOutput = model(**inputs)
+
+    # 使用 processor 的后处理，将相对坐标转换为像素坐标
+    image_size = (image.height, image.width)
+    processed = processor.post_process_keypoint_detection(
+        output,
+        [image_size],
+    )
+    # processed 是长度为 batch_size 的 list，这里只有一张图
+    keypoints = processed[0]["keypoints"]  # [N, 2]，(x, y) 为像素坐标
+    scores = processed[0]["scores"]        # [N]
+    descriptors = processed[0]["descriptors"]  # [N, D]
+    scores = scores.detach().cpu().numpy()
+
+    print(f"检测到关键点数量: {keypoints.shape[0]}")
+    print(f"描述符维度: {descriptors.shape}")
+
+    # 5. 使用 OpenCV 的 drawKeypoints 在图像中画出关键点并展示
+    # PIL 图像 -> numpy -> BGR
+    image_np = np.array(image)  # RGB
+    image_bgr = cv2.cvtColor(image_np, cv2.COLOR_RGB2BGR)
+
+    # 将 SuperPoint 的关键点转换为 OpenCV 的 KeyPoint 列表
+    cv2_keypoints = []
+    for (x, y), score in zip(keypoints, scores):
+        # x, y 是像素坐标；score 作为响应值
+        # OpenCV 只有在 angle != -1 时，DRAW_RICH_KEYPOINTS 才会画出“半径线”
+        kp = cv2.KeyPoint(
+            x=float(x),
+            y=float(y),
+            size=7,
+            response=float(score),
+        )
+        cv2_keypoints.append(kp)
+
+    # 使用 drawKeypoints 画关键点
+    image_with_kp = cv2.drawKeypoints(
+        image_bgr,
+        cv2_keypoints,
+        None,
+        color=(0, 0, 255),
+        flags=cv2.DRAW_MATCHES_FLAGS_DRAW_RICH_KEYPOINTS,
+    )
+
+    show_image(image_with_kp)
+    return
+
+
+if __name__ == "__main__":
+    main()

project_settings.py

@@ -0,0 +1,27 @@
+#!/usr/bin/python3
+# -*- coding: utf-8 -*-
+import os
+from pathlib import Path
+
+from toolbox.os.environment import EnvironmentManager
+
+
+project_path = os.path.abspath(os.path.dirname(__file__))
+project_path = Path(project_path)
+
+time_zone_info = "Asia/Shanghai"
+
+log_directory = project_path / "logs"
+log_directory.mkdir(parents=True, exist_ok=True)
+
+temp_directory = project_path / "temp"
+temp_directory.mkdir(parents=True, exist_ok=True)
+
+environment = EnvironmentManager(
+    path=os.path.join(project_path, "dotenv"),
+    env=os.environ.get("environment", "dev"),
+)
+
+
+if __name__ == "__main__":
+    pass

requirements.txt

@@ -0,0 +1,7 @@
+python-dotenv
+transformers
+torch
+torchvision
+opencv-python
+Pillow
+requests

toolbox/json/__init__.py

@@ -0,0 +1,6 @@
+#!/usr/bin/python3
+# -*- coding: utf-8 -*-
+
+
+if __name__ == '__main__':
+    pass

toolbox/json/misc.py

@@ -0,0 +1,63 @@
+#!/usr/bin/python3
+# -*- coding: utf-8 -*-
+from typing import Callable
+
+
+def traverse(js, callback: Callable, *args, **kwargs):
+    if isinstance(js, list):
+        result = list()
+        for l in js:
+            l = traverse(l, callback, *args, **kwargs)
+            result.append(l)
+        return result
+    elif isinstance(js, tuple):
+        result = list()
+        for l in js:
+            l = traverse(l, callback, *args, **kwargs)
+            result.append(l)
+        return tuple(result)
+    elif isinstance(js, dict):
+        result = dict()
+        for k, v in js.items():
+            k = traverse(k, callback, *args, **kwargs)
+            v = traverse(v, callback, *args, **kwargs)
+            result[k] = v
+        return result
+    elif isinstance(js, int):
+        return callback(js, *args, **kwargs)
+    elif isinstance(js, str):
+        return callback(js, *args, **kwargs)
+    else:
+        return js
+
+
+def demo1():
+    d = {
+        "env": "ppe",
+        "mysql_connect": {
+            "host": "$mysql_connect_host",
+            "port": 3306,
+            "user": "callbot",
+            "password": "NxcloudAI2021!",
+            "database": "callbot_ppe",
+            "charset": "utf8"
+        },
+        "es_connect": {
+            "hosts": ["10.20.251.8"],
+            "http_auth": ["elastic", "ElasticAI2021!"],
+            "port": 9200
+        }
+    }
+
+    def callback(s):
+        if isinstance(s, str) and s.startswith('$'):
+            return s[1:]
+        return s
+
+    result = traverse(d, callback=callback)
+    print(result)
+    return
+
+
+if __name__ == '__main__':
+    demo1()

toolbox/keypoint_match/__init__.py

@@ -0,0 +1,64 @@
+#!/usr/bin/python3
+# -*- coding: utf-8 -*-
+
+from toolbox.keypoint_match.types import (
+    Detection,
+    DetectionResult,
+    ImageArray,
+    KeyPointSet,
+    MatchSet,
+)
+from toolbox.keypoint_match.base import (
+    KeyPointExtract,
+    KeyPointExtractConfig,
+    KeyPointMatch,
+    KeyPointMatchConfig,
+    KeyPointTemplateDetector,
+    RegionScorer,
+    RegionScorerConfig,
+)
+from toolbox.keypoint_match.detector import SimpleKeyPointTemplateDetector
+from toolbox.keypoint_match.keypoint_extracter.sift import SiftExtractConfig, SiftKeyPointExtract
+from toolbox.keypoint_match.keypoint_extracter.superpoint import SuperPointExtractConfig, SuperPointKeyPointExtract
+from toolbox.keypoint_match.keypoint_match.single_image_match import SingleImageMatcher, SingleImageMatcherConfig
+from toolbox.keypoint_match.keypoint_detector.single_image_detector import (
+    SingleImageDetector,
+    SingleImageDetectorConfig,
+    SingleImageDetectorResult,
+)
+from toolbox.keypoint_match.keypoint_detector.multi_image_detector import (
+    MultiImageDetector,
+    MultiImageDetectorConfig,
+    MultiImageDetectorItem,
+    MultiImageDetectorResult,
+)
+
+__all__ = [
+    "Detection",
+    "DetectionResult",
+    "ImageArray",
+    "KeyPointSet",
+    "MatchSet",
+    "KeyPointExtract",
+    "KeyPointExtractConfig",
+    "KeyPointMatch",
+    "KeyPointMatchConfig",
+    "KeyPointTemplateDetector",
+    "RegionScorer",
+    "RegionScorerConfig",
+    "SimpleKeyPointTemplateDetector",
+    "SiftExtractConfig",
+    "SiftKeyPointExtract",
+    "SuperPointExtractConfig",
+    "SuperPointKeyPointExtract",
+    "SingleImageMatcher",
+    "SingleImageMatcherConfig",
+    "SingleImageDetector",
+    "SingleImageDetectorConfig",
+    "SingleImageDetectorResult",
+    "MultiImageDetector",
+    "MultiImageDetectorConfig",
+    "MultiImageDetectorItem",
+    "MultiImageDetectorResult",
+]
+

toolbox/keypoint_match/base.py

@@ -0,0 +1,141 @@
+#!/usr/bin/python3
+# -*- coding: utf-8 -*-
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+from typing import Any, Mapping, Optional, Sequence, Tuple
+
+import numpy as np
+
+from toolbox.keypoint_match.types import (
+    DetectionResult,
+    ImageArray,
+    KeyPointSet,
+    MatchSet,
+)
+
+
+@dataclass(frozen=True)
+class KeyPointExtractConfig:
+    """关键点/描述子提取器的通用配置。"""
+
+    max_keypoints: Optional[int] = None
+    # 允许实现方在 meta 中存放更多参数，例如：nms_radius、score_threshold、scale_pyramid 等
+    extra: Optional[Mapping[str, Any]] = None
+
+
+class KeyPointExtract(ABC):
+    """
+    抽象：从一张图片提取关键点与描述子。
+
+    适配来源：
+    - OpenCV: ORB/SIFT/AKAZE 等
+    - Kornia: KeyNetAffNetHardNet、DISK 等
+    - SuperPoint/LightGlue 等深度模型
+    """
+
+    def __init__(self, config: Optional[KeyPointExtractConfig] = None):
+        self.config = config or KeyPointExtractConfig()
+
+    @abstractmethod
+    def extract(self, image: ImageArray) -> KeyPointSet:
+        """输入一张图，输出关键点集合（包含可选描述子）。"""
+
+    def batch_extract(self, images: Sequence[ImageArray]) -> Sequence[KeyPointSet]:
+        return [self.extract(im) for im in images]
+
+
+@dataclass(frozen=True)
+class KeyPointMatchConfig:
+    """匹配器的通用配置。"""
+
+    # 常见：ratio test 的阈值（若实现方使用 KNN）
+    ratio: Optional[float] = None
+    # 允许实现方控制返回的匹配数量上限
+    max_matches: Optional[int] = None
+    extra: Optional[Mapping[str, Any]] = None
+
+
+class KeyPointMatch(ABC):
+    """
+    抽象：对两张图（或两组描述子）进行匹配，输出匹配对。
+    """
+
+    def __init__(self, config: Optional[KeyPointMatchConfig] = None):
+        self.config = config or KeyPointMatchConfig()
+
+    @abstractmethod
+    def match(self, query: KeyPointSet, train: KeyPointSet) -> MatchSet:
+        """
+        query: 通常来自“小图/模板”
+        train: 通常来自“大图/搜索图”
+        """
+
+
+@dataclass(frozen=True)
+class RegionScorerConfig:
+    """
+    匹配点聚集成“区域”的通用配置。
+
+    说明：你的核心算法描述是“某个区域匹配点特别多 => 目标被找到”，
+    因此我们把“如何聚类/评分/生成 bbox”抽象成 RegionScorer。
+    """
+
+    # 大图上聚类半径（像素）。例如：DBSCAN eps 或网格统计的 cell_size
+    radius_px: float = 24.0
+    # 认为“找到”的最低匹配点数阈值
+    min_match_count: int = 12
+    # 最多输出多少个候选区域
+    topk: int = 10
+    extra: Optional[Mapping[str, Any]] = None
+
+
+class RegionScorer(ABC):
+    """
+    抽象：把匹配关系映射成候选区域（bbox + score）。
+
+    输入包含关键点坐标与匹配对，因此实现可以：
+    - 做简单的网格投票 / 密度聚类
+    - 用单应性 / RANSAC 过滤外点后再成簇
+    - 用匹配点的局部一致性做评分
+    """
+
+    def __init__(self, config: Optional[RegionScorerConfig] = None):
+        self.config = config or RegionScorerConfig()
+
+    @abstractmethod
+    def score(
+        self,
+        query: KeyPointSet,
+        train: KeyPointSet,
+        matches: MatchSet,
+        *,
+        template_id: Optional[str] = None,
+        template_size: Optional[Tuple[int, int]] = None,  # (h, w)
+    ) -> DetectionResult:
+        """
+        template_size: 小图大小，便于从匹配点推断 bbox 尺寸（可选）
+        """
+
+
+class KeyPointTemplateDetector(ABC):
+    """
+    抽象：把 (提取器 + 匹配器 + 区域评分器) 组合成“模板检测”。
+
+    你可以实现一个具体 Detector，将其用于：
+    - 多模板检索（小图集合在大图中找出现位置）
+    - 单模板定位（某个小图在大图的哪里）
+    """
+
+    @abstractmethod
+    def detect(
+        self,
+        template_image: ImageArray,
+        search_image: ImageArray,
+        *,
+        template_id: Optional[str] = None,
+    ) -> DetectionResult:
+        ...
+

toolbox/keypoint_match/detector.py

@@ -0,0 +1,52 @@
+#!/usr/bin/python3
+# -*- coding: utf-8 -*-
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Optional, Tuple
+
+from toolbox.keypoint_match.base import KeyPointExtract, KeyPointMatch, KeyPointTemplateDetector, RegionScorer
+from toolbox.keypoint_match.types import DetectionResult, ImageArray, KeyPointSet, MatchSet
+
+
+@dataclass
+class SimpleKeyPointTemplateDetector(KeyPointTemplateDetector):
+    """
+    一个“组合式”的默认 Detector 实现。
+
+    说明：
+    - 这是一个可直接工作的拼装类：extract(template) + extract(search) + match + score
+    - 具体的“找区域”逻辑由 RegionScorer 决定（因此仍保持算法可替换/可扩展）
+    """
+
+    extractor: KeyPointExtract
+    matcher: KeyPointMatch
+    region_scorer: RegionScorer
+
+    def detect(
+        self,
+        template_image: ImageArray,
+        search_image: ImageArray,
+        *,
+        template_id: Optional[str] = None,
+    ) -> DetectionResult:
+        template_kp: KeyPointSet = self.extractor.extract(template_image)
+        search_kp: KeyPointSet = self.extractor.extract(search_image)
+        matches: MatchSet = self.matcher.match(template_kp, search_kp)
+
+        template_size: Optional[Tuple[int, int]] = None
+        try:
+            h, w = int(template_image.shape[0]), int(template_image.shape[1])
+            template_size = (h, w)
+        except Exception:
+            template_size = None
+
+        return self.region_scorer.score(
+            template_kp,
+            search_kp,
+            matches,
+            template_id=template_id,
+            template_size=template_size,
+        )
+

toolbox/keypoint_match/keypoint_detector/__init__.py

@@ -0,0 +1,25 @@
+#!/usr/bin/python3
+# -*- coding: utf-8 -*-
+
+from toolbox.keypoint_match.keypoint_detector.single_image_detector import (
+    SingleImageDetector,
+    SingleImageDetectorConfig,
+    SingleImageDetectorResult,
+)
+from toolbox.keypoint_match.keypoint_detector.multi_image_detector import (
+    MultiImageDetector,
+    MultiImageDetectorConfig,
+    MultiImageDetectorItem,
+    MultiImageDetectorResult,
+)
+
+__all__ = [
+    "SingleImageDetector",
+    "SingleImageDetectorConfig",
+    "SingleImageDetectorResult",
+    "MultiImageDetector",
+    "MultiImageDetectorConfig",
+    "MultiImageDetectorItem",
+    "MultiImageDetectorResult",
+]
+

toolbox/keypoint_match/keypoint_detector/multi_image_detector.py

@@ -0,0 +1,239 @@
+#!/usr/bin/python3
+# -*- coding: utf-8 -*-
+
+from __future__ import annotations
+
+import argparse
+from pathlib import Path
+from dataclasses import dataclass
+from typing import Any, Dict, List, Optional, Sequence, Tuple
+
+import cv2
+import numpy as np
+
+from project_settings import project_path
+from toolbox.keypoint_match.base import KeyPointExtract
+from toolbox.keypoint_match.keypoint_match.single_image_match import (
+    SingleImageMatcher,
+    SingleImageMatcherConfig,
+)
+from toolbox.keypoint_match.types import ImageArray, KeyPointSet, MatchSet
+
+
+@dataclass(frozen=True)
+class MultiImageDetectorConfig:
+    """
+    多模板（多个小图）在同一张大图中的关键点匹配检测配置。
+
+    - 不做仿射/单应性估计
+    - 只画出“大图中匹配得很好的关键点”
+    """
+
+    ratio: float = 0.75
+    max_matches: int = 120
+    max_keypoints: int = 2000
+    point_radius: int = 4
+    point_thickness: int = 2
+    # 每个模板对应一个颜色（BGR），不足时循环使用
+    colors_bgr: Sequence[Tuple[int, int, int]] = (
+        (0, 0, 255),    # red
+        (0, 255, 0),    # green
+        (255, 0, 0),    # blue
+        (0, 255, 255),  # yellow
+        (255, 0, 255),  # magenta
+        (255, 255, 0),  # cyan
+    )
+    extra: Optional[Dict[str, Any]] = None
+
+
+@dataclass(frozen=True)
+class MultiImageDetectorItem:
+    template_id: str
+    template_kp: KeyPointSet
+    search_kp: KeyPointSet
+    matches: MatchSet
+    color_bgr: Tuple[int, int, int]
+    meta: Optional[Dict[str, Any]] = None
+
+
+@dataclass(frozen=True)
+class MultiImageDetectorResult:
+    items: Sequence[MultiImageDetectorItem]
+    vis_search: np.ndarray
+    meta: Optional[Dict[str, Any]] = None
+
+
+class MultiImageDetector:
+    """
+    Multi image detector：给定多个模板小图，在同一张大图中找“匹配得很好的关键点”，并可视化。
+    """
+
+    def __init__(self, extractor: KeyPointExtract, config: Optional[MultiImageDetectorConfig] = None):
+        self.extractor = extractor
+        self.config = config or MultiImageDetectorConfig()
+
+    def _color_for_index(self, i: int) -> Tuple[int, int, int]:
+        palette = list(self.config.colors_bgr) if self.config.colors_bgr else [(0, 0, 255)]
+        return tuple(int(c) for c in palette[i % len(palette)])
+
+    def _draw_points_on_search(
+        self,
+        base_image: ImageArray,
+        search_kp: KeyPointSet,
+        matches: MatchSet,
+        color_bgr: Tuple[int, int, int],
+    ) -> np.ndarray:
+        img = np.asarray(base_image).copy()
+        if img.ndim == 2:
+            img = cv2.cvtColor(img, cv2.COLOR_GRAY2BGR)
+
+        if matches.m == 0 or search_kp.n == 0:
+            return img
+
+        idx = matches.train_idx.astype(np.int64)
+        idx = idx[(idx >= 0) & (idx < search_kp.n)]
+        if idx.size == 0:
+            return img
+
+        pts = search_kp.xy[idx]
+        for x, y in pts:
+            cv2.circle(
+                img,
+                center=(int(round(float(x))), int(round(float(y)))),
+                radius=int(self.config.point_radius),
+                color=color_bgr,
+                thickness=int(self.config.point_thickness),
+                lineType=cv2.LINE_AA,
+            )
+        return img
+
+    def detect(
+        self,
+        template_images: Sequence[ImageArray],
+        search_image: ImageArray,
+        *,
+        template_ids: Optional[Sequence[str]] = None,
+    ) -> MultiImageDetectorResult:
+        if template_ids is None:
+            template_ids = [f"template_{i}" for i in range(len(template_images))]
+        if len(template_ids) != len(template_images):
+            raise ValueError("template_ids 的长度必须与 template_images 一致")
+
+        matcher = SingleImageMatcher(
+            extractor=self.extractor,
+            config=SingleImageMatcherConfig(
+                ratio=float(self.config.ratio),
+                max_matches=int(self.config.max_matches),
+            ),
+        )
+
+        # 为了避免重复提取大图特征点：这里直接复用 matcher 的实现会重复提取，
+        # 但为了接口简单先保持这样。后续需要性能时，可扩展 matcher 支持传入已提取的 search_kp。
+        items: List[MultiImageDetectorItem] = []
+        vis = np.asarray(search_image).copy()
+        if vis.ndim == 2:
+            vis = cv2.cvtColor(vis, cv2.COLOR_GRAY2BGR)
+
+        for i, (tid, tmpl) in enumerate(zip(template_ids, template_images)):
+            template_kp, search_kp, matches = matcher.match(tmpl, search_image, template_id=str(tid))
+            color = self._color_for_index(i)
+
+            # 叠加绘制
+            vis = self._draw_points_on_search(vis, search_kp, matches, color_bgr=color)
+
+            items.append(
+                MultiImageDetectorItem(
+                    template_id=str(tid),
+                    template_kp=template_kp,
+                    search_kp=search_kp,
+                    matches=matches,
+                    color_bgr=color,
+                    meta={
+                        "kp_template": int(template_kp.n),
+                        "kp_search": int(search_kp.n),
+                        "match_count": int(matches.m),
+                    },
+                )
+            )
+
+        meta: Dict[str, Any] = {
+            "template_count": int(len(template_images)),
+            "ratio": float(self.config.ratio),
+            "max_matches": int(self.config.max_matches),
+        }
+        if self.config.extra:
+            meta["extra"] = dict(self.config.extra)
+
+        return MultiImageDetectorResult(items=items, vis_search=vis, meta=meta)
+
+
+def get_args():
+    parser = argparse.ArgumentParser()
+    parser.add_argument(
+        "--template_paths",
+        type=str,
+        nargs="+",
+        default=[
+            (project_path / "data/images/keyboard/g98-v2-pink/model/local/roller/roller1.png").as_posix(),
+            (project_path / "data/images/keyboard/g98-v2-pink/local/roller/roller1.png").as_posix(),
+            (project_path / "data/images/keyboard/g98-v2-pink/local/roller/roller2.png").as_posix(),
+            (project_path / "data/images/keyboard/g98-v2-pink/local/roller/roller3.png").as_posix(),
+        ],
+    )
+    parser.add_argument(
+        "--search_path",
+        type=str,
+        # default=(project_path / "data/images/keyboard/g98-v2-pink/model/keyboard1.png").as_posix(),
+        default=(project_path / "data/images/keyboard/g98-v2-pink/keyboard2.jpg").as_posix(),
+        # default=(project_path / "data/images/keyboard/g98-v2-pink/keyboard3.jpg").as_posix(),
+        # default=(project_path / "data/images/keyboard/g98-v2-pink/keyboard4.jpg").as_posix(),
+        # default=(project_path / "data/images/keyboard/g98-v2-pink/keyboard6.jpg").as_posix(),
+    )
+    parser.add_argument("--ratio", type=float, default=0.90)
+    parser.add_argument("--max_matches", type=int, default=120)
+    parser.add_argument("--max_keypoints", type=int, default=2000)
+    return parser.parse_args()
+
+
+def main():
+    from toolbox.keypoint_match.keypoint_extracter import SiftExtractConfig, SiftKeyPointExtract
+
+    args = get_args()
+
+    search = cv2.imread(args.search_path)
+    if search is None:
+        raise FileNotFoundError(f"无法读取搜索图: {args.search_path}")
+
+    templates: List[np.ndarray] = []
+    template_ids: List[str] = []
+    for p in args.template_paths:
+        img = cv2.imread(p)
+        if img is None:
+            raise FileNotFoundError(f"无法读取模板图: {p}")
+        templates.append(img)
+        template_ids.append(Path(p).stem)
+
+    extractor = SiftKeyPointExtract(SiftExtractConfig(max_keypoints=int(args.max_keypoints)))
+    detector = MultiImageDetector(
+        extractor=extractor,
+        config=MultiImageDetectorConfig(
+            ratio=float(args.ratio),
+            max_matches=int(args.max_matches),
+            max_keypoints=int(args.max_keypoints),
+        ),
+    )
+
+    result = detector.detect(templates, search, template_ids=template_ids)
+
+    # 在窗口标题里打印每个模板的匹配数量
+    stat = ", ".join([f"{it.template_id}:{it.matches.m}" for it in result.items])
+    title = f"multi_image_detector | {stat}"
+    cv2.imshow(title, result.vis_search)
+    cv2.waitKey(0)
+    cv2.destroyAllWindows()
+    return
+
+
+if __name__ == "__main__":
+    main()
+

toolbox/keypoint_match/keypoint_detector/single_image_detector.py

@@ -0,0 +1,206 @@
+#!/usr/bin/python3
+# -*- coding: utf-8 -*-
+
+from __future__ import annotations
+
+import argparse
+from dataclasses import dataclass
+from typing import Any, Dict, Optional, Tuple
+
+import cv2
+import numpy as np
+
+from project_settings import project_path
+from toolbox.keypoint_match.base import KeyPointExtract
+from toolbox.keypoint_match.keypoint_match.single_image_match import (
+    SingleImageMatcher,
+    SingleImageMatcherConfig,
+)
+from toolbox.keypoint_match.types import ImageArray, KeyPointSet, MatchSet
+
+
+@dataclass(frozen=True)
+class SingleImageDetectorConfig:
+    """
+    单目标小图在大图中的“关键点匹配检测”配置。
+
+    注意：这里不做仿射/单应性估计，只保留“匹配得很好的点”，并把这些点在大图上画出来。
+    """
+
+    ratio: float = 0.75
+    max_matches: int = 120
+    max_keypoints: int = 2000
+    # 画点参数
+    point_radius: int = 4
+    point_thickness: int = 2
+    color_bgr: Tuple[int, int, int] = (0, 0, 255)
+    # 是否同时在模板图上也画出参与匹配的点（便于对照）
+    draw_on_template: bool = False
+    extra: Optional[Dict[str, Any]] = None
+
+
+@dataclass(frozen=True)
+class SingleImageDetectorResult:
+    template_kp: KeyPointSet
+    search_kp: KeyPointSet
+    matches: MatchSet
+    vis_search: np.ndarray
+    vis_template: Optional[np.ndarray] = None
+    meta: Optional[Dict[str, Any]] = None
+
+
+class SingleImageDetector:
+    """
+    Single image detector：输入小图与大图，输出“匹配到的大图关键点可视化”。
+
+    - 初始化时传入关键点提取器（SIFT/SuperPoint 等）
+    - 内部复用 `SingleImageMatcher` 做匹配
+    """
+
+    def __init__(self, extractor: KeyPointExtract, config: Optional[SingleImageDetectorConfig] = None):
+        self.extractor = extractor
+        self.config = config or SingleImageDetectorConfig()
+
+    def detect(self, template_image: ImageArray, search_image: ImageArray, *, template_id: Optional[str] = None) -> SingleImageDetectorResult:
+        matcher = SingleImageMatcher(
+            extractor=self.extractor,
+            config=SingleImageMatcherConfig(
+                ratio=float(self.config.ratio),
+                max_matches=int(self.config.max_matches),
+            ),
+        )
+        template_kp, search_kp, matches = matcher.match(template_image, search_image, template_id=template_id)
+
+        vis_search = self.draw_matched_keypoints_on_search(search_image, search_kp, matches)
+        vis_template = None
+        if self.config.draw_on_template:
+            vis_template = self.draw_matched_keypoints_on_template(template_image, template_kp, matches)
+
+        meta = {
+            "template_id": template_id,
+            "kp_template": int(template_kp.n),
+            "kp_search": int(search_kp.n),
+            "match_count": int(matches.m),
+            "ratio": float(self.config.ratio),
+        }
+        if self.config.extra:
+            meta["extra"] = dict(self.config.extra)
+
+        return SingleImageDetectorResult(
+            template_kp=template_kp,
+            search_kp=search_kp,
+            matches=matches,
+            vis_search=vis_search,
+            vis_template=vis_template,
+            meta=meta,
+        )
+
+    def draw_matched_keypoints_on_search(self, search_image: ImageArray, search_kp: KeyPointSet, matches: MatchSet) -> np.ndarray:
+        img = np.asarray(search_image).copy()
+        if img.ndim == 2:
+            img = cv2.cvtColor(img, cv2.COLOR_GRAY2BGR)
+
+        if matches.m == 0 or search_kp.n == 0:
+            return img
+
+        # 在大图上画出被匹配到的 train_idx 对应关键点
+        idx = matches.train_idx.astype(np.int64)
+        idx = idx[(idx >= 0) & (idx < search_kp.n)]
+        if idx.size == 0:
+            return img
+
+        pts = search_kp.xy[idx]
+        for x, y in pts:
+            cv2.circle(
+                img,
+                center=(int(round(float(x))), int(round(float(y)))),
+                radius=int(self.config.point_radius),
+                color=tuple(int(c) for c in self.config.color_bgr),
+                thickness=int(self.config.point_thickness),
+                lineType=cv2.LINE_AA,
+            )
+        return img
+
+    def draw_matched_keypoints_on_template(self, template_image: ImageArray, template_kp: KeyPointSet, matches: MatchSet) -> np.ndarray:
+        img = np.asarray(template_image).copy()
+        if img.ndim == 2:
+            img = cv2.cvtColor(img, cv2.COLOR_GRAY2BGR)
+
+        if matches.m == 0 or template_kp.n == 0:
+            return img
+
+        idx = matches.query_idx.astype(np.int64)
+        idx = idx[(idx >= 0) & (idx < template_kp.n)]
+        if idx.size == 0:
+            return img
+
+        pts = template_kp.xy[idx]
+        for x, y in pts:
+            cv2.circle(
+                img,
+                center=(int(round(float(x))), int(round(float(y)))),
+                radius=max(2, int(self.config.point_radius) - 1),
+                color=(0, 255, 0),
+                thickness=int(self.config.point_thickness),
+                lineType=cv2.LINE_AA,
+            )
+        return img
+
+
+def get_args():
+    parser = argparse.ArgumentParser()
+    parser.add_argument(
+        "--template_path",
+        type=str,
+        default=(project_path / "data/images/keyboard/g98-v2-pink/model/local/roller.png"),
+    )
+    parser.add_argument(
+        "--search_path",
+        type=str,
+        # default=(project_path / "data/images/keyboard/g98-v2-pink/model/keyboard1.png"),
+        default=(project_path / "data/images/keyboard/g98-v2-pink/keyboard1.jpg"),
+    )
+    parser.add_argument("--ratio", type=float, default=0.75)
+    parser.add_argument("--max_matches", type=int, default=120)
+    parser.add_argument("--max_keypoints", type=int, default=2000)
+    parser.add_argument("--draw_on_template", action="store_true")
+    return parser.parse_args()
+
+
+def main():
+    from toolbox.keypoint_match.keypoint_extracter import SiftExtractConfig, SiftKeyPointExtract
+
+    args = get_args()
+
+    template = cv2.imread(args.template_path)
+    search = cv2.imread(args.search_path)
+    if template is None:
+        raise FileNotFoundError(f"无法读取模板图: {args.template_path}")
+    if search is None:
+        raise FileNotFoundError(f"无法读取搜索图: {args.search_path}")
+
+    extractor = SiftKeyPointExtract(SiftExtractConfig(max_keypoints=int(args.max_keypoints)))
+    detector = SingleImageDetector(
+        extractor=extractor,
+        config=SingleImageDetectorConfig(
+            ratio=float(args.ratio),
+            max_matches=int(args.max_matches),
+            max_keypoints=int(args.max_keypoints),
+            draw_on_template=bool(args.draw_on_template),
+        ),
+    )
+
+    result = detector.detect(template, search, template_id="roller")
+
+    title = f"single_image_detector | matches={result.matches.m}"
+    cv2.imshow(title, result.vis_search)
+    if result.vis_template is not None:
+        cv2.imshow("template_matched_keypoints", result.vis_template)
+    cv2.waitKey(0)
+    cv2.destroyAllWindows()
+    return
+
+
+if __name__ == "__main__":
+    main()
+

toolbox/keypoint_match/keypoint_extracter/__init__.py

@@ -0,0 +1,13 @@
+#!/usr/bin/python3
+# -*- coding: utf-8 -*-
+
+from toolbox.keypoint_match.keypoint_extracter.sift import SiftExtractConfig, SiftKeyPointExtract
+from toolbox.keypoint_match.keypoint_extracter.superpoint import SuperPointExtractConfig, SuperPointKeyPointExtract
+
+__all__ = [
+    "SiftExtractConfig",
+    "SiftKeyPointExtract",
+    "SuperPointExtractConfig",
+    "SuperPointKeyPointExtract",
+]
+

toolbox/keypoint_match/keypoint_extracter/sift.py

@@ -0,0 +1,184 @@
+#!/usr/bin/python3
+# -*- coding: utf-8 -*-
+from __future__ import annotations
+
+import argparse
+from dataclasses import dataclass
+from typing import Any, Dict, Optional
+
+import numpy as np
+import cv2
+
+from project_settings import project_path
+from toolbox.keypoint_match.base import KeyPointExtract, KeyPointExtractConfig
+from toolbox.keypoint_match.types import ImageArray, KeyPointSet
+
+
+@dataclass(frozen=True)
+class SiftExtractConfig(KeyPointExtractConfig):
+    """
+    OpenCV SIFT 的常用参数封装。
+
+    说明：OpenCV 的 SIFT_create 参数较多，这里保留最常见的几项；其余可放到 extra。
+    """
+
+    n_features: int = 0
+    n_octave_layers: int = 3
+    contrast_threshold: float = 0.04
+    edge_threshold: float = 10.0
+    sigma: float = 1.6
+
+
+class SiftKeyPointExtract(KeyPointExtract):
+    """基于 OpenCV SIFT 的特征点/描述子提取器。"""
+
+    def __init__(self, config: Optional[SiftExtractConfig] = None):
+        super().__init__(config=config or SiftExtractConfig())
+        self.config: SiftExtractConfig
+        self._sift = self._create_sift()
+
+    def _create_sift(self):
+        try:
+            import cv2  # 延迟导入，避免无 OpenCV 时影响其它模块
+        except Exception as e:  # pragma: no cover
+            raise ImportError("使用 SiftKeyPointExtract 需要先安装 opencv-python 或 opencv-contrib-python") from e
+
+        if not hasattr(cv2, "SIFT_create"):
+            raise RuntimeError(
+                "当前 OpenCV 不包含 SIFT（可能缺少 contrib 模块）。"
+                "请安装/替换为 `opencv-contrib-python`。"
+            )
+
+        cfg = self.config
+        return cv2.SIFT_create(
+            nfeatures=int(cfg.n_features),
+            nOctaveLayers=int(cfg.n_octave_layers),
+            contrastThreshold=float(cfg.contrast_threshold),
+            edgeThreshold=float(cfg.edge_threshold),
+            sigma=float(cfg.sigma),
+        )
+
+    @staticmethod
+    def _to_gray_u8(image: ImageArray) -> np.ndarray:
+        """
+        SIFT 在 OpenCV 中通常使用 8-bit 灰度图。
+        - 输入 uint8: 直接处理（若为彩色则转灰）
+        - 输入 float: 若在 [0,1]，缩放到 [0,255]；否则 clip 到 [0,255]
+        """
+        import cv2
+
+        img = np.asarray(image)
+        if img.ndim == 3 and img.shape[2] >= 3:
+            # OpenCV 读图一般是 BGR；这里不强制颜色空间，仅做灰度化
+            img = cv2.cvtColor(img, cv2.COLOR_BGR2GRAY)
+        elif img.ndim != 2:
+            raise ValueError(f"image 需要是 HxW 或 HxWxC，但得到 {img.shape=}")
+
+        if img.dtype == np.uint8:
+            return img
+
+        img_f = img.astype(np.float32, copy=False)
+        if img_f.size > 0 and img_f.max() <= 1.0:
+            img_f = img_f * 255.0
+        img_u8 = np.clip(img_f, 0.0, 255.0).astype(np.uint8)
+        return img_u8
+
+    def extract(self, image: ImageArray) -> KeyPointSet:
+        import cv2
+
+        gray = self._to_gray_u8(image)
+        keypoints, descriptors = self._sift.detectAndCompute(gray, mask=None)
+
+        if keypoints is None or len(keypoints) == 0:
+            empty_xy = np.zeros((0, 2), dtype=np.float32)
+            return KeyPointSet(xy=empty_xy, descriptors=None, scores=None, meta={"backend": "opencv_sift"})
+
+        xy = np.array([kp.pt for kp in keypoints], dtype=np.float32)  # (x,y)
+        scores = np.array([kp.response for kp in keypoints], dtype=np.float32)
+
+        if descriptors is not None:
+            descriptors = np.asarray(descriptors)
+
+        # 若设置了 max_keypoints，则按 response 排序截断（SIFT 本身也可能受 nfeatures 影响）
+        max_kp = self.config.max_keypoints
+        if max_kp is not None and xy.shape[0] > int(max_kp):
+            idx = np.argsort(-scores)[: int(max_kp)]
+            xy = xy[idx]
+            scores = scores[idx]
+            if descriptors is not None:
+                descriptors = descriptors[idx]
+
+        meta: Dict[str, Any] = {
+            "backend": "opencv_sift",
+            "n_features": int(self.config.n_features),
+            "n_octave_layers": int(self.config.n_octave_layers),
+            "contrast_threshold": float(self.config.contrast_threshold),
+            "edge_threshold": float(self.config.edge_threshold),
+            "sigma": float(self.config.sigma),
+        }
+        if self.config.extra:
+            meta["extra"] = dict(self.config.extra)
+
+        return KeyPointSet(
+            xy=xy,
+            descriptors=descriptors,
+            scores=scores,
+            meta=meta,
+        )
+
+
+
+def get_args():
+    parser = argparse.ArgumentParser()
+    parser.add_argument(
+        "--image_path",
+        default=(project_path / "data/images/keyboard/g98-v2-pink/model/keyboard1.png").as_posix(),
+        # default=(project_path / "data/images/keyboard/g98-v2-pink/model/local/roller.png").as_posix(),
+        type=str
+    )
+    parser.add_argument("--max_keypoints", type=int, default=8000)
+
+    args = parser.parse_args()
+    return args
+
+
+def main():
+    args = get_args()
+
+    image = cv2.imread(args.image_path)
+    if image is None:
+        raise FileNotFoundError(f"无法读取图片: {args.image_path}")
+
+    extractor = SiftKeyPointExtract(
+        SiftExtractConfig(
+            max_keypoints=int(args.max_keypoints),
+        )
+    )
+    kp_set = extractor.extract(image)
+
+    cv2_keypoints = [
+        cv2.KeyPoint(
+            x=float(x),
+            y=float(y),
+            size=7,
+            response=float(score) if kp_set.scores is not None else 0.0,
+        )
+        for (x, y), score in zip(kp_set.xy, kp_set.scores if kp_set.scores is not None else np.zeros((kp_set.n,)))
+    ]
+
+    image_with_kp = cv2.drawKeypoints(
+        image,
+        cv2_keypoints,
+        None,
+        color=(0, 0, 255),
+        flags=cv2.DRAW_MATCHES_FLAGS_DRAW_RICH_KEYPOINTS,
+    )
+
+    cv2.imshow("sift_keypoints", image_with_kp)
+    cv2.waitKey(0)
+    cv2.destroyAllWindows()
+    return
+
+
+if __name__ == "__main__":
+    main()

toolbox/keypoint_match/keypoint_extracter/superpoint.py

@@ -0,0 +1,191 @@
+#!/usr/bin/python3
+# -*- coding: utf-8 -*-
+
+from __future__ import annotations
+
+import argparse
+import os
+from dataclasses import dataclass
+from typing import Any, Dict, Optional
+
+import numpy as np
+
+from project_settings import project_path
+from toolbox.keypoint_match.base import KeyPointExtract, KeyPointExtractConfig
+from toolbox.keypoint_match.types import ImageArray, KeyPointSet
+
+
+@dataclass(frozen=True)
+class SuperPointExtractConfig(KeyPointExtractConfig):
+    model_name: str = "magic-leap-community/superpoint"
+    model_cache_dir: str = (project_path / "../../hf_hub_models").as_posix()
+    device: str = "cpu"  # "cpu" / "cuda"
+    # 设置 HuggingFace 镜像（与示例保持一致）
+    hf_endpoint: Optional[str] = "https://hf-mirror.com"
+
+
+class SuperPointKeyPointExtract(KeyPointExtract):
+    """
+    基于 transformers 的 SuperPoint 特征点/描述子提取器。
+
+    参考：examples/keypoints/superpoint/test.py
+    """
+
+    def __init__(self, config: Optional[SuperPointExtractConfig] = None):
+        super().__init__(config=config or SuperPointExtractConfig())
+        self.config: SuperPointExtractConfig
+
+        if self.config.hf_endpoint:
+            os.environ.setdefault("HF_ENDPOINT", str(self.config.hf_endpoint))
+
+        self._processor = None
+        self._model = None
+
+    def _lazy_init(self):
+        if self._processor is not None and self._model is not None:
+            return
+
+        import torch
+        from transformers import AutoImageProcessor
+        from transformers.models.superpoint.modeling_superpoint import SuperPointForKeypointDetection
+
+        self._processor = AutoImageProcessor.from_pretrained(
+            pretrained_model_name_or_path=self.config.model_name,
+            cache_dir=self.config.model_cache_dir,
+        )
+        self._model = SuperPointForKeypointDetection.from_pretrained(
+            pretrained_model_name_or_path=self.config.model_name,
+            cache_dir=self.config.model_cache_dir,
+        )
+        self._model.eval()
+
+        device = torch.device(self.config.device)
+        self._model.to(device)
+
+    @staticmethod
+    def _to_pil_rgb(image: ImageArray):
+        from PIL import Image
+        import cv2
+
+        img = np.asarray(image)
+        if img.ndim == 2:
+            img = cv2.cvtColor(img, cv2.COLOR_GRAY2RGB)
+        elif img.ndim == 3 and img.shape[2] >= 3:
+            # 默认按 OpenCV 的 BGR 输入处理
+            img = cv2.cvtColor(img[:, :, :3], cv2.COLOR_BGR2RGB)
+        else:
+            raise ValueError(f"image 需要是 HxW 或 HxWxC，但得到 {img.shape=}")
+
+        if img.dtype != np.uint8:
+            img_f = img.astype(np.float32, copy=False)
+            if img_f.size > 0 and img_f.max() <= 1.0:
+                img_f = img_f * 255.0
+            img = np.clip(img_f, 0.0, 255.0).astype(np.uint8)
+
+        return Image.fromarray(img).convert("RGB")
+
+    def extract(self, image: ImageArray) -> KeyPointSet:
+        import torch
+
+        self._lazy_init()
+        assert self._processor is not None
+        assert self._model is not None
+
+        pil = self._to_pil_rgb(image)
+        inputs = self._processor(pil, return_tensors="pt")
+
+        device = next(self._model.parameters()).device
+        inputs = {k: v.to(device) for k, v in inputs.items()}
+
+        with torch.no_grad():
+            output = self._model(**inputs)
+
+        image_size = (pil.height, pil.width)
+        processed = self._processor.post_process_keypoint_detection(
+            output,
+            [image_size],
+        )
+
+        keypoints = processed[0]["keypoints"]  # [N,2] (x,y)
+        scores = processed[0]["scores"]        # [N]
+        descriptors = processed[0]["descriptors"]  # [N,D]
+
+        keypoints_np = keypoints.detach().cpu().numpy().astype(np.float32)
+        scores_np = scores.detach().cpu().numpy().astype(np.float32)
+        desc_np = descriptors.detach().cpu().numpy().astype(np.float32)
+
+        # 统一按 scores 截断到 max_keypoints
+        max_kp = self.config.max_keypoints
+        if max_kp is not None and keypoints_np.shape[0] > int(max_kp):
+            idx = np.argsort(-scores_np)[: int(max_kp)]
+            keypoints_np = keypoints_np[idx]
+            scores_np = scores_np[idx]
+            desc_np = desc_np[idx]
+
+        meta: Dict[str, Any] = {
+            "backend": "transformers_superpoint",
+            "model_name": str(self.config.model_name),
+            "device": str(self.config.device),
+        }
+        if self.config.extra:
+            meta["extra"] = dict(self.config.extra)
+
+        return KeyPointSet(
+            xy=keypoints_np,
+            descriptors=desc_np,
+            scores=scores_np,
+            meta=meta,
+        )
+
+
+def main():
+    import cv2
+
+    parser = argparse.ArgumentParser()
+    parser.add_argument(
+        "--image_path",
+        type=str,
+        default=(project_path / "data/images/keyboard/g98-v2-pink/model/keyboard1.png").as_posix(),
+    )
+    parser.add_argument("--device", type=str, default="cpu")
+    parser.add_argument("--max_keypoints", type=int, default=2000)
+    args = parser.parse_args()
+
+    image = cv2.imread(args.image_path)
+    if image is None:
+        raise FileNotFoundError(f"无法读取图片: {args.image_path}")
+
+    extractor = SuperPointKeyPointExtract(
+        SuperPointExtractConfig(
+            device=str(args.device),
+            max_keypoints=int(args.max_keypoints),
+        )
+    )
+    kp_set = extractor.extract(image)
+
+    cv2_keypoints = [
+        cv2.KeyPoint(
+            x=float(x),
+            y=float(y),
+            size=7,
+            response=float(score),
+        )
+        for (x, y), score in zip(kp_set.xy, kp_set.scores if kp_set.scores is not None else np.zeros((kp_set.n,), dtype=np.float32))
+    ]
+
+    image_with_kp = cv2.drawKeypoints(
+        image,
+        cv2_keypoints,
+        None,
+        color=(0, 0, 255),
+        flags=cv2.DRAW_MATCHES_FLAGS_DRAW_RICH_KEYPOINTS,
+    )
+    cv2.imshow(f"superpoint_keypoints | n={kp_set.n}", image_with_kp)
+    cv2.waitKey(0)
+    cv2.destroyAllWindows()
+    return
+
+
+if __name__ == "__main__":
+    main()
+

toolbox/keypoint_match/keypoint_match/__init__.py

@@ -0,0 +1,10 @@
+#!/usr/bin/python3
+# -*- coding: utf-8 -*-
+
+from toolbox.keypoint_match.keypoint_match.single_image_match import SingleImageMatcher, SingleImageMatcherConfig
+
+__all__ = [
+    "SingleImageMatcher",
+    "SingleImageMatcherConfig",
+]
+

toolbox/keypoint_match/keypoint_match/single_image_match.py

@@ -0,0 +1,280 @@
+#!/usr/bin/python3
+# -*- coding: utf-8 -*-
+from __future__ import annotations
+
+import argparse
+from dataclasses import dataclass
+from typing import Any, Dict, Optional, Tuple
+
+import cv2
+import numpy as np
+
+from project_settings import project_path
+from toolbox.keypoint_match.base import KeyPointExtract
+from toolbox.keypoint_match.types import ImageArray, KeyPointSet, MatchSet
+from toolbox.keypoint_match.keypoint_extracter import SiftExtractConfig, SiftKeyPointExtract
+
+
+@dataclass(frozen=True)
+class SingleImageMatcherConfig:
+    """
+    单模板图 vs 单大图 的匹配配置。
+    """
+
+    # KNN ratio test 阈值（Lowe's ratio test），越小越严格
+    ratio: float = 0.75
+    # 最多保留多少条匹配（按 distance 从小到大截断）
+    max_matches: Optional[int] = 500
+    # 是否做 mutual check（A->B 与 B->A 互相最近邻一致才保留）
+    mutual_check: bool = False
+    extra: Optional[Dict[str, Any]] = None
+
+
+class SingleImageMatcher:
+    """
+    匹配类：输入一张目标小图 + 一张包含目标的大图，输出匹配对。
+
+    - 初始化时传入关键点提取器（例如 `SiftKeyPointExtract` / SuperPoint 提取器等）
+    - `match(...)` 会提取两张图的 KeyPointSet，然后用 OpenCV BFMatcher 做匹配并输出 MatchSet
+    """
+
+    def __init__(self, extractor: KeyPointExtract, config: Optional[SingleImageMatcherConfig] = None):
+        self.extractor = extractor
+        self.config = config or SingleImageMatcherConfig()
+
+    @staticmethod
+    def _infer_norm_type(desc: np.ndarray) -> int:
+        import cv2
+
+        # ORB/BRIEF 等通常是 uint8 的二进制描述子；SIFT/SuperPoint 等通常是 float32
+        if desc.dtype == np.uint8:
+            return cv2.NORM_HAMMING
+        return cv2.NORM_L2
+
+    def _bfmatcher(self, query_desc: np.ndarray):
+        import cv2
+
+        norm = self._infer_norm_type(query_desc)
+        # mutual_check=True 时，OpenCV 的 crossCheck 只能用于 match()（不能用于 knnMatch）
+        return cv2.BFMatcher(normType=norm, crossCheck=False)
+
+    def _knn_ratio_match(self, bf, query_desc: np.ndarray, train_desc: np.ndarray) -> Tuple[np.ndarray, np.ndarray, np.ndarray]:
+        """
+        返回 (query_idx, train_idx, distance) 的一维数组
+        """
+        knn = bf.knnMatch(query_desc, train_desc, k=2)
+        q_idx = []
+        t_idx = []
+        dist = []
+        ratio = float(self.config.ratio)
+        for pair in knn:
+            if len(pair) < 2:
+                continue
+            m, n = pair[0], pair[1]
+            if m.distance < ratio * n.distance:
+                q_idx.append(int(m.queryIdx))
+                t_idx.append(int(m.trainIdx))
+                dist.append(float(m.distance))
+
+        if len(q_idx) == 0:
+            return (
+                np.zeros((0,), dtype=np.int64),
+                np.zeros((0,), dtype=np.int64),
+                np.zeros((0,), dtype=np.float32),
+            )
+
+        q_idx_arr = np.asarray(q_idx, dtype=np.int64)
+        t_idx_arr = np.asarray(t_idx, dtype=np.int64)
+        dist_arr = np.asarray(dist, dtype=np.float32)
+
+        # 按 distance 从小到大排序，并截断
+        order = np.argsort(dist_arr)
+        if self.config.max_matches is not None:
+            order = order[: int(self.config.max_matches)]
+        return q_idx_arr[order], t_idx_arr[order], dist_arr[order]
+
+    @staticmethod
+    def _mutual_filter(
+        q_to_t: Tuple[np.ndarray, np.ndarray, np.ndarray],
+        t_to_q: Tuple[np.ndarray, np.ndarray, np.ndarray],
+    ) -> Tuple[np.ndarray, np.ndarray, np.ndarray]:
+        """
+        q_to_t: (q_idx, t_idx, dist) from query->train
+        t_to_q: (t_idx, q_idx, dist) from train->query  (注意顺序)
+        保留互为最近邻/通过 ratio 的匹配对。
+        """
+        q_idx, t_idx, dist = q_to_t
+        t_idx2, q_idx2, _ = t_to_q
+        if q_idx.size == 0 or t_idx2.size == 0:
+            return q_idx, t_idx, dist
+
+        # 用集合做互相包含过滤
+        pairs_qt = {(int(q), int(t)) for q, t in zip(q_idx.tolist(), t_idx.tolist())}
+        pairs_tq = {(int(q), int(t)) for t, q in zip(t_idx2.tolist(), q_idx2.tolist())}  # 统一成 (q,t)
+        keep_pairs = pairs_qt.intersection(pairs_tq)
+        if not keep_pairs:
+            return (
+                np.zeros((0,), dtype=np.int64),
+                np.zeros((0,), dtype=np.int64),
+                np.zeros((0,), dtype=np.float32),
+            )
+
+        keep_mask = np.array([(int(q), int(t)) in keep_pairs for q, t in zip(q_idx, t_idx)], dtype=bool)
+        return q_idx[keep_mask], t_idx[keep_mask], dist[keep_mask]
+
+    def match(
+        self,
+        template_image: ImageArray,
+        search_image: ImageArray,
+        *,
+        template_id: Optional[str] = None,
+    ) -> Tuple[KeyPointSet, KeyPointSet, MatchSet]:
+        """
+        返回：(template_kp, search_kp, matches)
+        """
+        template_kp = self.extractor.extract(template_image)
+        search_kp = self.extractor.extract(search_image)
+
+        q_desc = np.asarray(template_kp.descriptors) if template_kp.descriptors is not None else np.zeros((0, 0), dtype=np.float32)
+        t_desc = np.asarray(search_kp.descriptors) if search_kp.descriptors is not None else np.zeros((0, 0), dtype=np.float32)
+        if q_desc.size == 0 or t_desc.size == 0:
+            matches = MatchSet(
+                query_idx=np.zeros((0,), dtype=np.int64),
+                train_idx=np.zeros((0,), dtype=np.int64),
+                distance=np.zeros((0,), dtype=np.float32),
+                meta={"backend": "opencv_bf_knn_ratio", "template_id": template_id},
+            )
+            return template_kp, search_kp, matches
+
+        bf = self._bfmatcher(q_desc)
+        q_to_t = self._knn_ratio_match(bf, q_desc, t_desc)
+
+        if self.config.mutual_check:
+            bf2 = self._bfmatcher(t_desc)
+            t_to_q = self._knn_ratio_match(bf2, t_desc, q_desc)
+            q_idx, t_idx, dist = self._mutual_filter(q_to_t, t_to_q)
+        else:
+            q_idx, t_idx, dist = q_to_t
+
+        meta: Dict[str, Any] = {
+            "backend": "opencv_bf_knn_ratio",
+            "ratio": float(self.config.ratio),
+            "mutual_check": bool(self.config.mutual_check),
+            "template_id": template_id,
+        }
+        if self.config.max_matches is not None:
+            meta["max_matches"] = int(self.config.max_matches)
+        if self.config.extra:
+            meta["extra"] = dict(self.config.extra)
+
+        matches = MatchSet(
+            query_idx=q_idx,
+            train_idx=t_idx,
+            distance=dist,
+            meta=meta,
+        )
+        return template_kp, search_kp, matches
+
+
+def _to_cv2_keypoints(kp_set: KeyPointSet):
+    import cv2
+
+    scores = (
+        kp_set.scores
+        if kp_set.scores is not None
+        else np.zeros((kp_set.n,), dtype=np.float32)
+    )
+    return [
+        cv2.KeyPoint(
+            x=float(x),
+            y=float(y),
+            size=7,
+            response=float(score),
+        )
+        for (x, y), score in zip(kp_set.xy, scores)
+    ]
+
+
+def _to_cv2_matches(match_set: MatchSet):
+    import cv2
+
+    dist = (
+        match_set.distance
+        if match_set.distance is not None
+        else np.zeros((match_set.m,), dtype=np.float32)
+    )
+    return [
+        cv2.DMatch(
+            _queryIdx=int(q),
+            _trainIdx=int(t),
+            _imgIdx=0,
+            _distance=float(d),
+        )
+        for q, t, d in zip(match_set.query_idx, match_set.train_idx, dist)
+    ]
+
+
+def get_args():
+    parser = argparse.ArgumentParser()
+    parser.add_argument(
+        "--template_path",
+        type=str,
+        default=(project_path / "data/images/keyboard/g98-v2-pink/model/local/roller.png"),
+    )
+    parser.add_argument(
+        "--search_path",
+        type=str,
+        default=(project_path / "data/images/keyboard/g98-v2-pink/model/keyboard1.png"),
+    )
+    parser.add_argument("--ratio", type=float, default=0.75)
+    parser.add_argument("--max_matches", type=int, default=80)
+    parser.add_argument("--max_keypoints", type=int, default=2000)
+    args = parser.parse_args()
+
+    return args
+
+
+def main():
+    args = get_args()
+
+    template = cv2.imread(args.template_path)
+    search = cv2.imread(args.search_path)
+    if template is None:
+        raise FileNotFoundError(f"无法读取模板图: {args.template_path}")
+    if search is None:
+        raise FileNotFoundError(f"无法读取搜索图: {args.search_path}")
+
+    extractor = SiftKeyPointExtract(SiftExtractConfig(max_keypoints=int(args.max_keypoints)))
+    matcher = SingleImageMatcher(
+        extractor=extractor,
+        config=SingleImageMatcherConfig(
+            ratio=float(args.ratio),
+            max_matches=int(args.max_matches),
+        ),
+    )
+
+    template_kp, search_kp, matches = matcher.match(template, search)
+
+    template_cv2_kp = _to_cv2_keypoints(template_kp)
+    search_cv2_kp = _to_cv2_keypoints(search_kp)
+    cv2_matches = _to_cv2_matches(matches)
+
+    vis = cv2.drawMatches(
+        template,
+        template_cv2_kp,
+        search,
+        search_cv2_kp,
+        cv2_matches,
+        None,
+        flags=cv2.DrawMatchesFlags_NOT_DRAW_SINGLE_POINTS,
+    )
+
+    title = f"single_match | kp_t={template_kp.n} kp_s={search_kp.n} matches={matches.m}"
+    cv2.imshow(title, vis)
+    cv2.waitKey(0)
+    cv2.destroyAllWindows()
+    return
+
+
+if __name__ == "__main__":
+    main()

toolbox/keypoint_match/types.py

@@ -0,0 +1,112 @@
+#!/usr/bin/python3
+# -*- coding: utf-8 -*-
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Mapping, Optional, Sequence, Tuple
+
+import numpy as np
+
+
+ArrayF32 = np.ndarray
+ArrayU8 = np.ndarray
+ImageArray = np.ndarray  # HxWxC or HxW, dtype不限（uint8/float32均可）
+
+
+@dataclass(frozen=True)
+class KeyPointSet:
+    """
+    统一表示一张图片上的关键点与（可选）描述子。
+
+    约定：
+    - xy: shape [N, 2]，列为 (x, y)，float32/float64
+    - descriptors: shape [N, D]（可选）。例如 ORB: uint8；SIFT/SuperPoint: float32
+    - scores: shape [N]（可选），越大表示点越“强”
+    """
+
+    xy: ArrayF32
+    descriptors: Optional[np.ndarray] = None
+    scores: Optional[ArrayF32] = None
+    meta: Optional[Mapping[str, Any]] = None
+
+    def __post_init__(self) -> None:
+        xy = np.asarray(self.xy)
+        if xy.ndim != 2 or xy.shape[1] != 2:
+            raise ValueError(f"KeyPointSet.xy 必须是 [N,2]，但得到 {xy.shape=}")
+        if self.descriptors is not None:
+            desc = np.asarray(self.descriptors)
+            if desc.ndim != 2 or desc.shape[0] != xy.shape[0]:
+                raise ValueError(
+                    "KeyPointSet.descriptors 必须是 [N,D] 且与 xy 的 N 一致，"
+                    f"但得到 {desc.shape=} vs {xy.shape=}"
+                )
+        if self.scores is not None:
+            sc = np.asarray(self.scores)
+            if sc.ndim != 1 or sc.shape[0] != xy.shape[0]:
+                raise ValueError(
+                    "KeyPointSet.scores 必须是 [N] 且与 xy 的 N 一致，"
+                    f"但得到 {sc.shape=} vs {xy.shape=}"
+                )
+
+    @property
+    def n(self) -> int:
+        return int(np.asarray(self.xy).shape[0])
+
+    @property
+    def has_descriptors(self) -> bool:
+        return self.descriptors is not None
+
+
+@dataclass(frozen=True)
+class MatchSet:
+    """
+    统一表示两组关键点之间的匹配关系。
+
+    - query_idx: 对应“模板/小图”关键点的索引，shape [M]
+    - train_idx: 对应“大图/搜索图”关键点的索引，shape [M]
+    - distance: 该匹配的距离/相似度度量，shape [M]（越小越相似是最常见约定）
+    """
+
+    query_idx: np.ndarray
+    train_idx: np.ndarray
+    distance: Optional[np.ndarray] = None
+    meta: Optional[Mapping[str, Any]] = None
+
+    def __post_init__(self) -> None:
+        qi = np.asarray(self.query_idx)
+        ti = np.asarray(self.train_idx)
+        if qi.ndim != 1 or ti.ndim != 1 or qi.shape[0] != ti.shape[0]:
+            raise ValueError(f"MatchSet 索引必须是同长度的一维数组，但得到 {qi.shape=} {ti.shape=}")
+        if self.distance is not None:
+            dist = np.asarray(self.distance)
+            if dist.ndim != 1 or dist.shape[0] != qi.shape[0]:
+                raise ValueError(f"MatchSet.distance 必须是 [M]，但得到 {dist.shape=} vs {qi.shape=}")
+
+    @property
+    def m(self) -> int:
+        return int(np.asarray(self.query_idx).shape[0])
+
+
+@dataclass(frozen=True)
+class Detection:
+    """
+    一次“模板在大图中被找到”的候选结果。
+    """
+
+    bbox_xyxy: Tuple[float, float, float, float]  # (x1,y1,x2,y2)
+    score: float
+    match_count: int
+    template_id: Optional[str] = None
+    meta: Optional[Mapping[str, Any]] = None
+
+
+@dataclass(frozen=True)
+class DetectionResult:
+    """
+    一次检测（一个模板对一张大图）输出的结果集合。
+    """
+
+    detections: Sequence[Detection]
+    meta: Optional[Mapping[str, Any]] = None
+

toolbox/os/__init__.py

@@ -0,0 +1,6 @@
+#!/usr/bin/python3
+# -*- coding: utf-8 -*-
+
+
+if __name__ == '__main__':
+    pass

toolbox/os/command.py

@@ -0,0 +1,59 @@
+#!/usr/bin/python3
+# -*- coding: utf-8 -*-
+import os
+
+
+class Command(object):
+    custom_command = [
+        "cd"
+    ]
+
+    @staticmethod
+    def _get_cmd(command):
+        command = str(command).strip()
+        if command == "":
+            return None
+        cmd_and_args = command.split(sep=" ")
+        cmd = cmd_and_args[0]
+        args = " ".join(cmd_and_args[1:])
+        return cmd, args
+
+    @classmethod
+    def popen(cls, command):
+        cmd, args = cls._get_cmd(command)
+        if cmd in cls.custom_command:
+            method = getattr(cls, cmd)
+            return method(args)
+        else:
+            resp = os.popen(command)
+            result = resp.read()
+            resp.close()
+            return result
+
+    @classmethod
+    def cd(cls, args):
+        if args.startswith("/"):
+            os.chdir(args)
+        else:
+            pwd = os.getcwd()
+            path = os.path.join(pwd, args)
+            os.chdir(path)
+
+    @classmethod
+    def system(cls, command):
+        return os.system(command)
+
+    def __init__(self):
+        pass
+
+
+def ps_ef_grep(keyword: str):
+    cmd = "ps -ef | grep {}".format(keyword)
+    rows = Command.popen(cmd)
+    rows = str(rows).split("\n")
+    rows = [row for row in rows if row.__contains__(keyword) and not row.__contains__("grep")]
+    return rows
+
+
+if __name__ == "__main__":
+    pass

toolbox/os/environment.py

@@ -0,0 +1,114 @@
+#!/usr/bin/python3
+# -*- coding: utf-8 -*-
+import json
+import os
+
+from dotenv import load_dotenv
+from dotenv.main import DotEnv
+
+from toolbox.json.misc import traverse
+
+
+class EnvironmentManager(object):
+    def __init__(self, path, env, override=False):
+        filename = os.path.join(path, '{}.env'.format(env))
+        self.filename = filename
+
+        load_dotenv(
+            dotenv_path=filename,
+            override=override
+        )
+
+        self._environ = dict()
+
+    def open_dotenv(self, filename: str = None):
+        filename = filename or self.filename
+        dotenv = DotEnv(
+            dotenv_path=filename,
+            stream=None,
+            verbose=False,
+            interpolate=False,
+            override=False,
+            encoding="utf-8",
+        )
+        result = dotenv.dict()
+        return result
+
+    def get(self, key, default=None, dtype=str):
+        result = os.environ.get(key)
+        if result is None:
+            if default is None:
+                result = None
+            else:
+                result = default
+        else:
+            result = dtype(result)
+        self._environ[key] = result
+        return result
+
+
+_DEFAULT_DTYPE_MAP = {
+    'int': int,
+    'float': float,
+    'str': str,
+    'json.loads': json.loads
+}
+
+
+class JsonConfig(object):
+    """
+    将 json 中, 形如 `$float:threshold` 的值, 处理为:
+    从环境变量中查到 threshold, 再将其转换为 float 类型.
+    """
+    def __init__(self, dtype_map: dict = None, environment: EnvironmentManager = None):
+        self.dtype_map = dtype_map or _DEFAULT_DTYPE_MAP
+        self.environment = environment or os.environ
+
+    def sanitize_by_filename(self, filename: str):
+        with open(filename, 'r', encoding='utf-8') as f:
+            js = json.load(f)
+
+        return self.sanitize_by_json(js)
+
+    def sanitize_by_json(self, js):
+        js = traverse(
+            js,
+            callback=self.sanitize,
+            environment=self.environment
+        )
+        return js
+
+    def sanitize(self, string, environment):
+        """支持 $ 符开始的, 环境变量配置"""
+        if isinstance(string, str) and string.startswith('$'):
+            dtype, key = string[1:].split(':')
+            dtype = self.dtype_map[dtype]
+
+            value = environment.get(key)
+            if value is None:
+                raise AssertionError('environment not exist. key: {}'.format(key))
+
+            value = dtype(value)
+            result = value
+        else:
+            result = string
+        return result
+
+
+def demo1():
+    import json
+
+    from project_settings import project_path
+
+    environment = EnvironmentManager(
+        path=os.path.join(project_path, 'server/callbot_server/dotenv'),
+        env='dev',
+    )
+    init_scenes = environment.get(key='init_scenes', dtype=json.loads)
+    print(init_scenes)
+    print(environment._environ)
+    return
+
+
+if __name__ == '__main__':
+    demo1()

toolbox/os/other.py

@@ -0,0 +1,9 @@
+import os
+import inspect
+
+
+def pwd():
+    """你在哪个文件调用此函数, 它就会返回那个文件所在的 dir 目标"""
+    frame = inspect.stack()[1]
+    module = inspect.getmodule(frame[0])
+    return os.path.dirname(os.path.abspath(module.__file__))