ponychart-classifier 0.1.0__tar.gz

ponychart_classifier-0.1.0/PKG-INFO

@@ -0,0 +1,194 @@
+Metadata-Version: 2.4
+Name: ponychart-classifier
+Version: 0.1.0
+Summary: Multi-label image classifier for PonyChart character identification.
+Author: Kuan-Lun Wang
+License: GNU Affero General Public License v3
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: License :: OSI Approved :: GNU Affero General Public License v3 or later (AGPLv3+)
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: <3.14,>=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: numpy>=2.2.6
+Requires-Dist: opencv-python>=4.12.0.88
+Requires-Dist: onnxruntime>=1.15.0
+Provides-Extra: train
+Requires-Dist: torch>=2.0; extra == "train"
+Requires-Dist: torchvision>=0.15; extra == "train"
+Requires-Dist: scikit-learn>=1.3; extra == "train"
+Requires-Dist: onnx>=1.20.1; extra == "train"
+Requires-Dist: onnxscript>=0.6.2; extra == "train"
+Requires-Dist: flask>=3.0; extra == "train"
+Requires-Dist: psutil>=5.9; extra == "train"
+Requires-Dist: Pillow>=10.0; extra == "train"
+Provides-Extra: publish
+Requires-Dist: build; extra == "publish"
+Requires-Dist: twine; extra == "publish"
+
+# PonyChart Classifier
+
+PonyChart 角色辨識模型，用於自動辨識 HentaiVerse 戰鬥中出現的 PonyChart 圖片中的角色。
+
+## 目錄結構
+
+```
+ponychart-classifier/
+├── src/
+│   └── ponychart_classifier/          # PyPI 套件
+│       ├── __init__.py                # 公開 API (re-export model_spec)
+│       ├── model_spec.py              # 推論常數 + select_predictions()
+│       ├── model.onnx                 # ONNX 模型 (推論用)
+│       ├── thresholds.json            # 各角色的分類閾值 (推論用)
+│       └── training/                  # 訓練函式庫
+│           ├── __init__.py            # Re-export 所有 symbol
+│           ├── constants.py           # 常數與訓練超參數 (single source of truth)
+│           ├── device.py              # 裝置偵測
+│           ├── dataset.py             # 資料載入、Dataset、transforms
+│           ├── model.py               # Backbone registry + build_model()
+│           ├── training.py            # 訓練迴圈、evaluate、threshold 優化
+│           ├── sampling.py            # 樣本載入與平衡
+│           ├── splitting.py           # Hash-based group splitting
+│           ├── log_helpers.py         # 日誌輔助
+│           └── export.py              # ONNX 匯出
+├── scripts/                           # 開發用腳本 (不隨套件發佈)
+│   ├── train.py                       # 模型訓練腳本
+│   ├── label_images.py                # 圖片標註工具 (GUI)
+│   ├── inspect_checkpoint.py          # Checkpoint 資訊檢視
+│   ├── compare_backbones.py           # Backbone 架構比較
+│   ├── compare_crops.py               # 裁切圖片效果分析
+│   ├── compare_pos_weight.py          # pos_weight 效果比較
+│   ├── compare_resolution.py          # 輸入解析度比較
+│   ├── compare_resume_scratch.py      # Resume vs from-scratch 分析
+│   ├── evaluate_holdout.py            # Holdout 評估
+│   ├── analyze_augmentations.py       # 資料增強 ablation study
+│   ├── analyze_distribution.py        # 標籤分布互動式視覺化 (Flask)
+│   ├── learning_curve.py              # Learning curve 分析 + power-law 外推
+│   ├── search_batch_lr.py             # LR 超參數搜尋
+│   └── profile_dataloader.py          # DataLoader 效能分析
+├── rawimage/                          # 訓練用原始圖片 (PNG)
+├── labels.json                        # 標註資料 {"rawimage/filename.png": [1,3]}
+├── checkpoint.pt                      # PyTorch checkpoint (resume 訓練用)
+├── pyproject.toml
+└── README.md
+```
+
+## 標籤對照
+
+| 編號 | 角色 |
+|------|------|
+| 1 | Twilight Sparkle |
+| 2 | Rarity |
+| 3 | Fluttershy |
+| 4 | Rainbow Dash |
+| 5 | Pinkie Pie |
+| 6 | Applejack |
+
+## 安裝
+
+```bash
+# 推論用 (hbrowser 會自動安裝)
+pip install ponychart-classifier
+
+# 開發用 (包含訓練依賴)
+pip install -e ".[train]"
+```
+
+## 工作流程
+
+### 1. 收集圖片
+
+將新的 PonyChart 截圖 (PNG) 放入 `rawimage/` 資料夾。
+
+### 2. 標註圖片
+
+```bash
+uv run python scripts/label_images.py
+```
+
+操作方式：
+- `1`~`6`: 加/取消對應角色標籤
+- `A` / `D`: 上一張 / 下一張
+- `S`: 儲存目前標籤
+
+標註結果會即時更新到 `labels.json`。
+
+### 3. 訓練模型
+
+```bash
+# 安裝訓練依賴 (只需一次)
+uv pip install -e ".[train]"
+
+# 執行訓練 (若存在 checkpoint.pt 則自動從上次結果繼續訓練)
+uv run python scripts/train.py
+
+# 強制從頭訓練 (忽略 checkpoint，從 ImageNet 預訓練權重開始)
+uv run python scripts/train.py --from-scratch
+```
+
+訓練完成後會覆寫 `model.onnx`、`thresholds.json` 和 `checkpoint.pt`，下次推論自動使用新模型。
+
+### Resume 訓練
+
+新增圖片並標註後，直接執行 `train.py` 即可。腳本會自動偵測 `checkpoint.pt`：
+- **有 checkpoint**: 載入之前的模型權重，跳過 Phase 1 (head-only)，直接進入 Phase 2 fine-tuning，收斂更快
+- **無 checkpoint**: 從 ImageNet 預訓練權重開始完整兩階段訓練
+
+### 訓練超參數
+
+所有超參數集中於 `src/ponychart_classifier/training/constants.py`，修改後對所有腳本生效：
+
+| 參數 | 預設值 | 說明 |
+|------|--------|------|
+| `BACKBONE` | `efficientnet_b0` | 見下方支援的 backbone |
+| `BATCH_SIZE` | 32 | 批次大小 |
+| `SEED` | 42 | 隨機種子 |
+| `PHASE1_EPOCHS` | 10 | Phase 1 (head-only) 訓練輪數 |
+| `PHASE2_EPOCHS` | 100 | Phase 2 (full fine-tuning) 最大訓練輪數 |
+| `PHASE2_PATIENCE` | 12 | Phase 2 early stopping patience |
+
+## 支援的 Backbone
+
+| Backbone | 參數量 | ONNX 大小 | 說明 |
+|----------|--------|-----------|------|
+| `mobilenet_v3_small` | 2.5M | ~4MB | 輕量快速 |
+| `mobilenet_v3_large` | 5.4M | ~9MB | 精度最高 |
+| `efficientnet_b0` | 5.3M | ~11MB | 預設，精度接近 Large，但訓練較慢 |
+
+所有 backbone 都使用 ImageNet 預訓練權重 + transfer learning。
+推論端使用 ONNX Runtime，backbone 更換後只需重新匯出 `model.onnx`，推論程式碼不需改動。
+
+## 分析腳本
+
+分析腳本使用 `training/constants.py` 中的超參數設定：
+
+```bash
+# 比較三種 backbone 的效果
+uv run python scripts/compare_backbones.py
+
+# 分析裁切圖片的影響
+uv run python scripts/compare_crops.py
+
+# 資料增強 ablation study
+uv run python scripts/analyze_augmentations.py
+
+# 標籤分布互動式視覺化 (Flask web UI)
+uv run python scripts/analyze_distribution.py
+
+# Learning curve 分析 (估算增加資料的邊際效益)
+uv run python scripts/learning_curve.py
+
+# LR 超參數搜尋
+uv run python scripts/search_batch_lr.py
+```
+
+## 模型架構
+
+- **Backbone**: 可選 MobileNetV3-Small/Large 或 EfficientNet-B0 (預設 EfficientNet-B0，ImageNet 預訓練)
+- **訓練策略**: Phase 1 head-only + Phase 2 full fine-tuning，支援從 checkpoint 繼續訓練
+- **輸出**: 6 個 sigmoid 節點 (多標籤分類)
+- **推論引擎**: ONNX Runtime (CPU)
+- **推論速度**: 3-21ms / 張

ponychart_classifier-0.1.0/README.md

@@ -0,0 +1,163 @@
+# PonyChart Classifier
+
+PonyChart 角色辨識模型，用於自動辨識 HentaiVerse 戰鬥中出現的 PonyChart 圖片中的角色。
+
+## 目錄結構
+
+```
+ponychart-classifier/
+├── src/
+│   └── ponychart_classifier/          # PyPI 套件
+│       ├── __init__.py                # 公開 API (re-export model_spec)
+│       ├── model_spec.py              # 推論常數 + select_predictions()
+│       ├── model.onnx                 # ONNX 模型 (推論用)
+│       ├── thresholds.json            # 各角色的分類閾值 (推論用)
+│       └── training/                  # 訓練函式庫
+│           ├── __init__.py            # Re-export 所有 symbol
+│           ├── constants.py           # 常數與訓練超參數 (single source of truth)
+│           ├── device.py              # 裝置偵測
+│           ├── dataset.py             # 資料載入、Dataset、transforms
+│           ├── model.py               # Backbone registry + build_model()
+│           ├── training.py            # 訓練迴圈、evaluate、threshold 優化
+│           ├── sampling.py            # 樣本載入與平衡
+│           ├── splitting.py           # Hash-based group splitting
+│           ├── log_helpers.py         # 日誌輔助
+│           └── export.py              # ONNX 匯出
+├── scripts/                           # 開發用腳本 (不隨套件發佈)
+│   ├── train.py                       # 模型訓練腳本
+│   ├── label_images.py                # 圖片標註工具 (GUI)
+│   ├── inspect_checkpoint.py          # Checkpoint 資訊檢視
+│   ├── compare_backbones.py           # Backbone 架構比較
+│   ├── compare_crops.py               # 裁切圖片效果分析
+│   ├── compare_pos_weight.py          # pos_weight 效果比較
+│   ├── compare_resolution.py          # 輸入解析度比較
+│   ├── compare_resume_scratch.py      # Resume vs from-scratch 分析
+│   ├── evaluate_holdout.py            # Holdout 評估
+│   ├── analyze_augmentations.py       # 資料增強 ablation study
+│   ├── analyze_distribution.py        # 標籤分布互動式視覺化 (Flask)
+│   ├── learning_curve.py              # Learning curve 分析 + power-law 外推
+│   ├── search_batch_lr.py             # LR 超參數搜尋
+│   └── profile_dataloader.py          # DataLoader 效能分析
+├── rawimage/                          # 訓練用原始圖片 (PNG)
+├── labels.json                        # 標註資料 {"rawimage/filename.png": [1,3]}
+├── checkpoint.pt                      # PyTorch checkpoint (resume 訓練用)
+├── pyproject.toml
+└── README.md
+```
+
+## 標籤對照
+
+| 編號 | 角色 |
+|------|------|
+| 1 | Twilight Sparkle |
+| 2 | Rarity |
+| 3 | Fluttershy |
+| 4 | Rainbow Dash |
+| 5 | Pinkie Pie |
+| 6 | Applejack |
+
+## 安裝
+
+```bash
+# 推論用 (hbrowser 會自動安裝)
+pip install ponychart-classifier
+
+# 開發用 (包含訓練依賴)
+pip install -e ".[train]"
+```
+
+## 工作流程
+
+### 1. 收集圖片
+
+將新的 PonyChart 截圖 (PNG) 放入 `rawimage/` 資料夾。
+
+### 2. 標註圖片
+
+```bash
+uv run python scripts/label_images.py
+```
+
+操作方式：
+- `1`~`6`: 加/取消對應角色標籤
+- `A` / `D`: 上一張 / 下一張
+- `S`: 儲存目前標籤
+
+標註結果會即時更新到 `labels.json`。
+
+### 3. 訓練模型
+
+```bash
+# 安裝訓練依賴 (只需一次)
+uv pip install -e ".[train]"
+
+# 執行訓練 (若存在 checkpoint.pt 則自動從上次結果繼續訓練)
+uv run python scripts/train.py
+
+# 強制從頭訓練 (忽略 checkpoint，從 ImageNet 預訓練權重開始)
+uv run python scripts/train.py --from-scratch
+```
+
+訓練完成後會覆寫 `model.onnx`、`thresholds.json` 和 `checkpoint.pt`，下次推論自動使用新模型。
+
+### Resume 訓練
+
+新增圖片並標註後，直接執行 `train.py` 即可。腳本會自動偵測 `checkpoint.pt`：
+- **有 checkpoint**: 載入之前的模型權重，跳過 Phase 1 (head-only)，直接進入 Phase 2 fine-tuning，收斂更快
+- **無 checkpoint**: 從 ImageNet 預訓練權重開始完整兩階段訓練
+
+### 訓練超參數
+
+所有超參數集中於 `src/ponychart_classifier/training/constants.py`，修改後對所有腳本生效：
+
+| 參數 | 預設值 | 說明 |
+|------|--------|------|
+| `BACKBONE` | `efficientnet_b0` | 見下方支援的 backbone |
+| `BATCH_SIZE` | 32 | 批次大小 |
+| `SEED` | 42 | 隨機種子 |
+| `PHASE1_EPOCHS` | 10 | Phase 1 (head-only) 訓練輪數 |
+| `PHASE2_EPOCHS` | 100 | Phase 2 (full fine-tuning) 最大訓練輪數 |
+| `PHASE2_PATIENCE` | 12 | Phase 2 early stopping patience |
+
+## 支援的 Backbone
+
+| Backbone | 參數量 | ONNX 大小 | 說明 |
+|----------|--------|-----------|------|
+| `mobilenet_v3_small` | 2.5M | ~4MB | 輕量快速 |
+| `mobilenet_v3_large` | 5.4M | ~9MB | 精度最高 |
+| `efficientnet_b0` | 5.3M | ~11MB | 預設，精度接近 Large，但訓練較慢 |
+
+所有 backbone 都使用 ImageNet 預訓練權重 + transfer learning。
+推論端使用 ONNX Runtime，backbone 更換後只需重新匯出 `model.onnx`，推論程式碼不需改動。
+
+## 分析腳本
+
+分析腳本使用 `training/constants.py` 中的超參數設定：
+
+```bash
+# 比較三種 backbone 的效果
+uv run python scripts/compare_backbones.py
+
+# 分析裁切圖片的影響
+uv run python scripts/compare_crops.py
+
+# 資料增強 ablation study
+uv run python scripts/analyze_augmentations.py
+
+# 標籤分布互動式視覺化 (Flask web UI)
+uv run python scripts/analyze_distribution.py
+
+# Learning curve 分析 (估算增加資料的邊際效益)
+uv run python scripts/learning_curve.py
+
+# LR 超參數搜尋
+uv run python scripts/search_batch_lr.py
+```
+
+## 模型架構
+
+- **Backbone**: 可選 MobileNetV3-Small/Large 或 EfficientNet-B0 (預設 EfficientNet-B0，ImageNet 預訓練)
+- **訓練策略**: Phase 1 head-only + Phase 2 full fine-tuning，支援從 checkpoint 繼續訓練
+- **輸出**: 6 個 sigmoid 節點 (多標籤分類)
+- **推論引擎**: ONNX Runtime (CPU)
+- **推論速度**: 3-21ms / 張

ponychart_classifier-0.1.0/pyproject.toml

@@ -0,0 +1,62 @@
+[build-system]
+requires = ["setuptools", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "ponychart-classifier"
+version = "0.1.0"
+description = "Multi-label image classifier for PonyChart character identification."
+readme = "README.md"
+authors = [{ name = "Kuan-Lun Wang" }]
+license = { text = "GNU Affero General Public License v3" }
+requires-python = ">=3.11,<3.14"
+dependencies = [
+    "numpy>=2.2.6",
+    "opencv-python>=4.12.0.88",
+    "onnxruntime>=1.15.0",
+]
+
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "License :: OSI Approved :: GNU Affero General Public License v3 or later (AGPLv3+)",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+]
+
+[project.optional-dependencies]
+train = [
+    "torch>=2.0",
+    "torchvision>=0.15",
+    "scikit-learn>=1.3",
+    "onnx>=1.20.1",
+    "onnxscript>=0.6.2",
+    "flask>=3.0",
+    "psutil>=5.9",
+    "Pillow>=10.0",
+]
+publish = [
+    "build",
+    "twine",
+]
+
+[tool.setuptools]
+include-package-data = true
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+"ponychart_classifier" = [
+    "py.typed",
+    "model.onnx",
+    "thresholds.json",
+]
+
+[tool.ruff]
+line-length = 88
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP"]

ponychart_classifier-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

ponychart_classifier-0.1.0/src/ponychart_classifier/__init__.py

@@ -0,0 +1,27 @@
+"""PonyChart classifier -- inference constants and prediction utilities."""
+
+from .inference import PonyChartClassifier, predict, preload
+from .model_spec import (
+    CLASS_NAMES,
+    IMAGENET_MEAN,
+    IMAGENET_STD,
+    INPUT_SIZE,
+    MAX_K,
+    NUM_CLASSES,
+    PRE_RESIZE,
+    select_predictions,
+)
+
+__all__ = [
+    "CLASS_NAMES",
+    "IMAGENET_MEAN",
+    "IMAGENET_STD",
+    "INPUT_SIZE",
+    "MAX_K",
+    "NUM_CLASSES",
+    "PRE_RESIZE",
+    "PonyChartClassifier",
+    "predict",
+    "preload",
+    "select_predictions",
+]

ponychart_classifier-0.1.0/src/ponychart_classifier/inference.py

@@ -0,0 +1,114 @@
+"""High-level inference API for PonyChart character classification."""
+
+from __future__ import annotations
+
+import json
+import os
+import sys
+from typing import Any
+
+import cv2 as cv
+import numpy as np
+import onnxruntime as ort
+
+from .model_spec import (
+    CLASS_NAMES,
+    IMAGENET_MEAN,
+    IMAGENET_STD,
+    INPUT_SIZE,
+    PRE_RESIZE,
+    select_predictions,
+)
+
+_IMAGENET_MEAN = np.array(IMAGENET_MEAN, dtype=np.float32)
+_IMAGENET_STD = np.array(IMAGENET_STD, dtype=np.float32)
+
+
+def _package_dir() -> str:
+    return os.path.dirname(__file__)
+
+
+class PonyChartClassifier:
+    """Lazy-loading ONNX classifier for PonyChart images."""
+
+    def __init__(self) -> None:
+        self._loaded = False
+        self._session: Any = None
+        self._classes: list[str] = list(CLASS_NAMES)
+        self._thresholds: dict[str, float] = {}
+
+    def load(self) -> None:
+        """Load the ONNX model and thresholds. Safe to call multiple times."""
+        if self._loaded:
+            return
+
+        d = _package_dir()
+        model_path = os.path.join(d, "model.onnx")
+        th_path = os.path.join(d, "thresholds.json")
+        self._session = ort.InferenceSession(
+            model_path, providers=["CPUExecutionProvider"]
+        )
+        with open(th_path, encoding="utf-8") as f:
+            self._thresholds = json.load(f)
+        self._loaded = True
+
+    def _preprocess(self, bgr: np.ndarray[Any, Any]) -> np.ndarray[Any, Any]:
+        """BGR image -> NCHW float32 tensor (matching training transforms)."""
+        resized = cv.resize(bgr, (PRE_RESIZE, PRE_RESIZE), interpolation=cv.INTER_AREA)
+        offset = (PRE_RESIZE - INPUT_SIZE) // 2
+        cropped = resized[offset : offset + INPUT_SIZE, offset : offset + INPUT_SIZE]
+        rgb = cv.cvtColor(cropped, cv.COLOR_BGR2RGB).astype(np.float32) / 255.0
+        normalized = (rgb - _IMAGENET_MEAN) / _IMAGENET_STD
+        # HWC -> CHW -> NCHW
+        return normalized.transpose(2, 0, 1)[np.newaxis, ...].astype(np.float32)
+
+    def predict(
+        self, img_path: str, min_k: int = 1, max_k: int = 3
+    ) -> tuple[list[str], dict[str, float]]:
+        """Predict characters in a PonyChart image.
+
+        Returns ``(picked_names, scores)`` where *picked_names* is a list of
+        selected character names and *scores* maps every class name to its
+        sigmoid probability.
+        """
+        self.load()
+        img = cv.imread(img_path, cv.IMREAD_COLOR)
+        if img is None:
+            raise RuntimeError(f"Cannot read image: {img_path}")
+
+        input_tensor = self._preprocess(img)
+        input_name: str = self._session.get_inputs()[0].name
+        logits = self._session.run(None, {input_name: input_tensor})[0]
+        probs = 1.0 / (1.0 + np.exp(-logits[0]))
+
+        scores = {self._classes[i]: float(probs[i]) for i in range(len(self._classes))}
+        thresholds = [self._thresholds.get(c, 0.5) for c in self._classes]
+        indices = select_predictions(list(probs), thresholds, min_k=min_k, max_k=max_k)
+        picked = [self._classes[i] for i in indices]
+        return picked, scores
+
+
+_default_classifier = PonyChartClassifier()
+
+
+def predict(
+    img_path: str, min_k: int = 1, max_k: int = 3
+) -> tuple[list[str], dict[str, float]]:
+    """Predict characters using the default classifier instance."""
+    return _default_classifier.predict(img_path, min_k=min_k, max_k=max_k)
+
+
+def preload() -> None:
+    """Pre-load the ONNX model to catch dependency issues early."""
+    try:
+        _default_classifier.load()
+    except ImportError as e:
+        msg = "onnxruntime failed to load."
+        if sys.platform == "win32" and "DLL load failed" in str(e):
+            msg += (
+                "\nPossible cause: missing Microsoft Visual C++ Redistributable."
+                "\nDownload from https://aka.ms/vs/17/release/vc_redist.x64.exe"
+            )
+        else:
+            msg += "\nPlease install: pip install onnxruntime"
+        raise RuntimeError(msg) from e